About this guide

First off, welcome! While reading this guide, it’s recommended to have the online editor open so you can try the examples mentioned here first-hand; do so by creating a new story, just for learning.

A story is made of cards

Each story is made up of one or more cards. A card is just some text accompanied with 0 or more choices. When a player clicks on a choice, they are taken to another card, and so on. A story ends when the player reaches a card with no choices (at which point they’re prompted to share or pay for the story).

Creating a card

Here’s a simple card:

* [This is a card's text!]     
    ? [This is the first choice]     
    ? [Second choice...]     
    ? [You can have as many choices as you want!]

The star (*) denotes a card’s text while the question mark (?) denotes a choice’s text. All text should be enclosed in square brackets ([ and ]).

Whitespace is flexible so you can add or remove spaces, tabs, or new lines anywhere you want without affecting the result.

Going to a specific card when a choice is made

As mentioned before, a story is just a collection of cards, so you can create as many cards as you want (each with it’s own text & choices).

To go to another card, use -> go to CARD_LABEL, where CARD_LABEL is some text positioned above the card you want to go to, like this:

* [Do you like cats or dogs?]     
    ? [I like cats!] -> go to likes_cats     
    ? [I like dogs!] -> go to likes_dogs      

likes_cats:   
* [Big cats or little ones?]
    ? [No doubt big ones] -> go to likes_big_cats     
    ? [The little cute ones] -> -> go to likes_small_cats

likes_dogs:   
* [Why do you like dogs?]
    ? [They're friendly] -> go to likes_friendly_dogs     
    ? [They're fierce!] -> go to likes_fierce_dogs

…and so on, you get the idea!

Note that labels can’t have spaces in them, so you’d usually want to use underscores like_this. You can also write goto instead of go to, they’re both the same.

Congrats! You can now make simple stories & games! Read on for more.

Card falldowns

If you don’t include a go to statement on a choice, it will take the player to the next card below it (falldown to the next card), like this:

* [I hate it when you use my toothbrush!]     
    ? [But I did not!]     
    ? [Sorry, won't do it again] -> go to apology       

* [Liar! I saw you use it yesterday!]
    ? [Alright, I'm sorry!]

apology:   
* [Just don't do it again, please]
    ? [I'll try...]

In this example, the choice But I did not! doesn’t have a go to; so when the player selects it, they will be taken to the next card directly below the it (falldown to it), which is Liar! I saw you use it yesterday!. (paste it in the editor and try it out!)

Sometimes using too much go tos can become unmanageable and hard to follow, which is why it’s recommended to make use of falldowns as much as possible.

Checking if a specific label has been visited

Sometimes you want to see if a card with a specific label has been visited or not, then act on that information. For example you may have this choice first:

* [Clementine was bitten by a zombie...]     
    ? [Save her, she'll get better]  -> go to saved_clem
    ? [Leave her, she'll just turn into one] -> go to left_clem
    
saved_clem :   
* [She thanks you...]     
    ? [continued...]
   
left_clem :   
* [You feel guilty..]     
    ? [continued...]

…then later in the story you want to show a specific choice only if saved_clem has been previously visited, you’d do it like this:

* [You stop to scavenge for resources]     
   ? [Find water] -> goto ...     
   ? [Find food] -> goto ...     
   ? [Find medicine for Clementine] if visited saved_clem -> goto ...

Notice the if visited saved_clem before the -> goto in the last choice. It reads: “show the choice ‘Find medicine for clementine’ only if a card with the label ‘saved_clem’ has been previously visited”. If that label hasn’t been visited, the choice will not be shown and the player won’t be able to select it.

You can also have not to do the opposite (ie. if not visited left_clem). In addition, you can have and, or, and other constructs, for example, you might have: if visited saved_clem and not visited clem_dies) (sorry for the spoilers!). Use brackets () for nesting if necessary.

Similarly for card falldowns

The same concepts also apply to cards: * [Clementine asks for some water…] if visited saved_clem ? [Pass bottle] ? [Ignore her]

The if visited saved_clem, basically says “only show this card if a card with the label ‘saved_clem’ has been previously visited”. Note that this only applies when using falldowns, if you explicitly use a go to then this condition will be ignored.

Label reuse

For flexibility, a card can have more than one label (just separate them by spaces or commas) and labels can be reused in multiple cards (go to always just goes to the nearest one below).

Quick-time events (QTEs)

Quick time events introduce a countdown timer to a card, once it reaches 0, the player will be taken to a card of your choosing. To add a QTE to a card, just add a timed choice like this:

* [The train is taking is taking off, quick jump on!]
    ? [Jump on the train & join Baskets] -> go to left     
    ? [Stay right where you are] -> go to stayed     
    ? 5s -> go to stayed

Here the last choice reads “five seconds”, as in “after five seconds, if the player doesn’t make any other choice, this choice will be automatically selected”; so after 5s it will go to the card with the label stayed. A countdown timer bar is shown to tell the player how much time remains.

When using QTEs it’s important to give the player enough time to read all the card’s contents before making a choice, so you’d usually make these the cards with the least text, with a preparatory card showing earlier.

Comments

You can add single-line comments by using the hash symbol (eg. # this is a comment that's completely ignored by the interpreter).

Variables

A variable is essentially just a some number that changes throughout your story (eg. life and money could be variables). You can easily change variables in response to the choices the player makes (eg. subtracting 10 from money if the player decides to buy something in your story). And later, you get to check those variables and act upon their values (eg. end the story once the player has 0 money).

Creating a variable

First off, you should create a variable before using it. Do so by listing the variables you want & their inital values at the start of your code, before any cards, like this:

variables:       
    money = 100       
    cool = 10       
    energy = 10

This tells stoura to create three variables, each with it’s own initial value (money being 100, cool being 10, and soon). These variables will appear when the player starts reading your story.

Changing a variable’s value

Variables are of no use if you can’t vary them! Here’s an example of changing a variable:

* [You see some money on the floor]
    ? [Pick it up] -> goto taken_money and money + 10     
    ? [Leave it be] -> goto left_money 

As you can see, the first choice has an extra bit besides the go to. It also adds 10 to the player’s money variable we created earlier. You can also subtract, multiply and divide variables:

* [Would you like a drink?]
    ? [Yes please] -> energy * 2 and money - 5     
    ? [Not now...]

Selecting the first choice would double the energy variable and subtract 5 from money. Note how you don’t need to use go tos with variables: a choice’s sole purpose could be to just change some variables.

Checking and acting upon a variable

So you have variables, and your variables change in response to player’s choices. Now you need to check and act upon their values. Doing so is very similar checking if the player has visited a card or not (As discussed earlier). Here’s an example:

* [What would you like to buy?]     
    ? [Just a bike] -> goto bike     
    ? [A car] if money > 20 -> goto car and money - 20

In this example, the last choice has a condition (ie. if) in it. The player will only see the second choice if their money is more than 20, and so on. If their money is less than 20, they won’t see any choice other than the first.

You can also use and, or, and not as well as bracket nesting (eg. if energy > 10 and cool > 5 or if superhuman = 1).

Other operators include: more than (>), less than (<), equal to (=), not equal to (!=) (which can be not and =).

Note: all the arrows -> can be replaced the word then, if you prefer so.

Hiding a variable from the player

Sometimes you just want to use a variable internally only for more control over the story’s flow (especially 1 or 0 variables where 1 means yes and 0 means no). To hide a variable from the player, simply preface the variable’s name with an underscore. If you changed money to _money, the player won’t be able to see it.

Spaces in variables

Variables and labels are so-called “identifiers”, meaning they can’t have spaces in them (which is why we_love_underscores). However, sometimes you might want to include spaces in a variable’s name (eg. if it’s two words). To do so, just enclose the variable’s name in square brackets ([]), the same way you did with card & choice text. For example: variables: money = 10 [total score] = 0

Every time you mention the variable [total score], you have to include the square brackets.

PS. you can the the same thing with labels but I’m not sure why you’d do that since the player never sees them anyway.

Everyturn actions

What if you want to modify & check a variable every turn, that is, every time the player makes a choice? For example, you might want to check to see if life is less than zero, and if so, go to the “death” card. That’s the purpose of everyturn actions!

Everyturn actions are declared below the variable creation area, but before all the cards. For instance:

variables:       
    life = 100
    energy = 10

everyturn:       
    if life < 0 then goto death       
    (always) -> energy - 1       
    if energy < 1 then goto tired

Here you have 3 everyturn actions. The first one checks if life ever gets below zero, and if so, takes the player to the card with the death label (where the story probably ends).

The second one doesn’t do any checks, instead uses the the special (always) keyword which means “always do this”. So it essentially subtracts 1 from energy whenever the player makes a choice. The last everyturn action takes the player to a tired card if the they have energy less than one (supposedly in this story the player has to maintain their life & energy!).

Note the interchangeable use of the arrow (->) and then; just use what sounds more natural to you.

Nesting

Choice nesting is supported, for example:

* [What would you like today?]
    ? [Coffee]
        {
            * [Here's your coffee sir.]
                ? [...]
        }
    ? [Tea]
        {
            * [Here you go, fresh tea...]
                ? [...]
        }

* [Are you enjoying your drink?]
    ? [...]

This is useful if you don’t want to make a whole new card just for one specific choice. You can also replace { and } with | and . to suit whatever you find more readable.

Formatting

Both markdown formatting and HTML formatting. For example, enclosing some text in stars will italicize it (hello becomes hello), and two stars will strengthen it (hello becomes hello). Of coarse, there’s a lot more to it but I’ll leave that to the many markdown/HTML guides you can find online.

Images, video, & audio

Since HTML5 tags are supported, you can include use <img>, <video>, and <audio> tags to include images, GIFs, videos, audio, etc. Note that you can also use markdown to do the same but HTML5 gives you more control over the size & position (PS. you can include a <style> tag too) of your media.

Character limits

A card’s text is limited to 500 characters, while a choice’s text is limited to 30 characters. This limits forces the writer to include more choices which adds to story’s immersion (even if some are minor/fake choices). This character limit also applies when including HTML tags so it’s recommended to use URL shorteners.

Testing Features

Here are some of the features included in the online editor intended for testing your stories before publishing them. A more advanced autoplay-test feature is in the works.

Live preview

The story shown next to the online editor is a live preview of the code you write, including text, state, and variables. You edit these properties using the features mentioned below.

Go to card

Each card is given a “card ID”, starting at 0 (the first card) and going up (however many cards you have) in the order they appear in your source code. The go to card feature enables you to jump to a card by typing in it’s card ID. Variables and other state are maintained.

Edit a variable

This feature allows you to edit variables of the live preview story in real time. You might see variables with names starting in _VISITED_[label name], these indicate labels and weather they’ve been visited (set to 1) or not (set to 0).

Reload & auto-reload

The reload button resets the live preview story’s variables and state, taking you back to the first card, with default variables & no visited labels.The auto-reload feature essentially presses the reload button for you every time you make a change to the story’s source code, which you might find useful. However, if you want to maintain your live preview story’s variables, turn this off!.