Ordering Puzzles

Ordering puzzles

Ordering puzzles ask readers to rearrange a shuffled list into the sequence written by the author. A solved puzzle can reveal a success passage and, in a Game Mode story, save one 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.

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. It 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. 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 solved 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 a Game State value

Add one set game:... assignment when solving the puzzle should affect the story:

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

Create timeline_fixed as a Yes/No game variable first, following Reader and Game Variables, and use the exact name shown on the story's Story variables page. This form needs an active game; until one begins, the puzzle controls are unavailable and Check order shows Start game.

When the correct order is checked, CHYOA sets the value, saves the completion, refreshes Game State and inventory, and updates conditional text and continuation choices. If the puzzle remains in a visible passage, returning during that game restores it as solved.

An ordering puzzle uses = to set one existing value. It cannot increase or decrease a value and cannot change several values. Yes/No, numeric, Text, and Dropdown values follow the same type rules as a state-changing reveal or code lock.

Back and reset

A state-changing completion is one saved game step. Going Back past it restores the earlier value and makes the puzzle available to solve again. Reset Game or Start Over also starts 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 local arrangement. 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 complete it until that passage is visible. If a puzzle's own saved change hides its surrounding passage, the completion remains saved; making the passage visible again restores the solved puzzle unless the reader has gone Back past that completion. 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 wrong answer shows Try again without giving away the solution;
5. Start over restores the original shuffled arrangement;
6. the solved list freezes and the optional success passage appears;
7. a state-changing puzzle shows Start game when inactive and saves the intended value when solved;
8. going Back past a saved completion restores the earlier value and makes the puzzle usable again;
9. long items and links remain readable on a narrow screen and in every site appearance.