@aethervtt/shard-physics 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { characterSystem } from './character.js';
 export { BODY_KINDS, type BodyKind, CharacterController, CharacterGroundEvent, type CharacterGroundEventData, CharacterIntent, CharacterState, Collider, CollisionEvent, type CollisionEventData, ContactForceEvent, type ContactForceEventData, ExternalForce, ExternalImpulse, GravitySource, JOINT_KINDS, Joint, Mass, PhysicsConfig, type PhysicsConfigValue, PhysicsParked, PhysicsRange, type PhysicsRangeValue, RigidBody, SHAPES, type Shape, Velocity, } from './components.js';
 export { physicsMethods } from './methods.js';
-export { Physics, PhysicsSystems, physics, physics2dPlugin, physics3dPlugin } from './plugin.js';
-export { type BodyRecord, CHARACTER_OFFSET, type CharacterRecord, createRayHit, loadRapier, type PhysicsStats, PhysicsWorld, type QueryOptions, type QueryShape, type RayHit, } from './world.js';
+export { Physics, type PhysicsPluginOptions, PhysicsSystems, physics, physics2dPlugin, physics3dPlugin, } from './plugin.js';
+export { type LoadRapierOptions, loadRapier, type Rapier, type RapierVariant } from './rapier.js';
+export { type BodyRecord, CHARACTER_OFFSET, type CharacterRecord, createRayHit, type MeshLookup, type PhysicsStats, PhysicsWorld, type QueryOptions, type QueryShape, type RayHit, } from './world.js';

package/dist/index.js

@@ -22,11 +22,17 @@ import {
   Velocity
 } from "./components.js";
 import { physicsMethods } from "./methods.js";
