@woosh/meep-engine 3.38.0 → 3.39.0

package/src/engine/physics/solver/apply_impulse_to_body.d.ts

@@ -11,26 +11,48 @@
  * iteration — and it was previously written out twice, identically, in the contact solver and the
  * constraint solver.
  *
+ * The lever and the impulse are read from arrays, not passed as numbers: the routine is too big for V8
+ * to inline at every call site of a solver loop, and a call that is not inlined boxes each number it is
+ * passed into a new heap object. Arrays and offsets cross the call as they are.
+ *
  * `scratch` is supplied by the caller rather than closed over: the two copies disagreed on this, and an
  * explicit buffer keeps the routine free of shared mutable state between call sites.
  *
- * A zero inverse mass means a static/kinematic body, which absorbs impulses without responding — so this
- * returns immediately rather than writing zeros.
+ * The inverse mass is the body's, from its span. A zero inverse mass means a static/kinematic body, which
+ * absorbs impulses without responding — so this returns immediately rather than writing zeros.
  *
  * @param {Float64Array} ss solver body state array
  * @param {number} base offset of this body's span within `ss`
- * @param {number} invM inverse mass
- * @param {number} rx lever arm x, from centre of mass to the application point
- * @param {number} ry
- * @param {number} rz
- * @param {number} Px impulse x
- * @param {number} Py
- * @param {number} Pz
+ * @param {Float64Array} lever holds the lever arm, from centre of mass to the application point
+ * @param {number} lever_offset where in `lever` its x is, y and z following
+ * @param {Float64Array} impulse holds the impulse `P`
+ * @param {number} impulse_offset where in `impulse` its x is, y and z following
  * @param {number} sign +1 for body A, -1 for body B
  * @param {Float64Array} scratch at least 3 elements, overwritten
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function apply_impulse_to_body(ss: Float64Array, base: number, invM: number, rx: number, ry: number, rz: number, Px: number, Py: number, Pz: number, sign: number, scratch: Float64Array): void;
+export function apply_impulse_to_body(ss: Float64Array, base: number, lever: Float64Array, lever_offset: number, impulse: Float64Array, impulse_offset: number, sign: number, scratch: Float64Array): void;
+/**
+ * {@link apply_impulse_to_body} with the world inverse inertia evaluated at a given orientation rather
+ * than the one in the body's span, which the substep loop advances.
+ *
+ * For a constraint row whose effective mass was computed once, at one orientation, and is applied
+ * across substeps while the body turns: the impulse must go through the inertia that mass was
+ * computed from, or the row's Gauss-Seidel update over-corrects by the ratio of the two.
+ *
+ * @param {Float64Array} ss solver body state array
+ * @param {number} base offset of this body's span within `ss`
+ * @param {Float64Array} rotation holds the orientation the world inverse inertia is evaluated at, a unit
+ *        quaternion `[x, y, z, w]`
+ * @param {number} rotation_offset where in `rotation` its x is
+ * @param {Float64Array} lever holds the lever arm, from centre of mass to the application point
+ * @param {number} lever_offset where in `lever` its x is, y and z following
+ * @param {Float64Array} impulse holds the impulse `P`
+ * @param {number} impulse_offset where in `impulse` its x is, y and z following
+ * @param {number} sign +1 for body A, -1 for body B
+ * @param {Float64Array} scratch at least 3 elements, overwritten
+ */
+export function apply_impulse_to_body_oriented(ss: Float64Array, base: number, rotation: Float64Array, rotation_offset: number, lever: Float64Array, lever_offset: number, impulse: Float64Array, impulse_offset: number, sign: number, scratch: Float64Array): void;
 //# sourceMappingURL=apply_impulse_to_body.d.ts.map

package/src/engine/physics/solver/apply_impulse_to_body.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply_impulse_to_body.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/solver/apply_impulse_to_body.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,0CAfW,YAAY,QACZ,MAAM,QACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QACN,MAAM,WACN,YAAY,QAuCtB"}
+{"version":3,"file":"apply_impulse_to_body.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/solver/apply_impulse_to_body.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,0CAZW,YAAY,QACZ,MAAM,SACN,YAAY,gBACZ,MAAM,WACN,YAAY,kBACZ,MAAM,QACN,MAAM,WACN,YAAY,QAoBtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,mDAZW,YAAY,QACZ,MAAM,YACN,YAAY,mBAEZ,MAAM,SACN,YAAY,gBACZ,MAAM,WACN,YAAY,kBACZ,MAAM,QACN,MAAM,WACN,YAAY,QA2CtB"}

