@woosh/meep-engine 3.63.3 → 3.64.1

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -68,18 +68,71 @@ import { RigidBodyFlags } from "./RigidBodyFlags.js";
 import { SleepState } from "./SleepState.js";
 
 /**
- * Scratch for {@link applyImpulseAt}'s angular delta calculation.
+ * Scratch for the angular velocity change {@link applyImpulseAt} and
+ * {@link predictStepMeanVelocity} work out.
  * @type {Float64Array}
  */
 const scratch_angular_delta = new Float64Array(3);
 
 /**
- * Scratch for {@link applyImpulseAt}'s LockRot*-masked inverse-inertia
- * diagonal (the same mask {@link SolverBodyState#gather} applies).
+ * Scratch for the LockRot*-masked inverse-inertia diagonal (the same mask
+ * {@link SolverBodyState#gather} applies) of {@link applyImpulseAt} and
+ * {@link predictStepMeanVelocity}.
  * @type {Float64Array}
  */
 const scratch_locked_inertia = new Float64Array(3);
 
+/**
+ * The damping and the substep {@link substep_mean_shares} reads.
+ * @type {Float64Array}
+ */
+const scratch_mean_params = new Float64Array(2);
+
+/**
+ * The shares {@link substep_mean_shares} writes.
+ * @type {Float64Array}
+ */
+const scratch_mean_shares = new Float64Array(2);
+
+/**
+ * The mean of the velocities that `count` substeps of {@link integrate_velocity_gravity} at `h` leave, one
+ * after each, as shares: `out[0]` of the velocity they start from, and `out[1]` of the gravity they add
+ * together, `gravity·gravityScale·h·count`.
+ *
+ * A substep adds `gravity·gravityScale·h` and then decays the velocity by `k = 1/(1 + damping·h)`, or not
+ * at all unless the damping is above 0. After substep `i` that leaves `kⁱ` of the velocity the substeps
+ * started from, and `Σⱼ₌₁…ᵢ kʲ` substeps' worth of gravity; so over `n = count` substeps
+ *
+ *     out[0] = (1/n)·Σᵢ₌₁…ₙ kⁱ,   out[1] = (1/n²)·Σᵢ₌₁…ₙ Σⱼ₌₁…ᵢ kʲ,
+ *
+ * 1 and `(n + 1)/(2n)` undamped. Summed term by term, as exact for a damping near 0 as for any other.
+ *
+ * Reads the damping (per second) at `params[0]` and `h` (seconds) at `params[1]`. They travel in an array
+ * because a number handed to a call V8 does not inline is boxed into a new heap object.
+ *
+ * @param {Float64Array} out
+ * @param {Float64Array} params
+ * @param {number} count substeps, at least 1
+ */
+function substep_mean_shares(out, params, count) {
+    const damping = params[0];
+    const h = params[1];
+    const k = damping > 0 ? 1 / (1 + damping * h) : 1;
+
+    let power = 1; // kⁱ
+    let sum = 0; // Σⱼ₌₁…ᵢ kʲ
+    let sum_of_sums = 0;
+
+    for (let i = 0; i < count; i++) {
+        power *= k;
+        sum += power;
+        sum_of_sums += sum;
+    }
+
+    out[0] = sum / count;
+    out[1] = sum_of_sums / (count * count);
+}
+
 /**
  * Reusable scratch buffer for world-AABB construction so the link path is
  * allocation-free in steady state.
@@ -1377,6 +1430,141 @@ export class PhysicsSystem extends System {
         this.__wake_body(rigidBody);
     }
 
+    /**
+     * The mean velocity a body will have across the next {@link fixedUpdate}`(dt)` under what already
+     * acts on it: gravity, its damping, and the force and torque accumulated so far, with no contact or
+     * joint. Its displacement over that step is this times `dt`.
+     *
+     * The accumulated force and torque are spent before the substeps, as is an impulse applied before
+     * the step ({@link applyImpulseAt}): the mean keeps {@link predictStepMeanVelocityShare} of the
+     * velocity change each makes, all of it on a body nothing damps. Gravity enters at each of the `N`
+     * {@link substeps}: it adds `gravity·gravityScale·dt` to an undamped body's end velocity, but only
+     * `(N + 1)/(2N)` of that to its mean. A damping above 0 decays the velocity at each substep by
+     * `k = 1/(1 + damping·dt/N)`, so the mean keeps `(1/N)·Σᵢ kⁱ` of the velocity the substeps start
+     * from and `(1/N²)·Σᵢ Σⱼ₌₁…ᵢ kʲ` of the step's gravity, `i = 1…N`; the angular velocity decays the
+     * same way at the angular damping. A controller that works out its impulses from where the coming
+     * step will carry the body predicts that motion with this.
+     *
+     * A body that is not Dynamic is predicted to keep its velocity, as a kinematic body moving at the
+     * velocity it carries does. A KinematicPosition body given a target for the step
+     * ({@link setTargetPose}) takes the velocity that reaches the target instead, and a Static body does
+     * not move.
+     *
+     * @param {Float64Array|number[]} linear receives the mean linear velocity, indexed as [x, y, z]
+     * @param {Float64Array|number[]} angular receives the mean angular velocity, indexed as [x, y, z]
+     * @param {RigidBody} rigidBody
+     * @param {Transform64} transform the body's world transform
+     * @param {number} dt seconds, the step the next fixedUpdate takes
+     */
+    predictStepMeanVelocity(linear, angular, rigidBody, transform, dt) {
+        const lv = rigidBody.linearVelocity;
+        const av = rigidBody.angularVelocity;
+
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            linear[0] = lv[0];
+            linear[1] = lv[1];
+            linear[2] = lv[2];
+
+            angular[0] = av[0];
+            angular[1] = av[1];
+            angular[2] = av[2];
+
+            return;
+        }
+
+        const substeps = this.__substep_count();
+        const inv_m = rigidBody.mass > 0 ? 1 / rigidBody.mass : 0;
+        const af = rigidBody.accumulatedForce;
+        const g = this.gravity;
+
+        scratch_mean_params[0] = rigidBody.linearDamping;
+        scratch_mean_params[1] = dt / substeps;
+        substep_mean_shares(scratch_mean_shares, scratch_mean_params, substeps);
+
+        const share = scratch_mean_shares[0];
+        const gravity_share = rigidBody.gravityScale * dt * scratch_mean_shares[1];
+
+        linear[0] = share * (lv[0] + af[0] * inv_m * dt) + g[0] * gravity_share;
+        linear[1] = share * (lv[1] + af[1] * inv_m * dt) + g[1] * gravity_share;
+        linear[2] = share * (lv[2] + af[2] * inv_m * dt) + g[2] * gravity_share;
+
+        scratch_mean_params[0] = rigidBody.angularDamping;
+        substep_mean_shares(scratch_mean_shares, scratch_mean_params, substeps);
+
+        const angular_share = scratch_mean_shares[0];
+
+        const at = rigidBody.accumulatedTorque;
+
+        if (at[0] !== 0 || at[1] !== 0 || at[2] !== 0) {
+            locked_inverse_inertia(scratch_locked_inertia, 0, rigidBody);
+            world_inverse_inertia_apply_raw(
+                scratch_angular_delta, 0,
+                scratch_locked_inertia[0], scratch_locked_inertia[1], scratch_locked_inertia[2],
+                transform.rotation_x, transform.rotation_y, transform.rotation_z, transform.rotation_w,
+                at[0], at[1], at[2]
+            );
+
+            angular[0] = angular_share * (av[0] + scratch_angular_delta[0] * dt);
+            angular[1] = angular_share * (av[1] + scratch_angular_delta[1] * dt);
+            angular[2] = angular_share * (av[2] + scratch_angular_delta[2] * dt);
+        } else {
+            angular[0] = angular_share * av[0];
+            angular[1] = angular_share * av[1];
+            angular[2] = angular_share * av[2];
+        }
+    }
+
+    /**
+     * How much of a change to a body's velocity, made before the next {@link fixedUpdate}`(dt)`, its mean
+     * velocity across that step keeps, with no contact or joint: `out[0]` of a change to its linear
+     * velocity, `out[1]` of one to its angular velocity. An impulse applied before the step
+     * ({@link applyImpulseAt}) moves the {@link predictStepMeanVelocity} by these times the velocity
+     * change it makes. A controller that solves for impulses against that motion takes their effect on
+     * it from these.
+     *
+     * A damping above 0 decays the velocity at each of the `N` {@link substeps} by
+     * `k = 1/(1 + damping·dt/N)`, so the mean keeps `(1/N)·Σᵢ₌₁…ₙ kⁱ` of a change: 1 for a body nothing
+     * damps, less the more it is damped and the longer the step. A body that is not Dynamic: 1 and 1,
+     * nothing damps it — as {@link predictStepMeanVelocity} predicts it to keep its velocity, with the
+     * same exceptions.
+     *
+     * @param {Float64Array|number[]} out receives the linear share at [0] and the angular share at [1]
+     * @param {RigidBody} rigidBody
+     * @param {number} dt seconds, the step the next fixedUpdate takes
+     */
+    predictStepMeanVelocityShare(out, rigidBody, dt) {
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            out[0] = 1;
+            out[1] = 1;
+
+            return;
+        }
+
+        const substeps = this.__substep_count();
+
+        scratch_mean_params[0] = rigidBody.linearDamping;
+        scratch_mean_params[1] = dt / substeps;
+        substep_mean_shares(scratch_mean_shares, scratch_mean_params, substeps);
+
+        out[0] = scratch_mean_shares[0];
+
+        scratch_mean_params[0] = rigidBody.angularDamping;
+        substep_mean_shares(scratch_mean_shares, scratch_mean_params, substeps);
+
+        out[1] = scratch_mean_shares[0];
+    }
+
+    /**
+     * The number of substeps {@link fixedUpdate} divides a step into: {@link substeps}, truncated, and 1
+     * for anything below 2 — a count of 0, negative or fractional would make the substep `dt / N`
+     * infinite and the loop bound meaningless.
+     * @private
+     * @returns {number}
+     */
+    __substep_count() {
+        return this.substeps > 1 ? this.substeps | 0 : 1;
+    }
+
     /**
      * Replace the linear velocity. Wakes the body if asleep.
      *
@@ -2599,10 +2787,7 @@ export class PhysicsSystem extends System {
         // separate between substeps — the TGS stack-stability mechanism —
         // without re-running narrowphase. Restitution is applied after the
         // loop.
-        // Clamp the substep count: 0 (or a negative / fractional value) would
-        // feed h = dt / N = Infinity into prepare_contacts and a broken loop
-        // bound into the solver.
-        const N = this.substeps > 1 ? this.substeps | 0 : 1;
+        const N = this.__substep_count();
         const h = dt / N;
         const count_after_wake = storage.awake_count;
 

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#487@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#490@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#487@#clear_field"(fluid: FluidComponent): void;
+    static "__#490@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#487@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#490@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#487@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#490@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidObstacle> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof FluidComponent>)[];

package/src/engine/physics/inertia/world_inverse_inertia.d.ts

@@ -39,11 +39,9 @@ export function world_inverse_inertia_apply(result: number[] | Float64Array, res
  * is the body-relative application point. The full constraint denominator is
  * `invM_A + invM_B + contribution_A + contribution_B`.
  *
- * The shared kernel behind the contact/joint solver's SoA path and the
- * raycast-vehicle's component path — each previously inlined the cross
- * product + {@link world_inverse_inertia_apply_raw} + dot themselves.
- * Identical operation order in every caller keeps the paths bit-identical
- * (the determinism contract): the arithmetic is
+ * The kernel the contact/joint solver's SoA path and the CCD sweep's component
+ * path share. Identical operation order in every caller keeps the paths
+ * bit-identical (the determinism contract): the arithmetic is
  * {@link angular_effective_mass_array}'s, which this packs its scalars for.
  *
  * @param {number} ix

package/src/engine/physics/inertia/world_inverse_inertia.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world_inverse_inertia.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/world_inverse_inertia.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oDAXW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,qBACN,MAAM,EAAE,GAAC,YAAY,YAErB,MAAM,EAAE,GAAC,YAAY,MAGrB,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,+CAhBW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,WACN,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CA4BlB;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,qDAZW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,EAAE,GAAC,YAAY,sBACrB,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,QACN,MAAM,EAAE,GAAC,YAAY,eACrB,MAAM,WACN,MAAM,EAAE,GAAC,YAAY,QA6B/B;AAKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wDAbW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAsBhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DATW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,EAAE,GAAC,YAAY,sBACrB,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,YACrB,MAAM,QAwDhB"}
+{"version":3,"file":"world_inverse_inertia.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/world_inverse_inertia.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oDAXW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,qBACN,MAAM,EAAE,GAAC,YAAY,YAErB,MAAM,EAAE,GAAC,YAAY,MAGrB,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+CAhBW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,WACN,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CA4BlB;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,qDAZW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,EAAE,GAAC,YAAY,sBACrB,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,QACN,MAAM,EAAE,GAAC,YAAY,eACrB,MAAM,WACN,MAAM,EAAE,GAAC,YAAY,QA6B/B;AAKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wDAbW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAsBhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DATW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,EAAE,GAAC,YAAY,sBACrB,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,YACrB,MAAM,QAwDhB"}

package/src/engine/physics/inertia/world_inverse_inertia.js

@@ -56,11 +56,9 @@ export function world_inverse_inertia_apply(
  * is the body-relative application point. The full constraint denominator is
  * `invM_A + invM_B + contribution_A + contribution_B`.
  *
- * The shared kernel behind the contact/joint solver's SoA path and the
- * raycast-vehicle's component path — each previously inlined the cross
- * product + {@link world_inverse_inertia_apply_raw} + dot themselves.
- * Identical operation order in every caller keeps the paths bit-identical
- * (the determinism contract): the arithmetic is
+ * The kernel the contact/joint solver's SoA path and the CCD sweep's component
+ * path share. Identical operation order in every caller keeps the paths
+ * bit-identical (the determinism contract): the arithmetic is
  * {@link angular_effective_mass_array}'s, which this packs its scalars for.
  *
  * @param {number} ix

package/src/engine/physics/vehicle/RaycastVehicle.d.ts

@@ -25,13 +25,22 @@ export class Wheel {
     contactNormal: Float64Array;
     /** Body id of the surface under the wheel, or −1. */
     contactBodyId: number;
