Author Scenario

Authoring scenarios

A scenario is a rhai program attached to an entity. Production scenarios are task/event-driven policy. They must not define on_tick; that hook is reserved for authored tests under assets/scenarios/tests/ to sample live telemetry and publish a bounded verdict. Continuous rover dynamics remain in fixed-step physics/Modelica. Runtime plugins install their own cycles from the selected application composition. A scenario may declare its peer-role execution target with // @peer host|client|both and its cadence with // @timing simulation; host includes standalone authoritative mode. These directives do not choose its Core/Application/Twin owner or install schedules. Rust assigns the owner route and retains schedule ownership. Unsupported metadata disables only that program and publishes a document diagnostic for its source revision. Keep runtime errors visible; do not catch and erase them as successful no-ops.

Scenario actors submit, commit, and run in GlobalEntityId order from the source-owned component, not from ECS query order or the API lookup index. A local-only host without a global identity uses a world-local Bevy key and is not part of cross-session replay ordering. If one scenario's synchronous command must be visible to another in the same pass, test that handoff through a production Rhai scene with stable actor identities.

For mission operations, read the generic mission and engineering quality gates before authoring the scenario. Treat the ConOps, mode transitions, command and telemetry contract, timing/resources, nominal path, and contingency/recovery paths as explicit requirements. Exercise fault stimuli and safe/degraded modes through event-driven policy and tests; do not turn missing telemetry or an invalid command into a silent fallback.

For live route edits, Rhai owns the route policy and calls the generic typed USD operation command. The reusable waypoint_editor tool authors ordinary USD route points, whether their route scope is inline or composed from a separate route-plan asset. Document authoring composes the base, runtime, and view layers at their actual strengths before validating selected-variant children; the route_variant_lifecycle production gate covers add, move, and delete on that route shape. It uses a local active=false opinion when a point comes from a reference arc, and updates the disposable ribbon in the document's @view@ layer under the selected route scope from the committed USD route. An edit can use the selected route point to resolve its enclosing route and does not require rover possession; multiple routes still require an explicit route or subject selection. A selection-only delete resolves the selected point when no pointer target is present. Bind a route program to its composed USD document and build its ribbon from the matching usd.document.projected event; that event is the authoritative boundary for the route identity and does not wait for Modelica admission. Keep on_visualization(me, ctx) for presentation preparation that does not depend on a document attachment that may still be settling. This one-shot callback runs in PreUpdate, after the time spine and before the first fixed tick, top-level initialization, or on_start; use the host id, parameters, and read-only queries. Rhai blocks world writes and events there; ApplyUsdTransientOps is the only available command and always edits the disposable view layer. Keeping the ribbon under that scope preserves the route points' USD parent frame. The subject and route owner remain live: route edits do not rebuild or reset their physics, Modelica state, pose, possession, or Rhai this state. The authored inputs:enabled value is only an initial policy; F changes the scenario's runtime state and must not write it back to USD. Do not implement this policy with a polling on_tick loop or move USD identity resolution, terrain sampling, collision events, or fixed-step steering into Rhai. Document-backed route edits remain valid during the short projection interval: the generic resolver uses a locally authored target before its live ECS entity exists. If the canonical child list is not synchronized, the editor reports a retryable error rather than guessing a point name or writing to a different program. Composed-only paths still require the mounted canonical stage. When a source is hot-swapped, the program emits the generic typed program.ready event after on_start; one-shot UI or control actions wait for that lifecycle edge rather than relying on a timer. Sensor events may carry a nested collider; match the entrant through the generic parent() chain to the authored subject instead of adding a route-specific child relationship. If the mounted document is attached after on_start, defer document-backed route reads and task actions until the matching usd.document.projected event binds it; do not retry against an empty identity each task pass. Initial scenario admission waits for all world and entity readiness holds because a program may depend on entities outside its own hierarchy. After admission, an entity hold idles only scenarios attached within that subtree; release resumes them without a stop/start cycle. Fixed-step hooks run after SimTickSet and release only events stamped before the current tick. Paused simulations deliver discrete events on the next Update without advancing the tick. The first on_start does not replay events from before the program started. Query current state from the owning subsystem for startup decisions, then use on_event for later transitions. Connected co-simulation event outputs are edge-detected on admitted simulation ticks after SimTickSet and the full scripting pass. During startup holds, an edge may occur before scenario execution opens and is not replayed to a later on_start; read the current state from its owning subsystem during startup. Event time comes from MissionClock at the producer's SimTick; later edges are delivered on an eligible scenario pass.

