@adobe/data-gpu 0.9.69

package/src/physics/joint/joint-type/joint-type.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+
+/**
+ * How a joint constrains the two bodies it connects:
+ *   fixed — rigidly locks them together (no relative motion).
+ *   point — a ball/spherical joint: anchors coincide, free rotation (chains, ragdoll joints).
+ *   hinge — a revolute joint: 1 rotational DOF about an axis, with optional angle limits (doors, elbows).
+ *   cone  — a swing-twist joint: the bone axis is bound to a cone (half-angle
+ *           `jointSwingLimit`) around the reference axis, with a twist range
+ *           (`jointMinLimit`/`jointMaxLimit`) about it — anatomical shoulder/hip
+ *           limits for ragdolls. Full on Jolt (SwingTwist); Rapier's compat
+ *           binding has no cone limit, so it approximates `cone` as a free `point`.
+ */
+export type JointType = Schema.ToType<typeof schema>;
+
+export * as JointType from "./public.js";

package/src/physics/joint/joint-type/public.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { schema } from "./schema.js";

package/src/physics/joint/joint-type/schema.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+
+export const schema = { type: "string", enum: ["fixed", "point", "hinge", "cone"] } as const satisfies Schema;

package/src/physics/joint/joint.ts

@@ -0,0 +1,27 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Entity } from "@adobe/data/ecs";
+import type { Vec3 } from "@adobe/data/math";
+import type { JointType } from "./joint-type/joint-type.js";
+
+/**
+ * One row of the `Joint` archetype — a constraint between two bodies, solved by
+ * whichever physics solver is active. Anchors are in each body's local frame;
+ * at rest the two anchor points coincide in world space (the joint location).
+ *
+ * `jointAxis` is the reference axis (body-A local) for `hinge` and `cone`,
+ * ignored otherwise. `jointMinLimit`/`jointMaxLimit` bound the hinge angle, or
+ * the `cone` twist angle, in radians (`min >= max` ⇒ free); `jointSwingLimit` is
+ * the `cone` swing half-angle.
+ */
+export interface Joint {
+    jointType: JointType;
+    jointBodyA: Entity;
+    jointBodyB: Entity;
+    jointAnchorA: Vec3;
+    jointAnchorB: Vec3;
+    jointAxis: Vec3;
+    jointMinLimit: number;
+    jointMaxLimit: number;
+    jointSwingLimit: number;
+}

package/src/physics/physics-clock-plugin.ts

@@ -0,0 +1,61 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { core } from "../core/core-plugin.js";
+
+/**
+ * Fixed-timestep physics clock — decouples the simulation rate from the render
+ * rate (Fiedler "fix your timestep"). Each render frame the accumulator absorbs
+ * the variable `frameTime.dt`; the solver then runs a whole number of fixed
+ * `fixedDt` steps (0, 1, or several), and `alpha` is the leftover fraction used
+ * to interpolate the rendered pose between the last two simulated states.
+ *
+ * Default 60 Hz; set another rate at init with `setFixedTimestep(hz)`.
+ */
+export interface PhysicsClock {
+    /** Fixed simulation step length, seconds (default 1/60). */
+    readonly fixedDt: number;
+    /** Unsimulated time carried to the next frame, seconds (< fixedDt). */
+    readonly accumulator: number;
+    /** accumulator / fixedDt ∈ [0,1): render interpolation fraction prev→current. */
+    readonly alpha: number;
+    /** Whole steps the solver should run this frame (0..maxSubSteps). */
+    readonly steps: number;
+    /** Cap on steps/frame — prevents the "spiral of death" after a long stall. */
+    readonly maxSubSteps: number;
+}
+
+const DEFAULT: PhysicsClock = { fixedDt: 1 / 60, accumulator: 0, alpha: 0, steps: 0, maxSubSteps: 8 };
+
+/**
+ * Provides the `physicsClock` resource and advances it once per render frame.
+ * Solver plugins extend this and run `physicsClock.steps` fixed steps; the
+ * interpolation system reads `physicsClock.alpha`. The advance runs first in the
+ * `physics` phase so solvers (scheduled `after: ["advancePhysicsClock"]`) see it.
+ */
+export const physicsClock = Database.Plugin.create({
+    extends: core,
+    resources: {
+        physicsClock: { default: DEFAULT as PhysicsClock, transient: true },
+    },
+    transactions: {
+        /** Set the simulation rate (Hz). Call once at init; default is 60. */
+        setFixedTimestep(t, hz: number) {
+            t.resources.physicsClock = { ...t.resources.physicsClock, fixedDt: 1 / hz };
+        },
+    },
+    systems: {
+        advancePhysicsClock: {
+            schedule: { during: ["physics"] },
+            create: db => () => {
+                const c = db.store.resources.physicsClock;
+                const h = c.fixedDt;
+                // clamp the absorbed time to the step budget so a long stall (tab
+                // backgrounded, GC) can't queue hundreds of steps (spiral of death)
+                const acc = c.accumulator + Math.min(db.store.resources.frameTime.dt, h * c.maxSubSteps);
+                const steps = Math.min(Math.floor(acc / h), c.maxSubSteps);
+                db.store.resources.physicsClock = { ...c, accumulator: acc - steps * h, alpha: (acc - steps * h) / h, steps };
+            },
+        },
+    },
+});

