@jgengine/core 0.18.1 → 0.19.0

package/dist/physics/aircraftDynamics.js

@@ -0,0 +1,704 @@
+import { uniformGravity } from "./gravityField.js";
+const DEFAULT_SUBSTEP = 1 / 240;
+const SEA_LEVEL_DENSITY = 1.225;
+/** Quaternion for a heading about world up, forward `[sin h, 0, cos h]`. */
+export function aircraftHeadingQuaternion(heading) {
+    return [0, Math.sin(heading / 2), 0, Math.cos(heading / 2)];
+}
+/**
+ * Quaternion from heading, nose-up pitch and right bank, rad — the inverse of a step's `heading`/`pitch`/`bank`.
+ * Matches three.js `Euler(-pitch, heading, bank, "YXZ")`.
+ */
+export function aircraftAttitudeQuaternion(heading, pitch, bank) {
+    const [x1, y1, z1, w1] = aircraftHeadingQuaternion(heading);
+    const hx = -pitch / 2;
+    const [x2, w2] = [Math.sin(hx), Math.cos(hx)];
+    const hz = bank / 2;
+    const [z3, w3] = [Math.sin(hz), Math.cos(hz)];
+    const ax = w1 * x2 + x1 * w2;
+    const ay = y1 * w2 + z1 * x2;
+    const az = z1 * w2 - y1 * x2;
+    const aw = w1 * w2 - x1 * x2;
+    return [ax * w3 + ay * z3, ay * w3 - ax * z3, az * w3 + aw * z3, aw * w3 - az * z3];
+}
+function prepareSurface(surface) {
+    const [ax, ay, az] = surface.at;
+    let [nx, ny, nz] = surface.normal ?? [0, 1, 0];
+    nz = 0;
+    const nl = Math.hypot(nx, ny) || 1;
+    nx /= nl;
+    ny /= nl;
+    // Span s = n × forward; the chord always runs along body forward.
+    const sx = ny;
+    const sy = -nx;
+    const sz = 0;
+    // The lever arm at × n says which way this surface's lift turns the body; controls are signed from it.
+    const mx = ay * nz - az * ny;
+    const my = az * nx - ax * nz;
+    const mz = ax * ny - ay * nx;
+    const signed = (gain, axis) => (gain === undefined || Math.abs(axis) < 1e-9 ? 0 : Math.sign(axis) * gain);
+    return {
+        ax,
+        ay,
+        az,
+        nx,
+        ny,
+        nz,
+        sx,
+        sy,
+        sz,
+        area: surface.area,
+        slope: surface.liftSlope ?? 5,
+        stall: surface.stallAngle ?? 0.28,
+        postStall: surface.postStallLift ?? 0.6,
+        incidence: surface.incidence ?? 0,
+        cd0: surface.cd0 ?? 0.02,
+        k: surface.inducedDrag ?? 0.06,
+        kPitch: signed(surface.control?.pitch, -mx),
+        kRoll: signed(surface.control?.roll, mz),
+        kYaw: signed(surface.control?.yaw, -my),
+    };
+}
+function wrapAngle(angle) {
+    if (angle > Math.PI)
+        return angle - 2 * Math.PI;
+    if (angle < -Math.PI)
+        return angle + 2 * Math.PI;
+    return angle;
+}
+/** Lift coefficient: linear to the stall, then a flat-plate `sin 2α` curve scaled to `postStall` of peak. */
+function liftCoefficient(alpha, slope, stall, postStall) {
+    const magnitude = Math.abs(alpha);
+    if (magnitude <= stall)
+        return { cl: slope * alpha, stalled: 0 };
+    const peak = slope * stall;
+    const plate = (Math.sin(2 * alpha) * peak * postStall) / Math.max(1e-6, Math.sin(2 * stall));
+    const blend = Math.exp(-(magnitude - stall) / 0.04);
+    return { cl: plate + (Math.sign(alpha) * peak - plate) * blend, stalled: 1 - blend };
+}
+/**
+ * Creates a {@link RigidAircraft}: a quaternion rigid body with a diagonal inertia tensor, pushed by lifting surfaces,
+ * fuselage drag, an engine and gravity. Controls deflect surfaces through rate-limited actuators; nothing commands a
+ * rotation rate, so a jet loops when its tail can push the nose around and a glider stalls when it runs out of speed.
+ * Fixed internal substeps make it deterministic for a given `dt` sequence.
+ * @capability rigid-aircraft force-and-torque aircraft — lifting surfaces with stall and drag polar, control surfaces, inertia, loops and rolls
+ */
+export function createRigidAircraft(initial, options = {}) {
+    let tuning = initial;
+    let surfaces = initial.surfaces.map(prepareSurface);
+    let largest = largestSurface(surfaces);
+    const windAt = options.wind;
+    const groundAt = options.groundHeight ?? (() => 0);
+    const gravityField = options.gravityField ?? uniformGravity([0, -9.81, 0]);
+    const densityAt = options.airDensity ?? (() => SEA_LEVEL_DENSITY);
+    const state = fresh(options.position ?? [0, 0, 0], options.orientation ?? aircraftHeadingQuaternion(options.heading ?? 0));
+    if (options.velocity !== undefined)
+        [state.vx, state.vy, state.vz] = options.velocity;
+    const telemetry = { airspeed: 0, alpha: 0, sideslip: 0, gLoad: 1, stallFraction: 0, stalled: false, thrust: 0, grounded: false };
+    const rotorTelemetry = { thrust: 0, torque: 0, groundEffect: 1, translationalLift: 1 };
+    const motorTelemetry = { thrust: 0 };
+    const lastCommand = { pitch: 0, roll: 0, yaw: 0 };
+    let limited = false;
+    function largestSurface(list) {
+        let best = -1;
+        for (let i = 0; i < list.length; i += 1)
+            if (best < 0 || list[i].area > list[best].area)
+                best = i;
+        return best;
+    }
+    function fresh(position, orientation) {
+        const [qx, qy, qz, qw] = orientation;
+        const n = Math.hypot(qx, qy, qz, qw) || 1;
+        return {
+            x: position[0],
+            y: position[1],
+            z: position[2],
+            vx: 0,
+            vy: 0,
+            vz: 0,
+            qx: qx / n,
+            qy: qy / n,
+            qz: qz / n,
+            qw: qw / n,
+            wx: 0,
+            wy: 0,
+            wz: 0,
+            pitchDeflection: 0,
+            rollDeflection: 0,
+            yawDeflection: 0,
+            spool: 0,
+            rotorSpeed: 0,
+            burnTime: 0,
+            propellantKg: tuning.motor?.propellantKg ?? 0,
+            holdPitch: 0,
+            holdRoll: 0,
+            holdYaw: 0,
+            trimPitch: 0,
+            trimRoll: 0,
+            trimYaw: 0,
+            driftX: 0,
+            driftZ: 0,
+            time: 0,
+        };
+    }
+    // Scratch for rotating vectors without allocating in the substep.
+    const out = [0, 0, 0];
+    function toWorld(x, y, z) {
+        const { qx, qy, qz, qw } = state;
+        const tx = 2 * (qy * z - qz * y);
+        const ty = 2 * (qz * x - qx * z);
+        const tz = 2 * (qx * y - qy * x);
+        out[0] = x + qw * tx + (qy * tz - qz * ty);
+        out[1] = y + qw * ty + (qz * tx - qx * tz);
+        out[2] = z + qw * tz + (qx * ty - qy * tx);
+    }
+    function toBody(x, y, z) {
+        const { qx, qy, qz, qw } = state;
+        const tx = 2 * (-qy * z + qz * y);
+        const ty = 2 * (-qz * x + qx * z);
+        const tz = 2 * (-qx * y + qy * x);
+        out[0] = x + qw * tx + (-qy * tz + qz * ty);
+        out[1] = y + qw * ty + (-qz * tx + qx * tz);
+        out[2] = z + qw * tz + (-qx * ty + qy * tx);
+    }
+    function slew(current, target, rate, h) {
+        const step = rate * h;
+        return current + Math.max(-step, Math.min(step, target - current));
+    }
+    function substep(h, input, modifiers) {
+        const t = tuning;
+        const m = t.massKg + (t.motor === undefined ? 0 : state.propellantKg);
+        const controls = t.controls;
+        const pitchCh = controls?.pitch;
+        const rollCh = controls?.roll;
+        const yawCh = controls?.yaw;
+        const engine = t.engine;
+        const throttle = Math.max(0, Math.min(1, input.throttle));
+        state.spool += (throttle - state.spool) * (1 - Math.exp(-(engine?.spoolRate ?? 1.5) * h));
+        let wvx = state.vx;
+        let wvy = state.vy;
+        let wvz = state.vz;
+        if (windAt !== undefined) {
+            const wind = windAt([state.x, state.y, state.z]);
+            wvx -= wind[0];
+            wvy -= wind[1];
+            wvz -= wind[2];
+        }
+        toBody(wvx, wvy, wvz);
+        const bx = out[0];
+        const by = out[1];
+        const bz = out[2];
+        const command = t.assists === undefined ? pilotCommand(input) : assist(t.assists, input, h, bx, by, bz);
+        lastCommand.pitch = command.pitch;
+        lastCommand.roll = command.roll;
+        lastCommand.yaw = command.yaw;
+        state.pitchDeflection = slew(state.pitchDeflection, command.pitch * (pitchCh?.maxDeflection ?? 0.35), pitchCh?.rate ?? 2, h);
+        state.rollDeflection = slew(state.rollDeflection, command.roll * (rollCh?.maxDeflection ?? 0.35), rollCh?.rate ?? 2, h);
+        state.yawDeflection = slew(state.yawDeflection, command.yaw * (yawCh?.maxDeflection ?? 0.35), yawCh?.rate ?? 2, h);
+        const rho = densityAt(state.y);
+        const { wx, wy, wz } = state;
+        const liftScale = modifiers?.liftScale ?? 1;
+        const dragScale = modifiers?.dragScale ?? 1;
+        let fx = 0;
+        let fy = 0;
+        let fz = 0;
+        let mx = modifiers?.torque?.[0] ?? 0;
+        let my = modifiers?.torque?.[1] ?? 0;
+        let mz = modifiers?.torque?.[2] ?? 0;
+        let stalledArea = 0;
+        let totalArea = 0;
+        let largestStalled = false;
+        for (let i = 0; i < surfaces.length; i += 1) {
+            const s = surfaces[i];
+            totalArea += s.area;
+            // Local airflow includes the body's rotation (ω × r): that is where pitch, roll and yaw damping come from.
+            const px = bx + (wy * s.az - wz * s.ay);
+            const py = by + (wz * s.ax - wx * s.az);
+            const pz = bz + (wx * s.ay - wy * s.ax);
+            const un = px * s.nx + py * s.ny + pz * s.nz;
+            const uf = pz;
+            const speed2 = un * un + uf * uf;
+            if (speed2 < 1e-8)
+                continue;
+            const alpha = wrapAngle(Math.atan2(-un, uf) + s.incidence + s.kPitch * state.pitchDeflection + s.kRoll * state.rollDeflection + s.kYaw * state.yawDeflection);
+            const { cl, stalled } = liftCoefficient(alpha, s.slope, s.stall, s.postStall);
+            // Below ~1 m/s of local flow the angle of attack is noise, not a stall.
+            if (stalled > 0.5 && speed2 > 1) {
+                stalledArea += s.area;
+                if (i === largest)
+                    largestStalled = true;
+            }
+            const cd = s.cd0 + s.k * cl * cl + 1.28 * Math.sin(alpha) ** 2 * stalled;
+            const speed = Math.sqrt(speed2);
+            // d: direction the air moves past the surface; lift is perpendicular to it, in the plane across the span.
+            const dx = -(un * s.nx) / speed;
+            const dy = -(un * s.ny) / speed;
+            const dz = -(un * s.nz + uf) / speed;
+            const lx = s.sy * dz - s.sz * dy;
+            const ly = s.sz * dx - s.sx * dz;
+            const lz = s.sx * dy - s.sy * dx;
+            const q = 0.5 * rho * speed2 * s.area;
+            const lift = q * cl * liftScale;
+            const drag = q * cd * dragScale;
+            const sfx = lift * lx + drag * dx;
+            const sfy = lift * ly + drag * dy;
+            const sfz = lift * lz + drag * dz;
+            fx += sfx;
+            fy += sfy;
+            fz += sfz;
+            mx += s.ay * sfz - s.az * sfy;
+            my += s.az * sfx - s.ax * sfz;
+            mz += s.ax * sfy - s.ay * sfx;
+        }
+        const airspeed = Math.hypot(bx, by, bz);
+        if (t.dragArea !== undefined && airspeed > 0) {
+            const k = -0.5 * rho * t.dragArea * airspeed * dragScale;
+            fx += k * bx;
+            fy += k * by;
+            fz += k * bz;
+        }
+        let thrust = 0;
+        if (engine !== undefined) {
+            thrust = engine.maxThrust * state.spool * (modifiers?.thrustScale ?? 1);
+            const [tdx, tdy, tdz] = engine.direction ?? [0, 0, 1];
+            const tl = Math.hypot(tdx, tdy, tdz) || 1;
+            const tx = (thrust * tdx) / tl;
+            const ty = (thrust * tdy) / tl;
+            const tz = (thrust * tdz) / tl;
+            fx += tx;
+            fy += ty;
+            fz += tz;
+            if (engine.at !== undefined) {
+                const [ax, ay, az] = engine.at;
+                mx += ay * tz - az * ty;
+                my += az * tx - ax * tz;
+                mz += ax * ty - ay * tx;
+            }
+        }
+        const motor = t.motor;
+        if (motor !== undefined) {
+            const curve = motor.thrustCurve;
+            const lastTime = curve.length === 0 ? 0 : curve[curve.length - 1][0];
+            let motorThrust = 0;
+            if (throttle > 0 && state.propellantKg > 0 && state.burnTime < lastTime) {
+                const rated = sampleCurve(curve, state.burnTime) * throttle;
+                const flow = (motor.massFlow * rated) / Math.max(1e-9, peakOf(curve));
+                const burned = Math.min(state.propellantKg, flow * h);
+                // The last sliver of propellant only delivers its share of the substep.
+                motorThrust = rated * (flow > 0 ? burned / (flow * h) : 1) * (modifiers?.thrustScale ?? 1);
+                state.propellantKg -= burned;
+                if (state.propellantKg < 1e-9)
+                    state.propellantKg = 0;
+                state.burnTime += h;
+            }
+            const [nx, ny, nz] = motor.at ?? [0, 0, -1];
+            const gimbal = motor.gimbal ?? 0;
+            // A nozzle behind the centre of mass swings its thrust the opposite way to the turn it makes.
+            const lever = nz <= 0 ? 1 : -1;
+            const gp = (state.pitchDeflection / (pitchCh?.maxDeflection ?? 0.35)) * gimbal;
+            const gy = (state.yawDeflection / (yawCh?.maxDeflection ?? 0.35)) * gimbal;
+            const tx = motorThrust * lever * Math.sin(gy);
+            const ty = -motorThrust * lever * Math.sin(gp);
+            const tz = motorThrust * Math.sqrt(Math.max(0, 1 - Math.sin(gy) ** 2 - Math.sin(gp) ** 2));
+            fx += tx;
+            fy += ty;
+            fz += tz;
+            mx += ny * tz - nz * ty;
+            my += nz * tx - nx * tz;
+            mz += nx * ty - ny * tx;
+            thrust += motorThrust;
+            motorTelemetry.thrust = motorThrust;
+        }
+        const rotor = t.rotor;
+        if (rotor !== undefined) {
+            state.rotorSpeed += (throttle - state.rotorSpeed) * (1 - Math.exp(-(rotor.spoolRate ?? 0.5) * h));
+            const [hx, hy, hz] = rotor.at ?? [0, 1.5, 0];
+            const cyclic = rotor.cyclic ?? 0.15;
+            const tiltPitch = (state.pitchDeflection / (pitchCh?.maxDeflection ?? 0.35)) * cyclic;
+            const tiltRoll = (state.rollDeflection / (rollCh?.maxDeflection ?? 0.35)) * cyclic;
+            // Nose-up cyclic tilts the disc back (−forward), right cyclic tilts it right (−left).
+            let dx = -Math.sin(tiltRoll);
+            let dz = -Math.sin(tiltPitch);
+            let dy = Math.sqrt(Math.max(0, 1 - dx * dx - dz * dz));
+            const collective = clamp01(input.collective ?? 0);
+            const rpm2 = state.rotorSpeed * state.rotorSpeed;
+            const nominal = rotor.maxThrust * collective * rpm2;
+            const disc = Math.PI * rotor.radius * rotor.radius;
+            // Momentum theory: hover induced velocity v_i = √(T / 2ρA). Clean air arriving at about v_i adds translational
+            // lift; climbing through the disc at w cuts thrust by roughly w / 2v_i, which damps vertical motion.
+            const induced = Math.sqrt(Math.max(nominal, rotor.maxThrust * 0.05) / (2 * rho * disc));
+            const hubVx = bx + (wy * hz - wz * hy);
+            const hubVy = by + (wz * hx - wx * hz);
+            const hubVz = bz + (wx * hy - wy * hx);
+            const edgewise = Math.hypot(hubVx, hubVz);
+            const translational = 1 + (rotor.translationalLift ?? 0.2) * (1 - Math.exp(-((edgewise / induced) ** 2)));
+            const inflow = Math.max(0.2, Math.min(1.5, 1 - hubVy / (2 * induced)));
+            toWorld(hx, hy, hz);
+            const clearance = Math.max(rotor.radius / 2, state.y + out[1] - groundAt(state.x, state.z));
+            // Cheeseman–Bennett: T_IGE / T_OGE = 1 / (1 − (R / 4z)²).
+            const groundEffect = 1 / (1 - (rotor.radius / (4 * clearance)) ** 2);
+            const rotorThrust = nominal * translational * inflow * groundEffect;
+            dx *= rotorThrust;
+            dy *= rotorThrust;
+            dz *= rotorThrust;
+            fx += dx;
+            fy += dy;
+            fz += dz;
+            mx += hy * dz - hz * dy;
+            my += hz * dx - hx * dz;
+            mz += hx * dy - hy * dx;
+            const torque = rotor.torque * collective * rpm2;
+            my += torque;
+            const damping = rotor.damping ?? 0;
+            mx -= damping * wx;
+            mz -= damping * wz;
+            if (rotor.tail !== undefined) {
+                const [, ty, tz] = rotor.tail.at;
+                const side = bx + (wy * tz - wz * ty);
+                const tailThrust = rotor.tail.maxThrust * rpm2 * (state.yawDeflection / (yawCh?.maxDeflection ?? 0.35)) -
+                    (rotor.tail.sideDamping ?? rotor.tail.maxThrust / 10) * state.rotorSpeed * side;
+                fx += tailThrust;
+                // A sideways force along +left at the tail: moment = at × (F, 0, 0).
+                my += tz * tailThrust;
+                mz -= ty * tailThrust;
+            }
+            rotorTelemetry.thrust = rotorThrust;
+            rotorTelemetry.torque = torque;
+            rotorTelemetry.groundEffect = groundEffect;
+            rotorTelemetry.translationalLift = translational;
+        }
+        toWorld(fx, fy, fz);
+        let ax = out[0] / m;
+        let ay = out[1] / m;
+        let az = out[2] / m;
+        if (modifiers?.force !== undefined) {
+            ax += modifiers.force[0] / m;
+            ay += modifiers.force[1] / m;
+            az += modifiers.force[2] / m;
+        }
+        const gravity = gravityField.sample([state.x, state.y, state.z]);
+        const gear = t.gear;
+        const floor = gear === undefined ? Number.NEGATIVE_INFINITY : groundAt(state.x, state.z) + gear.height;
+        let grounded = gear !== undefined && state.y <= floor + 1e-4;
+        let supportY = 0;
+        if (grounded && gear !== undefined) {
+            const netY = ay + gravity[1];
+            if (netY <= 0) {
+                supportY = -netY;
+                const load = supportY;
+                // Heading-aligned tyre frame on flat ground: rolling resistance and brakes along, grip across.
+                toWorld(0, 0, 1);
+                const hl = Math.hypot(out[0], out[2]) || 1;
+                const hx = out[0] / hl;
+                const hz = out[2] / hl;
+                const along = state.vx * hx + state.vz * hz;
+                const across = -state.vx * hz + state.vz * hx;
+                const roll = (gear.rollingResistance ?? 0.02) * load + clamp01(input.brake ?? 0) * (gear.brakeDecel ?? 4);
+                const alongDv = Math.min(Math.abs(along), roll * h) * Math.sign(along);
+                const acrossDv = Math.min(Math.abs(across), (gear.sideGrip ?? 0.8) * load * h) * Math.sign(across);
+                ax -= (alongDv * hx - acrossDv * hz) / h;
+                az -= (alongDv * hz + acrossDv * hx) / h;
+            }
+            else {
+                grounded = false;
+            }
+        }
+        state.vx += (ax + gravity[0]) * h;
+        state.vy += (ay + gravity[1] + supportY) * h;
+        state.vz += (az + gravity[2]) * h;
+        state.x += state.vx * h;
+        state.y += state.vy * h;
+        state.z += state.vz * h;
+        const inertiaScale = m / t.massKg;
+        const ip = t.inertia.pitch * inertiaScale;
+        const iy = t.inertia.yaw * inertiaScale;
+        const ir = t.inertia.roll * inertiaScale;
+        // Euler's rotation equation, body frame: I·ω̇ = M − ω × (I·ω).
+        const gx = wy * (ir * wz) - wz * (iy * wy);
+        const gy = wz * (ip * wx) - wx * (ir * wz);
+        const gz = wx * (iy * wy) - wy * (ip * wx);
+        state.wx += ((mx - gx) / ip) * h;
+        state.wy += ((my - gy) / iy) * h;
+        state.wz += ((mz - gz) / ir) * h;
+        integrateOrientation(h);
+        if (gear !== undefined) {
+            const ground = groundAt(state.x, state.z) + gear.height;
+            if (state.y < ground) {
+                state.y = ground;
+                if (state.vy < 0)
+                    state.vy = 0;
+                grounded = true;
+            }
+            if (grounded)
+                settleOnGear(gear.maxPitch ?? 0.25);
+        }
+        const g0 = Math.max(1e-3, Math.hypot(gravity[0], gravity[1], gravity[2]));
+        // Specific force (everything but gravity) along body up, over g: what the pilot's seat feels.
+        toBody(ax, ay + supportY, az);
+        telemetry.gLoad = out[1] / g0;
+        telemetry.airspeed = airspeed;
+        telemetry.alpha = airspeed > 1e-3 ? Math.atan2(-by, bz) : 0;
+        telemetry.sideslip = airspeed > 1e-3 ? Math.asin(Math.max(-1, Math.min(1, -bx / airspeed))) : 0;
+        telemetry.stallFraction = totalArea > 0 ? stalledArea / totalArea : 0;
+        telemetry.stalled = largestStalled;
+        telemetry.thrust = thrust;
+        telemetry.grounded = grounded;
+        state.time += h;
+    }
+    function pilotCommand(input) {
+        limited = false;
+        return { pitch: clamp1(input.pitch), roll: clamp1(input.roll), yaw: clamp1(input.yaw) };
+    }
+    function assist(a, input, h, bx, by, bz) {
+        const pilot = pilotCommand(input);
+        const attitude = attitudeOf(state);
+        const q = -state.wx;
+        const r = -state.wy;
+        const p = state.wz;
+        const airspeed = Math.hypot(bx, by, bz);
+        const alpha = airspeed > 1 ? Math.atan2(-by, bz) : 0;
+        const g0 = 9.81;
+        const gLoad = (airspeed * q) / g0 + Math.cos(attitude.pitch) * Math.cos(attitude.bank);
+        const hands = { pitch: 1 - Math.abs(pilot.pitch), roll: 1 - Math.abs(pilot.roll), yaw: 1 - Math.abs(pilot.yaw) };
+        const command = { ...pilot };
+        const level = a.autoLevel ?? 0;
+        const hover = a.hoverHold ?? 0;
+        const sas = a.sas;
+        if (sas !== undefined) {
+            const full = Math.max(1e-3, a.sasRate ?? 0.5);
+            const holdsAttitude = level === 0 && hover === 0;
+            // Hands-off, SAS is a PID on body angle: rate (D), angle since release (P) and a learned trim (I).
+            const axis = (strength, stick, handsFree, rate, hold, trim, holds) => {
+                const k = strength ?? 0;
+                const active = Math.abs(stick) > 0.05;
+                const nextHold = active || !holds ? 0 : hold + rate * h;
+                const nextTrim = active || !holds || k === 0 ? trim : trim + nextHold * 0.5 * h;
+                return { hold: nextHold, trim: nextTrim, command: -(k * handsFree * (rate + nextHold + nextTrim)) / full };
+            };
+            const pitchAxis = axis(sas.pitch, pilot.pitch, hands.pitch, q, state.holdPitch, state.trimPitch, holdsAttitude);
+            const rollAxis = axis(sas.roll, pilot.roll, hands.roll, p, state.holdRoll, state.trimRoll, holdsAttitude);
+            const yawAxis = axis(sas.yaw, pilot.yaw, hands.yaw, r, state.holdYaw, state.trimYaw, true);
+            state.holdPitch = pitchAxis.hold;
+            state.trimPitch = pitchAxis.trim;
+            state.holdRoll = rollAxis.hold;
+            state.trimRoll = rollAxis.trim;
+            state.holdYaw = yawAxis.hold;
+            state.trimYaw = yawAxis.trim;
+            command.pitch += pitchAxis.command;
+            command.roll += rollAxis.command;
+            command.yaw += yawAxis.command;
+        }
+        if (level > 0) {
+            command.roll -= (level * hands.roll * (attitude.bank + 0.5 * p)) / 0.5;
+            command.pitch -= (level * hands.pitch * (attitude.pitch + 0.5 * q)) / 0.5;
+        }
+        const hfx = Math.sin(attitude.heading);
+        const hfz = Math.cos(attitude.heading);
+        const forward = state.vx * hfx + state.vz * hfz;
+        const right = -state.vx * hfz + state.vz * hfx;
+        if (hover > 0) {
+            const cyclicFree = Math.abs(pilot.pitch) <= 0.05 && Math.abs(pilot.roll) <= 0.05;
+            state.driftX = cyclicFree ? state.driftX + state.vx * h : 0;
+            state.driftZ = cyclicFree ? state.driftZ + state.vz * h : 0;
+            const driftForward = state.driftX * hfx + state.driftZ * hfz;
+            const driftRight = -state.driftX * hfz + state.driftZ * hfx;
+            // Position → velocity → attitude → rate: tilt against drift plus distance moved, capped at 0.25 rad.
+            const pitchTarget = Math.max(-0.25, Math.min(0.25, 0.05 * (forward + 0.3 * driftForward)));
+            const bankTarget = Math.max(-0.25, Math.min(0.25, -0.05 * (right + 0.3 * driftRight)));
+            command.pitch += hover * hands.pitch * (4 * (pitchTarget - attitude.pitch) - q);
+            command.roll += hover * hands.roll * (4 * (bankTarget - attitude.bank) - p);
+        }
+        limited = false;
+        if (a.maxAngleOfAttack !== undefined && airspeed > 1) {
+            // Lead the limit by where the pitch rate is taking the angle of attack.
+            const predicted = alpha + 0.1 * q;
+            const ceiling = (a.maxAngleOfAttack - predicted) / 0.1;
+            const floor = (-a.maxAngleOfAttack - predicted) / 0.1;
+            if (command.pitch > ceiling || command.pitch < floor)
+                limited = true;
+            command.pitch = Math.max(floor, Math.min(ceiling, command.pitch));
+        }
+        if (a.maxG !== undefined) {
+            const ceiling = a.maxG - gLoad;
+            if (command.pitch > ceiling) {
+                command.pitch = ceiling;
+                limited = true;
+            }
+        }
+        if (a.policy !== undefined) {
+            const out = a.policy({
+                dt: h,
+                airspeed,
+                angleOfAttack: alpha,
+                heading: attitude.heading,
+                pitch: attitude.pitch,
+                bank: attitude.bank,
+                pitchRate: q,
+                yawRate: r,
+                rollRate: p,
+                velocity: [state.vx, state.vy, state.vz],
+                forward,
+                right,
+                gLoad,
+                heightAboveGround: state.y - groundAt(state.x, state.z),
+                pilot: input,
+            }, command);
+            command.pitch = out.pitch;
+            command.roll = out.roll;
+            command.yaw = out.yaw;
+        }
+        command.pitch = clamp1(command.pitch);
+        command.roll = clamp1(command.roll);
+        command.yaw = clamp1(command.yaw);
+        return command;
+    }
+    function integrateOrientation(h) {
+        const { qx, qy, qz, qw, wx, wy, wz } = state;
+        // q̇ = ½ q ⊗ (ω, 0) with ω in the body frame.
+        const nx = qx + 0.5 * h * (qw * wx + qy * wz - qz * wy);
+        const ny = qy + 0.5 * h * (qw * wy + qz * wx - qx * wz);
+        const nz = qz + 0.5 * h * (qw * wz + qx * wy - qy * wx);
+        const nw = qw - 0.5 * h * (qx * wx + qy * wy + qz * wz);
+        const n = Math.hypot(nx, ny, nz, nw) || 1;
+        state.qx = nx / n;
+        state.qy = ny / n;
+        state.qz = nz / n;
+        state.qw = nw / n;
+    }
+    function settleOnGear(maxPitch) {
+        const attitude = attitudeOf(state);
+        const pitch = Math.max(0, Math.min(maxPitch, attitude.pitch));
+        if (pitch === attitude.pitch && attitude.bank === 0)
+            return;
+        const [qx, qy, qz, qw] = aircraftAttitudeQuaternion(attitude.heading, pitch, 0);
+        state.qx = qx;
+        state.qy = qy;
+        state.qz = qz;
+        state.qw = qw;
+        state.wz = 0;
+        if (pitch !== attitude.pitch)
+            state.wx = 0;
+    }
+    function stepOf() {
+        const attitude = attitudeOf(state);
+        return {
+            position: [state.x, state.y, state.z],
+            velocity: [state.vx, state.vy, state.vz],
+            orientation: [state.qx, state.qy, state.qz, state.qw],
+            heading: attitude.heading,
+            pitch: attitude.pitch,
+            bank: attitude.bank,
+            pitchRate: -state.wx,
+            yawRate: -state.wy,
+            rollRate: state.wz,
+            airspeed: telemetry.airspeed,
+            angleOfAttack: telemetry.alpha,
+            sideslip: telemetry.sideslip,
+            gLoad: telemetry.gLoad,
+            stalled: telemetry.stalled,
+            stallFraction: telemetry.stallFraction,
+            thrust: telemetry.thrust,
+            deflection: { pitch: state.pitchDeflection, roll: state.rollDeflection, yaw: state.yawDeflection },
+            grounded: telemetry.grounded,
+            massKg: tuning.massKg + (tuning.motor === undefined ? 0 : state.propellantKg),
+            command: { ...lastCommand },
+            limited,
+            ...(tuning.motor === undefined
+                ? {}
+                : {
+                    motor: {
+                        thrust: motorTelemetry.thrust,
+                        burnTime: state.burnTime,
+                        propellantKg: state.propellantKg,
+                        burnedOut: state.propellantKg <= 0 || state.burnTime >= (tuning.motor.thrustCurve.at(-1)?.[0] ?? 0),
+                    },
+                }),
+            ...(tuning.rotor === undefined
+                ? {}
+                : {
+                    rotor: {
+                        speed: state.rotorSpeed,
+                        thrust: rotorTelemetry.thrust,
+                        torque: rotorTelemetry.torque,
+                        groundEffect: rotorTelemetry.groundEffect,
+                        translationalLift: rotorTelemetry.translationalLift,
+                    },
+                }),
+        };
+    }
+    return {
+        tick(dt, input, modifiers) {
+            const maxSub = Math.max(1 / 4000, tuning.maxSubstep ?? DEFAULT_SUBSTEP);
+            const steps = dt > 0 ? Math.max(1, Math.ceil(dt / maxSub - 1e-9)) : 0;
+            const h = steps > 0 ? dt / steps : 0;
+            for (let i = 0; i < steps; i += 1)
+                substep(h, input, modifiers);
+            return stepOf();
+        },
+        pose: () => ({ position: [state.x, state.y, state.z], orientation: [state.qx, state.qy, state.qz, state.qw] }),
+        velocity: () => [state.vx, state.vy, state.vz],
+        applyImpulse(dv) {
+            state.vx += dv[0];
+            state.vy += dv[1];
+            state.vz += dv[2];
+        },
+        retune(next) {
+            if (next.motor !== tuning.motor) {
+                state.burnTime = 0;
+                state.propellantKg = next.motor?.propellantKg ?? 0;
+            }
+            tuning = next;
+            surfaces = next.surfaces.map(prepareSurface);
+            largest = largestSurface(surfaces);
+        },
+        tuning: () => tuning,
+        snapshot: () => ({ ...state }),
+        restore(next) {
+            Object.assign(state, next);
+        },
+        resetTo(position, orientation) {
+            Object.assign(state, fresh(position, orientation ?? aircraftHeadingQuaternion(attitudeOf(state).heading)));
+        },
+    };
+}
+function sampleCurve(curve, time) {
+    if (curve.length === 0)
+        return 0;
+    if (time <= curve[0][0])
+        return curve[0][1];
+    for (let i = 1; i < curve.length; i += 1) {
+        const [t1, v1] = curve[i];
+        if (time <= t1) {
+            const [t0, v0] = curve[i - 1];
+            return t1 > t0 ? v0 + ((v1 - v0) * (time - t0)) / (t1 - t0) : v1;
+        }
+    }
+    return 0;
+}
+function peakOf(curve) {
+    let peak = 0;
+    for (const [, value] of curve)
+        peak = Math.max(peak, value);
+    return peak;
+}
+function clamp1(value) {
+    return Math.max(-1, Math.min(1, value));
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/** Heading, nose-up pitch and right bank of a body orientation (three.js `YXZ` Euler with `x = -pitch`). */
+function attitudeOf(q) {
+    const { qx: x, qy: y, qz: z, qw: w } = q;
+    const m13 = 2 * (x * z + w * y);
+    const m23 = 2 * (y * z - w * x);
+    const m33 = 1 - 2 * (x * x + y * y);
+    const m21 = 2 * (x * y + w * z);
+    const m22 = 1 - 2 * (x * x + z * z);
+    const m31 = 2 * (x * z - w * y);
+    const m11 = 1 - 2 * (y * y + z * z);
+    const ex = Math.asin(-Math.max(-1, Math.min(1, m23)));
+    if (Math.abs(m23) < 0.9999999)
+        return { heading: Math.atan2(m13, m33), pitch: -ex, bank: Math.atan2(m21, m22) };
+    return { heading: Math.atan2(-m31, m11), pitch: -ex, bank: 0 };
+}