Basics

Learn how to use scenes and paths to write a story.

Scenes and paths

A Choicelab story is made of scenes. A scene is a short sequence of action in your story — usually no more than 60 seconds — that moves the narrative forward. A scene can present dialogue between characters, provide exposition, or ask a question. When the scene ends, anything on screen clears, and the player moves on to the next scene.

A group of related scenes make up a path. You add paths to your story folder, with each one in its own .path file. You connect these paths together to form your story, and the player will traverse down different paths based on their answers. (See Connecting paths, below.)

Scenes are written in plain text — stored in the scenes folder inside your story folder — and Choicelab turns these into visual, sequential moments.

Here's an example of a small, single scene in a path:

~~

You wake up with a spring in your step. It's a new day, and you're gonna seize it.

The ~~ markers denote a new scene, and the line of text will show as onscreen text when this story plays in the browser.

To add scenes, write them out in a plain text file. Separate each scene with at least one line of ~~:

~~



Here is the first scene, with a single line of onscreen text.

~~

Here is the second scene, also with a single line of onscreen text.

These ~~ lines make up the scene's header. You can add consecutive lines of ~~ for readability or to use some special features — which we'll get to in a bit.

Asking a question

Let's go back to our first example, and add a new line of text with a question:

~~

You wake up with a spring in your step. It's a new day, and you're gonna seize it.

What do you do first?

To collect a player's answer, first create a variable, which will store the answer so we can use it later. Name your variable as a single word in upper- or lower-case letters; add a question mark at the end, and wrap it in square brackets: [whatFirst?]

Then, add each possible answer choice on a new line by writing >, the text of the button, and the corresponding value in square brackets:

[whatFirst?]

> Make some coffee. [coffee]

> Go outside and take in the fresh air. [outside]

Putting this together gives us a scene comprising one line of text, a question, and some answer choices:

~~

You wake up with a spring in your step. It's a new day, and you're gonna seize it.

What do you do first?

[whatFirst?]

> Make some coffee. [coffee]

> Go outside and take in the fresh air. [outside]

Connecting paths

Interactive stories take the player down a particular path. In Choicelab, you accomplish this by sending players to different path files.

In your story folder, Choicelab always starts at scenes/start.path. From there, you can send a player to a different path file by writing a goto.

To write a goto in a path file, add a > after the ~~ markers, followed by the name of the file. So, if you have a path in your story folder called path1.path, you could point to it in another path by writing ~~> path1.

~~

You wake up with a spring in your step. It's a new day, and you're gonna seize it.

What do you do first?

[whatFirst?]

> Make some coffee. [coffee]

> Go outside and take in the fresh air. [outside]


~~> path1

Now, what if we want two possible paths, based on the player's answer? Rules let us do just that. A rule is a small statement you put before a scene or goto that tells Choicelab whether it should include it in the story, or ignore it and move on.

To write a rule for a scene or goto, add a second line of ~~, the variable to check, an =, the value the variable should have, and a question mark:

~~> variableName = certainValue?

In our example above, let's add two gotos that correspond to the two answer choices:

~~


You wake up with a spring in your step. It's a new day, and you're gonna seize it.

What do you do first?

[whatFirst?]

> Make some coffee. [coffee]

> Go outside and take in the fresh air. [outside]


~~ whatFirst = coffee?

~~> pathInside



~~ whatFirst = outside?

~~> pathOutside

These gotos point to different path files in our story folder: scenes/pathInside.path and scenes/pathOutside.path.

If the player chooses to "make some coffee," they'll go to pathInside. If they decide to "go outside and take in the fresh air," they'll go to pathOutside.

Those are the basic building blocks of Choicelab. Next, we’ll discuss how to make your scenes come alive with actions and timing.