@aethervtt/shard-physics 0.0.1 → 0.1.0

package/dist/track/record.js

@@ -0,0 +1,286 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { loadDeterministic3d } from "../rapier.js";
+import { TRACK_VERSION } from "./format.js";
+import {
+  checkTrackScene,
+  sceneHash
+} from "./scene.js";
+const settleWhenAsleep = (view) => {
+  for (let i = 0; i < view.bodyCount; i++) if (view.sleeping[i] === 0) return "continue";
+  return "done";
+};
+const builtinSettleRules = {
+  sleep: () => settleWhenAsleep
+};
+const TRACK_CHUNK_STEPS = 64;
+const TRACK_CHUNK_MS = 4;
+function trackCancelled() {
+  return new ShardError("physics/track-cancelled", "The track recording was cancelled", {
+    hint: "Its signal was aborted or its client disposed: nothing to fix, record again when needed."
+  });
+}
+const host = globalThis;
+let channel;
+const waiting = [];
+function yieldTask() {
+  if (host.setImmediate) return new Promise((resolve) => host.setImmediate(resolve));
+  if (!channel) {
+    channel = new host.MessageChannel();
+    channel.port1.onmessage = () => waiting.shift()?.();
+  }
+  return new Promise((resolve) => {
+    waiting.push(resolve);
+    channel.port2.postMessage(0);
+  });
+}
+const ALL_GROUPS = 4294967295;
+const packGroups = (g) => ((g.layers & 65535) << 16 | g.mask & 65535) >>> 0;
+function colliderDesc(R, c, path) {
+  const D = R.ColliderDesc;
+  let desc;
+  if (c.shape === "ball") desc = D.ball(c.radius);
+  else if (c.shape === "cuboid")
+    desc = D.cuboid(c.halfExtents[0], c.halfExtents[1], c.halfExtents[2]);
+  else desc = D.convexHull(c.points);
+  if (!desc) {
+    throw new ShardError(
+      "physics/track-scene",
+      `${path} has no volume: its convex points all lie in one plane`,
+      { path, hint: "See TrackScene in @aethervtt/shard-physics/track." }
+    );
+  }
+  if (c.translation) desc.setTranslation(c.translation[0], c.translation[1], c.translation[2]);
+  if (c.rotation) {
+    const [x, y, z, w] = c.rotation;
+    desc.setRotation({ x, y, z, w });
+  }
+  desc.setFriction(c.friction);
+  desc.setRestitution(c.restitution);
+  desc.setDensity(c.density);
+  return desc;
+}
+async function recordTrack(scene, options = {}) {
+  const { signal } = options;
+  checkTrackScene(scene);
+  if (signal?.aborted) throw trackCancelled();
+  const R = await loadDeterministic3d();
+  if (signal?.aborted) throw trackCancelled();
+  const settle = options.settle ?? settleWhenAsleep;
+  const n = scene.bodies.length;
+  const maxSteps = scene.maxSteps;
+  const g = scene.gravity;
+  const world = new R.World({ x: g[0], y: g[1], z: g[2] });
+  const events = new R.EventQueue(true);
+  try {
+    world.timestep = scene.step;
+    const groups = /* @__PURE__ */ new Map();
+    const inGroup = /* @__PURE__ */ new Map();
+    for (const [name, group] of Object.entries(scene.groups ?? {})) {
+      groups.set(name, packGroups(group));
+      inGroup.set(name, []);
+    }
+    const addCollider = (c, path, body) => {
+      const desc = colliderDesc(R, c, path);
+      desc.setCollisionGroups(c.group === void 0 ? ALL_GROUPS : groups.get(c.group));
+      if (body && options.contacts) {
+        desc.setActiveEvents(R.ActiveEvents.CONTACT_FORCE_EVENTS);
+        desc.setContactForceEventThreshold(options.contacts.minForce);
+      }
+      const collider = world.createCollider(desc, body);
+      if (c.group !== void 0) inGroup.get(c.group).push(collider);
+      return collider;
+    };
+    scene.fixed.forEach((c, i) => {
+      addCollider(c, `fixed[${i}]`);
+    });
+    const bodies = [];
+    const bodyOf = /* @__PURE__ */ new Map();
+    scene.bodies.forEach((b, i) => {
+      const [x, y, z, w] = b.rotation;
+      const desc = R.RigidBodyDesc.dynamic().setTranslation(b.translation[0], b.translation[1], b.translation[2]).setRotation({ x, y, z, w }).setLinvel(b.linear[0], b.linear[1], b.linear[2]).setAngvel({ x: b.angular[0], y: b.angular[1], z: b.angular[2] }).setCcdEnabled(b.ccd ?? false).setCanSleep(b.canSleep ?? true).setLinearDamping(b.linearDamping ?? 0).setAngularDamping(b.angularDamping ?? 0);
+      const body = world.createRigidBody(desc);
+      bodies.push(body);
+      b.colliders.forEach((c, j) => {
+        bodyOf.set(addCollider(c, `bodies[${i}].colliders[${j}]`, body).handle, i);
+      });
+    });
+    let capacity = Math.min(maxSteps + 1, 256);
+    let positions = new Float32Array(capacity * n * 3);
+    let rotations = new Float32Array(capacity * n * 4);
+    const v3 = { x: 0, y: 0, z: 0 };
+    const q4 = { x: 0, y: 0, z: 0, w: 1 };
+    const writePoses = (s) => {
+      if (s >= capacity) {
+        capacity = Math.min(maxSteps + 1, capacity * 2);
+        const p = new Float32Array(capacity * n * 3);
+        p.set(positions);
+        positions = p;
+        const r = new Float32Array(capacity * n * 4);
+        r.set(rotations);
+        rotations = r;
+      }
+      for (let i = 0; i < n; i++) {
+        const body = bodies[i];
+        const t = body.translation(v3);
+        const r = body.rotation(q4);
+        const o3 = (s * n + i) * 3;
+        const o4 = (s * n + i) * 4;
+        positions[o3] = t.x;
+        positions[o3 + 1] = t.y;
+        positions[o3 + 2] = t.z;
+        rotations[o4] = r.x;
+        rotations[o4 + 1] = r.y;
+        rotations[o4 + 2] = r.z;
+        rotations[o4 + 3] = r.w;
+        const bad = t.x - t.x + (t.y - t.y) + (t.z - t.z);
+        if (bad + (r.x - r.x) + (r.y - r.y) + (r.z - r.z) + (r.w - r.w) !== 0) {
+          throw new ShardError(
+            "physics/track-diverged",
+            `Body "${scene.bodies[i].id}" left finite numbers at step ${s}`,
+            {
+              path: `bodies[${i}]`,
+              hint: "Check its speed, mass and colliders; a smaller step or ccd can help."
+            }
+          );
+        }
+      }
+    };
+    let step = 0;
+    const sleeping = new Uint8Array(n);
+    const view = {
+      get step() {
+        return step;
+      },
+      bodyCount: n,
+      sleeping,
+      pose(body, outPos, outRot) {
+        const o3 = (step * n + body) * 3;
+        const o4 = (step * n + body) * 4;
+        outPos[0] = positions[o3];
+        outPos[1] = positions[o3 + 1];
+        outPos[2] = positions[o3 + 2];
+        outRot[0] = rotations[o4];
+        outRot[1] = rotations[o4 + 1];
+        outRot[2] = rotations[o4 + 2];
+        outRot[3] = rotations[o4 + 3];
+      }
+    };
+    const applyPhase = (phase) => {
+      const changed = /* @__PURE__ */ new Set();
+      for (const [name, group] of Object.entries(phase.groups ?? {})) {
+        if (!groups.has(name)) throw unknownGroup(name, step);
+        groups.set(name, packGroups(group));
+        changed.add(name);
+      }
+      for (const name of phase.disableGroups ?? []) {
+        if (!groups.has(name)) throw unknownGroup(name, step);
+        groups.set(name, 0);
+        changed.add(name);
+      }
+      for (const name of changed) {
+        for (const c of inGroup.get(name)) c.setCollisionGroups(groups.get(name));
+      }
+      for (const d of phase.damping ?? []) {
+        const body = bodies[d.body];
+        if (!body || !Number.isInteger(d.body)) {
+          throw new ShardError(
+            "physics/track-scene",
+            `A settle phase at step ${step} damps body ${d.body}; the track has ${n}`,
+            { path: "bodies" }
+          );
+        }
+        if (d.linear !== void 0) body.setLinearDamping(d.linear);
+        if (d.angular !== void 0) body.setAngularDamping(d.angular);
+      }
+      if (phase.wake) for (const body of bodies) body.wakeUp();
+    };
+    const contacts = options.contacts;
+    const maxContacts = contacts?.max ?? 1024;
+    const dedupe = contacts?.dedupeSteps ?? 3;
+    const lastSeen = /* @__PURE__ */ new Map();
+    const cSteps = [];
+    const cA = [];
+    const cB = [];
+    const cForce = [];
+    const onForce = (e) => {
+      let a = bodyOf.get(e.collider1()) ?? -1;
+      let b = bodyOf.get(e.collider2()) ?? -1;
+      if (a < 0 || b >= 0 && b < a) {
+        const swap = a;
+        a = b;
+        b = swap;
+      }
+      if (a < 0) return;
+      const key = a * 65536 + b + 1;
+      const last = lastSeen.get(key);
+      lastSeen.set(key, step);
+      if (last !== void 0 && step - last <= dedupe || cSteps.length >= maxContacts) return;
+      cSteps.push(step);
+      cA.push(a);
+      cB.push(b);
+      cForce.push(e.totalForceMagnitude());
+    };
+    writePoses(0);
+    let settled = false;
+    let simulationMs = 0;
+    while (!settled && step < maxSteps) {
+      const start = performance.now();
+      for (let k = 0; k < TRACK_CHUNK_STEPS && step < maxSteps; k++) {
+        world.step(events);
+        step++;
+        if (contacts) events.drainContactForceEvents(onForce);
+        writePoses(step);
+        for (let i = 0; i < n; i++) sleeping[i] = bodies[i].isSleeping() ? 1 : 0;
+        const result = settle(view);
+        if (result === "done") {
+          settled = true;
+          break;
+        }
+        if (typeof result === "object") applyPhase(result);
+        if (performance.now() - start >= TRACK_CHUNK_MS) break;
+      }
+      simulationMs += performance.now() - start;
+      if (settled || step >= maxSteps) break;
+      await yieldTask();
+      if (signal?.aborted) throw trackCancelled();
+    }
+    const poses = (step + 1) * n;
+    return {
+      version: TRACK_VERSION,
+      engine: `rapier3d-deterministic@${R.version()}`,
+      sceneHash: sceneHash(scene),
+      step: scene.step,
+      steps: step,
+      bodyCount: n,
+      settled,
+      maxStepsHit: !settled,
+      positions: positions.slice(0, poses * 3),
+      rotations: rotations.slice(0, poses * 4),
+      contacts: {
+        steps: Uint16Array.from(cSteps),
+        a: Int16Array.from(cA),
+        b: Int16Array.from(cB),
+        force: Float32Array.from(cForce)
+      },
+      simulationMs
+    };
+  } finally {
+    world.free();
+    events.free();
+  }
+}
+function unknownGroup(name, step) {
+  return new ShardError(
+    "physics/track-scene",
+    `A settle phase at step ${step} names group "${name}", which isn't in scene.groups`,
+    { path: "groups" }
+  );
+}
+export {
+  TRACK_CHUNK_MS,
+  TRACK_CHUNK_STEPS,
+  builtinSettleRules,
+  recordTrack,
+  settleWhenAsleep,
+  trackCancelled
+};

