Please check out This Way or That, a new collaborative fiction site.

The Basics

Welcome. We'll teach the basics here.

I. Syntax

All stories you write will be made up of two main elements: paragraphs and branches.

Think of your story as a script. This script is made up of paragraphs. Every once in a while, after a paragraph will be a list of options, these are the branches. A script is made up of one or more paragraphs. Each paragraph has zero or more options. Each option leads to a branch.

Paragraphs are one or more sentences of text and are presented to the reader in short bite-sized blocks. Once the reader is done with that block, either they are presented with a list of options to pick from, which causes the story to branch, or they are provided a "More..." button to present the next paragraph.

Branches are themselves scripts. Whenever the reader encounters an option in the story, that option leads to a sequence of paragraphs and branches, essentially a script that is only accessible by that option.

With that preamble, it'll be easier to see what we mean by diving into a few examples.

II. Paragraphs

The Simplest Example

Let's try an example script with only paragraphs and no branches.

Below is a simple script made up of three paragraphs.

You are in a dark cave. You hear footsteps in the distance.

You sit and wait.

The footsteps are getting closer...

At this point, we recommend clicking the link below to open up the new story editor. It will open in a new window. Copy-paste the above text into the story editor and hit 'Start' to try it out.

  1. Open the story editor.

Notice how each paragraph is presented one at a time to the reader. Also notice above that paragraphs are separated by blank lines...

More Advanced Paragraphs

Paragraphs are separated by blank lines. You can type as much as you want in a paragraph so long as there are no blank lines between them. When the story is presented to the reader, all of the lines are grouped together and presented as one long paragraph.

Below is an example of several paragraphs.

Once upon a time, there was a one-sentence paragraph.

There was also another paragraph.
It was made of these two sentences.

Soon, another paragraph appeared. It was made of
sentences that could wrap multiple lines.
matter what.
They were all part of the same paragraph.

In fact, you could put each sentence in each paragraph on one line.
These are two sentences on two lines.

Try copy-pasting the above again in the story editor.

  1. Open the story editor.

Did you see how the paragraphs that are broken up into multiple lines are still presented as one longer paragraph? This is done to allow you some freedom in how you write.

Creating Multiple Paragraphs

To create multiple paragraphs, simply separate lines of text with a lone '-'. All the text will be grouped onto one screen but will be broken up into multiple paragraphs.

This is the first paragraph.
This is the second one. And
this line is also part of the second paragraph.
Here is the third and final paragraph.

Now we start the first paragraph of the next page since there was no '-' character on the previous line.
Here's the second paragraph of the second page.

III. Branching

To write a story with branches, you follow a paragraph's text with one or more curly-braced sections. A branch starts with '{' and ends with '}'.

The first paragraph inside a branch becomes the title of the branch, which is presented as an option to the reader.

Here's the simplest branching example.

You are standing in front of two doors.
{ Open the left door.

  You opened the left door.
{ Open the right door.

  You opened the right door.
You wonder what to do next.

Copy the above text, then click the link below to write a new story in a new browser window. Paste the text into the screen and hit the Start button to try it out.

Merging Branches

Notice in the previous example that the line "You wonder what to do next." is printed regardless of which branch you chose. This is because once a branch completes, the story flow continues to the paragraph immediately following the paragraph that encountered the original branch. This is a very important point.

This feature allows you to merge branches back to a main story flow.

Nesting Branches

Another important feature is nesting. You can place as many branches within other branches as you'd like, such as the following.

You're sitting by a lake.
{ Place fishing line in the water.

  Something tugs at your line!
  { Pull on it.

    You caught a fish!
    { Clean it.

      You gutted it and cleaned its insides.
    { Let it go.

      You tossed it back in.
{ Stare at the sky.

  You wonder why it's so cloudy today.

IV. Ending the Story Early

If you wish to terminate a branch early and avoid merging it back to the main storyline, you can use the redirect command and redirect to the special 'end' section. The redirect command is simply => followed by a label.

You are climbing up the stairs.

{ Trip and fall

  Oh no, you fell and hit your head. You went to the hospital!

  You'll never amount to anything now, you klutz!
  => end
{ Successfully climb the stairs

  You made it to the top.
You became a Supreme Court Justice.

In the above example, the first branch will end early and the reader won't find success in the Supremest Court in the land.

V. Defining Sections

In the previous section, you were introduced to the redirect command =>. You can use it to redirect the reader to a section in your script. You can define sections by prefixing them with a label in this form [label name].

Here's an example.

[left room]
You are in the left room.
{ Go right => right room }

[right room]
You are in the right room.
{ Go left => left room }

The story begins...
=> left room

In the above example, there is a section called "main". The story always starts in the main section.

Also note that you can redirect to a section immediately in a branch. You don't need to write any text in it other than the branch title if that's all you want.

All scripts must have a main section.. Note that if you start out the script with no label, the script will automatically take on the label "main". The example below uses this implicit section. (Also, if you have only one section and it's named something other than main, we'll use it.)

I'm standing in the lobby waiting for a friend.
{ Wait a little longer.

  Ok. I'll wait a bit longer.
  => main
{ Leave. This is taking too long.

  Your friend is taking forever.
You hopped in your car and went to Disneyland without them.

In the above example, when you take the first branch, you will be redirected to the top of the script.

VI. A Longer Example

Okay, let's put it all together in an example.

You are standing in a clearing.

In front of you is a wishing well.
  Throw a coin into the well.

  You threw a coin into the well...

  But nothing happened.
  Look into the well.

  You slowly lower your head into the dark well...

  Almost immediately, a monster appears and rips your head off.

  => END

You wonder what to do next...

VII. More ahead

Now that you know the basics, read up on how to use variables to make your stories even more interesting.

  1. Read about advanced topics.