@series-inc/rundot-syncplay 5.23.0-beta.8 → 5.23.0

package/dist/cjs/physics3d-vehicle.js

@@ -0,0 +1,467 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepDeterministicVehicle3D = stepDeterministicVehicle3D;
+exports.runDeterministicVehicle3DFixture = runDeterministicVehicle3DFixture;
+/**
+ * Deterministic raycast-wheel vehicle controller on the rigid-body solver.
+ *
+ * A vehicle is one dynamic chassis body plus N suspension raycasts (wheels are
+ * rays, not bodies — Bullet/Godot raycast-vehicle lineage). Per step the
+ * stateless controller reads the chassis pose/velocity from the world, casts
+ * each wheel, computes spring-damper suspension + friction-circle tire
+ * impulses, and returns them for the game to apply via
+ * `applyDeterministicImpulse3D` before the next physics step. v1 is specified
+ * against static ground: the controller emits chassis-only impulses (no
+ * moving-ground relative velocity, no reaction impulse on the ground body).
+ */
+const canonical_js_1 = require("./canonical.js");
+const math_js_1 = require("./math.js");
+const physics3d_js_1 = require("./physics3d.js");
+const physics3d_shared_js_1 = require("./physics3d-shared.js");
+const vehicleMath = (0, math_js_1.createDeterministicMath)();
+/** Fraction of the suspension impulse lost to rolling resistance each step. */
+const ROLLING_RESISTANCE = 0.02;
+/** Gauss-Seidel passes over the wheels for the tire (drive/brake/grip) solve. */
+const TIRE_ITERATIONS = 6;
+const TWO_PI = 2 * Math.PI;
+/** Chassis-local forward axis: vehicles drive along +z. */
+const LOCAL_FORWARD = { x: 0, y: 0, z: 1 };
+/** Rodrigues rotation of `v` about unit axis `axis` given cos/sin of the angle. */
+function rotateAboutAxis(v, axis, cos, sin) {
+    const term1 = (0, physics3d_shared_js_1.scaleVec3)(v, cos);
+    const term2 = (0, physics3d_shared_js_1.scaleVec3)((0, physics3d_shared_js_1.crossVec3)(axis, v), sin);
+    const term3 = (0, physics3d_shared_js_1.scaleVec3)(axis, (0, physics3d_shared_js_1.dotVec3)(axis, v) * (1 - cos));
+    return (0, physics3d_shared_js_1.addVec3)((0, physics3d_shared_js_1.addVec3)(term1, term2), term3);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function assertIntegerInput(value, label, min, max) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new Error(`stepDeterministicVehicle3D: ${label} must be an integer in [${min}, ${max}], received ${value}`);
+    }
+}
+function assertPositiveWheelField(value, wheelLabel, name) {
+    if (!isFiniteNumber(value) || value <= 0) {
+        throw new Error(`${wheelLabel}: ${name} must be a positive finite number`);
+    }
+}
+function validateVehicle3D(vehicle, input, world, options) {
+    const chassis = (0, physics3d_js_1.deterministicPhysicsBodyById3D)(world, vehicle.chassisId);
+    if (chassis === undefined) {
+        throw new Error(`stepDeterministicVehicle3D: unknown chassis body ${vehicle.chassisId}`);
+    }
+    // Point-impulse yaw is silently dropped by applyDeterministicImpulse3D for
+    // non-dynamic or orientation-less bodies, so steering would be a no-op.
+    if (chassis.kind !== 'dynamic' || chassis.orientation === undefined) {
+        throw new Error(`vehicle ${vehicle.chassisId}: chassis must be a dynamic body with an orientation quaternion`);
+    }
+    if (vehicle.wheels.length === 0) {
+        throw new Error(`vehicle ${vehicle.chassisId}: wheels must not be empty`);
+    }
+    for (const [name, value] of [['driveForce', vehicle.driveForce], ['brakeForce', vehicle.brakeForce]]) {
+        if (!isFiniteNumber(value) || value < 0) {
+            throw new Error(`vehicle ${vehicle.chassisId}: ${name} must be a non-negative finite number`);
+        }
+    }
+    for (let index = 0; index < vehicle.wheels.length; index += 1) {
+        const wheel = vehicle.wheels[index];
+        const wheelLabel = `vehicle ${vehicle.chassisId} wheel ${index}`;
+        for (const [name, point] of [['localAnchor', wheel.localAnchor], ['suspensionDir', wheel.suspensionDir]]) {
+            if (!isFiniteNumber(point.x) || !isFiniteNumber(point.y) || !isFiniteNumber(point.z)) {
+                throw new Error(`${wheelLabel}: ${name} must have finite components`);
+            }
+        }
+        if (wheel.suspensionDir.x === 0 && wheel.suspensionDir.y === 0 && wheel.suspensionDir.z === 0) {
+            throw new Error(`${wheelLabel}: suspensionDir must be a non-zero vector`);
+        }
+        assertPositiveWheelField(wheel.radius, wheelLabel, 'radius');
+        assertPositiveWheelField(wheel.suspensionRestLength, wheelLabel, 'suspensionRestLength');
+        assertPositiveWheelField(wheel.suspensionMaxTravel, wheelLabel, 'suspensionMaxTravel');
+        assertPositiveWheelField(wheel.stiffness, wheelLabel, 'stiffness');
+        if (wheel.suspensionMaxTravel > wheel.suspensionRestLength) {
+            throw new Error(`${wheelLabel}: suspensionMaxTravel must not exceed suspensionRestLength`);
+        }
+        for (const [name, value] of [['damping', wheel.damping], ['grip', wheel.grip]]) {
+            if (!isFiniteNumber(value) || value < 0) {
+                throw new Error(`${wheelLabel}: ${name} must be a non-negative finite number`);
+            }
+        }
+        if (!isFiniteNumber(wheel.maxSteerAngleTurns) || wheel.maxSteerAngleTurns < 0 || wheel.maxSteerAngleTurns > 0.25) {
+            throw new Error(`${wheelLabel}: maxSteerAngleTurns must be within [0, 0.25]`);
+        }
+    }
+    assertIntegerInput(input.throttle, 'throttle', -10, 10);
+    assertIntegerInput(input.steer, 'steer', -10, 10);
+    assertIntegerInput(input.brake, 'brake', 0, 10);
+    if (options.dtTicks !== undefined && (!isFiniteNumber(options.dtTicks) || options.dtTicks <= 0)) {
+        throw new Error(`stepDeterministicVehicle3D: dtTicks must be a positive finite number, received ${options.dtTicks}`);
+    }
+    return chassis;
+}
+/**
+ * Effective mass of the chassis at lever arm `r` along direction `dir`
+ * (1 / (1/m + d·((I⁻¹(r×d))×r))) — the impulse that cancels the point velocity
+ * exactly, including the rotational coupling a plain mass share would ignore.
+ */
+function effectiveMassAt(invMass, invInertiaWorld, r, dir) {
+    // k = invMass + quadratic form of the SPD inverse inertia: always > 0.
+    const rCrossDir = (0, physics3d_shared_js_1.crossVec3)(r, dir);
+    const k = invMass + (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.crossVec3)((0, physics3d_shared_js_1.mulMat3Vec)(invInertiaWorld, rCrossDir), r), dir);
+    return 1 / k;
+}
+function castWheel(world, chassis, wheel) {
+    const orientation = chassis.orientation;
+    const chassisPos = { x: chassis.x, y: chassis.y, z: chassis.z };
+    const anchor = (0, physics3d_shared_js_1.addVec3)(chassisPos, (0, physics3d_shared_js_1.rotatePointByQuat)(orientation, wheel.localAnchor));
+    const dir = (0, physics3d_shared_js_1.normalizeVec3)((0, physics3d_shared_js_1.rotatePointByQuat)(orientation, wheel.suspensionDir));
+    const suspensionUp = (0, physics3d_shared_js_1.scaleVec3)(dir, -1);
+    const hits = (0, physics3d_js_1.raycastDeterministicPhysics3DDetailed)(world, {
+        x: anchor.x,
+        y: anchor.y,
+        z: anchor.z,
+        dx: dir.x,
+        dy: dir.y,
+        dz: dir.z,
+        maxDistance: wheel.suspensionRestLength + wheel.radius,
+        hitTriggers: false,
+        hitSensors: false,
+        hitSolids: true,
+    });
+    // No exclude-id query knob exists; post-filter the distance-sorted hits.
+    const hit = hits.find((candidate) => candidate.bodyId !== chassis.id);
+    if (hit === undefined) {
+        return { grounded: false, compression: 0, groundFriction: 0, anchor, suspensionUp };
+    }
+    const groundBody = (0, physics3d_js_1.deterministicPhysicsBodyById3D)(world, hit.bodyId);
+    // hit.distance <= restLength + radius (the ray's maxDistance), so the raw
+    // compression is never negative — only the maxTravel clamp is needed.
+    const rawCompression = wheel.suspensionRestLength - (hit.distance - wheel.radius);
+    const compression = (0, physics3d_shared_js_1.quantizeDistance)(rawCompression > wheel.suspensionMaxTravel ? wheel.suspensionMaxTravel : rawCompression);
+    return {
+        grounded: compression > 0,
+        compression,
+        bodyId: hit.bodyId,
+        point: hit.point,
+        normal: hit.normal,
+        groundFriction: groundBody.material?.friction ?? 0,
+        anchor,
+        suspensionUp,
+    };
+}
+function stepDeterministicVehicle3D(vehicle, input, world, options = {}) {
+    const chassis = validateVehicle3D(vehicle, input, world, options);
+    const dt = options.dtTicks ?? 1;
+    const contacts = vehicle.wheels.map((wheel) => castWheel(world, chassis, wheel));
+    const chassisPos = { x: chassis.x, y: chassis.y, z: chassis.z };
+    // Internal velocity state, advanced as impulses accumulate so each solve
+    // stage sees the effect of the previous ones.
+    let chassisVel = { x: chassis.vx, y: chassis.vy, z: chassis.vz };
+    let angularVel = chassis.angularVel ?? { x: 0, y: 0, z: 0 };
+    const orientation = chassis.orientation;
+    const forwardWorld = (0, physics3d_shared_js_1.rotatePointByQuat)(orientation, LOCAL_FORWARD);
+    const chassisMass = chassis.mass ?? 1;
+    const wheelCount = vehicle.wheels.length;
+    const drivenCount = vehicle.wheels.filter((wheel) => wheel.isDriven).length;
+    const invMass = 1 / chassisMass;
+    const invInertiaWorld = (0, physics3d_shared_js_1.worldInvInertia)((0, physics3d_shared_js_1.quatToMat3)(orientation), (0, physics3d_js_1.deriveInverseInertia)(chassis.shape, chassisMass));
+    const throttleFraction = input.throttle / 10;
+    const brakeFraction = input.brake / 10;
+    const steerFraction = input.steer / 10;
+    const impulses = [];
+    const applyDelta = (impulseVec, point) => {
+        chassisVel = (0, physics3d_shared_js_1.addVec3)(chassisVel, (0, physics3d_shared_js_1.scaleVec3)(impulseVec, invMass));
+        angularVel = (0, physics3d_shared_js_1.addVec3)(angularVel, (0, physics3d_shared_js_1.mulMat3Vec)(invInertiaWorld, (0, physics3d_shared_js_1.crossVec3)((0, physics3d_shared_js_1.subVec3)(point, chassisPos), impulseVec)));
+    };
+    /** Quantize and emit an impulse; returns the quantized impulse (undefined if it rounds to zero). */
+    const emitImpulse = (impulseVec, point) => {
+        const quantized = {
+            x: (0, physics3d_shared_js_1.quantizeDistance)(impulseVec.x),
+            y: (0, physics3d_shared_js_1.quantizeDistance)(impulseVec.y),
+            z: (0, physics3d_shared_js_1.quantizeDistance)(impulseVec.z),
+        };
+        if (quantized.x === 0 && quantized.y === 0 && quantized.z === 0) {
+            return undefined;
+        }
+        impulses.push({ bodyId: vehicle.chassisId, impulse: quantized, point });
+        return quantized;
+    };
+    // Phase A — suspension for every wheel before any tire force, so tire slip is
+    // measured against the settled post-suspension state (interleaving lets a
+    // wheel's slip cancel sample the lopsided half-applied suspension state and
+    // steers the car under symmetric input).
+    const suspensionImpulseMags = vehicle.wheels.map((wheel, index) => {
+        const contact = contacts[index];
+        if (!contact.grounded || contact.point === undefined || contact.normal === undefined) {
+            return 0;
+        }
+        const anchorVel = (0, physics3d_shared_js_1.addVec3)(chassisVel, (0, physics3d_shared_js_1.crossVec3)(angularVel, (0, physics3d_shared_js_1.subVec3)(contact.anchor, chassisPos)));
+        const compressionVelocity = -(0, physics3d_shared_js_1.dotVec3)(anchorVel, contact.suspensionUp);
+        const rawForce = wheel.stiffness * contact.compression + wheel.damping * compressionVelocity;
+        const suspensionForce = rawForce > 0 ? rawForce : 0;
+        const suspensionImpulseMag = suspensionForce * dt;
+        const emitted = emitImpulse((0, physics3d_shared_js_1.scaleVec3)(contact.normal, suspensionImpulseMag), contact.point);
+        if (emitted !== undefined) {
+            applyDelta(emitted, contact.point);
+        }
+        return suspensionImpulseMag;
+    });
+    const tireStates = [];
+    const spinDeltas = vehicle.wheels.map(() => 0);
+    for (let index = 0; index < vehicle.wheels.length; index += 1) {
+        const wheel = vehicle.wheels[index];
+        const contact = contacts[index];
+        if (!contact.grounded || contact.point === undefined || contact.normal === undefined) {
+            continue;
+        }
+        // Steer angle through the deterministic fixed-point trig instance: float
+        // turn fraction → fixed-point turns → sin/cos → quantized float.
+        const steerFixedTurns = wheel.isSteered
+            ? Math.round(steerFraction * wheel.maxSteerAngleTurns * vehicleMath.fixedScale)
+            : 0;
+        const sinSteer = (0, physics3d_shared_js_1.quantizeDistance)(vehicleMath.sinTurns(steerFixedTurns) / vehicleMath.fixedScale);
+        const cosSteer = (0, physics3d_shared_js_1.quantizeDistance)(vehicleMath.cosTurns(steerFixedTurns) / vehicleMath.fixedScale);
+        const steeredForward = steerFixedTurns === 0
+            ? forwardWorld
+            : rotateAboutAxis(forwardWorld, contact.suspensionUp, cosSteer, sinSteer);
+        const forwardPlanar = (0, physics3d_shared_js_1.subVec3)(steeredForward, (0, physics3d_shared_js_1.scaleVec3)(contact.normal, (0, physics3d_shared_js_1.dotVec3)(steeredForward, contact.normal)));
+        const forwardDir = (0, physics3d_shared_js_1.normalizeVec3)(forwardPlanar);
+        if (forwardDir.x === 0 && forwardDir.y === 0 && forwardDir.z === 0) {
+            continue;
+        }
+        // Tire impulses act at the contact point projected into the COM plane along
+        // the normal: the lever arm is then ⊥ normal, so lateral grip yields pure
+        // yaw with zero roll/pitch injection. Applying side friction at ground
+        // level couples into the (small-inertia) roll axis and the per-wheel slip
+        // cancels ping-pong into a self-propelling limit cycle — the same reason
+        // Bullet's raycast vehicle raises its side-impulse point (rollInfluence).
+        const tirePoint = (0, physics3d_shared_js_1.addVec3)(contact.point, (0, physics3d_shared_js_1.scaleVec3)(contact.normal, (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(chassisPos, contact.point), contact.normal)));
+        const sideDir = (0, physics3d_shared_js_1.normalizeVec3)((0, physics3d_shared_js_1.crossVec3)(contact.normal, forwardDir));
+        const leverArm = (0, physics3d_shared_js_1.subVec3)(tirePoint, chassisPos);
+        const suspensionImpulseMag = suspensionImpulseMags[index];
+        tireStates.push({
+            index,
+            forwardDir,
+            sideDir,
+            tirePoint,
+            effLateralMass: effectiveMassAt(invMass, invInertiaWorld, leverArm, sideDir),
+            effForwardMass: effectiveMassAt(invMass, invInertiaWorld, leverArm, forwardDir),
+            maxTireImpulse: ((wheel.grip * contact.groundFriction) / 10) * suspensionImpulseMag,
+            longitudinal: 0,
+            lateral: 0,
+            // brake + rolling resistance oppose the forward speed, spent from a fixed
+            // per-frame budget so iterations cannot over-apply them
+            resistBudget: (brakeFraction * vehicle.brakeForce * dt) / wheelCount
+                + ROLLING_RESISTANCE * suspensionImpulseMag,
+            driveBudget: wheel.isDriven ? (throttleFraction * vehicle.driveForce * dt) / drivenCount : 0,
+        });
+    }
+    for (let iteration = 0; iteration < TIRE_ITERATIONS; iteration += 1) {
+        for (const tire of tireStates) {
+            const contactVel = (0, physics3d_shared_js_1.addVec3)(chassisVel, (0, physics3d_shared_js_1.crossVec3)(angularVel, (0, physics3d_shared_js_1.subVec3)(tire.tirePoint, chassisPos)));
+            const forwardSpeed = (0, physics3d_shared_js_1.dotVec3)(contactVel, tire.forwardDir);
+            const lateralSpeed = (0, physics3d_shared_js_1.dotVec3)(contactVel, tire.sideDir);
+            if (iteration === 0) {
+                spinDeltas[tire.index] = (0, physics3d_shared_js_1.quantizeDistance)((forwardSpeed * dt) / (TWO_PI * vehicle.wheels[tire.index].radius));
+            }
+            const drive = tire.driveBudget;
+            tire.driveBudget = 0;
+            const absForwardSpeed = forwardSpeed < 0 ? -forwardSpeed : forwardSpeed;
+            const resistCap = absForwardSpeed * tire.effForwardMass;
+            const resistWanted = tire.resistBudget > resistCap ? resistCap : tire.resistBudget;
+            const resist = forwardSpeed > 0 ? resistWanted : forwardSpeed < 0 ? -resistWanted : 0;
+            tire.resistBudget -= resistWanted;
+            let longitudinal = tire.longitudinal + drive - resist;
+            let lateral = tire.lateral - lateralSpeed * tire.effLateralMass;
+            // friction circle in impulse units on the ACCUMULATED tire impulse:
+            // sqrt(long² + lat²) ≤ μ · suspension impulse
+            const tireMag = (0, physics3d_shared_js_1.solverSqrt)(longitudinal * longitudinal + lateral * lateral);
+            if (tireMag > tire.maxTireImpulse) {
+                // tireMag > maxTireImpulse >= 0 implies tireMag > 0
+                const scale = tire.maxTireImpulse / tireMag;
+                longitudinal *= scale;
+                lateral *= scale;
+            }
+            const delta = (0, physics3d_shared_js_1.addVec3)((0, physics3d_shared_js_1.scaleVec3)(tire.forwardDir, longitudinal - tire.longitudinal), (0, physics3d_shared_js_1.scaleVec3)(tire.sideDir, lateral - tire.lateral));
+            applyDelta(delta, tire.tirePoint);
+            tire.longitudinal = longitudinal;
+            tire.lateral = lateral;
+        }
+    }
+    for (const tire of tireStates) {
+        emitImpulse((0, physics3d_shared_js_1.addVec3)((0, physics3d_shared_js_1.scaleVec3)(tire.forwardDir, tire.longitudinal), (0, physics3d_shared_js_1.scaleVec3)(tire.sideDir, tire.lateral)), tire.tirePoint);
+    }
+    const wheels = vehicle.wheels.map((wheel, index) => {
+        const contact = contacts[index];
+        const steerFixedTurns = wheel.isSteered
+            ? Math.round(steerFraction * wheel.maxSteerAngleTurns * vehicleMath.fixedScale)
+            : 0;
+        return {
+            grounded: contact.grounded,
+            compression: contact.compression,
+            steerAngleTurns: (0, physics3d_shared_js_1.quantizeDistance)(steerFixedTurns / vehicleMath.fixedScale),
+            contactBodyId: contact.grounded ? contact.bodyId : undefined,
+            contactPoint: contact.grounded ? contact.point : undefined,
+            contactNormal: contact.grounded ? contact.normal : undefined,
+            spinDeltaTurns: spinDeltas[index],
+        };
+    });
+    const events = [];
+    if (contacts.every((contact) => !contact.grounded)) {
+        events.push('airborne');
+    }
+    // Checksum covers only the load-bearing outputs — impulses, grounded flags,
+    // compressions, events. Cosmetic telemetry (contact point, spin) is excluded
+    // so it cannot false-diverge a replay.
+    const checksum = (0, canonical_js_1.defaultChecksum)({
+        impulses,
+        grounded: wheels.map((wheel) => wheel.grounded),
+        compressions: wheels.map((wheel) => wheel.compression),
+        events,
+    });
+    return { impulses, wheels, events, checksum };
+}
+const FIXTURE_GRAVITY_Y = -0.02;
+function fixtureWheel(localAnchor, steered) {
+    return {
+        localAnchor,
+        suspensionDir: { x: 0, y: -1, z: 0 },
+        suspensionRestLength: 0.6,
+        suspensionMaxTravel: 0.3,
+        radius: 0.3,
+        stiffness: 60,
+        damping: 220,
+        grip: 1,
+        maxSteerAngleTurns: 0.1,
+        isSteered: steered,
+        isDriven: steered,
+    };
+}
+function fixtureVehicle(chassisId) {
+    return {
+        chassisId,
+        driveForce: 12,
+        brakeForce: 40,
+        wheels: [
+            fixtureWheel({ x: -0.9, y: -0.25, z: 1.5 }, true),
+            fixtureWheel({ x: 0.9, y: -0.25, z: 1.5 }, true),
+            fixtureWheel({ x: -0.9, y: -0.25, z: -1.5 }, false),
+            fixtureWheel({ x: 0.9, y: -0.25, z: -1.5 }, false),
+        ],
+    };
+}
+function fixtureBodies() {
+    const chassis = (id, x) => ({
+        id,
+        kind: 'dynamic',
+        x,
+        y: 1.55,
+        z: 0,
+        vx: 0,
+        vy: 0,
+        vz: 0,
+        mass: 1200,
+        orientation: { x: 0, y: 0, z: 0, w: 1 },
+        shape: { type: 'box', halfX: 1, halfY: 0.25, halfZ: 2 },
+        layer: 1,
+        mask: 1,
+    });
+    return [
+        {
+            id: 'vehicle-ground',
+            kind: 'static',
+            x: 0,
+            y: 0,
+            z: 0,
+            vx: 0,
+            vy: 0,
+            vz: 0,
+            shape: { type: 'box', halfX: 60, halfY: 0.5, halfZ: 60 },
+            layer: 1,
+            mask: 1,
+            material: { friction: 8, restitution: 0 },
+        },
+        chassis('vehicle-car-a', -4),
+        chassis('vehicle-car-b', 4),
+    ];
+}
+function fixtureInput(frame, chassisId) {
+    const phase = chassisId === 'vehicle-car-a' ? 0 : 1;
+    return {
+        throttle: frame < 80 ? 10 : 0,
+        steer: (Math.trunc(frame / 20) + phase) % 2 === 0 ? 10 : -10,
+        brake: frame >= 100 ? 10 : 0,
+    };
+}
+function impulseComponentClean(value) {
+    return Number.isFinite(value) && !Object.is(value, -0);
+}
+function runVehicleFixtureLoop(initialWorld, vehicleOrder, frames, priorFrameChecksums = []) {
+    let world = initialWorld;
+    const frameChecksums = [...priorFrameChecksums];
+    const snapshotFrame = initialWorld.frame + Math.trunc(frames / 2);
+    let snapshot = initialWorld;
+    let impulseSamples = 0;
+    let groundedWheelSamples = 0;
+    let impulsesQuantizedClean = true;
+    for (let frame = 0; frame < frames; frame += 1) {
+        if (world.frame === snapshotFrame) {
+            snapshot = (0, canonical_js_1.cloneCanonical)(world);
+        }
+        // Step vehicles in the given (possibly permuted) order; each step is a pure
+        // read of the same world. Impulses are applied in canonical chassis-id
+        // order so authoring order cannot leak into the outcome.
+        const results = vehicleOrder.map((vehicle) => ({
+            vehicle,
+            result: stepDeterministicVehicle3D(vehicle, fixtureInput(world.frame, vehicle.chassisId), world, { dtTicks: 1 }),
+        }));
+        // chassis ids are unique (normalizeBodies enforces world-wide uniqueness)
+        const canonical = [...results].sort((left, right) => (left.vehicle.chassisId < right.vehicle.chassisId ? -1 : 1));
+        for (const entry of canonical) {
+            impulseSamples += entry.result.impulses.length;
+            groundedWheelSamples += entry.result.wheels.filter((wheel) => wheel.grounded).length;
+            impulsesQuantizedClean = impulsesQuantizedClean && entry.result.impulses.every((impulse) => impulseComponentClean(impulse.impulse.x)
+                && impulseComponentClean(impulse.impulse.y)
+                && impulseComponentClean(impulse.impulse.z));
+            world = (0, physics3d_js_1.applyDeterministicImpulses3D)(world, entry.result.impulses.map((impulse) => ({
+                bodyId: impulse.bodyId,
+                impulse: impulse.impulse,
+                worldPoint: impulse.point,
+            })));
+        }
+        world = (0, physics3d_js_1.stepDeterministicPhysicsWorld3D)(world, { gravityY: FIXTURE_GRAVITY_Y, computeChecksum: false }).world;
+        frameChecksums.push((0, canonical_js_1.defaultChecksum)({
+            frame: world.frame,
+            vehicles: canonical.map((entry) => entry.result.checksum),
+        }));
+    }
+    return { world, frameChecksums, snapshot, snapshotFrame, impulseSamples, groundedWheelSamples, impulsesQuantizedClean };
+}
+/**
+ * Determinism fixture for the raycast vehicle: the full read→apply→step loop is
+ * bit-identical across a mid-run snapshot/restore and across world body /
+ * vehicle authoring-order permutation (wheel arrays are authored and fixed —
+ * wheel-order permutation is intentionally NOT part of the contract).
+ */
+function runDeterministicVehicle3DFixture(frames = 120) {
+    const bodies = fixtureBodies();
+    const vehicles = [fixtureVehicle('vehicle-car-a'), fixtureVehicle('vehicle-car-b')];
+    const run = runVehicleFixtureLoop((0, physics3d_js_1.createDeterministicPhysicsWorld3D)(bodies), vehicles, frames);
+    const restored = runVehicleFixtureLoop(run.snapshot, vehicles, frames - run.snapshotFrame, run.frameChecksums.slice(0, run.snapshotFrame));
+    const permuted = runVehicleFixtureLoop((0, physics3d_js_1.createDeterministicPhysicsWorld3D)([...bodies].reverse()), [...vehicles].reverse(), frames);
+    const checksum = (0, canonical_js_1.defaultChecksum)({ world: run.world, frameChecksums: run.frameChecksums });
+    const restoredChecksum = (0, canonical_js_1.defaultChecksum)({ world: restored.world, frameChecksums: restored.frameChecksums });
+    const permutedChecksum = (0, canonical_js_1.defaultChecksum)({ world: permuted.world, frameChecksums: permuted.frameChecksums });
+    return {
+        checksum,
+        restoredChecksum,
+        permutedChecksum,
+        rollbackEquivalent: checksum === restoredChecksum,
+        stableUnderAuthoringOrderPermutation: checksum === permutedChecksum,
+        frames,
+        vehicles: vehicles.length,
+        impulseSamples: run.impulseSamples,
+        groundedWheelSamples: run.groundedWheelSamples,
+        impulsesQuantizedClean: run.impulsesQuantizedClean,
+    };
+}