@woosh/meep-engine 3.63.3 → 3.64.0

package/src/core/math/linalg/solve_box_constrained_qp.js

@@ -0,0 +1,205 @@
+import { lu_factor_linear_system } from "./lu_factor_linear_system.js";
+import { lu_solve_linear_system } from "./lu_solve_linear_system.js";
+
+/** Solved for, anywhere between its bounds. */
+const FREE = 0;
+/** Held at its lower bound. */
+const AT_LOWER = 1;
+/** Held at its upper bound. */
+const AT_UPPER = 2;
+
+// Working storage, grown to the largest system solved so far.
+let scratch_matrix = new Float64Array(64);
+let scratch_target = new Float64Array(8);
+let scratch_free = new Uint32Array(8);
+let scratch_pivot = new Uint32Array(8);
+let scratch_state = new Uint8Array(8);
+
+/**
+ * Solve the bound-constrained quadratic program
+ *
+ *     minimise  ½·xᵀ·A·x − bᵀ·x   subject to   lo ≤ x ≤ hi
+ *
+ * for a symmetric positive-definite `A`; equivalently the box LCP: `x` within `[lo, hi]` where
+ * `w = A·x − b` is zero for every `x_i` strictly between its bounds, non-negative where `x_i = lo_i`
+ * and non-positive where `x_i = hi_i`. The solution is unique.
+ *
+ * Primal active-set method (Nocedal & Wright, *Numerical Optimization*, 2nd ed., §16.5). It starts
+ * from the point of the box nearest the origin, with every variable free. Each pass solves for the
+ * free variables with the held ones at their bounds, and steps toward that solution as far as the box
+ * allows; a variable that cuts the step short is held at the bound it reached. A full step is the
+ * minimum over the variables currently free: then the held variable whose `w` has the wrong sign by
+ * the most is freed, or, when none has, `x` is the solution. The objective falls from each such
+ * minimum to the next, so no set of held variables repeats and the search ends; it also ends where
+ * rounding stops the objective falling. When no bound is reached it is one factorisation of `A`.
+ *
+ * @param {ArrayLike<number>} A n×n, column-major (`A[j·n + i]` is row `i`, column `j`); being symmetric,
+ *   row-major reads the same. Not modified.
+ * @param {ArrayLike<number>} b length n
+ * @param {ArrayLike<number>} lo lower bounds, length n; `-Infinity` where there is none
+ * @param {ArrayLike<number>} hi upper bounds, length n, none below its `lo`; `Infinity` where there is none
+ * @param {Float64Array|number[]} x receives the solution, length n
+ * @param {number} n
+ * @returns {boolean} true when solved; false when `A` did not factor as positive definite, `x` then
+ *   holding the last point reached, within the bounds
+ */
+export function solve_box_constrained_qp(A, b, lo, hi, x, n) {
+    if (scratch_state.length < n) {
+        scratch_matrix = new Float64Array(n * n);
+        scratch_target = new Float64Array(n);
+        scratch_free = new Uint32Array(n);
+        scratch_pivot = new Uint32Array(n);
+        scratch_state = new Uint8Array(n);
+    }
+
+    const state = scratch_state;
+
+    let diagonal_max = 0;
+
+    for (let i = 0; i < n; i++) {
+        const lower = lo[i];
+        const upper = hi[i];
+
+        x[i] = lower > 0 ? lower : (upper < 0 ? upper : 0);
+        state[i] = FREE;
+
+        const d = A[i * n + i];
+
+        if (d > diagonal_max) {
+            diagonal_max = d;
+        }
+    }
+
+    if (n === 0) {
+        return true;
+    }
+
+    if (!(diagonal_max < Infinity) || diagonal_max <= 0) {
+        return false;
+    }
+
+    // lu_factor_linear_system refuses a pivot under an absolute 1e-12; with the largest diagonal scaled
+    // to one, that is relative to A.
+    const scale = 1 / diagonal_max;
+
+    const matrix = scratch_matrix;
+    const target = scratch_target;
+    const free = scratch_free;
+    const pivot = scratch_pivot;
+
+    let last_minimum = Infinity;
+
+    for (; ;) {
+        let free_count = 0;
+
+        for (let i = 0; i < n; i++) {
+            if (state[i] === FREE) {
+                free[free_count++] = i;
+            }
+        }
+
+        if (free_count > 0) {
+            // A_FF·x_F = b_F − A_FH·x_H, with the held variables at their bounds.
+            for (let r = 0; r < free_count; r++) {
+                const i = free[r];
+
+                let rhs = b[i];
+
+                for (let j = 0; j < n; j++) {
+                    if (state[j] !== FREE) {
+                        rhs -= A[j * n + i] * x[j];
+                    }
+                }
+
+                target[r] = rhs * scale;
+
+                for (let c = 0; c < free_count; c++) {
+                    matrix[c * free_count + r] = A[free[c] * n + i] * scale;
+                }
+            }
+
+            if (!lu_factor_linear_system(matrix, pivot, free_count)) {
+                return false;
+            }
+
+            lu_solve_linear_system(matrix, pivot, target, free_count);
+
+            // The longest step toward the solution that stays inside the box.
+            let step = 1;
+            let blocking = -1;
+            let blocking_state = FREE;
+
+            for (let r = 0; r < free_count; r++) {
+                const i = free[r];
+                const t = target[r];
+                const xi = x[i];
+
+                if (t < lo[i]) {
+                    const s = (xi - lo[i]) / (xi - t);
+
+                    if (s < step) {
+                        step = s;
+                        blocking = i;
+                        blocking_state = AT_LOWER;
+                    }
+                } else if (t > hi[i]) {
+                    const s = (hi[i] - xi) / (t - xi);
+
+                    if (s < step) {
+                        step = s;
+                        blocking = i;
+                        blocking_state = AT_UPPER;
+                    }
+                }
+            }
+
+            if (blocking !== -1) {
+                for (let r = 0; r < free_count; r++) {
+                    const i = free[r];
+                    x[i] += step * (target[r] - x[i]);
+                }
+
+                x[blocking] = blocking_state === AT_LOWER ? lo[blocking] : hi[blocking];
+                state[blocking] = blocking_state;
+
+                continue;
+            }
+
+            for (let r = 0; r < free_count; r++) {
+                x[free[r]] = target[r];
+            }
+        }
+
+        // x is the minimum over the free variables. Free the held variable whose multiplier
+        // w_i = (A·x − b)_i has the wrong sign by the most.
+        let objective = 0;
+        let release = -1;
+        let worst = 0;
+
+        for (let i = 0; i < n; i++) {
+            let ax = 0;
+
+            for (let j = 0; j < n; j++) {
+                ax += A[j * n + i] * x[j];
+            }
+
+            objective += x[i] * (0.5 * ax - b[i]);
+
+            const w = ax - b[i];
+            const s = state[i];
+            const violation = s === AT_LOWER ? -w : (s === AT_UPPER ? w : 0);
+
+            if (violation > worst) {
+                worst = violation;
+                release = i;
+            }
+        }
+
+        if (release === -1 || !(objective < last_minimum)) {
+            return true;
+        }
+
+        last_minimum = objective;
+        state[release] = FREE;
+    }
+}

