Build Vehicle

Build a vehicle

A vehicle is a thin assembly: a kind = "assembly" Xform root that references library components and authors only its own decisions — poses, indices, scale, paint. Components own their defaults; variants choose components, they never restate them.

For script-authored assembly edits, the dynamically reloadable assets/scripting/tools/assembly_builder.rhai library provides semantic frame/shape construction, placement, Cube and composed collision alignment/clearance, referenced-part mounting, existing-mount frame realignment, and body/joint plans. A referenced assembly uses referenced_instance_plan (or its targeted form), then applies select_variants_plan only after the reference children are queryable. Parameter edits use parameter_plan and the same typed ApplyUsdOps boundary as the Editor; the planner is generic and does not know vehicle names or paths.

When iterating a referenced component in Editor, use component_editor::selected_update_context to preserve the exact preview, document, path, and generation, then use component_editor::update_plan with the component recipe from the owning Twin. Review and commit its one typed change set before checking the composed rover; do not put vehicle-specific recipes or a component registry in Rust.

Mission-specific recipes and study assets belong in the Twin that owns them, rather than in the core asset library. A Twin tool may compose these generic helpers and supply its own explicit paths and study values, but it must remain Rhai-owned and use the proposal/journal boundary. Keep component defaults in reusable USD components and author vehicle-specific choices in the Twin assembly.

When a vehicle part is already attached and a socket or plug frame moves, use assembly_builder::mount_frame_realignment_plan with the exact authored paths. The tool composes nested translate/rotateXYZ unit-scale frames, updates the part and its recorded joint anchor atomically through the review boundary, and rejects invalid topology or non-rigid frame data before any USD edit.

For an AI- or human-led vehicle build, use model_authoring::model_context before choosing parts and readiness_report after the component contracts are composed. Use port_graph to inspect the standard USD endpoint surface and wiring_plan to produce one typed, generation-checked connection plan for Modelica/Rhai/physics endpoints. Use scene_recipe for the surrounding test scene and publish_component when a validated part is ready for explicit Save-As. These are dry Rhai facades; keep wheel/rover policy and dimensions in the owning Twin and send all USD operations through the existing journal path. See scripting-guide.md for the call sequence.

Working exemplars, simplest first: assets/vessels/rovers/skid_rover.usda (4-wheel skid), ackermann_rover.usda (steering), six_wheel_rover.usda (per-wheel port wiring + driveLaw variant), six_wheel_independent.usda (fully authored per-wheel mix), rocker_bogie.usda (linkage + gear-joint differential), rucheyok/ (Z-forward, Modelica electrical).

Reuse-first vehicle audit

Before authoring a new vehicle, identify the closest shipped assembly and read its component references, variant axes, composing scene, and runtime test. Use the existing assembly as the structural template and change only the authored vehicle facts: poses, dimensions, mass properties, topology, bindings, and parameters.

Classify the request before editing:

existing generic mechanism -> compose/configure it
missing vehicle asset       -> author USD assembly/components
missing equation            -> extend/reuse Modelica package
missing engine behavior     -> prove with a focused fixture before Rust
missing evidence            -> add an authored test and production run

Do not infer an engine gap from the absence of a mission-specific vehicle file. Do not use a tutorial or presentation-only vehicle as the production physics contract without checking its consumer and test.

The component library (assets/components/)

Minimal rover

