Actions

The base block:

The same spawn id twice in ONE handler is a lint Error; the same id across two handlers (an either-or fork) is a Warn.

region variants (struct variants - single parens, named fields):

asteroid_kinds is drawn from the scatter's OWN seed, on a stream of its own: adding a kind to a field that already ships moves no rock and changes no radius. An asteroid template with no mix, or with every weight at zero, is a lint error and spawns nothing - a belt has to say what it is made of.

Bodies are kept clear of each other WITHOUT you sizing anything. Every placement records its own reach - a rock's noise mesh reach (up to 6x the nominal radius, drawn from the same seed the body will use), a planet's surface radius, zero for anything with no body - and a candidate is rejected inside existing reach + candidate reach. A field of mixed sizes is therefore packed by the bodies it actually holds, not by one number sized for its biggest pair. This checks earlier ScatterObjects placements only: a planet spawned by SpawnScenarioObject is not in that set. Keep the entire field outside each planet's sphere of influence plus the largest rock's physical reach if its template starts at zero velocity. Otherwise a rock can spawn inside the planet or start falling toward it; lint cannot infer a safe orbit from one velocity shared by every randomly positioned copy.

min_separation is what you add ON TOP of that: a spacing you want for gameplay rather than for geometry - a belt you can fly through, a picket line that reads as a line. The rule is max(min_separation, reach + reach), so a value smaller than two bodies side by side changes nothing.

A randomized asteroid_radius is drawn BEFORE placement, on a stream of its own, so a rock is the same size however many tries its neighbourhood cost. Scatter results are gameplay content and are never thinned by graphics quality.

A body despawned while inside a trigger area fires NO OnExit for itself.

Works mid-scenario, and works even when created AROUND a body already inside (the entry still fires).

A beacon with area_radius is its OWN area - no separate CreateScenarioArea needed for it.

Re-posting the same id with new text updates the entry in place (the "recovered N/3" tally trick). A duplicate post otherwise warns.

Re-attaching updates the label in place. A despawned target detaches implicitly.

The accent. A line carries ONE presentation fact, and it is a colour, not an id. The panel derives everything it paints from it: the border, the speaker header, the fallback icon tile, and the reading copy lifted toward white. The background is the same dark for every card, and a card's opacity depends only on its normal display and fade.

Leave it out and the line is drawn in the comms blue - the work channel, traffic addressed to this ship, which is what nearly every line in a scenario is. Authoring the blue on all of them would bury the few that differ, so the default is written nowhere and the generated base scenarios carry no accent: line at all.

Name a colour when the line is NOT ordinary traffic: a distress band, a corporate net, a voice in the room off the radio, something the cockpit merely overheard. Nothing looks an id up, so nothing can fail to resolve one, and a mod invents as many voices as it has colours. Colour is tagged the same way it is everywhere else in content - LinearRgba((..)) or Srgba((..)).

Two lines the player must tell apart should differ by more than a shade. The useful distance is being CALLED versus OVERHEARING, and blue against amber reads at a glance where two blues do not.

Pacing is yours, not the panel's. A card holds its full time whatever is waiting behind it - the panel never takes reading time back to catch up - so the gap between two POSTS is what sets the reading rate. Post a line every 3-4 seconds and the reader has three cards up, the newest shoving the others upward as it lands; six to seven seconds leaves the card being read as the only one moving. Budget more where the player is flying and less where a cut has taken the helm, and keep a line to one thought: a card that needs longer than its hold is two lines, not one line held open.

Scenario-scoped: teardown clears the log.

Two story lines in one handler is a lint Warn (unreadable); a story line beside an Outcome in one handler is a Warn (frozen behind the overlay). Let the outcome's own message carry the closing line.

One fire is enough; the readout tracks the variable's current value every frame thereafter. It freezes under pause and behind the outcome overlay because the variable does - a time-trial's final time simply holds through the banner. Cleared at teardown.