package/src/physics/physics-clock.test.ts

@@ -0,0 +1,55 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { Database } from "@adobe/data/ecs";
+import { physicsClock, type PhysicsClock } from "./physics-clock-plugin.js";
+
+/** The accumulator turns a variable render dt into a whole number of fixed steps
+ *  plus a leftover interpolation `alpha`, capped against the spiral of death. */
+describe("physicsClock", () => {
+    // A created database carries a writable `store` (runtime invariant; not on the
+    // public type — same loose access the solver benchmark uses to drive frames).
+    interface ClockStore { resources: { physicsClock: PhysicsClock; frameTime: { now: number; dt: number; elapsed: number } } }
+
+    const make = () => {
+        const db = Database.create(physicsClock); // 60 Hz default
+        const store = (db as unknown as { store: ClockStore }).store;
+        const advance = (dt: number): PhysicsClock => {
+            store.resources.frameTime = { now: 0, dt, elapsed: 0 };
+            db.system.functions.advancePhysicsClock?.();
+            return store.resources.physicsClock;
+        };
+        return { db, advance };
+    };
+
+    it("matched render rate → exactly one step per frame, alpha ≈ 0", () => {
+        const c = make().advance(1 / 60);
+        expect(c.steps).toBe(1);
+        expect(c.alpha).toBeCloseTo(0);
+    });
+
+    it("render slower than sim → multiple steps per frame", () => {
+        expect(make().advance(1 / 30).steps).toBe(2); // two 1/60 steps fit one 1/30 frame
+    });
+
+    it("render faster than sim → 0-step frames that accumulate, alpha rising then resetting", () => {
+        const { advance } = make();
+        const a = advance(1 / 120); // half a step accrued
+        expect(a.steps).toBe(0);
+        expect(a.alpha).toBeCloseTo(0.5);
+        const b = advance(1 / 120); // now a full step is due
+        expect(b.steps).toBe(1);
+        expect(b.alpha).toBeCloseTo(0);
+    });
+
+    it("a long stall is capped at maxSubSteps (no spiral of death)", () => {
+        const c = make().advance(10); // 600 steps' worth of time
+        expect(c.steps).toBe(c.maxSubSteps);
+    });
+
+    it("setFixedTimestep changes the rate", () => {
+        const { db, advance } = make();
+        db.transactions.setFixedTimestep(30);
+        expect(advance(1 / 30).steps).toBe(1); // one 1/30 step per 1/30 frame
+    });
+});

package/src/physics/physics-data-plugin.ts

