@msb235/blits-rapier 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ 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
+
+- `@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

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.
 
@@ -65,30 +68,85 @@ 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
-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 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.
+
+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
-
-- 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.
+## 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/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 { type Body, type Physics, type PhysicsOptions, physics } from './physics.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, physicsStore } 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 { physics } from './physics.js';
+export { channels2, channels3, kinematic2, kinematic3, } from './channels.js';
+export { physics, physicsStore } 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 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';
-/** 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]`. */
@@ -39,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,20 +1,89 @@
-import { mix, patch, } from '@msb235/blits';
+import { mix, patch, watched, } 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';
+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 m = mix(kit, { ...rest, stepMs: rest.stepMs ?? 1000 / 60 });
-    const log = [];
+    const stepMs = rest.stepMs ?? 1000 / 60;
+    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.
+    // 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);
+    };
+    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,
+        ...(store !== undefined && transport === undefined
+            ? { history: { ...history, store } }
+            : {}),
+        stepMs,
+        name,
+        keyOf: (subject) => keys.get(subject),
+    });
+    const log = [];
     const frameAt = (t) => {
         let lo = 0;
         let hi = pushLog.length;
@@ -59,6 +128,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,17 +155,23 @@ 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 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 {};
         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();
@@ -126,13 +208,118 @@ 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) => {
                 if ('subjects' in spec)
                     throw new Error('blits-rapier: a body cues on itself; its spec names no subjects');
@@ -152,11 +339,10 @@ 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({
                 patch: simulated,
                 subjects: [body],
@@ -166,40 +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 = {};
-            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];
-            }
-            const at = m.timestamp;
-            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, pushes, holds: holding });
-            let old = 0;
-            while (old < pushLog.length - 1 && pushLog[old + 1].at < at - keep)
-                old++;
-            if (old > 0)
-                pushLog.splice(0, old);
-            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/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

@@ -11,27 +11,32 @@ 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. */
 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.3.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.18.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.18.0"
+    "@msb235/blits": "0.20.0"
   },
   "peerDependenciesMeta": {
     "@dimforge/rapier2d-compat": {