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

package/dist/physics3d-vehicle.d.ts

@@ -0,0 +1,84 @@
+import { type DeterministicPhysicsWorld3D } from './physics3d.js';
+import { type Point3D } from './physics3d-shared.js';
+export interface DeterministicVehicleWheel3D {
+    readonly localAnchor: Point3D;
+    /** Local-space suspension ray direction (typically {0,-1,0}); normalized internally. */
+    readonly suspensionDir: Point3D;
+    readonly suspensionRestLength: number;
+    readonly suspensionMaxTravel: number;
+    readonly radius: number;
+    /** Suspension force per unit compression. */
+    readonly stiffness: number;
+    /** Suspension force per unit compression-velocity. */
+    readonly damping: number;
+    /** Dimensionless tire-friction factor combined with ground material friction. */
+    readonly grip: number;
+    /** Max steer as a float turn fraction in [0, 0.25]. */
+    readonly maxSteerAngleTurns: number;
+    readonly isSteered: boolean;
+    readonly isDriven: boolean;
+}
+export interface DeterministicVehicle3D {
+    readonly chassisId: string;
+    readonly wheels: readonly DeterministicVehicleWheel3D[];
+    /** Full-throttle drive force for the whole vehicle, split across driven wheels. */
+    readonly driveForce: number;
+    /** Full-brake force for the whole vehicle, split across all wheels. */
+    readonly brakeForce: number;
+}
+/** Integer deci-units for determinism: throttle/steer in -10..10, brake in 0..10. */
+export interface DeterministicVehicleInput3D {
+    readonly throttle: number;
+    readonly steer: number;
+    readonly brake: number;
+}
+export interface DeterministicVehicleWheelTelemetry3D {
+    /** Load-bearing (checksummed): contact found and suspension engaged. */
+    readonly grounded: boolean;
+    /** Load-bearing (checksummed): suspension compression in [0, maxTravel], quantized. */
+    readonly compression: number;
+    /** Applied steer angle in turns (quantized). */
+    readonly steerAngleTurns: number;
+    /** Cosmetic render-only telemetry — NOT checksummed. */
+    readonly contactBodyId?: string;
+    readonly contactPoint?: Point3D;
+    readonly contactNormal?: Point3D;
+    /** Cosmetic wheel-spin delta for this step, in turns (accumulate game-side). */
+    readonly spinDeltaTurns: number;
+}
+export interface DeterministicVehicleImpulse3D {
+    readonly bodyId: string;
+    readonly impulse: Point3D;
+    readonly point: Point3D;
+}
+export interface DeterministicVehicleStepResult3D {
+    /** Apply via `applyDeterministicImpulse3D` before the next physics step. */
+    readonly impulses: readonly DeterministicVehicleImpulse3D[];
+    readonly wheels: readonly DeterministicVehicleWheelTelemetry3D[];
+    readonly events: readonly string[];
+    readonly checksum: string;
+}
+export interface DeterministicVehicleStepOptions3D {
+    readonly dtTicks?: number;
+}
+export declare function stepDeterministicVehicle3D(vehicle: DeterministicVehicle3D, input: DeterministicVehicleInput3D, world: DeterministicPhysicsWorld3D, options?: DeterministicVehicleStepOptions3D): DeterministicVehicleStepResult3D;
+export interface DeterministicVehicle3DFixtureResult {
+    readonly checksum: string;
+    readonly restoredChecksum: string;
+    readonly permutedChecksum: string;
+    readonly rollbackEquivalent: boolean;
+    readonly stableUnderAuthoringOrderPermutation: boolean;
+    readonly frames: number;
+    readonly vehicles: number;
+    readonly impulseSamples: number;
+    readonly groundedWheelSamples: number;
+    /** Every emitted impulse component was finite and never negative zero. */
+    readonly impulsesQuantizedClean: boolean;
+}
+/**
+ * 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).
+ */
+export declare function runDeterministicVehicle3DFixture(frames?: number): DeterministicVehicle3DFixtureResult;

package/dist/physics3d-vehicle.js

