reze-engine 0.33.2 → 0.35.0

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/dist/physics/world.d.ts

@@ -3,14 +3,47 @@ import type { RigidBodyStore } from "./body";
 import type { SixDofSpringConstraint } from "./constraint";
 import { type SolverCache } from "./solver";
 import { type ContactPool } from "./contact";
+/**
+ * Air movement across the whole world.
+ *
+ * Applied as an acceleration alongside gravity, which is the same shape MMD's
+ * own wind plugins take and keeps it free: gravity and wind are summed once per
+ * substep, so the per-body predict loop is untouched. Terminal velocity comes
+ * out of the existing per-body damping rather than a drag model — PMX authors
+ * already tune that damping to get the hang they want, and a second, hidden
+ * drag term would fight it.
+ */
+export interface WindOptions {
+    /** Direction the air travels. Normalised on assignment; a zero vector is off. */
+    direction: Vec3;
+    /** Acceleration along it, in gravity's units — the built-in gravity is 98. */
+    strength: number;
+    /** Gust depth, clamped to 0–1. 0 is a steady breeze; 1 swings between still
+     *  and double. It is a clamp rather than a free scalar because past 1 the
+     *  swing goes negative and the wind blows backwards on every other beat,
+     *  which is never what a caller meant by "more turbulent". */
+    turbulence?: number;
+    /** Gusts per second. */
+    frequency?: number;
+}
 export declare class World {
     readonly gravity: Vec3;
     solverIterations: number;
     private dampCacheDt;
     private linDampFactor;
     private angDampFactor;
+    private windX;
+    private windY;
+    private windZ;
+    private windTurbulence;
+    private windFrequency;
+    /** Advances with simulated time, not wall time, so a scrubbed or exported
+     *  take gusts identically to a live one. */
+    private windClock;
     constructor(gravity: Vec3);
     setGravity(g: Vec3): void;
+    setWind(wind: WindOptions | null): void;
+    getWind(): WindOptions | null;
     step(store: RigidBodyStore, constraints: SixDofSpringConstraint[], cache: SolverCache, contacts: ContactPool, dt: number): void;
 }
 //# sourceMappingURL=world.d.ts.map

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,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;gBAErC,OAAO,EAAE,IAAI;IAIzB,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI;IAMzB,IAAI,CACF,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,sBAAsB,EAAE,EACrC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,WAAW,EACrB,EAAE,EAAE,MAAM,GACT,IAAI;CA2JR"}
+{"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"}

package/dist/physics/world.js

@@ -2,11 +2,6 @@ import { Vec3 } from "../math";
 import { RigidbodyType } from "./types";
 import { solveConstraints } from "./solver";
 import { findContacts } from "./contact";
