Code Locks

Code locks

Code locks let an author hide part of a chapter behind an exact answer. Readers see a prompt, an answer field, and an Unlock button. Authors can allow retries or make the first submitted answer final. In a Game Mode story, a correct or incorrect answer can also save a Game State value.

Preview

Enter 1234 to unlock the safe:

{lock "Enter the four-digit code" answer "1234"}
The safe clicks open. A map rests inside.
{endlock}

This is a plain lock, so it works without starting a game and does not change Game State.

Copyable syntax

Put the prompt and answer in matching straight quotation marks. Place the passage between the opening tag and {endlock}:

{lock "Enter the four-digit code" answer "1234"}
The safe clicks open. A map rests inside.
{endlock}

The reader initially sees Enter the four-digit code, a text field, and Unlock. Entering 1234 changes the control to Unlocked and reveals the passage. An incorrect answer leaves the passage hidden and shows Try again.

Give the reader one attempt

Add once after the quoted answer when the reader's first submitted answer should decide the lock:

{lock "Open the vault" answer "1234" once}
The safe clicks open. A map rests inside.
{endlock}

A correct answer ends as Unlocked and reveals the passage. A wrong answer ends as Failed, keeps the passage hidden, and prevents another attempt.

This plain once form works without an active game. CHYOA remembers its Unlocked or Failed result for the current browser session, including after the reader leaves and returns to the chapter. A later browser session starts with a fresh lock.

Match the answer exactly

Answers are case-sensitive and include every space inside the quotation marks. For example, Ember, ember, and Ember are different answers. Tell readers enough to understand the expected form when capitalization or punctuation matters.

Both the prompt and answer must contain text. Use matching straight single or double quotation marks, and do not put another chapter tag inside either value:

{lock 'Speak the password' answer 'Open, sesame!'}
The stone door moves aside.
{endlock}

A code lock is a story puzzle, not secure protection. Do not place private information, real credentials, prizes, or anything else that must remain secret behind it.

Save success or failure to Game State

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

{lock "Open vault" answer "1234" once set game:vault_open = true fail set game:alarm = true}
The safe clicks open. A map rests inside.
{endlock}

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

First create each target as described in Game State Variables and Inventory, then use the exact name and capitalization shown on the story's Story variables page. If either assignment is present, the lock needs an active game. Until one begins, its field is unavailable and the button shows Start game.

On a correct answer, CHYOA applies the success assignment and reveals the protected passage. On a wrong answer, it applies the failure assignment when one is present and keeps the passage hidden. Without once, the lock then shows Try again and permits another answer; each wrong answer can apply the failure assignment again. With once, the first wrong answer ends as Failed and cannot be retried.

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

In a compact example, the same pattern may be written as {lock "Open vault" answer "1234" once set game:vault_open = true fail set game:alarm = true}...{endlock}. Replace ... with the passage shown only after the correct answer.

A retryable lock may omit the success assignment: {lock "Enter code" answer "1234" fail set game:alarm = true}...{endlock}. A correct answer reveals its passage without changing Game State. Each wrong answer sets alarm to Yes and still permits another try.

Each set or fail set clause changes one existing value, so one outcome cannot change several values. A fixed assignment uses = and a value that matches the target type:

• Yes/No accepts true, false, yes, no, 1, or 0.
• Number, Percent, and Age use a whole number within that type's range.
• Text and Dropdown values may be quoted, and values containing spaces must be quoted.
• A Dropdown value should be one of the choices configured for that variable.

For example:

{lock "Name the marked route" answer "North road" set game:route = "north road"}
The compass needle settles.
{endlock}

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

{lock "Open vault" answer "1234" once set game:wealth += game:reward fail set game:wealth -= game:penalty}
The safe clicks open. A map rests inside.
{endlock}

The compact form is {lock "Open vault" answer "1234" once set game:wealth += game:reward fail set game:wealth -= game:penalty}...{endlock}. On the correct answer, the current reward is added to wealth. On the first wrong answer, the current penalty is subtracted instead. 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 an outcome's formula cannot be calculated, no Game State change is saved and that answer is not made final, even with once. The lock can be attempted again.

Results, Back, and reset

A repeatable plain lock stays open only on the currently loaded page. Reloading the chapter closes it and asks for the answer again. A plain once lock instead keeps its final Unlocked or Failed result for the current browser session.

A state-changing result is saved as a game step. If the lock is still in a visible passage, returning to the chapter during that game restores a final Unlocked or Failed result without calculating its assignment again. A formula with DICE or RANDOM therefore chooses once for that submitted answer. Going Back past that result restores the earlier value and makes the lock available again. A repeatable wrong answer that applies a failure assignment remains retryable; each new wrong answer is a new interaction, while going Back past its game step restores the earlier value. Reset Game or Start Over also begins a fresh game with an available lock.

Conditional text can hide an entire lock before or after an answer. A hidden lock cannot be answered. If a lock's own saved change hides its surrounding passage, that result remains in the game. Making the passage visible again restores a final Unlocked or Failed result, while a repeatable wrong answer remains available for another try. Going Back past the corresponding game step undoes the change.

Content and combinations

The hidden passage can contain paragraphs, headings, lists, links, and other supported Markdown. It can also contain supported chapter elements such as a reveal, ordering puzzle, or action button. If an action or ordering puzzle is inside a lock, readers must unlock the surrounding passage before they can use it.

Do not place a code lock inside another code lock. Keep {lock ...} and {endlock} paired, and use a separate block for each answer. To show lock tags as literal text in a chapter, put them in backticks or a fenced block.

The story's Element Theme controls the lock panel, field, button, incorrect and failed states, and unlocked passage without changing the answer or Game State behavior.

Before publishing

Save a draft and test that:

1. the prompt tells readers what kind of answer to enter;
2. the exact intended answer opens the passage;
3. a near match with different capitalization, spacing, or punctuation is rejected;
4. the unlocked passage and any elements inside it work on narrow and wide screens;
5. a once lock ends as Unlocked or Failed after its first submitted answer and cannot be answered again;
6. a lock with either assignment shows Start game when inactive and saves the intended correct or incorrect value;
7. every formula value exists whenever the lock can be answered or has an intended EXISTS, IF, or IFERROR fallback, and calculation errors do not consume the answer;
8. conditional text, inventory, and continuation choices refresh after an applied assignment;
9. going Back past a saved final result restores the earlier value and makes the lock usable again;
10. the lock remains readable with the story's Element Theme in White, Black, and Sepia appearance.