@msb235/blits-rapier 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.5.0
+
+### Breaking
+
+- `@msb235/blits` is a peer at `^0.20.0`, where it was `^0.19.0`. Built and tested against engine
+  0.20.0; a physics mix on a transport reads its `Transport.history`.
+
+### Added
+
+- A physics mix plays on a shared `transport`: the host syncs the transport and calls the new
+  `sim.step()`, and the world seeks with the transport's other mixes. `physicsStore(store)` wraps
+  the transport's history store so the world's log of pushes pages through it. `sim.sync` on a
+  transport throws, as does `physics` on a transport whose store is not wrapped.
+- The mix is named `'physics'` when `physics` is given no `name`, so the debug panel lists it.
+
+### Fixed
+
+- A seek forward after playing on from a seek back replays the world with the pushes logged the
+  first time. Playing on dropped every frame logged ahead, so the world replayed that stretch with
+  one frame's push.
+- An `impulse`, `drop` or `body` call made after a seek lets go of the calls logged ahead of it
+  before the seek. A host making its calls again on the way did each twice, and a call it did not
+  make again still happened.
+- A body shows the time sought as soon as a seek lands, and `sim.world()` returns that world. It
+  showed the world from before the seek until the next frame, and on that frame too if no time
+  had passed.
+- A mix given no `history` keeps the one a debugger's `watched().history` gives it. The world
+  logged only one frame of pushes, so the debugger's seek replayed every step with that frame's.
+- Without a history `store`, the log of `impulse`, `drop` and `body` calls lets go of what history
+  can no longer reach. It grew for the session, holding every body's Rapier description.
+
 ## 0.4.0
 
 ### Breaking

package/README.md

@@ -56,7 +56,10 @@ const { position, rotation } = sim.mix.probe(box);
   role adds on top of wherever physics has it.
 - **`body.impulse(v)`** applies an impulse once, on the step after the mix's current time.
   **`body.drop()`** takes the body out of the world then. Both are logged at that time, so a seek
-  back before it undoes them and playing forward through it does them again.
+  back before it undoes them and playing forward through it does them again. One of these calls,
+  or `sim.body`, made after a seek lets go of the calls logged ahead of it before the seek, as a
+  call on the mix's tape starts a new future: a host that makes its calls again on the way does
+  each once.
 - **`sim.world()`** is the Rapier world as the last `sync` left it, for reading: raycasts, contact
   queries, debugging draws. A change made to it directly is lost at the next seek.
 
@@ -96,9 +99,15 @@ 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
-per interval, so it runs at the same rate whatever the frame rate. Pass `history` and a `tape` to
-seek. The world lives in the mix as the state of a stateful patch, so blits' history keeps a copy
+`physics` makes the mix, named `'physics'` unless you name it, with `stepMs` 1000 / 60 unless you
+set it; the world takes one Rapier step per interval of mix time, so it runs at the same rate
+whatever the frame rate or the mix's `rate`. Each frame reads every body's controls once, and the
+steps that frame takes all push by what it read, so a force that changes faster than the frame
+rate is sampled at it. A long frame, such as the first after a tab was hidden, catches up every
+step it owes, unless the mix's `maxDt` caps how far a frame steps: two seconds take 120 steps
+without it and 6 under `maxDt: 100`, the rest dropped rather than owed. Call `mix.rebase()` when a
+tab comes back to leave the hidden time out instead. Pass `history` and a `tape` to
+seek, or leave `history` out and a debugger's `watched().history` is kept as the mix's. 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, back
@@ -109,9 +118,35 @@ to the copy a replay at the edge of memory would start from.
 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.
 
+On a shared `transport`, the world plays on the transport's clock and history beside its other
+mixes: sync the transport, then call `sim.step()` each frame, where a mix alone calls
+`sim.sync(now)`. If the transport keeps a history `store`, make it with `physicsStore(store)`, so
+the log of pushes pages through it; `physics` throws for a transport whose store is not wrapped.
+
+```ts
+const t = transport({ history: { ms: 10_000, tape, store: physicsStore(store) } });
+const sim = physics(kit<Pose3>(channels3), { rapier: RAPIER, transport: t, name: 'world' });
+// each frame
+t.sync(now);
+sim.step();
+```
+
 Replay matches the first pass exactly on one machine. To match across machines, pass Rapier's
 deterministic build.
 
