@woosh/meep-engine 2.139.0 → 2.140.0

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

@@ -2,8 +2,8 @@
  * Apply the world-frame inverse inertia tensor of a rigid body to a world-space
  * vector and write the result.
  *
- * Body-frame inverse inertia is stored as a diagonal in principal axes
- * (`rb.inverseInertiaLocal`). World inverse inertia is
+ * Body-frame inverse inertia is supplied as a diagonal in principal axes
+ * (a Vector3-like with `.x .y .z`). World inverse inertia is
  * `I_w⁻¹ = R · diag · R^T` where `R` is the body's orientation. We compute
  * `result = R · diag · R^T · v` without materialising the full 3x3 matrix:
  *
@@ -17,21 +17,26 @@
  * Sphere short-circuit: if the inverse inertia is isotropic (ix === iy === iz),
  * the rotation cancels and `result = ix * v`. Skip the trig and save the work.
  *
+ * Decoupled from RigidBody / Transform on purpose — callers pass only what
+ * is actually read. Lets `compute_penetration` and other standalone
+ * geometry helpers reuse this without manufacturing a body.
+ *
  * @param {number[]|Float64Array} result length >= 3
  * @param {number} result_offset
- * @param {RigidBody} rb
- * @param {Transform} transform
+ * @param {{x: number, y: number, z: number}} inv_inertia_local
+ *        Body-frame inverse inertia diagonal (typically `rb.inverseInertiaLocal`).
+ * @param {{x: number, y: number, z: number, w: number}} rotation
+ *        Body orientation as a unit quaternion (typically `transform.rotation`).
  * @param {number} vx
  * @param {number} vy
  * @param {number} vz
  */
 export function world_inverse_inertia_apply(
     result, result_offset,
-    rb, transform,
+    inv_inertia_local, rotation,
     vx, vy, vz
 ) {
-    const ii = rb.inverseInertiaLocal;
-    const ix = ii.x, iy = ii.y, iz = ii.z;
+    const ix = inv_inertia_local.x, iy = inv_inertia_local.y, iz = inv_inertia_local.z;
 
     if (ix === iy && iy === iz) {
         // Isotropic — rotation cancels.
@@ -41,39 +46,32 @@ export function world_inverse_inertia_apply(
         return;
     }
 
-    const q = transform.rotation;
-    const qx = q.x, qy = q.y, qz = q.z, qw = q.w;
+    const qx = rotation.x, qy = rotation.y, qz = rotation.z, qw = rotation.w;
 
     // Step 1: v_body = R^T · v.  R^T corresponds to applying the conjugate
-    // quaternion (-qx, -qy, -qz, qw).
-    // Identity: v' = q · v · q*. For inverse rotation use q* on either side.
-    // Equivalent expanded form:
-    //   t = (q* · v_quat)   where v_quat = (vx, vy, vz, 0)
-    //   v_body = (t · q).xyz
-    {
-        const cx = -qx, cy = -qy, cz = -qz;
-        // t = c · v (Hamilton product, treating v as pure quaternion w=0)
-        const tx = qw * vx + cy * vz - cz * vy;
-        const ty = qw * vy + cz * vx - cx * vz;
-        const tz = qw * vz + cx * vy - cy * vx;
-        const tw = -cx * vx - cy * vy - cz * vz;
-        // v_body = t · (c*)  where c* = (qx, qy, qz, qw)
-        const vbx = tx * qw + tw * qx + ty * qz - tz * qy;
-        const vby = ty * qw + tw * qy + tz * qx - tx * qz;
-        const vbz = tz * qw + tw * qz + tx * qy - ty * qx;
+    // quaternion (-qx, -qy, -qz, qw). Inlined for V8 inliner — see
+    // PosedShape.support and core/geom/vec3/v3_quat3_apply_inverse.js
+    // for the canonical form.
+    const cx = -qx, cy = -qy, cz = -qz;
+    const tx = qw * vx + cy * vz - cz * vy;
+    const ty = qw * vy + cz * vx - cx * vz;
+    const tz = qw * vz + cx * vy - cy * vx;
+    const tw = -cx * vx - cy * vy - cz * vz;
+    const vbx = tx * qw + tw * qx + ty * qz - tz * qy;
+    const vby = ty * qw + tw * qy + tz * qx - tx * qz;
+    const vbz = tz * qw + tw * qz + tx * qy - ty * qx;
 
-        // Step 2: scale by diagonal.
-        const sx = vbx * ix;
-        const sy = vby * iy;
-        const sz = vbz * iz;
+    // Step 2: scale by the principal-frame diagonal.
+    const sx = vbx * ix;
+    const sy = vby * iy;
+    const sz = vbz * iz;
 
-        // Step 3: result = R · scaled = q · scaled · q*
-        const ux = qw * sx + qy * sz - qz * sy;
-        const uy = qw * sy + qz * sx - qx * sz;
-        const uz = qw * sz + qx * sy - qy * sx;
-        const uw = -qx * sx - qy * sy - qz * sz;
-        result[result_offset]     = ux * qw + uw * (-qx) + uy * (-qz) - uz * (-qy);
-        result[result_offset + 1] = uy * qw + uw * (-qy) + uz * (-qx) - ux * (-qz);
-        result[result_offset + 2] = uz * qw + uw * (-qz) + ux * (-qy) - uy * (-qx);
-    }
+    // Step 3: result = R · scaled = q · scaled · q*. Inlined likewise.
+    const ux =  qw * sx + qy * sz - qz * sy;
+    const uy =  qw * sy + qz * sx - qx * sz;
+    const uz =  qw * sz + qx * sy - qy * sx;
+    const uw = -qx * sx - qy * sy - qz * sz;
+    result[result_offset]     = ux * qw + uw * (-qx) + uy * (-qz) - uz * (-qy);
+    result[result_offset + 1] = uy * qw + uw * (-qy) + uz * (-qx) - ux * (-qz);
+    result[result_offset + 2] = uz * qw + uw * (-qz) + ux * (-qy) - uy * (-qx);
 }

package/src/engine/physics/integration/integrate_position.d.ts

@@ -1,16 +1,34 @@
 /**
  * Integrate `transform.position` and `transform.rotation` from the body's
- * current linear and angular velocity over a step `dt`. Static bodies are not
- * touched.
+ * current linear and angular velocity over a step `dt`. Static bodies are
+ * not touched.
  *
- * KinematicPosition bodies are treated like Dynamic for the position update —
- * if the gameplay code is driving them, their velocity is whatever the user
- * wrote (typically zero); the step is effectively a no-op in that case.
- * KinematicVelocity bodies advance under their user-set velocity.
+ * The trailing six arguments are the body's *pseudo-velocity*: the
+ * position-pass output from the constraint solver (Catto split-impulse).
+ * Pseudo-velocity exists only inside the step — it's folded into the
+ * integration so the position update reflects depth correction, then
+ * implicitly discarded. The body's persistent `linearVelocity` /
+ * `angularVelocity` (which carry restitution + warm-start across steps)
+ * are never contaminated by it.
+ *
+ * Callers with no position-pass output should pass zeros for the six
+ * pseudo arguments — folding zero is free (one add per axis).
+ *
+ * KinematicPosition bodies are treated like Dynamic for the position
+ * update — if the gameplay code is driving them, their velocity is
+ * whatever the user wrote (typically zero); the step is effectively a
+ * no-op in that case. KinematicVelocity bodies advance under their
+ * user-set velocity.
  *
  * @param {RigidBody} rb
  * @param {Transform} transform
  * @param {number} dt
+ * @param {number} ps_lin_x pseudo-linear-velocity x (0 when no contacts)
+ * @param {number} ps_lin_y
+ * @param {number} ps_lin_z
+ * @param {number} ps_ang_x pseudo-angular-velocity x (0 when no contacts)
+ * @param {number} ps_ang_y
+ * @param {number} ps_ang_z
  */
-export function integrate_position(rb: RigidBody, transform: Transform, dt: number): void;
+export function integrate_position(rb: RigidBody, transform: Transform, dt: number, ps_lin_x: number, ps_lin_y: number, ps_lin_z: number, ps_ang_x: number, ps_ang_y: number, ps_ang_z: number): void;
 //# sourceMappingURL=integrate_position.d.ts.map

package/src/engine/physics/integration/integrate_position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrate_position.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_position.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,4EAFW,MAAM,QA8BhB"}
+{"version":3,"file":"integrate_position.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_position.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,4EARW,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,QA2ChB"}

package/src/engine/physics/integration/integrate_position.js

@@ -5,19 +5,41 @@ const scratch_q = new Float64Array(4);
 
 /**
  * Integrate `transform.position` and `transform.rotation` from the body's
- * current linear and angular velocity over a step `dt`. Static bodies are not
- * touched.
+ * current linear and angular velocity over a step `dt`. Static bodies are
+ * not touched.
  *
- * KinematicPosition bodies are treated like Dynamic for the position update —
- * if the gameplay code is driving them, their velocity is whatever the user
- * wrote (typically zero); the step is effectively a no-op in that case.
- * KinematicVelocity bodies advance under their user-set velocity.
+ * The trailing six arguments are the body's *pseudo-velocity*: the
+ * position-pass output from the constraint solver (Catto split-impulse).
+ * Pseudo-velocity exists only inside the step — it's folded into the
+ * integration so the position update reflects depth correction, then
+ * implicitly discarded. The body's persistent `linearVelocity` /
+ * `angularVelocity` (which carry restitution + warm-start across steps)
+ * are never contaminated by it.
+ *
+ * Callers with no position-pass output should pass zeros for the six
+ * pseudo arguments — folding zero is free (one add per axis).
+ *
+ * KinematicPosition bodies are treated like Dynamic for the position
+ * update — if the gameplay code is driving them, their velocity is
+ * whatever the user wrote (typically zero); the step is effectively a
+ * no-op in that case. KinematicVelocity bodies advance under their
+ * user-set velocity.
  *
  * @param {RigidBody} rb
  * @param {Transform} transform
  * @param {number} dt
+ * @param {number} ps_lin_x pseudo-linear-velocity x (0 when no contacts)
+ * @param {number} ps_lin_y
+ * @param {number} ps_lin_z
+ * @param {number} ps_ang_x pseudo-angular-velocity x (0 when no contacts)
+ * @param {number} ps_ang_y
+ * @param {number} ps_ang_z
  */
-export function integrate_position(rb, transform, dt) {
+export function integrate_position(
+    rb, transform, dt,
+    ps_lin_x, ps_lin_y, ps_lin_z,
+    ps_ang_x, ps_ang_y, ps_ang_z,
+) {
     if (rb.kind === BodyKind.Static) {
         return;
     }
@@ -25,22 +47,31 @@ export function integrate_position(rb, transform, dt) {
     const lv = rb.linearVelocity;
     const p = transform.position;
 
+    // Combined integration velocity: persistent + pseudo. The pseudo
+    // contribution exists only for this step and never lands in `lv`.
+    const vx = lv[0] + ps_lin_x;
+    const vy = lv[1] + ps_lin_y;
+    const vz = lv[2] + ps_lin_z;
+
     // Direct reads via typed-array index; the write goes through .set() so
     // Transform's onChanged subscribers (matrix recompose, parent/child sync,
     // viewport position, fog-of-war reveal) fire once per body per step.
     p.set(
-        p[0] + lv[0] * dt,
-        p[1] + lv[1] * dt,
-        p[2] + lv[2] * dt
+        p[0] + vx * dt,
+        p[1] + vy * dt,
+        p[2] + vz * dt
     );
 
     const av = rb.angularVelocity;
-    if (av[0] !== 0 || av[1] !== 0 || av[2] !== 0) {
+    const wx = av[0] + ps_ang_x;
+    const wy = av[1] + ps_ang_y;
+    const wz = av[2] + ps_ang_z;
+    if (wx !== 0 || wy !== 0 || wz !== 0) {
         const q = transform.rotation;
         quat_integrate(
             scratch_q,
             q[0], q[1], q[2], q[3],
-            av[0], av[1], av[2],
+            wx, wy, wz,
             dt
         );
         q.set(scratch_q[0], scratch_q[1], scratch_q[2], scratch_q[3]);

package/src/engine/physics/integration/integrate_velocity.d.ts

@@ -22,4 +22,34 @@
  * @param {number} dt step size in seconds
  */
 export function integrate_velocity(rb: RigidBody, transform: Transform, gx: number, gy: number, gz: number, dt: number): void;
+/**
+ * Apply the accumulated force / torque to velocity over a step `dt`, then
+ * zero the accumulators. Gravity and damping are NOT applied here.
+ *
+ * The "once per outer step" half of the TGS integrator: a user force is a
+ * per-frame budget that must land in full exactly once, independent of
+ * substep count. Gravity is the continuous field re-applied every substep
+ * by {@link integrate_velocity_gravity}.
+ *
+ * @param {RigidBody} rb
+ * @param {Transform} transform  used to rotate body-frame inertia into world
+ * @param {number} dt full outer-step size in seconds
+ */
+export function integrate_velocity_forces(rb: RigidBody, transform: Transform, dt: number): void;
+/**
+ * Apply gravity and velocity damping over a (sub)step `dt`. Does NOT touch
+ * the force / torque accumulators (consumed once by
+ * {@link integrate_velocity_forces}).
+ *
+ * The "every substep" half of the TGS integrator. Per substep the body sees
+ * only `g·h` of gravity, which the per-substep contact warm-start + solve
+ * cancels exactly — keeping a resting stack at zero velocity. Damping is the
+ * stable implicit decay `v *= 1/(1 + d·dt)` applied at the substep `dt`.
+ *
+ * @param {RigidBody} rb
+ * @param {Transform} transform  (unused; signature symmetry with the family)
+ * @param {number} gx @param {number} gy @param {number} gz world gravity
+ * @param {number} dt sub-step size in seconds
+ */
+export function integrate_velocity_gravity(rb: RigidBody, transform: Transform, gx: number, gy: number, gz: number, dt: number): void;
 //# sourceMappingURL=integrate_velocity.d.ts.map

package/src/engine/physics/integration/integrate_velocity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrate_velocity.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_velocity.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4EALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoDhB"}
+{"version":3,"file":"integrate_velocity.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_velocity.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4EALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoDhB;AAED;;;;;;;;;;;;GAYG;AACH,mFAFW,MAAM,QA6BhB;AAED;;;;;;;;;;;;;;GAcG;AACH,oFAHW,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,QAwBhB"}

package/src/engine/physics/integration/integrate_velocity.js

@@ -60,7 +60,7 @@ export function integrate_velocity(rb, transform, gx, gy, gz, dt) {
     let avy = av[1];
     let avz = av[2];
     if (at[0] !== 0 || at[1] !== 0 || at[2] !== 0) {
-        world_inverse_inertia_apply(scratch_angular, 0, rb, transform, at[0], at[1], at[2]);
+        world_inverse_inertia_apply(scratch_angular, 0, rb.inverseInertiaLocal, transform.rotation, at[0], at[1], at[2]);
         avx += scratch_angular[0] * dt;
         avy += scratch_angular[1] * dt;
         avz += scratch_angular[2] * dt;
@@ -77,3 +77,84 @@ export function integrate_velocity(rb, transform, gx, gy, gz, dt) {
     af[0] = 0; af[1] = 0; af[2] = 0;
     at[0] = 0; at[1] = 0; at[2] = 0;
 }
+
+/**
+ * Apply the accumulated force / torque to velocity over a step `dt`, then
+ * zero the accumulators. Gravity and damping are NOT applied here.
+ *
+ * The "once per outer step" half of the TGS integrator: a user force is a
+ * per-frame budget that must land in full exactly once, independent of
+ * substep count. Gravity is the continuous field re-applied every substep
+ * by {@link integrate_velocity_gravity}.
+ *
+ * @param {RigidBody} rb
+ * @param {Transform} transform  used to rotate body-frame inertia into world
+ * @param {number} dt full outer-step size in seconds
+ */
+export function integrate_velocity_forces(rb, transform, dt) {
+    const af = rb.accumulatedForce;
+    const at = rb.accumulatedTorque;
+
+    if (rb.kind !== BodyKind.Dynamic) {
+        af[0] = 0; af[1] = 0; af[2] = 0;
+        at[0] = 0; at[1] = 0; at[2] = 0;
+        return;
+    }
+
+    const inv_m = rb.mass > 0 ? 1 / rb.mass : 0;
+
+    const lv = rb.linearVelocity;
+    lv[0] += af[0] * inv_m * dt;
+    lv[1] += af[1] * inv_m * dt;
+    lv[2] += af[2] * inv_m * dt;
+
+    if (at[0] !== 0 || at[1] !== 0 || at[2] !== 0) {
+        world_inverse_inertia_apply(scratch_angular, 0, rb.inverseInertiaLocal, transform.rotation, at[0], at[1], at[2]);
+        const av = rb.angularVelocity;
+        av[0] += scratch_angular[0] * dt;
+        av[1] += scratch_angular[1] * dt;
+        av[2] += scratch_angular[2] * dt;
+    }
+
+    af[0] = 0; af[1] = 0; af[2] = 0;
+    at[0] = 0; at[1] = 0; at[2] = 0;
+}
+
+/**
+ * Apply gravity and velocity damping over a (sub)step `dt`. Does NOT touch
+ * the force / torque accumulators (consumed once by
+ * {@link integrate_velocity_forces}).
+ *
+ * The "every substep" half of the TGS integrator. Per substep the body sees
+ * only `g·h` of gravity, which the per-substep contact warm-start + solve
+ * cancels exactly — keeping a resting stack at zero velocity. Damping is the
+ * stable implicit decay `v *= 1/(1 + d·dt)` applied at the substep `dt`.
+ *
+ * @param {RigidBody} rb
+ * @param {Transform} transform  (unused; signature symmetry with the family)
+ * @param {number} gx @param {number} gy @param {number} gz world gravity
+ * @param {number} dt sub-step size in seconds
+ */
+export function integrate_velocity_gravity(rb, transform, gx, gy, gz, dt) {
+    if (rb.kind !== BodyKind.Dynamic) {
+        return;
+    }
+
+    const gs = rb.gravityScale;
+    const lv = rb.linearVelocity;
+    let lvx = lv[0] + gx * gs * dt;
+    let lvy = lv[1] + gy * gs * dt;
+    let lvz = lv[2] + gz * gs * dt;
+
+    if (rb.linearDamping > 0) {
+        const k = 1 / (1 + rb.linearDamping * dt);
+        lvx *= k; lvy *= k; lvz *= k;
+    }
+    lv[0] = lvx; lv[1] = lvy; lv[2] = lvz;
+
+    if (rb.angularDamping > 0) {
+        const av = rb.angularVelocity;
+        const k = 1 / (1 + rb.angularDamping * dt);
+        av[0] *= k; av[1] *= k; av[2] *= k;
+    }
+}

package/src/engine/physics/narrowphase/PosedShape.d.ts

@@ -45,14 +45,6 @@ export class PosedShape extends AbstractShape3D {
         z: number;
         w: number;
     }): void;
-    /**
-     * @param {number[]|Float32Array|Float64Array} result
-     * @param {number} result_offset
-     * @param {number} dx world-space query direction x (unit)
-     * @param {number} dy world-space query direction y
-     * @param {number} dz world-space query direction z
-     */
-    support(result: number[] | Float32Array | Float64Array, result_offset: number, dx: number, dy: number, dz: number): void;
     compute_bounding_box(result: any): void;
 }
 import { AbstractShape3D } from "../../../core/geom/3d/shape/AbstractShape3D.js";

package/src/engine/physics/narrowphase/PosedShape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PosedShape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/PosedShape.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAKQ,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CACd;IAEjB,WAAW;IAAE,WAAW;IAAE,WAAW;IACrC,WAAW;IAAE,WAAW;IAAE,WAAW;IAAE,WAAW;IAGtD;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAM1D;IAED;;;;;;OAMG;IACH,gBANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAyChB;IAED,wCASC;CACJ;gCA7G+B,gDAAgD"}
+{"version":3,"file":"PosedShape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/PosedShape.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAKQ,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CACd;IAEjB,WAAW;IAAE,WAAW;IAAE,WAAW;IACrC,WAAW;IAAE,WAAW;IAAE,WAAW;IAAE,WAAW;IAGtD;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAM1D;IAgDD,wCASC;CACJ;gCA1G+B,gDAAgD"}

package/src/engine/physics/narrowphase/PosedShape.js

@@ -1,5 +1,5 @@
+import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
 import { AbstractShape3D } from "../../../core/geom/3d/shape/AbstractShape3D.js";
-import { aabb_transform_oriented } from "../broadphase/aabb_transform_oriented.js";
 
 const scratch_local = new Float64Array(3);
 const scratch_local_aabb = new Float64Array(6);
@@ -57,49 +57,47 @@ export class PosedShape extends AbstractShape3D {
      * @param {number} dz world-space query direction z
      */
     support(result, result_offset, dx, dy, dz) {
-        // Rotate world direction into body frame using the conjugate quaternion.
-        // Conjugate: (-qx, -qy, -qz, qw). v_local = q* · v_world · q
+        // Inline q·v·q* math: PosedShape.support is the hottest GJK call
+        // (twice per iteration of the body-level fallback, once per
+        // triangle for concave dispatch). V8 declines to inline
+        // v3_quat3_apply at 9-arg call sites, so the math is repeated
+        // inline here at the cost of ~7 extra lines per direction.
+        // See core/geom/vec3/v3_quat3_apply.js for the canonical form
+        // — this is a literal expansion of it.
         const qx = this.qx, qy = this.qy, qz = this.qz, qw = this.qw;
 
-        // Apply conjugate quaternion to dir: same formula as Vector3.applyQuaternion
-        // but with (qx,qy,qz) negated.
-        const cx = -qx, cy = -qy, cz = -qz;
+        // Rotate world direction into body frame via the conjugate
+        // quaternion: v_local = q* · v_world · q.  Conjugate xyz are
+        // negated (cx, cy, cz below).
+        const tdx = qw * dx - qy * dz + qz * dy;
+        const tdy = qw * dy - qz * dx + qx * dz;
+        const tdz = qw * dz - qx * dy + qy * dx;
+        const tdw = qx * dx + qy * dy + qz * dz;
 
-        // t = c · v
-        const tx = qw * dx + cy * dz - cz * dy;
-        const ty = qw * dy + cz * dx - cx * dz;
-        const tz = qw * dz + cx * dy - cy * dx;
-        const tw = -cx * dx - cy * dy - cz * dz;
-
-        // result_local = t · c^-1; conjugate of c is (-cx,-cy,-cz,qw) = (qx,qy,qz,qw) = original q
-        const ldx = tx * qw + tw * (-cx) + ty * (-cz) - tz * (-cy);
-        const ldy = ty * qw + tw * (-cy) + tz * (-cx) - tx * (-cz);
-        const ldz = tz * qw + tw * (-cz) + tx * (-cy) - ty * (-cx);
+        const ldx = tdx * qw + tdw * qx + tdy * qz - tdz * qy;
+        const ldy = tdy * qw + tdw * qy + tdz * qx - tdx * qz;
+        const ldz = tdz * qw + tdw * qz + tdx * qy - tdy * qx;
 
         // Ask the local shape for its support point in body-local space.
         this.shape.support(scratch_local, 0, ldx, ldy, ldz);
 
-        // Rotate result back to world frame using original quaternion.
+        // Rotate the body-local support point back to world: v_world =
+        // q · v_local · q*.
         const lsx = scratch_local[0], lsy = scratch_local[1], lsz = scratch_local[2];
 
-        // v_world = q · v_local · q*
-        const ix = qw * lsx + qy * lsz - qz * lsy;
-        const iy = qw * lsy + qz * lsx - qx * lsz;
-        const iz = qw * lsz + qx * lsy - qy * lsx;
-        const iw = -qx * lsx - qy * lsy - qz * lsz;
-
-        const wx = ix * qw + iw * (-qx) + iy * (-qz) - iz * (-qy);
-        const wy = iy * qw + iw * (-qy) + iz * (-qx) - ix * (-qz);
-        const wz = iz * qw + iw * (-qz) + ix * (-qy) - iy * (-qx);
+        const tsx =  qw * lsx + qy * lsz - qz * lsy;
+        const tsy =  qw * lsy + qz * lsx - qx * lsz;
+        const tsz =  qw * lsz + qx * lsy - qy * lsx;
+        const tsw = -qx * lsx - qy * lsy - qz * lsz;
 
-        result[result_offset] = wx + this.px;
-        result[result_offset + 1] = wy + this.py;
-        result[result_offset + 2] = wz + this.pz;
+        result[result_offset]     = tsx * qw - tsw * qx - tsy * qz + tsz * qy + this.px;
+        result[result_offset + 1] = tsy * qw - tsw * qy - tsz * qx + tsx * qz + this.py;
+        result[result_offset + 2] = tsz * qw - tsw * qz - tsx * qy + tsy * qx + this.pz;
     }
 
     compute_bounding_box(result) {
         this.shape.compute_bounding_box(scratch_local_aabb);
-        aabb_transform_oriented(
+        aabb3_transform_oriented(
             result, 0,
             scratch_local_aabb[0], scratch_local_aabb[1], scratch_local_aabb[2],
             scratch_local_aabb[3], scratch_local_aabb[4], scratch_local_aabb[5],

package/src/engine/physics/narrowphase/box_box_manifold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AAiIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAwUnB;AA1bD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}
+{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AA+HA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA0anB;AAvhBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}

package/src/engine/physics/narrowphase/box_box_manifold.js

@@ -1,3 +1,6 @@
+import { line3_closest_points_segment_segment } from "../../../core/geom/3d/line/line3_closest_points_segment_segment.js";
+import { quat3_to_matrix3 } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
+
 /**
  * Multi-point manifold construction for two oriented bounding boxes.
  *
@@ -61,16 +64,11 @@ const clipped_uv_out = new Float64Array(8 * 2);
 // Stride 4 per candidate: x, y, z, depth.
 const candidates = new Float64Array(8 * 4);
 
-// --- helpers ---------------------------------------------------------------
+// Output of line3_closest_points_segment_segment for the edge-cross
+// SAT-winner path: (s, t) parameters along the two edges.
+const scratch_edge_st = new Float64Array(2);
 
-function quat_to_axes(out, off, qx, qy, qz, qw) {
-    const xx = qx * qx, yy = qy * qy, zz = qz * qz;
-    const xy = qx * qy, xz = qx * qz, yz = qy * qz;
-    const wx = qw * qx, wy = qw * qy, wz = qw * qz;
-    out[off]     = 1 - 2 * (yy + zz); out[off + 1] = 2 * (xy + wz);     out[off + 2] = 2 * (xz - wy);
-    out[off + 3] = 2 * (xy - wz);     out[off + 4] = 1 - 2 * (xx + zz); out[off + 5] = 2 * (yz + wx);
-    out[off + 6] = 2 * (xz + wy);     out[off + 7] = 2 * (yz - wx);     out[off + 8] = 1 - 2 * (xx + yy);
-}
+// --- helpers ---------------------------------------------------------------
 
 function projected_half_extent(axes, off, hx, hy, hz, lx, ly, lz) {
     const px = lx * axes[off]     + ly * axes[off + 1] + lz * axes[off + 2];
@@ -157,8 +155,8 @@ export function box_box_manifold(
     ax, ay, az, aqx, aqy, aqz, aqw, ahx, ahy, ahz,
     bx, by, bz, bqx, bqy, bqz, bqw, bhx, bhy, bhz
 ) {
-    quat_to_axes(scratch_axes_a, 0, aqx, aqy, aqz, aqw);
-    quat_to_axes(scratch_axes_b, 0, bqx, bqy, bqz, bqw);
+    quat3_to_matrix3(scratch_axes_a, 0, aqx, aqy, aqz, aqw);
+    quat3_to_matrix3(scratch_axes_b, 0, bqx, bqy, bqz, bqw);
 
     const ta = scratch_axes_a;
     const tb = scratch_axes_b;
@@ -217,14 +215,112 @@ export function box_box_manifold(
     const nx = best_nx, ny = best_ny, nz = best_nz;
     out[0] = nx; out[1] = ny; out[2] = nz;
 
-    // ---- Edge-cross axis: single-point fallback ----
+    // ---- Edge-cross axis: closest-pair on the two involved edges ----
+    //
+    // When SAT identifies an edge-edge separating axis (source 6..14 =
+    // 6 + i*3 + j, where `i` is box A's local edge-axis index and
+    // `j` is box B's), the contact happens where one specific edge of
+    // A crosses (or is closest to) one specific edge of B. The earlier
+    // body-centre-midpoint fallback was sufficient for "we know they
+    // collide" but produced lever arms that confused the solver — for
+    // skewed-box stacks this led to slow drift.
+    //
+    // Procedure:
+    //   1. Decode (i, j) from `best_source`.
+    //   2. Among box A's 4 parallel edges along axis i, pick the one
+    //      whose corner is most in the −n direction (closest to B).
+    //   3. Same for box B with +n direction.
+    //   4. `line3_closest_points_segment_segment` returns (s, t)
+    //      parameters; reconstruct the world contact on each edge.
     if (best_source >= 6) {
-        const mx = (ax + bx) * 0.5;
-        const my = (ay + by) * 0.5;
-        const mz = (az + bz) * 0.5;
+        const ax_src = best_source - 6;
+        const i_a = (ax_src / 3) | 0;
+        const j_b = ax_src - i_a * 3;
+
+        // Edge directions in world.
+        const edge_a_dx = ta[i_a * 3];
+        const edge_a_dy = ta[i_a * 3 + 1];
+        const edge_a_dz = ta[i_a * 3 + 2];
+        const edge_b_dx = tb[j_b * 3];
+        const edge_b_dy = tb[j_b * 3 + 1];
+        const edge_b_dz = tb[j_b * 3 + 2];
+
+        // Edge half-extents (along the chosen axis).
+        const edge_a_half = i_a === 0 ? ahx : (i_a === 1 ? ahy : ahz);
+        const edge_b_half = j_b === 0 ? bhx : (j_b === 1 ? bhy : bhz);
+
+        // Perpendicular axes (the other two) and their half-extents.
+        let u_a_idx, v_a_idx;
+        if (i_a === 0)      { u_a_idx = 1; v_a_idx = 2; }
+        else if (i_a === 1) { u_a_idx = 2; v_a_idx = 0; }
+        else                { u_a_idx = 0; v_a_idx = 1; }
+        const u_a_x = ta[u_a_idx * 3], u_a_y = ta[u_a_idx * 3 + 1], u_a_z = ta[u_a_idx * 3 + 2];
+        const v_a_x = ta[v_a_idx * 3], v_a_y = ta[v_a_idx * 3 + 1], v_a_z = ta[v_a_idx * 3 + 2];
+        const half_u_a = u_a_idx === 0 ? ahx : (u_a_idx === 1 ? ahy : ahz);
+        const half_v_a = v_a_idx === 0 ? ahx : (v_a_idx === 1 ? ahy : ahz);
+
+        let u_b_idx, v_b_idx;
+        if (j_b === 0)      { u_b_idx = 1; v_b_idx = 2; }
+        else if (j_b === 1) { u_b_idx = 2; v_b_idx = 0; }
+        else                { u_b_idx = 0; v_b_idx = 1; }
+        const u_b_x = tb[u_b_idx * 3], u_b_y = tb[u_b_idx * 3 + 1], u_b_z = tb[u_b_idx * 3 + 2];
+        const v_b_x = tb[v_b_idx * 3], v_b_y = tb[v_b_idx * 3 + 1], v_b_z = tb[v_b_idx * 3 + 2];
+        const half_u_b = u_b_idx === 0 ? bhx : (u_b_idx === 1 ? bhy : bhz);
+        const half_v_b = v_b_idx === 0 ? bhx : (v_b_idx === 1 ? bhy : bhz);
+
+        // The contact normal `n` (= best_n) points B → A. From A's
+        // perspective B is in the −n direction; pick the A-corner most
+        // in that direction. From B's perspective A is in +n; pick the
+        // B-corner most in +n.
+        const minus_n_dot_u_a = -(nx * u_a_x + ny * u_a_y + nz * u_a_z);
+        const minus_n_dot_v_a = -(nx * v_a_x + ny * v_a_y + nz * v_a_z);
+        const u_sign_a = minus_n_dot_u_a >= 0 ? 1 : -1;
+        const v_sign_a = minus_n_dot_v_a >= 0 ? 1 : -1;
+
+        const plus_n_dot_u_b = nx * u_b_x + ny * u_b_y + nz * u_b_z;
+        const plus_n_dot_v_b = nx * v_b_x + ny * v_b_y + nz * v_b_z;
+        const u_sign_b = plus_n_dot_u_b >= 0 ? 1 : -1;
+        const v_sign_b = plus_n_dot_v_b >= 0 ? 1 : -1;
+
+        // Box-A edge centre = A_centre + u_sign_a * half_u_a * u_a
+        //                              + v_sign_a * half_v_a * v_a.
+        const corner_a_cx = ax + u_a_x * u_sign_a * half_u_a + v_a_x * v_sign_a * half_v_a;
+        const corner_a_cy = ay + u_a_y * u_sign_a * half_u_a + v_a_y * v_sign_a * half_v_a;
+        const corner_a_cz = az + u_a_z * u_sign_a * half_u_a + v_a_z * v_sign_a * half_v_a;
+        const edge_a_p1_x = corner_a_cx - edge_a_dx * edge_a_half;
+        const edge_a_p1_y = corner_a_cy - edge_a_dy * edge_a_half;
+        const edge_a_p1_z = corner_a_cz - edge_a_dz * edge_a_half;
+        const edge_a_p2_x = corner_a_cx + edge_a_dx * edge_a_half;
+        const edge_a_p2_y = corner_a_cy + edge_a_dy * edge_a_half;
+        const edge_a_p2_z = corner_a_cz + edge_a_dz * edge_a_half;
+
+        const corner_b_cx = bx + u_b_x * u_sign_b * half_u_b + v_b_x * v_sign_b * half_v_b;
+        const corner_b_cy = by + u_b_y * u_sign_b * half_u_b + v_b_y * v_sign_b * half_v_b;
+        const corner_b_cz = bz + u_b_z * u_sign_b * half_u_b + v_b_z * v_sign_b * half_v_b;
+        const edge_b_p1_x = corner_b_cx - edge_b_dx * edge_b_half;
+        const edge_b_p1_y = corner_b_cy - edge_b_dy * edge_b_half;
+        const edge_b_p1_z = corner_b_cz - edge_b_dz * edge_b_half;
+        const edge_b_p2_x = corner_b_cx + edge_b_dx * edge_b_half;
+        const edge_b_p2_y = corner_b_cy + edge_b_dy * edge_b_half;
+        const edge_b_p2_z = corner_b_cz + edge_b_dz * edge_b_half;
+
+        line3_closest_points_segment_segment(
+            scratch_edge_st,
+            edge_a_p1_x, edge_a_p1_y, edge_a_p1_z, edge_a_p2_x, edge_a_p2_y, edge_a_p2_z,
+            edge_b_p1_x, edge_b_p1_y, edge_b_p1_z, edge_b_p2_x, edge_b_p2_y, edge_b_p2_z
+        );
+        const s = scratch_edge_st[0];
+        const t = scratch_edge_st[1];
+        const contact_a_x = edge_a_p1_x + s * (edge_a_p2_x - edge_a_p1_x);
+        const contact_a_y = edge_a_p1_y + s * (edge_a_p2_y - edge_a_p1_y);
+        const contact_a_z = edge_a_p1_z + s * (edge_a_p2_z - edge_a_p1_z);
+        const contact_b_x = edge_b_p1_x + t * (edge_b_p2_x - edge_b_p1_x);
+        const contact_b_y = edge_b_p1_y + t * (edge_b_p2_y - edge_b_p1_y);
+        const contact_b_z = edge_b_p1_z + t * (edge_b_p2_z - edge_b_p1_z);
+
         out[3] = 1;
-        out[4] = mx; out[5] = my;  out[6] = mz;
-        out[7] = mx; out[8] = my;  out[9] = mz;
+        out[4] = contact_a_x; out[5] = contact_a_y; out[6] = contact_a_z;
+        out[7] = contact_b_x; out[8] = contact_b_y; out[9] = contact_b_z;
         out[10] = best_overlap;
         return true;
     }