reze-engine 0.36.0 → 0.37.0

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/dist/pmx-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pmx-loader.d.ts","sourceRoot":"","sources":["../src/pmx-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EAWN,MAAM,SAAS,CAAA;AAGhB,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEzE,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,kBAAkB,CAAI;IAC9B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAY;IAC/B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAe;IAE/B,OAAO;IAQP,OAAO,CAAC,IAAI;WAMC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAI9C,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK;WAIpC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAKxF,OAAO,CAAC,KAAK;IAiBb,OAAO,CAAC,WAAW;IAwDnB,OAAO,CAAC,aAAa;IA+FrB,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,cAAc;IAqEtB,OAAO,CAAC,UAAU;IAsKlB,OAAO,CAAC,WAAW;IA2JnB,OAAO,CAAC,iBAAiB;IAgDzB,OAAO,CAAC,gBAAgB;IA+FxB,OAAO,CAAC,WAAW;IAmGnB,OAAO,CAAC,kBAAkB;IAmC1B,OAAO,CAAC,OAAO;IAkJf,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,OAAO;IAwBf,OAAO,CAAC,QAAQ;CAIjB"}
+{"version":3,"file":"pmx-loader.d.ts","sourceRoot":"","sources":["../src/pmx-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EAcN,MAAM,SAAS,CAAA;AAGhB,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEzE,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,kBAAkB,CAAI;IAC9B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAY;IAC/B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAe;IAE/B,OAAO;IAQP,OAAO,CAAC,IAAI;WAMC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAI9C,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK;WAIpC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAKxF,OAAO,CAAC,KAAK;IAiBb,OAAO,CAAC,WAAW;IAwDnB,OAAO,CAAC,aAAa;IA+FrB,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,cAAc;IAqEtB,OAAO,CAAC,UAAU;IAsKlB,OAAO,CAAC,WAAW;IAgMnB,OAAO,CAAC,iBAAiB;IAgDzB,OAAO,CAAC,gBAAgB;IA+FxB,OAAO,CAAC,WAAW;IAmGnB,OAAO,CAAC,kBAAkB;IAmC1B,OAAO,CAAC,OAAO;IAkJf,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,OAAO;IAwBf,OAAO,CAAC,QAAQ;CAIjB"}

package/dist/pmx-loader.js

@@ -457,6 +457,14 @@ export class PmxLoader {
                         vertexOffsets: [],
                         groupReferences: [],
                     };
+                    // Allocated only for the type that uses them, so `morph.boneOffsets`
+                    // being undefined means "not that kind of morph" rather than "empty".
+                    if (morphType === 2)
+                        morph.boneOffsets = [];
+                    else if (morphType >= 3 && morphType <= 7)
+                        morph.uvOffsets = [];
+                    else if (morphType === 8)
+                        morph.materialOffsets = [];
                     // Parse vertex morphs (type 1)
                     if (morphType === 1) {
                         for (let j = 0; j < offsetCount; j++) {
@@ -492,62 +500,94 @@ export class PmxLoader {
                         }
                     }
                     else {
-                        // Skip other morph types for now
+                        // Bone, UV and material morphs are kept; flip and impulse (PMX 2.1)
+                        // are still read past — nothing in the wild uses them, and impulse
+                        // would need to drive rigidbodies.
                         for (let j = 0; j < offsetCount; j++) {
                             if (this.offset >= this.view.buffer.byteLength) {
                                 break;
                             }
                             if (morphType === 2) {
                                 // Bone morph
-                                this.getNonVertexIndex(this.boneIndexSize); // boneIndex
-                                this.getFloat32(); // x
-                                this.getFloat32(); // y
-                                this.getFloat32(); // z
-                                this.getFloat32(); // rotation quaternion x
-                                this.getFloat32(); // rotation quaternion y
-                                this.getFloat32(); // rotation quaternion z
-                                this.getFloat32(); // rotation quaternion w
+                                const boneIndex = this.getNonVertexIndex(this.boneIndexSize);
+                                const tx = this.getFloat32();
+                                const ty = this.getFloat32();
+                                const tz = this.getFloat32();
+                                const rx = this.getFloat32();
+                                const ry = this.getFloat32();
+                                const rz = this.getFloat32();
+                                const rw = this.getFloat32();
+                                if (boneIndex >= 0) {
+                                    const offset = {
+                                        boneIndex,
+                                        translation: [tx, ty, tz],
+                                        rotation: [rx, ry, rz, rw],
+                                    };
+                                    morph.boneOffsets.push(offset);
+                                }
                             }
                             else if (morphType >= 3 && morphType <= 7) {
                                 // UV morph + additional UV channels 1-4; offset is always a Float4 per spec
-                                this.getIndex(this.vertexIndexSize); // vertexIndex
-                                this.getFloat32(); // x
-                                this.getFloat32(); // y
-                                this.getFloat32(); // z
-                                this.getFloat32(); // w
+                                const vertexIndex = this.getIndex(this.vertexIndexSize);
+                                const x = this.getFloat32();
+                                const y = this.getFloat32();
+                                const z = this.getFloat32();
+                                const w = this.getFloat32();
+                                if (vertexIndex >= 0 && vertexIndex < this.vertexCount) {
+                                    const offset = { vertexIndex, offset: [x, y, z, w] };
+                                    morph.uvOffsets.push(offset);
+                                }
                             }
                             else if (morphType === 8) {
                                 // Material morph
-                                this.getNonVertexIndex(this.materialIndexSize); // materialIndex
-                                this.getUint8(); // offsetType
-                                this.getFloat32(); // diffuse r
-                                this.getFloat32(); // diffuse g
-                                this.getFloat32(); // diffuse b
-                                this.getFloat32(); // diffuse a
-                                this.getFloat32(); // specular r
-                                this.getFloat32(); // specular g
-                                this.getFloat32(); // specular b
-                                this.getFloat32(); // specular power
-                                this.getFloat32(); // ambient r
-                                this.getFloat32(); // ambient g
-                                this.getFloat32(); // ambient b
-                                this.getFloat32(); // edgeColor r
-                                this.getFloat32(); // edgeColor g
-                                this.getFloat32(); // edgeColor b
-                                this.getFloat32(); // edgeColor a
-                                this.getFloat32(); // edgeSize
-                                this.getFloat32(); // textureCoeff r
-                                this.getFloat32(); // textureCoeff g
-                                this.getFloat32(); // textureCoeff b
-                                this.getFloat32(); // textureCoeff a
-                                this.getFloat32(); // sphereCoeff r
-                                this.getFloat32(); // sphereCoeff g
-                                this.getFloat32(); // sphereCoeff b
-                                this.getFloat32(); // sphereCoeff a
-                                this.getFloat32(); // toonCoeff r
-                                this.getFloat32(); // toonCoeff g
-                                this.getFloat32(); // toonCoeff b
-                                this.getFloat32(); // toonCoeff a
+                                const materialIndex = this.getNonVertexIndex(this.materialIndexSize);
+                                const offsetType = this.getUint8();
+                                const diffuseR = this.getFloat32();
+                                const diffuseG = this.getFloat32();
+                                const diffuseB = this.getFloat32();
+                                const diffuseA = this.getFloat32();
+                                const specularR = this.getFloat32();
+                                const specularG = this.getFloat32();
+                                const specularB = this.getFloat32();
+                                const shininess = this.getFloat32();
+                                const ambientR = this.getFloat32();
+                                const ambientG = this.getFloat32();
+                                const ambientB = this.getFloat32();
+                                const edgeR = this.getFloat32();
+                                const edgeG = this.getFloat32();
+                                const edgeB = this.getFloat32();
+                                const edgeA = this.getFloat32();
+                                const edgeSize = this.getFloat32();
+                                const texR = this.getFloat32();
+                                const texG = this.getFloat32();
+                                const texB = this.getFloat32();
+                                const texA = this.getFloat32();
+                                const sphR = this.getFloat32();
+                                const sphG = this.getFloat32();
+                                const sphB = this.getFloat32();
+                                const sphA = this.getFloat32();
+                                const toonR = this.getFloat32();
+                                const toonG = this.getFloat32();
+                                const toonB = this.getFloat32();
+                                const toonA = this.getFloat32();
+                                // -1 is legal and means "every material" — kept as-is so the
+                                // applier can fan it out without a second convention.
+                                if (materialIndex >= -1) {
+                                    const offset = {
+                                        materialIndex,
+                                        offsetType,
+                                        diffuse: [diffuseR, diffuseG, diffuseB, diffuseA],
+                                        specular: [specularR, specularG, specularB],
+                                        shininess,
+                                        ambient: [ambientR, ambientG, ambientB],
+                                        edgeColor: [edgeR, edgeG, edgeB, edgeA],
+                                        edgeSize,
+                                        textureCoeff: [texR, texG, texB, texA],
+                                        sphereCoeff: [sphR, sphG, sphB, sphA],
+                                        toonCoeff: [toonR, toonG, toonB, toonA],
+                                    };
+                                    morph.materialOffsets.push(offset);
+                                }
                             }
                             else if (morphType === 9) {
                                 // Flip morph (PMX 2.1): same layout as group morph

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.36.0",
+  "version": "0.37.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/camera.ts

@@ -4,6 +4,11 @@ import type { CameraPose } from "./camera-animation"
 /** Far cap / zoom limit; large enough for wide shots without clipping distant ground */
 const FAR_CAP = 8000
 const FAR_MIN = 200
+/** The character-framing value the cloth z-fighting fix settled on — never go below it. */
+const NEAR_MIN = 0.5
+/** ~40cm in MMD units. Past this the near plane would start clipping geometry a
+ *  user has deliberately pushed the camera up against. */
+const NEAR_MAX = 5
 
 export class Camera {
   alpha: number
@@ -226,8 +231,29 @@ export class Camera {
     this.far = Math.min(FAR_CAP, Math.max(FAR_MIN, this.radius * 12 + margin))
   }
 
+  /**
+   * Near plane scales with how far out you are framing.
+   *
+   * A 24-bit non-reversed depth buffer spends most of its precision just past
+   * the near plane, so what survives at distance is governed by the far/near
+   * ratio. 0.5 was chosen for character framing and fixed coplanar cloth there
+   * (see `near` above) — but a stage puts the floor 5–20× further out, where the
+   * same ratio leaves neighbouring surfaces sharing a depth value. They then win
+   * and lose per pixel as the camera turns, which reads as flickering bands and
+   * cracks across the floor.
+   *
+   * Tying near to the framing keeps character shots byte-identical (radius ~26
+   * still lands on the 0.5 floor) and buys back an order of magnitude once you
+   * pull out to see a whole stage. Capped so it can never clip something the
+   * user is deliberately close to.
+   */
+  private updateNearFromRadius(): void {
+    this.near = Math.min(NEAR_MAX, Math.max(NEAR_MIN, this.radius / 50))
+  }
+
   getProjectionMatrix(): Mat4 {
     this.updateFarFromRadius()
+    this.updateNearFromRadius()
     Mat4.perspectiveInto(this._projMat.values, this.fov, this.aspect, this.near, this.far)
     return this._projMat
   }