Node

A node is the unit you author choices and events on. Nodes belong to scenes, get gated by their Visible when expression, and fire a list of events when selected. The Node Graph in the editor IS the nodes-and-events view. The fields below are grouped to mirror the inspector.

For conventions shared by all entity types, see Entities.

Node inspector for Node B, posed on the Node Graph with the node selected, showing the Identity, Visibility, Behavior, Choice group, Events, and Tests sections. — The Node inspector, opened from the Node Graph with the node selected.

Identity fields

ID

The node’s expression-namespace identifier. You’ll use this in expressions that reference the node (Played(node_intro), Selected(node_id)). Renaming ID updates expressions that mention the old name; it does not break the node’s binding to its owning scene or any events that reference it.

Convention: node ids are prefixed node_. Existing nodes aren’t renamed when the prefix convention shifts; consistency is enforced at create-time only.

Title

Optional human-readable label shown on the Node Graph card and in the simulator UI. Free-form string, author-typed. If left empty the node renders as a plain card with no label. Useful for flow and system nodes that the player shouldn’t try to interpret.

Description

Optional author-facing prose explaining what the node is for. Surfaces in the editor’s node inspector as a detail row. No runtime effect.

Color

Optional color swatch used as an accent on the node’s card in the Node Graph. The inspector offers eight preset swatches (red, orange, yellow, green, teal, blue, purple, pink) plus None. Free-form color values aren’t supported; pick a swatch or leave the accent off.

Character

Only shown in multiplayer projects. Assigns choice ownership to a character: when this node appears in the visible set, only the assigned player can pick it. Hidden in single-player projects because every choice implicitly belongs to the one player. This field does NOT set the speaker for the node’s dialogue; caption entries on Play sequence events carry their own speakers.

Scene membership

Scene

Every node belongs to exactly one scene. Membership is set by placing the node inside a scene’s boundary on the Node Graph: drag a node into a scene to add it, drag it out (or into a different scene) to move it. The owning scene’s active state implicitly gates the node; a node is only visible when its scene is active, regardless of Visible when.

Visibility field

Visible when

Optional gating expression. When set and evaluating true, the node is included in the current visible set and can surface as a choice. When set and evaluating false, the node is hidden from the visible set. When empty, the node is treated as hidden by default; it’s only reachable via jump events. The standard pattern for flow and system nodes (intros, outros, exhausted lifecycle nodes) that the player should never select directly.

Behavior fields

Repeatable

Controls whether the node can be selected multiple times. Three values:

Once per run (default): the node is consumed after its first selection and never reappears in the visible set for the remainder of the run.
Once per visit: the node resets when its owning scene re-activates. The player can select it again after leaving and re-entering the scene.
Always: the node is never consumed. It stays in the visible set regardless of how many times the player selects it.

Most choice nodes use Once per run. Nodes that should re-appear on every scene visit use Once per visit. Always is rare and typically reserved for meta-nodes (e.g. a back button) that the player needs access to until the scene completes.

Priority

Marks a node as the default choice for timeout fallback. When the host presents a timed choice and the timer runs out without a selection, the highest-priority visible node is selected automatically. Ties: if multiple visible nodes share the highest priority, the runtime marks each of them as default and hands that flag to the host, which decides which one to fire. A visible set where every node’s Priority is 0 has no default, and a timed choice with no default runs to end-of-timer with no auto-selection.

Priority does NOT influence the display order of choices; that is Order alone.

Order

Integer sort key among sibling nodes in the visible set. Nodes with lower Order values appear first. Order is the sole sort input; there is no Priority-based tiebreak.

Timeout

Optional time-in-seconds limit specific to this node. When set, the runtime treats the node as “out of time” once the budget is exceeded; the exact effect depends on the host’s timeout handling. Inherits from the scene’s Timeout if left empty; inherits from the project’s default if the scene also leaves it empty.

Exclusive selection

Three-state inheritance flag controlling whether THIS node is consumed (dropped from the visible set) when a sibling choice is selected. Values: inherit (default), true, or false. When resolved true and a sibling is picked, this node is consumed and never returns in the current cycle (classic Telltale-style single-choice progression). When resolved false, this node survives a sibling selection and stays available. Resolves via Node → Scene → Project: the node’s own setting wins, then the owning scene’s setting, then the project default.

Undo barrier

Checkbox. When set, the runtime trims the undo stack when this node is selected: the player cannot rewind past this node once the choice has been committed. Use for moments the player should not be able to walk back from (a promise made, a door closed, a body found). Off by default.

Loading a saved game replays the run from the start, and the replay rebuilds the undo history, barriers included. After a load, undo stops at the same barrier it stopped at before the save.

Choice group field

Choice group

Optional choice group. Pick from the editor’s choice group picker. Sibling nodes that share the same Choice group collapse into a single synthesized topic choice when the runtime presents the visible set. Selecting the topic expands the group’s children so the player can pick one. Leave empty for nodes that present as standalone choices.

Events field

Events

List of authored events fired when the node is selected (or when it auto-fires for lifecycle nodes like intros and outros). Each event carries a type (Set Variable, Play Sequence, Start Scene, and many more) and a set of type-specific fields. The primary mechanism for changing state, advancing the story, and triggering host-side effects. The per-event pages document each event type’s fields and semantics.

Localization

Translator notes

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

When to reach for nodes

A node is the atomic unit the runtime presents: a beat, a choice, a flow point, an outro. Every step the player takes (or that the runtime auto-fires) is a node selection, and every list of events the runtime executes belongs to one. Reach for a new node any time you need a new presentable step, a new branch point, or a new place to hang events; reach for a new event INSIDE an existing node when the change is to what happens during a step rather than adding a step.

Nodes split into two informal kinds writers reach for differently. Content nodes are what the player sees: they have a Visible when expression so the runtime can include them in the visible set as choices. Logic nodes are the runtime’s plumbing: they leave Visible when empty (so the runtime never offers them as choices), get titles that mark them as system steps, and are only reached by jump events from elsewhere. The same field set serves both kinds; the difference is in what you fill in.