Description

Choicelab is a tool for making immersive, interactive stories in your browser. Think Choose Your Own Adventure, or an old-school text game, but with the full capabilities of modern web technologies.

This sample project has everything you need to get started: extremely minimal setup, a simple file structure, and a test server so you can view your project locally before sharing it with the world.

Documentation

• Installation
• Basics
  • Writing scenes
  • Creating paths
  • Working with timing
• Actions
  • audio
  • beat
  • continue
  • input
  • response
  • video

Installation

1. Make sure you have Node and npm installed.
2. Download or fork this repo, and navigate to it in your terminal:

• cd /path/to/choicelab-sample-project

3. From your terminal, run npm install to download all of the project's dependencies.
4. Run npm test and open the URL you see in your terminal.

Basics

A Choicelab experience is made of scenes. A scene is a chunk of content you show on screen for a certain amount of time — kind of like a slide in PowerPoint or Keynote, but more fun. You show a block of text, or a question with answer choices, and when everything is done, the screen clears so the next scene can begin.

Scenes are contained in path files (.path) stored in your project. A group of related scenes makes up a path, and viewers will navigate to different paths based on their answers. Scenes can be text-driven (writing in Markdown or plain text), but you can also sprinkle in actions, which gives scenes the ability to play audio, video, or other interactivity.

Here's an example of one scene in a .path file:

~~

  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]

So, what does this do?

1. The ~~ denotes a new scene. (More on this later.)
2. The sentence and question are shown onscreen as text.
3. The [whatFirst?] shortcode creates a variable called whatFirst.
4. The two lines starting with a > are answer choices. When the user chooses one, the value in the square brackets will be saved to whatFirst.

Writing scenes

To add scenes, write your Markdown, HTML, and Choicelab syntax in a plain text file. Separate each scene with at least one line of ~~:

~~
~~

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

~~
~~

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

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

Creating paths

A viewer traverses through scenes in the order they appear in a file. But interactive stories take a viewer down a particular path.

Choicelab always starts at the file at scenes/start.path. From there, you can write in scenes and branch off into different paths, stored in separate .path files.

To send a viewer to a different .path file (a different path), add a goto to the scene header:

~~
~~

  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]

~~
~~ goto: path1

In this example, the viewer will see the first scene, and when they answer the question, they'll go to path1.path.

But what if you have two possible paths to send the viewer down? In that case, you'd want to send them down a path based on an answer.

Rules let you do just that. You write rules using a simple faux-code in the header of a scene.

Consider our example above:

~~
~~

  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]


~~ goto: pathInside
~~> whatFirst = coffee


~~ goto: pathOutside
~~> whatFirst = outside

This time, we have two gotos pointing to two different scene files. But the little ~~> indicator means we're going to only send them to that file if whatFirst has a certain value — which will be set by the viewer's answer choice.

You can add multiple rules per scene, and specify whether all of a viewer's answers should match, or just some of them.

Match all variables

~~> morningOrNight = morning AND favoriteColor = red

Match any variable

~~> morningOrNight = morning OR favoriteColor = red

Working with timing

To make scenes feel more alive, you can bring elements onscreen at certain times using timing flags. When an action or line of text comes after a timing flag, it will appear once that amount of time has elapsed:

~~

[0.3s]

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

[2s]

What do you do first?

[2.5s]

[whatFirst?]
> Make some coffee. [coffee]
> Go outside and take in the fresh air. [outside]

In this example:

• After 0.3 seconds, the first line of text appears.
• After 2 seconds, the question appears.
• After 2.5 seconds, the answer choices appear.

You can also have elements disappear from screen after a certain amount of time, by including a second value in the flag:

~~

[0.3s 4s]

First you see this...

[5s]

...and then you see this.

The first line of text will disappear after 4 seconds, and the second one will appear after 5 seconds.

Actions

audio

Plays an audio file. Supports any file type supported by Howler, but mp3 files are recommended.

• src: required Path to an audio file.

  [audio src="media/path_explainer_02.mp3" alt="So, imagine this: you're standing on the beach..."]

• alt: Alternate text for the audio, which will appear automatically in closed captions.

beat

Targets an onscreen element, letting you add or remove classes. Useful for animating elements — like text or images — using CSS.

• selector: required The element to change. You can use any CSS selector, but if the selector applies to multiple elements, only the first element will be selected.
• addClass: Classes to add. Separate classes with spaces.
• removeClass: Classes to remove. Separate classes with spaces.

[beat selector="h1.big" addClass="color-blue" removeClass="color-red"]

continue

A simple button that holds the current moment until pressed.

• text: Text for the button. Defaults to "Continue" if unspecified.

[continue text="Let's move on!"]

input

Stores the values from HTML buttons and inputs into a variable.

• name: required The name of the variable you're saving a value to.

## What's your take on pizza?

<button value="great">Love the stuff.</button>
<button value="good">It's solid.</button>
<button value="nah">Not for me.</button>

[input name="howIsPizza"]

response

Plays an audio file after user input is submitted. Very similar to the audio shortcode in terms of features; see the audio action above for more details.

• src: required Path to an audio file.
• alt: Alternate text for the audio, which will appear automatically in closed captions.

I can do one of two things for you.

[path?]
> Explain what this is. [explainer]
> Tell me something nice. [nice]

[response name="path" value="explainer" src="media/response-explainer.mp3" alt="Cool."]
[response name="path" value="nice" src="media/response-nice.mp3" alt="Well..."]

video

Plays a video file. Supports any HTML5 file type, but mp4 files are recommended.

• src: required Path to a video file.

  [video src="media/space-art.mp4"]

• alt: Alternate text for the video, which will appear automatically in closed captions.