@@ -0,0 +1,73 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { F32 } from "@adobe/data/schema";
+import { Vec3, Quat } from "@adobe/data/math";
+import { BodyType } from "./body/body-type/body-type.js";
+import { ColliderShape } from "./body/collider-shape/collider-shape.js";
+import type { ColliderMesh } from "./body/collider-mesh.js";
+import { Material } from "../material/material.js";
+
+/**
+ * The shared, solver-agnostic rigid-body data model — the seam every physics
+ * solver plugs into. It declares *only* authored/canonical state (no systems):
+ *
+ *   bodyType, colliderShape, halfExtents, material  — authored shape + role
+ *   position, rotation, linearVelocity, angularVelocity — canonical live state
+ *
+ * A **solver plugin** `extends` this, may keep its own private `_`-prefixed
+ * internal state (broadphase, caches, GPU buffers), and each frame reads the
+ * authored state and writes back `position`/`rotation`/velocity for dynamic
+ * bodies. A renderer reads the canonical transforms, decoupled from which
+ * solver produced them — so solvers (`joltSolver`, `rapierSolver`; the GPU XPBD
+ * solver is shelved) are interchangeable over identical authored scenes.
+ *
+ * Two archetypes share these components:
+ *   - **RigidBody** — `dynamic` or `kinematic` bodies that move; carries
+ *     velocities and a `bodyType` discriminator.
+ *   - **StaticCollider** — immovable colliders (floor, wall, ramp, scenery).
+ *     No velocities (never integrated) and no `bodyType` (the archetype *is*
+ *     the static classification) — a lean row for the bulk-static workload.
+ *
+ * `_prevPosition`/`_prevRotation` are derived (`_`-prefixed): the solver snapshots
+ * the pose *before* its final fixed step into them, so a render-rate interpolation
+ * pass can smoothly blend the previous → current simulated pose (see
+ * `physics-clock-plugin` + `interpolation-plugin`). Like `_worldMatrix`, they are
+ * *not* in the authored archetype — the solver migrates them onto each dynamic
+ * body the first time it mirrors it, so authors never supply derived state.
+ *
+ * Mass + inertia are derived per solver from shape + material (not stored here).
+ */
+export const physicsData = Database.Plugin.create({
+    extends: Material.plugin,   // brings the `material` reference component
+    components: {
+        bodyType:        BodyType.schema,
+        colliderShape:   ColliderShape.schema,
+        halfExtents:     Vec3.schema,   // box extents; sphere radius in .x
+        position:        Vec3.schema,
+        rotation:        Quat.schema, // unified with Node.rotation so a body renders directly
+        linearVelocity:  Vec3.schema,
+        angularVelocity: Vec3.schema,
+        _prevPosition:   Vec3.schema, // derived: pose before the last fixed step (render interpolation)
+        _prevRotation:   Quat.schema,
+        // Bodies sharing the same non-zero collisionGroup do not collide with each
+        // other (they still collide with group 0 / the world) — e.g. a ragdoll's
+        // bones. 0 = default (collide with everything). Honored by both solvers
+        // (Rapier per-collider groups; Jolt a no-self-collide object layer). Note:
+        // it's currently binary (group 0 vs "some non-zero group"), not per-id masks.
+        collisionGroup:  F32.schema,
+        // Authored collision geometry for shapes `halfExtents` can't describe.
+        // Runtime objects (variable length, no schema): the solver reads them once
+        // when it mirrors the body, the bridge once to build the render mesh.
+        convexPoints:    { default: null as Float32Array | null }, // colliderShape "hull": point cloud → convex hull
+        colliderMesh:    { default: null as ColliderMesh | null }, // colliderShape "mesh": static triangle soup
+    },
+    archetypes: {
+        RigidBody: ["bodyType", "colliderShape", "halfExtents", "material", "position", "rotation", "linearVelocity", "angularVelocity"],
+        StaticCollider: ["colliderShape", "halfExtents", "material", "position", "rotation"],
+        // A convex-hull body (dynamic / kinematic): authored as a point cloud.
+        ConvexBody: ["bodyType", "colliderShape", "halfExtents", "material", "position", "rotation", "linearVelocity", "angularVelocity", "convexPoints"],
+        // A static triangle-mesh collider (terrain / level geometry).
+        MeshCollider: ["colliderShape", "halfExtents", "material", "position", "rotation", "colliderMesh"],
+    },
+});

package/src/physics/ragdoll/fit-bone-capsules.test.ts