package/dist/track/scene.d.ts

@@ -0,0 +1,74 @@
+import { type Quat, type Vec3 } from '@aethervtt/shard-core';
+/**
+ * What a track records: fixed colliders, and bodies with their starting poses and velocities. Plain
+ * data, so it crosses a worker boundary and hashes the same everywhere. The caller computes every
+ * number (dice draw theirs from a seeded Rng); the recorder never draws random numbers.
+ */
+export interface TrackScene {
+    version: 1;
+    dim: 3;
+    /** Seconds per step, e.g. 1 / 60. */
+    step: number;
+    /** The longest the track can be, in steps (at most 65535). */
+    maxSteps: number;
+    gravity: Vec3;
+    /** Floor, walls: colliders without a body. */
+    fixed: TrackCollider[];
+    /** Recorded, in this order: body i of the track is `bodies[i]`. */
+    bodies: TrackBody[];
+    /** Collision groups colliders name; a collider without one collides with everything. */
+    groups?: {
+        [name: string]: TrackGroup;
+    };
+}
+export interface TrackGroup {
+    /** Bits of the 16 collision layers this group is in. */
+    layers: number;
+    /** The layers it collides with. Two colliders touch when each one's layers meet the other's mask. */
+    mask: number;
+}
+export interface TrackBody {
+    /** Names the body in errors (`physics/track-diverged`); unique in the scene. */
+    id: string;
+    translation: Vec3;
+    rotation: Quat;
+    linear: Vec3;
+    angular: Vec3;
+    colliders: TrackCollider[];
+    ccd?: boolean;
+    /** Default true. */
+    canSleep?: boolean;
+    linearDamping?: number;
+    angularDamping?: number;
+}
+export interface TrackCollider {
+    shape: 'ball' | 'cuboid' | 'convex';
+    radius?: number;
+    halfExtents?: Vec3;
+    /** Convex hull points, x y z each, already scaled. */
+    points?: Float32Array;
+    /** Offset from the body (default none). Fixed colliders: their place in the world. */
+    translation?: Vec3;
+    rotation?: Quat;
+    friction: number;
+    restitution: number;
+    density: number;
+    /** A key of `TrackScene.groups`. */
+    group?: string;
+}
+export declare const TRACK_SCENE_VERSION = 1;
+/** Contacts store step indices as u16. */
+export declare const MAX_TRACK_STEPS = 65535;
+/** Contacts store body indices as i16. */
+export declare const MAX_TRACK_BODIES = 32767;
+/** Throws `physics/track-scene` naming the first thing wrong with a scene. */
+export declare function checkTrackScene(scene: TrackScene): void;
+/** A scene as JSON can hold it: convex points as plain arrays. */
+export declare function trackSceneToJson(scene: TrackScene): unknown;
+/** A scene from JSON (`trackSceneToJson`, a file): points become Float32Arrays, then it's checked. */
+export declare function trackSceneFromJson(json: unknown): TrackScene;
+/**
+ * The hash of a scene's canonical form: every field in a fixed order, defaults filled in, groups
+ * sorted by name. Two scenes that record the same track hash the same.
+ */
+export declare function sceneHash(scene: TrackScene): number;

