@aethervtt/shard-physics 0.0.1 → 0.1.0

package/dist/track/golden.json

@@ -0,0 +1,238 @@
+{
+  "note": "The 0053 golden track: this scene, recorded with these options, hashes to this in Node and in Chromium (the embedding demo prints it). A change means tracks recorded before it no longer replay.",
+  "hash": "5d32645f",
+  "steps": 211,
+  "contacts": {
+    "minForce": 0.5,
+    "dedupeSteps": 3,
+    "max": 1024
+  },
+  "scene": {
+    "version": 1,
+    "dim": 3,
+    "step": 0.016666666666666666,
+    "maxSteps": 480,
+    "gravity": [0, -9.81, 0],
+    "groups": {
+      "dice": {
+        "layers": 1,
+        "mask": 7
+      },
+      "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"
+      },
+      {
+        "shape": "cuboid",
+        "halfExtents": [6, 2, 0.2],
+        "translation": [0, 2, -4],
+        "friction": 0.3,
+        "restitution": 0.4,
+        "density": 1,
+        "group": "walls"
+      },
+      {
+        "shape": "cuboid",
+        "halfExtents": [6, 2, 0.2],
+        "translation": [0, 2, 3],
+        "friction": 0.3,
+        "restitution": 0.4,
+        "density": 1,
+        "group": "walls"
+      },
+      {
+        "shape": "cuboid",
+        "halfExtents": [0.2, 2, 5],
+        "translation": [-5.5, 2, 0],
+        "friction": 0.3,
+        "restitution": 0.4,
+        "density": 1,
+        "group": "walls"
+      },
+      {
+        "shape": "cuboid",
+        "halfExtents": [0.2, 2, 5],
+        "translation": [5.5, 2, 0],
+        "friction": 0.3,
+        "restitution": 0.4,
+        "density": 1,
+        "group": "walls"
+      }
+    ],
+    "bodies": [
+      {
+        "id": "die-0",
+        "translation": [1, 1.5, -1.6],
+        "rotation": [
+          0.7507218295153406, -0.4045870384509049, 0.5155324718259261, 0.08338065422936225
+        ],
+        "linear": [-6.812196585582569, 2.09721123194322, -1.5573603240773082],
+        "angular": [2.197787747718394, -13.691132047679275, -9.111604643985629],
+        "colliders": [
+          {
+            "shape": "convex",
+            "points": [
+              -0.30022212862968445, -0.30022212862968445, -0.30022212862968445,
+              -0.30022212862968445, -0.30022212862968445, 0.30022212862968445, -0.30022212862968445,
+              0.30022212862968445, -0.30022212862968445, -0.30022212862968445, 0.30022212862968445,
+              0.30022212862968445, 0.30022212862968445, -0.30022212862968445, -0.30022212862968445,
+              0.30022212862968445, -0.30022212862968445, 0.30022212862968445, 0.30022212862968445,
+              0.30022212862968445, -0.30022212862968445, 0.30022212862968445, 0.30022212862968445,
+              0.30022212862968445
+            ],
+            "friction": 0.6,
+            "restitution": 0.3,
+            "density": 1,
+            "group": "dice"
+          }
+        ],
+        "ccd": true
+      },
+      {
+        "id": "die-1",
+        "translation": [2.1, 1.5, -1.6],
+        "rotation": [
+          0.4179796170440059, -0.016522474652443442, -0.8417788304186479, -0.34121613125132116
+        ],
+        "linear": [-5.266812545945868, 1.1050165030173957, 0.09882906544953585],
+        "angular": [-7.046791661996394, 6.453980351798236, 0.7213422143831849],
+        "colliders": [
+          {
+            "shape": "convex",
+            "points": [
+              0.41999998688697815, 0, 0, -0.41999998688697815, 0, 0, 0, 0.41999998688697815, 0, 0,
+              -0.41999998688697815, 0, 0, 0, 0.41999998688697815, 0, 0, -0.41999998688697815
+            ],
+            "friction": 0.6,
+            "restitution": 0.3,
+            "density": 1,
+            "group": "dice"
+          }
+        ],
+        "ccd": true
+      },
+      {
+        "id": "die-2",
+        "translation": [3.2, 1.5, -1.6],
+        "rotation": [
+          0.04178289163490359, 0.4167475678988952, -0.09787973525272552, -0.9027708524558368
+        ],
+        "linear": [-6.4489554786123335, 1.0944269075989723, -1.6447181943804026],
+        "angular": [11.939043214078993, 4.859942682087421, 9.853415577672422],
+        "colliders": [
+          {
+            "shape": "convex",
+            "points": [
+              0, -0.21029244363307953, -0.3402603268623352, -0.21029244363307953,
+              -0.3402603268623352, 0, -0.3402603268623352, 0, -0.21029244363307953, 0,
+              -0.21029244363307953, 0.3402603268623352, -0.21029244363307953, 0.3402603268623352, 0,
+              0.3402603268623352, 0, -0.21029244363307953, 0, 0.21029244363307953,
+              -0.3402603268623352, 0.21029244363307953, -0.3402603268623352, 0, -0.3402603268623352,
+              0, 0.21029244363307953, 0, 0.21029244363307953, 0.3402603268623352,
+              0.21029244363307953, 0.3402603268623352, 0, 0.3402603268623352, 0, 0.21029244363307953
+            ],
+            "friction": 0.6,
+            "restitution": 0.3,
+            "density": 1,
+            "group": "dice"
+          }
+        ],
+        "ccd": true
+      },
+      {
+        "id": "die-3",
+        "translation": [4.300000000000001, 1.5, -1.6],
+        "rotation": [
+          -0.9772431469135252, -0.05165042736614883, 0.2057378095834278, 0.0001373726965942252
+        ],
+        "linear": [-4.456490154843777, 2.042309113778174, -1.5335630979388952],
+        "angular": [6.778595130890608, 9.521802021190524, 4.029458113946021],
+        "colliders": [
+          {
+            "shape": "convex",
+            "points": [
+              -0.30022212862968445, -0.30022212862968445, -0.30022212862968445,
+              -0.30022212862968445, -0.30022212862968445, 0.30022212862968445, -0.30022212862968445,
+              0.30022212862968445, -0.30022212862968445, -0.30022212862968445, 0.30022212862968445,
+              0.30022212862968445, 0.30022212862968445, -0.30022212862968445, -0.30022212862968445,
+              0.30022212862968445, -0.30022212862968445, 0.30022212862968445, 0.30022212862968445,
+              0.30022212862968445, -0.30022212862968445, 0.30022212862968445, 0.30022212862968445,
+              0.30022212862968445
+            ],
+            "friction": 0.6,
+            "restitution": 0.3,
+            "density": 1,
+            "group": "dice"
+          }
+        ],
+        "ccd": true
+      },
+      {
+        "id": "die-4",
+        "translation": [1, 1.5, -0.5],
+        "rotation": [
+          -0.7968478543235026, -0.03498283840132274, 0.5037619790793197, -0.331713078595801
+        ],
+        "linear": [-6.16427865694277, 1.8229942652396858, 1.056697765365243],
+        "angular": [-2.243573118466884, 8.441326045431197, 7.427894265856594],
+        "colliders": [
+          {
+            "shape": "convex",
+            "points": [
+              0.41999998688697815, 0, 0, -0.41999998688697815, 0, 0, 0, 0.41999998688697815, 0, 0,
+              -0.41999998688697815, 0, 0, 0, 0.41999998688697815, 0, 0, -0.41999998688697815
+            ],
+            "friction": 0.6,
+            "restitution": 0.3,
+            "density": 1,
+            "group": "dice"
+          }
+        ],
+        "ccd": true
+      },
+      {
+        "id": "die-5",
+        "translation": [2.1, 1.5, -0.5],
+        "rotation": [
+          -0.5120255545904042, 0.5988778185348096, 0.25405581693581236, 0.5609196304235162
+        ],
+        "linear": [-6.6429823213256896, 1.218745602760464, -0.9305891934782267],
+        "angular": [-5.407783112023026, 10.646891570650041, 10.517003992572427],
+        "colliders": [
+          {
+            "shape": "convex",
+            "points": [
+              0, -0.21029244363307953, -0.3402603268623352, -0.21029244363307953,
+              -0.3402603268623352, 0, -0.3402603268623352, 0, -0.21029244363307953, 0,
+              -0.21029244363307953, 0.3402603268623352, -0.21029244363307953, 0.3402603268623352, 0,
+              0.3402603268623352, 0, -0.21029244363307953, 0, 0.21029244363307953,
+              -0.3402603268623352, 0.21029244363307953, -0.3402603268623352, 0, -0.3402603268623352,
+              0, 0.21029244363307953, 0, 0.21029244363307953, 0.3402603268623352,
+              0.21029244363307953, 0.3402603268623352, 0, 0.3402603268623352, 0, 0.21029244363307953
+            ],
+            "friction": 0.6,
+            "restitution": 0.3,
+            "density": 1,
+            "group": "dice"
+          }
+        ],
+        "ccd": true
+      }
+    ]
+  }
+}