@@ -0,0 +1,66 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { fitBoneCapsules, type SkinVertices } from "./fit-bone-capsules.js";
+
+const IDENTITY_IBM = (n: number) => {
+    const m = new Float32Array(n * 16);
+    for (let j = 0; j < n; j++) { m[j * 16] = 1; m[j * 16 + 5] = 1; m[j * 16 + 10] = 1; m[j * 16 + 15] = 1; }
+    return m;
+};
+
+/** 8 corners of a box, all dominantly weighted to `joint`. */
+function boxCorners(cx: number, cy: number, cz: number, hx: number, hy: number, hz: number, joint: number) {
+    const pos: number[] = [], jn: number[] = [], wt: number[] = [];
+    for (const sx of [-1, 1]) for (const sy of [-1, 1]) for (const sz of [-1, 1]) {
+        pos.push(cx + sx * hx, cy + sy * hy, cz + sz * hz);
+        jn.push(joint, 0, 0, 0); wt.push(1, 0, 0, 0);
+    }
+    return { pos, jn, wt };
+}
+
+const skinFrom = (...parts: { pos: number[]; jn: number[]; wt: number[] }[]): SkinVertices => ({
+    positions: new Float32Array(parts.flatMap(p => p.pos)),
+    joints: new Uint32Array(parts.flatMap(p => p.jn)),
+    weights: new Float32Array(parts.flatMap(p => p.wt)),
+});
+
+// rotate (0,1,0) by a quaternion
+const rotateUp = (q: readonly number[]): [number, number, number] => {
+    const [x, y, z, w] = q;
+    return [2 * (x * y - w * z), 1 - 2 * (x * x + z * z), 2 * (y * z + w * x)];
+};
+
+describe("fitBoneCapsules", () => {
+    it("fits an X-elongated bone to an X-axis capsule of the right size", () => {
+        // box x∈[-2,2], y∈[-0.5,0.5], z∈[-0.4,0.4] → axis X, radius ½·max(1,0.8)=0.5, halfHeight 2−0.5=1.5
+        const caps = fitBoneCapsules({ jointCount: 1, inverseBindMatrices: IDENTITY_IBM(1), skin: skinFrom(boxCorners(0, 0, 0, 2, 0.5, 0.4, 0)) });
+        expect(caps).toHaveLength(1);
+        const c = caps[0];
+        expect(c.jointIndex).toBe(0);
+        expect(c.radius).toBeCloseTo(0.5);
+        expect(c.halfHeight).toBeCloseTo(1.5);
+        expect(c.offsetPosition[0]).toBeCloseTo(0);
+        // the capsule's local +Y, rotated by the offset, points along world X (the fit axis)
+        const up = rotateUp(c.offsetRotation);
+        expect(Math.abs(up[0])).toBeCloseTo(1);
+        expect(Math.abs(up[1])).toBeCloseTo(0);
+    });
+
+    it("fits one capsule per bone, grouping vertices by dominant weight", () => {
+        const caps = fitBoneCapsules({
+            jointCount: 2, inverseBindMatrices: IDENTITY_IBM(2),
+            skin: skinFrom(boxCorners(0, 0, 0, 1, 0.3, 0.3, 0), boxCorners(0, 5, 0, 0.3, 1, 0.3, 1)),
+        });
+        expect(caps.map(c => c.jointIndex).sort()).toEqual([0, 1]);
+        // bone 1 is Y-elongated → its capsule axis is Y (offset rotation ≈ identity)
+        const c1 = caps.find(c => c.jointIndex === 1)!;
+        expect(rotateUp(c1.offsetRotation)[1]).toBeCloseTo(1);
+        expect(c1.offsetPosition[1]).toBeCloseTo(5);
+    });
+
+    it("skips bones with too few assigned vertices", () => {
+        const sparse = { pos: [0, 0, 0, 1, 0, 0, 2, 0, 0], jn: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], wt: [1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0] };
+        expect(fitBoneCapsules({ jointCount: 1, inverseBindMatrices: IDENTITY_IBM(1), skin: skinFrom(sparse) })).toHaveLength(0);
+    });
+});

package/src/physics/ragdoll/fit-bone-capsules.ts