package/dist/track/scene.js

@@ -0,0 +1,153 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { Hasher } from "./hash.js";
+const TRACK_SCENE_VERSION = 1;
+const MAX_TRACK_STEPS = 65535;
+const MAX_TRACK_BODIES = 32767;
+function invalid(message, path) {
+  return new ShardError("physics/track-scene", message, {
+    path,
+    hint: "See TrackScene in @aethervtt/shard-physics/track."
+  });
+}
+function finite(v, path) {
+  if (typeof v !== "number" || !Number.isFinite(v))
+    throw invalid(`${path} is not a finite number`, path);
+}
+function vector(v, n, path) {
+  if (!Array.isArray(v) || v.length !== n) throw invalid(`${path} needs ${n} numbers`, path);
+  for (let i = 0; i < n; i++) finite(v[i], `${path}[${i}]`);
+}
+function checkCollider(c, path, groups) {
+  if (c.shape === "ball") {
+    finite(c.radius, `${path}.radius`);
+    if (c.radius <= 0) throw invalid(`${path}.radius must be positive`, `${path}.radius`);
+  } else if (c.shape === "cuboid") {
+    vector(c.halfExtents, 3, `${path}.halfExtents`);
+    if (c.halfExtents.some((h) => h <= 0))
+      throw invalid(`${path}.halfExtents must be positive`, `${path}.halfExtents`);
+  } else if (c.shape === "convex") {
+    const p = c.points;
+    if (!(p instanceof Float32Array) || p.length < 12 || p.length % 3 !== 0)
+      throw invalid(
+        `${path}.points needs 4 or more x y z points in a Float32Array`,
+        `${path}.points`
+      );
+    for (let i = 0; i < p.length; i++) finite(p[i], `${path}.points[${i}]`);
+  } else {
+    throw invalid(
+      `${path}.shape "${String(c.shape)}" isn't ball, cuboid or convex`,
+      `${path}.shape`
+    );
+  }
+  if (c.translation !== void 0) vector(c.translation, 3, `${path}.translation`);
+  if (c.rotation !== void 0) vector(c.rotation, 4, `${path}.rotation`);
+  finite(c.friction, `${path}.friction`);
+  finite(c.restitution, `${path}.restitution`);
+  finite(c.density, `${path}.density`);
+  if (c.group !== void 0 && !groups?.[c.group])
+    throw invalid(`${path}.group "${c.group}" isn't in scene.groups`, `${path}.group`);
+}
+function checkTrackScene(scene) {
+  if (scene.version !== TRACK_SCENE_VERSION)
+    throw invalid(`Track scene version ${scene.version} isn't 1`, "version");
+  if (scene.dim !== 3) throw invalid("Only 3D tracks exist (dim: 3)", "dim");
+  finite(scene.step, "step");
+  if (scene.step <= 0) throw invalid("step must be positive", "step");
+  if (!Number.isInteger(scene.maxSteps) || scene.maxSteps < 1 || scene.maxSteps > MAX_TRACK_STEPS)
+    throw invalid(`maxSteps must be an integer from 1 to ${MAX_TRACK_STEPS}`, "maxSteps");
+  vector(scene.gravity, 3, "gravity");
+  for (const [name, g] of Object.entries(scene.groups ?? {})) {
+    for (const key of ["layers", "mask"]) {
+      const v = g[key];
+      if (!Number.isInteger(v) || v < 0 || v > 65535)
+        throw invalid(`groups.${name}.${key} must be a 16-bit mask`, `groups.${name}.${key}`);
+    }
+  }
+  scene.fixed.forEach((c, i) => {
+    checkCollider(c, `fixed[${i}]`, scene.groups);
+  });
+  if (scene.bodies.length > MAX_TRACK_BODIES)
+    throw invalid(`A track holds at most ${MAX_TRACK_BODIES} bodies`, "bodies");
+  const ids = /* @__PURE__ */ new Set();
+  scene.bodies.forEach((b, i) => {
+    const path = `bodies[${i}]`;
+    if (typeof b.id !== "string" || ids.has(b.id))
+      throw invalid(`${path}.id must be a string unique in the scene`, `${path}.id`);
+    ids.add(b.id);
+    vector(b.translation, 3, `${path}.translation`);
+    vector(b.rotation, 4, `${path}.rotation`);
+    vector(b.linear, 3, `${path}.linear`);
+    vector(b.angular, 3, `${path}.angular`);
+    if (b.linearDamping !== void 0) finite(b.linearDamping, `${path}.linearDamping`);
+    if (b.angularDamping !== void 0) finite(b.angularDamping, `${path}.angularDamping`);
+    if (b.colliders.length === 0) throw invalid(`${path} has no colliders`, `${path}.colliders`);
+    b.colliders.forEach((c, j) => {
+      checkCollider(c, `${path}.colliders[${j}]`, scene.groups);
+    });
+  });
+}
+function trackSceneToJson(scene) {
+  const collider = (c) => c.points ? { ...c, points: Array.from(c.points) } : c;
+  return {
+    ...scene,
+    fixed: scene.fixed.map(collider),
+    bodies: scene.bodies.map((b) => ({ ...b, colliders: b.colliders.map(collider) }))
+  };
+}
+function trackSceneFromJson(json) {
+  if (typeof json !== "object" || json === null || !Array.isArray(json.bodies)) {
+    throw invalid("A track scene is an object with fixed and bodies", "");
+  }
+  const s = json;
+  const collider = (c) => Array.isArray(c.points) ? { ...c, points: Float32Array.from(c.points) } : c;
+  const scene = {
+    ...s,
+    fixed: (s.fixed ?? []).map(collider),
+    bodies: s.bodies.map((b) => ({ ...b, colliders: (b.colliders ?? []).map(collider) }))
+  };
+  checkTrackScene(scene);
+  return scene;
+}
+function hashCollider(h, c) {
+  h.str(c.shape).f64(c.radius ?? 0);
+  const he = c.halfExtents ?? [0, 0, 0];
+  h.f64(he[0]).f64(he[1]).f64(he[2]);
+  h.array(c.points ?? new Float32Array(0));
+  const t = c.translation ?? [0, 0, 0];
+  const r = c.rotation ?? [0, 0, 0, 1];
+  h.f64(t[0]).f64(t[1]).f64(t[2]);
+  h.f64(r[0]).f64(r[1]).f64(r[2]).f64(r[3]);
+  h.f64(c.friction).f64(c.restitution).f64(c.density).str(c.group ?? "");
+}
+function sceneHash(scene) {
+  const h = new Hasher();
+  h.u32(scene.version).u32(scene.dim).f64(scene.step).u32(scene.maxSteps);
+  h.f64(scene.gravity[0]).f64(scene.gravity[1]).f64(scene.gravity[2]);
+  const groups = Object.keys(scene.groups ?? {}).sort();
+  h.u32(groups.length);
+  for (const name of groups) {
+    const g = scene.groups[name];
+    h.str(name).u32(g.layers).u32(g.mask);
+  }
+  h.u32(scene.fixed.length);
+  for (const c of scene.fixed) hashCollider(h, c);
+  h.u32(scene.bodies.length);
+  for (const b of scene.bodies) {
+    h.str(b.id);
+    for (const v of [b.translation, b.rotation, b.linear, b.angular]) for (const x of v) h.f64(x);
+    h.bool(b.ccd ?? false).bool(b.canSleep ?? true);
+    h.f64(b.linearDamping ?? 0).f64(b.angularDamping ?? 0);
+    h.u32(b.colliders.length);
+    for (const c of b.colliders) hashCollider(h, c);
+  }
+  return h.digest();
+}
+export {
+  MAX_TRACK_BODIES,
+  MAX_TRACK_STEPS,
+  TRACK_SCENE_VERSION,
+  checkTrackScene,
+  sceneHash,
+  trackSceneFromJson,
+  trackSceneToJson
+};

