@msb235/blits-rapier 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. The release workflow refuses a `rapier-v*` tag with no
 section here.
 
+## 0.4.0
+
+### Breaking
+
+- `@msb235/blits` is a peer at `^0.19.0`, where it was `^0.18.0`. Built and tested against engine
+  0.19.0; nothing here uses what that release changed.
+- `PhysicsOptions` no longer takes `keyOf`: every subject in the mix is the driver's, and it keys
+  them itself.
+
+### Added
+
+- Kinematic bodies moved by a voice: `kinematic2` and `kinematic3` add `goal` and `facing` channels
+  to a body's controls, which move a kinematic body over the next step. Neither has a rest, so a
+  body no voice writes stays where it is.
+- History pages to a `store`. The world's state packs to plain data, its Rapier snapshot as base64,
+  and the log of each frame's pushes pages out beside it, so memory stays bounded.
+
+### Fixed
+
+- Pushes, impulses, drops and added bodies are logged at the mix's time (`mix.now`), not the host's
+  timestamp, so a seek, `rebase` or rate other than 1 no longer files them at the wrong step.
+- The log of each frame's pushes reaches back to the world copy a replay at the edge of memory
+  starts from, not just `history.ms`.
+- `channels2`'s `rotation` takes a turn as `2 * Math.PI`. It was `angle()`, whose turn is 360, so
+  two radian angles either side of ±π blended the long way round, through 0.
+
+## 0.3.0
+
+### Breaking
+
+- `@msb235/blits` is a peer at `^0.18.0`, where it was `^0.17.0`. Built and tested against engine
+  0.18.0; nothing here uses what that release changed.
+
 ## 0.2.0
 
 ### Breaking

package/README.md

@@ -65,13 +65,35 @@ const { position, rotation } = sim.mix.probe(box);
 | Channel | 2D (`channels2`) | 3D (`channels3`) | On |
 |---|---|---|---|
 | `position` | `vec(2, sum())` | `vec(3, sum())` | the body |
-| `rotation` | `angle()`, radians | `quat()`, `[x, y, z, w]` | the body |
+| `rotation` | `angle({ turn: 2 * Math.PI })`, radians | `quat()`, `[x, y, z, w]` | the body |
 | `force` | `vec(2, sum())` | `vec(3, sum())` | its controls |
 | `torque` | `sum()` | `vec(3, sum())` | its controls |
 
 Spread them into a kit with your own channels. Forces and torques are in Rapier's units, newtons
 and newton-meters for a body whose mass you set in kilograms.
 
+## Kinematic bodies
+
+A body made with `RigidBodyDesc.kinematicPositionBased()` goes where a voice on its controls says,
+through two more channels, `kinematic2` or `kinematic3`, spread into the kit beside the others:
+
+| Channel | 2D (`kinematic2`) | 3D (`kinematic3`) |
+|---|---|---|
+| `goal` | `vec(2, last())`, a position | `vec(3, last())`, a position |
+| `facing` | `last()`, an angle in radians | `last()`, an `[x, y, z, w]` quaternion |
+
+```ts
+const sim = physics(kit<Pose3 & Kinematic3>({ ...channels3, ...kinematic3 }), { rapier: RAPIER });
+const door = sim.body(RAPIER.RigidBodyDesc.kinematicPositionBased(), RAPIER.ColliderDesc.cuboid(1, 2, 0.1));
+door.drive({ patch: keys(800, [{ at: 0, delta: { goal: [0, 2, 0] } }, { at: 1, delta: { goal: [2, 2, 0] } }]) });
+```
+
+Neither has a rest: a body no voice writes a goal for stays where it is, and one whose voice has
+ended stays where it left it. The world moves the body there over the next step, at the speed that
+takes, so it pushes what it meets. Since the channels are `last`, a voice's weight only switches its
+goal on or off, and of the voices writing one, the last cued wins; keyframes between two goals
+interpolate, the facing the short way round.
+
 ## The clock and seeking
 
 `physics` makes the mix, with `stepMs` 1000 / 60 unless you set it; the world takes one Rapier step