package/src/engine/physics/constraint/soft_spring_coefficients.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Coefficients of a spring-damper solved as a soft velocity constraint over a step `h` (Catto, "Soft
+ * Constraints", GDC 2011). For a row with Jacobian `J`, position `C` (zero at the spring's rest) and
+ * impulse `λ`, the constraint
+ *
+ *     J·v⁺ + β·C + γ·λ = 0,      β = k / (c + h·k),      γ = 1 / (h·(c + h·k))
+ *
+ * is backward Euler for the spring force `−k·C − c·J·v`: its impulse is `λ = −h·(k·C⁺ + c·J·v⁺)`, with
+ * `C⁺ = C + h·J·v⁺` the position the step ends at. It is stable for every `k, c ≥ 0` and `h > 0`.
+ * `γ` is the row's compliance, added to its effective-mass denominator; `β` turns `C` into the
+ * velocity the spring restores at.
+ *
+ * Reads `[k, c, h]` from `params` and writes `[γ, β]` to `out`. The numbers travel in arrays because a
+ * number handed to a call V8 does not inline is boxed into a new heap object.
+ *
+ * @param {Float64Array|number[]} out receives `γ` at `out_offset` and `β` after it
+ * @param {number} out_offset
+ * @param {Float64Array|number[]} params stiffness `k` (N/m, or N·m/rad for an angular row), damping `c`
+ *   (N·s/m, or N·m·s/rad) and step `h` (seconds), from `params_offset`
+ * @param {number} params_offset
+ * @returns {boolean} false, writing nothing, when the spring is inert: no stiffness and no damping
+ */
+export function soft_spring_coefficients(out: Float64Array | number[], out_offset: number, params: Float64Array | number[], params_offset: number): boolean;
+//# sourceMappingURL=soft_spring_coefficients.d.ts.map

package/src/engine/physics/constraint/soft_spring_coefficients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"soft_spring_coefficients.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/soft_spring_coefficients.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8CAPW,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,UACN,YAAY,GAAC,MAAM,EAAE,iBAErB,MAAM,GACJ,OAAO,CAiBnB"}

