Action Buttons

Action buttons

Action buttons let readers change Game State without leaving the chapter. Authors can use them for choices such as taking an item, spending coins, changing a statistic, or recording a decision. Every action needs an active game and at least one existing game variable to change.

How the button behaves

With an active game and matching variables, the reader sees the action's label as a button. When its condition passes, selecting it applies the listed Game State changes and refreshes affected text and choices. For example, a Buy rope action can change coins from 5 to 2, change rope ownership to Yes, and immediately open a continuation that requires the rope.

A failed condition leaves the button visible as Unavailable. A completed once-only action shows Used.

Copyable syntax

The simplest action sets one value:

{action "Take key" set game:has_key = true}

The reader sees a Take key button. Selecting it sets the existing Yes/No variable has_key to Yes. Before a game starts, the button is unavailable and shows Start game.

Add a requirement and several changes

Use if when the current Game State must meet a requirement. Separate multiple changes with commas:

{action "Buy rope" if game:coins >= 3 set game:coins -= 3, game:has_rope = true}

Write an action in this order:

1. action and a non-empty quoted button label;
2. optional once;
3. optional if and its condition;
4. set and one or more changes separated by commas.

The if condition accepts the same comparisons, NOT (or its ! alias), AND, OR, and parentheses as conditional text. For example, {action "Take key" if NOT game:has_key = true set game:has_key = true} is available until has_key becomes Yes. A missing or otherwise unavailable value makes a comparison fail, and adding NOT does not turn it into a match. The button remains on the page in an Unavailable state until the condition passes; the condition does not hide it.

When a successful action changes a value used by its own condition, the button updates immediately. In the rope example, spending the last available coins can make the repeatable action unavailable after the first purchase.

Limit an action to one use

Place once before if when the action should succeed only once in that saved path:

{action "Buy rope" once if game:coins >= 3 set game:coins -= 3, game:has_rope = true}

After it succeeds, the button shows Used and cannot apply its changes again. Without once, readers may repeat the action for as long as its condition passes.

Each successful action is saved as a game step. Going Back past that step restores the previous values. For a once-only action, Back also removes its used state, so the action becomes available again when its other requirements pass. This differs from a saved once-only dice roll, which intentionally stays used after Back.

Reset Game or Start Over begins a fresh game and clears once-only action use along with the old Game State.

Set, increase, and decrease values

Every target must already exist as described in Reader and Game Variables, and its exact name and type must match the definition on the story's Story variables page.

Use = to replace a value:

{action "Choose the forest" set game:route = "forest path"}

Use += or -= with a non-negative whole number to change a Number, Percent, or Age:

{action "Work a shift" if game:energy >= 1 set game:energy -= 1, game:coins += 5}

Common forms are:

• Number: game:coins = -3 or game:coins += 5
• Percent: game:progress = 75 or game:progress -= 10
• Age: game:age = 21 or game:age += 1
• Yes/No: game:has_key = true
• Text or Dropdown: game:route = "forest path"

For a Dropdown, use one of its configured choices. Random R and D values are not action values; an action uses the fixed value written in its tag.

Changes happen from left to right

When one action contains several changes, each uses the result of the change before it. This matters when a variable appears more than once:

{action "Recalculate" set game:coins = 5, game:coins += 2}

This ends with 7. Reversing the two changes ends with 5. Type limits are applied as the values change, so an increase above a type's maximum stops at that maximum.

After a successful action, visible Game State, inventory, stats, meters, conditional text, and continuation choices refresh without a page reload.

Show or hide the whole action

An action's own if option leaves its button visible and unavailable. To omit the entire action until a condition passes, put it inside conditional text:

{if game:shop_open = true}
{action "Buy rope" once if game:coins >= 3 set game:coins -= 3, game:has_rope = true}
{endif}

The action appears only while shop_open is Yes. Conditional passages refresh after Game State changes, so actions can appear or disappear on the current page. A completed once-only action remains completed even if its own change causes the surrounding passage to disappear; going Back past that action is what makes it usable again.

Placement and combinations

Place an action tag as ordinary chapter text, outside a link. It may appear inside supported containers such as a reveal, code lock, email card, or fictional terminal. An action inside a code lock is usable only after the reader enters that lock's answer.

Use literal backticks or a fenced example when the tag should be displayed rather than turned into a button. The story's Element Theme controls the button's available, unavailable, loading, and used presentation.

Some older chapters omit the space between action and the label:

{action"Take key" set game:has_key = true}

That form remains available, but use the spaced form in new chapters because it is easier to read.

Before publishing

Test the action in a fresh game and check that:

1. it shows Start game before a game is active;
2. its label clearly describes what selecting it will do;
3. each target name, type, and value matches its definition;
4. conditions make the button available and unavailable at the intended times;
5. multiple changes happen in the intended left-to-right order;
6. repeatable actions stop when their own requirements no longer pass;
7. once-only actions show Used and cannot apply twice;
8. Game State, inventory, stats, meters, conditional text, and continuation choices refresh after success;
9. going Back restores the previous values and makes a once-only action reusable;
10. the action remains understandable in every surrounding block and site appearance.