package/dist/track/hash.d.ts

@@ -0,0 +1,12 @@
+export declare class Hasher {
+    h: number;
+    u32(v: number): this;
+    /** A number by its f64 bits; -0 hashes as 0. */
+    f64(v: number): this;
+    bool(v: boolean): this;
+    /** Its length, then its UTF-16 units. */
+    str(s: string): this;
+    /** Its length, then its elements' bits: f32 as words, 16-bit ones a word each. */
+    array(a: Float32Array | Int16Array | Uint16Array): this;
+    digest(): number;
+}

package/dist/track/hash.js

@@ -0,0 +1,41 @@
+import { mix32 } from "@aethervtt/shard-core";
+const f64 = new Float64Array(1);
+const f64Words = new Uint32Array(f64.buffer);
+class Hasher {
+  h = 2166136261;
+  u32(v) {
+    this.h = Math.imul(this.h ^ v >>> 0, 16777619);
+    return this;
+  }
+  /** A number by its f64 bits; -0 hashes as 0. */
+  f64(v) {
+    f64[0] = v === 0 ? 0 : v;
+    return this.u32(f64Words[0]).u32(f64Words[1]);
+  }
+  bool(v) {
+    return this.u32(v ? 1 : 0);
+  }
+  /** Its length, then its UTF-16 units. */
+  str(s) {
+    this.u32(s.length);
+    for (let i = 0; i < s.length; i++) this.u32(s.charCodeAt(i));
+    return this;
+  }
+  /** Its length, then its elements' bits: f32 as words, 16-bit ones a word each. */
+  array(a) {
+    this.u32(a.length);
+    if (a instanceof Float32Array) {
+      const words = new Uint32Array(a.buffer, a.byteOffset, a.length);
+      for (let i = 0; i < words.length; i++) this.u32(words[i]);
+      return this;
+    }
+    for (let i = 0; i < a.length; i++) this.u32(a[i] & 65535);
+    return this;
+  }
+  digest() {
+    return mix32(this.h);
+  }
+}
+export {
+  Hasher
+};

