Author Usd Physics

Authoring physics in USD

Physics is authored in USD and projected onto avian. USD is the source of truth; the ECS is the projection. Use maintained UsdPhysics schemas for topology, limits, and commandable drives. When USD has no material schema for a physical concept, use the narrow LunCo applied API that owns that concept. Do not add a LunCo schema when standard USD already owns the fact.

For a physical landing member, apply PhysicsDriveAPI:linear to a PhysicsPrismaticJoint. Author the drive's stiffness, damping, maxForce, and explicit force type; targetPosition and targetVelocity retain the standard USD defaults unless the asset needs to state them explicitly. The native Avian joint is the sole axial mechanism in the existing substep schedule. Do not duplicate standard fields under lunco:*. Missing or invalid fields fail projection; they are never replaced by a target, force cap, or solver-resolution workaround.

Native joint angle and displacement commands preserve the configured drive model and force/torque limit. They enable the motor and change its position target with zero target velocity; author drive gains and limits through the standard USD drive owner rather than through command-side tuning.

Omitted joint limits retain standard unbounded travel. The native port adapter maps lower negative infinity and upper positive infinity to absent bounds; malformed nonfinite limits remain invalid. Do not add artificial finite travel limits to make a valid unbounded joint accept a command.

Startup joint topology is prepared while the shared fixed clock is held. The BigSpace physics bridge seeds authored body poses in PreUpdate; USD joints are projected in JointPreparation during Update, after USD simulation projection and before the generic JointAdmission owner. This phase must not wait for a first physics step to resolve bodies or seat a joint.

Initial body admission validates raycast-wheel support footprints against the composed Avian collider geometry and its hit normal. It does not require a LocalGravity sample from a fixed cycle that has not been admitted yet. Keep authored-pose validation in lifecycle preparation; the first synchronized physics cycle begins only after the complete admission set is ready.

For asset-level checks, the authored assembly_audit tool can inspect explicit composed joint body relationships, cardinal axes, optional local frames, rigid-body/joint coverage, and mass/inertia/collider manifests. Use those reports to diagnose authored topology before changing solver settings. Pass the exact Editor document id first to each stage-reading helper; () explicitly selects the mounted live scene, not the focused preview. The tool does not infer a body from a name, turn a raycast wheel into a rigid body, or replace the standard USD physics owner. For a single explicit decision per maintained part, use assembly_audit::physicality_report(doc, manifest). Entries choose physical or visual-only; physical entries reuse the existing body/joint and collider/mass fields, while visual-only entries require a non-empty reason and must have no composed collision envelope. Unknown roles, duplicate paths, missing prims, and incomplete coverage are errors. This is Rhai policy and orchestration; it does not add a second collider reader or Rust asset rule.

Live joint detachment is one lifecycle

DetachJoint is the generic entity-detach command. It is deliberately not limited to entities carrying PhysicsJointLink: an ordinary non-joint target uses the normal entity-removal path. A target carrying native or pending joint state is classified as a joint and must use the physics lifecycle marker. The command records any authored endpoint invalidation and never directly removes a native joint. The lunco-usd-avian-joints::JointAttachPlugin consumes that marker at its Update boundary and performs one transaction in this order:

1. retire the Avian JointGraph edge and its PhysicsIslands entry;
2. remove the native or pending typed joint and JointComponentId;
3. release the transient joint collision filter;
4. despawn the now-disposable joint entity.

The retirement owner only runs when a PhysicsJointDetachRequested marker is present. Idle updates skip its exclusive graph transaction and world query. Joint admission readiness is also gated by one combined query over the existing PendingUsdJoint and PendingJointAdmission markers. The owner rechecks the scene projection and endpoint readiness before each pending batch is admitted, while settled updates with no pending joint skip that scan.

Scene teardown uses the same graph-retirement helper. This shared owner is what prevents a component-removal observer and a recursive despawn from unlinking one island edge twice. A command or Twin script must never implement a second joint detach path, disable JointDisabled as a substitute, or infer joint completion from the command acknowledgement; verify that the joint entity is gone and both endpoint bodies continue finite stepping. If a target has joint state but no PhysicsJointLink, the command warns and rejects it; the authored topology linter is the repair/diagnostic path. Persistent intent journals the typed USD active-state/remove operation separately, while Interactive remains a throwaway live transition.

