Encounters

An encounter is a scene staged at a location. While the player is there, the host shows the scene as something they can click: talk to that NPC, read that poster, examine that item. Encounters are the seam between the world layer (where the player is) and the narrative layer (what happens when they pick something), and they let those two move independently.

What’s not here: scene concepts and visit-state mechanics (Scenes and visit state), the full field-by-field reference for the Scene entity (Scene reference), and the same for Locations (Location reference).

The two-place shape

Every encounter is authored in two places at once: the location lists which scenes are staged there (in its Encounters section), and the scene declares what the player engages with in the world to enter it (its Trigger). Each row on the location has its own Encounter visible when gate, a single expression that controls every entry in the row, whether that row produces one affordance or several.

The Encounters section on a Location inspector, with two encounter rows and their per-row Encounter visible when fields.

Trigger styles: scene-level vs node-level

A scene can act as an encounter trigger in one of two ways.

Scene-level trigger. The scene’s own Trigger kind field sets what the player engages with: a specific character, a specific item, or the scene itself (self). Every encounter row this scene appears in produces one plain entry: one affordance in the world per row.

Node-level triggers. Individual nodes inside the scene carry a Trigger on their own trigger field. Each triggering node produces one fan-out entry per encounter row: a scene with three trigger nodes appears at a location as three separate affordances that all share the same Encounter visible when gate.

The scenes sidebar marks any scene that functions as an encounter trigger (either style) with a ◆ badge, so you can spot the encounter triggers at a glance.

Mutual exclusion. A scene uses one style or the other, never both. The editor prevents you from configuring both at once: if the scene already has a scene-level trigger, the NodeInspector’s Encounter section renders an info panel with an Open scene → jump-to instead of the trigger picker; if any node inside the scene already has a trigger, the SceneInspector renders a matching info panel in place of its Trigger kind dropdown.

NodeInspector's Encounter section rendered as a mutual-exclusion info panel with an Open scene jump-to.

If a project’s JSON somehow carries both a scene-level trigger and node triggers (usually via a merge conflict or hand-edit), the encounter_style_conflict validator warning fires against the scene. The runtime still emits both (plain entry from the scene, fan-out entries from the nodes), but the authoring surface treats it as a mistake worth flagging. See Error messages → 9.7.

Add an encounter

Three entry paths, one shared result: the scene appears as an encounter row on the chosen location.

From the location. Open the location inspector, click Add encounter in the Encounters section, and pick a scene.
From the scene. Open the scene inspector, expand the Encounter at section, click Add as Encounter, and pick a location.
From a node. Open a node inspector, expand the Encounter section, click Add scene as encounter, and pick a location. The whole owning scene gets added as an encounter at that location. The node picker is for triggering within the scene, not for adding half a scene.

If the owning scene already has a scene-level trigger, the NodeInspector’s Encounter section renders the info panel from §Trigger styles rather than the trigger picker; the same shape appears on the SceneInspector when any node inside carries a trigger.

NodeInspector Encounter section showing the full form: Trigger kind dropdown, entity picker, Encounter at derived list, and the Add scene as encounter button.

Once added, the location card renders one row per encounter, with a Triggers sub-list for fan-out entries:

LocationInspector card for a scene whose nodes carry triggers, showing the scene title, Triggers subheading, one fan-out row, and the Encounter visible when field with the shared-gate hint.

Mark an encounter as exhausted

A common pattern: a scene plays once and then disappears from the world. Set the scene’s Resolved when expression to the condition that means “done”, and turn on Hide when resolved. The runtime hides the encounter from the host the moment Resolved when evaluates true.

Scene inspector cropped to the Visibility section, showing Resolved when populated with a Played() call and Hide when resolved set to true.

Resolved when: the expression that means “done.”
Hide when resolved: whether resolving also hides the encounter.

The canonical example is a greeting that should play once: set Resolved when to Played(node_anne_intro) (the scene’s intro node) and Hide when resolved to true. Once the intro node has played, the encounter stops appearing.

Hide when resolved is a three-state dropdown (inherit, true, false). inherit defers to a project-wide default (which itself defaults to true), so setting Resolved when alone is usually enough. The example sets it to true explicitly to make the relationship visible in the inspector. See Scenes and visit state for the visit-state functions (Played, Selected, Visits) the Resolved when expression can use.

Make an encounter unskippable

Set the scene’s Modal field to true. While a modal encounter is running, the player cannot leave mid-scene; the host won’t render a Leave affordance. Like Hide when resolved, Modal is a three-state dropdown (inherit, true, false) that defers to a project-wide default when left as inherit. Reach for it when leaving partway through would break the narrative: a one-line greeting is fine non-modal; an interrogation should be modal.