@driftengine/physics 4.8.1 → 4.8.3

package/README.md

@@ -5,7 +5,7 @@ kinematic sweep that resolves a moving body against a static world one axis at a
 
 **It imports no other engine package.** Together with `@driftengine/entities` that makes a
 deterministic simulation you can run with no renderer in its module graph — in Node, in a worker,
-or on a server, which is what an authoritative host needs. **45.4 KB gzipped** standalone, measured
+or on a server, which is what an authoritative host needs. **47.0 KB gzipped** standalone, measured
 by `scripts/size-gate.test.mjs` against `scripts/fixtures/size/physics-only.ts`.
 
 **`@driftengine/core` re-exports every name here**, so reaching for collision through the core

package/dist/controller.js

@@ -313,9 +313,10 @@ export class CharacterController {
          * the same clamp and air control — only the plane is given up, not the feel.
          */
         if (input.projectMove === false) {
-            this.velX = approach(this.velX, wantX, step);
-            this.velY = approach(this.velY, wantY, step);
-            this.velZ = approach(this.velZ, wantZ, step);
+            const t = approachFraction(wantX - this.velX, wantY - this.velY, wantZ - this.velZ, step);
+            this.velX = t === 1 ? wantX : this.velX + (wantX - this.velX) * t;
+            this.velY = t === 1 ? wantY : this.velY + (wantY - this.velY) * t;
+            this.velZ = t === 1 ? wantZ : this.velZ + (wantZ - this.velZ) * t;
         }
         else {
             const alongUp = this.speedAlongUp;
@@ -326,9 +327,10 @@ export class CharacterController {
             const wantTangentX = wantX - this.upX * wantIntoUp;
             const wantTangentY = wantY - this.upY * wantIntoUp;
             const wantTangentZ = wantZ - this.upZ * wantIntoUp;
-            tangentX = approach(tangentX, wantTangentX, step);
-            tangentY = approach(tangentY, wantTangentY, step);
-            tangentZ = approach(tangentZ, wantTangentZ, step);
+            const t = approachFraction(wantTangentX - tangentX, wantTangentY - tangentY, wantTangentZ - tangentZ, step);
+            tangentX = t === 1 ? wantTangentX : tangentX + (wantTangentX - tangentX) * t;
+            tangentY = t === 1 ? wantTangentY : tangentY + (wantTangentY - tangentY) * t;
+            tangentZ = t === 1 ? wantTangentZ : tangentZ + (wantTangentZ - tangentZ) * t;
             this.velX = tangentX + this.upX * alongUp;
             this.velY = tangentY + this.upY * alongUp;
             this.velZ = tangentZ + this.upZ * alongUp;
@@ -675,12 +677,18 @@ export class CharacterController {
         this.pose.qw = w * inverse;
     }
 }
-/** Move `from` toward `to` by at most `step`. */
-function approach(from, to, step) {
-    const d = to - from;
-    if (d > step)
-        return from + step;
-    if (d < -step)
-        return from - step;
-    return to;
+/**
+ * How much of the way to close a gap of `(dx, dy, dz)` this tick: exactly 1 when the gap is no
+ * longer than `step`, which the caller reads as "land on the target", and `step` of its length
+ * otherwise.
+ *
+ * **Toward the wanted velocity as a vector, by at most `step` in length.** It was one world axis at
+ * a time, each by the whole step, so a diagonal gained and lost speed √2 times as fast as a straight
+ * run while the clamp on the wanted vector kept its top speed honest — the faster diagonal lived in
+ * the acceleration. What it gives up is that an axis no longer reaches its target on its own
+ * schedule: turning from one direction to another now curves rather than squaring the corner.
+ */
+function approachFraction(dx, dy, dz, step) {
+    const gap = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    return gap <= step ? 1 : step / gap;
 }

package/dist/ragdoll.d.ts

@@ -88,7 +88,15 @@ export interface Ragdoll {
     readonly bodyOf: Int32Array;
     /** How many bones were built. */
     readonly boneCount: number;
-    /** Write the ragdoll's current shape into a pose. */
+    /**
+     * Write the ragdoll's current shape into a pose.
+     *
+     * Each joint is turned by the bone that **starts** at it, which is the joint a skinned limb
+     * follows — the forearm's body turns the elbow — and a joint with no bone below it rides the one
+     * it hangs off. Translations are the rig's own, in each parent's frame. A root's rotation is
+     * written in the frame the character's node is placed in, at `rootX`, `rootY` and `rootZ`, with
+     * no rotation of its own; a joint no bone reaches is left as the pose had it.
+     */
     writePose(out: PoseTarget): void;
     /** Steer the bodies toward a pose. Weight 1 tracks it, weight 0 goes limp. */
     drive(world: PhysicsWorld, pose: PoseTarget, weight: number): void;

package/dist/ragdoll.js

@@ -45,8 +45,32 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
         return value === undefined || !Number.isFinite(value) ? fallback : value;
     };
     const bodyOf = new Int32Array(jointCount).fill(-1);
-    /** `conj(bodyRotation) · jointWorldRotation`, so a pose can be recovered from a body. */
+    /**
+     * `conj(bodyRotation) · jointWorldRotation` for the joint a bone **ends** at, so a joint with no
+     * bone of its own below it — a fingertip, a head's tip — can ride the bone it hangs off.
+     */
     const bodyToJoint = new Float32Array(jointCount * 4);
+    /**
+     * `conj(bodyRotation) · jointWorldRotation` for the joint a bone **starts** at, indexed like
+     * `bodyOf` — by the bone's own joint — and naming its parent's rotation.
+     *
+     * **This is the joint a skinned limb follows.** A forearm's vertices are weighted to the elbow,
+     * so the elbow's rotation is what points the forearm, and the body standing along the forearm is
+     * what carries it. Reading each joint off the bone that *ends* at it — the upper arm for the
+     * elbow — drew every limb one bone late: a hand 0.47 m from its body in a doll synced and never
+     * stepped, reported from a game. A bone is rigid in its start joint's frame, so the relation
+     * captured at rest holds for as long as the doll does.
+     */
+    const bodyToStart = new Float32Array(jointCount * 4);
+    /** The first bone starting at each joint, by that bone's own index, or −1 where none does. */
+    const startBone = new Int32Array(jointCount).fill(-1);
+    /**
+     * Each joint's translation in its parent's frame at rest, which is what a pose holds.
+     *
+     * **In the parent's frame, not the world's.** It was the world offset between the two, which is
+     * the same number only where the parent is unrotated at rest — true of every chain this module's
+     * tests were built from, and of no rig a game loads.
+     */
     const localRest = new Float32Array(jointCount * 3);
     const restRotation = new Float32Array(jointCount * 4);
     /**
@@ -58,6 +82,11 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
      * the bones meet.
      */
     const halfOf = new Float32Array(jointCount);
+    /**
+     * Each bone's rig offset over its length: 1 for a rig at unit scale, and what turns a length in
+     * metres back into the parent's own units where the rig is scaled.
+     */
+    const restScale = new Float32Array(jointCount).fill(1);
     let boneCount = 0;
     let firstBone = -1;
     /** Half the first bone's length, which is how far its head sits from the body's centre. */
@@ -73,9 +102,7 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
         const tx = worldMatrices[j * 16 + 12] ?? 0;
         const ty = worldMatrices[j * 16 + 13] ?? 0;
         const tz = worldMatrices[j * 16 + 14] ?? 0;
-        localRest[j * 3] = tx - hx;
-        localRest[j * 3 + 1] = ty - hy;
-        localRest[j * 3 + 2] = tz - hz;
+        intoParentFrame(worldMatrices, p, tx - hx, ty - hy, tz - hz, localRest, j * 3);
         const dx = tx - hx;
         const dy = ty - hy;
         const dz = tz - hz;
@@ -101,8 +128,18 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
         });
         bodyOf[j] = body;
         halfOf[j] = length / 2;
-        // What takes the body's rotation back to the joint's, captured while both are at rest.
+        const rx = localRest[j * 3] ?? 0;
+        const ry = localRest[j * 3 + 1] ?? 0;
+        const rz = localRest[j * 3 + 2] ?? 0;
+        restScale[j] = Math.sqrt(rx * rx + ry * ry + rz * rz) / length;
+        // What takes the body's rotation back to each of its two joints', captured at rest. Parents
+        // come before children in a rig, so the start joint's rotation is already read.
         multiplyConjugate(TMP, restRotation, j * 4, bodyToJoint, j * 4);
+        if (p >= j)
+            matrixRotation(worldMatrices, p, restRotation, p * 4);
+        multiplyConjugate(TMP, restRotation, p * 4, bodyToStart, j * 4);
+        if ((startBone[p] ?? -1) < 0)
+            startBone[p] = j;
         boneCount++;
         if (firstBone < 0) {
             firstBone = j;
@@ -111,15 +148,67 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
             firstBoneHalf = length / 2;
         }
     }
