Scenes and visit state

A scene is the activation unit in StoryBonsai. It groups a set of nodes; while the scene is active, those nodes are eligible to be visible. While the scene is inactive, none of its nodes can show up, no matter what their Visible when says.

For the full inspector field tour and per-scene authoring patterns, see Scenes.

Scenes are the activation unit

Every scene has a hidden flag the runtime tracks: whether the scene is currently active. Only nodes inside an active scene get their Visible when condition evaluated. When you enter a scene, its flag flips on. When you leave, it flips off. The Node Graph draws a labeled box around the scene’s nodes so you can see the boundary while you’re working.

Every row in the scenes sidebar has two independent controls. The checkbox on the left toggles whether the scene’s nodes are visible in the Node Graph. The row highlight (bold green text, on (3) above) marks the active scene. (1) is disabled, (2) is visible but inactive, (3) is visible and active. The active state is mostly used by the path tester and simulator to pick a starting scope; in the Node Graph you can have many scenes visible at once.

Every scene draws a labeled box around the nodes it owns. The box is what the runtime gates on: only nodes inside an active scene’s box can show up as choices.

Per-visit history vs whole-run history

When the player picks a visible node, that node’s events run in the order you wrote them. Events mutate variables, advance time, open or close audio scopes for the engine to handle, jump to other nodes, or any of the other things events do. The picked node is also recorded twice in the player’s history: as Selected (the player chose it) and as Played (it ran).

The distinction matters because not every node that plays is selected. If a visible choice node has a jump event targeting a hidden logic node, that logic node runs (it is Played) but the player never picked it (it is not Selected). Use Selected when you mean “the player made this decision,” and Played when you mean “this ran at all.”

Both of these are scoped to the current visit of the scene the node belongs to. Every time a scene activates, the runtime opens a fresh visit and the visit-state counters reset. So Played(node_id) answers “has this node played during the visit I’m in right now?” If the scene deactivates and re-activates later, Played reads false again at the start of the new visit; the slate is clean. There are also PlayedEver, SelectedEver, and SeenEver variants that look across the whole run rather than the current visit, for when you need the broader question.

Lifecycle nodes

A scene has four slots that point at nodes to fire at specific points in its lifecycle.

The numbered call-outs (1, 2, 3) mark the three core slots: Intro, Update, Outro. The two slots below (On leave and On exhausted) are extras covered briefly at the end of this section.

• (1) Intro fires once, when the scene activates. Use it to set the situation, introduce the characters who are present, or seed variables that depend on the scene’s context.
• (2) Update fires after every selection inside the scene, before the choices are re-evaluated. Use it to advance a clock, tick a counter, or recompute state that depends on what just happened.
• (3) Outro fires once, when the scene closes. Two paths take it there: another scene activates and the runtime closes this one in the transition, or a Complete scene event runs here. It does not fire when the player backs out via the Leave affordance; that path is handled by On leave below instead. Use Outro for closing mutations: marking the scene as resolved, writing back any state the rest of the project depends on.

A node wired into a lifecycle slot doesn’t need a Visible when condition. The slot fires it; the player never sees it as a choice. Use the lifecycle slots for the work the player shouldn’t pick; use ordinary visible nodes for the work the player does pick.

Two more advanced slots exist on the inspector: On leave (fires when the player backs out of a non-modal scene via the Leave affordance) and On exhausted (fires when the scene’s visible set goes empty). They follow the same pattern as the three above; see Scenes for how to wire them up.

See also

• Nodes and Visibility: the rule that decides which nodes inside an active scene actually show up as choices.
• Expressions: the grammar for writing conditions like Played and Selected that this page leans on.
• Scenes: the entity-shaped view, covering every field on the inspector, modal vs inline, encounter triggers, and the full field reference.
• Encounters: scenes that start from a Trigger; the workflow for surfacing one in the simulator and resolving it.
• Common pitfalls: My scene has no visible choices: what the choice panel shows when the intro is unset or every node’s condition is false.
• Common pitfalls: My scene’s intro keeps re-firing: why Played resets across re-activations and when to reach for the Ever variants.
• Error messages: Scenes: panel messages the runtime surfaces for scene structural issues, including missing entry scenes, dangling lifecycle-slot references, and teardown re-entry.