@@ -79,16 +101,17 @@ per interval, so it runs at the same rate whatever the frame rate. Pass `history
 seek. The world lives in the mix as the state of a stateful patch, so blits' history keeps a copy
 every `every` ms and a seek replays from the nearest one. A copy is Rapier's snapshot, kept as
 bytes and rebuilt into a world only when a replay needs it, so history costs memory in proportion
-to the world's size and `ms / every`. Each frame's pushes are logged beside it for the replay and
-pruned with history.
+to the world's size and `ms / every`. Each frame's pushes are logged beside it for the replay, back
+to the copy a replay at the edge of memory would start from.
+
+`history.store` works: the world pages out as plain data, its snapshot in base64. Give the mix a
+`name`, as every mix on a transport with a store needs; `physics` keys its own subjects, so it takes
+no `keyOf`. The log of each frame's pushes pages out with it, one `host` record a frame under the
+subject `'blits-rapier frames'`, and `prepare` loads it back for a seek past memory.
 
 Replay matches the first pass exactly on one machine. To match across machines, pass Rapier's
 deterministic build.
 
 ## Not yet
 
-- Kinematic bodies moved by a voice. They need a channel with no rest, which blits' `vec` of
-  `sum()` is not.
-- Paging history to a `store`: a Rapier description is not plain data, so a body's add cannot be
-  written out.
 - Soft bodies, cloth and ropes.

package/dist/channels.d.ts

@@ -21,3 +21,25 @@ export declare const channels2: {
 export declare const channels3: {
     [K in keyof Pose3]: Channel<Pose3[K]>;
 };
+/**
+ * Where a voice on a kinematic 2D body's controls moves it: a position and an angle in radians. Each
+ * has no rest, so a body with no voice writing it stays where it is. A voice's weight only switches
+ * its goal on or off, and of the voices writing one, the last cued wins.
+ */
+export interface Kinematic2 {
+    goal?: Vec<2>;
+    facing?: number;
+}
+/** Where a voice on a kinematic 3D body's controls moves it: a position and an `[x, y, z, w]` quaternion. See `Kinematic2`. */
+export interface Kinematic3 {
+    goal?: Vec<3>;
+    facing?: Vec<4>;
+}
+/** A kinematic 2D body's channels, to spread into a kit beside `channels2`. */
+export declare const kinematic2: {
+    [K in keyof Kinematic2]-?: Channel<NonNullable<Kinematic2[K]>>;
+};
+/** A kinematic 3D body's channels, to spread into a kit beside `channels3`. */
+export declare const kinematic3: {
+    [K in keyof Kinematic3]-?: Channel<NonNullable<Kinematic3[K]>>;
+};

package/dist/channels.js

@@ -1,8 +1,8 @@
-import { angle, quat, sum, vec } from '@msb235/blits';
+import { angle, last, quat, sum, vec } from '@msb235/blits';
 /** A 2D world's channels, to spread into a kit. */
 export const channels2 = {
     position: vec(2, sum()),
-    rotation: angle(),
+    rotation: angle({ turn: 2 * Math.PI }),
     force: vec(2, sum()),
     torque: sum(),
 };
@@ -13,3 +13,14 @@ export const channels3 = {
     force: vec(3, sum()),
     torque: vec(3, sum()),
 };
+const along = (a, b, u) => a + (b - a) * u;
+/** A kinematic 2D body's channels, to spread into a kit beside `channels2`. */
+export const kinematic2 = {
+    goal: vec(2, last({ lerp: along })),
+    facing: last({ lerp: angle({ turn: 2 * Math.PI }).lerp }),
+};
+/** A kinematic 3D body's channels, to spread into a kit beside `channels3`. */
+export const kinematic3 = {
+    goal: vec(3, last({ lerp: along })),
+    facing: last({ lerp: quat().lerp }),
+};

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { channels2, channels3, type Pose2, type Pose3 } from './channels.js';
+export { channels2, channels3, type Kinematic2, type Kinematic3, kinematic2, kinematic3, type Pose2, type Pose3, } from './channels.js';
 export { type Body, type Physics, type PhysicsOptions, physics } from './physics.js';
 export type { RapierBody, RapierModule, RapierVector, RapierWorld } from './rapier.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { channels2, channels3 } from './channels.js';
+export { channels2, channels3, kinematic2, kinematic3, } from './channels.js';
 export { physics } from './physics.js';

package/dist/physics.d.ts

@@ -1,8 +1,11 @@
 import { type Handle, type Kit, type Mix, type MixOptions, type Signal, type VoiceSpec } from '@msb235/blits';
 import type { Pose2, Pose3 } from './channels.js';
 import { type RapierModule, type RapierWorld } from './rapier.js';
-/** What `physics` takes: a mix's options, the Rapier module, and the world's gravity. */
-export interface PhysicsOptions<H> extends MixOptions<H> {
+/**
+ * What `physics` takes: a mix's options, the Rapier module, and the world's gravity. There is no
+ * `keyOf`: every subject is the driver's own, and it keys them itself for a history store.
+ */
+export interface PhysicsOptions<H> extends Omit<MixOptions<H>, 'keyOf'> {
     /** An initialized Rapier module. `@dimforge/rapier3d-compat` makes a 3D world, `rapier2d-compat` a 2D one. */
     rapier: RapierModule;
     /** Default: `[0, -9.81]` or `[0, -9.81, 0]`. */

package/dist/physics.js

@@ -1,20 +1,66 @@
 import { mix, patch, } from '@msb235/blits';
 import { dimsOf } from './rapier.js';
-import { applyLog, copy, insert, worldOf } from './world.js';
+import { applyLog, copy, insert, pack, unpack, worldOf } from './world.js';
 const ROLE = 'physics';
 const copyOf = (r) => typeof r === 'number' ? r : [...r];
+/** The subject key the world's frame records go under in a history store, on the `host` stream. */
+const FRAMES = 'blits-rapier frames';
 /** Makes a mix that holds a Rapier world, stepped on its `stepMs` clock and replayed by its history. */
 export function physics(kit, opts) {
     const { rapier, gravity, weight, ...rest } = opts;
     const dims = dimsOf(rapier);
     const g = gravity ?? (dims.n === 2 ? [0, -9.81] : [0, -9.81, 0]);
-    const m = mix(kit, { ...rest, stepMs: rest.stepMs ?? 1000 / 60 });
-    const log = [];
+    const stepMs = rest.stepMs ?? 1000 / 60;
+    const name = rest.name ?? '';
+    const history = rest.history;
+    const store = history?.store;
     // Each frame's pushes at its mix time. A seek replays steps on what the host reads now, so the
     // world reads the pushes of the frame that caused each step from here instead: the first frame
     // at or after the step's end, looked up half a step early since replayed times can round apart.
+    // It reaches back past memory to the world's copy a replay starts from; older frames go to the
+    // store as host records under `FRAMES`, and come back when `prepare` loads.
     const pushLog = [];
-    const keep = rest.history?.ms ?? 0;
+    const keep = history === undefined ? 0 : history.ms + (history.every ?? 200) + 2 * stepMs;
+    const ours = (r) => r.mix === name && r.stream === 'host' && r.subject === FRAMES;
+    const restore = (records, from) => {
+        let start = Number.NEGATIVE_INFINITY;
+        for (const r of records)
+            if (ours(r) && r.at <= from && r.at > start)
+                start = r.at;
+        const byAt = new Map();
+        for (const r of records)
+            if (ours(r) && r.at >= start && (byAt.get(r.at)?.seq ?? -1) < r.seq)
+                byAt.set(r.at, r);
+        const first = pushLog[0]?.at ?? Number.POSITIVE_INFINITY;
+        const older = [...byAt.values()]
+            .filter((r) => r.at < first)
+            .sort((a, b) => a.at - b.at)
+            .map((r) => ({ ...r.data, at: r.at, seq: r.seq }));
+        pushLog.unshift(...older);
+    };
+    const paging = store && {
+        page: (out) => store.page(out),
+        cut: (seq) => store.cut(seq),
+        async load(t) {
+            const all = await store.load(t);
+            // A replay to t starts from the world's latest copy at or before it, which needs the frames from there.
+            let from = t;
+            for (const r of all)
+                if (r.mix === name && r.stream === 'snap' && r.subject === 'world' && r.at < from)
+                    from = r.at;
+            restore(from < t ? await store.load(from) : all, from);
+            return all.filter((r) => !ours(r));
+        },
+    };
+    // Every subject is the driver's own: the world, each body and each body's controls.
+    const keys = new WeakMap();
+    const m = mix(kit, {
+        ...rest,
+        ...(paging ? { history: { ...history, store: paging } } : {}),
+        stepMs,
+        keyOf: (subject) => keys.get(subject),
+    });
+    const log = [];
     const frameAt = (t) => {
         let lo = 0;
         let hi = pushLog.length;
@@ -59,6 +105,13 @@ export function physics(kit, opts) {
                 if (handle !== undefined && h !== undefined)
                     dims.place(w.getRigidBody(handle), h.now, h.before, h.dt);
             }
+            const goals = frame?.goals ?? {};
+            for (const k in goals) {
+                const handle = s.handles.get(+k);
+                const g = goals[k];
+                if (handle !== undefined && g !== undefined)
+                    dims.aim(w.getRigidBody(handle), g);
+            }
             const pushed = [];
             for (const k in pushes) {
                 const handle = s.handles.get(+k);
@@ -79,8 +132,11 @@ export function physics(kit, opts) {
             s.t = setting.timestamp;
         },
         clone: copy,
+        pack,
+        unpack,
     });
     const WORLD = {};
+    keys.set(WORLD, 'world');
     let started = false;
     const simulated = patch(0, (_p, subject) => {
         const handle = live?.handles.get(subject.key);
@@ -89,7 +145,7 @@ export function physics(kit, opts) {
         const b = worldOf(live, rapier).getRigidBody(handle);
         return { position: dims.position(b), rotation: dims.rotation(b) };
     }, { writes: ['position', 'rotation'] });
-    const now = () => (Number.isNaN(m.timestamp) ? Number.NEGATIVE_INFINITY : m.timestamp);
+    const now = () => (Number.isNaN(m.now) ? Number.NEGATIVE_INFINITY : m.now);
     const driven = new Set();
     // Each body's voices in the simulation's role besides its own, and its pose the last frame they held it.
     const authored = new Map();
@@ -133,6 +189,7 @@ export function physics(kit, opts) {
             const key = next++;
             insert(log, { at: now(), key, kind: 'add', desc, colliders });
             const controls = {};
+            keys.set(controls, `controls ${key}`);
             const own = (spec, subject) => {
                 if ('subjects' in spec)
                     throw new Error('blits-rapier: a body cues on itself; its spec names no subjects');
@@ -157,6 +214,7 @@ export function physics(kit, opts) {
                     insert(log, { at: now(), key, kind: 'drop' });
                 },
             };
+            keys.set(body, `body ${key}`);
             body.simulated = m.cue({
                 patch: simulated,
                 subjects: [body],
@@ -173,13 +231,22 @@ export function physics(kit, opts) {
                 m.cue({ patch: world, subjects: [WORLD] });
             }
             const pushes = {};
+            const goals = {};
             for (const body of driven) {
                 const p = m.probe(body.controls, out);
                 const torque = typeof p.torque === 'number' ? [p.torque] : p.torque;
                 if (p.force.some((x) => x !== 0) || torque.some((x) => x !== 0))
                     pushes[body.key] = [...p.force, ...torque];
+                if (p.goal !== undefined || p.facing !== undefined) {
+                    const g = {};
+                    if (p.goal !== undefined)
+                        g.position = [...p.goal];
+                    if (p.facing !== undefined)
+                        g.rotation = copyOf(p.facing);
+                    goals[body.key] = g;
+                }
             }
-            const at = m.timestamp;
+            const at = m.now;
             let back = false;
             while (pushLog.length > 0 && pushLog[pushLog.length - 1].at >= at) {
                 pushLog.pop();
@@ -190,12 +257,20 @@ export function physics(kit, opts) {
                 holding = {};
                 held.clear();
             }
-            pushLog.push({ at, pushes, holds: holding });
+            pushLog.push({ at, seq: m.seq, pushes, holds: holding, goals });
             let old = 0;
             while (old < pushLog.length - 1 && pushLog[old + 1].at < at - keep)
                 old++;
-            if (old > 0)
-                pushLog.splice(0, old);
+            const gone = old > 0 ? pushLog.splice(0, old) : undefined;
+            if (gone !== undefined && store !== undefined)
+                store.page(gone.map(({ at, seq, pushes, holds, goals }) => ({
+                    mix: name,
+                    stream: 'host',
+                    subject: FRAMES,
+                    at,
+                    seq,
+                    data: { pushes, holds, goals },
+                })));
             m.probe(WORLD);
             live = seen;
             holding = holdsAt(at);

package/dist/rapier.d.ts

@@ -23,6 +23,8 @@ export interface RapierBody {
     setRotation(r: never, wake: boolean): void;
     setLinvel(v: RapierVector, wake: boolean): void;
     setAngvel(v: never, wake: boolean): void;
+    setNextKinematicTranslation(v: RapierVector): void;
+    setNextKinematicRotation(r: never): void;
 }
 /** What blits-rapier uses of a Rapier world, in either build. */
 export interface RapierWorld {
@@ -56,6 +58,13 @@ export interface Dims {
     torque(body: RapierBody, torque: number | readonly number[]): void;
     /** Puts the body at a pose, moving at the speed it took to get there from `before` over `dt` ms. */
     place(body: RapierBody, now: Placed, before: Placed | undefined, dt: number): void;
+    /** Moves a kinematic body to whichever of a position and rotation is given, over the next step. */
+    aim(body: RapierBody, goal: Goal): void;
+}
+/** Where a kinematic body's controls ask it to be: either part may be absent. */
+export interface Goal {
+    position?: readonly number[];
+    rotation?: number | readonly number[];
 }
 /** A body's position and rotation as the channels hold them. */
 export interface Placed {

package/dist/rapier.js

@@ -17,6 +17,12 @@ const two = {
         turn -= 2 * Math.PI * Math.round(turn / (2 * Math.PI));
         b.setAngvel((dt > 0 ? turn / (dt / 1000) : 0), true);
     },
+    aim: (b, goal) => {
+        if (goal.position !== undefined)
+            b.setNextKinematicTranslation(two.vector(goal.position));
+        if (goal.rotation !== undefined)
+            b.setNextKinematicRotation(goal.rotation);
+    },
 };
 const three = {
     n: 3,
@@ -37,6 +43,16 @@ const three = {
         b.setLinvel(three.vector(speed(now.position, before?.position, dt)), true);
         b.setAngvel(three.vector(spin(now.rotation, before?.rotation, dt)), true);
     },
+    aim: (b, goal) => {
+        if (goal.position !== undefined)
+            b.setNextKinematicTranslation(three.vector(goal.position));
+        if (goal.rotation === undefined)
+            return;
+        const [x, y, z, w] = goal.rotation;
+        // A keyed facing need not be unit length, and Rapier takes it as given.
+        const n = Math.hypot(x, y, z, w) || 1;
+        b.setNextKinematicRotation({ x: x / n, y: y / n, z: z / n, w: w / n });
+    },
 };
 /** The angular velocity turning `before` into `now` over `dt` ms, both `[x, y, z, w]`. */
 function spin(now, before, dt) {

package/dist/world.d.ts

@@ -32,6 +32,10 @@ export type Entry = {
 export declare function worldOf(state: State, rapier: RapierModule): RapierWorld;
 /** A copy sharing nothing with `state`, holding the world as a snapshot. */
 export declare function copy(state: State): State;
+/** The state as plain data, for a history store: the snapshot as base64 and the handles as pairs. */
+export declare function pack(state: State): unknown;
+/** A state from what `pack` made, its world left to `worldOf` to rebuild. */
+export declare function unpack(data: unknown): State;
 /** Puts `entry` into `log` after every entry at or before its time. */
 export declare function insert(log: Entry[], entry: Entry): void;
 /**

package/dist/world.js

@@ -15,6 +15,28 @@ export function copy(state) {
         t: state.t,
     };
 }
+/** The state as plain data, for a history store: the snapshot as base64 and the handles as pairs. */
+export function pack(state) {
+    const bytes = state.world === null ? state.bytes : state.world.takeSnapshot();
+    let text = '';
+    // In chunks: a spread of a large snapshot overflows the call stack.
+    for (let i = 0; i < (bytes?.length ?? 0); i += 0x8000)
+        text += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return {
+        bytes: btoa(text),
+        handles: [...state.handles],
+        t: Number.isNaN(state.t) ? null : state.t,
+    };
+}
+/** A state from what `pack` made, its world left to `worldOf` to rebuild. */
+export function unpack(data) {
+    const d = data;
+    const text = atob(d.bytes);
+    const bytes = new Uint8Array(text.length);
+    for (let i = 0; i < text.length; i++)
+        bytes[i] = text.charCodeAt(i);
+    return { bytes, world: null, handles: new Map(d.handles), t: d.t ?? Number.NaN };
+}
 /** Puts `entry` into `log` after every entry at or before its time. */
 export function insert(log, entry) {
     let i = log.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits-rapier",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Pairs Rapier rigid-body physics with a blits mix: voices push bodies, and each body's simulated pose blends with authored motion",
   "keywords": [
     "physics",
@@ -38,14 +38,14 @@
     "prepack": "rm -rf dist && npm run build"
   },
   "peerDependencies": {
-    "@msb235/blits": "^0.17.0",
+    "@msb235/blits": "^0.19.0",
     "@dimforge/rapier2d-compat": ">=0.21.0 <1.0.0",
     "@dimforge/rapier3d-compat": ">=0.21.0 <1.0.0"
   },
   "devDependencies": {
     "@dimforge/rapier2d-compat": "0.21.0",
     "@dimforge/rapier3d-compat": "0.21.0",
-    "@msb235/blits": "0.17.0"
+    "@msb235/blits": "0.19.0"
   },
   "peerDependenciesMeta": {
     "@dimforge/rapier2d-compat": {