Use simulation_dependencies(me, ctx) to declare simulation-clock Modelica port/event dependencies, generic live entities accessed through direct get, port, ReadPorts, or direct mutation, and broad API query providers. The owner uses the plan for startup admission and runtime access checks. Return all five plan arrays even when empty. Omitting a field is a source error:

fn simulation_dependencies(me, ctx) {
    #{
        modelica_entities: [find_path("/Rover/Controller")],
        entity_reads: [],
        entity_writes: [],
        query_reads: [],
        required_inputs: [
            #{ owner: "sysml.twin-analysis", identity: ctx.twin_name },
        ],
    }
}

Modelica entities join the shared fixed-step causal barrier. Required input keys name an owner namespace and an exact identity; the generic runtime waits on owner-published Pending/Ready/Failed state before top-level initialization and on_start. A pending scenario keeps its existing activation hold and resumes after the owner publishes a new state revision, so scripts should not poll analysis from on_tick. A missing owner or failed input produces a diagnostic. Keep the selection policy in Rhai and use the key contract exposed by the domain owner. Every modelica_entities id must resolve to a live Modelica participant; a live but unrelated entity fails the source revision before initialization. Declare every Modelica participant this scenario reads or writes through a port or whose event it consumes. The aggregate solver barrier is not an access grant: membership through USD connections or another scenario's plan does not authorize this scenario to read that participant. modelica_entities grants both read and write access to those live Modelica participants and adds them to the shared simulation barrier. entity_reads and entity_writes grant directional access to any live entity; a Modelica entity in either set also joins the shared barrier. Direct reflected and port reads require read access, while direct reflected writes, port writes, and structural verbs require write access. Entity-targeted query providers report the ids they read. Declare those target ids in entity_reads too; this includes QueryEntity, QueryPhysicsState, ReadPorts, GetPort, SolarPose, and single-entity ListPorts calls. Mounted-scene USD queries without doc_id use the committed Twin generation. For broad providers such as EntitiesInRadius, Raycast, or CosimStatus, list the public provider name in query_reads. This declares the provider's whole snapshot as a coarse dependency. Broad queries cannot run while the plan is being resolved; after commit, the same declaration authorizes the scenario-owned top-level initialization and lifecycle hooks. Undeclared simulation-clock access through direct get, port, or ReadPorts requires the matching direction. Targeted Modelica commands and Modelica event delivery require the target or producer in this scenario's own plan; aggregate barrier membership is not authorization. Hierarchy and spatial identity queries remain available for discovery. If a scenario uses their returned ids in direct get, port, or mutation calls, it must include those ids in the corresponding access set.

When a typed simulation command creates an entity whose id was not available while the plan was prepared, call track_entity_read(id) or track_entity_write(id) after the command has materialized the live entity and before accessing it. This commits access in serialized simulation order; if the entity is a Modelica participant, it also joins the scenario's barrier.

The reusable route marker is a translucent, unlit, shadowless annotation. Its unvisited colour is bright green and its visited colour is gray in standard primvars:displayColor; route_follow applies the visited colour through waypoint_editor's transient USD view operation. Route progress is keyed by USD point path and survives autopilot stop/start. At on_start, the program reads the current Avian contact for only the first unvisited route point through the generic SensorOccupants query. A simultaneous occupancy snapshot has no visit order, so it cannot mark later points. A later sensor enter marks a visit only when its zone is the first unvisited point; out-of-order arrivals are ignored until that point is entered after its predecessors. Active route progression uses the same order. This is presentation state, not a vessel component or a second route fact. The route context gesture opens its authored menu without selecting the point; selection and gizmo activation require the menu's explicit select action, and click-to-place movement requires the separate Move action. Pass the resolved document, route, and direct point in each menu action context so a later callback does not depend on viewport query scope. Resolve a route-bearing pointer target before a previously selected or controlled subject, especially when one subject has multiple route programs. User possession is a ControlLink/SessionRegistry lifecycle, while a route program is guidance policy. Releasing possession hides the vessel HUD and releases manual input holds; an enabled route then republishes its active guidance target without claiming the user's session. Route policy owns any stop setpoint and writes it explicitly. Repossession restores the HUD without restarting the route.