package/dist/track/test-scenes.d.ts

@@ -0,0 +1,6 @@
+import type { TrackScene } from './scene.js';
+export declare const CUBE_POINTS: Float32Array<ArrayBufferLike>;
+export declare const OCTAHEDRON_POINTS: Float32Array<ArrayBufferLike>;
+export declare const ICOSAHEDRON_POINTS: Float32Array<ArrayBufferLike>;
+/** `count` convex dice thrown from the tray's right side, velocities and spins from `seed`. */
+export declare function trayScene(count: number, seed: number, maxSteps?: number): TrackScene;

package/dist/track/test-scenes.js

@@ -0,0 +1,113 @@
+import { quat, Rng } from "@aethervtt/shard-core";
+const PHI = (1 + Math.sqrt(5)) / 2;
+function hull(points, radius) {
+  const out = new Float32Array(points.length * 3);
+  points.forEach((p, i) => {
+    const len = Math.sqrt(p[0] * p[0] + p[1] * p[1] + p[2] * p[2]);
+    for (let k = 0; k < 3; k++) out[i * 3 + k] = p[k] / len * radius;
+  });
+  return out;
+}
+const signs = [-1, 1];
+const CUBE_POINTS = hull(
+  signs.flatMap((x) => signs.flatMap((y) => signs.map((z) => [x, y, z]))),
+  0.52
+);
+const OCTAHEDRON_POINTS = hull(
+  [
+    [1, 0, 0],
+    [-1, 0, 0],
+    [0, 1, 0],
+    [0, -1, 0],
+    [0, 0, 1],
+    [0, 0, -1]
+  ],
+  0.42
+);
+const ICOSAHEDRON_POINTS = hull(
+  signs.flatMap(
+    (a) => signs.flatMap((b) => [
+      [0, a, b * PHI],
+      [a, b * PHI, 0],
+      [b * PHI, 0, a]
+    ])
+  ),
+  0.4
+);
+const SHAPES = [CUBE_POINTS, OCTAHEDRON_POINTS, ICOSAHEDRON_POINTS];
+function wall(x, z, hx, hz) {
+  return {
+    shape: "cuboid",
+    halfExtents: [hx, 2, hz],
+    translation: [x, 2, z],
+    friction: 0.3,
+    restitution: 0.4,
+    density: 1,
+    group: "walls"
+  };
+}
+function trayScene(count, seed, maxSteps = 480) {
+  const rng = new Rng(seed);
+  const bodies = [];
+  for (let i = 0; i < count; i++) {
+    const rotation = quat.fromEuler(
+      [0, 0, 0, 1],
+      rng.range(0, 360),
+      rng.range(0, 360),
+      rng.range(0, 360)
+    );
+    bodies.push({
+      id: `die-${i}`,
+      // A grid, so no two start inside each other.
+      translation: [1 + i % 4 * 1.1, 1.5 + Math.floor(i / 16) * 1.1, (i >> 2) % 4 * 1.1 - 1.6],
+      rotation,
+      linear: [rng.range(-7, -4), rng.range(1, 3), rng.range(-2, 2)],
+      angular: [rng.range(-15, 15), rng.range(-15, 15), rng.range(-15, 15)],
+      colliders: [
+        {
+          shape: "convex",
+          points: SHAPES[i % SHAPES.length],
+          friction: 0.6,
+          restitution: 0.3,
+          density: 1,
+          group: "dice"
+        }
+      ],
+      ccd: true
+    });
+  }
+  return {
+    version: 1,
+    dim: 3,
+    step: 1 / 60,
+    maxSteps,
+    gravity: [0, -9.81, 0],
+    groups: {
+      dice: { layers: 1, mask: 1 | 2 | 4 },
+      walls: { layers: 2, mask: 1 },
+      floor: { layers: 4, mask: 1 }
+    },
+    fixed: [
+      {
+        shape: "cuboid",
+        halfExtents: [8, 0.5, 8],
+        translation: [0, -0.5, 0],
+        friction: 0.6,
+        restitution: 0.3,
+        density: 1,
+        group: "floor"
+      },
+      wall(0, -4, 6, 0.2),
+      wall(0, 3, 6, 0.2),
+      wall(-5.5, 0, 0.2, 5),
+      wall(5.5, 0, 0.2, 5)
+    ],
+    bodies
+  };
+}
+export {
+  CUBE_POINTS,
+  ICOSAHEDRON_POINTS,
+  OCTAHEDRON_POINTS,
+  trayScene
+};