The dock normally hides verbs the player cannot use yet, so emphasizing an unavailable verb REVEALS its chip dimmed and pulses it. Emphasis never grants the capability (the SetShipCapability* actions do).

Interface is UI chrome - a prompt, a stinger, a chapter tone - scaled by the interface track. Hull is structure-borne through the player's own ship, something they feel rather than hear, scaled by the world track. The route is authored because those are different cues and neither is the safe guess.

Non-positional on purpose. An exterior cue is attenuated and panned by where it happened, and a beat has no position to give one; a cue authored here is heard in the cockpit, which is where the player is. Author the positional kind on the object that makes it.

A step:

Both waits may sit on one step, and they run TOGETHER: a gate that opens early still owes the delay, and a delay that elapses first still owes the gate. A step with neither runs the moment it becomes current - which is how a hand-off beat rides the end of a chain.

(
    after: Some(6.0),
    until: Some((
        name: OnUpdate,
        filters: [Expression((Equal(
            Term(Factor(Name("surveyed"))),
            Term(Factor(Literal(Number(1.0)))),
        )))],
    )),
    deadline: Some(600.0),
    actions: [ /* the beat */ ],
),

The semantics are WAIT, never SKIP: a step whose gate stays shut blocks the beats behind it. That is why a gated step must carry a deadline - when it expires the chain STOPS and logs an error, so a soft-lock is loud instead of silent. content lint refuses a gated step without one.

Delays ride the pause-frozen scenario clock, so a gap measures play time, not wall time.

One cursor per key. Starting a key whose chain is still running is refused and logged; a chain that has finished frees its key. Several handlers MAY start the same key when only one of them can ever fire - every win variant of a scenario starting one shared outro chain is the idiom.

A step's actions are a FRAME of their own, landing seconds after the handler that queued them, and everything else applies inside a step unchanged: an objective still must not share a beat with a comms line, and a beat may start a chain of its own.

What it replaces. A paced chain used to be sibling OnUpdate handlers strung together by hand: a counter variable seeded in OnStart, a VariableSet per beat to advance it, and a filter per beat reading both the counter and scenario_elapsed against a stamped deadline. All of that is about the machine. Reach for a chain whenever the only thing a beat is waiting for is "later"; keep a handler where the beat must still ASK something when it lands - which of two lines to speak, whether the fight is still live - because a step runs when its wait ends and only a handler can re-check.

The two ends are EVENTS, not fields. A scene does not carry an on-finish action list; it REPORTS, and the handlers that answer live beside it:

• OnCinematicFinished fires on every path out - the last beat, a skip, a CancelCinematic, a blown step deadline. What the scene owes the player back (camera released, control returned, the objective it was covering) is authored there, ONCE, so no path can forget it.
• OnCinematicSkipped fires first on a skip, and carries only the catch-up: what the beats that never played would have left behind - the actors spawned, moved or destroyed, the variables latched.

Filter both with Cinematic((key: "...")), or a scenario with two scenes answers the wrong one. A filter naming a key no Cinematic plays is a lint Error, and a lint error refuses the scenario at load.

skippable is authored on every scene because a scene that cannot be left is a real decision - three seconds long, or the first time only - and not the kind of thing that should happen because a field was left out.

skippable: true puts a prompt on the screen. The HUD prints <KEY> SKIP SCENE bottom-centre, above the keybind dock, for as long as the scene will take the key; it reads the player's live binding for the cinematic_skip action, so a rebind is reflected mid-scene and a pad player is shown a pad glyph. It appears when the 0.75 s hold-off below expires, not when the scene opens, and it goes the moment the scene ends by any path. There is no field to suppress it: the prompt IS the promise the flag makes, and it is one of the two HUD surfaces the player's own hide-HUD toggle cannot take away.

A skip cancels the CURSOR. It never runs the remaining steps at speed: a step chain is not a list of world edits, it holds camera moves, comms lines and shots the player has just said they do not want. Whatever the world still needs belongs in the skipped handler.

