reze-engine 0.31.2 → 0.32.0

package/dist/physics/worker-physics.d.ts

@@ -0,0 +1,28 @@
+import type { Rigidbody, Joint } from "./types";
+import type { Mat4 } from "../math";
+export declare class WorkerPhysics {
+    private readonly worker;
+    private dynamicBones;
+    private readonly boneCount;
+    /** Transfer buffer when idle; null while a step is in flight. */
+    private buf;
+    /** Latest completed pose from the worker (copied out of the transfer buffer). */
+    private readonly result;
+    private hasResult;
+    private pendingDt;
+    private queuedReset;
+    /** Worker-side cost of the last completed step — for engine stats. */
+    stepMs: number;
+    private constructor();
+    static supported(): boolean;
+    static create(rigidbodies: Rigidbody[], joints: Joint[], inverseBind: Float32Array): Promise<WorkerPhysics>;
+    /** Same signature as RezePhysics.step — the engine cannot tell them apart.
+     *  (inverseBind was shipped to the worker at init; the param is unused.) */
+    step(dt: number, boneWorldMatrices: Mat4[], _inverseBind: Float32Array): void;
+    /** Reset rides the same pipeline: the next posted frame carries a reset
+     *  command instead of a step, and stale results stop applying immediately. */
+    reset(boneWorldMatrices: Mat4[]): void;
+    dispose(): void;
+    private onStepped;
+}
+//# sourceMappingURL=worker-physics.d.ts.map

package/dist/physics/worker-physics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-physics.d.ts","sourceRoot":"","sources":["../../src/physics/worker-physics.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAYnC,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,iEAAiE;IACjE,OAAO,CAAC,GAAG,CAAoB;IAC/B,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,WAAW,CAAQ;IAC3B,sEAAsE;IACtE,MAAM,SAAI;IAEV,OAAO;IAOP,MAAM,CAAC,SAAS,IAAI,OAAO;IAI3B,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IA6B3G;gFAC4E;IAC5E,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI;IAuB7E;kFAC8E;IAC9E,KAAK,CAAC,iBAAiB,EAAE,IAAI,EAAE,GAAG,IAAI;IAOtC,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,SAAS;CAQlB"}

package/dist/physics/worker-physics.js