When an Editor workflow creates a new moving part, use assembly_edit::rigid_body_plan for the explicit body schema and mass facts, then add the shape, collider, and local transform in the same proposal. Use assembly_edit::revolute_joint_plan for a rotating part: pass both body paths, both authored frame anchors and quaternions, the cardinal joint axis, ordered degree limits, and the collision policy. These helpers return typed operations for review; they do not infer bodies from hierarchy or drive a mechanism with Euler poses. Use assembly_edit::fixed_joint_plan for a rigid adapter: it requires the same explicit two body paths, two local anchors, two local quaternions, and collision policy, and returns a standard PhysicsFixedJoint plan without mutating the document.

For higher-level construction, use the dynamically reloadable assembly_builder Rhai library. Its frame_plan, cube_plan, cylinder_shape_plan, movable_cube_plan, component_bundle_facts/component_bundle_plan, existing_rigid_body_plan, and hinge_plan compose the same explicit standard USD facts for new or referenced parts; it does not promote a completed body or reuse an occupied standard joint identity, while its placement and cube edge-alignment plans reject ambiguous parent/frame assumptions before the proposal reaches the USD owner. Keep the generated plan in one reviewed change set. A component bundle may author PhysicsMassAPI on its root and collision APIs on its geometry, but it does not infer a rigid body or joint; use the explicit body/joint/mount planners when the part is movable. A successful Rhai plan is not permission to omit the frame, collider, mass, or generation contract.

For an existing generic component whose geometry, frames, and mass must change together, use component_editor::update_plan with an explicit bundle recipe. Its component_editor::update_context/selected_update_context helpers are read-only discovery; the returned plan still goes through the normal proposal/review/commit path. The planner preserves topology and material ownership and rejects role drift, so it is not a replacement for explicit body or joint authoring.

For physical placement, use assembly_builder::place_with_clearance_plan with explicit Cube envelopes, or assembly_builder::place_with_collision_clearance_plan with exact moving and blocker body paths for referenced, Cylinder, Mesh, or compound bodies. The general tool reads aggregate QueryUsdPrim { collision_bounds: true } results from the shared collision owner and requires a translation-only common parent chain. Both paths reject overlap, insufficient gap, duplicate blockers, and ambiguous frame/geometry data before proposal. Do not rely on visual separation or an unreviewed generated USD transform to establish clearance. For deterministic mating of non-Cube bodies, use the companion align_collision_centers_plan or align_collision_edges_plan with exact paths and an explicit axis/edge/gap; these plans preserve authored physics facts and still require review before commit.

For reusable referenced parts, use assembly_builder::find_compatible_socket and assembly_builder::mount_component. These helpers select authored socket relationships and derive the reflected fixed/revolute/prismatic joint; the existing AttachComponent owner remains responsible for plug-frame math, reference lowering, occupancy, and atomic journalling. Do not copy a reference and guess a transform when the component already advertises a mount plug.

For a part that is already mounted, use assembly_builder::mount_frame_realignment_plan with the exact host, socket, part, and recorded-joint paths. It is a dynamic Rhai plan for nested canonical rigid frame composition and emits the part transform plus both exact joint anchors as one reviewed operation set. It preserves topology and fails before proposal on missing/ambiguous relationships, wrong plug/body identity, unsupported frame stacks, malformed values, or non-unit scale.

When a model is a reusable referenced assembly rather than a socket attachment, use assembly_builder::referenced_instance_plan or assembly_builder::referenced_instance_targeted_plan when the source prim must be explicit. Then wait for its composed children before using assembly_builder::select_variants_plan. This keeps first-use asset loading separate from the variant recompose and makes missing parents, occupied identities, and invalid targets fail in Rhai before review. Parameter edits use assembly_builder::parameter_plan; the resulting typed SetAttribute ops go through the same proposal/journal boundary as every other authored edit.

Mission-level recipes may compose these generic helpers through a Twin-local tool library. Keep those recipes and their study values in the owning Twin, not in the core asset library, and keep their output to explicit generic USD operations. The core should provide only reusable component facts, topology, placement, and typed-op validation.

Collision geometry and derived NURBS proxies

QueryUsdPrim { collision_geometry: true } reads the composed collider through the same USD-to-Avian geometry reader used by projection. Use it when a requirement must compare the backend shape to its visual or design geometry; authored radius/height, geometry_bounds, and collision_bounds answer different questions. This query predicts the geometry Avian will receive from the current composed USD. It does not prove that a live ECS entity has completed projection or is currently contacting the world.

For UsdGeomNurbsPatch, use the read-only PlanNurbsCollisionProxy query and the shared nurbs.rhai proposal. Pass max_refinement_delta_m in canonical metres. This bounds the sampled change between two successive tessellation levels; it is a deterministic convergence criterion, not a certified maximum distance from the exact rational surface. Review the proposal that creates an invisible, source-linked UsdGeomMesh carrying standard mesh-collision APIs. Projection re-cooks the source and rejects stale or edited derived geometry. Do not author a separate collider approximation by hand or treat this threshold as a CAD accuracy guarantee.

