@adobe/data-gpu 0.9.69

package/src/physics/solvers/rapier-solver-plugin.ts

@@ -0,0 +1,251 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import RAPIER from "@dimforge/rapier3d-compat";
+import { Database, type Entity } from "@adobe/data/ecs";
+import { True } from "@adobe/data/schema";
+import { physicsClock } from "../physics-clock-plugin.js";
+import { physicsData } from "../physics-data-plugin.js";
+import { jointData } from "../joint/joint-plugin.js";
+import { BodyType } from "../body/body-type/body-type.js";
+import { ColliderShape } from "../body/collider-shape/collider-shape.js";
+
+/**
+ * A second rigid-body solver behind the same `physicsData` seam — the
+ * battle-tested Rapier engine (dimforge, Rust→WASM). It reads the identical
+ * authored components (`RigidBody` + `StaticCollider`) and writes back
+ * `position`/`rotation`/velocity for dynamic bodies, exactly like `joltSolver`,
+ * so the same scene runs unchanged on either solver.
+ *
+ * Rapier's WASM must be initialised before use; per the repo's no-top-level-await
+ * rule, the init promise lives in the system closure and is awaited lazily — the
+ * system no-ops until the world exists, then runs every frame.
+ */
+
+const GRAVITY = 18; // matches joltSolver so the two solvers are directly comparable
+
+const RIGID = ["bodyType", "colliderShape", "halfExtents", "material", "position", "rotation", "linearVelocity", "angularVelocity"] as const;
+const STATIC = ["colliderShape", "halfExtents", "material", "position", "rotation"] as const;
+// Dynamic bodies carry the derived prev-pose snapshot (added on first sync) used
+// for render interpolation; this query reads/writes it alongside the live pose.
+const SNAPSHOT = ["bodyType", "position", "rotation", "_prevPosition", "_prevRotation"] as const;
+// Sync only over bodies not yet mirrored into Rapier: a private `_rapierBody`
+// tag is added once a body is created, and excluded here, so steady state
+// iterates zero rows (archetype-level) instead of re-scanning every body each
+// frame — the win for the "many static, few dynamic" target.
+const NEW_RIGID = { exclude: ["_rapierBody"] } as const;
+const NEW_STATIC = { exclude: ["linearVelocity", "_rapierBody"] } as const;
+// Kinematic bodies, by archetype shape (no per-row value test): they have
+// `bodyType` (so not a StaticCollider) and are mirrored (`_rapierBody`) but never
+// gained `_prevPosition` (only dynamics do) — so excluding it isolates kinematics.
+const KINEMATIC = ["bodyType", "position", "rotation", "_rapierBody"] as const;
+const KINEMATIC_ONLY = { exclude: ["_prevPosition"] } as const;
+const JOINT = ["jointType", "jointBodyA", "jointBodyB", "jointAnchorA", "jointAnchorB", "jointAxis", "jointMinLimit", "jointMaxLimit", "jointSwingLimit"] as const;
+const NEW_JOINT = { exclude: ["_rapierJoint"] } as const;
+
+interface MatProps { density: number; restitution: number; friction: number }
+
+export const rapierSolver = Database.Plugin.create({
+    extends: Database.Plugin.combine(physicsData, jointData, physicsClock),
+    components: {
+        _rapierBody: True.schema, // tag: this body has been mirrored into the Rapier world
+        _rapierJoint: True.schema, // tag: this joint has been mirrored into the Rapier world
+    },
+    systems: {
+        rapierStep: {
+            schedule: { during: ["physics"], after: ["advancePhysicsClock"] },
+            create: db => {
+                let world: RAPIER.World | null = null;
+                let initStarted = false;
+                const bodies = new Map<Entity, RAPIER.RigidBody>(); // entity → Rapier body
+
+                const matPropsOf = (id: Entity): MatProps => {
+                    // Material entities carry density/restitution/friction (read once at body creation).
+                    const m = db.store.read(id) as { density?: number; restitution?: number; friction?: number } | null;
+                    return { density: m?.density ?? 1, restitution: m?.restitution ?? 0.2, friction: m?.friction ?? 0.5 };
+                };
+
+                // hull/mesh colliders may be auto-generated from a model that's still
+                // loading — defer mirroring such a body until its collision data exists.
+                const colliderReady = (id: Entity, shape: ColliderShape): boolean => {
+                    if (shape !== "hull" && shape !== "mesh") return true;
+                    const r = db.store.read(id) as { convexPoints?: unknown; colliderMesh?: unknown } | null;
+                    return !!(r?.convexPoints || r?.colliderMesh);
+                };
+
+                const ensureBody = (id: Entity, motion: BodyType, shape: ColliderShape, hx: number, hy: number, hz: number, mat: Entity, px: number, py: number, pz: number, q: ArrayLike<number>, vx: number, vy: number, vz: number, wx: number, wy: number, wz: number): void => {
+                    if (!world || bodies.has(id)) return;
+                    const m = matPropsOf(mat);
+                    // dynamic = simulated; kinematic = position-driven (pushes dynamics,
+                    // isn't pushed back); fixed = immovable collider.
+                    const desc = motion === "dynamic" ? RAPIER.RigidBodyDesc.dynamic()
+                        : motion === "kinematic" ? RAPIER.RigidBodyDesc.kinematicPositionBased()
+                            : RAPIER.RigidBodyDesc.fixed();
+                    desc.setTranslation(px, py, pz).setRotation({ x: q[0], y: q[1], z: q[2], w: q[3] });
+                    if (motion === "dynamic") { desc.setLinvel(vx, vy, vz); desc.setAngvel({ x: wx, y: wy, z: wz }); }
+                    const body = world.createRigidBody(desc);
+                    // capsule: Y-aligned, halfHeight = cylinder half (hy), radius = hx.
+                    // hull: convex hull of the authored point cloud (read once here).
+                    let col: RAPIER.ColliderDesc | null;
+                    if (shape === "sphere") col = RAPIER.ColliderDesc.ball(hx);
+                    else if (shape === "capsule") col = RAPIER.ColliderDesc.capsule(hy, hx);
+                    else if (shape === "hull") {
+                        const pts = (db.store.read(id) as { convexPoints?: Float32Array | null }).convexPoints;
+                        col = pts ? RAPIER.ColliderDesc.convexHull(pts) : null;
+                        if (!col) col = RAPIER.ColliderDesc.ball(Math.max(hx, 0.1)); // degenerate cloud fallback
+                    } else if (shape === "mesh") {
+                        const cm = (db.store.read(id) as { colliderMesh?: { positions: Float32Array; indices: Uint32Array } | null }).colliderMesh;
+                        col = cm ? RAPIER.ColliderDesc.trimesh(cm.positions, cm.indices) : RAPIER.ColliderDesc.cuboid(0.1, 0.1, 0.1);
+                    } else col = RAPIER.ColliderDesc.cuboid(hx, hy, hz);
+                    col.setRestitution(m.restitution).setFriction(m.friction).setDensity(m.density);
+                    // collisionGroup g (>0): membership bit g, collide with everything
+                    // except bit g — so same-group bodies (e.g. a ragdoll's bones) skip
+                    // each other but still hit the world (group 0).
+                    const g = (db.store.read(id) as { collisionGroup?: number } | null)?.collisionGroup ?? 0;
+                    if (g > 0) { const bit = 1 << (g & 15); col.setCollisionGroups(((bit << 16) | (0xffff & ~bit)) >>> 0); }
+                    world.createCollider(col, body);
+                    bodies.set(id, body);
+                };
+
+                return () => {
+                    if (!world) {
+                        if (!initStarted) {
+                            initStarted = true;
+                            RAPIER.init().then(() => { world = new RAPIER.World({ x: 0, y: -GRAVITY, z: 0 }); });
+                        }
+                        return; // WASM not ready yet
+                    }
+
+                    // sync: mirror only bodies not yet in Rapier (excluded by tag),
+                    // then tag them. Iterate tail→head since every row migrates out
+                    // on tagging. Reads use column accessors (robust to the migration;
+                    // this loop only touches genuinely-new bodies, so it's cold).
+                    for (const arch of db.store.queryArchetypes(RIGID, NEW_RIGID)) {
+                        const ids = arch.columns.id, bt = arch.columns.bodyType, cs = arch.columns.colliderShape, mat = arch.columns.material;
+                        const he = arch.columns.halfExtents, pos = arch.columns.position, ori = arch.columns.rotation, lv = arch.columns.linearVelocity, av = arch.columns.angularVelocity;
+                        for (let r = arch.rowCount - 1; r >= 0; r--) {
+                            const id = ids.get(r), bodyType = bt.get(r), shape = cs.get(r), h = he.get(r), p = pos.get(r), o = ori.get(r), v = lv.get(r), w = av.get(r);
+                            if (!colliderReady(id, shape)) continue; // auto-collider not generated yet
+                            ensureBody(id, bodyType, shape, h[0], h[1], h[2], mat.get(r), p[0], p[1], p[2], o, v[0], v[1], v[2], w[0], w[1], w[2]);
+                            // Tag as mirrored. Dynamics also migrate onto the derived prev-pose
+                            // snapshot (the interpolator reads it); kinematic bodies are authored
+                            // each frame, so they render at the live pose with no snapshot — the
+                            // _prevPosition absence is exactly what the kinematic-drive query keys on.
+                            db.store.update(id, BodyType.isDynamic(bodyType) ? { _rapierBody: true, _prevPosition: p, _prevRotation: o } : { _rapierBody: true });
+                        }
+                    }
+                    for (const arch of db.store.queryArchetypes(STATIC, NEW_STATIC)) {
+                        const ids = arch.columns.id, cs = arch.columns.colliderShape, mat = arch.columns.material;
+                        const he = arch.columns.halfExtents, pos = arch.columns.position, ori = arch.columns.rotation;
+                        for (let r = arch.rowCount - 1; r >= 0; r--) {
+                            const id = ids.get(r), shape = cs.get(r), h = he.get(r), p = pos.get(r);
+                            if (!colliderReady(id, shape)) continue; // auto-collider not generated yet
+                            ensureBody(id, "static", shape, h[0], h[1], h[2], mat.get(r), p[0], p[1], p[2], ori.get(r), 0, 0, 0, 0, 0, 0);
+                            db.store.update(id, { _rapierBody: true });
+                        }
+                    }
+
+                    // Mirror new joints once both their bodies exist (tag + exclude;
+                    // tail→head since tagging migrates the row). Anchors are body-local.
+                    for (const arch of db.store.queryArchetypes(JOINT, NEW_JOINT)) {
+                        const ids = arch.columns.id, jt = arch.columns.jointType;
+                        const ba = arch.columns.jointBodyA, bb = arch.columns.jointBodyB;
+                        const aa = arch.columns.jointAnchorA, ab = arch.columns.jointAnchorB, axc = arch.columns.jointAxis;
+                        const lo = arch.columns.jointMinLimit, hi = arch.columns.jointMaxLimit;
+                        for (let r = arch.rowCount - 1; r >= 0; r--) {
+                            const a = bodies.get(ba.get(r)), b = bodies.get(bb.get(r));
+                            if (!a || !b) continue; // a body isn't mirrored yet — retry next frame
+                            const type = jt.get(r), pa = aa.get(r), pb = ab.get(r), ax = axc.get(r), min = lo.get(r), max = hi.get(r);
+                            const A = { x: pa[0], y: pa[1], z: pa[2] }, B = { x: pb[0], y: pb[1], z: pb[2] };
+                            let jd: RAPIER.JointData;
+                            if (type === "fixed") jd = RAPIER.JointData.fixed(A, { x: 0, y: 0, z: 0, w: 1 }, B, { x: 0, y: 0, z: 0, w: 1 });
+                            else if (type === "hinge") { jd = RAPIER.JointData.revolute(A, B, { x: ax[0], y: ax[1], z: ax[2] }); if (min < max) { jd.limitsEnabled = true; jd.limits = [min, max]; } }
+                            // point — and cone: the rapier3d-compat binding has no cone/swing-twist
+                            // limit, so a `cone` joint is approximated as a free spherical (use joltSolver
+                            // for anatomical ragdoll limits; see physics/README.md).
+                            else jd = RAPIER.JointData.spherical(A, B);
+                            world.createImpulseJoint(jd, a, b, true);
+                            db.store.update(ids.get(r), { _rapierJoint: true });
+                        }
+                    }
+
+                    // Step on the fixed clock: 0..N steps of `fixedDt` this frame
+                    // (decoupled from the render rate). On a stepping frame, snapshot
+                    // the pose entering the final step into `_prevPosition`/`_prevRotation`
+                    // first, so the pre-render interpolator can blend prev→current.
+                    const clock = db.store.resources.physicsClock;
+                    const steps = clock.steps;
+                    if (steps === 0) return; // no sim time accrued — leave pose + snapshot intact
+
+                    // Drive kinematic bodies to their authored pose: Rapier moves a
+                    // position-based kinematic toward the target over the step, deriving
+                    // the velocity that pushes dynamics. (Author the pose however you like —
+                    // a system, animation, input — the solver just follows it.)
+                    const toFlip: Entity[] = []; // kinematic bodies whose bodyType became "dynamic" (ragdoll)
+                    for (const arch of db.store.queryArchetypes(KINEMATIC, KINEMATIC_ONLY)) {
+                        const ids = arch.columns.id, bt = arch.columns.bodyType;
+                        const pos = arch.columns.position.getTypedArray(), ori = arch.columns.rotation.getTypedArray();
+                        for (let r = 0; r < arch.rowCount; r++) {
+                            const body = bodies.get(ids.get(r));
+                            if (!body) continue;
+                            if (bt.get(r) === "dynamic") { toFlip.push(ids.get(r)); continue; }
+                            const r3 = r * 3, r4 = r * 4;
+                            body.setNextKinematicTranslation({ x: pos[r3], y: pos[r3 + 1], z: pos[r3 + 2] });
+                            body.setNextKinematicRotation({ x: ori[r4], y: ori[r4 + 1], z: ori[r4 + 2], w: ori[r4 + 3] });
+                        }
+                    }
+                    // Flip kinematic→dynamic (after the loop, since migrating the row moves the
+                    // typed arrays): the engine body becomes dynamic and it gains the prev-pose
+                    // snapshot, so from now on it's simulated + written back like any dynamic body.
+                    for (const id of toFlip) {
+                        const body = bodies.get(id);
+                        if (!body) continue;
+                        body.setBodyType(RAPIER.RigidBodyType.Dynamic, true);
+                        const rec = db.store.read(id) as { position: ArrayLike<number>; rotation: ArrayLike<number> };
+                        db.store.update(id, {
+                            _prevPosition: [rec.position[0], rec.position[1], rec.position[2]],
+                            _prevRotation: [rec.rotation[0], rec.rotation[1], rec.rotation[2], rec.rotation[3]],
+                        });
+                    }
+                    for (const arch of db.store.queryArchetypes(SNAPSHOT)) {
+                        const bt = arch.columns.bodyType;
+                        const pos = arch.columns.position.getTypedArray(), ori = arch.columns.rotation.getTypedArray();
+                        const pp = arch.columns._prevPosition.getTypedArray(), pr = arch.columns._prevRotation.getTypedArray();
+                        for (let r = 0; r < arch.rowCount; r++) {
+                            if (!BodyType.isDynamic(bt.get(r))) continue;
+                            const r3 = r * 3, r4 = r * 4;
+                            pp[r3] = pos[r3]; pp[r3 + 1] = pos[r3 + 1]; pp[r3 + 2] = pos[r3 + 2];
+                            pr[r4] = ori[r4]; pr[r4 + 1] = ori[r4 + 1]; pr[r4 + 2] = ori[r4 + 2]; pr[r4 + 3] = ori[r4 + 3];
+                        }
+                    }
+                    world.timestep = clock.fixedDt;
+                    for (let s = 0; s < steps; s++) world.step();
+
+                    // write the dynamic bodies' new pose + velocity back onto the canonical columns
+                    for (const arch of db.store.queryArchetypes(RIGID)) {
+                        const ids = arch.columns.id, bt = arch.columns.bodyType;
+                        const pos = arch.columns.position.getTypedArray(), ori = arch.columns.rotation.getTypedArray();
+                        const lv = arch.columns.linearVelocity.getTypedArray(), av = arch.columns.angularVelocity.getTypedArray();
+                        for (let r = 0; r < arch.rowCount; r++) {
+                            if (!BodyType.isDynamic(bt.get(r))) continue;
+                            const body = bodies.get(ids.get(r));
+                            if (!body) continue;
+                            // PERF residual: rapier3d-compat returns a fresh {x,y,z}/{x,y,z,w}
+                            // object from each of these getters → ~4 small allocations per
+                            // dynamic body per frame (GC pressure). It scales with the *dynamic*
+                            // count only (small for our target), and the compat binding offers
+                            // no out-param read, so it's left as-is. If dynamic counts ever get
+                            // large, drop to rapier's raw bindings (rawBodies / a flat buffer)
+                            // to read straight into our typed arrays with zero allocation.
+                            const t = body.translation(), rot = body.rotation(), v = body.linvel(), w = body.angvel();
+                            const r3 = r * 3, r4 = r * 4;
+                            pos[r3] = t.x; pos[r3 + 1] = t.y; pos[r3 + 2] = t.z;
+                            ori[r4] = rot.x; ori[r4 + 1] = rot.y; ori[r4 + 2] = rot.z; ori[r4 + 3] = rot.w;
+                            lv[r3] = v.x; lv[r3 + 1] = v.y; lv[r3 + 2] = v.z;
+                            av[r3] = w.x; av[r3 + 1] = w.y; av[r3 + 2] = w.z;
+                        }
+                    }
+                };
+            },
+        },
+    },
+});