package/src/engine/physics/solver/apply_impulse_to_body.js

@@ -3,17 +3,13 @@ import {
     SBS_AV_Y,
     SBS_AV_Z,
     SBS_INV_I_X,
-    SBS_INV_I_Y,
-    SBS_INV_I_Z,
+    SBS_INV_MASS,
     SBS_LV_X,
     SBS_LV_Y,
     SBS_LV_Z,
-    SBS_QW,
     SBS_QX,
-    SBS_QY,
-    SBS_QZ,
 } from "../body/SolverBodyState.js";
-import { world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inertia.js";
+import { world_inverse_inertia_apply_array } from "../inertia/world_inverse_inertia.js";
 
 /**
  * Apply impulse `P` at lever arm `r` to one body's solver state:
@@ -28,21 +24,22 @@ import { world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inerti
  * iteration — and it was previously written out twice, identically, in the contact solver and the
  * constraint solver.
  *
+ * The lever and the impulse are read from arrays, not passed as numbers: the routine is too big for V8
+ * to inline at every call site of a solver loop, and a call that is not inlined boxes each number it is
+ * passed into a new heap object. Arrays and offsets cross the call as they are.
+ *
  * `scratch` is supplied by the caller rather than closed over: the two copies disagreed on this, and an
  * explicit buffer keeps the routine free of shared mutable state between call sites.
  *
- * A zero inverse mass means a static/kinematic body, which absorbs impulses without responding — so this
- * returns immediately rather than writing zeros.
+ * The inverse mass is the body's, from its span. A zero inverse mass means a static/kinematic body, which
+ * absorbs impulses without responding — so this returns immediately rather than writing zeros.
  *
  * @param {Float64Array} ss solver body state array
  * @param {number} base offset of this body's span within `ss`
- * @param {number} invM inverse mass
- * @param {number} rx lever arm x, from centre of mass to the application point
- * @param {number} ry
- * @param {number} rz
- * @param {number} Px impulse x
- * @param {number} Py
- * @param {number} Pz
+ * @param {Float64Array} lever holds the lever arm, from centre of mass to the application point
+ * @param {number} lever_offset where in `lever` its x is, y and z following
+ * @param {Float64Array} impulse holds the impulse `P`
+ * @param {number} impulse_offset where in `impulse` its x is, y and z following
  * @param {number} sign +1 for body A, -1 for body B
  * @param {Float64Array} scratch at least 3 elements, overwritten
  *
@@ -50,34 +47,78 @@ import { world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inerti
  * @copyright Company Named Limited (c) 2026
  */
 export function apply_impulse_to_body(
-    ss, base, invM,
-    rx, ry, rz,
-    Px, Py, Pz,
+    ss, base,
+    lever, lever_offset,
+    impulse, impulse_offset,
+    sign,
+    scratch
+) {
+    apply_impulse_to_body_oriented(
+        ss, base,
+        ss, base + SBS_QX,
+        lever, lever_offset,
+        impulse, impulse_offset,
+        sign,
+        scratch
+    );
+}
+
+/**
+ * {@link apply_impulse_to_body} with the world inverse inertia evaluated at a given orientation rather
+ * than the one in the body's span, which the substep loop advances.
+ *
+ * For a constraint row whose effective mass was computed once, at one orientation, and is applied
+ * across substeps while the body turns: the impulse must go through the inertia that mass was
+ * computed from, or the row's Gauss-Seidel update over-corrects by the ratio of the two.
+ *
+ * @param {Float64Array} ss solver body state array
+ * @param {number} base offset of this body's span within `ss`
+ * @param {Float64Array} rotation holds the orientation the world inverse inertia is evaluated at, a unit
+ *        quaternion `[x, y, z, w]`
+ * @param {number} rotation_offset where in `rotation` its x is
+ * @param {Float64Array} lever holds the lever arm, from centre of mass to the application point
+ * @param {number} lever_offset where in `lever` its x is, y and z following
+ * @param {Float64Array} impulse holds the impulse `P`
+ * @param {number} impulse_offset where in `impulse` its x is, y and z following
+ * @param {number} sign +1 for body A, -1 for body B
+ * @param {Float64Array} scratch at least 3 elements, overwritten
+ */
+export function apply_impulse_to_body_oriented(
+    ss, base,
+    rotation, rotation_offset,
+    lever, lever_offset,
+    impulse, impulse_offset,
     sign,
     scratch
 ) {
+    const invM = ss[base + SBS_INV_MASS];
 
     if (invM === 0) {
         return;
     }
 
-    const sPx = sign * Px;
-    const sPy = sign * Py;
-    const sPz = sign * Pz;
+    const sPx = sign * impulse[impulse_offset];
+    const sPy = sign * impulse[impulse_offset + 1];
+    const sPz = sign * impulse[impulse_offset + 2];
 
     ss[base + SBS_LV_X] += sPx * invM;
     ss[base + SBS_LV_Y] += sPy * invM;
     ss[base + SBS_LV_Z] += sPz * invM;
 
-    const tx = ry * sPz - rz * sPy;
-    const ty = rz * sPx - rx * sPz;
-    const tz = rx * sPy - ry * sPx;
+    const rx = lever[lever_offset];
+    const ry = lever[lever_offset + 1];
+    const rz = lever[lever_offset + 2];
+
+    // the torque r x P, transformed in place by the world inverse inertia
+    scratch[0] = ry * sPz - rz * sPy;
+    scratch[1] = rz * sPx - rx * sPz;
+    scratch[2] = rx * sPy - ry * sPx;
 
-    world_inverse_inertia_apply_raw(
+    world_inverse_inertia_apply_array(
         scratch, 0,
-        ss[base + SBS_INV_I_X], ss[base + SBS_INV_I_Y], ss[base + SBS_INV_I_Z],
-        ss[base + SBS_QX], ss[base + SBS_QY], ss[base + SBS_QZ], ss[base + SBS_QW],
-        tx, ty, tz
+        ss, base + SBS_INV_I_X,
+        rotation, rotation_offset,
+        scratch, 0
     );
 
     ss[base + SBS_AV_X] += scratch[0];

package/src/engine/physics/solver/solve_contacts.d.ts

@@ -15,8 +15,8 @@
 export function prepare_contacts(manifolds: ManifoldStore, system: PhysicsSystem, dt_sub: number): number;
 /**
  * Stage 1b (per substep) — warm-start: replay the cached accumulated
- * impulses `(j_n, j_t1, j_t2)` onto persistent velocity using the current
- * (refreshed) lever arms and tangents. Run once per substep, after
+ * impulses `(j_n, j_t1, j_t2)` onto persistent velocity through the row's
+ * lever arms, tangents and prepared orientations. Run once per substep, after
  * {@link refresh_contacts} and before {@link solve_velocity}.
  *
  * Per-substep warm-start is the crux of stable TGS: the stored impulse is a
@@ -41,11 +41,23 @@ export function warm_start_contacts(manifolds: ManifoldStore, system: PhysicsSys
  *    `Δseparation = (cpA − wA − (cpB − wB)) · n` is the change since prepare.
  *    Anchoring on the trusted prepare-time depth makes the sign convention
  *    irrelevant — only the analytic delta uses the anchors;
- *  - rebuild the impulse levers `rA`/`rB` from the moved midpoint;
  *  - recompute the position-correction bias from `depth_now`.
  *
  * The contact normal and tangents are held fixed for the outer step (valid
- * for the small per-step rotation), so they are not recomputed here.
+ * for the small per-step rotation), so they are not recomputed here. Nor are
+ * the impulse levers `rA` / `rB`: the row's effective mass was built from the
+ * prepared ones, and the levers must stay inside the bodies — the midpoint of
+ * the moved witnesses travels at half the slip speed, so a box sliding out
+ * from under another at 150 m/s carried it a metre past both within the step.
+ *
+ * Except a side with zero inverse mass (static, kinematic, asleep): its lever
+ * enters no mass, so it is moved to where the other side's contact point now
+ * is (that side's fixed lever from its current centre). Held at the prepared
+ * point, a kinematic turntable's surface velocity was read along the tangent
+ * of where the rider had been at the start of the step, for the whole step:
+ * a box gripped at 3 m on a table at 1 rad/s crept outward 0.33 m in 10 s,
+ * whatever the substep count. Two movable bodies keep both levers fixed, as
+ * Box3D does for every pair; a box on a free spinning disc creeps as that did.
  *
  * @param {ManifoldStore} manifolds
  * @param {Transform64[]} transforms
@@ -57,8 +69,8 @@ export function refresh_contacts(manifolds: ManifoldStore, transforms: Transform
  * For each concave-involved slot, re-runs the narrowphase geometry at the
  * current substep pose ({@link redetect_pair_geometry}, which rewrites the
  * manifold's witness / normal / depth in place), then re-derives the solver
- * scratch (lever arms, tangent basis, effective masses, position bias) for
- * that slot's contacts from the fresh geometry. This is the whole point of
+ * scratch (lever arms, orientations, tangent basis, effective masses, position
+ * bias) for that slot's contacts from the fresh geometry. This is the whole point of
  * the concave path: a body rocking on a mesh changes which triangle (and
  * normal) it rests on within a single outer step, and freezing that — as the
  * convex analytic refresh does — pumps energy in. Re-detecting gives a
@@ -72,7 +84,7 @@ export function refresh_contacts(manifolds: ManifoldStore, transforms: Transform
  * with prepare.
  *
  * Must run before {@link refresh_contacts} / {@link warm_start_contacts} each
- * substep. `rest_bias` (captured at prepare) and the `scratch_max_jn`
+ * substep. `rest_bias` (captured at prepare) and the `scratch_total_jn`
  * restitution gate are preserved.
  *
  * @param {ManifoldStore} manifolds
@@ -83,7 +95,7 @@ export function redetect_concave_contacts(manifolds: ManifoldStore, system: Phys
 /**
  * Stage 3 (per substep) — velocity iterations enforcing pure
  * non-penetration (`vn → 0`) plus Coulomb-disk friction. No bias: depth
- * correction is the position pass, restitution is the one-shot pass.
+ * correction is the position pass, restitution is {@link apply_restitution}'s.
  *
  * @param {ManifoldStore} manifolds
  * @param {PhysicsSystem} system
@@ -91,18 +103,36 @@ export function redetect_concave_contacts(manifolds: ManifoldStore, system: Phys
  */
 export function solve_velocity(manifolds: ManifoldStore, system: PhysicsSystem, iters: number, use_bias?: boolean): void;
 /**
- * Stage 4 (once, after the substep loop) — one-shot restitution
- * (Box2D-v3 `b2ApplyRestitution`, Catto 2018). Drives `vn → -e · vn_approach`
- * exactly once per closing contact, gated on (a) the contact having been
- * closing faster than the threshold at prepare, and (b) a compressive
- * normal impulse having formed during the velocity solve. The added impulse
- * accumulates into the same normal-impulse slot so it composes with
- * warm-start next frame.
+ * Stage 4 (after the substep loop) — restitution (Box3D `b3ApplyRestitution`,
+ * Catto). `iterations` Gauss-Seidel passes over every contact whose combined
+ * restitution is non-zero, each driving an ARMED contact's normal velocity
+ * toward `-e · vn_approach` and holding the rest of those contacts to plain
+ * non-penetration, so a bounce at one point does not drive another into the
+ * ground. A contact is armed when (a) it was closing faster than
+ * `system.restitutionThreshold` at prepare and (b) it pressed with a compressive
+ * normal impulse during the velocity solve. The impulses accumulate into the
+ * same normal-impulse slot so they compose with warm-start next frame.
+ *
+ * Why passes: a body striking at several points at once — a cube landing flat
+ * — is a coupled problem, and one sweep leaves it unconverged. The row solved
+ * first takes more than its share of the bounce, through the body's rotation
+ * as well as its translation, and the body leaves the ground spinning: a cube
+ * dropped flat on frictionless ground at e = 0.8 left at 5.2 rad/s, rebounding
+ * at 0.77 of its impact speed.
+ *
+ * Why the cap: a pass that has not converged overshoots — the row solved first
+ * sends its contact apart faster than `e` times its approach, and the body
+ * leaves with more energy than it struck with. So each contact may return at
+ * most `e` times the impulse it pressed with (Poisson's kinetic restitution),
+ * measured by {@link scratch_total_jn} as the impulse it delivered. Ported
+ * from Box3D's contact_solver.c (MIT, Erin Catto), which counts that impulse
+ * twice per substep; see there for why this counts it once.
  *
  * @param {ManifoldStore} manifolds
  * @param {PhysicsSystem} system
+ * @param {number} iterations passes over the contacts; 0 applies no restitution
  */
-export function apply_restitution(manifolds: ManifoldStore, system: PhysicsSystem): void;
+export function apply_restitution(manifolds: ManifoldStore, system: PhysicsSystem, iterations: number): void;
 /**
  * Stage 5 (per substep) — split-impulse position correction. Normal-only
  * (friction in the pseudo-velocity pass is ill-defined). Reads the per-body
@@ -137,8 +167,12 @@ export function solve_position(manifolds: ManifoldStore, system: PhysicsSystem,
  * pseudo-velocity, restitution writes real velocity — so the order is
  * consistency, not behaviour.)
  *
- * The position pass writes `system.__pseudo_velocity`; the caller must zero
- * that buffer before this call and fold it into the pose afterwards.
+ * With hard contacts the position pass writes `system.__pseudo_velocity`, a
+ * correction for the caller to fold into the pose or drop. It accumulates onto
+ * the buffer, which must hold zeros where the pass writes: it does after a
+ * soft-contact `fixedUpdate`, or after `system.__reset_pseudo_velocity()`.
+ * The driver marks the buffer written, so the system's next step zeroes it
+ * before it integrates rather than applying the correction again.
  *
  * @param {ManifoldStore} manifolds
  * @param {PhysicsSystem} system
@@ -147,6 +181,19 @@ export function solve_position(manifolds: ManifoldStore, system: PhysicsSystem,
  * @param {number} [pos_iters]
  */
 export function solve_contacts(manifolds: ManifoldStore, system: PhysicsSystem, dt: number, iters?: number, pos_iters?: number): void;
+/**
+ * Penetration allowed without applying position correction. Eliminates
+ * micro-jitter at near-zero overlap.
+ * @type {number}
+ */
+export const PENETRATION_SLOP: number;
+/**
+ * Default approach speed, m/s, below which restitution is suppressed (no
+ * micro-bounce buzz on resting stacks) — the default of
+ * `PhysicsSystem.restitutionThreshold`, which is what the solver reads.
+ * @type {number}
+ */
+export const RESTITUTION_VELOCITY_THRESHOLD: number;
 /** Whether this step's contacts are SOFT (system.contactHertz > 0) —
  *  set by prepare_contacts; read by the per-substep geometry passes
  *  (separation bookkeeping) and by the system loop (position pass vs

package/src/engine/physics/solver/solve_contacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solve_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/solver/solve_contacts.js"],"names":[],"mappings":"AA+gBA;;;;;;;;;;;;;GAaG;AACH,0FAHW,MAAM,GACJ,MAAM,CA8NlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,2FA0CC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uEAFW,aAAa,QAmGvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iGA2GC;AAED;;;;;;;;GAQG;AACH,uFAFW,MAAM,4BAwJhB;AAED;;;;;;;;;;;GAWG;AACH,yFAuDC;AAED;;;;;;;;;;;;;;GAcG;AACH,2FAFW,MAAM,QA2EhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,oFAJW,MAAM,UACN,MAAM,cACN,MAAM,QAkDhB;AA1wCD;;;mBAGmB;AACnB,oCAAmC;AA3FnC;;;;;GAKG;AACH,0CAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,0CAFU,MAAM,CAEsB"}
+{"version":3,"file":"solve_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/solver/solve_contacts.js"],"names":[],"mappings":"AAoqBA;;;;;;;;;;;;;GAaG;AACH,0FAHW,MAAM,GACJ,MAAM,CA4OlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,2FAqCC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,uEAFW,aAAa,QAuGvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iGAwGC;AAED;;;;;;;;GAQG;AACH,uFAFW,MAAM,4BA6JhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,+FAFW,MAAM,QAmFhB;AAED;;;;;;;;;;;;;;GAcG;AACH,2FAFW,MAAM,QA0EhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,oFAJW,MAAM,UACN,MAAM,cACN,MAAM,QAmDhB;AAliDD;;;;GAIG;AACH,+BAFU,MAAM,CAEsB;AA6BtC;;;;;GAKG;AACH,6CAFU,MAAM,CAEkC;AAkClD;;;mBAGmB;AACnB,oCAAmC;AA5FnC;;;;;GAKG;AACH,0CAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,0CAFU,MAAM,CAEsB"}