Ficdown

Story

A story block is defined by a level-one header. The story title must be an anchor that links to the first scene. The anchor must not contain conditionals or toggles.

The text of the story block will be the first thing displayed to the player.

# [Awesome Game](/first-scene)

Welcome to Awesome Game by *Some Author*.

Scenes

Scenes are defined by level-two headers. Scene descriptions can contain first-seen blocks and anchors to change the description based on player state or link to other scenes.

To display scene title text that is different from the scene name, you can wrap the scene's name in an anchor and specify the display text as the anchor's title.

## First Scene

This is the text displayed to the player when they visit this scene.

## [Second Scene]("Second Scene Title")

This is the second scene with a different display title specified.

Conditional Scenes

Scene names can be anchors that specify player state conditions that must be met to enter that scene. The anchor must not contain a target or toggles. If multiple scenes with the same name are defined, the player will only see a scene for which their current state satisfies all of the specified conditionals. If the player's state satisfies more than one scene's conditionals, they will see the one that has the most variables. If two scenes are satisfied with the same number of variables, the player will see the one that was defined first in the story file.

If only conditional scenes are defined and it is possible to be linked to that scene with a player state that does not satisfy any of them, this is considered an error in the story file. The safest way to avoid this is to always have a non-conditional version of the scene to fall back on when none of the conditional versions are satisfied.

## My Scene

This is the default scene that the player will see if none of the conditional versions are satisfied.

## [My Scene](?state-one)

The player will see this if their `state-one` variable has been toggled, but not if `state-two` has also been toggled because that matches a more specific conditional scene below.

## [My Scene](?state-one&state-two "Alternate Scene Title")

The player will see this if both `state-one` and `state-two` have been toggled.

First Seen

Description text inside blockquotes will only be displayed to a player the first time they enter that scene.

## My Scene

> This text will only display to the player once.

This text will display to the player every time they enter the scene.

> This text will also only be displayed to the player once.

Actions

Actions are defined by level-three headers. When a state variable is toggled that has a matching action defined, the action's description will be prepended to the next scene description that the player sees. Action names must not themselves be anchors. Anchors can be used within the action description to change text based on player state.

Actions are matched to state variables based on their normalized name.

Actions will be triggered by a toggle for variables even if that variable has been toggled before.

The first time an action is triggered, the toggled variable will be false within the action itself. In subsequent triggerings, the variable will be true. This can be used to differentiate the first time an action is shown.

### My State

This text will be displayed to the player whenever they toggle `my-state`. This is [not](?my-state) the first time the action was triggered.

Anchors

Anchors are used within scene descriptions to link players to other scenes in the story, and to change the description text based on the player state.

Anchors with a target or toggles will be rendered to the player as a clickable link. Anchors with only conditionals will be rendered as normal text.

Anchors can contain any number of conditionals and toggles, but can contain at most one target.

Anchor text cannot contain other anchors. For more more complex modification of scene descriptions you should use conditional scenes instead.

[Text to display when conditions are met|Text to display when conditions are not met](/target-scene?conditional-one&conditional-two#toggle-one+toggle-two)

Targets

The target in an anchor always comes first and is preceeded by a slash "/" character. The target should be the normalized name of the scene it links to. Anchors with a target will be rendered as a clickable link to the player. When they click the link, they will move to the scene specified by the target.

Anchors can have at most one target.

[Go To Scene Two](/scene-two)

Toggles

Toggles are used in anchors to set player state variables to true, and to trigger actions. They are preceeded in an anchor's link with a hash "#". Multiple toggles can be delimited by a plus "+" character. They always appear at the end of the link, after the target and conditionals.

Anchors with toggles will always be rendered as clickable links. If the anchor does not have a target, clicking the link will toggle the variables and then redirect the player back to the current scene.

[Toggle my variables](#toggle-one+toggle-two)

Conditionals

Conditionals are specified in an anchor's link between the target and the toggles. They are preceeded by a question mark "?" and delimited by ampersands "&". They are used to hide or change the displayed text based on the current player state. Conditionals are specified as the name of the variable to test for a true value, or the name of the variable preceeded by an exclamation mark "!" to test for a false value.

If the anchor's text contains a pipe character "|" then the text to the left of the pipe will be displayed if the current player state satisfies all of the conditionals, and the text to the right of the pipe will be displayed if the current player state does not satisfy all of the conditionals. Anchor text with no pipe will be hidden entirely if the player state does not satisfy the conditionals, and anchor text with nothing to the left of the pipe will be hidden if the player state does satisfy the conditionals.

Anchors with only conditionals and no target or toggles will not be rendered as a clickable link. These can be used to easily change a scene's description based on player state.

## My Scene

The last word of this paragraph will change based on the player's state. The `my-state` variable is [true|false](?my-state).

This is some text that will change depending on the state of several variables: [All true|Not all true](?my-state&my-state-two&my-state-three).

This is some text that will change depending on more complicated rules that check for both true and false values: [Satisfied|Not satisfied](?my-state&!my-state-two&!my-state-three).

The links at the end of this description will also change based on the player's state.

[This choice will always appear](/first-choice)

[This choice only appears if my-state is true](/second-choice?my-state)

[This choice only appears if another-state is false](/third-choice?!another-state)

[The text of this choice changes depending on the value of my-state|But it will always appear](/fourth-choice?my-state)

Normalization

Scene and action names are normalized by removing all non-alphanumeric characters, converting everything to lower case, then replacing spaces with dashes. Some examples:

Normalization is applied to scene names when used as the target in anchors, and to action names when triggered by toggles.

Player State

Player state is a collection of boolean variables that are assigned to your game's player and tracked throughout their playthrough of your game. All player state variables start off false. The variables are set to true when a player clicks a link that contains that variable as a toggle. Once toggled, a state variable will be true for the remainder of the playthrough (it cannot be reset to false).

It is not necessary to declare variables anywhere in your story other than where you use them in your story's anchors.

Variables are used in conditional anchors to change the text displayed or hide them entirely.

Conditional anchors wrapped around scene names are used to define conditional scenes.

When using the ficdown.exe tool to compile your story to HTML or epub format, you can pass the --debug flag which will output player state information at the bottom of every page in your story. This can be useful to track down misbehaving links or stories that don't behave the way you expected them to.