Events

An Entity filter never matches OnStart (no payload). Seed every variable your expression filters will read (they fail closed on unset variables), and post the first objective here.

Its spawns arrive over the next few frames, and the scenario is HELD until they have: no other handler runs, the scenario clock does not tick, and the LOADING panel stays up. So the first OnUpdate after OnStart already sees every object OnStart asked for - a count gate cannot read a half-built world.

The chain order is guaranteed: the scenario clock ticks, typed queries and watches update, ended timers fire, then OnUpdate fires. Query-backed gates see one coherent frame snapshot.

This is the workhorse for clock-driven beats and count thresholds that must not depend on handler order. Gate it with Expression filters, and add once: true when the beat happens one time - then the only filter left is the one about the game:

(
    name: OnUpdate,
    once: true,
    filters: [
        Expression((GreaterThan(
            Term(Factor(Name("scenario_elapsed"))),
            Term(Factor(Literal(Number(10.0)))),
        ))),
    ],
    actions: [
        NarrativeCue((
            speaker: "Control",
            text: "Ten seconds elapsed.",
        )),
    ],
),

A beat that genuinely repeats leaves once off and re-arms itself in its own actions - see the recipes.

Timer-end events queue before that frame's OnUpdate pulse.

Start or restart the delay with TimerStart. Cancel it with TimerCancel. Timers use live, unpaused scenario time and clear on retry or teardown.

OnCinematicFinished fires on EVERY way out of the scene - its last beat ran, the player skipped it, a CancelCinematic stopped it, or one of its steps blew its deadline. Author the post-state there, once, and no path can forget it.

OnCinematicSkipped fires FIRST on a skip, immediately before that scene's OnCinematicFinished. It carries only the catch-up: the actors the unplayed beats would have spawned, moved or destroyed, and the variables they would have latched. It is not a second copy of the scene - a skip means the player asked not to watch, so nothing presentational belongs here.

Always filter by key. A scenario with two scenes and an unfiltered handler answers whichever one ends first. A Cinematic filter naming a key no scene plays is a lint Error, so a typo costs the whole scenario, not one handler.

An order that is REFUSED when it is issued - a dangling ship id, a player's ship, an empty patrol route, an impossible tolerance - fires nothing at all. It was never installed, so there is nothing to report on. The lint catches each of those before the scenario runs.

A key is reusable: give the same order again and the lifecycle runs again.

What "reached" means is per order:

• MoveShipTo and StopShip complete when the ship's autopilot lets go - inside the standoff, or at rest.
• ForceAlign completes when the aim is inside its authored tolerance and steady there.
• PatrolShip completes at the END of its one loop, back where it started - not at each waypoint.
• OrbitShip completes when the ring is ESTABLISHED, and then keeps holding it.

Completion says the CONDITION was met, not that the behavior stopped. Move, Stop and Patrol release the helm as they report; Align and Orbit keep holding until something else takes it.

The order is NOT lost. It is parked: the ship keeps the key, the kind and its place in the route, the AI takes the helm back and fights, and when the signal clears the same order picks up from where it stopped - see OnShipOrderResumed.

A beat gated on the COMPLETION still waits, correctly: an interrupted patrol has not swept the belt yet.

Pairs one-for-one with OnShipOrderInterrupted, and can pair with it several times over one order's life. The resumed order flies its OWN directive, from the leg it was on - not a fresh copy from the top.

Cancellation is not completion, and a beat gated on the completion correctly never runs. This is the event for the OTHER side of that: cleaning up a readout, or telling the player the approach was called off.

An order that had already reported a terminal outcome says nothing more, so clearing a ship that is holding a finished ForceAlign is silent - the align already completed.

This is the event that keeps a Sequence gate from waiting forever on a beat that can never land. A wreck does not arrive.

It reports the ORDER, not the ship: a hull that is destroyed outright is OnDestroyed and OnDefeated, which is what a kill objective should be waiting on. Failure is for the ship that is still there and can no longer do the job.

Weapon actions have no lifecycle at all - what a shot produces is the weapon's own event chain.

Ordering is fixed:

• Neutralization: OnDefeated, then OnNeutralized.
• Direct ship destruction: OnDefeated, then OnDestroyed.
• Later destruction of an already-neutralized wreck: OnDestroyed only.

Scripted despawn, scenario teardown, and boundary cleanup fire none of these edges.

Type names are the object-kind constants: "anchor", "asteroid", "planet", "spaceship", "beacon", "light" - see Scenario objects.

A brain-dead ship cannot aim or fly, whatever else survives; thrusters play no part in the rule. The ship is NOT despawned, so no OnDestroyed fires with it. A ship that never had a computer (a bare emplacement) only neutralizes by losing its guns.

Use OnNeutralized only when the persistent-wreck distinction matters. Use OnDefeated for the shared combat outcome.

Two things produce trigger areas: the CreateScenarioArea action and a Beacon with area_radius set. Both report under their own id. Entering an area moves no cargo.

Or accept any spaceship that enters that area by filtering the other party's type:

(
    name: OnEnter,
    filters: [
        Entity((
            id: Some("repair_zone"),
            other_type_name: Some("spaceship"),
        )),
    ],
    actions: [ /* a ship entered */ ],
),

Notes:

• The entering body must itself be a scenario object (carry an id and type name) to be reported.
• An area created AROUND a body already inside it still fires OnEnter - the fresh overlapping pair counts as an entry. So arming a zone late, or spawning it on top of the player, works. (This was once not true; do not design around the old behavior.)
• OnEnter is a plain event, not a state: if the handler's variable gate is not open yet when the body enters, the entry is consumed and will NOT re-fire when the gate opens later. Place areas so the entry happens after the gate opens, or gate on a variable the repeat pulses can re-check (OnUpdate + occupancy variables you maintain yourself).

A body despawned while inside an area fires NO OnExit for itself - its occupancy rows are pruned silently.

Use other_type_name: Some("spaceship") instead of other_id when every ship leaving the area should match.

• OnOrbitStart: the maneuver engages for a well. The ship may still be aligning or burning toward its ring.

• OnOrbitStable: velocity error enters the autopilot's stable Hold band. It can fire again after stability is recovered.

• OnOrbitLap: the ship accumulates one net revolution in the planned travel direction. It fires again for each later complete lap.

  Counting starts when the ship first reaches the ring, not when the verb engages: the approach curves around the well and would otherwise bank most of a lap before the orbit began. From there it survives everything the autopilot does on the ring - an ORBIT that drops out of the stable band is correcting, not leaving - and only an absence of five seconds or more writes the partial lap off and starts it again at the ring. A lap objective therefore does not punish a player for one nudge.

• OnOrbitUnstable: velocity error leaves Hold while ORBIT stays engaged.

• OnOrbitEnd: a surviving ship cancels ORBIT, changes verb, loses flight capability, loses the well, or switches wells. Ship destruction emits only OnDestroyed, consistent with area despawn not emitting OnExit.

Switching wells queues OnOrbitEnd for the old well, then OnOrbitStart for the new one. Ending a stable orbit emits only OnOrbitEnd, not an unstable edge first.

A mission that requires one physical lap listens directly:

(
    name: OnOrbitLap,
    once: true,
    filters: [Entity((id: Some("planetoid"), other_id: Some("player_spaceship")))],
    actions: [ObjectiveComplete((id: "orbit_once"))],
),

A continuous eight-second stable hold uses a timer instead:

(
    name: OnOrbitStable,
    filters: [Entity((id: Some("planetoid"), other_id: Some("player_spaceship")))],
    actions: [TimerStart((key: "orbit_hold", seconds: Term(Factor(Literal(Number(8.0))))))],
),
(
    name: OnOrbitUnstable,
    filters: [Entity((id: Some("planetoid"), other_id: Some("player_spaceship")))],
    actions: [TimerCancel((key: "orbit_hold"))],
),
(
    name: OnOrbitEnd,
    filters: [Entity((id: Some("planetoid"), other_id: Some("player_spaceship")))],
    actions: [TimerCancel((key: "orbit_hold"))],
),
(
    name: OnTimerEnd,
    filters: [Timer((key: "orbit_hold"))],
    actions: [ObjectiveComplete((id: "hold_orbit"))],
),

A held lock stays quiet. AI locks do not fire scenario events. A direct target switch queues end for the old target, then start for the new target.

(
    name: OnTravelLockStart,
    filters: [Entity((
        id: Some("anchorage"),
        other_id: Some("player_spaceship"),
    ))],
    actions: [
        VariableSet((key: "surveyed", expression: Term(Factor(Literal(Number(1.0)))))),
        // ... the survey beat ...
    ],
),
(
    name: OnTravelLockEnd,
    filters: [Entity((
        id: Some("anchorage"),
        other_id: Some("player_spaceship"),
    ))],
    actions: [
        // ... react to losing the survey target ...
    ],
),

Use the combat pair for the red lock. To react to any locked target, omit id; keep other_id when the locking ship must be player_spaceship.

DOCK is a player verb, so other_id is the player's ship and id is whatever it flew up to.

OnDocked fires when the clamp exists, which is before the sleeves finish reaching across the gap - the joint is what holds the pair, and the tubes are art that follows it.

OnUndocked fires for EVERY ending, and carries no reason code: either pilot pressing DOCK again, a shot-off docking port, or one of the two ships dying. What a beat owes the pair back - the objective, the next order, the clearance to leave - is the same whichever way the clamp came off, and a scenario that must tell the endings apart has OnDestroyed to do it with.

Only a pair that dies WHOLE stays quiet, the way OnExit and OnOrbitEnd do for a despawned body. One hull dying is a release like any other: the survivor is free, and it is told so.

A delivery beat that opens when the player clamps on and closes when it lets go:

(
    name: OnDocked,
    once: true,
    filters: [Entity((
        id: Some("supply_tender"),
        other_id: Some("player_spaceship"),
    ))],
    actions: [
        ObjectiveComplete((id: "make_contact")),
        Objective((id: "carry_cargo", message: "Objective: Run the cargo home")),
    ],
),
(
    name: OnUndocked,
    filters: [Entity((
        id: Some("supply_tender"),
        other_id: Some("player_spaceship"),
    ))],
    actions: [
        VariableSet((key: "cargo_aboard", expression: Term(Factor(Literal(Number(1.0)))))),
    ],
),

To react to a dock with anything, omit id and keep other_id.