@aethervtt/shard-physics 0.0.1 → 0.2.0

package/dist/worker/client.js

@@ -0,0 +1,163 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { decodeTrack } from "../track/format.js";
+import { trackCancelled } from "../track/record.js";
+import { createTrackServer } from "./serve.js";
+function inlineWorker(rules) {
+  const listeners = [];
+  const server = createTrackServer((reply) => {
+    queueMicrotask(() => {
+      for (const listener of listeners) listener({ data: reply });
+    });
+  }, rules);
+  return {
+    postMessage: (message) => server.handle(message),
+    addEventListener(type, listener) {
+      if (type === "message") listeners.push(listener);
+    },
+    terminate: () => server.dispose()
+  };
+}
+function crashed(reason) {
+  return new ShardError("physics/worker-crashed", `The track worker crashed: ${reason}`, {
+    hint: "The next recording starts a new worker."
+  });
+}
+function createTrackClient(options) {
+  let worker;
+  let warm;
+  let readyReject;
+  let disposed = false;
+  let spawns = 0;
+  let nextId = 1;
+  const pending = /* @__PURE__ */ new Map();
+  function settle(id) {
+    const p = pending.get(id);
+    if (!p) return void 0;
+    pending.delete(id);
+    p.cleanup();
+    return p;
+  }
+  function rejectAll(err) {
+    for (const id of [...pending.keys()]) settle(id).reject(err);
+  }
+  function crash(reason) {
+    const w = worker;
+    worker = void 0;
+    warm = void 0;
+    const err = crashed(reason);
+    readyReject?.(err);
+    readyReject = void 0;
+    rejectAll(err);
+    w?.terminate();
+  }
+  function onReply(reply) {
+    if (reply.type === "ready") {
+      readyReject = void 0;
+      return;
+    }
+    if (reply.id === null) {
+      crash(reply.type === "error" ? reply.message : "init failed");
+      return;
+    }
+    const p = settle(reply.id);
+    if (!p) return;
+    if (reply.type === "track") {
+      try {
+        p.resolve(decodeTrack(reply.buffer));
+      } catch (err) {
+        p.reject(err);
+      }
+      return;
+    }
+    p.reject(new ShardError(reply.code, reply.message, { hint: reply.hint, path: reply.path }));
+  }
+  function ensure() {
+    if (disposed) {
+      throw new ShardError("physics/track-client-disposed", "The track client was disposed", {
+        hint: "Create another with createTrackClient."
+      });
+    }
+    if (worker) return worker;
+    const w = options.spawn === "inline" ? inlineWorker(options.rules) : options.spawn();
+    spawns++;
+    worker = w;
+    warm = new Promise((resolve, reject) => {
+      readyReject = reject;
+      w.addEventListener("message", (event) => {
+        if (worker !== w) return;
+        const reply = event.data;
+        if (reply.type === "ready") resolve();
+        onReply(reply);
+      });
+    });
+    warm.catch(() => {
+    });
+    const onCrash = (event) => {
+      if (worker !== w) return;
+      const message = event.message;
+      crash(message || (event.type === "messageerror" ? "a message could not be read" : "error"));
+    };
+    w.addEventListener("error", onCrash);
+    w.addEventListener("messageerror", onCrash);
+    w.postMessage({ type: "init" });
+    return w;
+  }
+  return {
+    get disposed() {
+      return disposed;
+    },
+    get spawns() {
+      return spawns;
+    },
+    async ready() {
+      ensure();
+      await warm;
+    },
+    record(scene, recordOptions = {}) {
+      let w;
+      try {
+        w = ensure();
+      } catch (err) {
+        return Promise.reject(err);
+      }
+      const { signal } = recordOptions;
+      if (signal?.aborted) return Promise.reject(trackCancelled());
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          if (!settle(id)) return;
+          if (worker === w) w.postMessage({ type: "cancel", id });
+          reject(trackCancelled());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        pending.set(id, {
+          resolve,
+          reject,
+          cleanup: () => signal?.removeEventListener("abort", onAbort)
+        });
+        w.postMessage({
+          type: "record",
+          id,
+          scene,
+          settle: recordOptions.settle,
+          contacts: recordOptions.contacts
+        });
+      });
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      const w = worker;
+      worker = void 0;
+      warm = void 0;
+      rejectAll(new ShardError("physics/track-cancelled", "The track client was disposed"));
+      if (w) {
+        w.postMessage({ type: "dispose" });
+        w.terminate();
+      }
+    }
+  };
+}
+export {
+  createTrackClient
+};