@@ -0,0 +1,463 @@
+/**
+ * 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).
+ */
+import { cloneCanonical, defaultChecksum } from './canonical.js';
+import { createDeterministicMath } from './math.js';
+import { applyDeterministicImpulses3D, createDeterministicPhysicsWorld3D, deriveInverseInertia, deterministicPhysicsBodyById3D, raycastDeterministicPhysics3DDetailed, stepDeterministicPhysicsWorld3D, } from './physics3d.js';
+import { addVec3, crossVec3, dotVec3, mulMat3Vec, normalizeVec3, quantizeDistance, quatToMat3, rotatePointByQuat, scaleVec3, solverSqrt, subVec3, worldInvInertia, } from './physics3d-shared.js';
+const vehicleMath = 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 = scaleVec3(v, cos);
+    const term2 = scaleVec3(crossVec3(axis, v), sin);
+    const term3 = scaleVec3(axis, dotVec3(axis, v) * (1 - cos));
+    return addVec3(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 = 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 = crossVec3(r, dir);
+    const k = invMass + dotVec3(crossVec3(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 = addVec3(chassisPos, rotatePointByQuat(orientation, wheel.localAnchor));
+    const dir = normalizeVec3(rotatePointByQuat(orientation, wheel.suspensionDir));
+    const suspensionUp = scaleVec3(dir, -1);
+    const hits = 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 = 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 = 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,
+    };
+}
+export 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 = 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 = worldInvInertia(quatToMat3(orientation), 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 = addVec3(chassisVel, scaleVec3(impulseVec, invMass));
+        angularVel = addVec3(angularVel, mulMat3Vec(invInertiaWorld, crossVec3(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: quantizeDistance(impulseVec.x),
+            y: quantizeDistance(impulseVec.y),
+            z: 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 = addVec3(chassisVel, crossVec3(angularVel, subVec3(contact.anchor, chassisPos)));
+        const compressionVelocity = -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(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 = quantizeDistance(vehicleMath.sinTurns(steerFixedTurns) / vehicleMath.fixedScale);
+        const cosSteer = quantizeDistance(vehicleMath.cosTurns(steerFixedTurns) / vehicleMath.fixedScale);
+        const steeredForward = steerFixedTurns === 0
+            ? forwardWorld
+            : rotateAboutAxis(forwardWorld, contact.suspensionUp, cosSteer, sinSteer);
+        const forwardPlanar = subVec3(steeredForward, scaleVec3(contact.normal, dotVec3(steeredForward, contact.normal)));
+        const forwardDir = 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 = addVec3(contact.point, scaleVec3(contact.normal, dotVec3(subVec3(chassisPos, contact.point), contact.normal)));
+        const sideDir = normalizeVec3(crossVec3(contact.normal, forwardDir));
+        const leverArm = 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 = addVec3(chassisVel, crossVec3(angularVel, subVec3(tire.tirePoint, chassisPos)));
+            const forwardSpeed = dotVec3(contactVel, tire.forwardDir);
+            const lateralSpeed = dotVec3(contactVel, tire.sideDir);
+            if (iteration === 0) {
+                spinDeltas[tire.index] = 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 = 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 = addVec3(scaleVec3(tire.forwardDir, longitudinal - tire.longitudinal), scaleVec3(tire.sideDir, lateral - tire.lateral));
+            applyDelta(delta, tire.tirePoint);
+            tire.longitudinal = longitudinal;
+            tire.lateral = lateral;
+        }
+    }
+    for (const tire of tireStates) {
+        emitImpulse(addVec3(scaleVec3(tire.forwardDir, tire.longitudinal), 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: 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 = 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 = 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 = applyDeterministicImpulses3D(world, entry.result.impulses.map((impulse) => ({
+                bodyId: impulse.bodyId,
+                impulse: impulse.impulse,
+                worldPoint: impulse.point,
+            })));
+        }
+        world = stepDeterministicPhysicsWorld3D(world, { gravityY: FIXTURE_GRAVITY_Y, computeChecksum: false }).world;
+        frameChecksums.push(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).
+ */
+export function runDeterministicVehicle3DFixture(frames = 120) {
+    const bodies = fixtureBodies();
+    const vehicles = [fixtureVehicle('vehicle-car-a'), fixtureVehicle('vehicle-car-b')];
+    const run = runVehicleFixtureLoop(createDeterministicPhysicsWorld3D(bodies), vehicles, frames);
+    const restored = runVehicleFixtureLoop(run.snapshot, vehicles, frames - run.snapshotFrame, run.frameChecksums.slice(0, run.snapshotFrame));
+    const permuted = runVehicleFixtureLoop(createDeterministicPhysicsWorld3D([...bodies].reverse()), [...vehicles].reverse(), frames);
+    const checksum = defaultChecksum({ world: run.world, frameChecksums: run.frameChecksums });
+    const restoredChecksum = defaultChecksum({ world: restored.world, frameChecksums: restored.frameChecksums });
+    const permutedChecksum = 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,
+    };
+}