The Avian mesh adapter advertises its implemented USD approximation modes via AvianMeshCollisionApproximations: none, convexHull, and convexDecomposition. none is valid only for static or kinematic bodies. Other standard USD tokens remain valid authored values, but this adapter rejects them until it can realize their stated semantics; it does not silently substitute another shape.

The local avatar is a runtime kinematic camera embodiment, not an authored rigid body. Its MoveAndSlide capsule reuses the standard UsdPhysics colliders projected by the Avian bridge in the active BigSpace frame. Do not add an avatar collider schema or a second collision representation; see the BigSpace physics boundary for the frame conversion and Twin-scoped traversal policy.

1. A joint is TWO FRAMES, not an axis

This is the single most expensive thing to get wrong, and it fails silently.

A UsdPhysicsJoint is defined by a frame on each body:

physics:axis can only name a cardinal axis. That is exactly why localRot exists: it is how a mechanism that is not axis-aligned — a landing leg raked 25° off vertical — says where its axis really points.

Both halves must cross into the engine. Every avian joint except the spherical constrains relative ORIENTATION through basis1/basis2. An identity basis therefore demands its body sit square to the other body. Carrying the rake in the axis alone aims the slider correctly and still wrenches the strut 25° out of true — the constraint is violated from the first step, the solver resolves it impulsively through the strut's lever arm, and the vehicle disassembles at kilometres per second.

The rule when a body rests at an angle: if body1 is rotated relative to body0 in the authored rest pose, that rotation lives in the FRAMES. The joint holds rot0 · localRot0 == rot1 · localRot1, so author whichever side is needed to make that identity true at rest.

# LegPX is raked +25° about Z (its own xformOp:rotateXYZ).
def PhysicsPrismaticJoint "LegPX_Spring" (
    prepend apiSchemas = ["PhysicsDriveAPI:linear"]
)
{
    rel physics:body0 = </DescentLander>
    rel physics:body1 = </DescentLander/LegPX>
    uniform token physics:axis = "Y"          # cardinal, IN the joint frame
    quatf physics:localRot0 = (-0.216440, 0, 0, 0.976296)   # 205° about Z: +Y down the strut
    quatf physics:localRot1 = (0, 0, 0, 1)                  # the same 180° flip; the leg body
                                                            # already carries the 25°
}

Quaternions in USD are (w, x, y, z). Angles — physics:lowerLimit, upperLimit, coneAngle0Limit, coneAngle1Limit — are degrees.

The diagnostic

The loader measures every joint against its authored frames at build and reports a violation, seating the body only where the constraint determines it uniquely:

[usd-avian] joint /…/PadNX_Weld starts violated by 0.000 m / 0.436 rad — seating
`/…/PadNX` onto the authored joint frame. frame0: localPos0=… localRot0=…,
frame1: localPos1=… localRot1=…, body0 at …, body1 at …

0.436 rad is 25°. An angular violation on a raked mechanism is almost always a missing physics:localRot1: body0's frame was authored off-cardinal and body1's was left at identity, so the joint demands body1 sit square to body0.

Position is checked for every joint type. Orientation is checked and seated only where all three rotational DOF are locked (fixed, prismatic); a revolute or spherical joint leaves rotation free by design, so it is reported and left to the solver.

1b. A rotating assembly is joints plus a controller — never Euler animation

An antenna, solar panel, camera gimbal, arm, or other tracking head has two separate concerns:

1. Mechanism: each moving frame applies PhysicsRigidBodyAPI and is joined to its immediate predecessor with a standard PhysicsRevoluteJoint.
2. Setpoint law: a Modelica program computes radians and wires them to the joint's native inputs:angle port. The cosim joint backend owns the position motor only while that port is wired.

The assembly owns its own hinges. Compose the assembly's root directly onto the host body and keep its internal joints and controller connections relative to that root. The host supplies no duplicate attachment joint; it only chooses to compose the assembly. Keep the visible mechanism under a unique child path.

This is the direction of dependency: a higher-level rover, lander, tower, or ground station knows it installs an antenna; the antenna knows only its own frames, joints, ports, and Modelica controller. The lower-level assembly never names Rover, Lander, or any other concrete host.

Never drive a tracking mechanism by xformOp:rotateXYZ. An authored rest orientation is allowed where it belongs in the joint frames; continuous yaw or pitch is a joint state. Euler writes bypass contacts, limits, solver state, and the measurable angle output, then race the physics bridge.