package/dist/worker/index.d.ts

@@ -0,0 +1,8 @@
+export { createTrackClient, type TrackClient, type TrackClientOptions, type TrackRecordOptions, type TrackWorkerLike, } from './client.js';
+export type { SettleRuleRef, TrackReply, TrackRequest } from './protocol.js';
+export { createTrackServer, type ServeTracksOptions, serveTracks, type TrackScope } from './serve.js';
+/**
+ * The default track worker, bundled by the host's bundler: Vite and webpack both recognize this
+ * `new Worker(new URL(…, import.meta.url))` form and bundle the entry with Rapier inside it.
+ */
+export declare function trackWorker(): Worker;

package/dist/worker/index.js

@@ -0,0 +1,13 @@
+import {
+  createTrackClient
+} from "./client.js";
+import { createTrackServer, serveTracks } from "./serve.js";
+function trackWorker() {
+  return new Worker(new URL("./track-worker.js", import.meta.url), { type: "module" });
+}
+export {
+  createTrackClient,
+  createTrackServer,
+  serveTracks,
+  trackWorker
+};

package/dist/worker/protocol.d.ts

@@ -0,0 +1,38 @@
+import type { TrackContactOptions } from '../track/record.js';
+import type { TrackScene } from '../track/scene.js';
+/** A settle rule the worker registered, and the parameters for this recording. */
+export interface SettleRuleRef {
+    rule: string;
+    params?: unknown;
+}
+export type TrackRequest = {
+    type: 'init';
+} | {
+    type: 'record';
+    id: number;
+    scene: TrackScene;
+    settle?: SettleRuleRef;
+    contacts?: TrackContactOptions;
+} | {
+    type: 'cancel';
+    id: number;
+} | {
+    type: 'dispose';
+};
+export type TrackReply = {
+    type: 'ready';
+    engine: string;
+} | {
+    type: 'track';
+    id: number;
+    buffer: ArrayBuffer;
+}
+/** `id` null: `init` failed. */
+ | {
+    type: 'error';
+    id: number | null;
+    code: string;
+    message: string;
+    hint?: string;
+    path?: string;
+};

package/dist/worker/serve.d.ts

@@ -0,0 +1,34 @@
+import { type SettleRule } from '../track/record.js';
+import type { TrackReply, TrackRequest } from './protocol.js';
+/** The side of a worker that receives requests: a worker's global scope, or a stand-in for one. */
+export interface TrackScope {
+    postMessage(message: TrackReply, transfer?: Transferable[]): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    close?(): void;
+}
+export interface ServeTracksOptions {
+    /** Settle rules by name, besides the built-in `sleep`. */
+    rules?: {
+        [name: string]: SettleRule;
+    };
+    /** Default: the worker's global scope. */
+    scope?: TrackScope;
+}
+/**
+ * Handles track requests one recording at a time, replying through `post`. `serveTracks` binds it
+ * to a worker; the inline client binds it to the calling thread.
+ */
+export declare function createTrackServer(post: (reply: TrackReply, transfer?: Transferable[]) => void, rules?: {
+    [name: string]: SettleRule;
+}): {
+    handle(request: TrackRequest): void;
+    dispose(): void;
+};
+/**
+ * A track worker's entry: records what the client asks for with the settle rules named here (and
+ * `sleep`). A package with its own rules ships its own entry, e.g.
+ * `serveTracks({ rules: { 'dice-settle': diceSettle } })`.
+ */
+export declare function serveTracks(options?: ServeTracksOptions): void;

package/dist/worker/serve.js

