@msb235/blits-rapier 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.2.0
+
+### Breaking
+
+- `@msb235/blits` is a peer at `^0.17.0`, where it was `^0.16.1`. Built and tested against engine
+  0.17.0; nothing here uses what that release changed.
+
+### Added
+
+- `physics` takes `weight`, a number or a signal, for every body's simulated voice. A signal hands
+  bodies between physics and authored poses with nothing written from the frame loop. Fading
+  `simulated` out ended it for good, so a body could not be handed back.
+
+### Fixed
+
+- A body handed back to physics starts where it was shown, at the speed it was shown moving. The
+  world went on simulating it while an authored voice held it, so it jumped back to wherever the
+  simulation had taken it, such as against a wall that a push had sent it to.
+
 ## 0.1.0
 
 ### Added

package/README.md

@@ -46,11 +46,14 @@ const { position, rotation } = sim.mix.probe(box);
   are read before the world steps and the pose after, which is why they are two subjects.
 - **`body.drive(spec)`** cues a voice on the controls; its weight scales the push.
   **`body.cue(spec)`** cues one on the pose. Neither spec names `subjects`.
-- **`body.simulated`** is the `Handle` of the voice that shows the body where the world puts it, at
-  weight 1, in the role `sim.role`. A voice cued in that role is an alternative to the simulation,
-  and the two crossfade by weight: fade `simulated` out and an authored pose in, and a body settles
-  from physics into a scripted place. A voice outside the role adds on top of wherever physics has
-  it.
+- **`body.simulated`** is the `Handle` of the voice that shows the body where the world puts it, in
+  the role `sim.role`, at the weight `physics` was given (default 1). A voice cued in that role is
+  an alternative to the simulation, and the two crossfade by weight. To hand bodies to authored
+  poses and back, give `physics` a `weight` signal and the authored voices its complement, such as
+  `share(k, 0, 2)` and `share(k, 1, 2)` of one `level`. While a body's simulated voice is at weight 0
+  and a voice in the role holds it, the world puts the body where it is shown, moving as fast as
+  the shown pose moves, so handing it back starts the simulation from there. A voice outside the
+  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.

package/dist/physics.d.ts

