reze-engine 0.34.0 → 0.36.0

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

@@ -0,0 +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"}

package/dist/physics/manifold.js

@@ -0,0 +1,68 @@
+// Contact impulse history — 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.
+//
+// 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 {
+    constructor() {
+        this.a = new Map();
+        this.b = new Map();
+    }
+    /** 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];
+        }
+    }
+    /** 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)
+                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;
+        }
+        const t = this.a;
+        this.a = this.b;
+        this.b = t;
+    }
+}

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;AAuDrD,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,CA4BN;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;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"}

package/dist/physics/solver.js

@@ -13,6 +13,29 @@
 import { Mat4 } from "../math";
 import { STOP_ERP } from "./constraint";
 const BOUNCE_THRESHOLD = 2.0;
+// Successive over-relaxation factor on CONTACT rows only (joints untouched).
+// Each contact row independently drives the relative velocity at its own point
+// to zero; when a dress panel carries up to 43 of them at once, they all
+// correct the same motion and the body is over-braked, differently every
+// substep. Scaling each row's step damps that without changing the fixed
+// point — the accumulated impulse still converges to the same answer, just
+// approached rather than overshot.
+//
+// The gain is PER CONTACT, scaled by how contended its two bodies are, not a
+// flat constant. A flat factor was measured first and is wrong: it also slows
+// the well-conditioned rows, and a body resting on a SINGLE contact can then
+// no longer cancel its approach velocity within the iteration budget, so it
+// creeps forever instead of settling (托特 peak speed at 15 s: 0.11 at gain
+// 1.0, 0.46 at 0.5, 0.72 at 0.3 — a permanent limit cycle on a one-contact
+// body). Over-constraint is a local property, so the remedy has to be local.
+//
+// gain = 1 / max(rows on A, rows on B), floored. One contact → 1.0, exact and
+// settling preserved; a dress panel sharing 20 rows → 0.05, damped. This is
+// the standard mass-splitting blend toward Jacobi in the contended cluster.
+const CONTACT_SOR_MIN = 0.12;
+// Per-body contact-row counts for the gain above; grown on demand, refilled
+// each substep. Module-level so the solve allocates nothing.
+let _rowCount = new Int32Array(0);
 // Ceilings on limit-correction velocity. In normal operation limit errors are
 // tiny; a large error only appears after a discontinuity (teleport, stall,
 // deep penetration), and feeding err·ERP/dt to the solver unclamped then
@@ -74,8 +97,27 @@ export function solveConstraints(store, constraints, cache, contacts, dt, iterat
     for (let c = 0; c < constraints.length; c++) {
         setupConstraint(constraints[c], c, cache, store, dt, invDt);
     }
+    // How many contact rows each body carries this substep — the per-contact
+    // relaxation gain below is a function of the more contended of its two
+    // bodies. Counting is O(contacts), done once, before any setup.
+    if (_rowCount.length < store.count)
+        _rowCount = new Int32Array(store.count);
+    else
+        _rowCount.fill(0, 0, store.count);
+    // Only DYNAMIC bodies are counted. A static body — above all the ground —
+    // collects a row from every body resting on it, and letting that inflate the
+    // count crushes the gain of each of those contacts to the floor, so nothing
+    // resting on the ground can build enough impulse and it creeps instead of
+    // settling. A body with invMass 0 cannot be over-braked in the first place.
+    for (let ci = 0; ci < contacts.count; ci++) {
+        const c = contacts.get(ci);
+        if (invMass[c.bodyA] > 0)
+            _rowCount[c.bodyA]++;
+        if (invMass[c.bodyB] > 0)
+            _rowCount[c.bodyB]++;
+    }
     for (let ci = 0; ci < contacts.count; ci++) {
-        setupContactRow(contacts.get(ci), lv, av, invMass, W);
+        setupContactRow(contacts.get(ci), lv, av, invMass, W, invDt);
     }
     for (let iter = 0; iter < iterations; iter++) {
         for (let c = 0; c < constraints.length; c++) {
@@ -692,7 +734,7 @@ function iterateConstraint(ci, cache, lv, av, invMass) {
 // SETUP: pre-compute Jacobians, friction basis, and the bounce reference
 // from the *initial* closing velocity (Bullet's pattern — captures restitution
 // before iter 1 zeroes out the approach).
-function setupContactRow(c, lv, av, invMass, W) {
+function setupContactRow(c, lv, av, invMass, W, invDt) {
     const ai = c.bodyA * 3;
     const bi = c.bodyB * 3;
     const a9 = c.bodyA * 9;
@@ -736,6 +778,24 @@ function setupContactRow(c, lv, av, invMass, W) {
     c.bounceVel = c.restitution > 0 && relVelN0 < -BOUNCE_THRESHOLD
         ? -c.restitution * relVelN0
         : 0;
+    // Speculative rows (depth < 0 — the shapes are inside the margin band but
+    // NOT touching) must not brake a body that hasn't arrived yet. Their whole
+    // job is to stop it crossing the surface within this substep, so the
+    // approach speed they leave alone is exactly the one that closes the
+    // remaining gap in dt; only the excess above that is cancelled.
+    //
+    // Without this the row targets relVelN = 0 like a touching contact and
+    // stops approaching bodies dead up to CONTACT_MARGIN away from anything.
+    // The push-only clamp does NOT prevent that — it only forbids a negative
+    // (pulling) impulse, not a large positive one on a body in mid-air. On a
+    // dress rig half of all contact rows are speculative and 88% of them fire,
+    // which is the field of invisible brakes the cloth was shaking against.
+    c.allowedApproachVel = c.depth < 0 ? -c.depth * invDt : 0;
+    // Relaxation gain, from the more contended of the two bodies (see
+    // CONTACT_SOR_MIN). A lone contact keeps gain 1.0 and stays exact.
+    const contended = _rowCount[c.bodyA] > _rowCount[c.bodyB] ? _rowCount[c.bodyA] : _rowCount[c.bodyB];
+    const gain = contended > 1 ? 1 / contended : 1;
+    c.sorGain = gain < CONTACT_SOR_MIN ? CONTACT_SOR_MIN : gain;
     // Friction tangent basis. Pick the axis least aligned with n.
     let t1x, t1y, t1z;
     if (Math.abs(nx) < 0.7071) {
@@ -840,7 +900,7 @@ function iterateContactRow(c, lv, av, invMass) {
     if (jacInvN > 0) {
         const nx = c.nx, ny = c.ny, nz = c.nz;
         const relVelN = dvx * nx + dvy * ny + dvz * nz;
-        let dImpN = (c.bounceVel - relVelN) * jacInvN;
+        let dImpN = (c.bounceVel - c.allowedApproachVel - relVelN) * jacInvN * c.sorGain;
         const oldN = c.appliedNormalImpulse;
         let newN = oldN + dImpN;
         if (newN < 0) {
@@ -890,7 +950,7 @@ function applyFrictionTangent(c, ai, bi, dvx, dvy, dvz, tx, ty, tz, cAx, cAy, cA
     if (jacInv <= 0)
         return;
     const relVel = dvx * tx + dvy * ty + dvz * tz;
-    let dImp = -relVel * jacInv;
+    let dImp = -relVel * jacInv * c.sorGain;
     const old = slot === 1 ? c.appliedFrictionImpulse1 : c.appliedFrictionImpulse2;
     let next = old + dImp;
     if (next < -muNormal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "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 {