@aethervtt/shard-physics 0.0.1 → 0.1.0

package/dist/render.js

@@ -0,0 +1,264 @@
+import { defineOverlay, Meshes } from "@aethervtt/shard-render";
+import { CharacterState } from "./components.js";
+import { rotate } from "./pose.js";
+import { Physics } from "./world.js";
+const KIND_DYNAMIC = 0;
+const KIND_FIXED = 1;
+function rendererMeshes(world, ref) {
+  return world.tryResource(Meshes)?.get(ref);
+}
+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 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 step = Math.max(1, Math.ceil(Math.max(rows, cols) / 64));
+  for (let r = 0; r < rows; r += step) {
+    for (let c = 0; c + step < cols; c += step) {
+      at(pa, r, c);
+      at(pb, r, c + step);
+      g.line(pa, pb, color);
+    }
+  }
+  for (let c = 0; c < cols; c += step) {
+    for (let r = 0; r + step < rows; r += step) {
+      at(pa, r, c);
+      at(pb, r + step, c);
+      g.line(pa, pb, color);
+    }
+  }
+}
+export {
+  collidersOverlay,
+  rendererMeshes
+};

package/dist/track/format.d.ts

@@ -0,0 +1,58 @@
+/** A recorded track: every body's pose at every fixed step, plus the contacts that mattered. */
+export interface Track {
+    version: 1;
+    /** The Rapier build that recorded it, e.g. `rapier3d-deterministic@0.20.0`. */
+    engine: string;
+    /** `sceneHash` of the scene it was recorded from. */
+    sceneHash: number;
+    /** Seconds per step. */
+    step: number;
+    /** Steps simulated; poses exist for steps 0 to `steps`. */
+    steps: number;
+    bodyCount: number;
+    /** The settle rule ended it. */
+    settled: boolean;
+    /** It ran to the scene's maxSteps without settling. */
+    maxStepsHit: boolean;
+    /** (steps + 1) × bodies × 3, step-major. */
+    positions: Float32Array;
+    /** (steps + 1) × bodies × 4 (x y z w), step-major. */
+    rotations: Float32Array;
+    /** Contacts in the order they happened; `b` is -1 for a fixed collider. */
+    contacts: TrackContacts;
+    /** Time spent stepping. Excluded from equality and hashing. */
+    simulationMs: number;
+}
+export interface TrackContacts {
+    steps: Uint16Array;
+    a: Int16Array;
+    b: Int16Array;
+    /** Total contact force, N. */
+    force: Float32Array;
+}
+export declare const TRACK_VERSION = 1;
+/** The engine tracks are recorded and played with; another one fails with `physics/track-version`. */
+export declare const TRACK_ENGINE = "rapier3d-deterministic@0.20.0";
+/** One buffer, header and arrays: what a worker transfers and what a host can store. */
+export declare function encodeTrack(track: Track): ArrayBuffer;
+export interface DecodeTrackOptions {
+    /** The engine the track must come from (default TRACK_ENGINE); null accepts any. */
+    engine?: string | null;
+}
+/**
+ * A track from `encodeTrack`'s buffer. Its arrays are views on the buffer, not copies. A track from
+ * another format version or engine fails with `physics/track-version`: poses from another build
+ * of Rapier might not be what this one would record.
+ */
+export declare function decodeTrack(buffer: ArrayBuffer, options?: DecodeTrackOptions): Track;
+/** A hash over the header and every array (not simulationMs): equal tracks hash equal. */
+export declare function trackHash(track: Track): number;
+/** Anything indexable to write numbers into: a typed array, a tuple, a component column. */
+export interface Writable {
+    [index: number]: number;
+}
+/**
+ * A body's pose at `time` seconds (clamped to the track), interpolated between the two steps
+ * around it: positions linearly, rotations by slerp. Allocates nothing.
+ */
+export declare function sampleTrack(track: Track, time: number, body: number, outPos: Writable, outRot: Writable): void;

package/dist/track/format.js

