Dice Rolls

Dice Rolls

Dice-roll tags add a button that produces a whole number from 1 through the chosen number of sides. A roll can stay on the displayed chapter, be limited to one use in a browser session, or save its result in Game State.

Preview

This six-sided roll works without an active game. Select Roll d6 to produce a value from 1 through 6:

{roll d6}

After the first result, the button changes to Roll again. The displayed value is replaced each time the reader rolls.

Copyable syntax

Use d followed by the number of sides:

{roll d6}

Choose the complete form that matches where the result should be kept:

Keep the parts in that order: die, optional as game:variable_name, then optional once.

Repeatable and browser-session rolls

{roll d6} does not need an active game. Its current result remains visible until the reader rolls again or reloads the chapter. Reloading starts the repeatable control again.

{roll d6 once} also works without an active game. After its first use, the button changes to Rolled and CHYOA remembers the result during the current browser session, including after a reload or return to the chapter. A later browser session can roll again.

These two forms do not change Game State or affect later branches.

Save a roll to Game State

First create a Number or Percent game variable as described in Reader and Game Variables, then use its exact name after as game::

{roll d20 as game:damage}

The reader needs an active game. Before one is active, the control is unavailable and shows Start game. Each successful roll replaces the variable's current value and immediately refreshes Game State, inventory, conditional content, and continuation choices.

Add once when that saved game should keep one result:

{roll d20 as game:damage once}

The used state belongs to the saved game and returns when the reader revisits the chapter. Going Back does not make a saved once-only roll available again, even if Back restores an earlier Game State value. Reset Game or Start Over creates a fresh game in which it can be rolled again.

Within one chapter, saved once-only rolls that use the same number of sides and the same target variable share one used state. If two rolls should be independent, save them to different target variables.

Only existing Number and Percent game variables can receive a roll. A Percent roll can use no more than 100 sides. Text, Dropdown, Age, and Yes/No variables cannot receive a saved dice result.

Sides, placement, and combinations

A die can have from 1 through 100,000 sides. The result includes both endpoints: d1 always produces 1, while d100 produces a number from 1 through 100.

A roll tag can appear in ordinary prose or inside a supported container such as a reveal. Do not use an active roll where an element accepts display text only, such as a Random Draw outcome or an ordering-puzzle item. Put it before or after that element instead.

The interactive {roll ...} tag is separate from R6 and D6 values in Changes to game state. A roll tag creates a reader-operated button; an R or D change is chosen automatically when the reader enters a chapter.

Before publishing

• Confirm that the number of sides is from 1 through 100,000.
• Decide whether the reader may reroll or should see the result only once.
• For a saved roll, verify the exact Number or Percent variable name.
• Keep Percent rolls at 100 sides or fewer.
• Test unsaved rolls without a game and saved rolls after selecting Start Game.
• If a saved result affects conditional text or a continuation, confirm that the page updates immediately after the roll.