Ficdown

Note: If you have javascript enabled on this page, many of the tutorial examples are playable right in your browser.

  1. Define Your Story
  2. Define Your Scenes
  3. Link Your Scenes Together
  4. First-Seen Descriptions
  5. Keep Track of State
  6. Conditional Anchors
  7. Actions
  8. Conditional Scenes

Define Your Story

All Ficdown stories start with a level-one heading that defines the story name, followed by some optional introductory text. The author can use the introductory text for any purpose, but may find it a convenient place for story metadata (such as author name, story version, dedication, and so on). The text can contain any formatting other than level-one or -two headings.

# Cloak of Darkness

A basic IF demonstration by **Jane Doe**.

*Version 1.0*

Hurrying through the rainswept November night, you're glad to see the bright lights of the Opera House. It's surprising that there aren't more people about but, hey, what do you expect in a cheap demo game...?

This is technically not a valid story file since there are no scenes yet, so it would throw an error if you tried to play or convert it.

Define Your Scenes

Scenes are defined by level-two headings. Let's add some scenes to our story:

# Cloak of Darkness

A basic IF demonstration by **Jane Doe**.

*Version 1.0*

Hurrying through the rainswept November night, you're glad to see the bright lights of the Opera House. It's surprising that there aren't more people about but, hey, what do you expect in a cheap demo game...?

## Foyer

You are standing in a spacious hall, splendidly decorated in red and gold, with glittering chandeliers overhead. The entrance from the street is to the north, and there are doorways south and west.

## Cloakroom

The walls of this small room were clearly once lined with hooks, though now only one remains. The exit is a door to the east.

## Bar

You walk to the bar, but it's so dark here you can't really make anything out. The foyer is back to the north.

We've now defined three scenes in the story (the foyer, the cloakroom, and the bar). This still isn't a valid story since there's no indication of which scene is the first. It would also be impossible to play even if it was valid, since none of the scenes are linked together yet.

Link Your Scenes Together

Technically, the only required link in a story file is from the story's title to its first scene. If you stopped there, your story would be pretty short—the player would be presented with the title page and introductory text, would click to continue to the first scene, and then the game would be over. We can make things a little more interesting by adding links to our scenes that will take the player to other scenes when clicked.

Scene links are specified using standard Markdown anchor syntax. The anchor's target should be the lower-case name of the destination scene with all non-alphanumeric characters stripped, and spaces replaced with a dash. For example a scene named "Ben's Room" would be linked to using the target "bens-room".

# [Cloak of Darkness](/foyer)

A basic IF demonstration by **Jane Doe**.

*Version 1.0*

Hurrying through the rainswept November night, you're glad to see the bright lights of the Opera House. It's surprising that there aren't more people about but, hey, what do you expect in a cheap demo game...?

## Foyer

You are standing in a spacious hall, splendidly decorated in red and gold, with glittering chandeliers overhead. The entrance from the street is to the north, and there are doorways [south](/bar) and [west](/cloakroom).

## Cloakroom

The walls of this small room were clearly once lined with hooks, though now only one remains. The exit is a door to the [east](/foyer).

## Bar

You walk to the bar, but it's so dark here you can't really make anything out. The foyer is back to the [north](/foyer).

This is now a valid Ficdown file, and you can play it by clicking the "Play" button. You'll probably notice that it's not a very interesting game yet, as it just allows the player to move back and forth between the three defined scenes, and never ends.

First-Seen Descriptions

Any text placed in a blockquote (lines preceeded by a ">" character) will only be displayed the first time a reader visits that scene. This is a simple way to re-use scenes without necessarily replaying the same text within that scene every time.

# [Cloak of Darkness](/foyer)

A basic IF demonstration by **Jane Doe**.

*Version 1.0*

Hurrying through the rainswept November night, you're glad to see the bright lights of the Opera House. It's surprising that there aren't more people about but, hey, what do you expect in a cheap demo game...?

## Foyer

> You quickly close the door behind you, and shake the water from your cloak. It is a handsome cloak, of velvet trimmed with satin, and slightly splattered with raindrops. Its blackness is so deep that it almost seems to suck light from the room.

You are standing in a spacious hall, splendidly decorated in red and gold, with glittering chandeliers overhead. The entrance from the street is to the north, and there are doorways [south](/bar) and [west](/cloakroom).

## Cloakroom

The walls of this small room were clearly once lined with hooks, though now only one remains. The exit is a door to the [east](/foyer).

## Bar

You walk to the bar, but it's so dark here you can't really make anything out. The foyer is back to the [north](/foyer).

If you play this example, you'll see that the description of your cloak is only displayed the first time you enter the foyer.

Keep Track of State

