This page is outdated.

My original post about ficdown is available below for historical purposes, but for up-to-date information about the current state of Ficdown please visit ficdown.com.

Introduction

Ficdown is a convention for writing interactive fiction stories in Markdown.

Heading levels 1 through 3 are used to break the story up into scenes and actions. Anchors are used to move a player between scenes and set player state values, as well as define conditional behavior based on the player’s current state. Blockquotes within scene descriptions are also reserved for a special purpose. Headings higher than level 3 and all other valid Markdown syntax can be used within scene descriptions and should be rendered appropriately when playing.

The kinds of stories that can be represented by Ficdown are similar to a choose-your-own-adventure style story, where the player is presented with scene descriptions and can branch to different scenes by clicking hyperlinks. Ficdown adds the concept of player-state, which is essentially a list of boolean values (false by default) that can be “toggled” to true by specific hyperlinks within the game. A story can only set state values to true (they cannot be changed back to false once they have been set). The player’s state can be used to change scene descriptions, or branch the user to entirely different scenes.

Goals

My goal in defining these conventions is to provide authors with a simple way to write interactive fiction that requires minimal understanding of complex programming environments or libraries, while still providing enough complexity to allow for interesting gameplay and mechanics. Whether these goals have been achieved (or are achievable at all) remains to be seen.

Another goal is for Ficdown to allow for game definitions that can realistically (within reason) be compiled to static HTML or different hyperlink-enabled eBook formats that enumerate every reachable scene and player state combination, to allow for gameplay in web browsers or eBook readers that may not support a scripting or programming interface that would otherwise be required. Whether or not this is a realistic goal also remains to be seen.

I also just really like writing in Markdown, and think it would be cool if I could write text adventures in it.

Conventions

I’ll present the conventions in the form of a brief tutorial. Each block of source below can actually be played using a (as of this writing, extremely alpha) version of Ficdown.js which allows you to play Ficdown games in your web browser.

Story and Scenes

Heading level 1 is used to define the story itself, and heading level 2 is used to define scenes within the story. For example:

# [My Story Title](/a-dark-alley)

An interactive story by Jane Doe

Version 1.0

## A Dark Alley

You find yourself standing in a dark alley.

A small bird flies by overhead, moving in the direction of the street.

## The Street

You walk into the street, and are almost hit by a passing car. What a jerk!

The street is lined with lights. You know that if you head north, you'll eventually reach the library. Your home is a couple blocks in the opposite direction.

Click here to play example 1.

The preceding example begins with the story definition (My Story Title), and has two scenes defined (A Dark Alley and The Street). The first convention in use here is that the story title should be an anchor that links to the first scene (scenes are referenced by sanitized versions of their names–all non-word characters are removed, and spaces are replaced with hyphens).

Scene Linking Anchors

The problem with this story is that currently there’s no way to move between scenes. If you try playing this game, you’ll be presented with the first scene (A Dark Alley) and that’s the end of the game. We can add something for the player to do by adding anchors that link between the scenes:

## A Dark Alley

You find yourself standing in a dark alley.

A small bird flies by overhead, moving in the direction of the street.

**What would you like to do?**

- [Go to the street.](/the-street)

## The Street

You walk into the street, and are almost hit by a passing car. What a jerk!

The street is lined with lights. You know that if you head north, you'll eventually reach the library. Your home is a couple blocks in the opposite direction. The entrance to a dark alley looms ominously between two of the buildings here.

**What would you like to do?**

- [Go to the dark alley.](/a-dark-alley)

Click here to play example 2.

Now each scene contains an anchor that links to the other scene, allowing the player to move back and forth. Note that I have put a bold call-to-action above my anchors which I have grouped in a list, but this is just personal preference. There is nothing stopping you from embedding anchors anywhere in your scene’s description.

First-Seen Descriptions

The problem with our story now is that every time you go to the dark alley, a bird flies overhead, and every time you go to the street, you almost get hit by a car. That’s kind of silly. To fix that we introduce the second convention.

Any text within a blockquote in a scene description will only be displayed the first time the player sees a given scene. In Markdown you create blockquotes by preceding each line with a > character:

## A Dark Alley

You find yourself standing in a dark alley.

> A small bird flies by overhead, moving in the direction of the street.

**What would you like to do?**

- [Go to the street.](/the-street)

## The Street

> You walk into the street, and are almost hit by a passing car. What a jerk!

The street is lined with lights. You know that if you head north, you'll eventually reach the library. Your home is a couple blocks in the opposite direction. The entrance to a dark alley looms ominously between two of the buildings here.

**What would you like to do?**

- [Go to the dark alley.](/a-dark-alley)

Click here to play example 3.

State Toggling Anchors

Now that’s all fine and dandy, but there’s nothing really interesting to do yet. Let’s add some more interactivity in the street.

## The Street

> You walk into the street, and are almost hit by a passing car. What a jerk!

The street is lined with lights. You know that if you head north, you'll eventually reach the library. Your home is a couple blocks in the opposite direction. The entrance to a dark alley looms ominously between two of the buildings here.

