Stats and Meters

Stats and Meters

Stats and meters place the reader's current Game State directly in chapter prose. Use a stat when the exact value matters. Use a meter when readers should understand progress through a range at a glance.

Both elements display existing values; neither one changes Game State.

What readers see

After a game starts, a stat shows a compact label and the current value. If gold is 12, {stat game:gold "Coins in purse"} shows Coins in purse with 12.

A meter also shows a track across its configured range. If health is 73 on the default 0–100 range, {meter game:health "Health"} shows Health, 73, and a track filled to 73%. Colors and accents follow the story's Element Theme.

Create the Game State variables first

Open Edit Story, then create the values on the Story variables page as explained in Reader and Game Variables. A stat can display any Game State variable type. A meter can display only a Number, Percent, or Age variable.

Use the exact variable name and capitalization from Story variables. For example, a variable named Health must be written as game:Health, not game:health.

Add a stat

The shortest stat uses the variable's configured label:

{stat game:gold}

To use a different label in this chapter, put a quoted label after the variable name:

{stat game:gold "Coins in purse"}

The quoted label changes this display only. It does not rename the variable on Story variables or anywhere else in the story.

A stat shows Text, Dropdown, Number, Percent, Age, and Yes/No values. Yes/No values use a Yes or No icon treatment. Other types show their current value as text. A Percent stat shows the stored number without adding a % sign.

Add a meter

A meter uses a range from 0 through 100 by default:

{meter game:health}

For example, {meter game:progress} shows the current progress value on that default range.

Add a quoted label when the configured variable label is not right for this scene:

{meter game:health "Health"}

Use min and max for another fixed range:

{meter game:level "Level progress" min 1 max 20}

Fixed bounds are whole numbers, and max must be greater than min. Negative bounds are allowed. An Age meter still defaults to 0 through 100, so use the full intended range when appropriate:

{meter game:level min 1 max 20} is the same fixed-range form without a custom label.

{meter game:age "Age" min 18 max 150}

Values below the minimum show an empty track, and values above the maximum show a full track. The number beside the meter remains the actual saved value.

Use changing meter bounds

The minimum or maximum can come from another Number, Percent, or Age Game State variable. This is useful for experience thresholds or capacities that change during play:

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

Omit the custom label when the configured label is suitable: {meter game:xp min game:xp_last_level max game:xp_next_level}.

Every variable named in the meter must already exist, use the exact capitalization from Story variables, and have a numeric type. When xp_last_level or xp_next_level changes, the meter uses the new range.

Understand unavailable values

Before the reader starts a game, a stat or meter displays Start game. A meter does not show its track in that state.

During an active game:

• a missing target value displays Unknown;
• a missing or non-numeric meter value leaves the track hidden;
• a missing or invalid variable used for min or max leaves the target's actual value visible but hides the track.

If an action, Random Draw, roll, reveal, code lock, ordering puzzle, or chapter change updates a displayed value, the stat or meter reflects the refreshed Game State. The display does not create a separate game step of its own.

Limits and combinations

• Stats use only game: variables; they cannot display reader: variables.
• Meters use only Number, Percent, or Age Game State values.
• Labels must be quoted and cannot contain chapter tags.
• Stats accept no options after the optional label.
• Meters may use a quoted label and min or max bounds; they do not accept step counts or other options.
• Several stats and meters may appear in one chapter, including several views of the same value.
• A stat or meter may sit beside ordinary prose and other supported chapter elements, but it only reports state and never changes it.

Before publishing

Save a draft and check that:

1. every referenced variable exists and uses its exact name and capitalization;
2. each stat label makes sense with short, long, zero, negative, and empty values where those values are possible;
3. every meter uses a sensible range whose maximum is greater than its minimum;
4. dynamic meter bounds exist and remain numeric throughout play;
5. the chapter makes sense before Start Game and when a value is missing;
6. values below and above the meter range still communicate the intended result;
7. interactions that change a displayed value refresh the stat or meter as expected;
8. the displays remain readable in White, Black, and Sepia appearance and on a narrow screen.