-    /** Current steering angle (rad), set via {@link RaycastVehicle#setSteering}. */
+    /**
+     * This wheel's steering angle (rad): its forward direction turned about its suspension axis, toward
+     * `up × forward` when positive. {@link RaycastVehicle#setSteering} sets every steered wheel's.
+     */
     steering: number;
     /** Accumulated spin angle (rad) for rendering. */
     rotation: number;
-    /** Forward ground speed at the contact (m/s). */
+    /**
+     * Forward ground speed at the contact across the coming step (m/s): the chassis' mean velocity there
+     * over the step, along the wheel's forward direction, with every impulse of the update in it.
+     */
     forwardSpeed: number;
-    /** Suspension force magnitude applied this frame (N). */
+    /**
+     * The suspension's push in the last {@link RaycastVehicle#update}, as a force: the impulse it
+     * applied along the contact normal, divided by the step (N).
+     */
     suspensionForce: number;
     suspensionRestLength: number;
     suspensionLength: number;
@@ -50,13 +59,101 @@ export class RaycastVehicle {
     __drivenCount: number;
     __ray: Ray3;
     __hit: PhysicsSurfacePoint;
-    __force: Float64Array;
+    /** Reused impulse payload for applyImpulseAt. @type {Float64Array} */
+    __impulse: Float64Array;
+    /**
+     * The chassis' mean linear and angular velocity across the coming step: before the springs push, for
+     * the spring solves; with them pushing, while the tyres solve and for each wheel's ground speed.
+     * @type {Float64Array}
+     */
+    __mean_linear: Float64Array;
+    /** @type {Float64Array} */
+    __mean_angular: Float64Array;
+    /** The chassis' mean velocity across the step per unit impulse applied before it, `M⁻¹`'s linear part. */
+    __mean_inverse_mass: number;
+    /**
+     * `M⁻¹`'s angular part, as the chassis' body-local inverse inertia diagonal (LockRot*-masked) times the
+     * angular share: turned to the world by the pose, its mean spin across the step per unit angular impulse.
+     * @type {Float64Array}
+     */
+    __mean_inverse_inertia: Float64Array;
+    /** Contact normal, forward and side directions (at FRAME_*), 9 per wheel. @type {Float64Array} */
+    __wheel_frame: Float64Array;
+    /** The contact's offset from the chassis' centre, 3 per wheel. @type {Float64Array} */
+    __wheel_lever: Float64Array;
+    /** 1 where the forward direction lies in the contact plane, so the tyre can grip and roll. @type {Uint8Array} */
+    __wheel_rolls: Uint8Array;
+    /**
+     * The tyre impulse the wheel applied in the last update, along its forward and side directions, 2 per
+     * wheel; zero for a wheel that applied none.
+     * @type {Float64Array}
+     */
+    __wheel_tyre: Float64Array;
+    /** The most impulse the tyre may apply this step, `μ·N·dt`. @type {Float64Array} */
+    __wheel_budget: Float64Array;
+    /**
+     * The brake's part of the forward impulse in {@link __wheel_tyre}: what the tyre applied along its
+     * forward direction, less the drive. The tyre starts the next update from it.
+     * @type {Float64Array}
+     */
+    __wheel_brake: Float64Array;
+    /**
+     * The chassis' mean velocity across the step per unit tyre impulse, the free springs answering it:
+     * `W·Jᵀ` for the forward, then the side direction, each linear then angular, 12 per wheel.
+     * @type {Float64Array}
+     */
+    __wheel_response: Float64Array;
+    /**
+     * The wheel's block of `J·W·Jᵀ`, how a unit tyre impulse changes its patch's slip: forward on forward,
+     * side on side, and either on the other, 3 per wheel.
+     * @type {Float64Array}
+     */
+    __wheel_block: Float64Array;
+    /** How many there are. */
+    __free_count: number;
+    /** Their rows. @type {Uint32Array} */
+    __free_row: Uint32Array;
     /**
-     * World contact point handed to applyForceAt / applyImpulseAt, which read a pose by index so a
-     * transform's own translation view can go straight in.
+     * Their block of {@link __row_matrix}, `J_s·M⁻¹·J_sᵀ + Γ`, times {@link __free_scale}, LU-factored.
      * @type {Float64Array}
      */
-    __point: Float64Array;
+    __free_matrix: Float64Array;
+    /** The LU factorisation's pivots. @type {Uint32Array} */
+    __free_pivot: Uint32Array;
+    /** One over the block's largest diagonal. */
+    __free_scale: number;
+    /** Each free spring's speed per unit of one tyre impulse, `J_s·M⁻¹·Jᵀ`. @type {Float64Array} */
+    __free_speed: Float64Array;
+    /**
+     * How much less each free spring pushes per unit of one tyre impulse,
+     * `(J_s·M⁻¹·J_sᵀ + Γ)⁻¹·J_s·M⁻¹·Jᵀ`.
+     * @type {Float64Array}
+     */
+    __free_answer: Float64Array;
+    /** The wheel. @type {Uint32Array} */
+    __row_wheel: Uint32Array;
+    /** The contact normal `n`, then `r × n`, 6 per row. @type {Float64Array} */
+    __row_jacobian: Float64Array;
+    /**
+     * `M⁻¹`'s angular part on `r × n`: the chassis' mean spin across the step per unit impulse along the row,
+     * 3 per row.
+     * @type {Float64Array}
+     */
+    __row_response: Float64Array;
+    /** The spring's compliance `γ`. @type {Float64Array} */
+    __row_compliance: Float64Array;
+    /** `β·x`, the velocity the spring restores at. @type {Float64Array} */
+    __row_restore: Float64Array;
+    /** `β·x − J·v̄`: what the spring asks for against where the step carries the chassis. @type {Float64Array} */
+    __row_rhs: Float64Array;
+    /** The least impulse: a spring does not pull. @type {Float64Array} */
+    __row_lower: Float64Array;
+    /** The most impulse, `suspensionMaxForce·dt`. @type {Float64Array} */
+    __row_upper: Float64Array;
+    /** The impulses solved for. @type {Float64Array} */
+    __row_impulse: Float64Array;
+    /** Rows × rows, column-major: `J·M⁻¹·Jᵀ` plus each row's compliance on the diagonal. @type {Float64Array} */
+    __row_matrix: Float64Array;
     system: PhysicsSystem;
     chassisBody: RigidBody;
     chassisTransform: Transform64;
@@ -92,19 +189,93 @@ export class RaycastVehicle {
         steered?: boolean;
         driven?: boolean;
     }): Wheel;