@@ -1,4 +1,4 @@
-import { type Handle, type Kit, type Mix, type MixOptions, type VoiceSpec } from '@msb235/blits';
+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. */
@@ -7,13 +7,18 @@ export interface PhysicsOptions<H> extends MixOptions<H> {
     rapier: RapierModule;
     /** Default: `[0, -9.81]` or `[0, -9.81, 0]`. */
     gravity?: readonly number[];
+    /**
+     * The weight of every body's simulated voice, a signal reading each body. A signal hands a body
+     * between physics and authored motion with no weight written from the frame loop. Default 1.
+     */
+    weight?: number | Signal<object, H>;
 }
 /** A rigid body: the mix's subject for its pose, with its controls beside it. */
 export interface Body<O, H> {
     readonly key: number;
     /** The subject whose `force` and `torque` push the body, read before the world steps. */
     readonly controls: object;
-    /** The voice that shows the body where the world puts it, in `Physics.role`. Weight 1. */
+    /** The voice that shows the body where the world puts it, in `Physics.role`, at `PhysicsOptions.weight`. */
     readonly simulated: Handle<object>;
     /** Cues a voice on the body's pose. In `Physics.role` it is an alternative to the simulation; outside it, it adds on top. */
     cue(spec: Omit<VoiceSpec<object, O, H>, 'subjects'>): Handle<object>;

package/dist/physics.js

@@ -2,9 +2,10 @@ import { mix, patch, } from '@msb235/blits';
 import { dimsOf } from './rapier.js';
 import { applyLog, copy, insert, worldOf } from './world.js';
 const ROLE = 'physics';
+const copyOf = (r) => typeof r === 'number' ? r : [...r];
 /** 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, ...rest } = 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 });
@@ -14,7 +15,7 @@ export function physics(kit, opts) {
     // at or after the step's end, looked up half a step early since replayed times can round apart.
     const pushLog = [];
     const keep = rest.history?.ms ?? 0;
-    const pushesAt = (t) => {
+    const frameAt = (t) => {
         let lo = 0;
         let hi = pushLog.length;
         while (lo < hi) {
@@ -24,7 +25,7 @@ export function physics(kit, opts) {
             else
                 hi = mid;
         }
-        return (pushLog[lo] ?? pushLog[pushLog.length - 1])?.pushes ?? {};
+        return pushLog[lo] ?? pushLog[pushLog.length - 1];
     };
     let seen;
     let live;
@@ -49,7 +50,15 @@ export function physics(kit, opts) {
             const w = worldOf(s, rapier);
             w.timestep = dt / 1000;
             applyLog(s, w, log, setting.timestamp, dt / 2, dims);
-            const pushes = pushesAt(setting.timestamp - dt / 2);
+            const frame = frameAt(setting.timestamp - dt / 2);
+            const pushes = frame?.pushes ?? {};
+            const holds = frame?.holds ?? {};
+            for (const k in holds) {
+                const handle = s.handles.get(+k);
+                const h = holds[k];
+                if (handle !== undefined && h !== undefined)
+                    dims.place(w.getRigidBody(handle), h.now, h.before, h.dt);
+            }
             const pushed = [];
             for (const k in pushes) {
                 const handle = s.handles.get(+k);
@@ -82,7 +91,40 @@ export function physics(kit, opts) {
     }, { writes: ['position', 'rotation'] });
     const now = () => (Number.isNaN(m.timestamp) ? Number.NEGATIVE_INFINITY : m.timestamp);
     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();
+    const held = new Map();
     const out = m.pose();
+    const shown = m.pose();
+    // Read at the end of each frame, for the next frame's steps to apply.
+    let holding = {};
+    const holdsAt = (at) => {
+        const holds = {};
+        for (const [body, voices] of authored) {
+            const playing = voices.filter((v) => v.state !== 'done');
+            if (playing.length === 0) {
+                authored.delete(body);
+                held.delete(body);
+                continue;
+            }
+            if (playing.length < voices.length)
+                authored.set(body, playing);
+            const p = m.probe(body, shown);
+            // Shown with none of the simulation, the body is put where it is shown, so the simulation
+            // takes it back from there.
+            if (!live?.handles.has(body.key) ||
+                body.simulated.weightOf(body) > 0 ||
+                !playing.some((v) => v.weightOf(body) > 0)) {
+                held.delete(body);
+                continue;
+            }
+            const now = { position: [...p.position], rotation: copyOf(p.rotation) };
+            const last = held.get(body);
+            holds[body.key] = { now, before: last?.pose, dt: last === undefined ? 0 : at - last.at };
+            held.set(body, { pose: now, at });
+        }
+        return holds;
+    };
     let next = 0;
     return {
         mix: m,
@@ -100,7 +142,12 @@ export function physics(kit, opts) {
                 key,
                 controls,
                 simulated: undefined,
-                cue: (spec) => own(spec, body),
+                cue: (spec) => {
+                    const h = own(spec, body);
+                    if (spec.role === ROLE)
+                        authored.set(body, [...(authored.get(body) ?? []), h]);
+                    return h;
+                },
                 drive: (spec) => {
                     driven.add(body);
                     return own(spec, controls);
@@ -114,6 +161,7 @@ export function physics(kit, opts) {
                 patch: simulated,
                 subjects: [body],
                 role: ROLE,
+                ...(weight === undefined ? {} : { weight }),
             });
             return body;
         },
@@ -132,9 +180,17 @@ export function physics(kit, opts) {
                     pushes[body.key] = [...p.force, ...torque];
             }
             const at = m.timestamp;
-            while (pushLog.length > 0 && pushLog[pushLog.length - 1].at >= at)
+            let back = false;
+            while (pushLog.length > 0 && pushLog[pushLog.length - 1].at >= at) {
                 pushLog.pop();
-            pushLog.push({ at, pushes });
+                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++;
@@ -142,6 +198,7 @@ export function physics(kit, opts) {
                 pushLog.splice(0, old);
             m.probe(WORLD);
             live = seen;
+            holding = holdsAt(at);
         },
         world: () => (live === undefined ? undefined : worldOf(live, rapier)),
     };

package/dist/rapier.d.ts

@@ -19,6 +19,10 @@ export interface RapierBody {
     applyImpulse(impulse: RapierVector, wake: boolean): void;
     resetForces(wake: boolean): void;
     resetTorques(wake: boolean): void;
+    setTranslation(v: RapierVector, wake: boolean): void;
+    setRotation(r: never, wake: boolean): void;
+    setLinvel(v: RapierVector, wake: boolean): void;
+    setAngvel(v: never, wake: boolean): void;
 }
 /** What blits-rapier uses of a Rapier world, in either build. */
 export interface RapierWorld {
@@ -50,6 +54,13 @@ export interface Dims {
     rotation(body: RapierBody): number | number[];
     /** Adds `torque`, a number in 2D and three numbers in 3D. */
     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;
+}
+/** A body's position and rotation as the channels hold them. */
+export interface Placed {
+    position: readonly number[];
+    rotation: number | readonly number[];
 }
 /** The 3D build where the module has `Vector3`, else the 2D. */
 export declare function dimsOf(rapier: RapierModule): Dims;

package/dist/rapier.js

@@ -1,3 +1,4 @@
+const speed = (now, before, dt) => now.map((x, i) => (before === undefined || dt <= 0 ? 0 : (x - (before[i] ?? x)) / (dt / 1000)));
 const two = {
     n: 2,
     vector: (v) => ({ x: v[0] ?? 0, y: v[1] ?? 0 }),
@@ -7,6 +8,15 @@ const two = {
     },
     rotation: (b) => b.rotation(),
     torque: (b, t) => b.addTorque((typeof t === 'number' ? t : (t[0] ?? 0)), true),
+    place: (b, now, before, dt) => {
+        const r = now.rotation;
+        b.setTranslation(two.vector(now.position), true);
+        b.setRotation(r, true);
+        b.setLinvel(two.vector(speed(now.position, before?.position, dt)), true);
+        let turn = before === undefined ? 0 : r - before.rotation;
+        turn -= 2 * Math.PI * Math.round(turn / (2 * Math.PI));
+        b.setAngvel((dt > 0 ? turn / (dt / 1000) : 0), true);
+    },
 };
 const three = {
     n: 3,
@@ -20,7 +30,33 @@ const three = {
         return [q.x, q.y, q.z, q.w];
     },
     torque: (b, t) => b.addTorque(three.vector(typeof t === 'number' ? [0, 0, t] : t), true),
+    place: (b, now, before, dt) => {
+        const [x, y, z, w] = now.rotation;
+        b.setTranslation(three.vector(now.position), true);
+        b.setRotation({ x, y, z, w }, true);
+        b.setLinvel(three.vector(speed(now.position, before?.position, dt)), true);
+        b.setAngvel(three.vector(spin(now.rotation, before?.rotation, dt)), true);
+    },
 };
+/** The angular velocity turning `before` into `now` over `dt` ms, both `[x, y, z, w]`. */
+function spin(now, before, dt) {
+    if (before === undefined || dt <= 0)
+        return [0, 0, 0];
+    const [ax, ay, az, aw] = now;
+    const [bx, by, bz, bw] = before;
+    // now · conj(before), taken the short way round.
+    let x = bw * ax - bx * aw - by * az + bz * ay;
+    let y = bw * ay - by * aw - bz * ax + bx * az;
+    let z = bw * az - bz * aw - bx * ay + by * ax;
+    let w = bw * aw + bx * ax + by * ay + bz * az;
+    if (w < 0)
+        [x, y, z, w] = [-x, -y, -z, -w];
+    const s = Math.hypot(x, y, z);
+    if (s < 1e-12)
+        return [0, 0, 0];
+    const k = (2 * Math.atan2(s, w)) / s / (dt / 1000);
+    return [x * k, y * k, z * k];
+}
 /** The 3D build where the module has `Vector3`, else the 2D. */
 export function dimsOf(rapier) {
     return 'Vector3' in rapier ? three : two;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits-rapier",
-  "version": "0.1.0",
+  "version": "0.2.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.16.1",
+    "@msb235/blits": "^0.17.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.16.1"
+    "@msb235/blits": "0.17.0"
   },
   "peerDependenciesMeta": {
     "@dimforge/rapier2d-compat": {