package/src/engine/physics/constraint/soft_spring_coefficients.js

@@ -0,0 +1,38 @@
+/**
+ * Coefficients of a spring-damper solved as a soft velocity constraint over a step `h` (Catto, "Soft
+ * Constraints", GDC 2011). For a row with Jacobian `J`, position `C` (zero at the spring's rest) and
+ * impulse `λ`, the constraint
+ *
+ *     J·v⁺ + β·C + γ·λ = 0,      β = k / (c + h·k),      γ = 1 / (h·(c + h·k))
+ *
+ * is backward Euler for the spring force `−k·C − c·J·v`: its impulse is `λ = −h·(k·C⁺ + c·J·v⁺)`, with
+ * `C⁺ = C + h·J·v⁺` the position the step ends at. It is stable for every `k, c ≥ 0` and `h > 0`.
+ * `γ` is the row's compliance, added to its effective-mass denominator; `β` turns `C` into the
+ * velocity the spring restores at.
+ *
+ * Reads `[k, c, h]` from `params` and writes `[γ, β]` to `out`. The numbers travel in arrays because a
+ * number handed to a call V8 does not inline is boxed into a new heap object.
+ *
+ * @param {Float64Array|number[]} out receives `γ` at `out_offset` and `β` after it
+ * @param {number} out_offset
+ * @param {Float64Array|number[]} params stiffness `k` (N/m, or N·m/rad for an angular row), damping `c`
+ *   (N·s/m, or N·m·s/rad) and step `h` (seconds), from `params_offset`
+ * @param {number} params_offset
+ * @returns {boolean} false, writing nothing, when the spring is inert: no stiffness and no damping
+ */
+export function soft_spring_coefficients(out, out_offset, params, params_offset) {
+    const stiffness = params[params_offset];
+    const damping = params[params_offset + 1];
+    const h = params[params_offset + 2];
+
+    const denom = damping + h * stiffness;
+
+    if (denom <= 0) {
+        return false;
+    }
+
+    out[out_offset] = 1 / (h * denom);
+    out[out_offset + 1] = stiffness / denom;
+
+    return true;
+}

package/src/engine/physics/constraint/solve_constraints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solve_constraints.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/solve_constraints.js"],"names":[],"mappings":"AAs6BA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qCAXW,OAAO,iCAEP,MAAM,SAEN,MAAM,YAGN,OAAO,QAgCjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAJW,OAAO,mCAEP,OAAO,QAgBjB"}
+{"version":3,"file":"solve_constraints.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/solve_constraints.js"],"names":[],"mappings":"AA86BA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qCAXW,OAAO,iCAEP,MAAM,SAEN,MAAM,YAGN,OAAO,QAgCjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAJW,OAAO,mCAEP,OAAO,QAgBjB"}

package/src/engine/physics/constraint/solve_constraints.js

@@ -27,6 +27,7 @@ import { JOINT_WORLD } from "../ecs/Joint.js";
 import { SleepState } from "../ecs/SleepState.js";
 import { angular_effective_mass_array, world_inverse_inertia_apply_array } from "../inertia/world_inverse_inertia.js";
 import { DofMode } from "./DofMode.js";
