//This guide assumes you are familiar with <a href="https://twinery.org/">twine</a>, how to <a href="https://twinery.org/reference/en/story-formats/adding.html">add a story format</a>, and how to <a href="https://twinery.org/reference/en/editing-stories/changing-story-format.html">select your story's format</a>.//
<div align="center">~</div>
AdventureTome will work with almost any existing twine story you have (though it may stumble if you have scripts, styling, or formatting specific to a different story format).
Select AdventureTome as your story format and give it a try; your passages will be numbered, shuffled, and displayed as a series of pages. Your passage links should also look a little different, having changed to a "turn to XYZ" format.
- [[Formatting Text]].
- [[Passage Links]].
__Every__ passage will be shuffled and displayed in a random order, unless it has had certain changes made to it. For example, the passage marked as the story's start will always be the first numbered passage (like this one), but you can add pages before and after the shuffled passages also.
- [[Passage Order]].
- [[Hidden Passages]].
Your story won't have a character sheet unless you set one up. This consists of making a passage that lists all the items that will be tracked on the sheet, and how those items will be displayed.
[[Character Sheets]].
AdventureTome has some additional features to make things easier for you and your readers. Check them out if you're interested.
- [[Page Headers and Footers]].
- [[Adding a passage to the Menu]].
- [[Text Swaps]].
You can interact with AdventureTome using JavaScript. This can be as simple as making buttons that assign certain values to character sheet items, or complete functions that read and write to the character sheet or turn to specific pages.
- [[Simple JavaScript Interactions]].
- [[Embedding Complex JavaScripts]].
- [[Using JavaScript to alter AdventureTome]]
AdventureTome has some compatibility with <a href="https://gordianbook.art/">Gordian Book</a>, to [[learn more->Gordian Book]]
For a quick-reference list of almost anything you might want to know there is a [[cheat sheet here->Quick Reference]].Text styling is done by placing it between the approriate characters:
`''`''bold''`''`
`//`//italics//`//`
`~~`~~strikethrough~~`~~`
`^^`^^superscript^^`^^`
`*`*emphasis*`*`
`**`**strong emphasis**`**`
`__`__underline__`__`
Formatting can be escaped by putting text within ``backticks``.
To display a backtick, place two consecutively: ````
You can also use <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">HTML tags</a>.
[[Want to learn more about AdventureTome?->Learning how to use AdventureTome]] Writing passage links is the same as normal, two "[" brackets on either side of your text will turn it into a link.
You can also use both "->" and "<-" links for text that describes something other than a passage title.
This even works with //completely blank// text links, which AdventureTome will use to insert a simple turn instruction with no accompanying text.
<style>.tabrow{border:1px solid #999;width:100%;display:table;} .tabcell {padding:10px;border:1px solid #999;display:table-cell;width:50%;text-align:left;vertical-align:middle;}</style>
Examples of passage link formatting and how they appear:
<div class="tabrow"><div class="tabcell"><small><code>`[[Passage Links]]`</code></small></div><div class="tabcell">[[Passage Links]]</div></div>
<div class="tabrow"><div class="tabcell"><small><code>`[[display text->Passage Links]]`</code></small></div><div class="tabcell">[[display text->Passage Links]]</div></div>
<div class="tabrow"><div class="tabcell"><small><code>`[[Passage Links<-display text]]`</code></small></div><div class="tabcell">[[Passage Links<-display text]]</div></div>
<div class="tabrow"><div class="tabcell"><small><code>`[[->Passage Links]]`</code></small></div><div class="tabcell">[[->Passage Links]]</div></div>
<div class="tabrow"><div class="tabcell"><small><code>`[[#->Passage Links]]`</code></small></div><div class="tabcell">[[#->Passage Links]]</div></div>
<div class="tabrow"><div class="tabcell"><small><code>`[[turnto->Passage Links]]`</code></small></div><div class="tabcell">[[turnto->Passage Links]]</div></div>
<div class="tabrow"><div class="tabcell"><small><code>`[[Turnto->Passage Links]]`</code></small></div><div class="tabcell">[[Turnto->Passage Links]]</div></div>
<div class="tabrow"><div class="tabcell"><small><code>`[["display text"->Passage Links]]`</code></small></div><div class="tabcell">[["display text"->Passage Links]]</div></div>
<div class="tabrow"><div class="tabcell"><small><code>`[[""->Passage Links]]`</code></small></div><div class="tabcell">[[""->Passage Links]]</div></div>
Links followed by <code>-peek</code> will open in a "peek" view:
<div class="tabrow"><div class="tabcell"><small><code>`[["display text"->Passage Links]]-peek`</code></small></div><div class="tabcell">[["display text"->Passage Links]]-peek</div></div>
//Links can also be formatted as //<code>`[@passageName@]`</code>//, with the inner brackets replaced by '@' symbols. This is useful because twine itself won't recognise these links and you can use them in cases where you don't want to see a link in twine (eg, many links from a contents page making your layout messy). However this is not without risk because ''twine itself won't recognise these links'' - if you rename a passage the relevant links will not be automatically updated if they use this format, so it is best used sparingly.//
[@Hey, here's a link back to the first passage!->Learning how to use AdventureTome@]Passages with a "<code>hidden</code>" or "<code>skip</code>" tag won't be displayed.
If you have any passage nodes you don't want to be visible (e.g: a "notes" node) make sure to mark them as hidden, or they will be shuffled into the list of passages and displayed with all the others.
Even if a passage is not connected, it will be shuffled into the others and get its own page unless it has a tag to hide it (you can use this to include secrets in the tome, and make them the solution to numeric puzzles by fixing their passage number. To learn more [[->Passage Order]]
[[Keep on learning about AdventureTome!->Learning how to use AdventureTome]]This passage won't be displayed, because it has the "hidden" tag.
Hello to people who dug into the data and found this passage, you're a cool nerd!
AdventureTome is a twine story format inspired by old-school adventure gamebooks, where a player chooses their path through a book, keeping track of a character with pen and paper, and rolling dice when their luck is tested.
Like the WritingFantasy story format, AdventureTome will shuffle twine story passages and show links in a "turn to XYZ" format. Unlike WritingFantasy however, AdventureTome is designed to facilitate play in a web browser rather than print and play - with an author-customisable character sheet and a game history with full undo/redo.
To begin Learning how to use AdventureTome ()Passages are shuffled randomly for the most part, with a few exceptions:
<ul><li>The passage marked as the 'start' in twine will always be the first numbered passage</li><li>A passage with the tag "<code>ending</code>" or "<code>last</code>" will always be the last numbered passage (just like this one)</li><li>Passages with a tag formatted as either "<code>fixednumber_123</code>" or "<code>123</code>" will be given the specified passage number, provided there are enough passages (otherwise it will be placed at the end)</li></ul>
You can organise passages into chapters. Chapters will be displayed in order, but the passages within them will be shuffled. Assign a passage to a chapter by giving it a tag formatted as "<code>chapter_123</code>". You can specify the first and last passage in a chapter with the additional tags "<code>chapter_end</code>" and "<code>chapter_end</code>". Passages without a chapter tag will all be placed in "chapter 0".
Passages can also appear outside of the list of numbered passages:
<ul><li>Passages with the tag "<code>frontmatter</code>" will always appear before numbered passages</li><li>Passages with the tag "<code>backmatter</code>" will always appear after numbered passages</li></ul>The order of front and back matter passages can be specified with tag formatting like "<code>frontmatter_1</code>", "<code>frontmatter_2</code>", etc.
Passage links work even when linking outside of the numbered passages, for example: [[->Thanks]].
Additionally, specially titled passages will appear around the story (and without their passage titles visible):
<ul><li>Passages titled "<code>gb-front-cover</code>" will before all other passages</li><li>Passages titled "<code>gb-introduction</code>" will just before numbered passages (after any front matter)</li><li>Passages titled "<code>gb-rear</code>" will after numbered passages and any back matter</li><li>Passages titled "<code>gb-back-cover</code>" will after all other passages</li></ul>
[[Want to go back to the first passage?->Learning how to use AdventureTome]] Thanks for your interest in AdventureTome, and especially thanks to all of my patrons whose support allows me to make things like this.
If you would like to support me on patreon, you can find me here:
<a href="https://www.patreon.com/SophieHoulden">patreon.com/SophieHoulden</a><a href="https://gordianbook.art/">Gordian Book</a> is tool very similar to WritingFantasy. Both take twine stories to make gamebooks, but the process and the results you get will be a bit different.
Most notably, WritingFantasy is a twine "Story Format" which builds and displays your gamebook at once, whereas Gordian Book is more explicitly a converter with an import/export process.
If you are interested in WritingFantasy or AdventureTome then Gordian Book is definitely worth a look, __especially__ if you are aiming to have a print/pdf version of your work.
The good news is it doesn't really have to be an either/or choice. Both systems have a degree of shared compatibility, so stories written for one will generally work with the other. Just make sure to check your results after switching as there isn't //complete// feature parity.
[[Learning how to use AdventureTome<-Return to first passage]]
<div align="center">//Page $$page_this$$ of $$page_total$$//</div><div align="center">//AdventureTome//</div>This character sheet, its contents, and its layout are all defined in a single twine passage!
$$d6a$$ $$d6b$$
$$charaName$$
Health:
$$HP$$$$MaxHP$$
Stats:
$$str$$$$dex$$$$mag$$
$$illusionring$$
$$inv$$
$$notesText$$
If you make a passage titled "<code>pageheader</code>" it will be placed above all pages, likewise a "<code>pagefooter</code>" passage will appear below all pages.
You can mark some passages as not having a header or footer by using the tags "<code>noheader</code>" or "<code>nofooter</code>".
Additionally, there are a couple of keys you can include that will be dynamically replaced and are useful for header/footer display (though they will work in any part of a page):
"<code>`$$page_this$$`</code>" will display the current page number.
"<code>`$$page_total$$`</code>" will display the total number of pages.
"<code>`$$passage_this$$`</code>" will display the current passage number (or its title if it is not one of the shuffled passages).
"<code>`$$passage_total$$`</code>" will display the total number of shuffled pages.
[[Learning how to use AdventureTome<-Enough of that, lets go back to the guide's menu!]] Character sheets are defined by passages with the tag "charactersheet".
//(You can have multiple character sheets, with ordered tabs by tagging them "charactersheet_1", "charactersheet_2", etc.)//
In these passages you create a set of character sheet items (defining their name, type, style, etc), and also where they appear on the character sheet.
Character sheet items formatted using basic XML-style formatting, all included within a <code>`<csitems>`</code> node. They are inserted where their name appears between two dollar signs.
An example of a passage defining a simple character sheet with just a name and HP would look like this:
<div style="border:1px solid var(--textCol);padding:10;font-family:monospace;"><small><code>`Your Hero:
$$character_name$$
$$character_HP$$
<csitems>
<text name="character_name" value="The Traveller" alt="Your character's name" label="Name">
<number name="character_HP" value="15" alt="Your hit points" label="HP">
</csitems>`</code></small></div>
These are the permitted types of tag you can use within csitems at present:
<b><code>`<text>`</code></b> - A single-line text input
<b><code>`<number>`</code></b> - A simple number input
<b><code>`<notes>`</code></b> - A multi-line text input
<b><code>`<toggle>`</code></b> - A single on/off element
<b><code>`<die>`</code></b> - a widget for a 6-sided die
<b><code>`<uneditable>`</code></b> - text that cannot be edited by a player, uneditable elements are hidden on the sheet if they have no value.
There are several attributes that can be applied to csitems, though only the "name" attribute is required:
<ul><li><code>''name''</code>: This is the name for the value the item represents, it is not displayed to a player but is used to identify the item, so you should make it unique.</li>
<li><code>''value''</code>: The default starting value when the player first opens the tome.</li>
<li><code>''label''</code>: The label which is displayed on the character sheet beside the item.</li>
<li><code>''alt''</code>: The tooltip text for when the player mouse-overs the item</li></ul>
Additionally there are styling attributes which can include css:
<ul><li><code>''itemstyle''</code>: The style of the item's container on the character sheet.</li>
<li><code>''labelstyle''</code>: The style of the item's label.</li>
<li><code>''inputstyle''</code>: The style of the item's input element.</li></ul>
You can make a csitem that holds multiple values by giving it the "<code>array</code>" attribute, and assigning multiple values to it seperated by the "<code>|</code>" character. Here is an example that will create a group of toggleable elements that begin on, on, and off:
<div style="border:1px solid var(--textCol);padding:10;font-family:monospace;"><small><code>`<toggle array values="1|1|0" name="saves">`</code></small></div>
Character sheet value changes are tracked in the game history and so can be undone and redone.
[[To learn something else->Learning how to use AdventureTome]] ''0.2.1 (2023/8/2)''
<ul><li>Tries to prevent extra lines being inserted before html tables defined in a passage, this was caused by line-breaks within the table tags being parsed as line breaks to display. Contents of td elements should remain unaffected.
</li><li>Fixed bookmarking peeked pages not working
</li><li>Fixed “-peek” links not working sometimes from within swapped text
</li><li>Adjusted page & panel sizing so they shouldn’t get clipped when changing screen orientation on mobile
</li><li>UI in general should fit better on tablet screens, and be a little smoother (except on iOS chrome, I have NO idea why it can get so laggy there)</li></ul>
''0.2.0 (2023/7/29)''
<ul><li>Added page search to the menu, lists all pages that contain the specified text
</li><li>die csitems can now have a “dietype” attribute. This defaults to “6pips” (a pipped 6-sided die), but you can now set this value to “coin” (a 2 sided die with “heads” and “tails” faces), “dX” (where X is a number value greater than 1), or a string with multiple faces separated by a “|” character for custom dice.
</li><li>Added font size and family settings. For now at least, these only effects text on the displayed page, and peeked text. Players can use this to overwrite an author’s text styling, so try to keep that in mind if you’re doing complex layout with text - make sure it’s still legible with different fonts and sizes.
</li><li>Added a dice animation setting (Normal, Simple, None), effects the dice rolling animation quality. This setting does not appear unless there is a “die” csitem defined.
</li><li>Die csitems now have a “dieBG” attribute, the contents of which will be added to an element behind the die faces - this is so that you can include a custom die appearance/shape. Recommended is to pass a 100px square svg (or other image).
</li><li>The “contents” tag is now “menulinked”, and supports adding multiple passages to the menu. Useful if you have multiple pages a player will need to reference (eg, contents, index, combat rules, etc). If you want to make a credits/about passage, this is a good way to present it. These can be ordered by tagging as “menulinked_123”
</li><li>Links can now be formatted as `[@passageName@]` instead of `[`[passageName]`]`, AdventureTome will treat these exactly the same, but Twine won’t. You can use this new formatting when you don’t want twine to display links while you are editing - useful if you don’t want to be distracted by a contents page that links to many nodes across your story.
</li><li>Added new text swaps `$$story_name$$` and `$$story_ifid$$` which will show the story’s name and IFID respectively.
</li><li>Links with the display text of just two quotation marks (eg: `[`[“”->PassageName]`]`) will display only the linked passage title, and not a “turn to 123” prompt. Even if the passage is a numbered one.
</li><li>Passage links with the display text “turnto” can now be capitalised if you instead use “Turnto”
</li><li>Dice now start with the value specified in their csitem definition
</li><li>Dice values are saved between sessions
</li><li>Dice can be manipulated with s functions: csSet, csSetTo, csAdd, csSubtract (the result will be clamped based on the number of faces the die has)
</li><li>When peeking a passage from a menu (search, menulinks), there is now a button to return to that menu above the peek view
</li><li>“Clear Game History” is now “Clear Game Progress”, to reflect that it now also reverts “nohistory” csitems to their initial values
</li><li>Properly sanitised passage names and links with the symbols &, “, and ‘ that would sometimes break
</li><li>Each passage’s formatting is parsed only once, (on its first display or when first searched, instead of every time). This should be better for battery use and speed up returning to pages with a lot to parse.
</li><li>Scripts in passages that are peeked are now added when the peek modal appears, and removed when it goes or changes.
</li><li>AdventureTome’s HTML is now somewhat minified
</li><li>Removed the “edit bookmarks” menu because it was not necessary in addition to the bookmarks panel
</li><li>Removed “fixedbookmark” since a bookmark that cannot be removed would be confusing to the user. Use “menulinked” instead.
</li><li>Fixed game history scroll area extending below the view area in the minimal layout
</li><li>Fixed the minimal view’s character sheet button not displaying the name of the first character sheet when the tome is initialised
</li><li>Fixed bug where escaped formatting broke passage rendering if there was no whitespace after the final backtick
</li><li>Fixed issue where html tags (and things that appeared to be html tags) in character sheets were formatted inconsistently compared to other passages
</li><li>Fixed bug where csitem values in an array would not load if there was no saved data for each previous array item
</li><li>new javascript minification settings mean more of the code is mangled/compressed</li></ul>
''0.1.1 (2023/7/24)''
<ul><li>Added “settings” to the menu, moved “clear history” and “edit bookmarks” there, and added a setting for the layout (auto, full, minimal - auto is the default and behaves as before)
</li><li>Numpad return will now act as a ‘submit’ for single-line csitem inputs like text and number.
</li><li>Fixed the “turn to 123” number displays for some types of links displaying the wrong number if you have more or less than 1 frontmatter page
</li><li>Fixed `$$passage_[passageName]$$` displaying the wrong passage number/title sometimes
</li><li>Fixed issue where continuing from a previous undo state wouldn’t erase the saved data of subsequent history actions that followed that state originally.</li></ul>
''0.1.0 (2023/7/23):''
<ul><li>You can now have multiple character sheets for a story. Character sheets are defined by the “charactersheet” tag, their passage name will be used as the display for the tab. You can order the tabs by numbering the tags “charactersheet_1”, “charactersheet_2”, etc. (csitem names between sheets must still be unique, this means the same csitem can exist on multiple sheet tabs and hold the same value)
</li><li>Added bookmarks, these are saved independently of game history and are accessible from the menu. Passages with the “bookmarked” tag will automatically be bookmarked when the tome is first opened. Passages with the “fixedbookmark” tag will be always bookmarked (the player cannot remove it).
</li><li>Added chapters, chapters appear in order but their passages are shuffled. Set chapter with a tag of “chapter_123” (by default, all shuffled passages go into chapter 0). You can specify a chapters start and end passages with “chapter_start” and “chapter_end”. - Keep in mind that fixed number passages will be inserted into whatever chapter has their specified passage number.
</li><li>Added toggleable dark mode
</li><li>csitems can now have an “array” attribute, allowing a single csitem to hold multiple values. Initial values are specified by assigning the “values” attribute with values seperated by the ‘|’ character. Existing csFunctions now have an additional optional parameter to specify the index of the value you are operating with (which will default to 0 - the first value in the csitem’s array)
</li><li>Added a “toggle” csitem type, an on/off flag that functions like a check box.
</li><li>Dice now bounce when rolled, and have a slight motion blur effect
</li><li>Added controls to turn the page on each side of it so that there is always a turn control visible no matter what the scrolling state is. This should make flicking through pages much simpler.
</li><li>Multiple elements of the default UI can now work for a single csitem, so they an input can appear in more than one place
</li><li>Fixed issue where peeks on iOS browsers resulted in zero-height passage views
</li><li>New build process so javascript and css for the story format are minified.
</li><li>Moved as much styling as possible to css so hardly any is hard-coded in html
</li><li>Fixed some csitems not having the correct default style applied
</li><li>text and notes csitems now default to a fixed width
</li><li>New default csitem styling
</li><li>Replaced “Go To Page” ui with a “Turn To…” dialog that can go to a specified page or passage number.
</li><li>Adjusted the way character sheets are parsed so that they can include `$$csval_name$$` replacements without showing a warning
</li><li>passage headers and footers now use the correct “passage” class for styling (if you want the text aligned centrally again, do it with html tags in those passages)
</li><li>Various UI improvements
</li><li>Using csSet() will no longer add a new step to the history if there is no change to the value
</li><li>All default csitem UI inputs now use a contenteditable element
</li><li>The page will only show a “Loading…” message until the tome has been initialised, if the tome fails to initialise then an error message will be displayed.</li></ul>
''0.0.4 (2023/7/15):''
<ul><li>Stories without a character sheet passage will now simply be displayed without the character sheet UI.</li><li>Game history controls are now fixed to the top of the panel and do not scroll away</li><li>Added peek dialog, links followed with “-peek” will display in a popup. If the link is to a passage that has a page, an option to turn to that page will be displayed. Peeks can also be triggered with the peek() function (the function can accept either a page index, or a passage name). The peek dialog can be closed with the closePeek() function.</li><li>Added a turnTo() function, like peek it can take a page index or passage name. If the passage specified doesn’t have a page, it will peek instead of turning to it.</li><li>If a passage is tagged “contents” there will be an extra navigation button to peek it. This works even if the passage is tagged ‘hidden’</li><li>Links to hidden passages now work, and will open in a peek view since they don’t have an actual page</li><li>Added ability to have passage link display without the “turn to XYZ” instruction, it will appear as a normal link if the display text is enclosed by quotation marks, eg `[ [“display text->passageName] ]`</li><li>browser forward and back are now essentially undo/redo to previous/next page turns, though for now it may be a little imperfect, and only covers page turns that happened since the page was loaded</li><li>csitems can now have the “nohistory” attribute which will seperate them from the game history: undo/redo will not change the value, and changing the value does not create an undoable action. Be careful using cs functions on this kind of item because there will be no undo for the player. nohistory csitems have still have their values saved between sessions (and will persist even if the history is cleared)</li><li>added functions beginActionGroup([description]) and endActionGroup(), all character sheet changes through the cs functions that occur between begin and end will be grouped into a single item in the game history, with the provided description. It is *essential* that you call endActionGroup() when you are done, or all future actions including page turns and other changes by the user will be added to the unclosed group, breaking game history for them.</li><li>added `$$csval_[name]$$` to insert the current value of a csitem into a passage, it is updated as the csitem value changes.</li><li>added `$$page_[passagename]$$` and `$$passage_[passagename]$$` replacements to get the page number or page title of a specified passage</li><li>Added a text swapping/replacement system, create a passage named “passagetextswaps” and difine the contents in the format of `“thingToReplace||Text that appears instead||”`, the replacement text can be across multiple lines. make sure your “thingToReplace” text is more than two characters, and keep in mind that it will replace ALL instances of that text (even in passage links) unless it appears within unformatted text (within backticks)</li><li>Backticks can now be displayed without escaping formatting by using two concurrently ````</li><li>Scripts entered through twine’s “twine-user-script” section will now execute, starting after the tome has initialised. The order embedded scripts are added to the DOM and executed are the twine user script, scripts in the character sheet passage, and scripts in the first page. From then scripts are added to the DOM from passages as they are displayed (in the order of header (if shown), main passage, and footer (if shown). twine user scripts and character sheet scripts will remain part of the DOM, scripts loaded from pages will be removed when the page changes.</li><li>twine-user-stylesheet rules will now properly override corresponding rules for the default AdventureTome style</li><li>in the narrow view layout, the history and character sheet buttons are now toggles, returning to the page if their panel is already visible</li><li>pages no longer use hash marking, and instead use queries of ?page=pageNumber. this is so book navigation and page linking can work better with browser history</li><li>contents of `<div>` and `<td>` now have their whitespace trimmed before display</li><li>turning to a new page will now scroll the page view to the top</li><li>fixed bug when using ‘go to page’ to try to go to a page before 1, or after the last page. It will now just turn to whichever is nearest instead.</li><li>fixed bug caused by linking to a non-existent passage</li><li>fixed bug caused by setting csitem values when there was no display/input for the csitem to update</li><li>fixed potential bugs caused by not finding a ‘charactersheet’ passage</li><li>fixed `$$passage_total$$` not working</li><li>fixed character sheet tab button appearing slightly offset</li></ul>
''0.0.3 (2023/7/9):''
<ul><li>Added functions to change csitems from interactive elements in a passage: csAdd(name, value), csSubtract(name, value), csSet(name, value), csSetTo(name, otherName), csAppend(name, value), and csPrepend(name, value). There is also a csGet(name) function to access the current value.</li><li>added “uneditable” csitem type, to display uneditable text. it is not displayed if it has no value.</li><li>added “notes” csitem type, it’s mostly for entering long amounts of text and has no display to style, just the input</li><li>added replaceable texts $$passage_this$$ and $$passage_total$$</li><li>Rebuilt the passage parsing/formatting code from scratch to fix several bugs, the new parsing also allows for embedded `<style>` and `<script>` tags in passages.</li><li>Passages with a tag ‘notitle’ will not have the title/passage number displayed at the top of their page</li><li>Changed data saving so that game progress is unique to each file name and path.</li><li>fixed minor bug where page number replacements could happen only once per paragraph</li><li>fixed bug where game history would not save if you were ‘repeating’ an action (eg changing HP twice in a row)</li></ul>
''0.0.2 (2023/7/7):''
<ul><li>Game history will save and load using localstorage, and can be cleared by the user to restart
</li><li>added a “die” csitem type, use it to add a pipped d6 to the character sheet that can be clicked for random numbers
</li><li>made a warning message that appears above the page if adventuretome encounters certain issues it cannot remedy (eg, a csitem not properly named, missing pages, or loading gamehistory for csitems that no longer exist or have been renamed)
</li><li>adjusted css for page/passage so it is better centered, and won’t be obsured by the history and character sheet tabs unless the window is very narrow
</li><li>url hashes are now used so specific pages/passages can be linked to
</li><li>made adjustments so the display on narrow screens is useable (making tabs for the character sheet, page, and history. showing only one at a time)
</li><li>Character sheet now starts hidden
</li><li>the display layout (page, history, and character sheet visibility) are saved and loaded between sessions.
</li><li>added css variables for all main colours so the color scheme is easier to modify
</li><li>changed csitem input style so there are display items and input items, which is visible depends on if the item has focus.
</li><li>completely reworked how csitems are formatted, parsed, and displayed.</li></ul>
''0.0.1 (2023/7/4):''
<ul><li>Ported from WritingFantasy 1.1.1, made single passage viewable at a time, added basic character sheet options, added undo/redo history for page turns and character sheet value changes</li></ul>This is a passage that will get shuffled into the rest, even though no other passage links to it.
However, because it has the tag '<code>fixednumber_5</code>', it will always be passage number 5!There are functions that can be used to alter the character sheet items and have the changes reflected in the game history. Here is an example of the ''<code>csAdd([name],[value])</code>'' function and how to use it:
<small><code>`<button onclick="csAdd('HP',3)">Add 3 HP</button>`</code></small>
<button onclick="csAdd('HP',3)">Add 3 HP</button>
Here is a list of the functions and what parameters they take (with examples):
''<code>`csSubtract([name],[value])`</code>''
<button onclick="csSubtract('HP',7)">Lose 7 HP!<br><br>csSubtract('HP',7)</button>
''<code>`csSet([name],[value])`</code>''
(Keep in mind that non-number values must be enclosed in apostrophes or quote marks)
<button onclick="csSet('HP',0)">Lose All HP!<br><br>csSet('HP',0)</button>
<button onclick="csSet('charaName','Charlie')">Set name to Charlie<br><br>csSet('charaName','Charlie')</button>
''<code>`csSetTo([name1],[name2])`</code>''
<button onclick="csSetTo('HP','MaxHP')">Restore HP!<br><br>csSetTo('HP','MaxHP')</button>
''<code>`csAppend([name],[value])`</code>''
<button onclick="csAppend('charaName',' the Hero')">Append 'the Hero' to name<br><br>csAppend('charaName',' the Hero')</button>
''<code>`csPrepend([name],[value])`</code>''
<button onclick="csPrepend('charaName','Amazing ')">Prepend 'Amazing' to name<br><br>csPrepend('charaName','Amazing ')</button>
There is also a ''<code>csGet([name])</code>'' function that can be used to retrieve character sheet values through [[javascript->Embedding Complex JavaScripts]]
[[Learning how to use AdventureTome<-Want to go back to the start?]] It is possible to embed javascript code into a passage within <code>`<script>`</code> tags, and have that code interact with character sheet items.
Here is a simple example that sets the Max HP to 2d6+strength:
<div style="border:1px solid var(--textCol);padding:10;font-family:monospace;"><small><code>`<script>
function myFunction(){
let hp = csGet("str") + d6roll() + d6roll();
csSet("MaxHP",hp);
}
function d6roll(){
return Math.floor(Math.random() * 6) + 1;
}
</script>
<button onclick="myFunction()">Roll Now!</button>`</code></small></div><script>
function myFunction(){
let hp = csGet("str") + d6roll() + d6roll();
csSet("MaxHP",hp);
}
function d6roll(){
return Math.floor(Math.random() * 6) + 1;
}
</script>
<button onclick="myFunction()">Roll Now!</button>
You can use any of the functions listed [[here->Simple JavaScript Interactions]] in your scripts to safely get and set character sheet items in a way that will update their displays and correctly work with the game history for proper undo/redo.
A key pair of functions you may wish to use if you are making several changes to the character sheet at once are <code>beginActionGroup(description)</code> and <code>endActionGroup()</code>. Changes made between these two calls will all be grouped into a single action in the game history, with the provided description. Here's an example:
<div style="border:1px solid var(--textCol);padding:10;font-family:monospace;"><small><code>`<script>
function newClass(className,hp,str,dex,mag){
beginActionGroup("Changed class to "+className);
csSet("HP",hp);
csSet("MaxHP",hp);
csSet("str",str);
csSet("dex",dex);
csSet("mag",mag);
endActionGroup();
}
</script>
<button onclick="newClass('Rogue',9,2,4,1)">Rogue</button>
<button onclick="newClass('Mage',8,1,1,5)">Mage</button>`</code></small></div>
<script>
function newClass(className,hp,str,dex,mag){
beginActionGroup("Changed class to "+className);
csSet("HP",hp);
csSet("MaxHP",hp);
csSet("str",str);
csSet("dex",dex);
csSet("mag",mag);
endActionGroup();
}
</script><button onclick="newClass('Rogue',9,2,4,1)">Rogue</button>
<button onclick="newClass('Mage',8,1,1,5)">Mage</button>
**Warning:** It is very important to call <code>endActionGroup()</code> after beginning it, as failing to do so will likely break the game history for the player, especially if they begin performing their own actions that are added to the group.
Want to learn [[Even more things JavaScript can do in AdventureTome?|Using JavaScript to alter AdventureTome]]
[[Done with the fancy stuff?->Learning how to use AdventureTome]] <div class="passageTitle">Contents</div>[[""->Introduction]]
[["Overview"->Learning how to use AdventureTome]]
''Basics:''
[[""->Formatting Text]].
[[""->Passage Links]].
''Passage Organisation:''
[[""->Passage Order]].
[[""->Hidden Passages]].
''Character Sheets:''
[[""->Character Sheets]].
''Getting into the weeds:''
[[""->Page Headers and Footers]].
[[""->Adding a passage to the Menu]].
[[""->Text Swaps]].
''Advanced topics:''
[[""->Simple JavaScript Interactions]].
[[""->Embedding Complex JavaScripts]].
[[""->Using JavaScript to alter AdventureTome]].
''tl;dr:''
[["Cheat Sheet"|Quick Reference]]
''Also:''
[[""|Change Log]]
[[""|Thanks]]<div align="center"><h1>Quick Reference</h1></div><h2>Passage Formatting</h2>`''`''bold''`''`
`//`//italics//`//`
`~~`~~strikethrough~~`~~`
`^^`^^superscript^^`^^`
`*`*emphasis*`*`
`**`**strong emphasis**`**`
`__`__underline__`__`
``Formatting escaped``
<h2>Passage Links</h2><small><code>`[[Passage Links]]`</code></small> = [[Passage Links]]
<small><code>`[[display text->Passage Links]]`</code></small> = [[display text->Passage Links]]
<small><code>`[[Passage Links<-display text]]`</code></small> = [[Passage Links<-display text]]
<small><code>`[[->Passage Links]]`</code></small> = [[->Passage Links]]
<small><code>`[[#->Passage Links]]`</code></small> = [[#->Passage Links]]
<small><code>`[[turnto->Passage Links]]`</code></small> = [[turnto->Passage Links]]
<small><code>`[[Turnto->Passage Links]]`</code></small> = [[Turnto->Passage Links]]
<small><code>`[["display text"->Passage Links]]`</code></small> = [["display text"->Passage Links]]
<small><code>`[["display text"->Passage Links]]-peek`</code></small> = [["display text"->Passage Links]]-peek
<small><code>`[@The editor doesn't notice this link->Passage Links@]`</code></small> = [@The editor doesn't notice this link->Passage Links@]
<h2>Passage Names</h2><code>pageheader</code>
<code>pagefooter</code>
<code>passagetextswaps</code>
<h2>Passage Tags</h2><code>hidden</code> //or// <code>skip</code>
<code>menulinked</code> //or// <code>menulinked_123</code>
<code>noheader</code>
<code>nofooter</code>
<code>notitle</code>
<code>charactersheet</code>
<code>charactersheet_123</code>
<code>ending</code> //or// <code>last</code>
<code>fixednumber_123</code> //or// <code>123</code>
<code>frontmatter</code> //or// <code>frontmatter_123</code>
<code>backmatter</code> //or// <code>backmatter_123</code>
<code>chapter_123</code>
<code>chapter_start</code>
<code>chapter_end</code>
<code>bookmarked</code>
<code>gb-front-cover</code>
<code>gb-introduction</code>
<code>gb-rear</code>
<code>gb-back-cover</code>
<h2>csitem Types</h2><code>number</code>
<code>text</code>
<code>toggle</code>
<code>notes</code>
<code>uneditable</code>
<code>die</code>
<h2>csitem Attributes</h2><code>name</code>
<code>value</code> //or// <code>values</code>
<code>label</code>
<code>alt</code>
<code>array</code>
<code>nohistory</code>
<code>itemstyle</code>
<code>labelstyle</code>
<code>inputstyle</code>
<h2>Text Swaps</h2><code>`$$page_this$$`</code>
<code>`$$page_total$$`</code>
<code>`$$page_[passageName]$$`</code>
<code>`$$passage_this$$`</code>
<code>`$$passage_total$$`</code>
<code>`$$passage_[passageName]$$`</code>
<code>`$$csval_[csitemName]$$`</code>
<code>`$$story_name$$`</code>
<code>`$$story_ifid$$`</code>
to add your own swaps, in a passage named "<code>passagetextswaps</code>":
<div style="border:1px solid var(--textCol);"><small><code>`thingToReplace||Text that appears instead||
otherThingToReplace||Replacement that
goes across
multiple lines||
thirdThingToReplace||third replacement`</code></small></div>etc...
<h2>Functions</h2><small><code>csGet(name [, valueIndex])</code>
<code>csSet(name, value [, valueIndex])</code>
<code>csSetTo(name, otherName [, valueIndex, otherValueIndex])</code>
<code>csAdd(name, value [, valueIndex])</code>
<code>csSubtract(name, value [, valueIndex])</code>
<code>csAppend(name, value [, valueIndex])</code>
<code>csPrepend(name, value [, valueIndex])</code>
<code>peek(pageIndex or passageTitle)</code>
<code>closePeek()</code>
<code>turnTo(pageIndex or passageTitle)</code>
<code>beginActionGroup(description)</code>
<code>endActionGroup()</code>
<code>addSwap(stringToReplace, replacementString)</code></small>If there is a passage with the tag "<code>menulinked</code>", a button linking to it will be added to the game menu (accessible from the hamburger button below each page) that will show that page in a peek view.
You can use this to present pages the player may frequently want to check, such as Contents, Index, Game Rules, etc. Alternatively it is a good way to highlight an "About the Author" section and other passages you'd like to be more prominent.
The order of multiple menu-linked passages can be set by appending the tag with an underscore and a number ("menulinked_1", "menulinked_2", etc)
Keep in mind that menu-linked page will be shuffled into the other passages unless it has the "<code>hidden</code>" tag or some other tag that effects [[Passage Order]]In addition to passage formatting, certain strings of text will be replaced dyanmically, some of these apply to all AdventureTome stories, but you can also create your own.
The included text swaps are:
<code>`$$page_this$$`</code> - displays the current page number
<code>`$$page_total$$`</code> - displays the total number of pages
<code>`$$page_[passageName]$$`</code> - displays the page number of a specified passage
<code>`$$passage_this$$`</code> - displays the current passage number (or name, if it is not a numbered/shuffled passage)
<code>`$$passage_total$$`</code> - displays the total number of shuffled passages
<code>`$$passage_[passageName]$$`</code> - displays the passage number (or name) of a specified passage
<code>`$$csval_[csitemName]$$`</code> - displays the current value of a specified csitem
<code>`$$story_name$$`</code> - displays the name of the story as specified in twine
<code>`$$story_ifid$$`</code> - displays the the IFID that twine has generated for the story
to add your own swaps, add a passage named "<code>passagetextswaps</code>" and within it write your desired text swaps in this format:
<div style="border:1px solid var(--textCol);"><small><code>`thingToReplace||Text that appears instead||
otherThingToReplace||Replacement that
goes across
multiple lines||
thirdThingToReplace||third replacement`</code></small></div>etc...
Keep in mind that unless they have been escaped **every** instance of text that matches a swap will be changed, so try to select unique terms!
If you have a lot of repeated elements in your story (eg roll prompts, item descriptions, or rule reminders) you can save a lot of time when writing to have use a single swap rather than rewriting it or copy/pasting every time.Some functions are exposed in case you need (or want) to make larger changes to AdventureTome's UI. Using just what has already been covered you should be able to make custom Character Sheet widgets, like this:
<div style="border:1px solid var(--textCol);padding:10;font-family:monospace;"><small><code>`HP: $$csval_HP$$
<button onclick="csAdd('HP',1)">+</button>
<button onclick="csSubtract('HP',1)">-</button>
<button onclick="csSetTo('HP','MaxHP')">Refill</button>`</code></small></div>HP: $$csval_HP$$ <button onclick="csAdd('HP',1)">+</button><button onclick="csSubtract('HP',1)">-</button><button onclick="csSetTo('HP','MaxHP')">Refill</button>
Functions for things other than the character sheet are:
<code>turnTo(page index or passage name)</code>
Will turn to a specified page (if no page exists for the passage, it will be displayed in a 'peek' view instead.
<code>peek(page index or passage name)</code>
Will display a passage in a modal dialog. The dialog has its own close button, and can be closed by the escape key, but you can also close it yourself by calling <code>closePeek()</code>
<code>addSwap(textToReplace, replacementText)</code>
Can be used to add a new textSwap, though for most cases you should probably just use a 'passagetextswaps' passage. [[Text Swaps<-turnto]] for more information.This sheet demonstrates a variety of ways character sheet items (csitems) can be used.
A csitem independent of game history: <toggle nohistory array name="deaths" label="Death Count" values="0|0|0|0|0"> $$deaths$$
A die with a custom dieBG: <die name="atcoin" dietype="d8" dieBG="<img src='https://sophiehoulden.com/twine/aticon.svg' style='width:100px;'>" > $$atcoin$$
AdventureTome is a twine story format inspired by old-school adventure gamebooks, where a player chooses their path through a book, keeping track of a character with pen and paper, and rolling dice when their luck is tested.
Like the WritingFantasy story format, AdventureTome will shuffle twine story passages and show links in a "turn to XYZ" format. Unlike WritingFantasy however, AdventureTome is designed to facilitate play in a web browser rather than print and play - with an author-customisable character sheet and a game history with full undo/redo.