Authoring Vessel Controllers

Authoring vessel controllers

Read luncosim-architecture before adding a sensor, actuator, generated network, or custom USD field. This skill owns the vessel-controller recipe; the architecture skill owns the standard-schema and no-compatibility gate.

A vessel that drives itself (a GNC, an autopilot) is built from three layers, each in the language that fits it. Never blur them.

The shipped lander is one reference implementation: assets/models/Lander.mo, assets/scenarios/lander_subsystems.rhai, assets/vessels/landers/descent_lander.usda (referenced by assets/scenes/luncosim/lander_ops.usda). For another vehicle, select the closest production controller, vehicle asset, composing scene, and test before authoring a new one. A tutorial model can clarify the idea while still being too simplified to serve as the production contract.

Start with the closest production exemplar

Before writing a new controller:

1. Search assets/models/, assets/vessels/, assets/components/, assets/scenes/, and assets/scenarios/ for an existing controller and its consumer.
2. Read the model's declared inputs/outputs, the USD wires, and the scene test that observes the behavior.
3. Reuse the same authority, sensor, frame, and actuation boundaries. Override vehicle facts in USD and controller tuning through the established input or parameter contract.
4. Add a new .mo only when the existing equation or public interface is genuinely insufficient; do not fork a working controller for naming alone.

This is a discovery rule, not a requirement to reuse one particular vehicle.

For a new controller assembly, use the generic Rhai authoring checkpoint before debugging the equations: model_context reads the exact program/body tree, readiness_report checks the caller's topology, physicality, mount, connection, control, and runtime policy, and port_graph/wiring_plan validates the standard USD endpoint paths and types. Keep the controller's continuous law in Modelica and the phase/mission policy in Rhai; these facades only inspect and return dry typed USD plans. See the model-authoring guide.

When propellant changes a hull's mass properties, connect the Modelica mass, body-local COM, and diagonal inertia outputs to the physical Avian inputs:mass, inputs:com_x/y/z, and inputs:inertia_xx/yy/zz through the document API. Controller inputs such as controller_inertia_xx/yy/zz consume separate wires; those inputs do not update the physical body. The live physical endpoint retains native f64 solver values through collider recomputation. Scalar inertia updates require an axis-aligned tensor and reject nonzero cross terms before commit; they cannot represent a coupled tensor update. Keep articulated appendages as their own bodies: the joint-island mass outputs are complete translational mass, not an assumed rigid assembly inertia. Verify live burn mass, COM, and inertia against QueryPhysicsState in the owning authored Rhai scene test. See the lander mass-property contract.

1. The control law → a Modelica model

The model reads what the vessel senses and outputs force/torque. It is a PROGRAM, and a program is a prim: the vessel's own flight-control system is inseparable from the airframe, so the vessel prim applies LunCoProgramAPI and names the model in place — uniform asset info:sourceAsset = @models/MyController.mo@. Its inputs: ARE the vessel's control surface. A control law that is bolted on (a guidance component, a supervisory script) is a a Scope applying LunCoProgramAPI CHILD prim instead, so deleting the prim removes the behaviour. Ports are wired with native USD connections (§3).

Because it drives a force on a body the client predicts, it must promise it steps fast enough for that: uniform bool lunco:program:realtimeSafe = true. Without the promise the wiring pass refuses it a force_*/torque_* port and says why.

model MyController
  input Real altitude, descent_rate;      // SENSED (wired from sensors, see §3)
  input Real piloted = 0.0;               // authority gate (wired, see §4)
  input Real external_throttle = 0.0;     // the pilot's stick (when piloted)
  output Real force_y, throttle;
  Real gnc_throttle, cmd;
equation
  gnc_throttle = <your control law>;                 // math, DIRECT (no lag)
  cmd = piloted*external_throttle + (1.0-piloted)*gnc_throttle;  // yield-to-pilot gate
  force_y = cmd * max_thrust;
end MyController;

Gotchas that will waste hours if you don't know them:

• rumoca folds unwired, algebraic-only inputs to their default. An input Real x used only in algebraic equations, never wired and never written, is constant-folded → runtime writes to it never reach the solver. To keep an input LIVE, either wire it (see §3/§4) or route it through a der (der(x_live)=(x-x_live)/0.02; use x_live). Symptom: set() returns true but has no effect.
• Inputs that feed a der are always live (a state depends on them) — that's why external_throttle/pitch are spool-filtered (der(filter)=(cmd-filter)/tau): it both gives pilot feel AND keeps them live.
• Keep the control (GNC) path DIRECT — no spool. A lag on the autonomous path makes it sluggish and can tumble the vehicle. Spool only the pilot's stick.
• rumoca mis-lowers if on algebraic vars. Use min/max for clamps and a branch-free arithmetic blend (a*x+(1-a)*y) for selection, never a nested if.

For a rover route, the drivetrain and any continuous control law remain the actuator-side Modelica/USD contract. Both skid RoverDrivetrain and wheel-steered RoverAckermannDrivetrain consume parameters:forward_yaw_offset on the drivetrain prim to align guidance with the wheel travel frame. Navigation uses −Z forward by default; a body-local +X wheel heading requires −π/2. Derive the travel direction from the authored steering axis crossed with the wheel axle, and keep that frame parameter when switching drive laws. Verify waypoint arrival in the authored production route test with its actual axle frame. A scene-level Rhai route program reads the route's composed point prims, waits for generic sensor enter events, and publishes current named-port guidance through the shared bridge. The route is not stored on the rover. User possession controls the local ControlLink, HUD, and manual-input session; possession alone does not stop an enabled route program. The shared controller requests ClaimControl when the operator first presses a bound intent on a target owned by another session. The existing control.authority.take Rhai policy decides whether that handoff is allowed. After the claim, the target-scoped semantic edge reaches the route policy and the held port command is applied.