-    /** Set the steering angle (rad) on every steered wheel. */
-    setSteering(angle: any): void;
+    /**
+     * Steer: turn every steered wheel so that its axle passes through one turn centre on a line across the
+     * chassis, and the tyres' grips agree on the point the chassis turns about. Each wheel's own angle goes
+     * into its {@link Wheel#steering}, from the wheels as they are configured when this is called. The
+     * wheels are taken to share their suspension axis and their straight-ahead direction, as a car's do;
+     * where they differ, their axles need not meet.
+     *
+     * The line passes through the unsteered wheels' mean mount position: the line their axles share.
+     * Where they sit on more than one line, no centre suits them all, and this one leaves them the least
+     * side slip, summed in squares. With every wheel steered, it passes through all the wheels' mean
+     * position: the line that needs the least steering, summed in squares, in a gentle turn.
+     *
+     * `angle` is the single-track ("bicycle") model's steering angle of the steered wheels farthest from
+     * the line, which turn the most: that of one wheel standing at the steered wheels' mean place across
+     * the chassis and as far ahead of the line as they are from it, with its axle through the centre.
+     * Steered wheels nearer the line turn less, and one on it changes nothing. Positive turns the chassis
+     * toward `up × forward` (+x for the default axes), where a positive {@link Wheel#steering} turns a
+     * wheel's forward direction; a steered wheel behind the line turns the other way. At 0 every wheel
+     * points straight. At ±π/2 the chassis pivots about the point of the line beside that one wheel, and
+     * the steered wheels on the inside of it turn past π/2. With every steered wheel on the line, to the
+     * rounding of the mean positions, none can move the centre along it, and each points straight.
+     *
+     * @param {number} angle radians
+     */
+    setSteering(angle: number): void;
     /** Total engine drive force (N), split evenly across the driven wheels. */
     setDriveForce(force: any): void;
     /** Brake force (N) per wheel, opposing each wheel's forward motion. */
     setBrake(force: any): void;
     /**
-     * Step the vehicle: cast suspension rays, apply suspension + tyre forces.
-     * Call once per frame **before** `PhysicsSystem.fixedUpdate(dt)` with the
-     * same `dt`.
+     * Size the per-wheel and per-row storage for `wheel_count` wheels, keeping each wheel's last tyre
+     * impulse and its brake's part.
+     * @param {number} wheel_count
+     * @private
+     */
+    private __reserve;
+    /**
+     * Step the vehicle: cast the suspension rays, apply the tyre impulses, then push the chassis up on its
+     * grounded springs. Every impulse acts on the chassis velocity at once, for the next
+     * `PhysicsSystem.fixedUpdate` to integrate. Call once per fixed step, with that step's `dt`.
      * @param {number} dt
      */
     update(dt: number): void;
