reze-engine 0.36.0 → 0.37.0

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"}