Location

A location is a spatial entity on the world layer. Spatial state (current location) and narrative state (current scene) are orthogonal axes: a player has a current location (where they physically are) and a current scene (what narrative state they’re in), and the two don’t have to move in lockstep. Locations form a spatial graph via connectsTo; scenes surface as encounter affordances on locations via pinnedScenes.

For conventions shared by all entity types, see Entities.

Location inspector for Side Street showing the display name with its translator note, one Main Street connection, and four encounters. — The Location inspector, opened from the Locations tab of the Data View.

Fields

ID

The location’s expression-namespace identifier. You’ll use this name in Move to events that relocate the player, in Connections destination references, and in expressions that reference the location. Renaming ID updates events and expressions that mention the old name; it does not break the location’s binding to events.

Convention: location ids are prefixed location_.

Display name

The human-readable label shown in the editor’s location picker, on the World Graph, and in any host UI that displays the player’s current location. Free-form string, author-typed.

Description

Optional author-facing prose explaining what the location is for or what the player sees there. Surfaces in the editor’s location inspector as a detail row. Has no runtime effect.

Ambiences

A list of named audio bundles the host can layer or cross-fade based on the player’s current location. Each ambience entry carries an Id (the expression handle), a Name (display label), and a list of Audio cue ids pointing to the audio cues to play together as a group. Multiple ambiences let writers define alternate audio sets for the same location; the host can cross-fade between them when a Move to event carries an Ambience id override. Leave empty for locations with no ambient audio.

Connections

A list of outgoing Connections: the routes the player can traverse from this location to reach other locations. Each connection entry carries a To field (the destination location’s id) and an optional Visible when expression that gates whether the connection is traversable. The destination is resolved by the target location’s id. Leave empty for dead-end locations.

Encounters

A list of scenes that surface as encounter affordances on this location: the interactable narrative content the player can access while at this location. Each encounter entry carries a Scene (the scene’s id) and an optional Visible when expression that gates whether the encounter shows. The host’s GetEncounters call reads this list to know what’s available at the player’s current location. Leave empty for locations with no encounter content.

On enter events

A list of authored events that fire when the player enters this location. Common uses: a Move to to place the player at a specific node, a Play sequence to trigger location-specific audio, a Set variable to track location visits. Per-event semantics live on the event types pages. Leave empty for locations with no entry logic.

On exit events

A list of authored events that fire when the player leaves this location. Common uses: stopping a location-specific audio cue, setting a variable to track that the player departed, firing a Set variable to update state for save/restore. Per-event semantics live on the event types pages. Leave empty for locations with no exit logic.

Translator notes

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

When to reach for locations

A location is the right shape when the world has a meaningful “where” the player can occupy and that “where” gates content. The location graph is independent of the narrative graph: a player has a current location AND a current scene, and the two move on their own axes. Reach for locations whenever the same set of scenes should surface differently depending on where the player physically is, or whenever connections between places matter to the gameplay (you can walk from A to B but not from A to C until something changes).

The player moves between locations with the move-to event; each location’s Encounters decide which scenes surface in GetEncounters while the player is there. Connections gate which destinations are reachable through per-connection visibility expressions, and Ambiences let the host layer or cross-fade audio bundles as the player crosses thresholds. For surfaces that have no spatial meaning (a UI panel, a menu state), use a scene instead; locations are for the physical layer only.