@@ -0,0 +1,111 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { loadDeterministic3d } from "../rapier.js";
+import { encodeTrack } from "../track/format.js";
+import { builtinSettleRules, recordTrack, trackCancelled } from "../track/record.js";
+function replyError(id, err) {
+  if (err instanceof ShardError) {
+    return {
+      type: "error",
+      id,
+      code: err.code,
+      message: err.message,
+      hint: err.hint,
+      path: err.path
+    };
+  }
+  return {
+    type: "error",
+    id,
+    code: "physics/track-failed",
+    message: err instanceof Error ? err.message : String(err)
+  };
+}
+function createTrackServer(post, rules) {
+  const allRules = { ...builtinSettleRules, ...rules };
+  const queue = [];
+  let current;
+  let draining = false;
+  let disposed = false;
+  async function run(job) {
+    const abort = new AbortController();
+    current = { id: job.id, abort };
+    try {
+      const ref = job.settle ?? { rule: "sleep" };
+      const rule = allRules[ref.rule];
+      if (!rule) {
+        throw new ShardError("physics/unknown-settle-rule", `No settle rule "${ref.rule}"`, {
+          hint: `This worker has: ${Object.keys(allRules).join(", ")}. Register yours with serveTracks({ rules }).`
+        });
+      }
+      const track = await recordTrack(job.scene, {
+        signal: abort.signal,
+        settle: rule(ref.params),
+        contacts: job.contacts
+      });
+      const buffer = encodeTrack(track);
+      post({ type: "track", id: job.id, buffer }, [buffer]);
+    } catch (err) {
+      post(replyError(job.id, err));
+    } finally {
+      current = void 0;
+    }
+  }
+  async function drain() {
+    draining = true;
+    while (queue.length > 0 && !disposed) await run(queue.shift());
+    draining = false;
+  }
+  function dispose() {
+    disposed = true;
+    queue.length = 0;
+    current?.abort.abort();
+  }
+  return {
+    handle(request) {
+      if (disposed) return;
+      switch (request.type) {
+        case "init":
+          loadDeterministic3d().then(
+            (R) => post({ type: "ready", engine: `rapier3d-deterministic@${R.version()}` }),
+            (err) => post(replyError(null, err))
+          );
+          return;
+        case "record":
+          queue.push(request);
+          if (!draining) void drain();
+          return;
+        case "cancel": {
+          if (current?.id === request.id) {
+            current.abort.abort();
+            return;
+          }
+          const i = queue.findIndex((job) => job.id === request.id);
+          if (i >= 0) {
+            queue.splice(i, 1);
+            post(replyError(request.id, trackCancelled()));
+          }
+          return;
+        }
+        case "dispose":
+          dispose();
+      }
+    },
+    dispose
+  };
+}
+function serveTracks(options = {}) {
+  const scope = options.scope ?? globalThis;
+  const server = createTrackServer(
+    (reply, transfer) => scope.postMessage(reply, transfer),
+    options.rules
+  );
+  scope.addEventListener("message", (event) => {
+    const request = event.data;
+    server.handle(request);
+    if (request.type === "dispose") scope.close?.();
+  });
+}
+export {
+  createTrackServer,
+  serveTracks
+};

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

@@ -0,0 +1 @@
+export {};

package/dist/worker/test-worker.js

@@ -0,0 +1,18 @@
+import { parentPort } from "node:worker_threads";
+import { serveTracks } from "./serve.js";
+const port = parentPort;
+serveTracks({
+  rules: {
+    crash: () => () => {
+      setTimeout(() => {
+        throw new Error("boom");
+      });
+      return "continue";
+    }
+  },
+  scope: {
+    postMessage: (message, transfer) => port.postMessage(message, transfer),
+    addEventListener: (_type, listener) => port.on("message", (data) => listener({ data })),
+    close: () => port.close()
+  }
+});

package/dist/worker/testing.d.ts

@@ -0,0 +1,11 @@
+import type { TrackWorkerLike } from './client.js';
+/**
+ * Runs the TypeScript worker entry at `entry` in a worker thread, through the web Worker interface
+ * the track client expects. Needs `tsx` installed.
+ *
+ * The thread registers tsx itself before it imports the entry. `--import tsx` in `execArgv` is not
+ * enough: tsx registers its hooks in a worker thread only on Node 22.22.3 and later (where it can
+ * tell a worker from Node's own loader thread). On earlier 22.x it skips them, and Node's built-in
+ * type stripping then loads the entry and fails on its extensionless imports.
+ */
+export declare function nodeTrackWorker(entry: URL): TrackWorkerLike;