+    /**
+     * Fill the `rows` springs' Jacobians, the chassis' angular response to each, and the matrix
+     * `J·M⁻¹·Jᵀ` with each spring's compliance on its diagonal — all fixed by the pose, so shared by
+     * every solve of the step.
+     * @param {number} rows
+     * @private
+     */
+    private __prepare_springs;
+    /**
+     * Solve the `rows` prepared springs as one backward-Euler step against the chassis' mean motion in
+     * {@link __mean_linear} / {@link __mean_angular}, into {@link __row_impulse}: each pushes, and no
+     * harder than its most force.
+     * @param {number} rows
+     * @private
+     */
+    private __solve_springs;
+    /**
+     * Ready the tyres' solve, after the springs are solved against the tyres pushing as they did the step
+     * before. Factors the springs that push freely in that solve, which answer the tyres; turns the motion
+     * in {@link __mean_linear} / {@link __mean_angular} into the step's with those springs pushing and no
+     * tyre; and works out each tyre's response, `W·Jᵀ` and `J·W·Jᵀ`.
+     * @param {number} rows
+     * @private
+     */
+    private __prepare_tyres;
+    /**
+     * The chassis' mean velocity across the step per unit impulse along wheel `wi`'s forward or side
+     * direction at its contact, the free springs answering: `W·Jᵀ`, linear then angular, into
+     * {@link __wheel_response}, and `J·W·Jᵀ`, the change of the contact's speed along that direction per
+     * unit impulse, into its diagonal of {@link __wheel_block}.
+     * @param {number} wi
+     * @param {number} direction {@link FRAME_FORWARD} or {@link FRAME_SIDE}
+     * @private
+     */
+    private __tyre_response;
+    /**
+     * Set wheel `wi`'s tyre impulse for the step from {@link scratch_grip}'s drive, brake and side:
+     * `drive + brake` along its forward direction and `side` along its side, clamped together to its
+     * friction circle. The change applies to the chassis, and to its motion in {@link __mean_linear} /
+     * {@link __mean_angular} with the free springs answering.
+     * @param {number} wi
+     * @private
+     */
+    private __grip;
 }
 import { Ray3 } from "../../../core/geom/3d/ray/Ray3.js";
 import { PhysicsSurfacePoint } from "../queries/PhysicsSurfacePoint.js";