package/dist/track/index.d.ts

@@ -0,0 +1,3 @@
+export { type DecodeTrackOptions, decodeTrack, encodeTrack, sampleTrack, TRACK_ENGINE, TRACK_VERSION, type Track, type TrackContacts, trackHash, type Writable, } from './format.js';
+export { builtinSettleRules, type RecordTrackOptions, recordTrack, type Settle, type SettleResult, type SettleRule, type SettleView, settleWhenAsleep, TRACK_CHUNK_MS, TRACK_CHUNK_STEPS, type TrackContactOptions, type TrackDamping, type TrackPhase, trackCancelled, } from './record.js';
+export { checkTrackScene, MAX_TRACK_BODIES, MAX_TRACK_STEPS, sceneHash, type TrackBody, type TrackCollider, type TrackGroup, type TrackScene, trackSceneFromJson, trackSceneToJson, } from './scene.js';

package/dist/track/index.js

@@ -0,0 +1,44 @@
+import {
+  decodeTrack,
+  encodeTrack,
+  sampleTrack,
+  TRACK_ENGINE,
+  TRACK_VERSION,
+  trackHash
+} from "./format.js";
+import {
+  builtinSettleRules,
+  recordTrack,
+  settleWhenAsleep,
+  TRACK_CHUNK_MS,
+  TRACK_CHUNK_STEPS,
+  trackCancelled
+} from "./record.js";
+import {
+  checkTrackScene,
+  MAX_TRACK_BODIES,
+  MAX_TRACK_STEPS,
+  sceneHash,
+  trackSceneFromJson,
+  trackSceneToJson
+} from "./scene.js";
+export {
+  MAX_TRACK_BODIES,
+  MAX_TRACK_STEPS,
+  TRACK_CHUNK_MS,
+  TRACK_CHUNK_STEPS,
+  TRACK_ENGINE,
+  TRACK_VERSION,
+  builtinSettleRules,
+  checkTrackScene,
+  decodeTrack,
+  encodeTrack,
+  recordTrack,
+  sampleTrack,
+  sceneHash,
+  settleWhenAsleep,
+  trackCancelled,
+  trackHash,
+  trackSceneFromJson,
+  trackSceneToJson
+};