The skip binding is held off for the first 0.75 s of the scene. The player is very often still holding the button that got them here, and without the hold-off a scene ends on the frame it opens and reads as a bug.

Nested chains outlive the skip. A Sequence started inside a scene has its own cursor, and cancelling the scene does not cancel it. A line that must not survive a skip belongs in the scene's own steps, not in a chain the scene started.

The scene still reports OnCinematicFinished, so whatever it took is given back. It does NOT report a skip: nobody asked to leave. Cancelling a key that is not running is a quiet no-op.

Nothing takes the card down. It expires on its own clock, so a scene that is skipped, cancelled, deadlined or torn down leaves a card that simply finishes. There is no handler to write and no ClearCinematicTitle to forget.

One card at a time. Posting a second replaces the first at its own age - two cards on screen are two answers to "where am I".

The corner is authored because only the shot knows which one is free. BottomLeft is the comms stack's corner, so a scene with dialogue in it wants a top corner; the top strip carries the status bar, which the card clears. A right-hand card mirrors a left-hand one: the accent rule stays on the outer edge and the lines stack against it.

The clock is the scenario's, not the frame's. A card holds through a pause rather than bleeding away behind the menu. A seconds shorter than the two fades together peaks lower instead of snapping on and off, which is the honest reading of "show this for half a second".

PRESENTATION ONLY: compose the consequence beside it. Queue a lingering NextScenario and the overlay offers Continue (Victory) or Retry (Defeat); queue nothing and it offers only Main Menu.

The paired switch must LINGER: an instant switch tears the scenario down the same frame and SWALLOWS the banner (lint warns on that composition).

Three gears:

• Hard cut - linger: false, no delay: switches on the next sync.
• Delayed cut - linger: false, delay: Some(4.0): the world keeps playing for the delay (a story line can land), then cuts. Ticks on pause-frozen time; Enter skips the wait.
• Modal hold - linger: true: waits for the scenario-advance input (Enter / DPadDown) or the outcome overlay's Continue/Retry.

The last request wins wholesale - a fresh NextScenario replaces a queued one and resets its clock.

A menu backdrop may not author NextScenario (lint Error): it reports with BackdropDone instead.

No fields. The backdrop never names its successor: the menu plays every backdrop once, in a shuffled order, before any plays again, and never the same one twice in a row when it has two or more.

• Every role: Backdrop scenario must author one (lint Error otherwise). A scene with no natural ending carries a timer, like the base backdrops' 150 s rotation limit.
• BackdropDone anywhere else is a lint Error: nothing reads it.
• The one-second beat runs on pause-frozen time. A second report inside the beat changes nothing.

The capability lands on the ship ROOT, not on its flight computer: a hull that loses every controller section loses its steering, never its permissions. Never withhold STOP by convention - an engaged autopilot should always be cancelable.

The spawn-time twin is the capabilities block on the spaceship object; these actions are its runtime mirror.

Completes when the ship's autopilot lets go - it is inside the standoff and settled - and fires OnShipOrderComplete with kind: Move.

arrival_standoff exists because the default 500 m is far too coarse to stage a shot with. It is a MARGIN, not a centre distance: the ship comes to rest with that much clear water between its own hull and the mark, so a warship and a shuttle sent to the same mark both stop where you staged them. It is installed for the life of the order and taken back off when the order retires - on completion as well as on a cancel or an interruption - so a cinematic's tight staging does not silently retune every later GOTO the hull flies. None uses the ship's own standoff.

A margin is a PARKING rule, not a route guarantee. The autopilot plans no route and dodges nothing on the way in, and gravity can bend the leg; stage the approach yourself if something is in it.

The hold is the point. A railgun does not traverse, so the shot leaves down whatever line the hull is holding: align, wait for the completion, then fire, and the slug goes where you aimed. The facing is held until another helm order replaces it, which is what lets several guns run their charges on one bearing.