package/src/engine/physics/vehicle/RaycastVehicle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RaycastVehicle.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/vehicle/RaycastVehicle.js"],"names":[],"mappings":"AAmFA;;;;GAIG;AACH;IAEI,8DAA8D;IAC9D,eAD8C,YAAY,CACtB;IAEpC,8EAA8E;IAC9E,oBAD8D,YAAY,CACvB;IAEnD,sEAAsE;IACtE,cADsD,YAAY,CACtB;IAE5C,4BAA0B;IAC1B,0BAAuB;IACvB,2BAA8B;IAC9B,eAAa;IACb,iBAAe;IACf,iBAAgB;IAChB,gBAAe;IAGf,mBAAkB;IAElB,oBAAgB;IAEhB,gDAAgD;IAChD,cADgC,YAAY,CACT;IAEnC,iDAAiD;IACjD,eADiC,YAAY,CACA;IAE7C,qDAAqD;IACrD,sBAAmB;IAEnB,gFAAgF;IAChF,iBAAa;IAEb,kDAAkD;IAClD,iBAAa;IAEb,iDAAiD;IACjD,qBAAiB;IAEjB,yDAAyD;IACzD,wBAAoB;IAGhB,6BAA+B;IAC/B,yBAAiD;CAExD;AAED;IAoBI;;;;OAIG;IACH,0FAOC;IA/BD,sBAAsB;IACtB,QADW,KAAK,EAAE,CACN;IAEZ,qBAAiB;IACjB,qBAAiB;IACjB,sBAAkB;IAClB,YAAmB;IACnB,2BAAkC;IAGlC,sBAA8B;IAE9B;;;;OAIG;IACH,SAFU,YAAY,CAEQ;IAQ1B,sBAAoB;IACpB,uBAA8B;IAC9B,8BAAwC;IAGxC,kDAAmF;IAGvF;;;;;;;;;;;;;;;;;OAiBG;IACH;QAb0B,aAAa,EAA5B,MAAM,EAAE;QACQ,kBAAkB,GAAlC,MAAM,EAAE;QACQ,YAAY,GAA5B,MAAM,EAAE;QACM,oBAAoB,GAAlC,MAAM;QACQ,mBAAmB,GAAjC,MAAM;QACQ,iBAAiB,GAA/B,MAAM;QACQ,kBAAkB,GAAhC,MAAM;QACQ,MAAM,GAApB,MAAM;QACQ,QAAQ,GAAtB,MAAM;QACS,OAAO,GAAtB,OAAO;QACQ,MAAM,GAArB,OAAO;QACL,KAAK,CA0BjB;IAED,2DAA2D;IAC3D,8BAIC;IAED,2EAA2E;IAC3E,gCAAmD;IAEnD,uEAAuE;IACvE,2BAA8C;IAE9C;;;;;OAKG;IACH,WAFW,MAAM,QA2IhB;CACJ;qBAtXoB,mCAAmC;oCACpB,mCAAmC"}
+{"version":3,"file":"RaycastVehicle.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/vehicle/RaycastVehicle.js"],"names":[],"mappings":"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"}