package/dist/worker/testing.js

@@ -0,0 +1,26 @@
+import { Worker } from "node:worker_threads";
+function nodeTrackWorker(entry) {
+  const tsx = JSON.stringify(import.meta.resolve("tsx/esm/api"));
+  const worker = new Worker(
+    `import(${tsx}).then((tsx) => { tsx.register(); return import(${JSON.stringify(entry.href)}) })`,
+    { eval: true }
+  );
+  const listeners = {
+    message: [],
+    error: [],
+    messageerror: []
+  };
+  const emit = (type, event) => {
+    for (const listener of listeners[type]) listener(event);
+  };
+  worker.on("message", (data) => emit("message", { data }));
+  worker.on("error", (err) => emit("error", { type: "error", message: err.message }));
+  return {
+    postMessage: (message, transfer) => worker.postMessage(message, transfer),
+    addEventListener: (type, listener) => void listeners[type].push(listener),
+    terminate: () => void worker.terminate()
+  };
+}
+export {
+  nodeTrackWorker
+};

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

@@ -0,0 +1 @@
+export {};

package/dist/worker/track-worker.js

@@ -0,0 +1,2 @@
+import { serveTracks } from "./serve.js";
+serveTracks();

package/dist/world.d.ts

@@ -1,16 +1,20 @@
-import { type Entity, ShardError, type World } from '@aethervtt/shard-core';
+import { type AssetRef, type Entity, ShardError, type World } from '@aethervtt/shard-core';
 import type { Mesh } from '@aethervtt/shard-mesh';
 import type RAPIER from '@dimforge/rapier3d-compat';
 import { type CollisionEventData, type PhysicsConfigValue } from './components.js';
-export type Rapier = typeof RAPIER;
+import type { Rapier, RapierVariant } from './rapier.js';
+export { loadRapier, type Rapier, type RapierVariant } from './rapier.js';
 type RWorld = InstanceType<Rapier['World']>;
 type RBody = InstanceType<Rapier['RigidBody']>;
 type RCollider = InstanceType<Rapier['Collider']>;
 type RJoint = InstanceType<Rapier['ImpulseJoint']>;
 /** The physics world, once Rapier has loaded (the plugin's `ready` step). */
 export declare const Physics: import("@aethervtt/shard-core").ResourceDef<PhysicsWorld>;