The tolerance is also what "settled" is measured against - a tight tolerance asks for a genuinely steady hull, a coarse one accepts a drift - so an alignment order on a tumbling wreck may take a while, and one with an impossible tolerance is refused outright rather than left never completing.

Completes when the maneuver ends, with kind: Stop. "Ended" is a deadband and not a dead stop: a residual the drive is already pointing at is braked out to 2 m/s, and one it is not - a sideways drift, or a head-on crumb - is released at up to 7.5 m/s rather than chased with attitude flips. A hull granted RCS settles the remainder on its jets. So a ship already inside that band completes almost immediately, and a beat that needs the hull genuinely still should gate on a Speed query rather than on this order alone.

ONE loop, then kind: Patrol and the helm goes back. A route of one point is one leg out and one leg home; a route with the same point twice in a row still flies both legs, and the second lands immediately. Repeat the action to run another loop, or hand the ship a ClearShipOrder mid-route to abandon it.

For a STANDING patrol that never ends, author the route on the ship instead - an AI ship's own patrol field (see Spaceship) is the routine it returns to when nothing is happening.

Completes with kind: Orbit the moment the ring is ESTABLISHED - the ship is in the band and holding - and then keeps holding it, the same way ForceAlign keeps its bearing. A completion here means "it is in orbit now", not "it has stopped orbiting".

No loaded well that matches, two wells that match equally, or a well with no stable band for this hull fails the order rather than leaving the beat waiting: see OnShipOrderFailed. Two wells at the same surface distance fall to the lower id.

If the well goes after the ring is established - a streamed sector unloads, the body is destroyed - the order retires without another event and the helm goes back to the ship. It does not pick the well up again if it reloads.

A None-controller hull KEEPS its velocity and coasts - this is space, and letting a ship drift out of frame is usually the point. An AI ship goes back to its own routine on the next frame.

Emits OnShipOrderCanceled, NOT a completion: an order that was called off did not finish, so a beat gated on the completion correctly never runs. It also puts back the ship's own arrival standoff if a MoveShipTo had displaced it. Clearing a ship that is under no order does nothing and says nothing.

This is the CINEMATIC counterpart to StopShip, and the only one of the two a player's hull accepts. A helm order cannot share a helm with live input, so StopShip refuses a player ship out loud; but a scene that cuts the camera away for a minute of dialogue has to leave the player's ship somewhere sane, and asking a suspended pilot to coast on through a rock field is not it. Use it behind a cut, where the ship is off screen and the arithmetic is nobody's business - season one's distress call does exactly that, and is worth reading.

It only ever takes speed off. A ship whose controller still wants to burn is moving again on the next tick, so pair it with SuspendPlayerControl for a player hull or with ClearShipOrder for an ordered one. It reports no completion: there is no maneuver to finish.

No target and no steering: a railgun does not traverse, so the shot leaves down whatever line the hull holds when the charge completes. Putting that line on something is ForceAlign's job. Everything else is the gun's own behavior - the authored charge time, the magazine, the reload, the recoil through the hull, the slug, the sound and the flash.

The order is ONE SHOT: it holds the trigger until the gun actually fires (through a reload, if the magazine was empty) and then retires itself. Fire a second shell with a second action.

ONE bay, addressed by its section id. The bay's own cooldown and ammo still time the launch, and the ordnance is committed to the target the same way an AI or player launch is - which is also what makes the torpedo visible to hostile point defense. The AI's launch gates (range envelope, hull-forward cone, line of sight, the AI cadence) do NOT apply: the script is the decision.

A missing target skips the launch entirely, so no dud goes out while a target is mid-respawn. The order is one shot, like the railgun's.

true puts each weapon's finite magazine aside and lets the section fire on its cooldown alone. false gives the magazine back at the section's own AUTHORED capacity, full, with the reload re-seeded from the section prototype - not at whatever count was left when it was suspended. A count from before the suspension is not a count the run earned either, and a full magazine is the one state a player and an author can both predict.

