Reader and Game Variables

Reader and game variables

Variables let authors personalize a story and remember what happens while a reader plays. There are two kinds:

• Reader variables hold details chosen by the reader, such as a name, pronouns, age, or favorite color.
• Game variables hold story progress, such as coins, health, a chosen route, or whether the reader found a key.

The two kinds are separate. A story may have both a reader variable and a game variable named mood. Use {reader:mood} / {game:mood} to make it clear which one you mean.

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.

Creating and finding 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.

Authors can 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.

Choosing a type

Choose the type that matches what the variable should hold:

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

Here are common uses for each type:

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.

Reader Number and Percent values may include decimals. Reader Age values are whole numbers. Game-state Number, Percent, and Age values use whole numbers, as do chapter changes, rolls, reveals, and actions.

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.

If a game-state change would go beyond the allowed range, CHYOA keeps the result at the nearest allowed value. For example, increasing a Percent value of 95 by 10 produces 100.

For a Dropdown, the options appear to readers in the order entered by the author. Selecting a different default does not move that choice. Blank choices and repeated choices are ignored, keeping the first occurrence. If the default is empty or no longer matches an option, the first choice is used.

Reader variables

Use {reader:name} to show a reader value in chapter text. Use {input reader:name} to add a field that the reader can edit and save from inside the chapter.

Readers can also change these values through Customize. Until a reader saves a different value, the story's default is used.

Reader inputs follow their type. Text returns to its default when left blank; Dropdown accepts one of its listed choices; Number and Percent accept values within their ranges, including decimals; Age uses a whole number from 18 to 150; and Yes/No presents two choices. If an older saved reader value no longer fits the variable's type or Dropdown choices, the current default is shown instead.

Reader variables can appear in story titles, subtitles, and synopses, as well as chapter titles, chapter text, and follow-up questions. Chapter text can update as soon as a value is changed. A title or follow-up question may update after the reader continues or reloads the page.

Reader values do not change just because the reader enters a chapter. They change only when the reader saves a choice through Customize or an input placed in chapter text.

Game variables

Game variables belong to the reader's saved game. Their starting values are used when a game begins. Chapters, rolls, reveals, and action buttons can then change them.

Use {game:coins} to show the current value. A game value is unavailable before the reader starts a game, unless the author provides a fallback where that feature allows one.

Starting values and their configured order apply when a reader starts or resets a game. On a fresh game, CHYOA applies those starting values first, then applies the first chapter's changes from top to bottom, and only then shows the chapter. A first-chapter change can therefore replace or hide a starting value before the reader sees it.

Changing a definition later does not rewrite a game already in progress. A newly defined variable may be missing, an edited initial value may keep its older saved value, and reordered definitions do not rearrange the existing ordinary Variables list. Inventory does use the current configured order. Test an updated story with both an existing game and a fresh or reset game.

A variable created only through Add new variable in a chapter change does not exist when the game starts. It first appears when the reader reaches that chapter. Define it while editing the story when a predictable starting value or inventory position matters.

Each game-variable name must keep one type throughout the story. For example, do not use score as a Number in one chapter and a Percent in another. If an older story behaves unexpectedly, check every condition and change that uses the name and make the type consistent.

Removing a game value makes it unavailable until a later change creates it again. Its starting value is not automatically restored at that point. Going Back can restore a recent earlier state that still contained it, and Reset Game reapplies the current starting definitions.

Labels, author shortcuts, and inventory

The Story variables page provides three separate display settings for game variables:

• Label gives the value a reader-friendly name in stats, meters, Game State, and inventory.
• Sidebar → Show adds an alphabetized game-variable quick-insert shortcut to the chapter editor. It does not reveal the value to readers or change the game. Reader-variable insertion shortcuts keep reader-definition order.
• Inventory → Show assigns the variable to the story's inventory instead of the ordinary Game State Variables list.

An inventory assignment appears only when its current value counts as owned:

No, zero, negative Numbers, empty text, missing values, and hidden values are omitted for ordinary readers. Show visibility does not make an unowned inventory value appear. Because inventory variables are kept out of the ordinary Variables list, a zero, No, or empty inventory value may be shown nowhere until it changes to an owned value.

What position and order really control

Different lists use position in different ways:

Use Move Up and Move Down while editing the story to arrange reader and defined game variables. Condition and change rows do not have move controls, so add changes in the order in which they should happen. Add Dropdown choices in the order in which readers should see them.

On a fresh or reset game, ordinary Game State begins in game-definition order. After play begins, it keeps the order in which values entered that saved game. Setting an existing value again leaves it in place. Removing and later recreating it puts it at the end of the ordinary Game State list. Inventory continues to use the configured game-definition order.

Repeated changes to one value are supported. Set 5, followed by Increase 2, produces 7; reversing those rows produces 5. Limits are applied after each row. For example, Percent 95 followed by Increase 10 and Decrease 10 ends at 90: the first change stops at 100, then the second subtracts 10.

Visibility choices follow the change rows too. Show makes a value visible in its normal Game State section, Hide hides it there, and Keep leaves it as it is at that moment. While a value continues to exist, the last Show or Hide decides its visibility. Remove also discards that visibility; if a later row recreates the value, it starts visible and Keep preserves the new visible state.

Names and capitalization

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 the Story variables page; {game:Coins} and {game:coins} are treated differently. Using Insert is the easiest way to avoid this mistake.

Changing an existing story

The Used in section on Story variables lists structured chapter conditions and game-state changes. It does not find names typed directly into chapter text.

Before renaming a variable or changing its type:

1. Open Used in and update or remove every listed condition and change.
2. Review chapter text manually for substitutions, if statements, stats, meters, rolls, reveals, and actions using the old name.
3. Test both a fresh game and a game that was already in progress.

CHYOA prevents changing the type of a game variable while structured rules still use it. Reader variables can change type, but an older reader choice that no longer fits uses the new default instead. Existing saved games are not rewritten when a game variable is renamed, retyped, reordered, or given a new initial value.

A game Dropdown choice that is still used by a structured chapter condition or change is retained even if it is removed from the definition, and it may be placed after the current choices. Update or remove those rules before removing the old choice completely.

Older stories

Older reader variables may use {name} instead of {reader:name}. This remains available, but the reader: form is clearer for new writing.

Some older stories also use a reader value inside a game-variable name, such as {{reader:rival}'s Sales}. Leave a working older story unchanged if it depends on this form. For new stories, use a fixed game-variable name instead.

Before publishing

Preview the story as a reader and check that:

1. every variable uses the intended type and exact capitalization;
2. reader defaults and Dropdown choices appear in the right order;
3. a fresh game begins with the intended game values and visibility;
4. repeated chapter changes produce the expected final value;
5. reader and game variables with the same name remain separate.

Related Guide chapters

• Chapter conditions and game-state changes
• Conditional text with if statements
• Showing reader and game values
• Random values, rolls, reveals, and actions