Scene

A scene is the unified state-machine entity: the unit of “where am I in the story right now.” Scenes nest into a tree, can be entered programmatically or surfaced as encounters on a location, run intro / update / outro lifecycle nodes, and gate every choice underneath them. The fields below are grouped to mirror the inspector.

For conventions shared by all entity types, see Entities.

Scene inspector for scene_anne_chat, showing identity, hierarchy, trigger, modality, resolved-when, lifecycle, and transition fields populated. — The Scene inspector, opened from the Scenes tab of the Data View.

Identity & display fields

ID

The scene’s expression-namespace identifier. You’ll use this in expressions that reference the scene (Resolved(scene_id), Completed(scene_id), Visits(scene_id)). Renaming ID updates expressions automatically; it doesn’t break the scene’s parent / child references on other scenes.

Convention: scene ids are prefixed scene_.

Display name

The human-readable name shown in the editor’s scenes table, on the Node Graph breadcrumb, and in the simulator UI. Free-form string.

Description

Optional author-facing prose explaining what the scene is for. Surfaces in the editor’s scene inspector as a hover-tip when scanning the scenes list. No runtime effect.

Hierarchy fields

Parent scene

Optional parent scene. Pick from the editor’s scene picker. Defines the scene tree: children inherit from their parent’s inherit-flagged settings, and the parent’s active state cascades into children flagged Activates with parent. Leave empty for root scenes.

Activates with parent

When true (and Parent scene is set), the scene activates automatically whenever its parent becomes active, at run start, or when the parent is entered via Start Scene. The intro fires as if the scene had been entered explicitly. The editor hides this control on root scenes where it has no effect.

Visibility & order fields

Visible when

Gating expression. The scene is enterable only when this expression evaluates true at scene-push time. New scenes default to true (always enterable); an empty value hides the scene, matching node visibility semantics. Distinct from Resolved when, which gates whether the scene’s encounter affordance is shown after the player has resolved it.

Order

Integer used for UI sort order in the scenes table and as the primary key for scene-exhaustion iteration. When multiple scenes go empty in the same choice cycle, the one with the lowest Order fires its On exhausted first.

Lifecycle fields

Intro

Optional node. Pick from the editor’s node picker. The scene runs this once when it activates. Common uses: an opening dialogue, a scene-setting Play Sequence. The intro fires before any of the scene’s body nodes become available. Leave empty for scenes that should activate silently.

Update

Optional node that fires every time the player’s choice-cycle ticks inside the scene. Useful for state machines that need to re-evaluate after each choice. The update node is typically Visible when set to false so it doesn’t show as a choice. Leave empty if no per-tick logic is needed.

Outro

Optional node that fires when the scene completes, typically via a Complete Scene event in the scene’s content, or when the scene’s visible-node set goes empty and On exhausted chains to a Complete Scene event. Counterpart to Intro.

On leave

Optional node that fires when the player backs out of the scene without completing it (non-modal scenes only). Distinct from Outro: “leave” means “I’m walking away, I’ll be back,” while the outro means “this scene is done.” Leave empty for a silent pop.

On exhausted

Optional node that fires when the scene’s visible-node set goes empty (no remaining choices). Common content: a Start Scene event to chain into the next scene, a Complete Scene to end the current one, or a Complete Project to end the run. The node must belong to this scene and should have Visible when set to false so it never surfaces as a choice itself.

Authoring footgun: a scene whose only nodes come from cascade-activated children (no body nodes of its own) exhausts on start; the On exhausted node fires immediately. If you want a scene to act as a pure container, give it at least one always-visible body node.

Transition fields

Timeout (seconds)

Optional time-in-seconds limit for the scene as a whole. When set, the runtime treats the scene as “out of time” once the budget is exceeded; the exact effect depends on the host’s timeout handling. Inherits from the project’s default if left empty.

Close on transition

Three-state inheritance flag controlling whether this scene closes (running its outro) when the player transitions out of it into another scene. Values: inherit (default), true, or false. Resolves via Scene → Project: the scene’s own setting wins, then the project default. There is no per-event override; a Start Scene event always defers to the source scene’s setting.

Exclusive selection

Three-state inheritance flag providing the scene-level default for whether nodes in this scene are consumed (dropped from the visible set) when a sibling choice is selected. Values: inherit (default), true, or false. Resolves per unpicked node via Node → Scene → Project: each node’s own setting wins, then this scene’s setting, then the project default. See Node → Exclusive selection for the per-node semantics.

Encounter fields

Trigger kind

What the player engages with in the world to enter this scene, once the scene is staged as an encounter at a location. A dropdown with four values:

(none) (default): the scene never surfaces as an encounter. You can only enter it with a Start Scene event (cutscene-style).
character: the player engages with a specific character. A Trigger character picker appears for choosing which one.
item: the player engages with a specific item. A Trigger item picker appears for choosing which one.
self: the scene is its own clickable feature at the location, with no character or item attached.

The trigger only says what kind of thing the encounter is; where it appears, and when, is set on the location. Each location lists the scenes staged there in its Encounters section, and each entry carries its own Visible at this location when expression. See Encounters for the full authoring flow.

Staged at

A read-only list of the locations that stage this scene as an encounter. Click a location to open it in the inspector. The Add as Encounter button stages the scene at another location; this is the same data you would edit from the location’s Encounters section, viewed from the scene’s side.

Three-state flag controlling whether the scene is modal. Modal scenes take over the UI exclusively until they complete; the player can’t back out or pop to a parent. Values: inherit (default), true, or false. Resolved when the scene activates: a Start Scene event’s Modal override wins, then this setting, then the project’s default modal setting.

Hide when resolved

Three-state flag controlling whether the scene’s encounter hides from its locations once Resolved when latches true. Values: inherit (default), true, or false; inherit defers to the project-wide default. Has no effect on programmatic entry; only on where the scene is staged as an encounter.

Resolved when

Optional expression that returns true or false. Exposed to other expressions via the Resolved(scene_id) function, and checked whenever the world surfaces this scene’s encounter so the encounter can hide once the expression latches true (gated by Hide when resolved). Leave empty for scenes that don’t have a “this is finished now” state.

Variable imports

List of cross-scene variable visibility entries: each one declares “this scene needs read or read-write access to a variable owned by another scene.” Used when a scene-scoped variable from scene A needs to be visible to scene B. Leave empty for scenes that only read world-scoped variables and their own scene-scoped ones.

Localization fields

Translator notes

Display name can carry a translator note: see Entities for more information.

When to reach for scenes

A scene is the unified state-machine entity, the unit of “where am I in the story right now.” Scenes nest, gate every node underneath them, and can be entered programmatically or surfaced as encounter affordances on a location. Reach for a new scene when the player needs to move between distinct narrative states (a chapter, a flashback, a conversation arc, a UI panel) and you want the runtime to track entry, exhaustion, and exit on it.

Scenes do a lot of work for one entity. Nodes belong to scenes and are only offered while their owning scene is active; lifecycle fields (Intro, Update, Outro, On leave, On exhausted) let the scene react to its own boundary events without scattering jumps; encounter fields (Trigger kind, Resolved when, Variable imports) let the scene surface as an encounter at a location. See scenes and visit state for the full lifecycle contract.