Coordinate contract for direction-tracking mechanisms

Before authoring or changing a tracker, write down and validate the complete chain: world direction convention, mount-frame conversion, each joint's positive axis/order, and the physical boresight of the final geometry. Do not assume the vehicle's conventional -Z forward is the antenna or panel boresight: inspect the composed asset. Derive the Modelica vector-to-angle equations from that actual geometry, then verify live that the target vector, controller setpoint, joint angle, and visible boresight agree. A controller's self-error/"locked" output alone is not evidence of physical pointing; it can validate the same wrong convention it commanded.

PhysicsRevoluteJoint is a generic mechanism, not a wheel marker. Do not infer vehicle topology from an antenna, solar tracker, or robotic-arm hinge.

2. A prismatic joint CARRIES MOMENT

A PhysicsPrismaticJoint locks all three rotational DOF. It is a slider, not a pin. This has a consequence that is easy to miss and impossible to see in a screenshot:

Because it carries moment, a sprung leg has two ways to absorb a landing: slide along its axis, which is the one you designed, or bend its angular lock, which you did not. The second is always available, and the solver will take it whenever a stray contact makes it cheaper.

The failure: a second contact steals the load path

A suspension has exactly one intended load path — foot → spring → chassis. Give the leg any second way to reach the ground and that path wins, because it is rigid and the spring is not. A contact that only sometimes touches is worse than one that always does: it latches on the first frame it grazes and never lets go.

The diagnostic is a conjunction: displacement remains zero, the joint force is absent or near zero under load, and the joint's angular lock is non-zero. Measure the angular error together with the reaction force; angular error alone is not enough because the joint solver is elastic.

Ground clearance is a load-path property, not a styling one. A raked box strut's bottom corner hangs half_thickness * sin(rake) below its tip, so a footpad centred on that tip clears it by almost nothing. Millimetres of margin on a metres-long vehicle is zero margin: a fraction of a degree of tip puts the strut on the ground. Size the foot so it is the only thing that can touch, by a margin no small rotation can close — and beware that half-measures make it worse, because a deeper foot demands a larger leg rotation to reach the ground, which brings the strut down faster than the foot drops.

Diagnosing it

Measure the angular lock directly from the two body orientations. A prismatic holds rot0 · localRot0 == rot1 · localRot1; the angle between the two authored joint axes is its constraint error. Then isolate contacts and inspect the composed collider geometry. A raked box can contact the ground with a corner; prefer a measured primitive or a deliberately authored proxy when the foot must be the sole load path. Change solver and friction parameters only after the geometry and contact ownership are verified.

Where a joint's rest position sits

Anchors left unauthored are DERIVED from the transform hierarchy, which puts displacement at exactly 0 in the authored rest pose. A leg authored -0.8 .. 0.0 therefore rests on its upper limit and travels one way only — by design: 0 is the fully-extended pose the geometry is drawn in, and the ground can only compress it.

So a stroke pinned at 0.0000 is not evidence the limits are backwards. Check the load path first. Widening the limit to make a jammed leg move buries the actual defect under a range the mechanism never needed.

Anchors are also why you cannot freely move a body to fix clearance. The anchor is derived from the body's origin; move the origin and you move the joint's zero, silently preloading the spring by the axial component of the shift. Change the part's extent, or the mating part, not the sprung body's origin.

2b. Author the body as a FRAME, with real dimensions

Make the body a frame, not a mesh

A prim that is both the rigid body and the geometry cannot host children, because its shaping transform applies to them too. Give the body its own frame and put the geometry inside it:

def Xform "LegPX" (prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsMassAPI"])
{
    # origin at the hull anchor, local -Y down the leg
    double3 xformOp:translate = (2.519, 1.388, 0)
    double3 xformOp:rotateXYZ = (0, 0, 25.0)
    uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ"]

    def Cylinder "Strut" (prepend apiSchemas = ["PhysicsCollisionAPI"])
    {
        uniform token axis = "Y"
        double radius = 0.075
        double height = 7.05                       # spans local y 0 .. -7.05
        double3 xformOp:translate = (0, -3.525, 0)
        uniform token[] xformOpOrder = ["xformOp:translate"]
    }
    def Cylinder "PadPX" (prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsCollisionAPI"])
    {
        double3 xformOp:translate = (0, -7.2, 0)   # 0.15 below the strut's tip
        ...                                        # + a joint, below
    }
}

Now every part of the leg is placed by how far down the leg it sits, in ONE frame, next to its neighbours. "The foot is below the strut's tip" is something a reader can see and a linter can compute. Place them in world coordinates instead and you have written the same geometry twice, in two frames — and the copies drift.