@@ -0,0 +1,106 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Vec3, Quat } from "@adobe/data/math";
+
+/**
+ * Fits one capsule collider to each significant bone of a skinned mesh — the
+ * per-bone colliders a ragdoll needs (you can't trimesh a deforming skin). Each
+ * vertex is assigned to the bone it's *most* weighted to; that bone's vertices
+ * are pushed into the bone's bind-local frame (via the joint's inverse-bind
+ * matrix) and a capsule is fitted to them: the longest local axis becomes the
+ * capsule axis, the perpendicular spread its radius.
+ *
+ * The result is expressed as a bone-local offset (`offsetPosition` /
+ * `offsetRotation`, which orients the Y-aligned capsule onto the fitted axis)
+ * plus dimensions — so the capsule's world pose each frame is just
+ * `jointWorldMatrix · offset`, tracking the animated skeleton.
+ */
+
+/** Skinned vertices in mesh (bind) space: `positions` (xyz triples), `joints`
+ *  (4 joint indices/vertex), `weights` (4 weights/vertex). */
+export interface SkinVertices {
+    positions: Float32Array;
+    joints: Uint32Array;
+    weights: Float32Array;
+}
+
+export interface FitBoneCapsulesInput {
+    jointCount: number;
+    /** glTF inverse-bind matrices, column-major, `jointCount × 16`. */
+    inverseBindMatrices: Float32Array;
+    skin: SkinVertices;
+    /** A vertex joins a bone only if its dominant weight ≥ this (default 0.5). */
+    minWeight?: number;
+    /** Bones with fewer assigned vertices than this get no capsule (default 6). */
+    minVertices?: number;
+}
+
+export interface BoneCapsule {
+    jointIndex: number;
+    offsetPosition: Vec3; // capsule centre, bone-bind-local
+    offsetRotation: Quat; // orients the Y-aligned capsule onto the fitted axis, bone-bind-local
+    radius: number;
+    halfHeight: number;   // half-length of the cylindrical section
+}
+
+/** Transform a point by a column-major 4×4 matrix (slice `o..o+16`), into `out`. */
+function transformPoint(m: Float32Array, o: number, x: number, y: number, z: number, out: [number, number, number]): void {
+    out[0] = m[o] * x + m[o + 4] * y + m[o + 8] * z + m[o + 12];
+    out[1] = m[o + 1] * x + m[o + 5] * y + m[o + 9] * z + m[o + 13];
+    out[2] = m[o + 2] * x + m[o + 6] * y + m[o + 10] * z + m[o + 14];
+}
+
+/** Shortest-arc quaternion rotating +Y onto unit vector `b`. */
+function quatFromY(bx: number, by: number, bz: number): Quat {
+    if (by > 0.99999) return [0, 0, 0, 1];               // already +Y
+    if (by < -0.99999) return [0, 0, 1, 0];              // 180° (about Z) onto −Y
+    // half-vector method: h = normalize((0,1,0) + b); q = ((0,1,0)×h, (0,1,0)·h)
+    const hx = bx, hy = 1 + by, hz = bz;
+    const hl = Math.hypot(hx, hy, hz) || 1;
+    const nx = hx / hl, ny = hy / hl, nz = hz / hl;
+    // (0,1,0) × (nx,ny,nz) = (nz·? ) → cross = (1*nz - 0*ny, 0*nx - 0*nz, 0*ny - 1*nx) = (nz, 0, -nx)
+    return [nz, 0, -nx, ny];
+}
+
+export function fitBoneCapsules(input: FitBoneCapsulesInput): BoneCapsule[] {
+    const { jointCount, inverseBindMatrices: ibm, skin } = input;
+    const minWeight = input.minWeight ?? 0.5;
+    const minVertices = input.minVertices ?? 6;
+    const vertexCount = skin.positions.length / 3;
+
+    // bone-local AABB per joint (min/max), accumulated over its dominant vertices
+    const min = new Float32Array(jointCount * 3).fill(Infinity);
+    const max = new Float32Array(jointCount * 3).fill(-Infinity);
+    const count = new Uint32Array(jointCount);
+    const p: [number, number, number] = [0, 0, 0];
+
+    for (let v = 0; v < vertexCount; v++) {
+        // dominant bone = the vertex's max-weight joint
+        let best = 0, bestW = -1;
+        for (let k = 0; k < 4; k++) { const w = skin.weights[v * 4 + k]; if (w > bestW) { bestW = w; best = skin.joints[v * 4 + k]; } }
+        if (bestW < minWeight || best >= jointCount) continue;
+        transformPoint(ibm, best * 16, skin.positions[v * 3], skin.positions[v * 3 + 1], skin.positions[v * 3 + 2], p);
+        const b = best * 3;
+        if (p[0] < min[b]) min[b] = p[0]; if (p[0] > max[b]) max[b] = p[0];
+        if (p[1] < min[b + 1]) min[b + 1] = p[1]; if (p[1] > max[b + 1]) max[b + 1] = p[1];
+        if (p[2] < min[b + 2]) min[b + 2] = p[2]; if (p[2] > max[b + 2]) max[b + 2] = p[2];
+        count[best]++;
+    }
+
+    const out: BoneCapsule[] = [];
+    for (let j = 0; j < jointCount; j++) {
+        if (count[j] < minVertices) continue;
+        const b = j * 3;
+        const ex = max[b] - min[b], ey = max[b + 1] - min[b + 1], ez = max[b + 2] - min[b + 2];
+        // longest extent = capsule axis; the other two give the (bounding) radius
+        let axis: 0 | 1 | 2 = 0, axisExtent = ex, r1 = ey, r2 = ez;
+        if (ey >= ex && ey >= ez) { axis = 1; axisExtent = ey; r1 = ex; r2 = ez; }
+        else if (ez >= ex && ez >= ey) { axis = 2; axisExtent = ez; r1 = ex; r2 = ey; }
+        const radius = Math.max(r1, r2) / 2 || 1e-3;
+        const halfHeight = Math.max(0, axisExtent / 2 - radius);
+        const offsetPosition: Vec3 = [(min[b] + max[b]) / 2, (min[b + 1] + max[b + 1]) / 2, (min[b + 2] + max[b + 2]) / 2];
+        const offsetRotation = quatFromY(axis === 0 ? 1 : 0, axis === 1 ? 1 : 0, axis === 2 ? 1 : 0);
+        out.push({ jointIndex: j, offsetPosition, offsetRotation, radius, halfHeight });
+    }
+    return out;
+}

