Chapter Conditions and Game-State Changes

Chapter conditions and game-state changes

Conditional branches let an author change which follow-up chapters a reader can choose. A story can require enough coins, a particular choice, a found item, or any other saved game value.

For example, a locked-door chapter might be available only after the reader finds a key. Readers who have the key can continue through the door; readers who do not have it see a disabled choice or no choice, depending on the story setting.

Turn on game state

While editing the story, enable Chapters can use game state. This adds two sections to chapter forms:

• Game state conditions to view this chapter decides whether the reader may enter that chapter.
• Changes to game state updates values when the reader enters the chapter.

Readers need to start a game before game-state conditions and changes can use their saved progress.

Add a condition to the destination chapter

A condition belongs to the chapter that it protects, not the chapter containing the choice that leads there.

Suppose a shop chapter should open only when a reader has at least three coins:

1. Create a Number game variable named coins.
2. Edit the shop chapter.
3. Turn on Game state conditions to view this chapter.
4. Choose coins, choose Greater or Equal (>=), and enter 3.

The form builds the condition game:coins >= 3, meaning that the current value of coins must be at least 3.

During an active game, CHYOA checks the condition when the shop appears as a follow-up. Opening the shop chapter directly does not bypass the condition. Without an active game, readers can browse chapters without saved-game checks.

What readers see when a condition fails

The story setting Show inaccessible chapters controls failed follow-up choices while a game is active:

• When enabled, the choice remains visible but cannot be selected.
• When disabled, the choice is not shown.

Either way, a reader playing an active game cannot choose the protected chapter until its conditions pass.

Comparisons

Choose a comparison that describes the required value:

Text, Dropdown, and Yes/No values support equal and not equal. Number, Percent, and Age support all six comparisons.

One variable can also be compared with another suitable game variable. For example, an author can require game:coins >= game:price. Number, Percent, and Age can be compared with one another; Text and Dropdown can be compared with one another; Yes/No can be compared only with Yes/No.

Text and Dropdown comparisons are exact. Capitalization matters: Forest and forest are different values.

If the variable being tested on the left is missing from the current game, the condition fails. This is also true for not equal: a missing coins value does not count as “not equal to 3.”

When the required value on the right is another game variable, CHYOA uses that variable's stored default when one is available, even if the value has not entered the current game yet. The condition fails if no usable default is available. This fallback belongs to chapter-form conditions; an inline {if ...} comparison fails when either side is missing.

Using several conditions

When a chapter has several condition rows, every row must pass. For example, a guarded gate might require both has_pass = true and reputation >= 10.

Two conditions for the same variable can describe a range. temperature >= 18 and temperature <= 25 together allow only values from 18 through 25.

Changing the order of condition rows does not change whether the chapter is available. If either one of two different requirements should grant access, create separate follow-up chapters for those routes. Conditional text can change what a reader sees after entering a chapter, but it does not grant access to that chapter.

Change values when a chapter opens

Use Changes to game state to update the reader's saved progress when they enter a chapter during an active game. The changes happen before the chapter is shown, so its text, Game State, inventory, and follow-up choices all use the new values.

The destination chapter's conditions are checked before the reader enters it. Changes on that same chapter therefore cannot make its own failed access condition pass; the required value must be set earlier in the path.

Some common examples are:

• Set coins to 5 replaces the current coin total.
• Increase coins by 2 adds two coins.
• Decrease coins by 3 spends three coins.
• True records that a Yes/No event happened.
• Reverse changes Yes to No or No to Yes.
• Remove makes the value unavailable until another change creates it again.

Changes happen from top to bottom

Each row uses the result of the row above it. If the same chapter sets coins to 5 and then increases it by 2, the final value is 7. If the increase comes first and Set 5 comes last, the final value is 5.

Change rows are added in their working order and do not have move controls. If the order is wrong, remove and recreate the affected rows in the intended sequence.

A later row can recreate a removed value. When Increase or Decrease recreates a missing Number or Percent, it begins at 0. A missing Age also begins at 0, but the result stops at the allowed minimum of 18. For example, increasing a missing Age by 2 produces 18, while increasing it by 30 produces 30. Reversing a missing Yes/No value creates Yes.

In the chapter form, enter an amount of 0 or higher and choose Increase or Decrease. To move a Number below zero, choose Decrease rather than entering a negative amount.

Values always stay within the range allowed by their type. Increasing Percent 95 by 10 produces 100. Decreasing Age 20 by 5 produces 18.

Limits apply after every row, not only after the final result. Percent 95 followed by Increase 10 and Decrease 10 ends at 90: the first row stops at 100, then the second subtracts 10.

Setting a value to 0, setting Yes/No to No, or setting Text to an empty value is different from Remove. Those values still exist and can be compared or displayed. Remove makes the value missing.

Show, Hide, and Keep

Each change can also decide whether the value is visible to the reader:

• Show allows it to appear in its normal Game State section; inventory rules still apply.
• Hide keeps it out of the ordinary reader view.
• Keep leaves its visibility as it is.

For a new value, Keep leaves it visible. While the value continues to exist, the last Show or Hide decides its visibility. Remove discards that visibility, so a later recreation starts visible and Keep preserves the new visible state. Inventory also requires Inventory → Show and an owned value: Yes, a number above 0, or non-empty Text/Dropdown.

Visibility affects the normal Game State and inventory displays only. If chapter text explicitly includes {game:secret}, {stat game:secret}, or {meter game:secret}, that output can still reveal the hidden value.

Authors and editors can expand Hidden variables while previewing a story. This helps test secret values without revealing them to ordinary readers.

Keep each name with one type

Use one type for each game-variable name throughout the story. If score is a Number, do not use it as a Percent or Yes/No value elsewhere. The Story variables page helps authors find where each variable is used.

Reader variables and game variables remain separate. Chapter condition rows use game values; a reader variable cannot directly open or close a path.

Entering, reloading, and going Back

Entry changes run when the reader advances into a chapter. Reloading the current chapter does not apply them again. Going Back restores a recent earlier saved state; advancing into the chapter again applies its changes again.

CHYOA retains at most ten recent game-state snapshots, including the current one. Back can therefore reach at most nine earlier snapshots. Rolls, reveals, actions, and Link chapters can add snapshots without representing separate chapters, so it may reach fewer earlier chapters than expected. Test long game paths without assuming that every earlier state can be restored.

When a fresh or reset game opens the first chapter, story-defined initial values are applied first and the first chapter's changes run afterward. Existing games keep their saved values until later changes or a reset.

Test both routes

Before publishing:

1. start at the story's first chapter with a fresh game;
2. try values that should pass and values that should fail;
3. check the result with Show inaccessible chapters both enabled and disabled;
4. confirm that chapter changes appear in the text, Game State, inventory, and later choices;
5. go back to an earlier chapter and make sure restored values open the expected path.

Related Guide chapters

• Reader and Game Variables
• Conditional Text with If Statements
• Showing Reader and Game Values
• Random Values, Rolls, Reveals, and Actions