Turning it on twice is idempotent, and turning it off on a ship that never had it on does nothing. A weapon authored with no magazine at all was already unlimited and is untouched in both directions.

This is an authoring bypass, not the ordinary reload: the ordinary idle reload (see Turret reload) spends matching ammunition from the ship's own inventory; this action never touches it, in either direction.

Each magazine returns to its authored capacity and any reload in flight is cleared. Weapons with no finite magazine - and any whose magazine is currently suspended by SetInfiniteAmmo - are skipped.

An authoring bypass, not the ordinary reload: it fills the magazine directly and spends nothing from the ship's inventory, unlike the ordinary idle reload.

Widening a leash mid-scenario is how a garrison is let off its post; releasing it entirely turns a picket into a pursuer. The anchor is an authored point, not the ship - moving the ship does not move the tether.

Wide is a long-watch emplacement that wakes for targets parked outside everyone else's detection. Short is a ship that ignores a brawl next door. Narrowing it mid-fight does NOT drop a target it has already acquired.

Short stages the intercept close in, where the player can see it. Past the turret's own ~1.8 km reach it only wastes the opening shots, so authoring wider than the guns can shoot buys nothing.

The duration is a numeric expression and must evaluate to a positive finite number. Invalid values log an error and leave an existing timer unchanged.

Timers freeze under pause and clear on retry or teardown. Use an OnTimerEnd handler with a Timer filter to react once.

A timer earns its handler when the beat must still ASK something when it lands - is the wing still alive, which line fits. A run of beats that only waits for later is a Sequence instead.

In the in-game editor the expression is not a text field: the action opens a Value page under its Key, a row per node, exactly as an expression filter opens its condition. See the typed form.

Blends. A blend rides on top of the pose, so a blend onto an anchored shot keeps tracking its subject all the way in. seconds is how long the move takes; easing is how those seconds are spent - omitted is Smooth, and Linear is the special case that wants to look like a rig on a rail (Some((seconds: 4.0, easing: Linear))). A pose authored as a cut also REMOVES any blend still running, or the cut would be swallowed by the move it was meant to interrupt.

Part of the screenshot/photo surface; no scenario camera present is a warn no-op.

Local composes the same shot whatever heading the anchor is on - an over-the-shoulder chase. World composes the same shot whatever the anchor is DOING, which is what you want while the player is still flying: their heading is not yours to choose.

look_at: Object follows a live object and falls back to the anchor if that object dies mid-shot; look_at: Point is fixed world space and survives whatever was standing there. Frame something that is about to be destroyed with Point, not Object.

Camera authority only. It never steers or stops the ship it rides and does not change player input authority. Like SetCamera it drops free-fly control and re-enforces the pose every frame; unlike SetCamera there is something to hand back to, so pair it with ReleaseCamera. Pair a staged shot that must own gameplay input with SuspendPlayerControl and explicitly resume when the shot returns control. An anchor id that names nothing warns and leaves the camera alone.

No fields. Takes off both SetCamera's fixed pose and SetCameraAnchor's ride, whichever is on. The chase rig never stopped solving underneath, so the shot ends and the player is looking out of their own ship again - there is no restore pose to author.

Harmless when nothing is pinned. This is camera-only: it does not implicitly resume player control.

No fields. The action immediately clears held burn, RCS, rotation, radar, combat stance, thruster, turret, torpedo, and railgun intent so an input pressed before the cut cannot remain latched. Pause, menu, and an explicitly always-live cinematic-skip binding remain available. Physics, timers, AI, scripted ships, weapons already in flight, and camera actions continue.

Repeated suspension is harmless. Scenario teardown always restores control, but authored content should still pair each interval with ResumePlayerControl.

No fields. Repeated resume is harmless. This is input-only: pair it with ReleaseCamera when returning both view and control.

Relative paths land under the NOVA_CAPTURE_DIR env var when set; parent directories are created.

The install is deferred until the new image has loaded; a failed load leaves the sky unchanged (warned).