Showing Reader and Game Values

Showing variable values

Authors can place reader choices and saved game values directly into chapter text. They can also add reader-editable fields, compact stat displays, and meters.

Show a reader value

Put reader: and the variable name inside braces:

Welcome, {reader:name}!

If the reader chose Alex, the chapter shows “Welcome, Alex!” If the reader has not chosen a custom value, the story's default is shown.

Use the exact name and capitalization from the Story variables page.

Show a game value

Use game: for a value from the reader's current game:

You have {game:coins} coins.

If coins is 12, the reader sees “You have 12 coins.” Reader and game variables remain separate, even when they have the same name. For example, {reader:mood} / {game:mood} shows two different values.

Provide a fallback when no game value is available

Use @ when the chapter should show another value before a game begins or when the game value is missing:

You sold {@36 game:Sales} cars this month.

When Sales exists, the reader sees its current value. Otherwise, the reader sees 36.

The fallback comes immediately after @. It can be true, false, or a whole number, including a negative number. This form is for game variables, not reader variables.

A fallback is used only when the game is inactive or the variable is missing. Existing values such as Number 0, Percent 0, Yes/No No, or empty Text are still present and do not use the fallback.

Without a fallback, an unavailable game variable remains visible in its original brace form. For example, {game:Sales} stays {game:Sales}. This makes a missing value noticeable instead of silently turning it into empty text.

Let the reader edit a value inside the chapter

Use an input when the reader should be able to change a reader variable without opening Customize:

{input reader:name}

The field matches the variable type. Text is a text field; 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. Leaving Text blank returns to its default. Saving an input changes the reader's customization; it does not change a game variable.

Direct Percent substitutions show the number without adding a % sign. Add the sign in the surrounding sentence when needed. A direct reader Yes/No substitution shows yes or no, while a direct game Yes/No substitution shows true or false.

Add a stat display

A stat shows a compact label and value for an existing game variable:

{stat game:gold}

It can show any game-variable type. By default, the label comes from the Story variables page. Add a quoted label to change it in this one place:

{stat game:gold "Coins in purse"}

A stat only displays the value. It does not change it.

Without an active game, a stat displays Start game. During a game, a missing value displays Unknown. Yes/No stats use a Yes or No icon treatment; other values are shown as text. A Percent stat does not add % automatically.

Add a meter

A meter gives readers a visual view of an existing Number, Percent, or Age game variable.

{meter game:progress} uses a range from 0 to 100.

For a different fixed range, add min and max:

{meter game:level min 1 max 20}

The ends of the meter can also come from other Number, Percent, or Age game variables:

{meter game:xp min game:xp_last_level max game:xp_next_level}

Add a quoted label before the range when needed:

{meter game:health "Health" min 0 max game:max_health}

For a fixed range, the maximum must be greater than the minimum. When another variable supplies an end of the meter, the meter changes with that value. Test what the reader sees when the value or either end is missing.

A meter only displays the current value. It does not increase or decrease it.

Without an active game, the meter value says Start game and no track is shown. During a game, a missing target value says Unknown and no track is shown. If the target exists but is not a number, its actual value remains visible but the track is omitted. A missing or invalid variable used for min or max also leaves the target's actual value visible while omitting the track.

Values below the meter's minimum show 0% fill, and values above its maximum show 100% fill. The displayed number remains the actual value. An Age meter still defaults to 0 through 100, so use {meter game:age min 18 max 150} to show the full Age range.

For game values, stats, and meters, use the exact name and capitalization shown on the Story variables page.

Removed or missing game values

Game displays need an active game and an available value. If a chapter removes a value, it remains unavailable until another chapter change, roll, reveal, or action creates it again.

Removing a value does not restore its starting value. If the story needs a reset, set the intended value directly.

Older chapters

Older reader variables may use {name} instead of {reader:name}.

Older game values may use {Sales} instead of {game:Sales} when no reader variable has the same name. An older fallback may appear as {@36 Sales} instead of {@36 game:Sales}.

These forms remain available for existing stories. Use reader: and game: in new chapters because they make the intended value clear.

Before publishing

Preview the chapter with:

1. a reader who kept the reader-variable default;
2. a reader who saved a custom value;
3. an active game with the expected game values;
4. no active game;
5. any game value used by a stat or meter removed;
6. the smallest and largest meter values.

Related Guide chapters

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