-## Not yet
-
+## Not handled
+
+- **Reads at another time.** `mix.project(t)` and `mix.trace` show a body where the world was at
+  the last `sync`, not at `t`, since the world is a voice on a subject of its own. A seek is
+  shown at once, before the next `sync`.
+- **Picking another future.** The tape's `switchBranch` brings back the mix's own calls, not
+  `impulse`, `drop` or `body` calls a later one let go of. A call on the mix itself, such as a
+  `cue`, made after a seek does not let go of those calls logged ahead.
+- **A seek forward past memory after playing on from a seek back**, with a `store`: the seek back
+  cuts the pushes paged after it from the store, so the world replays that stretch with the push
+  of the first frame it still holds. Within memory it replays exactly.
+- **Growth with a store.** Each `impulse`, `drop` and `body` call is kept for the session, since
+  a seek past memory replays it and a body's description is a Rapier object, not data a store
+  takes. Without a store they go once history can no longer reach them. Every body made keeps its
+  voices in the mix for the session, dropped or not.
 - Soft bodies, cloth and ropes.

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 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 Body, type Physics, type PhysicsOptions, physics, physicsStore } from './physics.js';
 export type { RapierBody, RapierModule, RapierVector, RapierWorld } from './rapier.js';

package/dist/index.js

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

package/dist/physics.d.ts

@@ -1,4 +1,4 @@
-import { type Handle, type Kit, type Mix, type MixOptions, type Signal, type VoiceSpec } from '@msb235/blits';
+import { type Handle, type HistoryStore, 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';
 /**
@@ -42,10 +42,21 @@ export interface Physics<O, H> {
      * the first step before the mix has synced.
      */
     body(desc: unknown, ...colliders: unknown[]): Body<O, H>;
-    /** Syncs the mix to `now`, reads every body's controls, and steps the world. Call it in place of `mix.sync`. */
+    /** Syncs the mix to `now`, then calls `step`. Call it in place of `mix.sync`; on a transport, call `step`. */
     sync(now: number): void;
+    /**
+     * Reads every body's controls and steps the world to the mix's time. On a transport, call it each
+     * frame after the transport's `sync`.
+     */
+    step(): void;
     /** The world as it stands after the last `sync`, for reading. A change made to it is lost at the next seek. */
     world(): RapierWorld | undefined;
 }
+/**
+ * Wraps a history store so the worlds of physics mixes on a transport page their log of each
+ * frame's pushes through it, and get it back on `prepare`. Make the transport with
+ * `history: { ..., store: physicsStore(store) }`; a mix made alone wraps its own store.
+ */
+export declare function physicsStore(store: HistoryStore): HistoryStore;
 /** Makes a mix that holds a Rapier world, stepped on its `stepMs` clock and replayed by its history. */
 export declare function physics<O extends Pose2 | Pose3, H extends object = Record<string, never>>(kit: Kit<O>, opts: PhysicsOptions<H>): Physics<O, H>;

package/dist/physics.js

@@ -1,19 +1,51 @@
-import { mix, patch, } from '@msb235/blits';
+import { mix, patch, watched, } from '@msb235/blits';
 import { dimsOf } from './rapier.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';
