reze-engine 0.35.0 → 0.36.1

package/dist/physics/world.d.ts

@@ -29,6 +29,8 @@ export interface WindOptions {
 export declare class World {
     readonly gravity: Vec3;
     solverIterations: number;
+    /** Per-pair contact impulse history behind warm starting. */
+    private manifolds;
     private dampCacheDt;
     private linDampFactor;
     private angDampFactor;

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

@@ -1 +1 @@
-{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/physics/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAC1D,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAA;AAC7D,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAO1D;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,SAAS,EAAE,IAAI,CAAA;IACf,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAA;IAChB;;;kEAG8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;IACtB,gBAAgB,SAAK;IAIrB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,aAAa,CAA4B;IAIjD,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,aAAa,CAAO;IAC5B;gDAC4C;IAC5C,OAAO,CAAC,SAAS,CAAI;gBAET,OAAO,EAAE,IAAI;IAIzB,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI;IAMzB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAoBvC,OAAO,IAAI,WAAW,GAAG,IAAI;IAW7B,IAAI,CACF,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,sBAAsB,EAAE,EACrC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,WAAW,EACrB,EAAE,EAAE,MAAM,GACT,IAAI;CA0KR"}
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/physics/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAC1D,OAAO,EAAgE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAA;AAEzG,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAO1D;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,SAAS,EAAE,IAAI,CAAA;IACf,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAA;IAChB;;;kEAG8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;IACtB,gBAAgB,SAAK;IAErB,6DAA6D;IAC7D,OAAO,CAAC,SAAS,CAAsB;IAIvC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,aAAa,CAA4B;IAIjD,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,aAAa,CAAO;IAC5B;gDAC4C;IAC5C,OAAO,CAAC,SAAS,CAAI;gBAET,OAAO,EAAE,IAAI;IAIzB,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI;IAMzB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAoBvC,OAAO,IAAI,WAAW,GAAG,IAAI;IAW7B,IAAI,CACF,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,sBAAsB,EAAE,EACrC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,WAAW,EACrB,EAAE,EAAE,MAAM,GACT,IAAI;CA4IR"}

package/dist/physics/world.js

@@ -1,10 +1,13 @@
 import { Vec3 } from "../math";
 import { RigidbodyType } from "./types";
-import { solveConstraints } from "./solver";
+import { solveConstraints, saveContactImpulses, applySplitImpulsePush } from "./solver";
+import { ManifoldCache } from "./manifold";
 import { findContacts } from "./contact";
 export class World {
     constructor(gravity) {
         this.solverIterations = 10;
+        /** Per-pair contact impulse history behind warm starting. */
+        this.manifolds = new ManifoldCache();
         // Per-body damping factors pow(1−damping, dt), cached because damping and
         // the fixed dt never change — two Math.pow per body per substep otherwise.
         this.dampCacheDt = -1;
@@ -121,50 +124,20 @@ export class World {
         findContacts(store, contacts);
         // 3. Solve joint + contact constraints (velocity-only).
         if (constraints.length > 0 || contacts.count > 0) {
-            solveConstraints(store, constraints, cache, contacts, dt, this.solverIterations);
+            solveConstraints(store, constraints, cache, contacts, dt, this.solverIterations, this.manifolds);
+            applySplitImpulsePush(store, dt);
+            saveContactImpulses(store, contacts, this.manifolds);
         }
-        // 4. Position correction (split impulse). Direct translation along the
-        //    contact normal — joint constraints in the same SI loop can't undo
-        //    it because it doesn't go through the velocity channel. Inverse-mass
-        //    weighted so a kinematic body stays put and only the dynamic one
-        //    translates.
-        // Softer and later than a rigid-body engine would use, deliberately. MMD
-        // cloth is a dense chain of small bodies resting on the character, and
-        // aggressive penetration recovery feeds those contacts energy that the
-        // joint springs hand straight back — the tips never settle. Measured on a
-        // 688-body model: resting peak velocity 1.79 → 1.10, and 12.9 → 6.6 under
-        // an idle animation, for a slop of two hundredths of a unit (under 2 mm at
-        // MMD scale) that no eye finds.
-        const POS_CORRECTION_FACTOR = 0.15;
-        const POS_SLOP = 0.02;
-        for (let ci = 0; ci < contacts.count; ci++) {
-            const c = contacts.get(ci);
-            if (c.depth <= POS_SLOP)
-                continue;
-            const imA = invMass[c.bodyA];
-            const imB = invMass[c.bodyB];
-            const total = imA + imB;
-            if (total <= 0)
-                continue;
-            const correction = (c.depth - POS_SLOP) * POS_CORRECTION_FACTOR;
-            const dx = correction * c.nx;
-            const dy = correction * c.ny;
-            const dz = correction * c.nz;
-            const ai = c.bodyA * 3;
-            const bi = c.bodyB * 3;
-            if (imA > 0) {
-                const fA = imA / total;
-                pos[ai + 0] -= dx * fA;
-                pos[ai + 1] -= dy * fA;
-                pos[ai + 2] -= dz * fA;
-            }
-            if (imB > 0) {
-                const fB = imB / total;
-                pos[bi + 0] += dx * fB;
-                pos[bi + 1] += dy * fB;
-                pos[bi + 2] += dz * fB;
-            }
+        else {
+            this.manifolds.clear();
         }
+        // 4. Penetration recovery happens in the contact velocity row (Baumgarte,
+        //    CONTACT_ERP), not here. Bullet 2.75 — the build MMD's physics runs —
+        //    defaults m_splitImpulse to false and folds positionalError straight
+        //    into m_rhs, so a separate position-translation pass is a divergence
+        //    from what PMX rigs are authored against. It also could not be made to
+        //    behave: every contact translated the body by its own full share, so a
+        //    panel carrying dozens of rows was shoved out dozens of times.
         // 5. Integrate. Cap angular velocity at π/2 per step — a high-impulse
         //    contact spike on a low-inertia body would otherwise spin past π
         //    in one step and trash the quaternion integration. Linear velocity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -3024,7 +3024,7 @@ export class Engine {
 
   dispose() {
     this.stopRenderLoop()
-    this.forEachInstance((inst) => inst.model.stopAnimation())
+    this.forEachInstance((inst) => inst.model.stop())
     if (Engine.instance === this) Engine.instance = null
     if (this.camera) this.camera.detachControl()
 
@@ -3100,7 +3100,7 @@ export class Engine {
   removeModel(name: string): void {
     const inst = this.modelInstances.get(name)
     if (!inst) return
-    inst.model.stopAnimation()
+    inst.model.stop()
     for (const path of inst.textureCacheKeys) {
       const tex = this.textureCache.get(path)
       if (!tex) continue

package/src/model.ts

@@ -1485,20 +1485,10 @@ export class Model {
     return true
   }
 
-  // @deprecated Use model.play()
-  playAnimation(): void {
-    this.animationState.play()
-  }
-
   pause(): void {
     this.animationState.pause()
   }
 
-  // @deprecated Use model.pause()
-  pauseAnimation(): void {
-    this.animationState.pause()
-  }
-
   stop(): void {
     this.blendEntries = null
     this.crossfade = null
@@ -1506,11 +1496,6 @@ export class Model {
     this.animationState.stop()
   }
 
-  // @deprecated Use model.stop()
-  stopAnimation(): void {
-    this.animationState.stop()
-  }
-
   /** Deactivate the current clip entirely (stop + forget). Unlike stop(), the
    *  pose is no longer re-applied each frame afterwards — follow with
    *  resetAllBones()/resetAllMorphs() to return to the bind pose. */
@@ -1528,11 +1513,6 @@ export class Model {
     this.animationState.seek(seconds)
   }
 
-  // @deprecated Use model.seek()
-  seekAnimation(seconds: number): void {
-    this.animationState.seek(seconds)
-  }
-
   getAnimationProgress(): AnimationProgress {
     const p = this.animationState.getProgress()
     return {

package/src/physics/contact.ts

@@ -51,11 +51,18 @@ export interface Contact {
   cBxN: number; cByN: number; cBzN: number   // rB × n
   jacInvN: number
   bounceVel: number   // restitution reference, captured at setup from initial relVelN
-  /** Per-contact relaxation gain, 1/max(rows on A, rows on B). See CONTACT_SOR_MIN. */
-  sorGain: number
-  // Approach speed this row is allowed to leave alone: gap / dt for a
-  // speculative row, 0 once the shapes actually touch. See setupContactRow.
-  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
   // Friction tangent 1:
   t1x: number; t1y: number; t1z: number
   cAxT1: number; cAyT1: number; cAzT1: number
@@ -84,8 +91,10 @@ function makeContact(): Contact {
     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,
@@ -108,6 +117,7 @@ export class ContactPool {
       c.appliedNormalImpulse = 0
       c.appliedFrictionImpulse1 = 0
       c.appliedFrictionImpulse2 = 0
+      c.appliedPushImpulse = 0
       this.count++
       return c
     }

package/src/physics/manifold.ts

@@ -0,0 +1,151 @@
+// Persistent contact manifolds — the cache that makes warm starting possible.
+//
+// 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.
+//
+// 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
+
+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 class ManifoldCache {
+  private pairs = new Map<number, Point[]>()
+  private touched = new Set<number>()
+
+  private static key(a: number, b: number): number {
+    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: number, b: number, lax: number, lay: number, laz: number): Point | null {
+    const list = this.pairs.get(ManifoldCache.key(a, b))
+    if (list === undefined) return null
+    let best: Point | null = 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: number, b: number,
+    lax: number, lay: number, laz: number,
+    lbx: number, lby: number, lbz: number,
+    normalImpulse: number, frictionImpulse1: number, frictionImpulse2: number,
+    age: number,
+  ): void {
+    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
+  }
+
+  /** 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 {
+    for (const [k, list] of this.pairs) {
+      if (!this.touched.has(k)) { this.pairs.delete(k); continue }
+      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(): void {
+    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: Point[], nx: number, ny: number, nz: number): number {
+  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: number[][] = [[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 }
+  }
+  return bestIdx
+}