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 save does not keep the player ship as a spawn: the open world streams around the ship OnResume spawns, and the save's ship state lands on it once it stands. A VariableSet here would overwrite the saved value, and an Objective would post a second copy of one the save already lists.

OnResume on a scenario that cannot be saved is a lint warning: it never fires there.

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.

A generated world's bounds block (see World) is an area named bounds the loader spawns before OnStart, so id: Some("bounds") here is how a scenario answers the player leaving it.

In a generated world the entering body may be one the generator placed - a rock, a derelict - whose id (sector_n2_0_0_background_rock_3) exists only at runtime. You cannot write that id in a filter or an action (lint refuses it); pass it on from the event instead with ObjectiveMarkerAttach((target_id: "$other_id", ..)).

• 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. Its type_name tells a station from a ship: a living station reads living_station, a dead one derelict_station (spawned dead, or a living one that lost its last turret), and any other hull spaceship. That is how a beat asks for "any living station" in a generated world, where no author can write the station's id:

(
    name: OnUndocked,
    once: true,
    filters: [Entity((
        type_name: Some("living_station"),
        other_id: Some("player"),
    ))],
    actions: [
        Objective((id: "find_help", message: "Find another living station")),
    ],
),

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.

The pair events follow the docking rule: the PASSIVE party is id and the ship that acted is other_id. A rock is mined, a tender is traded with, a station is stored at. The single-ship events name the ship the hold or purse belongs to.

OnMined fires per paying pulse: a pulse that flips no corner is silent, and count is the corners it did flip, which is the ore that lands in the hold only if the intake catches the chips. OnPickedUp and OnJettisoned fire once per STACK: a canister holding two item kinds raises two events with the same canister. A hold with room for only part of a canister takes whole items and raises OnPickedUp with the count it took; the rest is picked up later under the same canister.

OnTraded fires once per confirmed trade on the player's queue, so a buy of four rations is one event with count: 4. The credits move it causes raises one OnCreditsChanged per party, cause: Trade, in the same frame; the loot-take of a dead ship's purse raises one with cause: Take; a rebuild raises one per party with cause: Rebuild, the ship paying and the station paid, a swap one per party with cause: Swap, an add one per party with cause: Add, a hull buy one per party with cause: ShipBuy, and an escort hire one per party with cause: EscortHire. A station buy raises one, for the player only, with cause: StationBuy: the price goes to the civilization, so the station's purse does not move. An armed credits give or credits set command raises one with cause: Cheat. A move that leaves the purse unchanged raises nothing. OnStored and OnWithdrawn fire once per confirmed move and move no credits, so they raise no OnCreditsChanged.

Trades, stores, withdraws, repairs, rebuilds, swaps, adds, hull buys, escort hires and station buys come from the interface panes, which run while the world is paused: their events arrive on the first simulation tick after the pane closes. Intake and mining events arrive the frame the hold changes.

A prospecting berth that wants one of each:

(
    name: OnTraded,
    once: true,
    filters: [Entity((id: Some("example_tender"), other_id: Some("player_spaceship")))],
    actions: [ObjectiveComplete((id: "prospect_trade"))],
),
(
    name: OnMined,
    once: true,
    filters: [Entity((id: Some("example_ore_rock"), other_id: Some("player_spaceship")))],
    actions: [ObjectiveComplete((id: "prospect_mine"))],
),
(
    name: OnRepaired,
    once: true,
    filters: [Entity((id: Some("player_spaceship")))],
    actions: [ObjectiveComplete((id: "prospect_repair"))],
),

The example mod's example_prospect scenario runs all but OnRebuilt, OnSwapped, OnAdded, OnShipBought, OnEscortHired, OnStationBought, OnStripped, OnStored and OnWithdrawn.

An Entity filter on id matches a job id here, not a scenario object. A job id reads <station id>#<slot>.<posting> for a slot job and <station id>#<visit id>.<index> for a visit posting.

A refused accept fires nothing, and neither does a Load that restores held jobs, so a handler on this event never runs twice for one job.