@@ -0,0 +1,91 @@
+export class WorkerPhysics {
+    constructor(worker, boneCount) {
+        this.dynamicBones = [];
+        this.hasResult = false;
+        this.pendingDt = 0;
+        this.queuedReset = false;
+        /** Worker-side cost of the last completed step — for engine stats. */
+        this.stepMs = 0;
+        this.worker = worker;
+        this.boneCount = boneCount;
+        this.buf = new ArrayBuffer(boneCount * 64);
+        this.result = new Float32Array(boneCount * 16);
+    }
+    static supported() {
+        return typeof Worker !== "undefined";
+    }
+    static create(rigidbodies, joints, inverseBind) {
+        return new Promise((resolve, reject) => {
+            let worker;
+            try {
+                worker = new Worker(new URL("./physics.worker.js", import.meta.url), { type: "module" });
+            }
+            catch (e) {
+                reject(e instanceof Error ? e : new Error(String(e)));
+                return;
+            }
+            const wp = new WorkerPhysics(worker, inverseBind.length / 16);
+            const fail = (message) => {
+                worker.terminate();
+                reject(new Error(message));
+            };
+            worker.onerror = (e) => fail(`physics worker failed to boot: ${e.message || "worker error"}`);
+            worker.onmessage = (ev) => {
+                if (ev.data?.cmd !== "ready")
+                    return;
+                wp.dynamicBones = ev.data.dynamicBones;
+                worker.onmessage = (m) => wp.onStepped(m);
+                worker.onerror = null;
+                resolve(wp);
+            };
+            // Rigidbody/Joint carry only data (Vec3/Mat4 fields clone as plain
+            // objects with the same fields — the physics constructor reads fields,
+            // never methods), so structuredClone is a faithful serializer.
+            worker.postMessage({ cmd: "init", rigidbodies, joints, inverseBind: inverseBind.slice() });
+        });
+    }
+    /** Same signature as RezePhysics.step — the engine cannot tell them apart.
+     *  (inverseBind was shipped to the worker at init; the param is unused.) */
+    step(dt, boneWorldMatrices, _inverseBind) {
+        this.pendingDt += dt;
+        // Apply the newest completed simulation onto this frame's pose. Dynamic
+        // bones only: kinematic bones must keep the LIVE animation pose.
+        if (this.hasResult) {
+            const r = this.result;
+            for (const bi of this.dynamicBones) {
+                boneWorldMatrices[bi].values.set(r.subarray(bi * 16, bi * 16 + 16));
+            }
+        }
+        if (this.buf === null)
+            return; // worker mid-step: dt accumulated for the next post
+        const flat = new Float32Array(this.buf);
+        const n = Math.min(this.boneCount, boneWorldMatrices.length);
+        for (let i = 0; i < n; i++)
+            flat.set(boneWorldMatrices[i].values, i * 16);
+        this.worker.postMessage({ cmd: this.queuedReset ? "reset" : "step", dt: this.pendingDt, bones: this.buf }, [this.buf]);
+        this.buf = null;
+        this.pendingDt = 0;
+        this.queuedReset = false;
+    }
+    /** Reset rides the same pipeline: the next posted frame carries a reset
+     *  command instead of a step, and stale results stop applying immediately. */
+    reset(boneWorldMatrices) {
+        this.queuedReset = true;
+        this.hasResult = false;
+        // Post right away if idle — reuse step's snapshot/post path with dt 0.
+        if (this.buf !== null)
+            this.step(0, boneWorldMatrices, undefined);
+    }
+    dispose() {
+        this.worker.terminate();
+    }
+    onStepped(ev) {
+        const d = ev.data;
+        if (d?.cmd !== "stepped")
+            return;
+        this.buf = d.bones;
+        this.stepMs = d.stepMs;
+        this.result.set(new Float32Array(this.buf));
+        this.hasResult = true;
+    }
+}

package/dist/physics/world.d.ts

@@ -1,6 +1,7 @@
 import { Vec3 } from "../math";
 import type { RigidBodyStore } from "./body";
 import type { SixDofSpringConstraint } from "./constraint";