Script source edits made by a user go through the ScriptDocument host, so undo, redo, and the Twin journal see the same typed ScriptOp. A file-backed or USD-embedded source refresh uses the shared external-baseline path instead; it advances the runtime generation without duplicating the source owner's journal entry. The disposable ribbon follows the same rule: its typed @view@ projection is rebuilt from the committed route and is never authored as Twin content or placed in user history.

Reusable authored programs are managed through the generic Rhai program_editor tool. It lists LunCoProgramAPI children, selects or opens a program in the existing editor, atomically switches its info:sourceAsset arm, and can attach a new source-backed program without knowing whether the owner is a rover, lander, route, or another model. Twin policy may enable the standard program-browser surface on any USD scope with program_editor::enable_hud(doc, scope, visibility). The surface emits typed semantic actions; it does not contain vessel-specific Rust or an ad-hoc text input protocol. A subject may bind several programs through rel programs; the browser and generic scene selection keep one canonical program path active, so editing or F control never falls back to a hardcoded /Route.

Host = mechanism, script = policy. A scenario touches the world only through the same command/query API the HTTP API, MCP, and UI use — so it inherits every command for free and stays decoupled from physics.

Scene construction is an authoring/preflight concern, not production scenario logic. Use the generic Rhai model_authoring::scene_recipe before launching a scenario to place authored assemblies/terrain, define cameras and initial state, and record route/program hand-offs. Use model_context, readiness_report, and port_graph/wiring_plan to validate the exact document, paths, and generation first. Apply returned USD ops through assembly_edit; pass route entries to waypoint_editor and program entries to assembly_edit::attach_program. Keep mission sequencing here, continuous math in Modelica, and do not turn the recipe into an on_tick loop. See the model-authoring guide.

Scope boundary — do not blur these:

• Control MATH (PID, mixing, force/torque) → Modelica, NOT rhai. If you're writing a per-tick control loop here, stop — see authoring-vessel-controllers.
• Scene structure / spawning geometry / wiring → USD.
• Vector and angle math is already NATIVE — never write it in a script. vadd vsub vscale vlen norm_squared vdot vcross vnorm qrot clamp angle_deg yaw_delta_deg are Rust (lunco_scripting_rhai_core::rhai_math, on glam). Existing array operands remain supported; hot-loop code should use native Vec3/Quat from world_pos3, world_forward3, and world_rotation_quat, lowering with vec3_array/quat_array only at a command, telemetry, or USD-literal boundary. Reimplementing one in rhai is how four scripts ended up with four copies of the same broken acos guard.
• A scenario senses and decides; it drives via high-level verbs (nav_to, drive, cmd), reacts to events, and sequences phases.

The two rules that make the math surface safe:

1. Array reads preserve the observer contract and return () when there is nothing to measure — a () input, a wrong-length array, or a degenerate orientation. Native constructors/operations instead raise a script error for malformed values, so an authored program cannot silently continue with a poisoned native pose:

   let d = yaw_delta_deg(this.fprev, world_forward3(me));
   if d != () { this.yaw += d; }        // skip the tick, don't poison the sum

2. Angles are PER-TICK DELTAS. yaw_delta_deg saturates at 180°, so a total swept angle is accumulated from deltas — never measured start-to-end. Past half a revolution a direct measure folds back and reads as a turn the other way.

Full reference: docs/scripting-guide.md. The authoritative callable surface in one place: the ScriptingCatalog query.

1. Lifecycle hooks — the shape of every scenario

Define any subset. First param (me) is the host entity id. Production progression is returned by task(me, ctx) and advanced by the native behavior kernel; mission(me, ctx) supplies durable objective tracking. Lifecycle/event hooks remain available for setup, reactions, and teardown.