package/dist/worker/client.d.ts

@@ -0,0 +1,44 @@
+import { type Track } from '../track/format.js';
+import { type SettleRule, type TrackContactOptions } from '../track/record.js';
+import type { TrackScene } from '../track/scene.js';
+import type { SettleRuleRef, TrackRequest } from './protocol.js';
+/** What the client needs of a worker. A DOM `Worker` is one; Node's `worker_threads` needs an adapter. */
+export interface TrackWorkerLike {
+    postMessage(message: TrackRequest, transfer?: Transferable[]): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    addEventListener(type: 'error' | 'messageerror', listener: (event: Event) => void): void;
+    terminate(): void;
+}
+export interface TrackClientOptions {
+    /**
+     * Makes the worker: `trackWorker` from this module, a host's own entry (a package with its own
+     * settle rules), or `'inline'` to record on the calling thread (Node, tests).
+     */
+    spawn: (() => TrackWorkerLike) | 'inline';
+    /** With `'inline'`: settle rules besides `sleep`. A worker gets its rules from its entry. */
+    rules?: {
+        [name: string]: SettleRule;
+    };
+}
+export interface TrackRecordOptions {
+    /** Aborting it rejects at once with `physics/track-cancelled`, and stops the worker's recording. */
+    signal?: AbortSignal;
+    /** A rule the worker registered, and its parameters (default `sleep`). */
+    settle?: SettleRuleRef;
+    contacts?: TrackContactOptions;
+}
+export interface TrackClient {
+    /** Starts the worker and loads Rapier's WASM. Call it early to have it warm for the first roll. */
+    ready(): Promise<void>;
+    record(scene: TrackScene, options?: TrackRecordOptions): Promise<Track>;
+    /** Stops the worker; pending recordings reject with `physics/track-cancelled`. */
+    dispose(): void;
+    readonly disposed: boolean;
+    /** Workers spawned so far (a crash respawns on the next call). */
+    readonly spawns: number;
+}
+/**
+ * Records tracks off the main thread. One worker, started on first use; a crash rejects what's
+ * pending with `physics/worker-crashed`, and the next call starts another.
+ */
+export declare function createTrackClient(options: TrackClientOptions): TrackClient;