def Xform "MyRover" (
    kind = "assembly"
    prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysxRigidBodyAPI",
        "PhysicsMassAPI", "PhysxVehicleContextAPI",
        "LunCoCatalogAPI"]
)
{
    uniform bool lunco:spawnable = true
    float physics:mass = 1000.0
    float3 physics:diagonalInertia = (1028, 1354, 341)   # author it — see skid_rover

    def "Controls" ( prepend references = @lunco://vessels/control_profiles.usda@</RoverControls> ) {}

    def Cube "Chassis" ( prepend references = @lunco://components/mobility/chassis/box_chassis.usda@</Chassis> ) {}

    def Cylinder "Wheel_FL" (
        prepend apiSchemas = ["PhysxVehicleWheelAttachmentAPI", "PhysxVehicleWheelAPI"]
        prepend references = [
            @lunco://components/mobility/wheel.usda@</Wheel>,
            @lunco://components/mobility/suspensions/standard.usda@</Suspension>,
        ]
        variants = { string tire = "regolith" }
    )
    {
        double3 xformOp:translate = (-1.0, -0.15, -1.225)
        uniform token[] xformOpOrder = ["xformOp:translate"]
        int physxVehicleWheelAttachment:index = 0
    }
    # …Wheel_FR/RL/RR: index 1/2/3, mirrored translates…
}

• PhysxVehicleContextAPI on the root ⇒ MobilityRoot + OutputPorts + authored ports; MobilityRoot identifies the vehicle and OutputPorts indexes the generic command/output surface.
• Vehicle motion policy is authored in the composed Modelica/Rhai controller. Skid, Ackermann, crab, and independent-wheel modes are programs that publish different named outputs; they are not Rust type dispatch.
• Wheel→port wiring is a USD connection: each wheel connects float inputs:drive.connect and, where applicable, a heading-joint input to an authored float outputs:<port> on the controller/network boundary.

Wheel physics: one parameter set, two realizations

Both wheel kinds read the SAME attributes through ONE strict reader (lunco-usd-sim-authoring/src/wheel_params.rs). Only force generation differs:

• raycast (default): analytical spring + traction force at the hub. Requires a composed suspension.
• physical: authored PhysicsRevoluteJoint targeting the wheel via physics:body1 ⇒ rigid body + solved shaft torque boundary. That joint IS the switch — the drivetrain variantSet on the 4-wheel rovers just references the component that authors (or omits) the joints.

One authored mechanical network, so both realizations consume the same solve. DCMotor.mo solves winding current, back-EMF, electromagnetic torque, terminal voltage/current, and heat from its authored electrical pin and measured speed. Its solved torque crosses the authored generic Torque boundary into GearRatio.mo and AvianShaft.mo. The physical wheel applies that torque across its revolute joint; the raycast wheel uses the same solved torque in its contact-plane spin equation:

F_long = clamp(k_slip · (ω · radius − v_forward), −μN, +μN)
ω̇ = (τ_motor + τ_brake − F_long · radius − c_bearing · ω) / I

Speed is therefore determined by the authored motor, gearbox, complete wheel assembly inertia, and tire load, not by a second Rust motor curve or a copied no-load-speed clamp.

The motor speed input is connected to the engine's solved wheel speed, and its torque output is connected through the generic authored boundary. Both realizations consume that same solved network; no Rust motor or second shaft state mirrors it.

Strictness: every drivetrain/tire attr is required; a wheel missing any refuses to spawn and the error names ALL missing attrs. That now includes physxVehicleWheel:dampingRate (bearing + rolling drag): it is a physical property of the hub, so it is authored, never inferred from the drive torque — drive torque is not derived from unrelated values. physxVehicleWheel:moi is the complete authored tire-and-drivetrain assembly inertia; when omitted, the documented solid-cylinder derivation ½·m·r² applies. You never author them per vehicle — composing wheel.usda + a tire + (for raycast) a suspension is the complete set. If your wheel refuses to spawn, you dropped one of those three arcs.

Tuning: all wheel params carry schema-level slider hints, so every wheel gets Inspector sliders with zero per-asset authoring (SchemaRegistry::ui_hint → produce_usd_param_view; a per-asset authored customData still overrides — see author-usd-component).

To reach one wheel: select the rover, then Alt+Shift+click the wheel — that drills the Inspector to that subpart's own PRIM (crates/lunco-luncosim-edit-ui/src/selection.rs). Plain Shift+click is the multi-select extend and retains the existing selection; it does not drill. The drill also requires the rover to already be the primary selection.

Wheel, suspension, tire, and authored vehicle-control edits go ApplyUsdOp SetAttribute → document → in-place resync. UsdSimPlugin registers the vehicle wheel owner with lunco_usd_bevy_core::live_edit::UsdLiveEditRegistry; that owner claims the wheel, suspension, tire, and authored vehicle-control attributes and refreshes the live components from the composed stage, preserving the current entities and joints. Other edits that touch a rigid body, collider, or joint promote to a stage-wide reset so external joint endpoints are retired and admitted together. The physics owner removes graph edges before joint components and collider markers; a failed reset holds the active simulation and reports the owner error. Never poke WheelRaycast/RevoluteJoint components directly; the next document change would overwrite you.

Delivery order

Author the vehicle and its test in the owning Twin. Keep generic components and engine regression scenes in the shared LunCo asset library only when they are reusable beyond one mission or presentation. A scene-specific vehicle should reference the shared components rather than make the shared library depend on a one-off scene.

Build the smallest authored-controller, raycast rover path before adding power, thermal, autonomy, or a physical drivetrain. For a lunar presentation, start with the existing skid_rover on the shared lunar_surface base: it has the complete command surface and the least moving runtime parts. The first acceptance gate is scenes/tests/drivetrain_parity.usda: its Rhai scenario settles, drives both wheel realizations, and emits the real verdict DRIVETRAIN PARITY: PASS|FAIL. A rover that merely composes, or two rovers that are both stationary, do not pass.

Only after that gate passes, add one concern at a time:

1. terrain/course and presentation cameras;
2. the vehicle-specific assembly or rocker-bogie morphology;
3. the authored Modelica drive law, proved by scenes/tests/modelica_drive_law.usda (MODELICA DRIVE LAW: PASS|FAIL proves the composed output surface and motion);
4. battery, generation, thermal, then autonomy/story behaviour.

Do not combine these stages. A failed rover with a new terrain, Modelica model, and scenario has too many owners to diagnose; restore the last passing stage before adding the next one.

Coordinate contract for mounted mechanisms

For an antenna, camera gimbal, solar head, or other rover-mounted tracker, declare one coordinate contract before tuning: world axes, rover/mount local axes, joint positive axes and order, and the physical boresight. Derive the Modelica setpoint from that contract; never copy a -Z forward formula into a component whose geometry points along another axis. Validate the target vector, setpoint, measured joint angles, and rendered boresight together after a full scene reload.

For a fixed photovoltaic deck, there is no tracker controller to tune. Reference components/power/solar_panel.usda once, author its inputs:area and placement on the rover, use the component's +Y normal unless a different face is explicit, connect its connectors:p to the battery, and include both in the rover-root CollectionAPI:components collection with the driven loads. Keep the panel's visual frame and cell surface under that same mounted component; do not add a second rigid body or a disconnected visual proxy. A horizontal deck uses the component's +Y collecting face. Verify power_out, cos_incidence, battery current and soc_out, not only that a panel prim appears in the hierarchy.

Stability before tuning

If a lunar rover tips at launch, inspect the assembled load path before changing solver settings or adding visual smoothing. High-grip contact forces applied at the wheel plane create a real pitch moment when the authored physics:centerOfMass is high. The vehicle-level acceptance test should report travel, maximum tilt, detached descendants, and fixed-step sample count. A repeatable tilt failure is a geometry/mass/traction defect; a visual jitter with the body and its labels moving together is a coordinate/transform defect and needs composed transform inspection.