@@ -0,0 +1,171 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { Hasher } from "./hash.js";
+const TRACK_VERSION = 1;
+const TRACK_ENGINE = "rapier3d-deterministic@0.20.0";
+const MAGIC = 1263686739;
+const HEADER = 52;
+const SETTLED = 1;
+const MAX_STEPS_HIT = 2;
+function corrupt(message) {
+  return new ShardError("physics/track-invalid", message, {
+    hint: "Pass the ArrayBuffer encodeTrack made, whole."
+  });
+}
+function encodeTrack(track) {
+  const engineBytes = track.engine.length + 3 & ~3;
+  const c = track.contacts.steps.length;
+  const size = HEADER + engineBytes + (track.positions.length + track.rotations.length) * 4 + c * 10;
+  const buf = new ArrayBuffer(size);
+  const view = new DataView(buf);
+  view.setUint32(0, MAGIC, true);
+  view.setUint32(4, track.version, true);
+  view.setUint32(8, track.sceneHash >>> 0, true);
+  view.setFloat64(12, track.step, true);
+  view.setUint32(20, track.steps, true);
+  view.setUint32(24, track.bodyCount, true);
+  view.setUint32(28, (track.settled ? SETTLED : 0) | (track.maxStepsHit ? MAX_STEPS_HIT : 0), true);
+  view.setUint32(32, c, true);
+  view.setFloat64(36, track.simulationMs, true);
+  view.setUint32(44, track.engine.length, true);
+  view.setUint32(48, 0, true);
+  const bytes = new Uint8Array(buf);
+  for (let i = 0; i < track.engine.length; i++)
+    bytes[HEADER + i] = track.engine.charCodeAt(i) & 127;
+  let o = HEADER + engineBytes;
+  new Float32Array(buf, o, track.positions.length).set(track.positions);
+  o += track.positions.length * 4;
+  new Float32Array(buf, o, track.rotations.length).set(track.rotations);
+  o += track.rotations.length * 4;
+  new Float32Array(buf, o, c).set(track.contacts.force);
+  o += c * 4;
+  new Uint16Array(buf, o, c).set(track.contacts.steps);
+  o += c * 2;
+  new Int16Array(buf, o, c).set(track.contacts.a);
+  o += c * 2;
+  new Int16Array(buf, o, c).set(track.contacts.b);
+  return buf;
+}
+function decodeTrack(buffer, options) {
+  if (buffer.byteLength < HEADER) throw corrupt("The buffer is too short for a track");
+  const view = new DataView(buffer);
+  if (view.getUint32(0, true) !== MAGIC) throw corrupt("The buffer isn't a track");
+  const version = view.getUint32(4, true);
+  const engineLength = view.getUint32(44, true);
+  if (HEADER + engineLength > buffer.byteLength) throw corrupt("The track header is cut off");
+  const bytes = new Uint8Array(buffer, HEADER, engineLength);
+  let engine = "";
+  for (let i = 0; i < engineLength; i++) engine += String.fromCharCode(bytes[i]);
+  const expected = options?.engine === void 0 ? TRACK_ENGINE : options.engine;
+  if (version !== TRACK_VERSION || expected !== null && engine !== expected) {
+    throw new ShardError(
+      "physics/track-version",
+      `The track is version ${version} from ${engine}; expected version ${TRACK_VERSION} from ${expected ?? "any engine"}`,
+      { hint: "Record it again with this build, or play it with the build that recorded it." }
+    );
+  }
+  const steps = view.getUint32(20, true);
+  const bodyCount = view.getUint32(24, true);
+  const flags = view.getUint32(28, true);
+  const c = view.getUint32(32, true);
+  const poses = (steps + 1) * bodyCount;
+  let o = HEADER + (engineLength + 3 & ~3);
+  if (o + poses * 28 + c * 10 > buffer.byteLength) throw corrupt("The track is cut off");
+  const positions = new Float32Array(buffer, o, poses * 3);
+  o += poses * 12;
+  const rotations = new Float32Array(buffer, o, poses * 4);
+  o += poses * 16;
+  const force = new Float32Array(buffer, o, c);
+  o += c * 4;
+  const contactSteps = new Uint16Array(buffer, o, c);
+  o += c * 2;
+  const a = new Int16Array(buffer, o, c);
+  o += c * 2;
+  const b = new Int16Array(buffer, o, c);
+  return {
+    version: TRACK_VERSION,
+    engine,
+    sceneHash: view.getUint32(8, true),
+    step: view.getFloat64(12, true),
+    steps,
+    bodyCount,
+    settled: (flags & SETTLED) !== 0,
+    maxStepsHit: (flags & MAX_STEPS_HIT) !== 0,
+    positions,
+    rotations,
+    contacts: { steps: contactSteps, a, b, force },
+    simulationMs: view.getFloat64(36, true)
+  };
+}
+function trackHash(track) {
+  const h = new Hasher();
+  h.u32(track.version).str(track.engine).u32(track.sceneHash).f64(track.step);
+  h.u32(track.steps).u32(track.bodyCount).bool(track.settled).bool(track.maxStepsHit);
+  h.array(track.positions).array(track.rotations);
+  const c = track.contacts;
+  h.array(c.steps).array(c.a).array(c.b).array(c.force);
+  return h.digest();
+}
+function sampleTrack(track, time, body, outPos, outRot) {
+  const n = track.bodyCount;
+  if (body < 0 || body >= n || !Number.isInteger(body)) {
+    throw new ShardError("physics/track-body", `The track has no body ${body}`, {
+      hint: `Bodies are 0 to ${n - 1}, in the scene's order.`
+    });
+  }
+  let f = time / track.step;
+  if (!(f > 0)) f = 0;
+  if (f > track.steps) f = track.steps;
+  const i0 = Math.floor(f);
+  const i1 = i0 < track.steps ? i0 + 1 : i0;
+  const t = f - i0;
+  const p = track.positions;
+  const a3 = (i0 * n + body) * 3;
+  const b3 = (i1 * n + body) * 3;
+  outPos[0] = p[a3] + (p[b3] - p[a3]) * t;
+  outPos[1] = p[a3 + 1] + (p[b3 + 1] - p[a3 + 1]) * t;
+  outPos[2] = p[a3 + 2] + (p[b3 + 2] - p[a3 + 2]) * t;
+  const r = track.rotations;
+  const a4 = (i0 * n + body) * 4;
+  const b4 = (i1 * n + body) * 4;
+  const ax = r[a4];
+  const ay = r[a4 + 1];
+  const az = r[a4 + 2];
+  const aw = r[a4 + 3];
+  let bx = r[b4];
+  let by = r[b4 + 1];
+  let bz = r[b4 + 2];
+  let bw = r[b4 + 3];
+  let cos = ax * bx + ay * by + az * bz + aw * bw;
+  if (cos < 0) {
+    cos = -cos;
+    bx = -bx;
+    by = -by;
+    bz = -bz;
+    bw = -bw;
+  }
+  let ka = 1 - t;
+  let kb = t;
+  if (cos < 0.9995) {
+    const angle = Math.acos(cos);
+    const sin = Math.sin(angle);
+    ka = Math.sin((1 - t) * angle) / sin;
+    kb = Math.sin(t * angle) / sin;
+  }
+  const x = ax * ka + bx * kb;
+  const y = ay * ka + by * kb;
+  const z = az * ka + bz * kb;
+  const w = aw * ka + bw * kb;
+  const len = Math.sqrt(x * x + y * y + z * z + w * w) || 1;
+  outRot[0] = x / len;
+  outRot[1] = y / len;
+  outRot[2] = z / len;
+  outRot[3] = w / len;
+}
+export {
+  TRACK_ENGINE,
+  TRACK_VERSION,
+  decodeTrack,
+  encodeTrack,
+  sampleTrack,
+  trackHash
+};