Fictional Adventure

Fictional Adventure is a Twine story format that allows publication to Archive Of Our Own, or any other site that allows HTML and CSS but not JavaScript.

• Check out a demo fic on AO3
• Join the Discord
• View the source code

How To Use

Add the story format to Twine

Fictional Adventure is a Twine "story format", basically a plugin that controls how the story will appear. You'll only need to do this once.

1. Open Twine's editor, either installed on your computer or directly in your web browser.

2. From the menubar, click "Twine" and then "Story Formats".

   

3. In the Story Formats window, click "+ Add".

4. In the dialogue box that appears, paste the following URL:
   • https://fictional.tools/adventure/dist/format.js Copy

5. Click the green "+ Add" button. This will add Fictional Adventure to Twine.

   

Create a new story using Fictional Adventure

1. Click "+ New" from the menubar to create a new story.

2. Click "Story" from the menubar, and then "Details".

   

3. A dialogue box will open. From the "Story Format" dropdown, select "Fictional Adventure".

   

4. Create the story. You can check out Twine's reference guide for full instructions, but in short:

   1. Double-click on a passage to open it in a window
   2. Type in contents of each passage as normal. You can use Markdown for formatting like italics, bolds, etc.
   3. Create links to other passages by surrounding text in square brackets. For example, [[Part Two]] will link to a passage named "Part Two" and create it if it doesn't already exist.

   4. To make big, finger-friendly buttons, put your links on their own lines starting with an asterisk:

      * [[Go to Part Two]]
      * [[Or to Part Three]]
      

   5. You can test out your story by clicking "Build" from the menubar and then clicking "Play". This will format your story with Fictional Adventure. Check out the "Preview" section to see your story in action.

      

   6. Once you're ready to publish to AO3 or elsewhere, play your story like above.

      1. Create a work skin on AO3 and paste in the contents of Fictional Adventure's "CSS" box.
      2. Create your fic on AO3 and paste in the contents of the "HTML" box as your chapter contents.
      3. Select your created work skin as the skin for your fic, then save.
   7. Your Twine story is now published to AO3!

If you publish a work using Fictional Adventure, consider adding a link in your end notes:

Created using <a href="https://twinery.org/">Twine</a> and <a href="https://fictional.tools/adventure?utm-source=user-share">Fictional Adventure</a>.

Advanced Features

Customizing Your Work Skin

If you want to customize how your fic appears, you can add custom CSS directly in Twine from the Story > Stylesheet menu. Just enter (or paste in) CSS and it'll be automatically get appended to Fictional Adventure's CSS output.

For example, you can alter the color of the link buttons like this:

li a {
  color: white;
  background-color: #593196;
}

Using Story Flags

If you want to add more complex logic to your story, you can use story flags. Story flags allow for simple "if this then that" sections to be added to your code to track things the player has done, such as picking up items. (In programming terms, story flags are boolean variables.)

Story flags can be either "set" or "unset". They are always "unset" to start with. They can be set by putting the following in a passage of your story:

You pick up the key.

{{set has-key}}

In other passages, you can check whether the flag has been set:

{{#if has-key}}
You have the key!
{{else}}
You don't have the key.
{{/if}}

Story flags can also be unset:

You drop the key.

{{unset has-key}}

Or toggled:

{{toggle has-key}}

Limitations

It's important to note that story flags can greatly increase the word count of the HTML that Fictional Adventure outputs. Since Archive Of Our Own can't run actual scripts, Fictional Adventure will instead generate a copy of each passage in your story for every combination of flags. So if you use one flag, you'll have two copies of each passage. Two flags will have four copies, three flags will have eight copies, and so on.

(Fictional Adventure will automatically trim any unreachable passage states, so you can cut down on the word count by unsetting flags as soon as your story no longer needs them.)

Boolean Logic

You can use complex boolean logic using the and, or, and not subexpressions. (These use Polish notation, with the logical operator first and the operands after.)

{{#if (and first-key second-key)}}
This will appear if both first-key and second-key are set.
{{/if}}

{{#if (or first-key second-key)}}
This will appear if either first-key or second-key are set.
{{/if}}

{{#if (not (and first-key second-key))}}
This will appear if neither first-key nor second-key are set.
{{/if}}

Handlebars

Internally, Fictional Adventure's story flags feature uses the Handlebars template engine. You can optionally use advanced Handlebars features like whitespace control.

Full Example

Passage "Start":

There is a locked door here. You {{#unless has-key}}don't{{/unless~}} have the key.

There is a box here. It is {{#if box-open}}open{{else}}closed{{/if}}.

{{#if has-key}}
* [[Unlock the door|Unlock]]
{{/if~}}
{{#if box-open}}
* [[Pick up the key|Get Key]]
* [[Close the box|Toggle Box]]
{{else}}
* [[Open the box|Toggle Box]]
{{/if}}

Passage "Toggle Box":

{{toggle box-open~}}

You {{#if box-open}}open{{else}}close{{/if~}} the box.

* [[Continue|Start]]

Passage "Get Key":

{{set has-key~}}

You pick up the key.

* [[Continue|Start]]

Passage "Unlock":

{{unset has-key~}}
{{unset box-open~}}

You unlock the door. You win!

* [[Play Again?|Start]]