Ordering Puzzles

Ordering puzzles

Ordering puzzles ask readers to rearrange a shuffled list into the sequence written by the author. Authors can allow retries or give readers only one check. In a Game Mode story, a correct or incorrect check can also save a Game State value.

Preview

The correct sequence follows the day from morning to night:

Drag an item by its grip or use Move up and Move down, then select Check order.

Copyable syntax

Write the items in their correct order. Put the opening tag, every item, and the closing tag on separate lines:

{order "Arrange the ritual steps"}
Light the candles.
Draw the circle.
Speak the true name.
{endorder}

CHYOA shuffles the items before the reader sees them. A wrong answer shows Try again without identifying which positions are correct. A correct answer changes Check order to Solved and freezes the list in the authored order.

Give the reader one check

Add once immediately after the quoted prompt when the first check should decide the puzzle:

{order "Stabilize the reactor" once}
Open the coolant valve.
Engage the auxiliary pump.
Restart the core.
{endorder}

The reader can arrange the items and use Start over before checking. Their first selection of Check order consumes the attempt. A correct order ends as Solved; a wrong order ends as Failed. Either result freezes the list and prevents another check.

This plain once form works without an active game. CHYOA remembers its final arrangement and Solved or Failed result for the current browser session. A later browser session starts with a fresh puzzle.

Reveal a success passage

Add {success} after the final item when solving should reveal more prose:

{order "Restore the timeline"}
The lights fail.
The vault opens.
The alarm sounds.
The guards arrive.
{success}
The console accepts the sequence. **Access granted.**
{endorder}

The success passage appears in a separate panel only after the correct order is checked. A failed once attempt does not reveal it. The passage may contain ordinary Markdown and links, but it must contain visible text and cannot contain active chapter tags. Use {success} at most once. Without it, the solved list and Solved control still show that the puzzle is complete.

Write useful puzzle items

Each puzzle needs from 3 through 20 unique items. Three through eight items are usually easier to read and rearrange, especially on a phone.

Each item:

• stays on one physical line;
• contains visible text;
• may use inline emphasis, a link, or inline code;
• must remain unique after its formatting is removed;
• cannot begin with a Markdown list marker such as -, *, or 1.;
• cannot contain an image, heading, block quotation, raw HTML, nested list, or active chapter tag.

Use wording that lets readers reason about the sequence. If two lines look identical after formatting, the chapter cannot tell them apart and the puzzle will not save.

How progress behaves

Readers can drag items or use the keyboard-friendly Move up and Move down controls. Before the puzzle reaches a final result, Start over returns the list to that browser session's original shuffled order. It does not show the answer and does not create a different shuffle.

For a plain puzzle, the current arrangement and any Solved or Failed state remain available while the reader uses the same browser session, including after leaving and returning to the chapter. They are not part of a saved game and do not carry into another browser session.

Save success or failure to Game State

Add set game:... for the correct order and fail set game:... for a wrong order. This one-check example records either result:

{order "Restore the timeline" once set game:timeline_fixed = true fail set game:timeline_fixed = false}
The lights fail.
The vault opens.
The alarm sounds.
{endorder}

Keep the opening-tag options in this order: quoted prompt, optional once, optional success set game:..., then optional fail set game:.... Either assignment may be omitted.

Create timeline_fixed as a Yes/No game variable first, following Game State Variables and Inventory, and use the exact name shown on the story's Story variables page. If either assignment is present, the puzzle needs an active game. Until one begins, the puzzle controls are unavailable and Check order shows Start game.

On a correct check, CHYOA applies the success assignment and ends the puzzle as Solved. On a wrong check, it applies the failure assignment when one is present. Without once, the puzzle then shows Try again and still permits another attempt. With once, the first wrong check ends as Failed and cannot be retried.

An applied assignment refreshes Game State and inventory and updates conditional text and continuation choices. Saved final outcomes return with the chapter during that game.

Each success or failure assignment changes one existing value, so one result cannot change several values. Fixed Yes/No, numeric, Text, and Dropdown values follow the same type rules as a state-changing reveal or code lock.

For a Number, Percent, or Age target, either result may use a formula after =, +=, or -=:

{order "Stabilize reactor" once set game:condition = MIN(100; game:condition + game:repair) fail set game:condition -= game:damage}
Open the coolant valve.
Engage the auxiliary pump.
Restart the core.
{endorder}

A correct order adds repair to condition without returning more than 100. A wrong order subtracts damage. The formula may use the arithmetic, checks, existence checks, rounding, and random functions described in Game-State Formulas. Formula assignments cannot target Yes/No, Text, or Dropdown variables.

If a result's formula cannot be calculated, no Game State change is saved and the check is not made final, even with once. The puzzle can be checked again.

Back and reset

A state-changing result is saved as a game step. Returning to a saved Solved or Failed result does not calculate its assignment again, so DICE or RANDOM chooses once for that check. Going Back past a saved Solved or Failed result restores the earlier value and makes the puzzle available again. A repeatable wrong check that applies a failure assignment remains retryable; each new check is a new interaction, while going Back past its game step restores the earlier value. Reset Game or the game's Start Over option begins a fresh game with a new unsolved puzzle.

An ordinary puzzle has no game step, so the story's Back control does not undo its browser-session arrangement or final result. Before it reaches a final result, use the puzzle's own Start over control to return to its first shuffled order during that browser session.

Placement and combinations

Ordering puzzles cannot be nested or placed inside chat bubbles. A Random Draw and an ordering puzzle cannot contain one another or cross each other's opening and closing tags. Keep all three puzzle tags on their own lines.

An ordering puzzle may appear inside a code lock. It can also use ordinary surrounding conditional text, but if a condition hides the puzzle, readers cannot check it until that passage is visible. If a puzzle's own saved change hides its surrounding passage, that result remains in the game. Making the passage visible again restores a final Solved or Failed result, while a repeatable wrong check remains available for another try. Going Back past the corresponding game step undoes the change. Do not use a puzzle to protect secrets, prizes, private information, or required access; its items and success passage belong to the chapter readers receive.

The story's Element Theme styles the prompt, items, controls, feedback, and success passage.

Before publishing

Save a draft and check that:

1. all items are written in the intended correct order and are visibly distinct;
2. the first view is shuffled rather than accidentally solved;
3. dragging and Move up or Move down can both reach the correct order;
4. a repeatable wrong answer shows Try again without giving away the solution;
5. a once puzzle ends as Solved or Failed after its first check and cannot be checked again;
6. Start over restores the original shuffled arrangement before the final check;
7. the solved list freezes and the optional success passage appears only after a correct check;
8. a puzzle with either assignment shows Start game when inactive and saves the intended correct or incorrect value;
9. every formula value exists whenever the puzzle can be checked or has an intended EXISTS, IF, or IFERROR fallback, and calculation errors do not consume the check;
10. going Back past a saved final result restores the earlier value and makes the puzzle usable again;
11. long items and links remain readable on a narrow screen and in every site appearance.