+import { type SolverCache } from "./solver";
 import { type ContactPool } from "./contact";
 export declare class World {
     readonly gravity: Vec3;
@@ -10,6 +11,6 @@ export declare class World {
     private angDampFactor;
     constructor(gravity: Vec3);
     setGravity(g: Vec3): void;
-    step(store: RigidBodyStore, constraints: SixDofSpringConstraint[], contacts: ContactPool, dt: number): void;
+    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;AAE1D,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,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,sBAAsB,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;CAoJ5G"}
+{"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;CAoJR"}

package/dist/physics/world.js

@@ -22,7 +22,7 @@ export class World {
         this.gravity.y = g.y;
         this.gravity.z = g.z;
     }
-    step(store, constraints, contacts, dt) {
+    step(store, constraints, cache, contacts, dt) {
         if (dt <= 0)
             return;
         const N = store.count;
@@ -72,7 +72,7 @@ export class World {
         findContacts(store, contacts);
         // 3. Solve joint + contact constraints (velocity-only).
         if (constraints.length > 0 || contacts.count > 0) {
-            solveConstraints(store, constraints, contacts, dt, this.solverIterations);
+            solveConstraints(store, constraints, cache, contacts, dt, this.solverIterations);
         }
         // 4. Position correction (split impulse). Direct translation along the
         //    contact normal — joint constraints in the same SI loop can't undo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.31.2",
+  "version": "0.32.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 { WorkerPhysics } from "./physics/worker-physics"
 import {
   createFetchAssetReader,
   createFileMapAssetReader,
@@ -346,6 +347,11 @@ export interface GizmoDragEvent {
 export type GizmoDragCallback = (event: GizmoDragEvent) => void
 
 export type EngineOptions = {
+  /** Run each model's physics on a dedicated Web Worker (default true where
+   *  Workers exist). Pipelined one frame deep: main-thread physics cost drops
+   *  to two small copies and multi-model scenes pay for the SLOWEST model
+   *  instead of the sum. false = classic main-thread stepping. */
+  physicsWorkers?: boolean
   world?: WorldOptions
   sun?: SunOptions
   camera?: CameraOptions
@@ -376,6 +382,7 @@ export interface EngineStats {
   jitter: number // ms — stddev of frame intervals (pacing evenness; high = janky at any mean fps)
   cpuAnimMs: number // ms/frame (EMA) — model updates: blending, IK, world matrices
   cpuPhysicsMs: number // ms/frame (EMA) — physics stepping across all instances
+  cpuPhysicsWorkerMs: number // ms/frame (EMA) — the SLOWEST worker's step cost. Background-thread time (often an efficiency core), parallel to the frame: it only matters if it exceeds the frame budget.
   cpuRenderMs: number // ms/frame (EMA) — the rest of the render thread: uniforms, encoding, submit
 }
 
@@ -429,7 +436,7 @@ interface ModelInstance {
   pickPerInstanceBindGroup: GPUBindGroup
   pickDrawCalls: PickDrawCall[]
   hiddenMaterials: Set<string>
-  physics: RezePhysics | null
+  physics: RezePhysics | WorkerPhysics | null
   vertexBufferNeedsUpdate: boolean
   gpuMorph: GpuMorph | null
   // Style groups applied to this model: group id → compiled install.
@@ -830,6 +837,7 @@ export class Engine {
     fps1PercentLow: 0,
     cpuAnimMs: 0,
     cpuPhysicsMs: 0,
+    cpuPhysicsWorkerMs: 0,
     cpuRenderMs: 0,
     jitter: 0,
   }
@@ -839,6 +847,7 @@ export class Engine {
   private viewTransform!: ViewTransformOptions
 
   constructor(canvas: HTMLCanvasElement, options?: EngineOptions) {
+    this.physicsWorkersEnabled = options?.physicsWorkers ?? true
     this.canvas = canvas
     const d = DEFAULT_ENGINE_OPTIONS
     this.world = {
@@ -3031,7 +3040,10 @@ export class Engine {
 
   dispose() {
     this.stopRenderLoop()
-    this.forEachInstance((inst) => inst.model.stopAnimation())
+    this.forEachInstance((inst) => {
+      inst.model.stopAnimation()
+      if (inst.physics instanceof WorkerPhysics) inst.physics.dispose()
+    })
     if (Engine.instance === this) Engine.instance = null
     if (this.camera) this.camera.detachControl()
 
@@ -3108,6 +3120,7 @@ export class Engine {
     const inst = this.modelInstances.get(name)
     if (!inst) return
     inst.model.stopAnimation()
+    if (inst.physics instanceof WorkerPhysics) inst.physics.dispose()
     for (const path of inst.textureCacheKeys) {
       const tex = this.textureCache.get(path)
       if (!tex) continue
@@ -3281,6 +3294,9 @@ export class Engine {
   // else on the render thread. The first question of any perf report.
   private cpuAnimMs = 0
   private cpuPhysicsMs = 0
+  /** EMA of worker-side step cost (all instances) — the off-thread physics bill. */
+  private cpuPhysicsWorkerMs = 0
+  private physicsWorkersEnabled = true
   private cpuRenderMs = 0
   private frameAnimMsRaw = 0
   private framePhysicsMsRaw = 0
@@ -3288,6 +3304,7 @@ export class Engine {
   private updateInstances(deltaTime: number): void {
     let animMs = 0
     let physicsMs = 0
+    let workerMs = 0
     this.forEachInstance((inst) => {
       const tAnim = performance.now()
       const verticesChanged = inst.model.update(deltaTime, this.ikEnabled)
@@ -3313,6 +3330,7 @@ export class Engine {
         const tPhys = performance.now()
         inst.physics.step(deltaTime, inst.model.getWorldMatrices(), inst.model.getBoneInverseBindMatrices())
         physicsMs += performance.now() - tPhys
+        if (inst.physics instanceof WorkerPhysics) workerMs = Math.max(workerMs, inst.physics.stepMs)
       }
       if (inst.vertexBufferNeedsUpdate) this.updateVertexBuffer(inst)
     })
@@ -3321,6 +3339,7 @@ export class Engine {
     const EMA = 0.1
     this.cpuAnimMs += (animMs - this.cpuAnimMs) * EMA
     this.cpuPhysicsMs += (physicsMs - this.cpuPhysicsMs) * EMA
+    this.cpuPhysicsWorkerMs += (workerMs - this.cpuPhysicsWorkerMs) * EMA
   }
 
   private updateVertexBuffer(inst: ModelInstance): void {
@@ -3432,7 +3451,17 @@ export class Engine {
     this.device.queue.writeBuffer(indexBuffer, 0, indices)
 
     const rbs = model.getRigidbodies()
-    const physics = rbs.length > 0 ? new RezePhysics(rbs, model.getJoints()) : null
+    let physics: RezePhysics | WorkerPhysics | null = null
+    if (rbs.length > 0) {
+      if (this.physicsWorkersEnabled && WorkerPhysics.supported()) {
+        try {
+          physics = await WorkerPhysics.create(rbs, model.getJoints(), model.getBoneInverseBindMatrices())
+        } catch (e) {
+          console.warn("[reze] physics worker unavailable — falling back to main-thread physics:", e)
+        }
+      }
+      if (!physics) physics = new RezePhysics(rbs, model.getJoints())
+    }
 
     const shadowBindGroup = this.device.createBindGroup({
       label: `${name}: shadow bind`,
@@ -5486,6 +5515,7 @@ export class Engine {
     this.stats.jitter = Math.round(stddev * 100) / 100
     this.stats.cpuAnimMs = Math.round(this.cpuAnimMs * 100) / 100
     this.stats.cpuPhysicsMs = Math.round(this.cpuPhysicsMs * 100) / 100
+    this.stats.cpuPhysicsWorkerMs = Math.round(this.cpuPhysicsWorkerMs * 100) / 100
     this.stats.cpuRenderMs = Math.round(this.cpuRenderMs * 100) / 100
   }
 }

package/src/physics/body.ts

@@ -53,6 +53,10 @@ export class RigidBodyStore {
   // Built lazily on first access.
   private collisionPairs: Uint16Array | null = null
 
+  /** Index of the built-in floor body (see RezePhysics constructor), -1 if none.
+   *  Excluded from the pair list; findContacts gives it a dedicated plane pass. */
+  groundIndex = -1
+
   constructor(rigidbodies: Rigidbody[]) {
     const N = rigidbodies.length
     this.count = N

package/src/physics/constraint.ts

@@ -33,64 +33,33 @@ export interface SixDofSpringConstraint {
   // positions and full-rate corrections chatter (see LOOP_ERP_SCALE).
   isLoop: boolean
 
-  // Per-substep cache. Filled by solver's setup pass once before SI iters,
+  // Per-substep solver cache lives in solver.ts' SolverCache (flat SoA typed
+  // arrays indexed by constraint slot) — see F_STRIDE layout there.
   // read by the velocity-only iter loop. None of these depend on lv/av — only
   // on pos/ori/inertia which are constant during solve.
-  cacheSkip: boolean              // both bodies static — skip entirely
-  cacheLeverA: Float32Array       // 3: rA = anchor − posA (world-space)
-  cacheLeverB: Float32Array       // 3
-  cacheLinAxes: Float32Array      // 9: 3 linear axes × xyz, world-space
-  cacheLinCrossA: Float32Array    // 9: I⁻¹A·(rA × ax) per axis
-  cacheLinCrossB: Float32Array    // 9: I⁻¹B·(rB × ax) per axis
-  cacheLinJacInv: Float32Array    // 3: 1/(im+im+cA²·ii+cB²·ii) per axis
   // Limit rows are unilateral (Bullet-style): the per-substep accumulated
   // impulse is clamped to the corrective sign, so a limit can push a body
   // back into range but never pull it deeper / brake its natural recovery —
   // bilateral limit rows act as motors and pump energy into swinging cloth.
-  cacheLinTargetVel: Float32Array // 3: limit ERP target, signed
-  cacheLinActive: Uint8Array      // 3
-  cacheLinLimitImp: Float32Array  // 3: accumulated limit impulse (per substep)
   // Spring rows are velocity-target drives; setup clamps k to the deadbeat
   // stability bound so they cannot pump energy. maxImp bounds the per-substep
   // accumulated impulse by the real spring force (k·|err|·dt) for rows that
   // must stay force-limited (loop-edge welds); Infinity for authored springs.
-  cacheLinSpringTarget: Float32Array // 3
-  cacheLinSpringMaxImp: Float32Array // 3
-  cacheLinSpringImp: Float32Array    // 3
-  cacheLinSpringActive: Uint8Array   // 3
-  cacheAngAxes: Float32Array      // 9 (spring rows)
-  cacheAngTargetVel: Float32Array // 3 (spring rows)
-  cacheAngActive: Uint8Array      // 3 (spring rows)
   // Per-axis angular Jacobians and tensor-multiplied axes: with full inertia
   // tensors the effective mass differs per axis, and impulse application
   // needs I⁻¹·axis per body.
-  cacheAngJacInv: Float32Array    // 3: 1/(axᵀ(I⁻¹A+I⁻¹B)ax) per axis
   // Angular spring force clamp (|k·err|·dt) + per-substep accumulator —
   // unclamped spring velocity-drives pump energy slowly (the restoring
   // magnitude on derived euler axes is orientation-dependent by up to ~25%,
   // and a mis-scaled oscillator restoring force injects per cycle).
-  cacheAngSpringMaxImp: Float32Array // 3
-  cacheAngSpringImp: Float32Array    // 3
-  cacheAngWA: Float32Array        // 9: I⁻¹A·axis per axis
-  cacheAngWB: Float32Array        // 9
   // Single geodesic limit row: shortest rotation from the current relative
   // orientation to the euler-clamped target. Per-axis euler limit rows are
   // geometrically inconsistent for large violations (asin singularity) and
   // pump energy instead of converging. Unilateral like the linear limits.
-  cacheAngLimAxis: Float32Array   // 3, world-space unit axis
-  cacheAngLimWA: Float32Array     // 3: I⁻¹A·axis
-  cacheAngLimWB: Float32Array     // 3
-  cacheAngLimJacInv: number
-  cacheAngLimTarget: number       // target relative angular velocity along axis
-  cacheAngLimActive: number
-  cacheAngLimImp: number          // accumulated impulse (per substep)
   // Per-axis angular limit rows for the small-violation regime. act:
   // 1 = bilateral (locked axis), 2 = unilateral stop (ranged axis) — a
   // bilateral row on a ranged axis brakes natural recovery and pumps
   // energy into swinging cloth.
-  cacheAngPATarget: Float32Array // 3
-  cacheAngPAActive: Uint8Array   // 3
-  cacheAngPAImp: Float32Array    // 3
 }
 
 // Stop-limit ERP. PMX rigs are tuned against MMD's stiff limit response;
@@ -173,38 +142,6 @@ export function buildConstraints(
       springStiffness,
       equilibriumPoint: new Float32Array(6),
       isLoop: false,
-      cacheSkip: false,
-      cacheLeverA: new Float32Array(3),
-      cacheLeverB: new Float32Array(3),
-      cacheLinAxes: new Float32Array(9),
-      cacheLinCrossA: new Float32Array(9),
-      cacheLinCrossB: new Float32Array(9),
-      cacheLinJacInv: new Float32Array(3),
-      cacheLinTargetVel: new Float32Array(3),
-      cacheLinActive: new Uint8Array(3),
-      cacheLinLimitImp: new Float32Array(3),
-      cacheLinSpringTarget: new Float32Array(3),
-      cacheLinSpringMaxImp: new Float32Array(3),
-      cacheLinSpringImp: new Float32Array(3),
-      cacheLinSpringActive: new Uint8Array(3),
-      cacheAngAxes: new Float32Array(9),
-      cacheAngTargetVel: new Float32Array(3),
-      cacheAngActive: new Uint8Array(3),
-      cacheAngJacInv: new Float32Array(3),
-      cacheAngSpringMaxImp: new Float32Array(3),
-      cacheAngSpringImp: new Float32Array(3),
-      cacheAngWA: new Float32Array(9),
-      cacheAngWB: new Float32Array(9),
-      cacheAngLimAxis: new Float32Array(3),
-      cacheAngLimWA: new Float32Array(3),
-      cacheAngLimWB: new Float32Array(3),
-      cacheAngLimJacInv: 0,
-      cacheAngLimTarget: 0,
-      cacheAngLimActive: 0,
-      cacheAngLimImp: 0,
-      cacheAngPATarget: new Float32Array(3),
-      cacheAngPAActive: new Uint8Array(3),
-      cacheAngPAImp: new Float32Array(3),
     })
   }
 

package/src/physics/contact.ts

@@ -993,4 +993,84 @@ export function findContacts(store: RigidBodyStore, pool: ContactPool): void {
     if (!aabbOverlap(store, i, j)) continue
     generateContacts(store, i, j, pool)
   }
+  // Built-in floor: a plane pass against every dynamic body. Cheaper and more
+  // complete than routing the huge ground box through the pair machinery —
+  // one y-test per body, and box hems collide too (there is no generic
+  // box-box narrowphase to lean on).
+  const g = store.groundIndex
+  if (g >= 0) {
+    const minA = store.aabbMin
+    for (let i = 0; i < store.count; i++) {
+      if (store.invMass[i] <= 0) continue
+      if (minA[i * 3 + 1] > CONTACT_MARGIN) continue
+      detectFloor(store, i, g, pool)
+    }
+  }
+}
+
+// The floor's top face is the model-space plane y = 0; its body (`g`) exists so
+// contact rows have a static B side. Normal convention matches the detectors:
+// A→B, so pointing DOWN into the floor; depth > 0 = penetrating.
+function detectFloor(store: RigidBodyStore, a: number, g: number, pool: ContactPool): void {
+  const ai = a * 3
+  const pos = store.positions
+  const gx = pos[g * 3 + 0]
+  const gy = pos[g * 3 + 1]
+  const gz = pos[g * 3 + 2]
+  const emit = (px: number, py: number, pz: number, depth: number) => {
+    const c = pool.acquire()
+    c.bodyA = a
+    c.bodyB = g
+    c.nx = 0
+    c.ny = -1
+    c.nz = 0
+    c.depth = depth
+    c.rAx = px - pos[ai + 0]
+    c.rAy = py - pos[ai + 1]
+    c.rAz = pz - pos[ai + 2]
+    c.rBx = px - gx
+    c.rBy = py - gy
+    c.rBz = pz - gz
+    combineMaterials(store, a, g, c)
+  }
+  const cx = pos[ai + 0]
+  const cy = pos[ai + 1]
+  const cz = pos[ai + 2]
+  switch (store.shape[a]) {
+    case RigidbodyShape.Sphere: {
+      const r = store.size[ai + 0]
+      const low = cy - r
+      if (low <= CONTACT_MARGIN) emit(cx, low, cz, -low)
+      break
+    }
+    case RigidbodyShape.Capsule: {
+      const r = store.size[ai + 0]
+      const h = store.size[ai + 1] * 0.5
+      const ax = _capPoint
+      capsuleAxis(store, a, ax)
+      for (const sgn of [-1, 1]) {
+        const ex = cx + ax[0] * h * sgn
+        const ey = cy + ax[1] * h * sgn
+        const ez = cz + ax[2] * h * sgn
+        const low = ey - r
+        if (low <= CONTACT_MARGIN) emit(ex, low, ez, -low)
+      }
+      break
+    }
+    case RigidbodyShape.Box: {
+      const hx = store.size[ai + 0]
+      const hy = store.size[ai + 1]
+      const hz = store.size[ai + 2]
+      const out = _capPointB
+      for (let k = 0; k < 8; k++) {
+        const lx = k & 1 ? hx : -hx
+        const ly = k & 2 ? hy : -hy
+        const lz = k & 4 ? hz : -hz
+        bodyLocalToWorldDir(store, a, lx, ly, lz, out)
+        const wy = cy + out[1]
+        if (wy <= CONTACT_MARGIN) emit(cx + out[0], wy, cz + out[2], -wy)
+      }
+      break
+    }
+  }
 }

package/src/physics/physics.ts

@@ -1,9 +1,10 @@
 import { Vec3, Quat, Mat4 } from "../math"
 import type { Rigidbody, Joint } from "./types"
-import { RigidbodyType } from "./types"
+import { RigidbodyType, RigidbodyShape } from "./types"
 import { RigidBodyStore } from "./body"
 import { World } from "./world"
 import { buildConstraints, type SixDofSpringConstraint } from "./constraint"
+import { SolverCache } from "./solver"
 import { ContactPool } from "./contact"
 
 const _bodyMat = new Float32Array(16)
@@ -19,6 +20,7 @@ export class RezePhysics {
   private store: RigidBodyStore
   private world: World
   private constraints: SixDofSpringConstraint[]
+  private solverCache: SolverCache
   private contacts: ContactPool
   private firstFrame = true
   private timeAccum = 0
@@ -67,9 +69,40 @@ export class RezePhysics {
   constructor(rigidbodies: Rigidbody[], joints: Joint[] = []) {
     this.rigidbodies = rigidbodies
     this.joints = joints
-    this.store = new RigidBodyStore(rigidbodies)
+    // The floor is part of every world: a huge static box whose top face is
+    // model-space y = 0, so hair and hems rest on the ground instead of
+    // clipping through when a pose reaches it. Boneless (every bone-sync loop
+    // skips boneIndex < 0); collides with EVERY dynamic body regardless of
+    // group masks via findContacts' dedicated plane pass (spheres, capsules
+    // and boxes — box hems included).
+    const ground: Rigidbody = {
+      name: "__ground__",
+      englishName: "__ground__",
+      boneIndex: -1,
+      group: 0,
+      collisionMask: 0xffff,
+      shape: RigidbodyShape.Box,
+      size: new Vec3(500, 1, 500),
+      shapePosition: new Vec3(0, -1, 0),
+      shapeRotation: new Vec3(0, 0, 0),
+      mass: 0,
+      linearDamping: 0,
+      angularDamping: 0,
+      restitution: 0,
+      friction: 0.6,
+      type: RigidbodyType.Static,
+      bodyOffsetMatrixInverse: Mat4.identity(),
+    }
+    this.store = new RigidBodyStore([...rigidbodies, ground])
+    const gi = this.store.count - 1
+    // Mask 0 keeps the floor OUT of the generic pair list — findContacts runs a
+    // dedicated plane pass against every dynamic body (all shapes, boxes too).
+    this.store.collisionGroup[gi] = 0
+    this.store.willCollideMask[gi] = 0
+    this.store.groundIndex = gi
     this.world = new World(new Vec3(0, -98, 0))
     this.constraints = buildConstraints(rigidbodies, joints)
+    this.solverCache = new SolverCache(this.constraints)
     this.contacts = new ContactPool()
     this.prevPositions = new Float32Array(this.store.count * 3)
     this.prevOrientations = new Float32Array(this.store.count * 4)
@@ -226,7 +259,7 @@ export class RezePhysics {
       this.savePrevState()
       this.advanceKinematicToTargets(1 / (nSub - k))
       const tStep = performance.now()
-      this.world.step(this.store, this.constraints, this.contacts, this.fixedTimeStep)
+      this.world.step(this.store, this.constraints, this.solverCache, this.contacts, this.fixedTimeStep)
       this.stepCostEmaMs += (performance.now() - tStep - this.stepCostEmaMs) * 0.2
       this.restoreNonFiniteBodies()
       this.timeAccum -= this.fixedTimeStep

package/src/physics/physics.worker.ts

@@ -0,0 +1,66 @@
+// Physics worker: owns ONE model's RezePhysics world. The host posts the
+// frame's bone world matrices as a transferable buffer; the worker steps the
+// simulation (identical math to the main-thread path — same class, same code)
+// and returns the buffer with the dynamic bones' matrices written back, plus
+// its own step cost for the host's stats.
+//
+// The incoming buffer is COPIED into a persistent local pose (and back out)
+// rather than wrapped: transferred ArrayBuffers get a fresh identity on every
+// hop, so wrappers could never be cached against them — and two ~20KB copies
+// per frame are microseconds.
+import { RezePhysics } from "./physics"
+import { Mat4 } from "../math"
+import type { Rigidbody, Joint } from "./types"
+import { RigidbodyType } from "./types"
+
+interface InitMsg {
+  cmd: "init"
+  rigidbodies: Rigidbody[]
+  joints: Joint[]
+  inverseBind: Float32Array
+}
+interface PoseMsg {
+  cmd: "step" | "reset"
+  dt: number
+  bones: ArrayBuffer
+}
+
+const ctx = self as unknown as {
+  onmessage: ((e: MessageEvent<InitMsg | PoseMsg>) => void) | null
+  postMessage(msg: unknown, transfer?: Transferable[]): void
+}
+
+let physics: RezePhysics | null = null
+let inverseBind: Float32Array<ArrayBufferLike> = new Float32Array(0)
+let pose = new Float32Array(0)
+let mats: Mat4[] = []
+
+ctx.onmessage = (e) => {
+  const msg = e.data
+  if (msg.cmd === "init") {
+    physics = new RezePhysics(msg.rigidbodies, msg.joints)
+    inverseBind = msg.inverseBind
+    const boneCount = inverseBind.length / 16
+    pose = new Float32Array(boneCount * 16)
+    mats = new Array(boneCount)
+    for (let i = 0; i < boneCount; i++) mats[i] = new Mat4(pose.subarray(i * 16, i * 16 + 16) as Float32Array)
+    // The host copies back only the bones physics can write — the bones of
+    // dynamic bodies. Kinematic bones must NOT round-trip: in the pipelined
+    // protocol they would drag a stale (frame-old) pose over the live one.
+    const dynamicBones: number[] = []
+    for (const rb of msg.rigidbodies) {
+      if (rb.type === RigidbodyType.Dynamic && rb.mass > 0 && rb.boneIndex >= 0) dynamicBones.push(rb.boneIndex)
+    }
+    ctx.postMessage({ cmd: "ready", dynamicBones })
+    return
+  }
+  if (!physics) return
+  const incoming = new Float32Array(msg.bones)
+  pose.set(incoming)
+  const t0 = performance.now()
+  if (msg.cmd === "step") physics.step(msg.dt, mats, inverseBind)
+  else physics.reset(mats)
+  const stepMs = performance.now() - t0
+  incoming.set(pose)
+  ctx.postMessage({ cmd: "stepped", bones: msg.bones, stepMs }, [msg.bones])
+}