Evaluation cycle

Every time the player picks a choice, StoryBonsai runs the same short sequence of steps. The picked node’s events fire, the runtime adjusts state, and the new set of visible choices is presented. Knowing what runs when (and what’s already finished by the time the next visible set appears) is how you reason about why a choice did or did not surface.

Selecting a node runs its events

When the player picks a visible node, that node’s events run in the order you wrote them. The picked node is recorded in the player’s history twice: as Selected (the player chose it) and as Played (it ran). For what the split means in practice, and why both reset when a scene visit restarts, see Scenes and visit state.

The cycle in order

Once a choice is picked, the runtime walks the following steps before it asks the player for anything else.

1. Mutation phase. The picked node’s events fire top to bottom. Variables are updated; jumps to other nodes execute their events too; Start Scene activates a target scene (and runs that scene’s Intro); Complete Scene flags the current scene for closure (its Outro runs in step 4). Everything that the events declare to happen, happens now.
2. Exclusive selection. For each unpicked sibling, the runtime resolves that sibling’s own Exclusive selection (node, then its scene, then the project; the first explicit value wins). Any sibling that resolves to on is marked consumed: it won’t reappear as a choice for the rest of the scene’s visit. Consumption is separate from play history: Played(sibling) still reads 0 for a consumed sibling, because the node was hidden without ever running. Because the check is per sibling, a single sibling with Exclusive selection set to false explicitly can opt out of the sweep even when everything around it clears out.
3. Scene update. The active scene fires its Update node if one is wired up. Use Update for clocks, counters, or any per-cycle bookkeeping.
4. Scene and project close. If the mutation phase (or the Update pass) fired a Complete scene, the closing scene’s Outro runs here. If a Complete project fired, the project ends after that.
5. Re-evaluation. Every node whose Visible when could have been affected by the mutations so far is re-checked. New visible nodes appear; nodes that just lost their condition disappear.
6. Scene exhaustion. If the visible set is now empty and the active scene has an On exhausted node, that node fires. Its events can queue more work and the cycle iterates.
7. Presentation. The player sees the new visible set as the next choices.

The first shot below shows the moment before a click; the second shows the state the runtime arrives at once the cycle has finished.

1. First choice. Offer the deal.
2. Second choice. Speak plainly.
3. Third choice. Stay silent.

Before the click. Three nodes, all visible. The simulator is paused for input.

1. Picked node’s dialogue. The Dialogue event on the picked node ran first and pushed “I won’t lie to you about it.” into the transcript.
2. Set variable. The picked node’s next event was a Set variable that advanced var_doc_trust from 0 to 5.
3. Jump. The picked node’s third and last event was a Jump into the hidden Aftermath node, which carried the mutation phase forward into another node’s events.
4. Aftermath dialogue. Aftermath ran its own Dialogue event, pushing “And that’s all I’ll say for now.” into the transcript.

All four events happened in a single mutation phase, triggered by one click. The shot above is the simulator with the Debug toggle on, so non-dialogue events (here: Set variable and Jump) appear inline next to the dialogue lines they ran alongside; off, the timeline shows just the dialogue. The choice panel below the timeline is empty because Exclusive selection consumed the two unpicked siblings and re-evaluation found no new visible nodes. Project complete appears once the scene’s On exhausted node fires.

Exclusive selection

By default at the project level, Exclusive selection is off. When it’s off, the player picks one choice, its events run, and the unpicked siblings stay in the visible pool. The player can pick another, and another, like ticking a checklist. When Exclusive selection is on, the unpicked siblings are consumed alongside the picked one: this OR that OR the other, then move on.

Exclusive selection changes whether the unpicked siblings are consumed alongside the picked one. The picked node still runs, still records, and still gets removed under its own Repeatable rule. What you’re toggling is the fate of everything next to it.

The scene in the shots above has Exclusive selection set to true at the scene level explicitly. That’s why one click cleared the panel.

Where to set it

Exclusive selection lives at three levels, and the runtime walks them in order: node, then scene, then project. The first explicit value wins. If the node says inherit, the runtime looks at the node’s scene; if the scene says inherit, the runtime falls back to the project setting; if the project setting was never touched, the answer is off (the default for new projects).

The base is the Project Settings panel. Open it from the Project menu; its Defaults section has the Exclusive selection checkbox. That’s the value everything inherits when nothing more specific is set.

Any scene can override the project default in its inspector. The picker has three states: inherit, true, false. Inherit means “use whatever my parent has set”; true and false are explicit. Nodes follow the same shape in their own inspector, one step further down.

The Scene Inspector’s Transitions section. This scene has Exclusive selection set to false explicitly, so its choices stay in the pool even after one is picked.

The override chain is useful when most of the project wants the default behavior but one scene has a “tick all the boxes” rhythm, or a node needs to be the one stubborn exception.

See also

• Nodes and Visibility: the rule that decides which nodes count as choices in the first place; the rule the cycle’s re-evaluation step re-applies.
• Scenes and visit state: when the lifecycle nodes (Intro, Update, Outro) fire relative to the cycle; the per-visit history that Played and Selected track.
• State: why the cycle’s re-evaluation step is cheap; only conditions whose variables changed are re-checked.
• Expressions: the grammar for the conditions the cycle re-evaluates.
• Common pitfalls: My other choices vanish after I pick one: when Exclusive selection consumes siblings the writer expected to keep.