reze-engine 0.36.0 → 0.36.1

package/README.md

@@ -333,9 +333,10 @@ In-house sequential-impulse rigid-body solver for PMX rigs (sphere / box / capsu
 - **Implicit spring-dampers** — each sprung axis solves the backward-Euler soft constraint `relVel⁺ + (k/γ)·err + s·λ = 0` (`γ = c + h·k`, `s = 1/(h·γ)`), unconditionally stable for any authored stiffness, with damping `c = 2ζ√(k·m_eff)` intrinsic to the row. Resting cloth genuinely settles: the previous clamped velocity-drive could inject energy far from equilibrium but not absorb it near it, so static dresses slowly "boiled" — measured 15× lower resting velocity after the change, with authored stiffness now delivered in full (no deadbeat clamp).
 - **Angular limits** — hybrid: small violations (< 0.5 rad, the resting-cloth regime) use per-axis Euler stop rows, which converge cleanly and keep resting cloth still; larger violations switch to a single geodesic row toward the Euler-clamped target rotation, because per-axis Euler rows chase phantom errors near the ±90° singularity and pump energy. Ranged stops are unilateral (accumulated impulse clamped to the corrective sign) so a limit pushes back into range but never brakes natural recovery; locked axes stay bilateral equality joints. Spring rows stay per-axis, with stiffness clamped to the `k·dt² ≤ ¼` stability bound.
 - **Narrowphase** — analytical sphere-sphere / -capsule / -box, capsule-capsule / -box, and box-box (SAT + face clipping, up to 4 points per manifold). MMD dress rigs are built from box panels, and box-box is the majority of collidable pairs on those models — without it cloth passes through cloth. Capsule-capsule emits multiple contacts along near-parallel axes so cloth can't pivot around a single closest point.
-- **Speculative contacts** (`margin 0.04`) fire at near-touch and cancel only the approach velocity in excess of what closes the remaining gap in one substep (`gap/dt`), so they stop fast bodies tunneling thin surfaces while staying inert until the body would actually arrive. The push-only clamp does not achieve that on its own — it forbids a pulling impulse, not a large pushing one on a body still in mid-air.
-- **Contact relaxation** — each contact row's gain is `1/max(rows on A, rows on B)` over dynamic bodies (floor 0.12). Every row drives the relative velocity at its own point to zero, so a dress panel carrying dozens at once is over-braked, differently each substep; a body on a lone contact keeps full gain and still settles exactly. A flat factor damps the well-conditioned rows too and leaves single-contact bodies creeping instead of settling.
-- **Split-impulse correction** resolves penetration by a mass-weighted translation _outside_ the velocity solver, so joint pulls can't fight separation.
+- **Penetration and separation are one term**, ported from Bullet 2.75 (`m_erp` 0.2), the build MMD's own physics runs: the contact row's target carries `depth · erp / dt`. Penetrating, it pushes apart; separated — a speculative row inside the `0.04` margin — it *allows* the approach that closes the gap, which is what keeps those rows inert until the body would really arrive. A push-only clamp does not achieve that on its own: it forbids a pulling impulse, not a large pushing one on a body still in mid-air.
+- **Warm starting** (`0.85`) over persistent per-pair manifolds, up to 4 points matched in each body's own local frame, so a resting stack starts each substep already holding roughly the load it needs. When a 5th point arrives the one dropped is whichever leaves the largest quadrilateral — area is what stops a resting box pivoting.
+- **Contact ordering is reshuffled between iterations.** Projected Gauss-Seidel is order-biased, rows solved first win, and on a cross-linked skirt lattice that reads as chatter. The shuffle is re-seeded per substep, so a scene still replays identically.
+- **Split impulse** resolves deep overlap on a pseudo-velocity channel with its own full iteration pass, integrated straight into the transform. Recovering penetration therefore adds no real momentum for the joint springs to hand back — the property MMD depends on, given how constantly its hair and layered skirts clip.
 - **Kinematic advancement** — bone-driven bodies move toward the frame's bone pose incrementally per substep, with velocities derived over the fixed step, so the solver never sees more than one 60 Hz step of anchor motion regardless of render dt.
 - **Discontinuity guards** — a bone-pose jump beyond continuous motion (timeline scrub, long stall) rigidly carries each dynamic body along with its kinematic root's transform delta and zeroes momentum instead of dragging cloth across the gap; correction velocities are clamped (120 u/s linear, 30 rad/s angular), per-step travel is capped, and any body that still goes non-finite is restored to its previous substep pose.
 - Sleeping is off (cloth must always react); resting bodies bleed micro-velocity via per-PMX damping.

package/dist/physics/contact.d.ts

@@ -26,9 +26,18 @@ export interface Contact {
     cBzN: number;
     jacInvN: number;
     bounceVel: number;
-    /** Per-contact relaxation gain, 1/max(rows on A, rows on B). See CONTACT_SOR_MIN. */
-    sorGain: number;
-    allowedApproachVel: number;
+    /** Substeps this contact point has persisted (from the manifold cache).
+     *  Bullet kills restitution past m_restingContactRestitutionThreshold = 2. */
+    age: number;
+    /** Penetration term routed to the SPLIT (pseudo-velocity) channel instead of
+     *  the real one, when the contact is deeper than the split threshold. */
+    rhsPenetration: number;
+    /** Accumulated impulse on the split channel — Bullet's m_appliedPushImpulse. */
+    appliedPushImpulse: number;
+    /** Baumgarte bias, depth·ERP/dt — Bullet 2.75's positionalError. Positive
+     *  when penetrating (pushes apart), negative when separated (allows the
+     *  approach that closes the gap). See CONTACT_ERP. */
+    biasVel: number;
     t1x: number;
     t1y: number;
     t1z: number;

package/dist/physics/contact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contact.d.ts","sourceRoot":"","sources":["../../src/physics/contact.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAa5C,eAAO,MAAM,cAAc,OAAO,CAAA;AAElC,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IAEb,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IAEX,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IAEnB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,uBAAuB,EAAE,MAAM,CAAA;IAC/B,uBAAuB,EAAE,MAAM,CAAA;IAI/B,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;IACxC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAA;IAGf,kBAAkB,EAAE,MAAM,CAAA;IAE1B,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;IACrC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;IAC3C,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;IAC3C,QAAQ,EAAE,MAAM,CAAA;IAEhB,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;IACrC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;IAC3C,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;IAC3C,QAAQ,EAAE,MAAM,CAAA;CACjB;AAgCD,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAgB;IAC5B,KAAK,SAAI;IAET,OAAO,IAAI,OAAO;IAelB,KAAK,IAAI,IAAI;IAGb,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;CAGxB;AASD,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAahF;AAwoCD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAgDrG;AAiCD,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAsB3E"}
+{"version":3,"file":"contact.d.ts","sourceRoot":"","sources":["../../src/physics/contact.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAa5C,eAAO,MAAM,cAAc,OAAO,CAAA;AAElC,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IAEb,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IAEX,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IAEnB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,uBAAuB,EAAE,MAAM,CAAA;IAC/B,uBAAuB,EAAE,MAAM,CAAA;IAI/B,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;IACxC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB;kFAC8E;IAC9E,GAAG,EAAE,MAAM,CAAA;IACX;6EACyE;IACzE,cAAc,EAAE,MAAM,CAAA;IACtB,gFAAgF;IAChF,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;0DAEsD;IACtD,OAAO,EAAE,MAAM,CAAA;IAEf,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;IACrC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;IAC3C,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;IAC3C,QAAQ,EAAE,MAAM,CAAA;IAEhB,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;IACrC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;IAC3C,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;IAC3C,QAAQ,EAAE,MAAM,CAAA;CACjB;AAkCD,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAgB;IAC5B,KAAK,SAAI;IAET,OAAO,IAAI,OAAO;IAgBlB,KAAK,IAAI,IAAI;IAGb,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;CAGxB;AASD,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAahF;AAwoCD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAgDrG;AAiCD,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAsB3E"}

package/dist/physics/contact.js

@@ -35,8 +35,10 @@ function makeContact() {
         cBxN: 0, cByN: 0, cBzN: 0,
         jacInvN: 0,
         bounceVel: 0,
-        sorGain: 1,
-        allowedApproachVel: 0,
+        age: 0,
+        rhsPenetration: 0,
+        appliedPushImpulse: 0,
+        biasVel: 0,
         t1x: 0, t1y: 0, t1z: 0,
         cAxT1: 0, cAyT1: 0, cAzT1: 0,
         cBxT1: 0, cByT1: 0, cBzT1: 0,
@@ -59,6 +61,7 @@ export class ContactPool {
             c.appliedNormalImpulse = 0;
             c.appliedFrictionImpulse1 = 0;
             c.appliedFrictionImpulse2 = 0;
+            c.appliedPushImpulse = 0;
             this.count++;
             return c;
         }

package/dist/physics/manifold.d.ts

@@ -1,13 +1,34 @@
-import type { ContactPool } from "./contact";
-export declare class ImpulseCache {
-    private a;
-    private b;
-    /** Seed this substep's contacts with what the same rows converged to last
-     *  substep. Contacts with no history start at zero, as new contacts should. */
-    seed(pool: ContactPool): void;
-    /** Store the converged impulses, then swap: this substep's results become the
-     *  next one's history. Double-buffered so a pair that stops touching simply
-     *  falls out rather than needing an expiry sweep. */
-    writeback(pool: ContactPool): void;
+interface Point {
+    /** Contact point in each body's local frame (lever arms are world-space and
+     *  rotate with the body, so they cannot be compared across substeps). */
+    lax: number;
+    lay: number;
+    laz: number;
+    lbx: number;
+    lby: number;
+    lbz: number;
+    normalImpulse: number;
+    frictionImpulse1: number;
+    frictionImpulse2: number;
+    /** Substeps this point has survived — Bullet disables restitution past
+     *  m_restingContactRestitutionThreshold (2) so resting contacts stop bouncing. */
+    age: number;
+    /** Marks points seen this substep; unseen ones are dropped. */
+    seen: boolean;
 }
+export declare class ManifoldCache {
+    private pairs;
+    private touched;
+    private static key;
+    /** Look up what this contact point converged to last substep. Returns null
+     *  when it is new. */
+    find(a: number, b: number, lax: number, lay: number, laz: number): Point | null;
+    /** Record what this point converged to, for the next substep to start from. */
+    store(a: number, b: number, lax: number, lay: number, laz: number, lbx: number, lby: number, lbz: number, normalImpulse: number, frictionImpulse1: number, frictionImpulse2: number, age: number): void;
+    /** Drop every point not re-seen this substep, and every pair left empty.
+     *  Without this a separated pair keeps handing back a stale impulse. */
+    endStep(): void;
+    clear(): void;
+}
+export {};
 //# sourceMappingURL=manifold.d.ts.map

package/dist/physics/manifold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifold.d.ts","sourceRoot":"","sources":["../../src/physics/manifold.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAK5C,qBAAa,YAAY;IACvB,OAAO,CAAC,CAAC,CAAkC;IAC3C,OAAO,CAAC,CAAC,CAAkC;IAE3C;mFAC+E;IAC/E,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAmB7B;;yDAEqD;IACrD,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;CAgBnC"}
+{"version":3,"file":"manifold.d.ts","sourceRoot":"","sources":["../../src/physics/manifold.ts"],"names":[],"mappings":"AAuBA,UAAU,KAAK;IACb;6EACyE;IACzE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;IACrC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;IACxB,gBAAgB,EAAE,MAAM,CAAA;IACxB;sFACkF;IAClF,GAAG,EAAE,MAAM,CAAA;IACX,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAA;CACd;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,OAAO,CAAoB;IAEnC,OAAO,CAAC,MAAM,CAAC,GAAG;IAIlB;0BACsB;IACtB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAc/E,+EAA+E;IAC/E,KAAK,CACH,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EACrC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EACrC,aAAa,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EACzE,GAAG,EAAE,MAAM,GACV,IAAI;IAoCP;4EACwE;IACxE,OAAO,IAAI,IAAI;IAgBf,KAAK,IAAI,IAAI;CAId"}

package/dist/physics/manifold.js

@@ -1,68 +1,148 @@
-// Contact impulse history — the cache that makes warm starting possible.
+// Persistent contact manifolds — the cache that makes warm starting possible.
 //
-// Bullet keeps a btPersistentManifold per body pair and carries each point's
-// m_appliedImpulse into the next substep at m_warmstartingFactor (0.85), so a
-// resting contact starts from the answer it converged to last time instead of
-// from zero. Without it a sustained contact is rediscovered every substep:
-// it overshoots, releases, re-forms — which is chatter. Measured here, contacts
-// account for ALL of the visible shake under animation (25 shaking bodies with
-// contacts on, 0 with them off), so this is the mechanism that matters.
+// Bullet 2.75 keeps a btPersistentManifold per body pair holding up to 4 points,
+// each carrying the impulse it converged to last step. At setup the solver seeds
+// each row with `cp.m_appliedImpulse * m_warmstartingFactor` (0.85) and applies
+// it immediately, so a resting stack starts the substep already holding roughly
+// the load it needs instead of rediscovering it from zero every time.
 //
-// Identity is by ORDINAL within the pair, not by proximity. Our narrowphase is
-// deterministic — the same pair walks the same code path and emits its contacts
-// in the same order every substep — so "the third contact of this pair" is a
-// stabler key than "the cached point nearest this one", which needs a distance
-// threshold and mis-pairs whenever two contacts fall inside it.
-const MAX_PER_PAIR = 8;
-const STRIDE = 3; // normal, friction1, friction2
-export class ImpulseCache {
+// That is not a nicety here: penetration recovery rides in the contact velocity
+// row as a Baumgarte term, and a row rebuilt from zero each substep overshoots
+// it. Warm starting on its own was measured WORSE on this engine — but that was
+// against a solver with no bias term and a position-correction pass, which is a
+// different system. The two are one design in Bullet and are ported as one.
+//
+// Points are matched by proximity in each body's own local frame, which is what
+// btPersistentManifold does — a world-space match would drift with the body.
+const MAX_POINTS = 4;
+/** Match radius, in model units. Bullet's gContactBreakingThreshold is 0.02;
+ *  ours is the contact margin, so a point that merely slid along a face is
+ *  still recognised as the same point rather than dropped and rebuilt. */
+const MATCH_DIST_SQ = 0.04 * 0.04;
+export class ManifoldCache {
     constructor() {
-        this.a = new Map();
-        this.b = new Map();
+        this.pairs = new Map();
+        this.touched = new Set();
     }
-    /** Seed this substep's contacts with what the same rows converged to last
-     *  substep. Contacts with no history start at zero, as new contacts should. */
-    seed(pool) {
-        const ord = new Map();
-        for (let i = 0; i < pool.count; i++) {
-            const c = pool.get(i);
-            const key = c.bodyA * 65536 + c.bodyB;
-            const n = ord.get(key) ?? 0;
-            ord.set(key, n + 1);
-            c.manifoldKey = key;
-            c.manifoldSlot = n;
-            if (n >= MAX_PER_PAIR)
-                continue;
-            const prev = this.a.get(key);
-            if (!prev)
-                continue;
-            const o = n * STRIDE;
-            c.appliedNormalImpulse = prev[o];
-            c.appliedFrictionImpulse1 = prev[o + 1];
-            c.appliedFrictionImpulse2 = prev[o + 2];
+    static key(a, b) {
+        return a < b ? a * 65536 + b : b * 65536 + a;
+    }
+    /** Look up what this contact point converged to last substep. Returns null
+     *  when it is new. */
+    find(a, b, lax, lay, laz) {
+        const list = this.pairs.get(ManifoldCache.key(a, b));
+        if (list === undefined)
+            return null;
+        let best = null;
+        let bestD = MATCH_DIST_SQ;
+        for (let i = 0; i < list.length; i++) {
+            const p = list[i];
+            const dx = p.lax - lax, dy = p.lay - lay, dz = p.laz - laz;
+            const d = dx * dx + dy * dy + dz * dz;
+            if (d < bestD) {
+                bestD = d;
+                best = p;
+            }
+        }
+        return best;
+    }
+    /** Record what this point converged to, for the next substep to start from. */
+    store(a, b, lax, lay, laz, lbx, lby, lbz, normalImpulse, frictionImpulse1, frictionImpulse2, age) {
+        const k = ManifoldCache.key(a, b);
+        this.touched.add(k);
+        let list = this.pairs.get(k);
+        if (list === undefined) {
+            list = [];
+            this.pairs.set(k, list);
+        }
+        // Replace the nearest existing point, else append; past MAX_POINTS drop the
+        // shallowest-held one so the manifold keeps the load-bearing corners.
+        let best = -1;
+        let bestD = MATCH_DIST_SQ;
+        for (let i = 0; i < list.length; i++) {
+            const p = list[i];
+            const dx = p.lax - lax, dy = p.lay - lay, dz = p.laz - laz;
+            const d = dx * dx + dy * dy + dz * dz;
+            if (d < bestD) {
+                bestD = d;
+                best = i;
+            }
+        }
+        if (best < 0) {
+            if (list.length < MAX_POINTS) {
+                list.push({ lax, lay, laz, lbx, lby, lbz, normalImpulse, frictionImpulse1, frictionImpulse2, age, seen: true });
+                return;
+            }
+            // btPersistentManifold::sortCachedPoints — when a 5th point arrives, drop
+            // whichever of the 5 leaves the largest quadrilateral. Area is what keeps
+            // a resting box from pivoting; dropping the shallowest instead can leave
+            // four nearly-collinear points that pin position but not orientation.
+            best = worstAreaIndex(list, lax, lay, laz);
         }
+        const p = list[best];
+        p.lax = lax;
+        p.lay = lay;
+        p.laz = laz;
+        p.lbx = lbx;
+        p.lby = lby;
+        p.lbz = lbz;
+        p.normalImpulse = normalImpulse;
+        p.frictionImpulse1 = frictionImpulse1;
+        p.frictionImpulse2 = frictionImpulse2;
+        p.age = age;
+        p.seen = true;
     }
-    /** Store the converged impulses, then swap: this substep's results become the
-     *  next one's history. Double-buffered so a pair that stops touching simply
-     *  falls out rather than needing an expiry sweep. */
-    writeback(pool) {
-        this.b.clear();
-        for (let i = 0; i < pool.count; i++) {
-            const c = pool.get(i);
-            if (c.manifoldSlot >= MAX_PER_PAIR)
+    /** Drop every point not re-seen this substep, and every pair left empty.
+     *  Without this a separated pair keeps handing back a stale impulse. */
+    endStep() {
+        for (const [k, list] of this.pairs) {
+            if (!this.touched.has(k)) {
+                this.pairs.delete(k);
                 continue;
-            let arr = this.b.get(c.manifoldKey);
-            if (!arr) {
-                arr = new Float32Array(MAX_PER_PAIR * STRIDE);
-                this.b.set(c.manifoldKey, arr);
             }
-            const o = c.manifoldSlot * STRIDE;
-            arr[o] = c.appliedNormalImpulse;
-            arr[o + 1] = c.appliedFrictionImpulse1;
-            arr[o + 2] = c.appliedFrictionImpulse2;
+            let w = 0;
+            for (let i = 0; i < list.length; i++) {
+                const p = list[i];
+                if (!p.seen)
+                    continue;
+                p.seen = false;
+                list[w++] = p;
+            }
+            list.length = w;
+            if (w === 0)
+                this.pairs.delete(k);
+        }
+        this.touched.clear();
+    }
+    clear() {
+        this.pairs.clear();
+        this.touched.clear();
+    }
+}
+/** Which of the 4 cached points to replace so the surviving quad keeps the most
+ *  area once the new point joins it. */
+function worstAreaIndex(list, nx, ny, nz) {
+    let bestIdx = 0;
+    let bestArea = -1;
+    for (let drop = 0; drop < list.length; drop++) {
+        // The quad is: the new point plus the three survivors.
+        const pts = [[nx, ny, nz]];
+        for (let i = 0; i < list.length; i++)
+            if (i !== drop)
+                pts.push([list[i].lax, list[i].lay, list[i].laz]);
+        if (pts.length < 4)
+            continue;
+        // |d0 × d1| over the diagonals — Bullet's area proxy.
+        const d0x = pts[0][0] - pts[2][0], d0y = pts[0][1] - pts[2][1], d0z = pts[0][2] - pts[2][2];
+        const d1x = pts[1][0] - pts[3][0], d1y = pts[1][1] - pts[3][1], d1z = pts[1][2] - pts[3][2];
+        const cx = d0y * d1z - d0z * d1y;
+        const cy = d0z * d1x - d0x * d1z;
+        const cz = d0x * d1y - d0y * d1x;
+        const area = cx * cx + cy * cy + cz * cz;
+        if (area > bestArea) {
+            bestArea = area;
+            bestIdx = drop;
         }
-        const t = this.a;
-        this.a = this.b;
-        this.b = t;
     }
+    return bestIdx;
 }

package/dist/physics/solver.d.ts

@@ -1,7 +1,11 @@
 import type { RigidBodyStore } from "./body";
 import type { SixDofSpringConstraint } from "./constraint";
 import type { ContactPool } from "./contact";
-export declare function solveConstraints(store: RigidBodyStore, constraints: SixDofSpringConstraint[], cache: SolverCache, contacts: ContactPool, dt: number, iterations: number): void;
+import type { ManifoldCache } from "./manifold";
+export declare function solveConstraints(store: RigidBodyStore, constraints: SixDofSpringConstraint[], cache: SolverCache, contacts: ContactPool, dt: number, iterations: number, manifolds?: ManifoldCache | null): void;
+/** Integrate the accumulated push/turn velocity straight into the transform —
+ *  btSolverBody::writebackVelocity(timeStep). Never touches real momentum. */
+export declare function applySplitImpulsePush(store: RigidBodyStore, dt: number): void;
 export declare class SolverCache {
     readonly F: Float32Array;
     readonly I: Int32Array;
@@ -10,4 +14,6 @@ export declare class SolverCache {
     readonly D: Float64Array;
     constructor(constraints: SixDofSpringConstraint[]);
 }
+/** Store every solved row back into the manifold for the next substep. */
+export declare function saveContactImpulses(store: RigidBodyStore, contacts: ContactPool, manifolds: ManifoldCache): void;
 //# sourceMappingURL=solver.d.ts.map

package/dist/physics/solver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solver.d.ts","sourceRoot":"","sources":["../../src/physics/solver.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAE1D,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,WAAW,CAAA;AAgFrD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,sBAAsB,EAAE,EACrC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,WAAW,EACrB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,GACjB,IAAI,CA2CN;AAyCD,qBAAa,WAAW;IACtB,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAA;IACxB,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAA;IACtB;sEACkE;IAClE,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAA;gBACZ,WAAW,EAAE,sBAAsB,EAAE;CAUlD"}
+{"version":3,"file":"solver.d.ts","sourceRoot":"","sources":["../../src/physics/solver.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAE1D,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAmJ/C,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,sBAAsB,EAAE,EACrC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,WAAW,EACrB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,aAAa,GAAG,IAAW,GACrC,IAAI,CA+FN;AAgDD;8EAC8E;AAC9E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CA8B7E;AAyCD,qBAAa,WAAW;IACtB,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAA;IACxB,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAA;IACtB;sEACkE;IAClE,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAA;gBACZ,WAAW,EAAE,sBAAsB,EAAE;CAUlD;AAs6BD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,WAAW,EACrB,SAAS,EAAE,aAAa,GACvB,IAAI,CAcN"}