+const paging = new WeakMap();
+/**
+ * Wraps a history store so the worlds of physics mixes on a transport page their log of each
+ * frame's pushes through it, and get it back on `prepare`. Make the transport with
+ * `history: { ..., store: physicsStore(store) }`; a mix made alone wraps its own store.
+ */
+export function physicsStore(store) {
+    const worlds = new Set();
+    const wrapped = {
+        page: (out) => store.page(out),
+        cut: (seq) => store.cut(seq),
+        async load(t) {
+            const all = await store.load(t);
+            for (const w of worlds) {
+                // 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 === w.name && r.stream === 'snap' && r.subject === 'world' && r.at < from)
+                        from = r.at;
+                w.restore(from < t ? await store.load(from) : all, from);
+            }
+            return all.filter((r) => !(r.stream === 'host' && r.subject === FRAMES));
+        },
+    };
+    paging.set(wrapped, worlds);
+    return wrapped;
+}
 /** 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 stepMs = rest.stepMs ?? 1000 / 60;
-    const name = rest.name ?? '';
-    const history = rest.history;
-    const store = history?.store;
+    const name = rest.name ?? 'physics';
+    const transport = rest.transport;
+    // A mix naming no history keeps the one a debugger gives mixes made from now on.
+    const history = transport === undefined ? (rest.history ?? watched().history) : transport.history;
+    const outer = history?.store;
+    if (outer !== undefined && transport !== undefined && !paging.has(outer))
+        throw new Error("blits-rapier: a physics mix on a transport with a history store needs the transport's store made with physicsStore(store), so the world's frames page with it");
+    const store = outer === undefined ? undefined : transport === undefined ? physicsStore(outer) : outer;
     // 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.
@@ -38,26 +70,17 @@ export function physics(kit, opts) {
             .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));
-        },
-    };
+    if (store !== undefined)
+        paging.get(store)?.add({ ours, restore, name });
     // 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 } } : {}),
+        ...(store !== undefined && transport === undefined
+            ? { history: { ...history, store } }
+            : {}),
         stepMs,
+        name,
         keyOf: (subject) => keys.get(subject),
     });
     const log = [];
@@ -138,7 +161,10 @@ export function physics(kit, opts) {
     const WORLD = {};
     keys.set(WORLD, 'world');
     let started = false;
-    const simulated = patch(0, (_p, subject) => {
+    const simulated = patch(0, (_p, subject, setting) => {
+        // A read at another time sees the world as it stands; see the README.
+        if (setting.timestamp === m.now)
+            fresh();
         const handle = live?.handles.get(subject.key);
         if (live === undefined || handle === undefined)
             return {};
@@ -182,12 +208,116 @@ export function physics(kit, opts) {
         return holds;
     };
     let next = 0;
+    // The frame, mix time and host timestamp of the last `step`, the first frame after a seek it
+    // noticed, and the frame `live` was read in. A seek comes and goes without the driver hearing.
+    let lastSeq;
+    let lastAt = Number.NEGATIVE_INFINITY;
+    let lastTs = Number.NaN;
+    let soughtSeq = Number.NEGATIVE_INFINITY;
+    let liveSeq = Number.NaN;
+    let startAt = Number.NaN;
+    const sought = () => lastSeq !== undefined && history?.tape !== undefined && (m.seq > lastSeq + 1 || m.now < lastAt);
+    /** Reads the world at the time sought after seeks since the last step, with no sync since. */
+    const fresh = () => {
+        if (lastSeq === undefined ||
+            history?.tape === undefined ||
+            liveSeq === m.seq ||
+            m.timestamp !== lastTs)
+            return;
+        m.probe(WORLD);
+        live = seen;
+        liveSeq = m.seq;
+    };
+    /** Logs a call, letting go of the calls logged ahead of it before a seek, as the mix's tape does. */
+    const call = (entry) => {
+        if (sought())
+            soughtSeq = lastSeq + 1;
+        const from = entry.at - stepMs / 2;
+        for (let i = log.length - 1; i >= 0 && log[i].at >= from; i--)
+            if (log[i].seq < soughtSeq)
+                log.splice(i, 1);
+        insert(log, entry);
+    };
+    const step = () => {
+        // Cued before the mix has a time, the world would catch up from mix time 0 on its first step.
+        if (!started) {
+            started = true;
+            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.now;
+        const seq = m.seq;
+        if (Number.isNaN(startAt))
+            startAt = at;
+        // This frame stands for the frames logged after where the mix stood before it, up to its own
+        // time. Those ahead stay for a seek forward, which replays them as the mix's tape does its calls.
+        let before = lastAt;
+        if (sought()) {
+            before = m.project({ frame: seq - 1 }).timestamp;
+            soughtSeq = lastSeq + 1;
+            holding = {};
+            held.clear();
+        }
+        let end = pushLog.length;
+        while (end > 0 && pushLog[end - 1].at > at)
+            end--;
+        let start = end;
+        while (start > 0 &&
+            (pushLog[start - 1].at > before || pushLog[start - 1].at === at))
+            start--;
+        pushLog.splice(start, end - start, { at, seq, pushes, holds: holding, goals });
+        lastSeq = seq;
+        lastAt = at;
+        lastTs = m.timestamp;
+        let old = 0;
+        while (old < pushLog.length - 1 && pushLog[old + 1].at < at - keep)
+            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;
+        liveSeq = seq;
+        // Without a store, calls older than any copy a replay starts from are in every copy already,
+        // once history no longer reaches the world's first step, which a fresh world replays from.
+        const reach = Math.min(at, live?.t ?? at) - keep - stepMs;
+        if (store === undefined && reach > startAt) {
+            let n = 0;
+            while (n < log.length && log[n].at < reach)
+                n++;
+            if (n > 0)
+                log.splice(0, n);
+        }
+        holding = holdsAt(at);
+    };
     return {
         mix: m,
         role: ROLE,
         body(desc, ...colliders) {
             const key = next++;
-            insert(log, { at: now(), key, kind: 'add', desc, colliders });
+            call({ at: now(), seq: m.seq, key, kind: 'add', desc, colliders });
             const controls = {};
             keys.set(controls, `controls ${key}`);
             const own = (spec, subject) => {
@@ -209,10 +339,8 @@ export function physics(kit, opts) {
                     driven.add(body);
                     return own(spec, controls);
                 },
-                impulse: (v) => insert(log, { at: now(), key, kind: 'impulse', v: [...v] }),
-                drop: () => {
-                    insert(log, { at: now(), key, kind: 'drop' });
-                },
+                impulse: (v) => call({ at: now(), seq: m.seq, key, kind: 'impulse', v: [...v] }),
+                drop: () => call({ at: now(), seq: m.seq, key, kind: 'drop' }),
             };
             keys.set(body, `body ${key}`);
             body.simulated = m.cue({
@@ -224,57 +352,15 @@ export function physics(kit, opts) {
             return body;
         },
         sync(t) {
+            if (transport !== undefined)
+                throw new Error('blits-rapier: this physics plays on a transport: sync the transport, then call step()');
             m.sync(t);
-            // Cued before the mix has a time, the world would catch up from mix time 0 on its first step.
-            if (!started) {
-                started = true;
-                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.now;
-            let back = false;
-            while (pushLog.length > 0 && pushLog[pushLog.length - 1].at >= at) {
-                pushLog.pop();
-                back = true;
-            }
-            // A seek back leaves the holds read before it, and their speeds, behind.
-            if (back) {
-                holding = {};
-                held.clear();
-            }
-            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++;
-            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);
+            step();
+        },
+        step,
+        world: () => {
+            fresh();
+            return live === undefined ? undefined : worldOf(live, rapier);
         },
-        world: () => (live === undefined ? undefined : worldOf(live, rapier)),
     };
 }

package/dist/world.d.ts

@@ -11,23 +11,24 @@ export interface State {
     /** The mix time of the last step, NaN before the first. */
     t: number;
 }
-/** Something done to the world at a mix time, applied by whichever step reaches it, on every replay. */
+/**
+ * Something done to the world at a mix time, applied by whichever step reaches it, on every
+ * replay. `seq` is the frame the host made the call in.
+ */
 export type Entry = {
     at: number;
+    seq: number;
     key: number;
+} & ({
     kind: 'add';
     desc: unknown;
     colliders: readonly unknown[];
 } | {
-    at: number;
-    key: number;
     kind: 'drop';
 } | {
-    at: number;
-    key: number;
     kind: 'impulse';
     v: readonly number[];
-};
+});
 /** The state's world, rebuilt from its snapshot where it has none yet. */
 export declare function worldOf(state: State, rapier: RapierModule): RapierWorld;
 /** A copy sharing nothing with `state`, holding the world as a snapshot. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits-rapier",
-  "version": "0.4.0",
+  "version": "0.5.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.19.0",
+    "@msb235/blits": "^0.20.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.19.0"
+    "@msb235/blits": "0.20.0"
   },
   "peerDependenciesMeta": {
     "@dimforge/rapier2d-compat": {