There's a key on the ground here. It looks like your house key! You must have dropped it.

**What would you like to do?**

- [Pick up your key.](#picked-up-key)
- [Go to the dark alley.](/a-dark-alley)

Click here to play example 4.

You can see a new anchor has been added with the href ‘#picked-up-key’. This indicates that clicking that link should set a the player’s picked-up-key state to true. There is no need to declare state variables anywhere other than when you use them in anchors–Ficdown assumes all states are false by default until the user triggers them.

Conditional Anchors

When you play this example, you’ll see that even if you click the option to pick up your key, the key is still on the ground in the description and the option to pick it up is still there. This is where conditional anchors comes into play:

## The Street

> You walk into the street, and are almost hit by a passing car. What a jerk!

The street is lined with lights. You know that if you head north, you'll eventually reach the library. Your home is a couple blocks in the opposite direction. The entrance to a dark alley looms ominously between two of the buildings here.

[You idly play with the key in your pocket.|There's a key on the ground here. It looks like your house key! You must have dropped it.](?picked-up-key)

**What would you like to do?**

- [|Pick up your key.](?picked-up-key#picked-up-key)
- [Go to the dark alley.](/a-dark-alley)

Click here to play example 5.

If you play the example now, you can see that once you pick up your key, that option is no longer available on the street, and the street’s description changes to indicate that the key is now in your pocket. This was done by adding conditionals to the anchors. Conditionals are specified by a question mark followed by the player state that determines how or whether the anchor is displayed. The text of a conditional anchor (the part between the square brackets) can be split by a pipe “|” character. The text before the pipe will be displayed when the player’s state satisfies the condition, otherwise the text after the pipe will be displayed. Either side of the pipe can be empty, in which case the anchor will be removed entirely.


Updated June 3, 2014

The spec now allows for checking negative conditions as well, by preceding the condition name with an exclamation mark !. For example, the following:

[Pick up your key.](?!picked-up-key#picked-up-key)

Is equivalent to the hyperlink in the example.


In our example, the portion of the scene description talking about the key is conditional to ?picked-up-key, which is set when the user clicks the anchor that toggles the #picked-up-key state. You’ll notice that the toggle anchor is itself also conditional to the ?picked-up-key state, and since there is no text in front of the pipe character for that anchor, it means that the anchor will be removed altogether when the ?picked-up-key state is true.

We have now seen all three possible components of an anchor’s href: target scenes, conditional states, and toggle states. They can generally appear in any combination, but must always be in that order. You can also specify multiple conditional states by separating them with an ampersand “&”, and multiple toggle states by separating them with a plus “+”. For example, a complex anchor that goes to a new scene, requires a number of different states to display, and toggles more than one state when clicked might look like this:

/target-scene?first-condition&second-condition#third-condition+fourth-condition

Anchors that only contain conditionals will not be rendered as hyperlinks, since they have nowhere to link to. Anchors that contain toggles but no target will be rendered as a hyperlink, but will redirect back to the current scene after toggling the specified values in the player state.

Actions

Let’s say now in our example we want to provide some kind of feedback to the user when they pick up the key. Let’s say that they knock over a garbage can when they bend over. We could write a whole new scene that is an identical copy of the current street scene with the key-picking-up-trash-knocking text in a blockquote so it only displays the first time, but that would be wasteful (we don’t want to have to copy and paste the street description to two different scenes, and then have to update both whenever we want to make a change).

This is where the “action” convention comes in. You specify action text using a level 3 header. Whenever a state is triggered 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).

## The Street

> You walk into the street, and are almost hit by a passing car. What a jerk!

The street is lined with lights. You know that if you head north, you'll eventually reach the library. Your home is a couple blocks in the opposite direction.

[You whistle innocuously, pretending not to see the knocked over trash can and garbage scattered all over the sidewalk.|There's a key on the ground here. It looks like your house key! You must have dropped it.](?picked-up-key)

**What would you like to do?**

- [Go to the dark alley.](/a-dark-alley)
- [|Pick up your key.](?picked-up-key#picked-up-key)

### Picked Up Key

When you bend over to grab your key, you accidentally knock over a trash can behind you. Oops! You hope nobody saw that as you drop the key in your pocket.

Click here to play example 6.

You’ll see if you play this example that now the “Picked Up Key” action text is displayed in front of the street’s description after you click the option to pick up the key. If we didn’t hide the option to pick up the key and you clicked it again, it would display the action text every time. You can include anchors in the action text as well, including conditional anchors on the state that the action represents–the very first time a user performs an action that renders your action text, its own state will be false. Every subsequent time it will be true. This could come in handy for conversations, for example:

## 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 the anchor, the guy will say “Gee, thanks,” but will shrug it off each subsequent time the player clicks it.

Conditional Scenes

The final convention I have defined so far are conditional scenes. Let’s say in our example that when the player moves south from their street toward their home, we want an entirely different scene with different available actions to the player depending on whether they have picked up the key or not.

Anchors cannot be embedded within anchors, so one giant scene-wrapping conditional anchor wouldn’t work. Wrapping all of the description text in conditionals and then having each anchor display conditionally as well would work, but would be ugly. We could put two different links from the street, one that is only displayed when #picked-up-key is true and a different one to a different scene which is only displayed when #picked-up-key is false, but that could get hard to manage if we had other scenes that we also wanted to link to the player’s home (coming from the other direction, for example, we would have to do the same thing).

The solution is to write two home scenes, like so:

## The Street

> You walk into the street, and are almost hit by a passing car. What a jerk!

The street is lined with lights. You know that if you head north, you'll eventually reach the library. Your home is a couple blocks in the opposite direction.

[You whistle innocuously, pretending not to see the knocked over trash can and garbage scattered all over the sidewalk.|There's a key on the ground here. It looks like your house key! You must have dropped it.](?picked-up-key)

**What would you like to do?**

- [Go to the dark alley.](/a-dark-alley)
- [|Pick up your key.](?picked-up-key#picked-up-key)
- [Go south to your house.](/your-house)

### Picked Up Key

When you bend over to grab your key, you accidentally knock over a trash can behind you. Oops! You hope nobody saw that as you drop the key in your pocket.

## Your House

You walk up to your house to enter, but realize you don't have your key anymore. It must have been that one you saw north of here on the street.

**What will you do?**

- [Head north to see if your key is still there.](/the-street)
- [Break a window and climb in that way.](#break-window)

### Break Window

That's crazy talk!

## [Your House](?picked-up-key "Inside House")

> You use the key that you so gracefully retrieved from the street to gain entrance to your house.

It smells funny in here! Maybe you should do some cleaning.

**Congratulations, you got into your house and won the game!**

Click here to play example 7.

As you can see, there are two “Your House” scenes defined here. The second version has a conditional anchor around the scene name, and also defines a different title attribute in quotes after the anchor’s href–this allows you to define the same scene for different conditions without being forced to have it display the same scene name to the user for each one. The text of the anchor in the square brackets still defines the name of the scene for use in href targets, but the text in the quotes will be what’s displayed to the player if it’s there.

In this simple example, the player will end up in one of two scenes depending on a single player state value. There could conceivably be situations in which a player’s state will be true for multiple conditional scenes–in this case there are two criteria that will be used to select which scene the player is sent to:

  1. The scene with the most conditions will always win, and
  2. If two scenes with the same number of conditions match, the one that was defined first will win.

Consider this example (descriptions removed for brevity’s sake):

## [Bank Vault](?has-gun)
## [Bank Vault](?started-charity&loves-cats)
## [Bank Vault](?has-cellphone)

In this case, if the player satisfied only the ?has-gun and ?has-cellphone states, they would land on the ?has-gun scene because it was defined first out of the two satisfied conditional scenes. If all four of the above defined states were true (the player has a gun, a cellphone, and also started a charity and loves cats), they would land on the ?started-charity&loves-cats scene because that has the most matching states. If they satisfied none of the above states, linking them to /bank-vault would result in an error. It’s probably a best-practice to always define a non-conditional version of your scenes.

Another Example

I wrote a slightly longer example story as a proof-of-concept while working these conventions out called The Robot King. It’s pretty lame, but shows some slightly more complex examples of Ficdown.


Updated July 3, 2014

I’ve written up a version of Roger Firth’s Cloak of Darkness IF example as well now. The only wonky bit is since there’s no equivalent to a universal “examine” verb in hyperlink-based games, I simply hyperlinked the first instance of the word “You” to a description of yourself, which also toggles a state variable to indicate that the player now knows he’s wearing the cloak. If I were making a real game, I’d probably try to think of a more clever way to do this.


Discussion, Development, Road Map

I’ve already mentioned Ficdown.js which is the Javascript Ficdown engine being used on all of the examples linked from here. It’s pretty messy, has some bugs, and needs a lot of work, but seems to prove the concept of Ficdown fairly well. Ultimately I’d like to package Ficdown.js in a way that makes it super simple for authors to publish their stories to the web.

I also have another Ficdown project on GitHub where I’ve started working on a Ficdown compiler–this will be a C# library that I’m hoping will be able to take any Ficdown story and compile it into static HTML or eBook formats for offline play without the need for an engine such as Ficdown.js. Ficdown stories should be reducible to a set of finite states, but depending on how many states you define in your story there may be so many branches that generating them all as static files may be unfeasible. We’ll see how bad it gets. The ultimate goal would be to have an online compiler where authors could upload their Ficdown files from their web browser, have their story parsed and validated, and then export it to any supported format.

If you have any feedback or input please feel free to leave a comment here, on GitHub, or start a discussion over on Mike Snyder’s intfiction.org forum which I check occasionally. Also if you think you might have anything to contribute to either project on GitHub, or wish to create your own implementation of Ficdown, I’d strongly encourage you to do so.