package/src/physics/solvers/README.md

@@ -0,0 +1,63 @@
+# Physics solvers
+
+Rigid-body solvers that plug into the shared `physicsData` seam. A solver reads
+the authored `RigidBody` + `StaticCollider` components and writes back
+`position`/`rotation`/velocity for dynamic bodies each frame, so the **same
+scene runs unchanged on any solver** (`Database.Plugin.combine(scene, solver)`).
+
+Two production-grade solvers ship, both compiled to WASM and wired identically:
+
+| solver | engine | license |
+| --- | --- | --- |
+| `joltSolver` | Jolt Physics (Jorrit Rouwe) | MIT |
+| `rapierSolver` | Rapier (dimforge) | Apache-2.0 |
+
+Both are **opt-in**: the engine packages are regular dependencies, but with
+`sideEffects: false` a bundler tree-shakes the solver (and its WASM) out unless
+you actually import it. (The from-scratch CPU-XPBD solver was removed — it was
+~10–15× slower and unstable on dense piles; these engines supersede it.)
+
+## Which to use
+
+**Default to `joltSolver`.** It's the most stable, it sleeps inert bodies (so
+"many static, few dynamic" scenes cost almost nothing), and it handles deep/dense
+stacks cleanly.
+
+**Choose `rapierSolver` only when** the scene is dominated by *many
+simultaneously-active dynamic bodies* most of the time **and** tight stability
+isn't critical — that's the one regime where Rapier's per-step dynamic
+throughput wins.
+
+## Measured baseline
+
+Headless harness (`runSolverBenchmark`), fixed 1/60 s timestep. Stability shown
+as end-state mean height / peak speed (a tight settle is low/low).
+
+**256 mixed dynamic bodies dropped into a walled bin (300 frames):**
+
+| solver | ms/frame | sim-fps | stability (avgY · maxV) |
+| --- | --- | --- | --- |
+| `rapierSolver` | **0.90** | 1117 | −1.3 · 57 |
+| `joltSolver` | 1.57 | 638 | **−0.4 · 47** (tighter) |
+
+→ Rapier ~1.7× faster on a busy dynamic pile; Jolt settles tighter.
+
+**8000 static + 64 dynamic (the "many static, few dynamic" target):**
+
+| solver | ms/frame |
+| --- | --- |
+| `joltSolver` | **0.196** |
+| `rapierSolver` | 0.344 |
+
+→ Jolt ~1.75× faster — it sleeps the inert statics to near-zero step cost.
+
+Reproduce / track regressions: `npx vitest --run
+src/physics/solvers/rapier-jolt.benchmark.test.ts`. Numbers are post the
+sync tag-exclude optimization (see this package's `CLAUDE.md`).
+
+## Adding another solver
+
+Implement the seam: extend `combine(physicsData, core)`, mirror new bodies into
+the engine in the `physics` phase (tag + `exclude` so the sync is O(new) — see
+the existing plugins and `CLAUDE.md`), step, and write the dynamic transforms
+back via `getTypedArray()`. Benchmark it through `runSolverBenchmark` to compare.