Reader and Game Variables

Reader and game variables

Variables let an author personalize a story and remember what happens while a reader plays. Choose the kind by asking who changes the value and whether it belongs to the saved game:

The two kinds are separate. A story may have both a reader variable and a game variable named mood. Write {reader:mood} or {game:mood} to make the intended value clear.

See a simple example

Suppose an author creates a reader variable named name with the default value Alex. In chapter text, the author writes:

Welcome, {reader:name}!

A reader who chooses Sam sees “Welcome, Sam!” A reader who keeps the default sees “Welcome, Alex!”

The same story could have a Number game variable named coins. Writing {game:coins} shows the number of coins in the reader's current game.

Create and find variables

Create reader and game variables while editing the story:

1. For reader variables, enable Readers can customize story variables, then choose Add Reader Variable.
2. For game variables, enable Chapters can use game state, then choose Add Game State Variable.
3. Enter the name, choose a type, set the default or initial value, and save the story.

Choose Manage Variables to open the Story variables page. Game variables first introduced by chapter conditions or changes are collected there too.

Create a variable before relying on it in chapter text. When editing a chapter, use Insert beside a listed variable to add the correctly spelled form without retyping it.

Choose a type

Both kinds use the same six types, but their allowed values can differ:

The add-variable type picker calls Text Free Text. After it is added, the Story variables page shows its type as Text.

Common choices include:

Number, Percent, and Age can be compared with one another. Text and Dropdown can be compared with one another. Yes/No can only be compared with Yes/No.

When an author leaves a default or initial value untouched, Text starts empty, Number and Percent start at 0, Age starts at 18, and Yes/No starts at Yes. A Dropdown uses its first valid choice when it has no valid selected default.

Text and Dropdown values are inserted into the story as plain text. A saved value is not treated as chapter formatting or as another CHYOA tag.

Use clear, valid names

New variable names:

• may contain letters, numbers, and underscores;
• must begin with a letter or underscore;
• may contain no more than 100 characters.

For example, player_name is valid. The prefix is not part of the saved name. Include reader: or game: when using the name in chapter text; Insert does this for you.

The names if, elseif, else, endif, reader, game, true, and false are reserved and cannot be used for new variables.

Names cannot differ only by capitalization. Even so, names typed in chapter text are case-sensitive. Use the exact capitals shown on Story variables; {game:Coins} and {game:coins} are treated differently.

Open the focused instructions

Use Reader Variables and Customization for defaults, Customize, inline inputs, display order, editing definitions, and older reader syntax.

Use Game State Variables and Inventory for starting values, existing games, visibility, inventory ownership, change order, and maintaining definitions safely.

To print either kind inside prose, see Showing Reader and Game Values. To control access or change a game value when a chapter opens, see Chapter Conditions and Game-State Changes.

Before publishing

Check that:

1. each value uses the appropriate reader or game scope;
2. every variable has the intended type, default or initial value, and exact name;
3. reader defaults and game starting values make sense before any choices are changed;
4. chapter text uses reader: and game: prefixes consistently;
5. a reader sees plain text rather than unintended formatting from saved Text or Dropdown values.