Random Values, Rolls, Reveals, and Actions

Random values, rolls, reveals, and actions

Authors can add several kinds of interaction to a game story:

• a chapter can choose a random value when the reader enters it;
• a reader can click a dice-roll button;
• a reader can reveal hidden text that changes a game value;
• a reader can press an action button that changes one or more values.

Changes to game variables need an active game.

Random values in chapter changes

In Changes to game state, enter an R or D value instead of a fixed amount for a Number, Percent, or Age.

These forms belong to the structured chapter-change fields. They are not values for reveals or actions. Uppercase and lowercase letters both work, although the uppercase R and D forms are easier to recognize.

The n means the highest number. For example:

• R6 chooses 0, 1, 2, 3, 4, 5, or 6.
• D6 chooses 1, 2, 3, 4, 5, or 6.

Both include the highest number. D0 is not available because a D value always begins at 1.

For a Number, n may be as high as 100000. For a Percent, it may be as high as 100. For an Age, it may be as high as 150.

Age follows its usual 18-to-150 range:

• Set Age to R50 chooses from 18 through 50.
• Set Age to R18 always produces 18.
• A D value cannot be used with Set Age, because it could choose a value below 18.
• Increase Age and Decrease Age can use either R or D; the final age remains between 18 and 150.

Set, increase, and decrease examples

For a Number variable:

• Set R3 produces 0, 1, 2, or 3.
• Starting at 10, Increase R3 produces 10 through 13.
• Starting at 10, Decrease R3 produces 7 through 10.

When a chapter contains several changes, they happen from top to bottom and each random value is chosen separately.

This can create familiar dice results:

• Set D6, then Increase 2 produces a value from 3 through 8.
• Set D6, then Increase D6 rolls two six-sided dice and produces 2 through 12. Results near 7 appear more often than 2 or 12, just as they do with two physical dice.

Add a dice-roll button

Dice may have 1 to 100000 sides. Choose the form that matches what should happen:

Unsaved rolls work even when the reader has not started a game. A roll using as game:... is disabled and displays Start game until a game is active.

The saved variable must already exist and must be a Number or Percent. A Percent roll may have no more than 100 sides. Text, Dropdown, Age, and Yes/No cannot receive a saved roll. Use the exact spelling from the Story variables page.

A once-only roll stays used even if the reader goes back to an earlier chapter. For an unsaved once-only roll, the result is remembered for the browser session. For a saved once-only roll, the used state belongs to the saved game.

Change a value when hidden text is revealed

A reveal can update one existing game variable when the reader opens it:

{reveal "Inspect" set game:found_key = true}...{endreveal}

The quoted words become the button label. The hidden text goes between the opening tag and {endreveal}.

A reveal uses = to set one value. It cannot increase or decrease a value. Yes/No accepts true, false, yes, no, 1, or 0. Number, Percent, and Age need a whole number within their allowed range. Put quotation marks around Text and Dropdown values that contain spaces. For a Dropdown, use one of the choices on the Story variables page; reveal text does not restrict the value to that list for you.

The value changes only when the reader opens the reveal. A reveal cannot be placed inside another reveal.

Add an action button

An action button changes game values without moving to another chapter. Start with a simple action:

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

The reader sees a Take key button. Pressing it sets has_key to Yes.

An action can require a condition, change several values, and be limited to one use:

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

The button remains visible but unavailable until the reader has at least three coins. Pressing it then spends three coins and records that the rope is owned.

Write the parts in this order:

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

Use = to set a value. Use += to increase a Number, Percent, or Age, and -= to decrease one. The amount after += or -= must be a whole number of 0 or higher.

Action conditions accept the same comparisons, AND, OR, and parentheses as if statements. A missing value makes the condition fail.

When an action has several changes, they happen from left to right. Each target variable must already exist, and every change must match its type and exact name.

Order matters even when one action changes the same variable twice. set game:coins = 5, game:coins += 2 ends with 7, while set game:coins += 2, game:coins = 5 ends with 5.

After the action succeeds, the reader immediately sees updated Game State, inventory, chapter choices, and any other displays that use those values.

With once, CHYOA applies the action only once. If the reader goes back to a point before that action, the button becomes available again. Without once, the reader can repeat the action as long as its condition still passes.

Changes for each variable type

These are individual changes that can appear after an action's set:

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

For a Dropdown, use one of the choices listed on the Story variables page. Action text does not restrict the value to that list for you; an unlisted value cannot be selected by a Dropdown reader input and may not match the author's later rules.

Place roll, reveal, and action tags as ordinary chapter text. When writing in Markdown, backticks or a fenced code block show the tags literally instead of creating controls. Interactive tags placed inside a link are not turned into buttons.

Older chapters

Some older chapter text may have no space between action and the quoted label:

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

This remains available, but the spaced form is easier to read and is recommended for new chapters.

Before publishing

Test each interaction with a fresh game:

1. confirm that the configured range includes the intended smallest and largest values;
2. confirm that chapter changes happen in the intended order;
3. try rerollable and once-only dice;
4. open every reveal and confirm its saved value;
5. try actions when their conditions pass and fail;
6. go back past a once-only roll and a once-only action to confirm their different behavior.

Related Guide chapters

• Reader and game variables
• Chapter conditions and game-state changes
• Conditional text with if statements
• Showing reader and game values