+    /*
+     * **A bone too short for a body is transparent.** Each joint resolves to the nearest one at or
+     * above it that a body ends at, or to its root: what hangs from a collar sitting on the chest
+     * joint hangs from the bone that ends at the chest. A rig puts one joint exactly on another as
+     * often as not, and a bone under `minLength` gets no body, so until 4.8.3 the spine above such a
+     * collar was jointed to nothing and collided with every bone it met there — compared by index,
+     * they shared no end. **What it gives up** is the skipped bone's own length, under `minLength`,
+     * which the joints below absorb exactly at rest: see `restAnchor`.
+     */
+    const attach = new Int32Array(jointCount);
+    for (let j = 0; j < jointCount; j++) {
+        let a = j;
+        while ((bodyOf[a] ?? -1) < 0 && (parents[a] ?? -1) >= 0)
+            a = parents[a] ?? -1;
+        attach[j] = a;
+    }
+    /** Where a bone's parent end really hangs: its parent joint, seen through any bone too short. */
+    const hangsFrom = (j) => {
+        const p = parents[j] ?? -1;
+        return p < 0 ? -1 : (attach[p] ?? p);
+    };
+    /**
+     * Bone `j`'s body-frame point at joint `at`'s rest position, into `REST_ANCHOR`. Where `at` is
+     * the bone's own parent joint this is its head, `(0, -half, 0)`, exactly as before; through a
+     * short bone it is where the two bones meet at rest, so a joint anchored there moves nothing on
+     * the first tick.
+     */
+    const restAnchor = (j, at) => {
+        const p = parents[j] ?? -1;
+        if (at === p) {
+            REST_ANCHOR[0] = 0;
+            REST_ANCHOR[1] = -(halfOf[j] ?? 0);
+            REST_ANCHOR[2] = 0;
+            return;
+        }
+        const body = bodyOf[j] ?? 0;
+        const dx = (worldMatrices[at * 16 + 12] ?? 0) - (world.bodies.posX[body] ?? 0);
+        const dy = (worldMatrices[at * 16 + 13] ?? 0) - (world.bodies.posY[body] ?? 0);
+        const dz = (worldMatrices[at * 16 + 14] ?? 0) - (world.bodies.posZ[body] ?? 0);
+        /* Into the body's frame: turned by the conjugate of its rotation. */
+        const ux = -(world.bodies.rotX[body] ?? 0);
+        const uy = -(world.bodies.rotY[body] ?? 0);
+        const uz = -(world.bodies.rotZ[body] ?? 0);
+        const w = world.bodies.rotW[body] ?? 1;
+        const cx = uy * dz - uz * dy;
+        const cy = uz * dx - ux * dz;
+        const cz = ux * dy - uy * dx;
+        REST_ANCHOR[0] = dx + 2 * (w * cx + (uy * cz - uz * cy));
+        REST_ANCHOR[1] = dy + 2 * (w * cy + (uz * cx - ux * cz));
+        REST_ANCHOR[2] = dz + 2 * (w * cz + (ux * cy - uy * cx));
+    };
     // Joint each bone to its parent's bone, at the shared end.
     for (let j = 0; j < jointCount; j++) {
         const body = bodyOf[j] ?? -1;
         if (body < 0)
             continue;
-        const p = parents[j] ?? -1;
+        const p = hangsFrom(j);
         const parentBody = p >= 0 ? (bodyOf[p] ?? -1) : -1;
         if (parentBody < 0)
             continue;
+        restAnchor(j, p);
         world.addJoint({
             type: JOINT_CONE_TWIST,
             bodyA: parentBody,
@@ -146,7 +235,9 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
              * so the first tick still moves nothing.
              */
             anchorAY: halfOf[p] ?? 0,
-            anchorBY: -(halfOf[j] ?? 0),
+            anchorBX: REST_ANCHOR[0],
+            anchorBY: REST_ANCHOR[1],
+            anchorBZ: REST_ANCHOR[2],
         });
     }
     /*
@@ -163,7 +254,7 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
         const body = bodyOf[j] ?? -1;
         if (body < 0)
             continue;
-        const p = parents[j] ?? -1;
+        const p = hangsFrom(j);
         if (p < 0 || (bodyOf[p] ?? -1) >= 0)
             continue;
         const first = firstUnder[p] ?? -1;
@@ -171,6 +262,11 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
             firstUnder[p] = j;
             continue;
         }
+        restAnchor(first, p);
+        const ax = REST_ANCHOR[0];
+        const ay = REST_ANCHOR[1];
+        const az = REST_ANCHOR[2];
+        restAnchor(j, p);
         world.addJoint({
             type: JOINT_CONE_TWIST,
             bodyA: bodyOf[first] ?? 0,
@@ -178,8 +274,12 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
             swingCos: limitAt(swingCos, Math.SQRT1_2, j),
             twistSin: limitAt(twistSin, 0.3826834323650898, j),
             axisY: 1,
-            anchorAY: -(halfOf[first] ?? 0),
-            anchorBY: -(halfOf[j] ?? 0),
+            anchorAX: ax,
+            anchorAY: ay,
+            anchorAZ: az,
+            anchorBX: REST_ANCHOR[0],
+            anchorBY: REST_ANCHOR[1],
+            anchorBZ: REST_ANCHOR[2],
         });
     }
     /*
@@ -202,40 +302,80 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
                 world.ignorePair(body, other);
                 continue;
             }
-            const pj = parents[j] ?? -1;
-            const pk = parents[k] ?? -1;
+            /* Seen through any bone too short for a body, which is where they really meet. */
+            const pj = hangsFrom(j);
+            const pk = hangsFrom(k);
             /* Jointed, either way round, or two bones hanging off the same parent joint: siblings share
                a head the way a parent and child share a point, so they overlap there too. */
             if (pk === j || pj === k || (pj === pk && pj >= 0))
                 world.ignorePair(body, other);
         }
     }
