Game State Variables and Inventory

Game State variables and inventory

Game variables remember story-controlled values such as health, coins, routes, clues, and collected items. They belong to the reader's saved game, so the reader needs to start a game before the current values are available.

If you still need to choose between Reader and Game scope or compare their types, start with Reader and Game Variables.

Create a starting value

Open Edit Story, enable Chapters can use game state, and choose Add Game State Variable. Enter its name, choose a type, set its initial value, and save the story.

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

Game-state Number, Percent, and Age values use whole numbers. If a change would go beyond the type's range, CHYOA keeps the result at the nearest allowed value. Increasing a Percent value of 95 by 10 therefore produces 100.

Each game-variable name must keep one type throughout the story. Do not use score as a Number in one chapter and a Percent in another.

Chapter-entry changes can update these values as a reader moves through the story. Reader-triggered Random Draws, Dice Rolls, Reveals, Code Locks, Ordering Puzzles, and Action Buttons can update them too; Interactive Chapter Elements leads to the instructions for each element.

Understand starting values and existing games

Starting values and their configured order apply when a reader starts or resets a game. On a fresh game, CHYOA applies those values first, then applies the first chapter's changes from top to bottom, and only then shows the chapter. A first-chapter change can 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.

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

Set labels and author shortcuts

The Story variables page provides three display settings:

• 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.
• Inventory → Show assigns the variable to the story's inventory instead of the ordinary Game State Variables list.

Reader-variable insertion shortcuts keep reader-definition order. Game-variable Sidebar → Show shortcuts remain alphabetical, so Move Up and Move Down do not rearrange those shortcuts.

Put a value in inventory

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.

The Inventory display card controls the inventory section itself. Display name replaces the default “Inventory” heading, and Icon chooses the symbol used in the story sidebar and mobile inventory drawer. These settings apply to the whole story; each variable's Label controls that item's name.

The story's Element Theme controls the appearance of Game State, inventory, stats, meters, and interactive controls. It changes presentation only, not values, ownership, visibility, or order.

Control order and visibility

Different lists use order differently:

Use Move Up and Move Down while editing the story to arrange defined game variables. Chapter-change rows have their own controls; use them to put calculations and other changes in execution order.

On a fresh or reset game, ordinary Game State begins in 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 current definition order.

Repeated changes to one value are supported. Set 5, followed by Increase 2, produces 7; reversing those rows produces 5. Game-State Formulas can read current Number, Percent, Age, and Yes/No values in a calculated change. Limits apply after each row, so the next row sees the adjusted result.

Show makes a value visible in its normal Game State section, Hide hides it there, and Keep leaves its current visibility unchanged. Remove discards the value and that visibility. If a later row recreates it, the value starts visible and Keep preserves that new state.

Change an existing story safely

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

Before renaming a variable or changing its type:

1. Open Used in and review every listed condition, change, and formula reference.
2. Review chapter text manually for substitutions, if statements, Random Draws, stats, meters, rolls, reveals, code locks, ordering puzzles, and actions using the old name.
3. Test both a fresh game and a game that was already in progress.

CHYOA prevents changing a game variable's type while structured rules still use it. Renaming through Story variables also updates structured formula references. Names typed directly into chapter text still need a manual review. Existing saved games are not rewritten when a variable is renamed, retyped, reordered, or given a new initial value.

A Dropdown choice still used by a structured condition or change is retained even if it is removed from the definition, and it may be placed after the current choices. Update those rules before removing the old choice completely. Also review Random Draws that save to that Dropdown: their quoted values must match current choices, and Used in does not list values written directly in chapter text.

Before publishing

Test a fresh game, a reset game, and an existing game. Check that:

1. starting values, types, visibility, and definition order are correct;
2. every first-chapter change produces the value the reader should initially see;
3. inventory items appear only for owned values and use the intended labels and order;
4. repeated changes and formulas produce the expected result from top to bottom;
5. missing, removed, restored, and newly added values behave correctly along every route;
6. renames, type changes, Dropdown changes, and direct chapter syntax have all been reviewed.

Older game-variable names

Some older stories 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.