package/dist/track/record.d.ts

@@ -0,0 +1,79 @@
+import { ShardError } from '@aethervtt/shard-core';
+import { type Track, type Writable } from './format.js';
+import { type TrackGroup, type TrackScene } from './scene.js';
+/** What a settle rule sees after each step. Reading it allocates nothing. */
+export interface SettleView {
+    /** The step just simulated, from 1. */
+    readonly step: number;
+    readonly bodyCount: number;
+    /** 1 where body i sleeps after this step. */
+    readonly sleeping: Uint8Array;
+    /** Body i's pose after this step. */
+    pose(body: number, outPos: Writable, outRot: Writable): void;
+}
+/**
+ * A change of rules mid-track, applied after the step that returned it (a die that won't settle
+ * cocked against a wall: walls off, dice stop touching each other, everyone wakes). Return it
+ * once; a rule keeps its own state.
+ */
+export interface TrackPhase {
+    /** New layers and masks for these groups. */
+    groups?: {
+        [name: string]: TrackGroup;
+    };
+    /** These groups collide with nothing from now on. */
+    disableGroups?: string[];
+    /** Wake every body. */
+    wake?: true;
+    /**
+     * New damping for these bodies (by index), from the next step: a rolling ball that should
+     * settle as soon as a die would, say. A rule can ramp it by returning a phase each step.
+     */
+    damping?: TrackDamping[];
+}
+export interface TrackDamping {
+    body: number;
+    linear?: number;
+    angular?: number;
+}
+export type SettleResult = 'continue' | 'done' | TrackPhase;
+/** Called after every step: end the track, keep going, or change the rules. */
+export type Settle = (view: SettleView) => SettleResult;
+/**
+ * A settle rule by name, for recordings in a worker, where a function can't be sent: it takes the
+ * recording's parameters and returns a fresh `Settle` for it.
+ */
+export type SettleRule = (params: unknown) => Settle;
+/** Done once every body sleeps. */
+export declare const settleWhenAsleep: Settle;
+/** The rules every worker knows: `sleep` ends the track when every body sleeps. */
+export declare const builtinSettleRules: {
+    [name: string]: SettleRule;
+};
+export interface TrackContactOptions {
+    /** Contacts weaker than this (N) aren't recorded. */
+    minForce: number;
+    /** A pair touching again within this many steps is the same contact (default 3). */
+    dedupeSteps?: number;
+    /** Stop recording contacts after this many (default 1024). */
+    max?: number;
+}
+export interface RecordTrackOptions {
+    /** Aborting it rejects the recording with `physics/track-cancelled` within one chunk. */
+    signal?: AbortSignal;
+    /** Default: done when every body sleeps. */
+    settle?: Settle;
+    /** Record contacts (default: none). */
+    contacts?: TrackContactOptions;
+}
+/** Steps run between yields at most this many at a time, and for about this long. */
+export declare const TRACK_CHUNK_STEPS = 64;
+export declare const TRACK_CHUNK_MS = 4;
+export declare function trackCancelled(): ShardError;
+/**
+ * Records a track: builds a deterministic Rapier world from the scene, in body order, and writes
+ * every body's pose at every step, step 0 included, until `settle` says done or maxSteps. Steps
+ * run in chunks with a macrotask between them, where `signal` is checked. Needs no ECS and no
+ * renderer: it runs the same in a worker, in Node, or inline.
+ */
+export declare function recordTrack(scene: TrackScene, options?: RecordTrackOptions): Promise<Track>;