+    /**
+     * One joint's world rotation, from the body that speaks for it: the first bone starting at the
+     * joint, or — for a joint with none below it, a fingertip — the bone it hangs off, which it then
+     * rides rigidly. False where neither exists and nothing can be said.
+     */
+    const recoverJoint = (w, j, out, at) => {
+        const start = startBone[j] ?? -1;
+        if (start >= 0) {
+            readBodyRotation(w, bodyOf[start] ?? 0, TMP);
+            multiplyInto(TMP, bodyToStart, start * 4, out, at);
+            return true;
+        }
+        const own = bodyOf[j] ?? -1;
+        if (own < 0)
+            return false;
+        readBodyRotation(w, own, TMP);
+        multiplyInto(TMP, bodyToJoint, j * 4, out, at);
+        return true;
+    };
     const root = firstBone;
     return {
         bodyOf,
         boneCount,
         writePose(out) {
+            /*
+             * Two passes, because a joint's local rotation needs its parent's world rotation and a rig
+             * is not obliged to list parents first. The first recovers every joint a body speaks for.
+             */
+            for (let j = 0; j < jointCount; j++)
+                KNOWN[j] = recoverJoint(world, j, WORLD_ROT, j * 4) ? 1 : 0;
             for (let j = 0; j < jointCount; j++) {
-                const body = bodyOf[j] ?? -1;
-                const p = parents[j] ?? -1;
-                if (body < 0) {
-                    // No bone: leave the joint as the pose already had it.
+                if (KNOWN[j] !== 1) {
+                    // No bone at either end: leave the joint as the pose already had it.
                     continue;
                 }
-                // The joint's world rotation, recovered from the body's.
-                readBodyRotation(world, body, TMP);
-                multiplyInto(TMP, bodyToJoint, j * 4, WORLD_ROT, j * 4);
-                const parentBody = p >= 0 ? (bodyOf[p] ?? -1) : -1;
-                if (parentBody >= 0) {
+                const p = parents[j] ?? -1;
+                if (p >= 0 && KNOWN[p] === 1) {
                     conjugateMultiply(WORLD_ROT, p * 4, WORLD_ROT, j * 4, out.rotation, j * 4);
                 }
                 else {
+                    /* A root, or a joint whose parent no bone speaks for: its rotation in the frame the
+                       caller places the character's node in, which `rootX` and its two siblings answer. */
                     copy4(WORLD_ROT, j * 4, out.rotation, j * 4);
                 }
-                // Bones are rigid, so translation stays what the rig was built with.
-                out.translation[j * 3] = localRest[j * 3] ?? 0;
-                out.translation[j * 3 + 1] = localRest[j * 3 + 1] ?? 0;
-                out.translation[j * 3 + 2] = localRest[j * 3 + 2] ?? 0;
+                if (p < 0)
+                    continue;
+                /*
+                 * **Placed along its own bone as the body holds it**, at the rig's length: the body's +y,
+                 * in the parent's frame. For the first bone under a joint that is the rig's offset exactly,
+                 * because the joint turns with that body; for a second or third — a thigh beside the spine,
+                 * a clavicle beside the neck — it is what keeps the branch on its own body. Placed by the
+                 * rig's offset, every branch but the first was swung by the first one's turn: reported as
+                 * a foot 0.24 m and an arm 0.17 m from their bodies after a fall. A joint with no bone of
+                 * its own keeps the rig's offset. **What would make it wrong** is a bone the body
+                 * stretches, which a rigid capsule cannot.
+                 */
+                const body = bodyOf[j] ?? -1;
+                if (body >= 0 && KNOWN[p] === 1) {
+                    boneInParentFrame(world, body, 2 * (halfOf[j] ?? 0) * (restScale[j] ?? 1), WORLD_ROT, p * 4, out.translation, j * 3);
+                }
+                else {
+                    out.translation[j * 3] = localRest[j * 3] ?? 0;
+                    out.translation[j * 3 + 1] = localRest[j * 3 + 1] ?? 0;
+                    out.translation[j * 3 + 2] = localRest[j * 3 + 2] ?? 0;
+                }
                 out.scale[j * 3] = 1;
                 out.scale[j * 3 + 1] = 1;
                 out.scale[j * 3 + 2] = 1;
@@ -245,27 +385,32 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
             if (weight <= 0)
                 return;
             const k = weight > 1 ? 1 : weight;
-            for (let j = 0; j < jointCount; j++) {
-                const body = bodyOf[j] ?? -1;
+            for (let c = 0; c < jointCount; c++) {
+                const body = bodyOf[c] ?? -1;
                 if (body < 0)
                     continue;
-                const p = parents[j] ?? -1;
-                const parentBody = p >= 0 ? (bodyOf[p] ?? -1) : -1;
+                /*
+                 * **A bone is steered by the joint it starts at**, the one whose rotation points it — the
+                 * forearm by the elbow — which is the same joint `writePose` reads it back as. Steered by
+                 * the joint it ends at, a pose's elbow bend went into the upper arm.
+                 */
+                const j = parents[c] ?? -1;
+                if (j < 0)
+                    continue;
                 /*
                  * The target is the pose's local rotation composed onto the parent's *current* world
                  * rotation, so a driven limb follows the animation relative to a body that may itself have
                  * been knocked aside — which is what a partial ragdoll is.
                  */
-                if (parentBody >= 0) {
-                    readBodyRotation(w, parentBody, TMP);
-                    multiplyInto(TMP, bodyToJoint, p * 4, PARENT_ROT, 0);
+                const p = parents[j] ?? -1;
+                if (p >= 0 && recoverJoint(w, p, PARENT_ROT, 0)) {
                     multiplyRaw(PARENT_ROT, 0, pose.rotation, j * 4, TARGET_ROT, 0);
                 }
                 else {
                     copy4(pose.rotation, j * 4, TARGET_ROT, 0);
                 }
                 readBodyRotation(w, body, TMP);
-                multiplyInto(TMP, bodyToJoint, j * 4, CURRENT_ROT, 0);
+                multiplyInto(TMP, bodyToStart, c * 4, CURRENT_ROT, 0);
                 // Twice the vector part of target · conj(current) is the rotation that closes the gap.
                 conjugateMultiply(CURRENT_ROT, 0, TARGET_ROT, 0, ERROR_ROT, 0);
                 let ex = ERROR_ROT[0] ?? 0;
@@ -301,22 +446,23 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
                 w.bodies.posY[body] = (hy + ty) / 2;
                 w.bodies.posZ[body] = (hz + tz) / 2;
                 /*
-                 * The rotation is taken from the *bone*, the same way the build took it: the capsule
-                 * stands along y, so the body is turned to put its y along the bone. Taking it from the
-                 * joint's world matrix instead would be wrong wherever a rig's bind orientation is not
-                 * the bone direction, which is most rigs.
+                 * **The rotation is the start joint's, carried through the relation captured at rest**,
+                 * which is the inverse of what `writePose` reads: `jointRotation · conj(bodyToStart)`.
+                 *
+                 * It was the shortest arc from +y onto the bone, which points the capsule correctly and
+                 * throws away the bone's twist about its own length — so a joint with two bones below it, a
+                 * wrist with a thumb beside the fingers, came back turned about the first and put the
+                 * second somewhere else. The joint's world matrix alone would be wrong too, wherever a
+                 * rig's bind orientation is not the bone direction, which is most rigs; the captured
+                 * relation is what absorbs that. **What would make it wrong** is a pose that stretches a
+                 * bone, which a ragdoll's rigid bones cannot follow either way.
                  */
-                const dx = tx - hx;
-                const dy = ty - hy;
-                const dz = tz - hz;
-                const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
-                if (length > 0) {
-                    alignYTo(dx / length, dy / length, dz / length, TMP);
-                    w.bodies.rotX[body] = TMP[0] ?? 0;
-                    w.bodies.rotY[body] = TMP[1] ?? 0;
-                    w.bodies.rotZ[body] = TMP[2] ?? 0;
-                    w.bodies.rotW[body] = TMP[3] ?? 1;
-                }
+                matrixRotation(worldMatrices, p, START_ROT, 0);
+                multiplyByConjugate(START_ROT, bodyToStart, j * 4, TMP);
+                w.bodies.rotX[body] = TMP[0] ?? 0;
+                w.bodies.rotY[body] = TMP[1] ?? 0;
+                w.bodies.rotZ[body] = TMP[2] ?? 0;
+                w.bodies.rotW[body] = TMP[3] ?? 1;
                 /* At rest, which is the half that makes it a reaction rather than a continuation: a body
                    carrying the speed of a two-second fall is thrown across the character the instant it
                    is written into the pose. */
@@ -341,6 +487,11 @@ export function ragdollFromBones(world, parents, worldMatrices, options = {}) {
     };
 }
 const WORLD_ROT = new Float32Array(256 * 4);
+/** Whether `writePose` recovered each joint's rotation this call: 1 if a body speaks for it. */
+const KNOWN = new Uint8Array(256);
+const START_ROT = new Float32Array(4);
+/** One joint anchor in a body's own frame, filled by `restAnchor` and read at once. */
+const REST_ANCHOR = new Float64Array(3);
 const PARENT_ROT = new Float32Array(4);
 const TARGET_ROT = new Float32Array(4);
 const CURRENT_ROT = new Float32Array(4);
@@ -454,6 +605,76 @@ function alignYTo(dx, dy, dz, out) {
     out[2] = az / len;
     out[3] = w / len;
 }
+/**
+ * A world-space offset from joint `p`, expressed in `p`'s own frame: the inverse of the matrix's
+ * upper 3x3 applied to it, so a scaled joint is undone as well as a rotated one.
+ */
+function intoParentFrame(m, p, dx, dy, dz, out, at) {
+    const o = p * 16;
+    const a = m[o] ?? 1;
+    const b = m[o + 4] ?? 0;
+    const c = m[o + 8] ?? 0;
+    const d = m[o + 1] ?? 0;
+    const e = m[o + 5] ?? 1;
+    const f = m[o + 9] ?? 0;
+    const g = m[o + 2] ?? 0;
+    const h = m[o + 6] ?? 0;
+    const i = m[o + 10] ?? 1;
+    const ei = e * i - f * h;
+    const fg = f * g - d * i;
+    const dh = d * h - e * g;
+    const det = a * ei + b * fg + c * dh;
+    if (Math.abs(det) < 1e-12) {
+        out[at] = dx;
+        out[at + 1] = dy;
+        out[at + 2] = dz;
+        return;
+    }
+    const inv = 1 / det;
+    out[at] = (ei * dx + (c * h - b * i) * dy + (b * f - c * e) * dz) * inv;
+    out[at + 1] = (fg * dx + (a * i - c * g) * dy + (c * d - a * f) * dz) * inv;
+    out[at + 2] = (dh * dx + (b * g - a * h) * dy + (a * e - b * d) * dz) * inv;
+}
+/** `a · conj(b)` into a Float64 quaternion, for turning a joint's rotation back into a body's. */
+function multiplyByConjugate(a, b, bAt, out) {
+    const ax = a[0] ?? 0;
+    const ay = a[1] ?? 0;
+    const az = a[2] ?? 0;
+    const aw = a[3] ?? 1;
+    const bx = -(b[bAt] ?? 0);
+    const by = -(b[bAt + 1] ?? 0);
+    const bz = -(b[bAt + 2] ?? 0);
+    const bw = b[bAt + 3] ?? 1;
+    out[0] = aw * bx + ax * bw + ay * bz - az * by;
+    out[1] = aw * by - ax * bz + ay * bw + az * bx;
+    out[2] = aw * bz + ax * by - ay * bx + az * bw;
+    out[3] = aw * bw - ax * bx - ay * by - az * bz;
+}
+/**
+ * A body's own +y at `length`, turned by the body and then back by the inverse of a parent's world
+ * rotation: the bone as the body holds it, in the parent's frame.
+ */
+function boneInParentFrame(world, body, length, parent, parentAt, out, outAt) {
+    const bx = world.bodies.rotX[body] ?? 0;
+    const by = world.bodies.rotY[body] ?? 0;
+    const bz = world.bodies.rotZ[body] ?? 0;
+    const bw = world.bodies.rotW[body] ?? 1;
+    /* The body's +y in the world, scaled. */
+    const vx = 2 * length * (bx * by - bw * bz);
+    const vy = length * (1 - 2 * (bx * bx + bz * bz));
+    const vz = 2 * length * (by * bz + bw * bx);
+    /* Turned by the conjugate of the parent's rotation: v + 2w(u×v) + 2u×(u×v), u = −q.xyz. */
+    const ux = -(parent[parentAt] ?? 0);
+    const uy = -(parent[parentAt + 1] ?? 0);
+    const uz = -(parent[parentAt + 2] ?? 0);
+    const w = parent[parentAt + 3] ?? 1;
+    const cx = uy * vz - uz * vy;
+    const cy = uz * vx - ux * vz;
+    const cz = ux * vy - uy * vx;
+    out[outAt] = vx + 2 * (w * cx + (uy * cz - uz * cy));
+    out[outAt + 1] = vy + 2 * (w * cy + (uz * cx - ux * cz));
+    out[outAt + 2] = vz + 2 * (w * cz + (ux * cy - uy * cx));
+}
 /** `conj(a) · b` into `out`. */
 function multiplyConjugate(a, b, bAt, out, at) {
     const ax = -a[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/physics",
-  "version": "4.8.1",
+  "version": "4.8.3",
   "description": "Collision shapes, spatial queries and swept kinematic collision",
   "license": "Apache-2.0",
   "type": "module",

package/src/controller.ts

@@ -453,9 +453,10 @@ export class CharacterController {
      * the same clamp and air control — only the plane is given up, not the feel.
      */
     if (input.projectMove === false) {
-      this.velX = approach(this.velX, wantX, step);
-      this.velY = approach(this.velY, wantY, step);
-      this.velZ = approach(this.velZ, wantZ, step);
+      const t = approachFraction(wantX - this.velX, wantY - this.velY, wantZ - this.velZ, step);
+      this.velX = t === 1 ? wantX : this.velX + (wantX - this.velX) * t;
+      this.velY = t === 1 ? wantY : this.velY + (wantY - this.velY) * t;
+      this.velZ = t === 1 ? wantZ : this.velZ + (wantZ - this.velZ) * t;
     } else {
       const alongUp = this.speedAlongUp;
       let tangentX = this.velX - this.upX * alongUp;
@@ -465,9 +466,15 @@ export class CharacterController {
       const wantTangentX = wantX - this.upX * wantIntoUp;
       const wantTangentY = wantY - this.upY * wantIntoUp;
       const wantTangentZ = wantZ - this.upZ * wantIntoUp;
-      tangentX = approach(tangentX, wantTangentX, step);
-      tangentY = approach(tangentY, wantTangentY, step);
-      tangentZ = approach(tangentZ, wantTangentZ, step);
+      const t = approachFraction(
+        wantTangentX - tangentX,
+        wantTangentY - tangentY,
+        wantTangentZ - tangentZ,
+        step,
+      );
+      tangentX = t === 1 ? wantTangentX : tangentX + (wantTangentX - tangentX) * t;
+      tangentY = t === 1 ? wantTangentY : tangentY + (wantTangentY - tangentY) * t;
+      tangentZ = t === 1 ? wantTangentZ : tangentZ + (wantTangentZ - tangentZ) * t;
       this.velX = tangentX + this.upX * alongUp;
       this.velY = tangentY + this.upY * alongUp;
       this.velZ = tangentZ + this.upZ * alongUp;
@@ -858,10 +865,18 @@ export class CharacterController {
   }
 }
 
-/** Move `from` toward `to` by at most `step`. */
-function approach(from: number, to: number, step: number): number {
-  const d = to - from;
-  if (d > step) return from + step;
-  if (d < -step) return from - step;
-  return to;
+/**
+ * How much of the way to close a gap of `(dx, dy, dz)` this tick: exactly 1 when the gap is no
+ * longer than `step`, which the caller reads as "land on the target", and `step` of its length
+ * otherwise.
+ *
+ * **Toward the wanted velocity as a vector, by at most `step` in length.** It was one world axis at
+ * a time, each by the whole step, so a diagonal gained and lost speed √2 times as fast as a straight
+ * run while the clamp on the wanted vector kept its top speed honest — the faster diagonal lived in
+ * the acceleration. What it gives up is that an axis no longer reaches its target on its own
+ * schedule: turning from one direction to another now curves rather than squaring the corner.
+ */
+function approachFraction(dx: number, dy: number, dz: number, step: number): number {
+  const gap = Math.sqrt(dx * dx + dy * dy + dz * dz);
+  return gap <= step ? 1 : step / gap;
 }

package/src/ragdoll.ts

@@ -95,7 +95,15 @@ export interface Ragdoll {
   readonly bodyOf: Int32Array;
   /** How many bones were built. */
   readonly boneCount: number;
-  /** Write the ragdoll's current shape into a pose. */
+  /**
+   * Write the ragdoll's current shape into a pose.
+   *
+   * Each joint is turned by the bone that **starts** at it, which is the joint a skinned limb
+   * follows — the forearm's body turns the elbow — and a joint with no bone below it rides the one
+   * it hangs off. Translations are the rig's own, in each parent's frame. A root's rotation is
+   * written in the frame the character's node is placed in, at `rootX`, `rootY` and `rootZ`, with
+   * no rotation of its own; a joint no bone reaches is left as the pose had it.
+   */
   writePose(out: PoseTarget): void;
   /** Steer the bodies toward a pose. Weight 1 tracks it, weight 0 goes limp. */
   drive(world: PhysicsWorld, pose: PoseTarget, weight: number): void;
@@ -185,8 +193,32 @@ export function ragdollFromBones(
   };
 
   const bodyOf = new Int32Array(jointCount).fill(-1);
-  /** `conj(bodyRotation) · jointWorldRotation`, so a pose can be recovered from a body. */
+  /**
+   * `conj(bodyRotation) · jointWorldRotation` for the joint a bone **ends** at, so a joint with no
+   * bone of its own below it — a fingertip, a head's tip — can ride the bone it hangs off.
+   */
   const bodyToJoint = new Float32Array(jointCount * 4);
+  /**
+   * `conj(bodyRotation) · jointWorldRotation` for the joint a bone **starts** at, indexed like
+   * `bodyOf` — by the bone's own joint — and naming its parent's rotation.
+   *
+   * **This is the joint a skinned limb follows.** A forearm's vertices are weighted to the elbow,
+   * so the elbow's rotation is what points the forearm, and the body standing along the forearm is
+   * what carries it. Reading each joint off the bone that *ends* at it — the upper arm for the
+   * elbow — drew every limb one bone late: a hand 0.47 m from its body in a doll synced and never
+   * stepped, reported from a game. A bone is rigid in its start joint's frame, so the relation
+   * captured at rest holds for as long as the doll does.
+   */
+  const bodyToStart = new Float32Array(jointCount * 4);
+  /** The first bone starting at each joint, by that bone's own index, or −1 where none does. */
+  const startBone = new Int32Array(jointCount).fill(-1);
+  /**
+   * Each joint's translation in its parent's frame at rest, which is what a pose holds.
+   *
+   * **In the parent's frame, not the world's.** It was the world offset between the two, which is
+   * the same number only where the parent is unrotated at rest — true of every chain this module's
+   * tests were built from, and of no rig a game loads.
+   */
   const localRest = new Float32Array(jointCount * 3);
   const restRotation = new Float32Array(jointCount * 4);
   /**
@@ -198,6 +230,11 @@ export function ragdollFromBones(
    * the bones meet.
    */
   const halfOf = new Float32Array(jointCount);
+  /**
+   * Each bone's rig offset over its length: 1 for a rig at unit scale, and what turns a length in
+   * metres back into the parent's own units where the rig is scaled.
+   */
+  const restScale = new Float32Array(jointCount).fill(1);
   let boneCount = 0;
   let firstBone = -1;
   /** Half the first bone's length, which is how far its head sits from the body's centre. */
@@ -214,9 +251,7 @@ export function ragdollFromBones(
     const tx = worldMatrices[j * 16 + 12] ?? 0;
     const ty = worldMatrices[j * 16 + 13] ?? 0;
     const tz = worldMatrices[j * 16 + 14] ?? 0;
-    localRest[j * 3] = tx - hx;
-    localRest[j * 3 + 1] = ty - hy;
-    localRest[j * 3 + 2] = tz - hz;
+    intoParentFrame(worldMatrices, p, tx - hx, ty - hy, tz - hz, localRest, j * 3);
 
     const dx = tx - hx;
     const dy = ty - hy;
@@ -243,8 +278,16 @@ export function ragdollFromBones(
     });
     bodyOf[j] = body;
     halfOf[j] = length / 2;
-    // What takes the body's rotation back to the joint's, captured while both are at rest.
+    const rx = localRest[j * 3] ?? 0;
+    const ry = localRest[j * 3 + 1] ?? 0;
+    const rz = localRest[j * 3 + 2] ?? 0;
+    restScale[j] = Math.sqrt(rx * rx + ry * ry + rz * rz) / length;
+    // What takes the body's rotation back to each of its two joints', captured at rest. Parents
+    // come before children in a rig, so the start joint's rotation is already read.
     multiplyConjugate(TMP, restRotation, j * 4, bodyToJoint, j * 4);
+    if (p >= j) matrixRotation(worldMatrices, p, restRotation, p * 4);
+    multiplyConjugate(TMP, restRotation, p * 4, bodyToStart, j * 4);
+    if ((startBone[p] ?? -1) < 0) startBone[p] = j;
     boneCount++;
     if (firstBone < 0) {
       firstBone = j;
@@ -254,13 +297,65 @@ export function ragdollFromBones(
     }
   }
 
+  /*
+   * **A bone too short for a body is transparent.** Each joint resolves to the nearest one at or
+   * above it that a body ends at, or to its root: what hangs from a collar sitting on the chest
+   * joint hangs from the bone that ends at the chest. A rig puts one joint exactly on another as
+   * often as not, and a bone under `minLength` gets no body, so until 4.8.3 the spine above such a
+   * collar was jointed to nothing and collided with every bone it met there — compared by index,
+   * they shared no end. **What it gives up** is the skipped bone's own length, under `minLength`,
+   * which the joints below absorb exactly at rest: see `restAnchor`.
+   */
+  const attach = new Int32Array(jointCount);
+  for (let j = 0; j < jointCount; j++) {
+    let a = j;
+    while ((bodyOf[a] ?? -1) < 0 && (parents[a] ?? -1) >= 0) a = parents[a] ?? -1;
+    attach[j] = a;
+  }
+  /** Where a bone's parent end really hangs: its parent joint, seen through any bone too short. */
+  const hangsFrom = (j: number): number => {
+    const p = parents[j] ?? -1;
+    return p < 0 ? -1 : (attach[p] ?? p);
+  };
+  /**
+   * Bone `j`'s body-frame point at joint `at`'s rest position, into `REST_ANCHOR`. Where `at` is
+   * the bone's own parent joint this is its head, `(0, -half, 0)`, exactly as before; through a
+   * short bone it is where the two bones meet at rest, so a joint anchored there moves nothing on
+   * the first tick.
+   */
+  const restAnchor = (j: number, at: number): void => {
+    const p = parents[j] ?? -1;
+    if (at === p) {
+      REST_ANCHOR[0] = 0;
+      REST_ANCHOR[1] = -(halfOf[j] ?? 0);
+      REST_ANCHOR[2] = 0;
+      return;
+    }
+    const body = bodyOf[j] ?? 0;
+    const dx = (worldMatrices[at * 16 + 12] ?? 0) - (world.bodies.posX[body] ?? 0);
+    const dy = (worldMatrices[at * 16 + 13] ?? 0) - (world.bodies.posY[body] ?? 0);
+    const dz = (worldMatrices[at * 16 + 14] ?? 0) - (world.bodies.posZ[body] ?? 0);
+    /* Into the body's frame: turned by the conjugate of its rotation. */
+    const ux = -(world.bodies.rotX[body] ?? 0);
+    const uy = -(world.bodies.rotY[body] ?? 0);
+    const uz = -(world.bodies.rotZ[body] ?? 0);
+    const w = world.bodies.rotW[body] ?? 1;
+    const cx = uy * dz - uz * dy;
+    const cy = uz * dx - ux * dz;
+    const cz = ux * dy - uy * dx;
+    REST_ANCHOR[0] = dx + 2 * (w * cx + (uy * cz - uz * cy));
+    REST_ANCHOR[1] = dy + 2 * (w * cy + (uz * cx - ux * cz));
+    REST_ANCHOR[2] = dz + 2 * (w * cz + (ux * cy - uy * cx));
+  };
+
   // Joint each bone to its parent's bone, at the shared end.
   for (let j = 0; j < jointCount; j++) {
     const body = bodyOf[j] ?? -1;
     if (body < 0) continue;
-    const p = parents[j] ?? -1;
+    const p = hangsFrom(j);
     const parentBody = p >= 0 ? (bodyOf[p] ?? -1) : -1;
     if (parentBody < 0) continue;
+    restAnchor(j, p);
     world.addJoint({
       type: JOINT_CONE_TWIST,
       bodyA: parentBody,
@@ -287,7 +382,9 @@ export function ragdollFromBones(
        * so the first tick still moves nothing.
        */
       anchorAY: halfOf[p] ?? 0,
-      anchorBY: -(halfOf[j] ?? 0),
+      anchorBX: REST_ANCHOR[0],
+      anchorBY: REST_ANCHOR[1],
+      anchorBZ: REST_ANCHOR[2],
     });
   }
 
@@ -304,13 +401,18 @@ export function ragdollFromBones(
   for (let j = 0; j < jointCount; j++) {
     const body = bodyOf[j] ?? -1;
     if (body < 0) continue;
-    const p = parents[j] ?? -1;
+    const p = hangsFrom(j);
     if (p < 0 || (bodyOf[p] ?? -1) >= 0) continue;
     const first = firstUnder[p] ?? -1;
     if (first < 0) {
       firstUnder[p] = j;
       continue;
     }
+    restAnchor(first, p);
+    const ax = REST_ANCHOR[0];
+    const ay = REST_ANCHOR[1];
+    const az = REST_ANCHOR[2];
+    restAnchor(j, p);
     world.addJoint({
       type: JOINT_CONE_TWIST,
       bodyA: bodyOf[first] ?? 0,
@@ -318,8 +420,12 @@ export function ragdollFromBones(
       swingCos: limitAt(swingCos, Math.SQRT1_2, j),
       twistSin: limitAt(twistSin, 0.3826834323650898, j),
       axisY: 1,
-      anchorAY: -(halfOf[first] ?? 0),
-      anchorBY: -(halfOf[j] ?? 0),
+      anchorAX: ax,
+      anchorAY: ay,
+      anchorAZ: az,
+      anchorBX: REST_ANCHOR[0],
+      anchorBY: REST_ANCHOR[1],
+      anchorBZ: REST_ANCHOR[2],
     });
   }
 
@@ -341,39 +447,85 @@ export function ragdollFromBones(
         world.ignorePair(body, other);
         continue;
       }
-      const pj = parents[j] ?? -1;
-      const pk = parents[k] ?? -1;
+      /* Seen through any bone too short for a body, which is where they really meet. */
+      const pj = hangsFrom(j);
+      const pk = hangsFrom(k);
       /* Jointed, either way round, or two bones hanging off the same parent joint: siblings share
          a head the way a parent and child share a point, so they overlap there too. */
       if (pk === j || pj === k || (pj === pk && pj >= 0)) world.ignorePair(body, other);
     }
   }
 
+  /**
+   * One joint's world rotation, from the body that speaks for it: the first bone starting at the
+   * joint, or — for a joint with none below it, a fingertip — the bone it hangs off, which it then
+   * rides rigidly. False where neither exists and nothing can be said.
+   */
+  const recoverJoint = (w: PhysicsWorld, j: number, out: Float32Array, at: number): boolean => {
+    const start = startBone[j] ?? -1;
+    if (start >= 0) {
+      readBodyRotation(w, bodyOf[start] ?? 0, TMP);
+      multiplyInto(TMP, bodyToStart, start * 4, out, at);
+      return true;
+    }
+    const own = bodyOf[j] ?? -1;
+    if (own < 0) return false;
+    readBodyRotation(w, own, TMP);
+    multiplyInto(TMP, bodyToJoint, j * 4, out, at);
+    return true;
+  };
+
   const root = firstBone;
   return {
     bodyOf,
     boneCount,
     writePose(out: PoseTarget): void {
+      /*
+       * Two passes, because a joint's local rotation needs its parent's world rotation and a rig
+       * is not obliged to list parents first. The first recovers every joint a body speaks for.
+       */
+      for (let j = 0; j < jointCount; j++)
+        KNOWN[j] = recoverJoint(world, j, WORLD_ROT, j * 4) ? 1 : 0;
       for (let j = 0; j < jointCount; j++) {
-        const body = bodyOf[j] ?? -1;
-        const p = parents[j] ?? -1;
-        if (body < 0) {
-          // No bone: leave the joint as the pose already had it.
+        if (KNOWN[j] !== 1) {
+          // No bone at either end: leave the joint as the pose already had it.
           continue;
         }
-        // The joint's world rotation, recovered from the body's.
-        readBodyRotation(world, body, TMP);
-        multiplyInto(TMP, bodyToJoint, j * 4, WORLD_ROT, j * 4);
-        const parentBody = p >= 0 ? (bodyOf[p] ?? -1) : -1;
-        if (parentBody >= 0) {
+        const p = parents[j] ?? -1;
+        if (p >= 0 && KNOWN[p] === 1) {
           conjugateMultiply(WORLD_ROT, p * 4, WORLD_ROT, j * 4, out.rotation, j * 4);
         } else {
+          /* A root, or a joint whose parent no bone speaks for: its rotation in the frame the
+             caller places the character's node in, which `rootX` and its two siblings answer. */
           copy4(WORLD_ROT, j * 4, out.rotation, j * 4);
         }
-        // Bones are rigid, so translation stays what the rig was built with.
-        out.translation[j * 3] = localRest[j * 3] ?? 0;
-        out.translation[j * 3 + 1] = localRest[j * 3 + 1] ?? 0;
-        out.translation[j * 3 + 2] = localRest[j * 3 + 2] ?? 0;
+        if (p < 0) continue;
+        /*
+         * **Placed along its own bone as the body holds it**, at the rig's length: the body's +y,
+         * in the parent's frame. For the first bone under a joint that is the rig's offset exactly,
+         * because the joint turns with that body; for a second or third — a thigh beside the spine,
+         * a clavicle beside the neck — it is what keeps the branch on its own body. Placed by the
+         * rig's offset, every branch but the first was swung by the first one's turn: reported as
+         * a foot 0.24 m and an arm 0.17 m from their bodies after a fall. A joint with no bone of
+         * its own keeps the rig's offset. **What would make it wrong** is a bone the body
+         * stretches, which a rigid capsule cannot.
+         */
+        const body = bodyOf[j] ?? -1;
+        if (body >= 0 && KNOWN[p] === 1) {
+          boneInParentFrame(
+            world,
+            body,
+            2 * (halfOf[j] ?? 0) * (restScale[j] ?? 1),
+            WORLD_ROT,
+            p * 4,
+            out.translation,
+            j * 3,
+          );
+        } else {
+          out.translation[j * 3] = localRest[j * 3] ?? 0;
+          out.translation[j * 3 + 1] = localRest[j * 3 + 1] ?? 0;
+          out.translation[j * 3 + 2] = localRest[j * 3 + 2] ?? 0;
+        }
         out.scale[j * 3] = 1;
         out.scale[j * 3 + 1] = 1;
         out.scale[j * 3 + 2] = 1;
@@ -382,25 +534,29 @@ export function ragdollFromBones(
     drive(w: PhysicsWorld, pose: PoseTarget, weight: number): void {
       if (weight <= 0) return;
       const k = weight > 1 ? 1 : weight;
-      for (let j = 0; j < jointCount; j++) {
-        const body = bodyOf[j] ?? -1;
+      for (let c = 0; c < jointCount; c++) {
+        const body = bodyOf[c] ?? -1;
         if (body < 0) continue;
-        const p = parents[j] ?? -1;
-        const parentBody = p >= 0 ? (bodyOf[p] ?? -1) : -1;
+        /*
+         * **A bone is steered by the joint it starts at**, the one whose rotation points it — the
+         * forearm by the elbow — which is the same joint `writePose` reads it back as. Steered by
+         * the joint it ends at, a pose's elbow bend went into the upper arm.
+         */
+        const j = parents[c] ?? -1;
+        if (j < 0) continue;
         /*
          * The target is the pose's local rotation composed onto the parent's *current* world
          * rotation, so a driven limb follows the animation relative to a body that may itself have
          * been knocked aside — which is what a partial ragdoll is.
          */
-        if (parentBody >= 0) {
-          readBodyRotation(w, parentBody, TMP);
-          multiplyInto(TMP, bodyToJoint, p * 4, PARENT_ROT, 0);
+        const p = parents[j] ?? -1;
+        if (p >= 0 && recoverJoint(w, p, PARENT_ROT, 0)) {
           multiplyRaw(PARENT_ROT, 0, pose.rotation, j * 4, TARGET_ROT, 0);
         } else {
           copy4(pose.rotation, j * 4, TARGET_ROT, 0);
         }
         readBodyRotation(w, body, TMP);
-        multiplyInto(TMP, bodyToJoint, j * 4, CURRENT_ROT, 0);
+        multiplyInto(TMP, bodyToStart, c * 4, CURRENT_ROT, 0);
         // Twice the vector part of target · conj(current) is the rotation that closes the gap.
         conjugateMultiply(CURRENT_ROT, 0, TARGET_ROT, 0, ERROR_ROT, 0);
         let ex = ERROR_ROT[0] ?? 0;
@@ -437,22 +593,23 @@ export function ragdollFromBones(
         w.bodies.posZ[body] = (hz + tz) / 2;
 
         /*
-         * The rotation is taken from the *bone*, the same way the build took it: the capsule
-         * stands along y, so the body is turned to put its y along the bone. Taking it from the
-         * joint's world matrix instead would be wrong wherever a rig's bind orientation is not
-         * the bone direction, which is most rigs.
+         * **The rotation is the start joint's, carried through the relation captured at rest**,
+         * which is the inverse of what `writePose` reads: `jointRotation · conj(bodyToStart)`.
+         *
+         * It was the shortest arc from +y onto the bone, which points the capsule correctly and
+         * throws away the bone's twist about its own length — so a joint with two bones below it, a
+         * wrist with a thumb beside the fingers, came back turned about the first and put the
+         * second somewhere else. The joint's world matrix alone would be wrong too, wherever a
+         * rig's bind orientation is not the bone direction, which is most rigs; the captured
+         * relation is what absorbs that. **What would make it wrong** is a pose that stretches a
+         * bone, which a ragdoll's rigid bones cannot follow either way.
          */
-        const dx = tx - hx;
-        const dy = ty - hy;
-        const dz = tz - hz;
-        const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
-        if (length > 0) {
-          alignYTo(dx / length, dy / length, dz / length, TMP);
-          w.bodies.rotX[body] = TMP[0] ?? 0;
-          w.bodies.rotY[body] = TMP[1] ?? 0;
-          w.bodies.rotZ[body] = TMP[2] ?? 0;
-          w.bodies.rotW[body] = TMP[3] ?? 1;
-        }
+        matrixRotation(worldMatrices, p, START_ROT, 0);
+        multiplyByConjugate(START_ROT, bodyToStart, j * 4, TMP);
+        w.bodies.rotX[body] = TMP[0] ?? 0;
+        w.bodies.rotY[body] = TMP[1] ?? 0;
+        w.bodies.rotZ[body] = TMP[2] ?? 0;
+        w.bodies.rotW[body] = TMP[3] ?? 1;
 
         /* At rest, which is the half that makes it a reaction rather than a continuation: a body
            carrying the speed of a two-second fall is thrown across the character the instant it
@@ -479,6 +636,11 @@ export function ragdollFromBones(
 }
 
 const WORLD_ROT = new Float32Array(256 * 4);
+/** Whether `writePose` recovered each joint's rotation this call: 1 if a body speaks for it. */
+const KNOWN = new Uint8Array(256);
+const START_ROT = new Float32Array(4);
+/** One joint anchor in a body's own frame, filled by `restAnchor` and read at once. */
+const REST_ANCHOR = new Float64Array(3);
 const PARENT_ROT = new Float32Array(4);
 const TARGET_ROT = new Float32Array(4);
 const CURRENT_ROT = new Float32Array(4);
@@ -596,6 +758,100 @@ function alignYTo(dx: number, dy: number, dz: number, out: Float64Array): void {
   out[3] = w / len;
 }
 
+/**
+ * A world-space offset from joint `p`, expressed in `p`'s own frame: the inverse of the matrix's
+ * upper 3x3 applied to it, so a scaled joint is undone as well as a rotated one.
+ */
+function intoParentFrame(
+  m: Float32Array,
+  p: number,
+  dx: number,
+  dy: number,
+  dz: number,
+  out: Float32Array,
+  at: number,
+): void {
+  const o = p * 16;
+  const a = m[o] ?? 1;
+  const b = m[o + 4] ?? 0;
+  const c = m[o + 8] ?? 0;
+  const d = m[o + 1] ?? 0;
+  const e = m[o + 5] ?? 1;
+  const f = m[o + 9] ?? 0;
+  const g = m[o + 2] ?? 0;
+  const h = m[o + 6] ?? 0;
+  const i = m[o + 10] ?? 1;
+  const ei = e * i - f * h;
+  const fg = f * g - d * i;
+  const dh = d * h - e * g;
+  const det = a * ei + b * fg + c * dh;
+  if (Math.abs(det) < 1e-12) {
+    out[at] = dx;
+    out[at + 1] = dy;
+    out[at + 2] = dz;
+    return;
+  }
+  const inv = 1 / det;
+  out[at] = (ei * dx + (c * h - b * i) * dy + (b * f - c * e) * dz) * inv;
+  out[at + 1] = (fg * dx + (a * i - c * g) * dy + (c * d - a * f) * dz) * inv;
+  out[at + 2] = (dh * dx + (b * g - a * h) * dy + (a * e - b * d) * dz) * inv;
+}
+
+/** `a · conj(b)` into a Float64 quaternion, for turning a joint's rotation back into a body's. */
+function multiplyByConjugate(
+  a: Float32Array,
+  b: Float32Array,
+  bAt: number,
+  out: Float64Array,
+): void {
+  const ax = a[0] ?? 0;
+  const ay = a[1] ?? 0;
+  const az = a[2] ?? 0;
+  const aw = a[3] ?? 1;
+  const bx = -(b[bAt] ?? 0);
+  const by = -(b[bAt + 1] ?? 0);
+  const bz = -(b[bAt + 2] ?? 0);
+  const bw = b[bAt + 3] ?? 1;
+  out[0] = aw * bx + ax * bw + ay * bz - az * by;
+  out[1] = aw * by - ax * bz + ay * bw + az * bx;
+  out[2] = aw * bz + ax * by - ay * bx + az * bw;
+  out[3] = aw * bw - ax * bx - ay * by - az * bz;
+}
+
+/**
+ * A body's own +y at `length`, turned by the body and then back by the inverse of a parent's world
+ * rotation: the bone as the body holds it, in the parent's frame.
+ */
+function boneInParentFrame(
+  world: PhysicsWorld,
+  body: number,
+  length: number,
+  parent: Float32Array,
+  parentAt: number,
+  out: Float32Array,
+  outAt: number,
+): void {
+  const bx = world.bodies.rotX[body] ?? 0;
+  const by = world.bodies.rotY[body] ?? 0;
+  const bz = world.bodies.rotZ[body] ?? 0;
+  const bw = world.bodies.rotW[body] ?? 1;
+  /* The body's +y in the world, scaled. */
+  const vx = 2 * length * (bx * by - bw * bz);
+  const vy = length * (1 - 2 * (bx * bx + bz * bz));
+  const vz = 2 * length * (by * bz + bw * bx);
+  /* Turned by the conjugate of the parent's rotation: v + 2w(u×v) + 2u×(u×v), u = −q.xyz. */
+  const ux = -(parent[parentAt] ?? 0);
+  const uy = -(parent[parentAt + 1] ?? 0);
+  const uz = -(parent[parentAt + 2] ?? 0);
+  const w = parent[parentAt + 3] ?? 1;
+  const cx = uy * vz - uz * vy;
+  const cy = uz * vx - ux * vz;
+  const cz = ux * vy - uy * vx;
+  out[outAt] = vx + 2 * (w * cx + (uy * cz - uz * cy));
+  out[outAt + 1] = vy + 2 * (w * cy + (uz * cx - ux * cz));
+  out[outAt + 2] = vz + 2 * (w * cz + (ux * cy - uy * cx));
+}
+
 /** `conj(a) · b` into `out`. */
 function multiplyConjugate(
   a: Float64Array,