Stat Bars

Display numeric variables as visual progress bars—perfect for health, relationships, skills, or any stat you want players to see at a glance.

Basic Usage

VAR health = 75

# STATBAR: health

Aliases: # STAT_BAR:, # PROGRESSBAR:, # PROGRESS_BAR:

This displays a progress bar showing the current value of health. By default, the bar assumes a range of 0–100 and uses the variable name as the label.

Custom Display Name

Add a quoted string to set a friendlier label:

# STATBAR: health "Hit Points"

Displays as “Hit Points” instead of “health”.

Custom Range

Specify min and max values when your stat doesn’t use 0–100:

VAR mana = 20

# STATBAR: mana 0 50 "Magical Energy"

The format is # STATBAR: variable min max "Label".

Opposed Stat Bars

For stats that represent a spectrum between two extremes (like ChoiceScript’s opposed pairs), use two labels:

VAR bravery = 65

# STATBAR: bravery "Brave" "Cowardly"

This creates a bar with “Brave” on the left and “Cowardly” on the right. The display shows both values (e.g., “65/35”) so players can see where they fall on the spectrum.

You can combine this with custom ranges:

# STATBAR: morality -100 100 "Evil" "Good"

Value Clamping

By default, stat bars display the actual variable value, even if it goes below the minimum or above the maximum. This is useful during development to spot logic errors.

For a polished release, add clamp to keep displayed values within range—regardless whether the true value overflows:

# STATBAR: health clamp
# STATBAR: health 0 100 "HP" clamp
# STATBAR: bravery "Brave" "Cowardly" clamp

Note: The visual bar always stays within bounds (it won’t overflow or go negative). Clamping only affects the displayed number.

Using on Special Pages

Stat bars work great on special pages for character sheets:

=== character_sheet ===
# SPECIAL_PAGE: Character

: Your Stats

# STATBAR: health "Health"
# STATBAR: mana 0 50 "Mana"
# STATBAR: reputation "Hated" "Beloved"

-> DONE

You can display multiple stat bars in a row; they’ll each appear on their own line.

Quick Reference

Note: Parameters can appear in any order after the variable name. If specifying a range, the first number found becomes min, the second becomes max.

Tips

• Variable must exist: Declare your variable with VAR before using it in a stat bar.
• Updates automatically: When you revisit a passage with a stat bar, it shows the current value.
• Combine with text: Add context around your stat bars with regular Ink text.
• Accessibility: Stat bars include ARIA attributes so screen readers announce values properly.

Example: RPG Character Sheet

VAR health = 80
VAR mana = 25
VAR strength = 60
VAR reputation = 45

=== stats_page ===
# SPECIAL_PAGE: Stats

: Character Stats

:: Combat

# STATBAR: health "Health" clamp
# STATBAR: mana 0 50 "Mana" clamp
# STATBAR: strength "Strength" clamp

:: Social

# STATBAR: reputation "Feared" "Respected"

-> DONE

Found a bug or have a feature idea?
Open an issue on GitHub, or use the feedback forms: Bug report · Feature request