-import { Physics, PhysicsSystems, physics, physics2dPlugin, physics3dPlugin } from "./plugin.js";
+import {
+  Physics,
+  PhysicsSystems,
+  physics,
+  physics2dPlugin,
+  physics3dPlugin
+} from "./plugin.js";
+import { loadRapier } from "./rapier.js";
 import {
   CHARACTER_OFFSET,
   createRayHit,
-  loadRapier,
   PhysicsWorld
 } from "./world.js";
 export {

package/dist/methods.js

@@ -98,12 +98,13 @@ const physicsMethods = [
   },
   {
     name: "physics.describe",
-    description: "Physics state: dimension, gravity, bodies by kind and how many sleep, colliders by shape, joints, contact pairs, colliders waiting for a mesh, bodies parked out of range (large worlds) and the range, the last step time, and every character controller with its state (grounded, ground, velocity, up).",
+    description: "Physics state: dimension, Rapier variant (regular or deterministic), gravity, bodies by kind and how many sleep, colliders by shape, joints, contact pairs, colliders waiting for a mesh, bodies parked out of range (large worlds) and the range, the last step time, and every character controller with its state (grounded, ground, velocity, up).",
     params: defineSchema("physics/DescribeParams", {}),
     handler: ({ world }) => {
       const physics = ready(world);
       return {
         dimension: physics.dim,
+        variant: physics.variant,
         gravity: physics.config.gravity,
         interpolate: physics.config.interpolate,
         paused: physics.config.paused,

package/dist/plugin.d.ts

@@ -6,8 +6,14 @@ export { Physics };
 export declare const PhysicsSystems: import("@aethervtt/shard-core").SystemSetDef;
 /** The physics world, or `physics/not-ready` before the plugin's `ready` step. */
 export declare function physics(world: World): PhysicsWorld;
+export interface PhysicsPluginOptions {
+    /**
+     * Run on Rapier's deterministic build: the same results on every machine and browser, at some
+     * cost in speed (0053). Default false.
+     */
+    deterministic?: boolean;
+}
 /** 3D rigid bodies, colliders, joints, and scene queries (Rapier). */
-export declare const physics3dPlugin: Plugin;
+export declare function physics3dPlugin(options?: PhysicsPluginOptions): Plugin;
 /** 2D rigid bodies, colliders, joints, and scene queries in the XY plane (Rapier 2D). */
-export declare const physics2dPlugin: Plugin;
-export declare const collidersOverlay: import("@aethervtt/shard-render").OverlayDef;
+export declare function physics2dPlugin(options?: PhysicsPluginOptions): Plugin;

package/dist/plugin.js

@@ -9,8 +9,7 @@ import {
   PostUpdate,
   ShardError
 } from "@aethervtt/shard-core";
-import { defineOverlay } from "@aethervtt/shard-render";
-import { FixedTime } from "@aethervtt/shard-runtime";
+import { FixedTime, FrameDemand } from "@aethervtt/shard-runtime";
 import {
   GlobalTransform,
   GridCell,
@@ -23,7 +22,6 @@ import { characterSystem } from "./character.js";
 import * as componentsModule from "./components.js";
 import {
   CharacterController,
-  CharacterState,
   Collider,
   CollisionEvent,
   ContactForceEvent,
@@ -39,8 +37,11 @@ import {
 import { createGravitySources, gatherGravitySources, sampleGravity } from "./gravity.js";
 import { physicsMethods } from "./methods.js";
 import * as pluginModule from "./plugin.js";
-import { isGrid, parentOf, rotate, worldToLocal } from "./pose.js";
-import { loadRapier, Physics, PhysicsWorld } from "./world.js";
+import { isGrid, parentOf, worldToLocal } from "./pose.js";
+import { loadRapier } from "./rapier.js";
+import * as renderModule from "./render.js";
+import { rendererMeshes } from "./render.js";
+import { Physics, PhysicsWorld } from "./world.js";
 const PhysicsSystems = defineSystemSet("physics/PhysicsSystems");
 function physics(world) {
   const p = world.tryResource(Physics);
@@ -376,6 +377,8 @@ const syncOut = defineSystem({
     visit: void 0,
     world,
     tick: 0,
+    /** Awake bodies sync-out wrote this step: while any are, on-demand apps keep rendering. */
+    awake: 0,
     pos: new Float64Array(3),
     rot: new Float64Array(4),
     rootIdentity: true,
@@ -400,6 +403,7 @@ const syncOut = defineSystem({
     s.visit ??= (handle) => {
       const record = p.bodyByHandle.get(handle);
       if (!record || record.kind === KIND_FIXED) return;
+      s.awake++;
       const o = record.slot * 7;
       const curr = p.curr;
       for (let k = 0; k < 7; k++) p.prev[o + k] = curr[o + k];
@@ -450,7 +454,9 @@ const syncOut = defineSystem({
         c.velTicks[row] = s.tick;
       }
     };
+    s.awake = 0;
     p.raw.islands.forEachActiveRigidBodyHandle(s.visit);
+    world.tryResource(FrameDemand)?.set("physics", s.awake > 0);
   }
 });
 const interpolate = defineSystem({
@@ -552,10 +558,11 @@ function observe(world) {
     get()?.shiftOrigin(data.offset[0], data.offset[1], data.offset[2], onCollision);
   });
 }
-function physicsPlugin(dim) {
+function physicsPlugin(dim, options) {
+  const deterministic = options?.deterministic === true;
   return {
     name: dim === 3 ? "physics3d" : "physics2d",
-    provides: [componentsModule, pluginModule],
+    provides: [componentsModule, pluginModule, renderModule],
     dependencies: ["core/transform"],
     build(app) {
       const other = dimensionOf.get(app.world);
@@ -585,268 +592,26 @@ function physicsPlugin(dim) {
       app.addMethod(...physicsMethods);
     },
     async ready(app) {
-      const R = await loadRapier(dim);
-      app.world.insertResource(Physics, new PhysicsWorld(R, dim, app.world.resource(PhysicsConfig)));
+      const R = await loadRapier(dim, { deterministic });
+      const config = app.world.resource(PhysicsConfig);
+      const variant = deterministic ? "deterministic" : "regular";
+      app.world.insertResource(Physics, new PhysicsWorld(R, dim, config, variant, rendererMeshes));
+    },
+    dispose(app) {
+      app.world.tryResource(Physics)?.free();
+      app.world.removeResource(Physics);
     }
   };
 }
-const physics3dPlugin = physicsPlugin(3);
-const physics2dPlugin = physicsPlugin(2);
-const COLORS = [
-  [1, 0.55, 0.2, 1],
-  // dynamic
-  [0.55, 0.55, 0.6, 1],
-  // fixed
-  [0.3, 0.8, 1, 1],
-  // kinematic
-  [0.3, 0.8, 1, 1]
-];
-const SLEEPING = [0.5, 0.35, 0.2, 1];
-const SENSOR = [0.3, 1, 0.4, 1];
-const CONTACT = [1, 0.2, 0.3, 1];
-const UP = [1, 0.9, 0.2, 1];
-const pa = new Float64Array(3);
-const pb = new Float64Array(3);
-const q = new Float64Array(4);
-const center = new Float64Array(3);
-const collidersOverlay = defineOverlay({
-  name: "colliders",
-  description: "Physics collider outlines, colored by body kind (sleeping dimmed, sensors green, characters cyan with their up in yellow), and contact normals.",
-  draw(world, g, passes) {
-    const p = world.tryResource(Physics);
-    if (!p) return;
-    for (const [entity, collider] of p.colliders) {
-      if (!passes(entity)) continue;
-      const owner = p.colliderOwner.get(entity);
-      const record = owner === void 0 ? void 0 : p.bodies.get(owner);
-      const color = collider.isSensor() ? SENSOR : record?.body.isSleeping() ? SLEEPING : COLORS[record?.kind ?? KIND_FIXED];
-      const t = collider.translation(p.v3);
-      center[0] = t.x;
-      center[1] = t.y;
-      center[2] = p.dim === 3 ? t.z : 0;
-      if (p.dim === 3) {
-        const r = collider.rotation(p.q4);
-        q[0] = r.x;
-        q[1] = r.y;
-        q[2] = r.z;
-        q[3] = r.w;
-      } else {
-        const angle = collider.rotation();
-        q[0] = 0;
-        q[1] = 0;
-        q[2] = Math.sin(angle / 2);
-        q[3] = Math.cos(angle / 2);
-      }
-      drawCollider(p, g, collider, p.colliderShape.get(entity), color);
-    }
-    for (const [entity, c] of p.characters) {
-      if (!passes(entity) || !world.has(entity, CharacterState)) continue;
-      const up = world.get(entity, CharacterState).up;
-      const t = c.collider.translation(p.v3);
-      const tall = p.colliderShape.get(entity) === "capsule" ? c.collider.halfHeight() : 0;
-      const reach = c.collider.radius() + tall + 0.5;
-      pa[0] = t.x;
-      pa[1] = t.y;
-      pa[2] = p.dim === 3 ? t.z : 0;
-      pb[0] = pa[0] + up[0] * reach;
-      pb[1] = pa[1] + up[1] * reach;
-      pb[2] = pa[2] + up[2] * reach;
-      g.line(pa, pb, UP);
-    }
-    contactBudget = MAX_CONTACT_PAIRS;
-    for (let i = 0; i < p.list.length && contactBudget > 0; i++) {
-      const record = p.list[i];
-      if (record.kind !== KIND_DYNAMIC || record.body.isSleeping()) continue;
-      const n = record.body.numColliders();
-      for (let c = 0; c < n; c++) drawContacts(p, g, record.body.collider(c));
-    }
-  }
-});
-const MAX_CONTACT_PAIRS = 1e3;
-let contactBudget = 0;
-function visitedFromOtherSide(other) {
-  const body = other.parent();
-  return body?.isDynamic() === true && !body.isSleeping();
-}
-function drawContacts(p, g, collider) {
-  p.raw.contactPairsWith(collider, (other) => {
-    if (contactBudget <= 0) return;
-    if (other.handle < collider.handle && visitedFromOtherSide(other)) return;
-    contactBudget--;
-    p.raw.contactPair(collider, other, (manifold) => {
-      const count = manifold.numSolverContacts();
-      if (count === 0) return;
-      const n = manifold.normal();
-      for (let i = 0; i < count; i++) {
-        const point = manifold.solverContactPoint(i);
-        if (!point) continue;
-        pa[0] = point.x;
-        pa[1] = point.y;
-        pa[2] = p.dim === 3 ? point.z : 0;
-        pb[0] = pa[0] + n.x * 0.25;
-        pb[1] = pa[1] + n.y * 0.25;
-        pb[2] = pa[2] + (p.dim === 3 ? n.z : 0) * 0.25;
-        g.line(pa, pb, CONTACT);
-      }
-    });
-  });
-}
-function local(out, x, y, z) {
-  rotate(out, 0, q, 0, x, y, z);
-  out[0] = out[0] + center[0];
-  out[1] = out[1] + center[1];
-  out[2] = out[2] + center[2];
-  return out;
-}
-const SEGMENTS = 24;
-const UNIT = (() => {
-  const out = new Float64Array((SEGMENTS + 1) * 2);
-  for (let i = 0; i <= SEGMENTS; i++) {
-    const t = i / SEGMENTS * Math.PI * 2;
-    out[i * 2] = Math.cos(t);
-    out[i * 2 + 1] = Math.sin(t);
-  }
-  return out;
-})();
-function localCircle(g, axis, r, dy, color) {
-  for (let i = 0; i <= SEGMENTS; i++) {
-    const u = UNIT[i * 2] * r;
-    const v = UNIT[i * 2 + 1] * r;
-    if (axis === 0) local(pb, 0, u + dy, v);
-    else if (axis === 1) local(pb, u, dy, v);
-    else local(pb, u, v + dy, 0);
-    if (i > 0) g.line(pa, pb, color);
-    pa[0] = pb[0];
-    pa[1] = pb[1];
-    pa[2] = pb[2];
-  }
-}
-function drawCollider(p, g, collider, shape, color) {
-  const is2d = p.dim === 2;
-  switch (shape) {
-    case "ball": {
-      const r = collider.radius();
-      localCircle(g, 2, r, 0, color);
-      if (!is2d) {
-        localCircle(g, 0, r, 0, color);
-        localCircle(g, 1, r, 0, color);
-      }
-      return;
-    }
-    case "cuboid": {
-      const he = collider.halfExtents();
-      const hz = is2d ? 0 : he.z;
-      const size = [he.x * 2, he.y * 2, hz * 2];
-      g.box(center, size, q, color);
-      return;
-    }
-    case "capsule":
-    case "cylinder":
-    case "cone": {
-      const r = collider.radius();
-      const h = collider.halfHeight();
-      if (is2d) {
-        local(pa, -r, -h, 0);
-        local(pb, -r, h, 0);
-        g.line(pa, pb, color);
-        local(pa, r, -h, 0);
-        local(pb, r, h, 0);
-        g.line(pa, pb, color);
-        localCircle(g, 2, r, h, color);
-        localCircle(g, 2, r, -h, color);
-        return;
-      }
-      const top = shape === "cone" ? 0 : r;
-      localCircle(g, 1, r, -h, color);
-      if (top > 0) localCircle(g, 1, top, h, color);
-      for (let k = 0; k < 4; k++) {
-        const a = k / 4 * Math.PI * 2;
-        local(pa, Math.cos(a) * r, -h, Math.sin(a) * r);
-        local(pb, Math.cos(a) * top, h, Math.sin(a) * top);
-        g.line(pa, pb, color);
-      }
-      if (shape === "capsule") {
-        localCircle(g, 0, r, h, color);
-        localCircle(g, 0, r, -h, color);
-        localCircle(g, 2, r, h, color);
-        localCircle(g, 2, r, -h, color);
-      }
-      return;
-    }
-    case "heightfield":
-      drawHeightfield(p, g, collider, color);
-      return;
-    default: {
-      const vertices = collider.vertices?.();
-      const indices = collider.indices?.();
-      if (!vertices || vertices.length === 0) return;
-      const d = p.dim;
-      const edge = (i, j) => {
-        local(pa, vertices[i * d], vertices[i * d + 1], d === 3 ? vertices[i * d + 2] : 0);
-        local(pb, vertices[j * d], vertices[j * d + 1], d === 3 ? vertices[j * d + 2] : 0);
-        g.line(pa, pb, color);
-      };
-      if (indices && indices.length > 0) {
-        const stride = shape === "polyline" || is2d ? 2 : 3;
-        const limit = Math.min(indices.length, 3e4);
-        for (let i = 0; i + stride - 1 < limit; i += stride) {
-          for (let k = 0; k < stride; k++) {
-            if (stride === 2 && k === 1) break;
-            edge(indices[i + k], indices[i + (k + 1) % stride]);
-          }
-        }
-      } else {
-        const n = vertices.length / d;
-        for (let i = 0; i + 1 < n; i++) edge(i, i + 1);
-        if (shape === "convex" && n > 2) edge(n - 1, 0);
-      }
-    }
-  }
+function physics3dPlugin(options) {
+  return physicsPlugin(3, options);
 }
-function drawHeightfield(p, g, collider, color) {
-  const hf = collider;
-  const heights = hf.heightfieldHeights();
-  const scale = hf.heightfieldScale();
-  if (p.dim === 2) {
-    const n = heights.length;
-    for (let i = 0; i < n; i++) {
-      local(pb, (i / (n - 1) - 0.5) * scale.x, heights[i] * scale.y, 0);
-      if (i > 0) g.line(pa, pb, color);
-      pa[0] = pb[0];
-      pa[1] = pb[1];
-      pa[2] = pb[2];
-    }
-    return;
-  }
-  const rows = hf.heightfieldNRows() + 1;
-  const cols = hf.heightfieldNCols() + 1;
-  const sz = scale.z ?? 1;
-  const at = (out, r, c) => local(
-    out,
-    (c / (cols - 1) - 0.5) * scale.x,
-    heights[c * rows + r] * scale.y,
-    (r / (rows - 1) - 0.5) * sz
-  );
-  const step2 = Math.max(1, Math.ceil(Math.max(rows, cols) / 64));
-  for (let r = 0; r < rows; r += step2) {
-    for (let c = 0; c + step2 < cols; c += step2) {
-      at(pa, r, c);
-      at(pb, r, c + step2);
-      g.line(pa, pb, color);
-    }
-  }
-  for (let c = 0; c < cols; c += step2) {
-    for (let r = 0; r + step2 < rows; r += step2) {
-      at(pa, r, c);
-      at(pb, r + step2, c);
-      g.line(pa, pb, color);
-    }
-  }
+function physics2dPlugin(options) {
+  return physicsPlugin(2, options);
 }
 export {
   Physics,
   PhysicsSystems,
-  collidersOverlay,
   physics,
   physics2dPlugin,
   physics3dPlugin

package/dist/rapier.d.ts

@@ -0,0 +1,22 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+export type Rapier = typeof RAPIER;
+/**
+ * Which Rapier build: `regular` (fastest, deterministic only on one build and platform) or
+ * `deterministic` (the same 0.20.0 API, with results that don't depend on the machine).
+ */
+export type RapierVariant = 'regular' | 'deterministic';
+export interface LoadRapierOptions {
+    /** Load the deterministic build (default false). */
+    deterministic?: boolean;
+}
+/**
+ * Loads and initializes Rapier's WASM for a dimension and variant, once per process. The variants
+ * are separate modules, so a page can run both (the game on the regular build, a dice worker on
+ * the deterministic one).
+ */
+export declare function loadRapier(dim: 2 | 3, options?: LoadRapierOptions): Promise<Rapier>;
+/**
+ * The deterministic 3D build alone. Tracks load it through this, so a track bundle references no
+ * other build.
+ */
+export declare function loadDeterministic3d(): Promise<Rapier>;

package/dist/rapier.js

@@ -0,0 +1,27 @@
+const modules = /* @__PURE__ */ new Map();
+function cached(key, load) {
+  let loading = modules.get(key);
+  if (!loading) {
+    loading = (async () => {
+      const mod = await load();
+      const R = mod.default ?? mod;
+      await R.init();
+      return R;
+    })();
+    modules.set(key, loading);
+  }
+  return loading;
+}
+function loadRapier(dim, options) {
+  if (options?.deterministic) {
+    return dim === 3 ? loadDeterministic3d() : cached("2/deterministic", () => import("@dimforge/rapier2d-deterministic-compat"));
+  }
+  return dim === 3 ? cached("3/regular", () => import("@dimforge/rapier3d-compat")) : cached("2/regular", () => import("@dimforge/rapier2d-compat"));
+}
+function loadDeterministic3d() {
+  return cached("3/deterministic", () => import("@dimforge/rapier3d-deterministic-compat"));
+}
+export {
+  loadDeterministic3d,
+  loadRapier
+};

package/dist/render.d.ts

@@ -0,0 +1,5 @@
+import type { AssetRef, World } from '@aethervtt/shard-core';
+import type { Mesh } from '@aethervtt/shard-mesh';
+/** Collider meshes from the renderer's mesh store. */
+export declare function rendererMeshes(world: World, ref: AssetRef): Mesh | undefined;
+export declare const collidersOverlay: import("@aethervtt/shard-render").OverlayDef;