Visualize Physics With Shaders

Visualizing physics values with shaders

A visual is a consequence of physics, not a performance of it. A strut turns red because it is carrying load, on the same tick and by the same number the solver computed. Nothing samples a clock, nothing tweens, and nothing in rhai paints anything.

The chain is three links, each owned by the layer that knows the fact:

Modelica / avian  ──►  a port  ──►  a USD connection  ──►  a WGSL uniform
   computes it        publishes it     wires it            draws it

The mechanism

There is no shader-specific plumbing. Shader parameters are ordinary port sinks: rewire_usd_connections turns any inputs:*.connect into a SimConnection without caring what the target is, propagate_connections writes it through PortRegistry, and lunco-render-bevy's SHADER_PARAM_BACKEND receives it into ShaderLook::live, which rebind_changed_shader_look drains to the GPU. Same graph as a thruster force or a battery load.

Connected names are seeded as empty slots in ShaderLook::live(). The compiled wire resolves the slot at a topology boundary and writes by handle thereafter; the first sample does not change the slot layout. Use set_value for authored parameters and set_live for engine-owned updates so topology identity changes only with the authored parameter shape.

Recipe

1. Declare the parameter in the WGSL. The engine reflects the Material struct — field names, offsets, and the //!@ annotations — straight out of the file. A field that isn't declared here does not exist.

//!@ui      base_color  color "Strut colour"
//!@default base_color  0.55,0.57,0.60
//!@ui      load_frac   0 1   "Load fraction (driven)"
//!@default load_frac   0.0
struct Material {
    base_color: vec4<f32>,
    load_frac:  f32,
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // The RAMP is a look decision and belongs here. The NUMBER being ramped is a
    // physics result and does not.
    let hot = vec3<f32>(1.0, 0.15, 0.05);
    return vec4<f32>(mix(material.base_color.rgb, hot, material.load_frac), 1.0);
}

2. Find the port that already publishes the physical result. Bodies, colliders and joints expose their state as ports because they exist — a PrismaticJoint's force is the spring's own reaction, in newtons, computed by the solver that integrates it. Nothing needs authoring to make it available, and a model written to restate it would be a second copy of the same fact.

3. Wire it on the BOUND GEOMETRY, and normalise ON THE WIRE. The sink's SSP linear transformation (lunco:factor:<port> / lunco:offset:<port>) turns the raw physical quantity into the shader's 0..1 parameter, so the rating is one number sitting next to the wire that uses it. The shader saturates.

def Mesh "LegPX_Strut" (prepend apiSchemas = ["MaterialBindingAPI"])
{
    rel material:binding = </Looks/StrutMat>
    float inputs:load_frac.connect = </DescentLander/LegPX_Spring.outputs:force>
    float lunco:factor:load_frac = 0.00066667   # 1 / 1500 N rated
}

A lunco:factor: is a UNIT CONVERSION, and nothing else. It carries the rating that takes newtons to a 0..1 fraction. Never put a SIGN in it. Which way a mechanism travels is a fact about the joint, authored once in its physics:localRot0; a sign in the factor states it a second time, and makes the render wiring silently depend on an orientation it never names. If a wire needs a negative factor to look right, the joint's axis is backwards — fix it there.

4. Verify. read_ports on the prim lists every declared parameter with its live value; the inspector shows driven rows greyed out. If the value moves in read_ports and the colour doesn't, the problem is the shader; if it doesn't move there, the problem is the wire.

The same wire drives a LIGHT, and a transform

A shader uniform is not the only render-side sink. lunco-render-bevy's SCENE_PROPERTY_BACKEND (scene_ports.rs) exposes the properties a simulation legitimately drives, as scalar In ports on the prim that carries the component:

def SphereLight "PlumeLight"
{
    float inputs:light_intensity.connect = </…/Photometry.outputs:intensity>
    float inputs:light_radius.connect    = </…/Photometry.outputs:radius>
}

The engine plume is the worked example end to end: propulsion and nozzle outputs feed LunCo.Propulsion.PlumePhotometry, which derives the physical free-jet length, visible length fraction, luminous power, and source radius. USD connects that length fraction and the light outputs to a fixed-capacity WGSL cone and its child light. WGSL owns the perceptual width response and flicker; Modelica owns the physical length and photometry; Rhai supplies stimulus and verdicts only. Zero thrust is therefore dark without a script-side visual mirror.

Aggregate propulsion with multiple nozzles

When a propulsion model publishes cluster-total thrust and flow but the vehicle has one visual nozzle per engine, set PlumePhotometry.engine_count to the configured nozzle count. Keep the input thrust and flow aggregate; supply each nozzle's own exit radius and area. The photometry model divides the extensive cluster values before deriving the per-nozzle momentum flux, exit pressure, and light output. Connect the same per-nozzle results to one fixed flame pair and one light at each nozzle. Source the count from the Twin's typed engine-instance configuration and verify the authored model parameter against it. Do not send the undivided cluster light to every nozzle or calculate per-engine plume state in Rhai.

Set the fixed envelope's nozzle end on the measured bell exit plane and point its narrow end down the exhaust axis. Start its throttle and light intensity at zero; the simulation's live outputs reveal the flame during a burn. Keep vehicle-specific material paths in the vehicle composition layer; a reusable nozzle component must not point at a particular vehicle's absolute material path.

Prove a plume is driven by the simulation

An authored connection proves only that a route exists. Before reporting a visible, simulation-driven flame, confirm the continuous model compiles and produces samples, then compare an idle sample with a powered sample:

• At zero delivered thrust, render_throttle, visual_length_fraction, and intensity are zero. radius may remain at its authored idle value; zero light intensity and the shader's zero throttle keep the plume dark.
• During a burn, those three outputs are finite and positive, and the powered values reach the cone and light through the composed USD connections.
• Read the composed ports on the photometry model and at least one flame/light sink, then inspect the rendered vehicle to confirm the cone responds and the light affects nearby terrain. A solver sample proves the values; a rendered inspection proves the visual result.

If the model is unbalanced or has no run, report the authored wiring as present and the dynamic/visual result as unverified. Do not make Rhai animate the flame to hide a missing solver result. The Griffin status example is in its Twin's contracts/implementation_gaps.md.

A driven Transform is not a licence to animate. A transform WIRED to a port is a consequence — some model or joint published the number and the stage shows where it came from. A transform COMPUTED per tick in a script is animation, and is still forbidden. Also: drive a transform only on a prim nothing else moves, or the wire fights the USD projector, a rigid body, or a joint.

Why the wire goes on the gprim, and what it costs

A UsdShade input belongs to the material, which is shared by every prim bound to it. A driven value is the opposite — per-instance; four legs each report their own load. So the bound geometry is where the meaning lives, and the engine makes that prim's material private (ShaderLook::unshared) so one leg's glow does not paint its three siblings.

Be honest that this is a LunCo convention, not portable USD. Attribute connections are core Sdf, so this is spec-legal and round-trips — but inputs: is a UsdShade convention, and connectability is gated by UsdShadeConnectableAPIBehavior, which registers Shader/NodeGraph/Material and never a Gprim. Hydra's HdMaterialNetwork never walks this edge; usdchecker's shading validators never see it; Omniverse and MaterialX (<geompropvalue>) ignore it. The material:binding chain is portable, the drive is not.

The standard answer to "one material, varying per gprim" is primvars: plus a UsdPrimvarReader node — and it would delete unshared and the private material outright. We don't use it yet because the binder resolves a single shader, not a network, so a reader node would have nothing to evaluate it. That is a deliberate deferral with a known migration path, not the absence of a standard.