fn task(me, ctx)           { seq([wait_until(|m| arrived(m, GOAL, 2.0))]); }
fn mission(me, ctx)        { [objective("survey", #{})]; }       // optional
fn on_start(me, ctx)       { this.i = 0; }                       // once, after declared inputs are ready
fn on_event(me, evt, ctx)  { if evt.name == "GO" { /* … */ } } // event-driven policy
fn on_stop(me, ctx)        { brake(me); }                       // hot-reload / detach / despawn
// Bounded sampled observer (tests only):
// fn on_tick(me, ctx) { this.samples.push(query("rover_status", #{id: me})); }

The state rule that trips up everyone (get this right first):

• rhai fns are pure — they CANNOT see top-level lets. Thread all persistent state through this.
• this is the persistent scenario-state map. Direct lifecycle/mission drivers receive the host entity id as me; task leaves receive that same id as their one positional argument and are authored as anonymous closures (|me| ...). The native task driver binds this while invoking those closures, and owns the task cursor/dwell/event state. Named callbacks are also supported as Fn("name") when declared fn name(me); the driver binds the same persistent state map as this.
• Rhai map arguments are value/copy-on-write values. A helper that assigns a persistent field must return the updated map, and the lifecycle callback must assign it back to this; helper-side field assignments alone do not persist.
• Hot-reload runs on_stop before installing the new program state; initialize all required this fields in the new run.
• Scenario initialization and readiness already have distinct owners: simulation_dependencies declares admission, the module body initializes per-instance state after admission, and on_start is the ready callback. Do not add duplicate init/ready hooks. on_event runs in the scenario's eligible Simulation pass (or paused Lifecycle pass); a listener does not select the producer's clock. Any future UI, Interaction, or Presentation listener needs its own cycle owner, inbox, and state, with typed messages across owners.
• For stateless Rhai decisions outside the scenario Simulation lane, use the existing owner-scheduled hook registry when that subsystem exposes a typed hook. The owner supplies its facts and runtime context, then validates and applies the result at its own boundary. Do not move one stateful scenario instance between cycles or create per-cycle scenario callbacks for policy that an owner-invoked hook can express.

Owner scope and reload

Rhai hooks inherit the owner scope chosen by their Rust host. A Twin-owned scenario carries that Twin's stable ID and scene generation in execution_context(); application and Core policy runtimes keep their own scope across Twin transitions. Do not infer ownership from the currently active Twin. A script projected from USD is scene-owned and is stopped when that scene is replaced; a file-backed tutorial launched for a Twin uses an isolated host and is stopped, with its source handles and document, at TwinClosed.

For a persistent Twin-owned host using reload_policy: "Retain", scene replacement preserves this and does not repeat initialization or on_start. The owner reruns simulation_dependencies against the new scene generation before admitting subsequent hooks. Resolve scene entity identities in that hook; retaining VM state does not retain outgoing entity access rights.

The outgoing Twin ID remains available to on_stop even after workspace selection changes. Pending asset completions are accepted only while that specific Twin remains mounted. Application-owned scenarios on WorldRoot are not replaced by Twin tutorial launches and are not recompiled because another Twin's scene generation changed.

2. The verb surface (host bridge — everything else is prelude)

JSON appears only at the cmd/query params seam. get/set are native reflect — no JSON round-trip.

3. Prelude helpers (hot-reloadable policy — no Rust rebuild)

assets/scripting/prelude/*.rhai, one file per topic. Read them for the full list. Highlights:

• Nav: drive(rover,fwd,steer), brake(rover), nav_to(entity,target,speed,radius) (returns true on arrival). New missions return task trees. goto is a reserved word — use nav_to.
• Sensing: distance, arrived, velocity3/velocity/speed, raycast, obstacle_ahead, ground_height, nearest, entities_in_radius.
• Selection: all_of_type, nearest_where, count_where, min_by/max_by.
• Task tree: seq/par_all/par_race/repeat/forever, leaves step/once/act_for/wait/wait_until/wait_for/wait_for_from, and failure nodes check/sel/retry/invert/force_ok/force_fail/reactive_seq/reactive_sel. Return the tree from task(me, ctx); the kernel owns event delivery and there is one task progression path.
• Testing (prelude/auto_tests.rhai): t_range t_max t_true t_rel t_present t_bounded t_moved report_verdict fail_fast expect_fault expect_runtime_fault expect_scene_load_failure seg find_or_none r2/r4.

Add helpers freely — edit the prelude, no rebuild.

For a reusable helper rather than mission-local policy, use a named Rhai tool library under assets/scripting/tools/ or the active Twin's tools/ directory. Follow author-rhai-tool: registered tools are called as name::function(...), do not use dynamic import for them, and a tool used to author USD must return typed operations to the document owner instead of writing USDA or mutating ECS.

3a. Writing a scene TEST

A test scenario is an ordinary scenario whose last act is a verdict. Take the assertions from prelude/auto_tests.rhai — do not paste private copies of r2/t_range/t_report into a new test.

Where it goes is what makes it a test, and there is no name convention to remember:

scripts/run_scene_tests.sh runs everything in scenes/tests/, the Scene menu hides it (AssetVisibilitySettings, one checkbox in Settings), and every_test_scene_carries_a_scenario fails on any of them that asserts nothing. A rig written into scenes/luncosim/ instead gates nothing however carefully it asserts — no_test_scene_hides_outside_the_tests_directory is the check that says so. Do NOT suffix the file _test: the folder already said it.

A check returns "" on pass and a MESSAGE on failure; collect them so every check runs and the report names all of them:

fn verdict(s) {
    let f = [];
    f.push(t_bounded(s.hull_pos, 100.0, "hull"));      // still a vehicle
    f.push(t_range(s.tilt, 0.0, 5.0, "tilt at rest (deg)"));
    f.push(t_moved(s.distance, 1.0, "rover travel"));  // and it actually drove
    report_verdict(f, "LANDING LEGS", "LANDING_LEGS"); // prints, emits, toasts
}

report_verdict(fails, title, channel) prints the greppable <title>: PASS|FAIL line, emits the verdict on channel — which is what sets luncosim test's exit code — and raises a toast. Call it once after assertions. For a test that intentionally loads a scene expected to fail, call expect_scene_load_failure(path, detail_contains) before the verdict and call load_scene(path) after it. The runner keeps the result open until it observes that exact typed transition outcome and verifies the failed mount released its load and admission state. Use fail_fast for setup failures (a find that returned -1, the wrong scene) so a broken run stops on tick one instead of ticking silently to the limit.

For a tutorial, this scenario is an observer, not a second lesson. Attach it to the same production scene fixture as the tutorial and observe its public cmd:* events, mission verdict, and live state. Count the mechanism that matters (cmd:AcquireControl plus a real port write, for example), then verify the resulting movement or value. Never make the observer send the same control commands as the lesson, and never accept MISSION_COMPLETE by itself.

This keeps tutorial regression tests in Rhai, where they can be edited and run without rebuilding the Rust core:

"$LUNCOSIM_BIN" test \
  --scene scenes/tests/tutorial_first_drive.usda --max-ticks 6000

Scene loading and asynchronous Modelica participant readiness are bounded by wall time, not update count. Use --readiness-timeout SECS when a machine needs a different compile budget; the shell gate uses its separate READINESS_TIMEOUT startup budget. The shell's larger SCENE_TIMEOUT wall-clock backstop allows valid long-running missions to keep advancing, while --max-ticks remains the simulated-time liveness bound after readiness. A readiness timeout is a no-verdict failure and must be diagnosed at the worker/readiness owner, not hidden by increasing an update-count constant.

The generic Rust contract may still compile every embedded script and exercise the shared hook seam. Keep it content-agnostic; a lesson's steps, required events, and expected command sequence belong in an authored Rhai observer.

A silent pass is not a pass. A scenario fails silently in every direction that matters: a hook that never fires, a phase that never advances, a find that missed. So assert that something was MEASURED (t_present) and that something MOVED (t_moved, or t_rel's both-near-zero rejection), and print a per-sample table — a run with no sample rows proves nothing.

For a user-visible mission or scene review, run the production luncosim headfully with --api PORT, keep the window open, and capture/inspect the viewport at each material phase. Do not silently replace that session with --no-ui or --offscreen; the user needs to see whether the authored vehicle actually lands, deploys, connects, or falls.

Run the deterministic numeric assertion headlessly only when visual acceptance is not part of the request:

"$LUNCOSIM_BIN" test \
    --scene scenes/tests/landing_legs.usda --max-ticks 500

When a source build is required, build the production binary in the current worktree and set LUNCOSIM_BIN to that executable. An installed production build can be used directly. Test commands consume the selected production binary; they do not use cargo run. For USD/Rhai-only iteration, reuse it without rebuilding:

./scripts/run_scene_tests.sh --no-build --exact <scene-name>
./scripts/run_scene_tests.sh --no-build -j 4 <scene-substring>

The runner defaults to four independent headless production processes. -j/--jobs N changes only that process bound; each gate process still uses --threads 1 --jitter 0, and graphics assertions run in their separate serial offscreen pass. Use -j 1 when diagnosing ordering or resource interactions.

For a standalone assertion against a running scene, use the live no-restart wrapper:

./scripts/api/run_rhai_test.sh 4101 assets/scripting/tests/test_usd_query.rhai /SandboxScene/Box

The helper assembles the prelude and delegates to the native luncosim rhai --stdout client, which sends the test through RunRhai; edit the .rhai file and run it again in the same API session. Keep generic command/lifecycle/cache tests in Rust, and move authored mission or vehicle outcomes into a discovered scenes/tests + scenarios/tests pair.