State in a Ficdown game is a list of boolean variables, all of which start off false. State variables can be toggled to true via special links of the form [Click here](#my-variable). In that example, when the player clicks the link, the variable called my-variable will be toggled to true. There is no need to declare variables anywhere before using them in an anchor. You can link to a scene and toggle a variable at the same time by including both a target and a toggle in the same anchor; for example, [Go north](/north#went-north) would both link the player to the north scene and toggle the went-north state variable to true.

You can include multiple toggles in the same anchor by separating them with a plus sign. For example, [Toggle two variables](#variable-one+variable-two). Once a state variable has been toggled, it cannot be "untoggled," it will remain true for the rest of the game.

Now that you know how to toggle state variables in your game, you can change your scene descriptions based on the player's current state. This allows you to present or branch your game differently depending on choices the player made at any point earlier in the game.

Conditional Anchors

Conditionals are specified in an anchor with a question mark, separating multiple variables with an ampersand "&" character. For example, the anchor [Anchor text](?state-one&state-two) would only display the anchor text to the player if their state-one and state-two variables had already been toggled earlier in the story. You can also check if a state variable has not been toggled yet by prepending an exclamation mark "!" to its name. If you wanted the anchor text to display only if state-one was true and state-two was false, it would look like [Anchor text](?state-one&!state-two). In these examples, since no target scene or toggles are specified in the anchor, the text in the scene would not be a clickable link—just normal text.

If you include a pipe character "|" in the anchor's text, you can specify alternate text to display when the condition is not met. For example, [my-state is true|my-state is false](?my-state). Either side of the pipe can be left empty to remove the anchor entirely when the conditionals merit. For example, the following anchors are equivalent to one another: [You have a key](?got-key) and [|You have a key](?!got-key).

You can combine toggles and conditionals in the same anchor—even using the same variable for both. For example, the anchor [Push the button again.|Push the button.](?pushed-button#pushed-button) would present the player with a link that says "Push the button." Once they click it, pushed-button would be toggled to true and the scene would reload, but with the link's text changed to "Push the button again." You could also specify a target scene for the link if you wanted to take the player elsewhere instead of simply reloading the current scene.

Anchors can have at most one target, but as many conditionals and toggles as you like. An example of a particularly complex anchor would be [Complex anchor](/new-scene?state-one&state-two&!state-three#state-three+state-four). Fun times!

Lets see how state variables and conditionals can add some more interactivity to our example game:

# [Cloak of Darkness](/foyer)

A basic IF demonstration by **Jane Doe**.

*Version 1.0*

Hurrying through the rainswept November night, you're glad to see the bright lights of the Opera House. It's surprising that there aren't more people about but, hey, what do you expect in a cheap demo game...?

## Foyer

> You quickly close the door behind you, and shake the water from your cloak. It is a handsome cloak, of velvet trimmed with satin, and slightly splattered with raindrops. Its blackness is so deep that it almost seems to suck light from the room.

You are standing in a spacious hall, splendidly decorated in red and gold, with glittering chandeliers overhead. The entrance from the street is to the north, and there are doorways [south](/bar) and [west](/cloakroom).

## Cloakroom

The walls of this small room were clearly once lined with hooks, though now only one remains. The exit is a door to the [east](/foyer).

[Your cloak is on the floor here.](?dropped-cloak)
[Your cloak is hanging on the hook.](?hung-cloak)

- [Examine the hook.](#examined-hook)
- [Hang your cloak on the hook.](?!lost-cloak#lost-cloak+hung-cloak)
- [Drop your cloak on the floor.](?!lost-cloak#lost-cloak+dropped-cloak)

## Bar

You walk to the bar, but it's so dark here you can't really make anything out. The foyer is back to the [north](/foyer).

If you play the above game, you'll see that you can now either hang your coat on the hook, or drop it on the floor of the cloakroom, and the scene's description will change depending on which choice you make. You'll notice there's also another option in the cloakroom to examine the hook which currently doesn't do anything.

Actions

Sometimes you will want to provide feedback to the player when they have toggled a specific variable without having to create a whole new scene. For example, we want to give the player a description of the hook in the cloakroom when they examine it. This would certainly be possible with an additional scene (basically a copy of the current cloakroom scene with the hook's description prepended), but that would mean having what are essentially duplicate scenes all over the place, which stinks. A game with many rooms containing examinable hooks would quickly become a nightmare to manage.

The solution to this in Ficdown is actions, which are specified by a level-three header. Whenever a variable is toggled that has a corresponding action block defined, the action text will be prepended to the following scene (even if it’s the same one you toggled the state from). We can use an action to wire up the "Examine hook" link in our example story like this:

# [Cloak of Darkness](/foyer)

A basic IF demonstration by **Jane Doe**.

*Version 1.0*

Hurrying through the rainswept November night, you're glad to see the bright lights of the Opera House. It's surprising that there aren't more people about but, hey, what do you expect in a cheap demo game...?

## Foyer

> You quickly close the door behind you, and shake the water from your cloak. It is a handsome cloak, of velvet trimmed with satin, and slightly splattered with raindrops. Its blackness is so deep that it almost seems to suck light from the room.

You are standing in a spacious hall, splendidly decorated in red and gold, with glittering chandeliers overhead. The entrance from the street is to the north, and there are doorways [south](/bar) and [west](/cloakroom).

## Cloakroom

The walls of this small room were clearly once lined with hooks, though now only one remains. The exit is a door to the [east](/foyer).

[Your cloak is on the floor here.](?dropped-cloak)
[Your cloak is hanging on the hook.](?hung-cloak)

- [Examine the hook.](#examined-hook)
- [Hang your cloak on the hook.](?!lost-cloak#lost-cloak+hung-cloak)
- [Drop your cloak on the floor.](?!lost-cloak#lost-cloak+dropped-cloak)

### Examined Hook

It's just a small brass hook, [with your cloak hanging on it|screwed to the wall](?hung-cloak).

## Bar

You walk to the bar, but it's so dark here you can't really make anything out. The foyer is back to the [north](/foyer).

As you can see, you can include anchors in the action text as well, including conditional anchors on the state that triggers the action. The first time a player toggles a variable that triggers an action, that variable will still be false when the action is displayed. Every subsequent time it will be true. The following example demonstrates how this could be useful:

## Some Scene

There's a guy here.

[Tell him he's cool!](#cool-guy)

### Cool Guy

[The guy shrugs. "You said that already," he says.|"Gee, thanks!" says the guy.](?cool-guy)

In this example, the first time the player clicks "Tell him he's cool!", the guy will say "Gee, thanks," but will shrug it off each subsequent time the player clicks it.

Conditional Scenes

Sometimes you will want to connect a link to different scenes depending on the current state. You could do this by creating multiple conditional links, but it could get hard to maintain if you're linking to the same place from multiple scenes. The solution to this is conditional scenes.

You can define the same scene multiple times, and wrap the scene name with conditional anchors that define the state that the player must match to enter that scene. Take, for example, the following scene definitions:

## Home

You arrive at your house. There is nothing out of the ordinary about it.

## [Home](?broken-window)

You arrive at your house. You frown at the broken window out front.

## [Home](?broken-window&fixed-window "Fixed Home")

You arrive at your house. You nod approvingly at the newly replaced window.

If you were to link to the home scene from anywhere else in this story, which scene the player would land in would depend on whether their broken-window and fixed-window variables had been toggled previously in the story. To enter a scene, the player must satisfy all of the conditions in the anchor. If the player matches all of the conditions for multiple scenes, the one with the most matched conditions will win. If the player satisfies the conditions on multiple scenes with the same number of conditions, they will enter the one that was defined first in the story. In the example, if only broken-window had been toggled, they would land on the second scene. If both variables had been toggled, they would land on the third scene.

The third scene also shows how to define an alternate display name. If you want to use the same scene name for multiple scenes like this, but have the story display different scene names to the player, you can define the alternate display name for the scene in double quotes in the anchor.

We can use this final convention to complete our Cloak of Darkness example game:

# [Cloak of Darkness](/foyer)

A basic IF demonstration by **Jane Doe**.

*Version 1.0*

Hurrying through the rainswept November night, you're glad to see the bright lights of the Opera House. It's surprising that there aren't more people about but, hey, what do you expect in a cheap demo game...?

## [Foyer]("Foyer of the Opera House")

> You quickly close the door behind you, and shake the water from your cloak. It is a handsome cloak, of velvet trimmed with satin, and slightly splattered with raindrops. Its blackness is so deep that it almost seems to suck light from the room.

You are standing in a spacious hall, splendidly decorated in red and gold, with glittering chandeliers overhead. The entrance from the street is to the north, and there are doorways [south](/bar) and [west](/cloakroom).

## Cloakroom

The walls of this small room were clearly once lined with hooks, though now only one remains. The exit is a door to the [east](/foyer).

[Your cloak is on the floor here.](?dropped-cloak)
[Your cloak is hanging on the hook.](?hung-cloak)

- [Examine the hook.](#examined-hook)
- [Hang your cloak on the hook.](?!lost-cloak#lost-cloak+hung-cloak)
- [Drop your cloak on the floor.](?!lost-cloak#lost-cloak+dropped-cloak)

### Examined Hook

It's just a small brass hook, [with your cloak hanging on it|screwed to the wall](?hung-cloak).

## [Bar]("Foyer Bar (In the dark)")

You walk to the bar, but it's so dark here you can't really make anything out. The foyer is back to the [north](/foyer).

- [Feel around for a light switch.](?!scuffled1#scuffled1+not-in-the-dark)
- [Sit on a bar stool.](?!scuffled2#scuffled2+not-in-the-dark)

### Not in the Dark

In the dark? You could easily disturb something.

## [Bar](?lost-cloak "Foyer Bar")

The bar, much rougher than you'd have guessed after the opulence of the foyer to the north, is completely empty. There seems to be some sort of message scrawled in the sawdust on the floor. The foyer is back to the [north](/foyer).

[Examine the message.](/message)

## [Message]("Foyer Bar")

The message, neatly marked in the sawdust, reads...

**You have won!**

## [Message](?scuffled1&scuffled2 "Foyer Bar")

The message has been carelessly trampled, making it difficult to read. You can just distinguish the words...

**You have lost.**

The above game is now completely playable, with two possible endings. Hopefully this guide and these examples have given you a good idea of what Ficdown is capable of and how to get started writing your own stories.