Route editing resolves composed LunCoProgramAPI and inputs:subject bindings, including when the pointer context has no selected or possessed subject. Identity and hierarchy queries explicitly request attrs: []; omitted attrs reads every authored attribute. Discover programs through bounded, branch-local QueryUsdPrims batches: Rhai limits aggregate string bytes in nested values, so a whole CAD hierarchy level can exceed the limit even without attributes. Verify both a unique unpossessed route and ambiguity rejection, and exercise the active scene_interaction hook through native window input for UI acceptance.

2. High-level logic → rhai, event-driven

A a Scope applying LunCoProgramAPI child prim on the vessel, naming a .rhai scenario (uniform asset info:sourceAsset = @scenarios/my_supervisor.rhai@), does supervision and sequencing — never a control loop. React to events; don't poll or step.

fn on_event(me, evt, ctx) {
    if evt.name == "lander_touchdown" { /* advance the mission */ }
    if evt.name == "low_fuel" { notify_kind("Low fuel", "warn"); }
}

• Phase timing comes from the mission sequencer (wait, wait_for, wait_until) or from Modelica condition outputs connected to LunCoEvent prims, not dt counting: def LunCoEvent "LowFuel" { float inputs:trigger.connect = </Lander.outputs:low_fuel>; uniform token lunco:event:name = "lander_low_fuel"; uniform token lunco:event:severity = "warning" }.
• Do not write the vessel's command ports every tick from rhai. If you're tempted to, the logic belongs in the model (math) or the wiring (authority).

3. Sensors → USD library primitives, wired

The controller reads SENSORS, not the god-view body. Sensors are reusable prims in assets/vessels/sensors/ (imu.usda, altimeter.usda), referenced + mounted:

def "Altimeter" (prepend references = @../../vessels/sensors/altimeter.usda@</Altimeter>)
{ double3 xformOp:translate = (0, -3.3, 0); uniform token[] xformOpOrder = ["xformOp:translate"] }

A wire is a native USD connection, authored on the prim that CONSUMES the value — float inputs:descent_rate.connect = </Lander.outputs:velocity_y>, float inputs:altitude.connect = </Lander/Altimeter.outputs:range>. Wired inputs are live (they reach the solver). Physical constants a model needs (mass, inertia) come from the body's own ports (inputs:vehicle_mass.connect = </Lander.outputs:mass>, inputs:inertia_xx.connect = …) — USD-derived, not magic numbers.

A Modelica parameter is authored as a typed USD constant and is placed in the compile-time parameter set by contract classification. A runtime Modelica input is a live signal and needs a native USD connection or an explicit runtime writer; do not infer its kind from the USD spelling alone.

Rust publishes only generic built-in observations. The sensor asset and USD connections identify placement and topology; Modelica performs filtering, frame conversion, navigation, and control. Do not add a semantic sensor registry, a world-coordinate force special case, or a fallback port when the parsed Modelica contract does not match the authored scene.

4. User possession → the piloted signal + ControlLink

This is the key pattern. Do not build a bespoke gate.

• The GNC is INTERNAL (part of the model). A local or remote user is an external session that may possess the vessel; SessionRegistry and RBAC (may_take_control) arbitrate those user sessions. An authored mission or route program is scenario policy, not a possession session.
• The internal controller yields to whoever possesses via the piloted port: a read-only cosim port (PILOTED_BACKEND, lunco-cosim/src/ports.rs) that is 1.0 when any session owns the vessel (SessionRegistry::owner_of(...).is_some()), else 0.
• Wire it (float inputs:piloted.connect = </Lander.outputs:piloted>) into the model as the manual-input authority signal. Gate the pilot stick with it, then combine manual input with authored program/autopilot inputs through the model's explicit authority signals. Do not let a possession change replace or zero an active program's enable, target, or speed inputs. Possession owns the manual input claim; authored model policy owns the command mux.
• When a bound local control intent arrives while another session owns the target, the shared controller requests the existing generic ClaimControl transition. The authored control.authority.take policy decides whether the local session can take the endpoint; Rust does not special-case an autopilot role.
• The pilot's stick reaches external_throttle/pitch/… through the vessel's intent→port Controls scope (next section) when they possess. Camera-follow without taking control: follow(entity) (inserts a chase camera, no ControlLink).

Scene replacement clears possession claims for outgoing USD prims at the shared SceneTeardown boundary. Because claims use stable GlobalEntityId values, a replacement projection may reuse an id without inheriting the previous scene's driver; persistent non-scene ids are not cleared by that sweep.

AcquireControl and ReleaseControlSource are the single owner of the possession transaction: they validate the endpoint and local binding before changing SessionRegistry or ControlLink. A handoff releases prior claims for that session (except the selected target). Releasing possession removes the local control/camera binding and updates the manual-input authority; it does not write endpoint ports or stop an authored autopilot. Wire-applied commands update host authority only and never bind a remote session to the local camera. Explicit endpoint lifecycle stops remain separate from possession release.