Event types

Events are the unit of authored behavior in StoryBonsai. They live on nodes (the Events list), on scenes through their lifecycle nodes (Intro, Update, Outro, On leave, On exhausted), and inside skill checks (the Success events, Failure events, Critical success events, and Critical fail events branches). When the runtime traverses a node, its events fire in the order they appear in the inspector.

The pages in this section document each event type: the fields a writer authors and the runtime behavior those fields drive.

Base properties

These properties exist on every event regardless of type. Per-event pages do not re-document them.

Condition

An expression that gates whether the event fires. Set this on the event in the inspector when you want the event to run conditionally; leave empty for events that always fire. The runtime evaluates the expression at fire time and runs the event only if the result is truthy.

Example: var_alarm_raised && !Played(node_warning).

See Expressions for the syntax.

Timing

Optional structured timing for the event. Most events fire immediately when the node activates; setting Timing in the timeline editor lets you delay events or trigger them at specific cues (after a media’s duration elapses, at a media’s story beat, or after a fixed offset).

All event types

Each entry below uses the label the editor’s event picker shows.

Mutation

Set Variable: assign an expression result to a variable.
Set Variable (Text): assign a templated string to a text variable.
Set Time Bucket: jump the world clock forward to a named time bucket.

Flow

Jump: move to another node, with optional return semantics.
Start Scene: activate a target scene, optionally modally.
Complete Scene: close the active scene.
Complete Project: mark the project complete.

Dialogue & media

Dialogue: line of spoken / on-screen text from a character.
Play Sequence: play a video or image sequence with captions.
Audio Cue: start an audio cue.
Stop Audio: stop audio on a layer.

World

Move To Location: relocate the player to a location.
Advance Time: advance the world clock by a number of minutes.

RPG

Skill Check: author a skill challenge with branching outcomes.
Unlock Codex: unlock a codex entry.
Activity: start a long-form activity with optional variable overrides.

Integration

Hook: fire a named hook back to the integrating studio.