+import { soft_spring_coefficients } from "./soft_spring_coefficients.js";
 
 /**
  * # 6-DOF constraint (joint) solver
@@ -150,6 +151,10 @@ const scratch_rel = new Float64Array(8);
 const scratch_ang_err = new Float64Array(3);
 /** One row's effective-mass denominator, body A's part at 0 and body B's at 1. */
 const scratch_keff = new Float64Array(2);
+/** A SPRING row's stiffness, damping and substep, for {@link soft_spring_coefficients}. */
+const scratch_spring_params = new Float64Array(3);
+/** A SPRING row's compliance `γ` at 0 and bias rate `β` at 1, from {@link soft_spring_coefficients}. */
+const scratch_spring = new Float64Array(2);
 
 // The numbers {@link fill_row} is given for one DOF, at these offsets in `scratch_dof`. They are computed
 // per row, and a computed number handed to a call that is not inlined (fill_row is past V8's inlining
@@ -459,8 +464,8 @@ function invert_sym3(K, out) {
  *
  * A spring drives the DOF position toward zero with stiffness `k` (N/m or
  * N·m/rad) and damping `c`, as a *regularised* row rather than a hard one. The
- * implicit-Euler soft constraint (Catto, "Soft Constraints") gives, per substep
- * `h`, with `denom = c + h·k`:
+ * implicit-Euler soft constraint (Catto, "Soft Constraints";
+ * {@link soft_spring_coefficients}) gives, per substep `h`, with `denom = c + h·k`:
  *   `γ = 1 / (h·denom)`         the compliance / regularisation (inverse mass),
  *   `bias = (k/denom)·C`        the restoring velocity, and a softened effective
  *   `effMass = 1/(K + γ)`       mass — so the row solves
@@ -554,14 +559,17 @@ function fill_row(joint, dofIndex, dof, spook_locked, spook_spec, dt_sub, out, o
     }
     if (mode === DofMode.SPRING) {
         if (keff === 0) { imp[dofIndex] = 0; return false; }
-        const ks = joint.dofStiffness[dofIndex];
-        const cs = joint.dofDamping[dofIndex];
-        const denom = cs + dt_sub * ks;
-        if (denom <= 0) { imp[dofIndex] = 0; return false; } // inert (no k, no c)
-        const gamma = 1 / (dt_sub * denom);
+        scratch_spring_params[0] = joint.dofStiffness[dofIndex];
+        scratch_spring_params[1] = joint.dofDamping[dofIndex];
+        scratch_spring_params[2] = dt_sub;
+        if (!soft_spring_coefficients(scratch_spring, 0, scratch_spring_params, 0)) {
+            imp[dofIndex] = 0; // inert (no k, no c)
+            return false;
+        }
+        const gamma = scratch_spring[0];
         out[o + ROW_EFF] = 1 / (keff + gamma);
         // restoring velocity toward pos = 0
-        out[o + ROW_BIAS] = out[o + ROW_RELAX_BIAS] = (ks / denom) * pos;
+        out[o + ROW_BIAS] = out[o + ROW_RELAX_BIAS] = scratch_spring[1] * pos;
         out[o + ROW_CLAMP_LO] = -Infinity;
         out[o + ROW_CLAMP_HI] = Infinity;
         out[o + ROW_GAMMA] = gamma;

package/src/engine/physics/ecs/PhysicsSystem.d.ts

@@ -704,6 +704,60 @@ export class PhysicsSystem extends System<any> {
      * @param {Vector3|ArrayLike<number>} force indexed as [x, y, z]
      */
     applyForce(rigidBody: RigidBody, force: Vector3 | ArrayLike<number>): void;
+    /**
+     * 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: Float64Array | number[], angular: Float64Array | number[], rigidBody: RigidBody, transform: Transform64, dt: number): void;
+    /**
+     * 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: Float64Array | number[], rigidBody: RigidBody, dt: number): void;
+    /**
+     * 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}
+     */
+    private __substep_count;
     /**
      * Replace the linear velocity. Wakes the body if asleep.
      *

package/src/engine/physics/ecs/PhysicsSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}

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;