-// World step: predict velocities → collide → solve → position correction →
-// integrate. Static and kinematic bodies are skipped during predict and
-// integrate; the parent class syncs them from bones around the step. The
-// solver pass runs on all bodies — kinematic ones have invMass = 0 and
-// act as anchors.
 export class World {
     constructor(gravity) {
         this.solverIterations = 10;
@@ -15,6 +10,16 @@ export class World {
         this.dampCacheDt = -1;
         this.linDampFactor = null;
         this.angDampFactor = null;
+        // Wind, resolved to a direction × strength at construction of the options so
+        // the step loop only multiplies by a gust scalar.
+        this.windX = 0;
+        this.windY = 0;
+        this.windZ = 0;
+        this.windTurbulence = 0;
+        this.windFrequency = 0.35;
+        /** Advances with simulated time, not wall time, so a scrubbed or exported
+         *  take gusts identically to a live one. */
+        this.windClock = 0;
         this.gravity = new Vec3(gravity.x, gravity.y, gravity.z);
     }
     setGravity(g) {
@@ -22,6 +27,35 @@ export class World {
         this.gravity.y = g.y;
         this.gravity.z = g.z;
     }
+    setWind(wind) {
+        // Shape first, and unconditionally: bailing out early on a zero strength
+        // used to leave turbulence and frequency holding whatever a previous call
+        // set, so raising the strength again resurrected settings the caller had
+        // since replaced.
+        this.windTurbulence = Math.min(1, Math.max(0, wind?.turbulence ?? 0));
+        this.windFrequency = Math.max(0, wind?.frequency ?? 0.35);
+        const d = wind?.direction;
+        const len = d ? Math.hypot(d.x, d.y, d.z) : 0;
+        if (!wind || !d || len < 1e-9 || wind.strength === 0) {
+            this.windX = this.windY = this.windZ = 0;
+            return;
+        }
+        const s = wind.strength / len;
+        this.windX = d.x * s;
+        this.windY = d.y * s;
+        this.windZ = d.z * s;
+    }
+    getWind() {
+        const strength = Math.hypot(this.windX, this.windY, this.windZ);
+        if (strength === 0)
+            return null;
+        return {
+            direction: new Vec3(this.windX / strength, this.windY / strength, this.windZ / strength),
+            strength,
+            turbulence: this.windTurbulence,
+            frequency: this.windFrequency,
+        };
+    }
     step(store, constraints, cache, contacts, dt) {
         if (dt <= 0)
             return;
@@ -34,9 +68,24 @@ export class World {
         const ldamp = store.linearDamping;
         const adamp = store.angularDamping;
         const invMass = store.invMass;
-        const gx = this.gravity.x;
-        const gy = this.gravity.y;
-        const gz = this.gravity.z;
+        // Gravity and wind are the same kind of term, so they are summed here and
+        // the predict loop below never learns wind exists.
+        let gx = this.gravity.x;
+        let gy = this.gravity.y;
+        let gz = this.gravity.z;
+        if (this.windX !== 0 || this.windY !== 0 || this.windZ !== 0) {
+            this.windClock += dt;
+            let gust = 1;
+            if (this.windTurbulence > 0 && this.windFrequency > 0) {
+                // Two incommensurate sines: a single one is a metronome, and real gusts
+                // do not repeat on a bar line. Stays within 1 ± turbulence.
+                const t = this.windClock * this.windFrequency * Math.PI * 2;
+                gust = 1 + this.windTurbulence * 0.5 * (Math.sin(t) + Math.sin(t * 0.37 + 1.3));
+            }
+            gx += this.windX * gust;
+            gy += this.windY * gust;
+            gz += this.windZ * gust;
+        }
         // 1. Predict — gravity + damping. The pow form (vs the linear
         //    1−damping·dt approximation) stays stable at high PMX damping
         //    values like 0.99. Factors are cached (damping and dt are constant).

package/package.json

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

@@ -7,6 +7,7 @@ import { VMDLoader } from "./vmd-loader"
 import { CameraAnimation } from "./camera-animation"
 import { PmxLoader } from "./pmx-loader"
 import { RezePhysics } from "./physics"
+import type { WindOptions } from "./physics/world"
 import {
   createFetchAssetReader,
   createFileMapAssetReader,
@@ -799,6 +800,10 @@ export class Engine {
   // IK and physics enabled at engine level (same for all models)
   private ikEnabled = true
   private physicsEnabled = true
+  // World-wide, not per-model: MMD treats gravity and wind as properties of the
+  // scene, and a model loaded later must arrive into the same air as the rest.
+  private gravity = new Vec3(0, -98, 0)
+  private wind: WindOptions | null = null
   // GPU vertex-morph path. Set false BEFORE loadModel to fall back to the CPU path (A/B).
   private useGpuMorphs = true
 
@@ -3249,6 +3254,39 @@ export class Engine {
     return this.physicsEnabled
   }
 
+  /**
+   * Scene gravity, applied to every model's cloth and hair. The default is
+   * (0, -98, 0) — MMD's own scale, where a character stands about 20 units
+   * tall. Lower magnitudes float; tilting it sideways hangs everything on a
+   * slant, which is the cheap way to fake a strong draught.
+   */
+  setGravity(gravity: Vec3): void {
+    this.gravity = new Vec3(gravity.x, gravity.y, gravity.z)
+    this.forEachInstance((inst) => inst.physics?.setGravity(this.gravity))
+  }
+
+  getGravity(): Vec3 {
+    return new Vec3(this.gravity.x, this.gravity.y, this.gravity.z)
+  }
+
+  /**
+   * Air movement across the scene — null is still air.
+   *
+   * Applied as an acceleration alongside gravity, so `strength` is in the same
+   * units: against the default gravity of 98, a strength of 10-30 reads as a
+   * breeze through hair and a skirt without lifting them off the body. Gusting
+   * is driven by simulated time rather than wall time, so an exported take
+   * gusts exactly as the preview did.
+   */
+  setWind(wind: WindOptions | null): void {
+    this.wind = wind ? { ...wind, direction: new Vec3(wind.direction.x, wind.direction.y, wind.direction.z) } : null
+    this.forEachInstance((inst) => inst.physics?.setWind(this.wind))
+  }
+
+  getWind(): WindOptions | null {
+    return this.wind ? { ...this.wind, direction: new Vec3(this.wind.direction.x, this.wind.direction.y, this.wind.direction.z) } : null
+  }
+
   resetPhysics(): void {
     this.forEachInstance((inst) => {
       if (!inst.physics) return
@@ -3421,6 +3459,12 @@ export class Engine {
 
     const rbs = model.getRigidbodies()
     const physics = rbs.length > 0 ? new RezePhysics(rbs, model.getJoints()) : null
+    // Adopt the scene's air, or a model added mid-session would fall under
+    // different gravity from the ones already on stage.
+    if (physics) {
+      physics.setGravity(this.gravity)
+      if (this.wind) physics.setWind(this.wind)
+    }
 
     const shadowBindGroup = this.device.createBindGroup({
       label: `${name}: shadow bind`,

package/src/index.ts

@@ -86,4 +86,5 @@ export { VMDLoader, type CameraKeyframe, type IkFrame } from "./vmd-loader"
 export { VMDWriter } from "./vmd-writer"
 export { PmxLoader } from "./pmx-loader"
 export { CameraAnimation, type CameraPose } from "./camera-animation"
-export { RezePhysics } from "./physics"
+export { RezePhysics } from "./physics"
+export type { WindOptions } from "./physics/world"