-/** Loads and initializes Rapier's WASM for a dimension, once per process. */
-export declare function loadRapier(dim: 2 | 3): Promise<Rapier>;
+/**
+ * A loaded mesh by reference, or undefined while it isn't loaded. The plugin passes the renderer's
+ * mesh store (`@aethervtt/shard-physics/render`), so the simulation doesn't import the renderer.
+ */
+export type MeshLookup = (world: World, ref: AssetRef) => Mesh | undefined;
 /** A body the physics world owns, by entity. */
 export interface BodyRecord {
     entity: Entity;
@@ -91,6 +95,10 @@ export interface PhysicsStats {
 export declare class PhysicsWorld {
     readonly R: Rapier;
     readonly dim: 2 | 3;
+    /** The Rapier build this world runs on. */
+    readonly variant: RapierVariant;
+    /** Finds collider meshes; without it, mesh colliders wait for one. */
+    meshes: MeshLookup | undefined;
     readonly raw: RWorld;
     readonly events: InstanceType<Rapier['EventQueue']>;
     readonly bodies: Map<number, BodyRecord>;
@@ -152,7 +160,7 @@ export declare class PhysicsWorld {
     readonly rawVec: unknown | undefined;
     private readonly ray;
     private logged;
-    constructor(R: Rapier, dim: 2 | 3, config: PhysicsConfigValue);
+    constructor(R: Rapier, dim: 2 | 3, config: PhysicsConfigValue, variant?: RapierVariant, meshes?: MeshLookup);
     gravityVector(): {
         x: number;
         y: number;
@@ -243,4 +251,3 @@ export declare class PhysicsWorld {
 }
 /** Angle around Z of a quaternion (2D rotation). */
 export declare function quatToAngle(q: ArrayLike<number>, o?: number): number;
-export {};

package/dist/world.js

@@ -4,7 +4,6 @@ import {
   defineResource,
   ShardError
 } from "@aethervtt/shard-core";
-import { Meshes } from "@aethervtt/shard-render";
 import { LogResource } from "@aethervtt/shard-runtime";
 import { GlobalTransform, GridFramesResource } from "@aethervtt/shard-transform";
 import {
@@ -18,19 +17,10 @@ import {
   Velocity
 } from "./components.js";
 import { createPose, mulQuat, parentOf, poseOf, rotate } from "./pose.js";
+import { loadRapier } from "./rapier.js";
 const Physics = defineResource("physics/World", {
   description: "The Rapier world: raycast, shapeCast, overlapPoint, overlapShape, describe. Present after the physics plugin is ready."
 });
-const modules = {};
-function loadRapier(dim) {
-  modules[dim] ??= (async () => {
-    const mod = dim === 3 ? await import("@dimforge/rapier3d-compat") : await import("@dimforge/rapier2d-compat");
-    const R = mod.default ?? mod;
-    await R.init();
-    return R;
-  })();
-  return modules[dim];
-}
 const CHARACTER_OFFSET = 0.01;
 const createRayHit = () => ({
   entity: -1,
@@ -45,6 +35,10 @@ const KIND_KINEMATIC_POSITION = 2;
 class PhysicsWorld {
   R;
   dim;
+  /** The Rapier build this world runs on. */
+  variant;
+  /** Finds collider meshes; without it, mesh colliders wait for one. */
+  meshes;
   raw;
   events;
   bodies = /* @__PURE__ */ new Map();
@@ -90,9 +84,11 @@ class PhysicsWorld {
   rawVec;
   ray;
   logged = /* @__PURE__ */ new Set();
-  constructor(R, dim, config) {
+  constructor(R, dim, config, variant = "regular", meshes) {
     this.R = R;
     this.dim = dim;
+    this.variant = variant;
+    this.meshes = meshes;
     this.config = config;
     this.raw = new R.World(this.gravityVector());
     this.events = new R.EventQueue(true);
@@ -627,7 +623,7 @@ class PhysicsWorld {
     if (owner !== void 0 && world.has(owner, Mass)) this.fixMass(world, owner);
   }
   meshFor(world, entity, ref) {
-    const mesh = world.tryResource(Meshes)?.get(ref);
+    const mesh = this.meshes?.(world, ref);
     if (mesh) return mesh;
     const server = assetServer(world);
     const entry = server.entry(ref);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-physics",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -8,6 +8,22 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./render": {
+      "types": "./dist/render.d.ts",
+      "default": "./dist/render.js"
+    },
+    "./track": {
+      "types": "./dist/track/index.d.ts",
+      "default": "./dist/track/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker/index.d.ts",
+      "default": "./dist/worker/index.js"
+    },
+    "./worker/testing": {
+      "types": "./dist/worker/testing.d.ts",
+      "default": "./dist/worker/testing.js"
     }
   },
   "files": [
@@ -16,14 +32,16 @@
     "README.md"
   ],
   "dependencies": {
+    "@aethervtt/shard-assets": "0.2.0",
+    "@aethervtt/shard-core": "0.2.0",
+    "@aethervtt/shard-mesh": "0.2.0",
+    "@aethervtt/shard-render": "0.2.0",
+    "@aethervtt/shard-runtime": "0.2.0",
+    "@aethervtt/shard-transform": "0.2.0",
     "@dimforge/rapier2d-compat": "0.20.0",
+    "@dimforge/rapier2d-deterministic-compat": "0.20.0",
     "@dimforge/rapier3d-compat": "0.20.0",
-    "@aethervtt/shard-assets": "0.0.1",
-    "@aethervtt/shard-core": "0.0.1",
-    "@aethervtt/shard-mesh": "0.0.1",
-    "@aethervtt/shard-render": "0.0.1",
-    "@aethervtt/shard-runtime": "0.0.1",
-    "@aethervtt/shard-transform": "0.0.1"
+    "@dimforge/rapier3d-deterministic-compat": "0.20.0"
   },
   "repository": {
     "type": "git",
@@ -35,6 +53,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
   }
 }