package/src/physics/solvers/solver-benchmark.ts

@@ -0,0 +1,172 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+
+/**
+ * Headless benchmark harness for a physics **solver plugin** (anything built on
+ * the `physicsData` seam — `rapierSolver`, `joltSolver`, …). It builds a fixed,
+ * deterministic scene (a floor + a grid of bodies dropped to pile up), then
+ * advances the simulation at a fixed timestep as fast as the CPU allows and
+ * reports the wall-clock cost per frame. No rendering, no rAF, no GPU — so the
+ * numbers reflect solver compute only and are directly comparable across plugins.
+ *
+ * Async because some solvers (Rapier) initialise WASM lazily; the warm-up phase
+ * yields to the event loop so that init + scene settling complete before timing.
+ */
+
+export interface SolverBenchmarkOptions {
+    /** Dynamic bodies dropped into the scene (≈ workload size). Default 256. */
+    bodies?: number;
+    /** Timed frames. Default 300. */
+    frames?: number;
+    /** Warm-up frames before timing (lets async init finish + the pile settle). Default 90. */
+    warmupFrames?: number;
+    /** Fixed timestep per frame (seconds). Default 1/60. */
+    dt?: number;
+    /** Fraction of `bodies` that are spheres (rest are boxes). Default 0.5. */
+    sphereFraction?: number;
+    /** Extra *static* collider boxes laid out as resting scenery. They barely
+     *  cost the engine (nothing moves) but they ARE mirrored once and then scanned
+     *  by a naive per-frame sync — so this isolates the gather/sync overhead, which
+     *  is the realistic "many static, few dynamic" target workload. Default 0. */
+    staticBodies?: number;
+}
+
+export interface SolverBenchmarkResult {
+    bodies: number;
+    frames: number;
+    /** Total wall-clock time of the timed frames (ms). */
+    totalMs: number;
+    /** Mean cost of one frame (ms) — the headline number. */
+    msPerFrame: number;
+    /** Simulation frames per real second (1000 / msPerFrame). */
+    simFps: number;
+    /** Slowest single frame (ms) — surfaces hitches. */
+    maxFrameMs: number;
+    // --- coarse end-state, for cross-solver parity / sanity (not perf) ---
+    avgY: number;      // mean height of dynamic bodies (piled ≈ low, exploded ≈ wild)
+    maxSpeed: number;  // fastest dynamic body (a stable pile is near 0)
+    belowFloor: number; // dynamic bodies that sank below the floor top (should be 0)
+}
+
+interface LooseStore {
+    archetypes: Record<string, { insert(v: unknown): number }>;
+    queryArchetypes(include: readonly string[], opts?: { exclude?: readonly string[] }): Iterable<{
+        rowCount: number;
+        columns: Record<string, { getTypedArray(): { [i: number]: number } }>;
+    }>;
+    resources: Record<string, unknown>;
+}
+interface LooseDb { store: LooseStore; system: { functions: Record<string, () => unknown>; order?: string[][] }; }
+
+const yieldToEventLoop = () => new Promise<void>(r => setTimeout(r, 0));
+
+export async function runSolverBenchmark(solver: Database.Plugin, opts: SolverBenchmarkOptions = {}): Promise<SolverBenchmarkResult> {
+    const bodies = opts.bodies ?? 256;
+    const frames = opts.frames ?? 300;
+    const warmupFrames = opts.warmupFrames ?? 90;
+    const dt = opts.dt ?? 1 / 60;
+    const sphereFraction = opts.sphereFraction ?? 0.5;
+    const staticBodies = opts.staticBodies ?? 0;
+
+    // The solver plugin extends `physicsData`, so the RigidBody / StaticCollider
+    // archetypes and the `frameTime` resource exist on the created database. The
+    // benchmark drives the sim dynamically, so the store is used through a loose
+    // shape (runtime invariant: these members exist on any physicsData solver).
+    const db = Database.create(solver) as unknown as LooseDb;
+
+    buildScene(db, bodies, sphereFraction, staticBodies);
+
+    // Drive one frame: set a fixed dt, then run every system except the rAF/clock
+    // ones (we supply dt ourselves so timing is deterministic and high-rate).
+    const order = db.system.order;
+    const names = order ? order.flat() : Object.keys(db.system.functions);
+    const runNames = names.filter(n => n !== "_frameTime" && n !== "schedulerSystem");
+    const tick = (f: number): void => {
+        db.store.resources.frameTime = { now: f * dt * 1000, dt, elapsed: f * dt };
+        for (const n of runNames) { const fn = db.system.functions[n]; if (fn) fn(); }
+    };
+
+    // Warm-up: yield to the event loop so lazy WASM init (Rapier) completes and
+    // the pile settles into a steady-state contact count before we measure.
+    for (let f = 0; f < warmupFrames; f++) { tick(f); await yieldToEventLoop(); }
+
+    // Timed run: tight synchronous loop — pure solver compute.
+    let maxFrameMs = 0;
+    const t0 = performance.now();
+    for (let f = 0; f < frames; f++) {
+        const a = performance.now();
+        tick(warmupFrames + f);
+        const ms = performance.now() - a;
+        if (ms > maxFrameMs) maxFrameMs = ms;
+    }
+    const totalMs = performance.now() - t0;
+
+    const { avgY, maxSpeed, belowFloor } = sampleState(db);
+    return {
+        bodies, frames,
+        totalMs, msPerFrame: totalMs / frames, simFps: 1000 / (totalMs / frames), maxFrameMs,
+        avgY, maxSpeed, belowFloor,
+    };
+}
+
+/** A thick static floor + `bodies` dynamic bodies in a compact cube grid that
+ *  drops a short distance and piles up — a steady-state contact workload. The
+ *  floor is deliberately thick (a finite box has a far side) and the drop is
+ *  short, so a correct solver never tunnels: end-state avgY/maxV then cleanly
+ *  separate a stable solver from an exploding one. Optional `staticBodies` adds
+ *  resting static scenery to exercise the sync/gather path at scale. */
+function buildScene(db: LooseDb, bodies: number, sphereFraction: number, staticBodies: number): void {
+    db.store.archetypes.StaticCollider.insert({
+        colliderShape: "box", halfExtents: [12, 2, 12], material: 0,
+        position: [0, -2, 0], rotation: [0, 0, 0, 1], // top face at y = 0
+    });
+    // resting static scenery far from the action (negligible engine cost, but it
+    // is mirrored once and then scanned every frame by a naive per-frame sync)
+    if (staticBodies > 0) {
+        const side = Math.ceil(Math.cbrt(staticBodies));
+        let n = 0;
+        for (let x = 0; x < side && n < staticBodies; x++)
+            for (let y = 0; y < side && n < staticBodies; y++)
+                for (let z = 0; z < side && n < staticBodies; z++, n++)
+                    db.store.archetypes.StaticCollider.insert({
+                        colliderShape: "box", halfExtents: [0.4, 0.4, 0.4], material: 0,
+                        position: [100 + x, y, z], rotation: [0, 0, 0, 1],
+                    });
+    }
+    const side = Math.ceil(Math.cbrt(bodies));
+    const gap = 1.5, base = -((side - 1) / 2) * gap; // spaced so the initial drop is non-overlapping
+    let n = 0;
+    for (let y = 0; y < side && n < bodies; y++) {
+        for (let x = 0; x < side && n < bodies; x++) {
+            for (let z = 0; z < side && n < bodies; z++, n++) {
+                const sphere = ((n * 0x9e3779b1) >>> 0) / 4294967296 < sphereFraction;
+                db.store.archetypes.RigidBody.insert({
+                    bodyType: "dynamic",
+                    colliderShape: sphere ? "sphere" : "box",
+                    halfExtents: sphere ? [0.45, 0, 0] : [0.45, 0.45, 0.45],
+                    material: 0,
+                    position: [base + x * gap, 0.6 + y * gap, base + z * gap],
+                    rotation: [0, 0, 0, 1],
+                    linearVelocity: [0, 0, 0],
+                    angularVelocity: [0, 0, 0],
+                });
+            }
+        }
+    }
+}
+
+function sampleState(db: LooseDb): { avgY: number; maxSpeed: number; belowFloor: number } {
+    let count = 0, sumY = 0, maxSpeed = 0, belowFloor = 0;
+    for (const arch of db.store.queryArchetypes(["linearVelocity", "position"])) {
+        const pos = arch.columns.position.getTypedArray(), lv = arch.columns.linearVelocity.getTypedArray();
+        for (let r = 0; r < arch.rowCount; r++, count++) {
+            const r3 = r * 3, y = pos[r3 + 1];
+            sumY += y;
+            if (y < -0.5) belowFloor++; // floor top is y = 0; a resting body sits above it
+            const sp = Math.hypot(lv[r3], lv[r3 + 1], lv[r3 + 2]);
+            if (sp > maxSpeed) maxSpeed = sp;
+        }
+    }
+    return { avgY: count ? sumY / count : 0, maxSpeed, belowFloor };
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES5", "ES2015", "ES2016", "ES2017", "ES2018", "ES2019", "ES2020", "ES2021", "ES2022", "ES2023", "ESNext", "DOM", "DOM.Iterable"],
+    "types": ["@webgpu/types"],
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "stripInternal": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"],
+  "references": []
+}