@driftengine/physics 4.8.2 → 4.8.4

package/src/exact.ts

@@ -0,0 +1,344 @@
+/**
+ * Transcendentals that give the same bits on every JavaScript engine.
+ *
+ * **Not more accurate than `Math`, and that is not what they are for.** These are within a couple
+ * of units in the last place of correctly rounded, which is about what a platform `sin` gives you.
+ * What they are is *reproducible*: ECMAScript declines to specify `sin`, `cos`, `exp`, `acos` and
+ * eighteen more, so two engines may differ by an ulp, and an ulp is enough to make two peers running
+ * the same simulation disagree — first invisibly, then completely.
+ *
+ * **In physics rather than core since 4.8.4**: a skinned cloth's damping needs `exp` and its bending
+ * `acos`, the simulation set may not call the platform's, and physics imports no other package. Core
+ * re-exports physics wholesale, so `exactExp` from `@driftengine/core` is the same function.
+ *
+ * `scripts/determinism.mjs` is the gate that refuses the unspecified ones inside the simulation set
+ * and names the twenty-two. Its header carries the other half of the argument: `+ - * /` are IEEE
+ * 754 operations by specification, JavaScript permits no fused-multiply-add contraction, and
+ * `Math.sqrt` is required correctly rounded and is *not* on that list. **So everything below uses
+ * only those five operations**, which is the whole design: reproducibility by construction rather
+ * than by hoping two engines chose the same algorithm.
+ *
+ * ---
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * `exactSin`, `exactCos`, `exactExp`, `exactAcos` and `exactLog`. Five, because five is what the
+ * engine and its first consumer actually reach for: the terrain binding's slope angle needs `acos`,
+ * a lockstep fixture rotating anything needs `sin` and `cos`, exponential decay needs `exp`, and a
+ * detector's box prior is a logit of the patch grid, which needs `log`.
+ *
+ * **`atan2` is absent.** It is the obvious fifth and nothing here needs one: `shape.ts` sorts by a
+ * comparison key computed from two in-plane axes rather than by an angle, and `joints.ts` compares
+ * a quaternion component against a half-angle's sine. *Reversed by* a site that genuinely needs a
+ * signed angle from two components, at which point it arrives with its own golden vectors.
+ *
+ * ## Nothing in core imports these
+ *
+ * Deliberately. `core-only` is the one size figure in this repository that every consumer pays, and
+ * a module reachable from `createRenderer` is in it whether anybody calls it or not. These are
+ * reached by the script bindings and by consumers who ask for them, so tree-shaking keeps them out
+ * of a bundle that does not, which is measured rather than assumed.
+ *
+ * ## The coefficients
+ *
+ * The polynomial and rational coefficients are fdlibm's, which is the ancestor of most platform
+ * libms and is public domain. They are written as literals: **a literal is the same number on
+ * every engine, which is the only property being bought.** Their provenance matters less than their
+ * fixity — a coefficient somebody re-derived to one more digit is a different function, and
+ * `exact.test.ts`'s golden bit patterns are what would catch that.
+ */
+
+/*
+ * π/2 in four pieces, most significant first, so a large multiple of it can be removed without
+ * losing the small remainder in the subtraction.
+ *
+ * **Two pieces are not enough and the measurement says so**: at an angle of 740 radians a two-part
+ * reduction leaves `sin` and `cos` 18.5 ulps out, because `k * PIO2_1` needs more than 53 bits once
+ * `k` grows. Three brings it under two ulps for the cost of two multiplies.
+ *
+ * **`PIO2_TAIL` and `PIO2_TAIL_LO` are one number in two halves, not two successive corrections.**
+ * fdlibm carries a fourth constant, `pio2_1t`, which is the tail for its *single*-iteration path;
+ * `pio2_2` is the same tail rounded differently, with `pio2_2t` as its own tail, and the two paths
+ * are alternatives. Refining the first with the second is not more accurate, it is wrong: it
+ * subtracts the tail twice and took `sin` to 2.2e11 ulps out, which is how this comment came to be
+ * here.
+ */
+const PIO2_1 = 1.5707963267341256;
+const PIO2_TAIL = 6.077100506303966e-11;
+const PIO2_TAIL_LO = 2.0222662487959506e-21;
+const TWO_OVER_PI = 0.6366197723675814;
+
+const HALF_PI = 1.5707963267948966;
+const PI = 3.141592653589793;
+
+/* fdlibm's `__kernel_sin` coefficients. */
+const S1 = -1.6666666666666632e-1;
+const S2 = 8.33333333332249e-3;
+const S3 = -1.984126982985795e-4;
+const S4 = 2.7557313707070068e-6;
+const S5 = -2.5050760253406863e-8;
+const S6 = 1.5896909952115501e-10;
+
+/* fdlibm's `__kernel_cos` coefficients. */
+const C1 = 4.1666666666666602e-2;
+const C2 = -1.388888888887411e-3;
+const C3 = 2.480158728947673e-5;
+const C4 = -2.7557314351390663e-7;
+const C5 = 2.0875723212981748e-9;
+const C6 = -1.1359647557788195e-11;
+
+/* fdlibm's `asin` rational, numerator then denominator. */
+const P0 = 1.6666666666666666e-1;
+const P1 = -3.2556581862240092e-1;
+const P2 = 2.0121253213486293e-1;
+const P3 = -4.0055534500679411e-2;
+const P4 = 7.9153499428981453e-4;
+const P5 = 3.4793310759602117e-5;
+const Q1 = -2.4033949117344142;
+const Q2 = 2.0209457602335057;
+const Q3 = -6.8828397160545329e-1;
+const Q4 = 7.7038150555901935e-2;
+
+/** ln 2, split for the same reason π/2 is. */
+const LN2_HI = 0.6931471803691238;
+const LN2_LO = 1.9082149292705877e-10;
+const ONE_OVER_LN2 = 1.4426950408889634;
+
+/** 2^(2^i), for i = 0 to 9. Every one is exact, so a product of them is exact. */
+const POW2 = [
+  2, 4, 16, 256, 65536, 4294967296, 1.8446744073709552e19, 3.402823669209385e38,
+  1.157920892373162e77, 1.3407807929942597e154,
+];
+
+/**
+ * Two to an integer power, by binary decomposition of the exponent.
+ *
+ * Multiplication by a power of two is exact in IEEE 754, so this is exact wherever it does not
+ * overflow — which is what makes it a legitimate substitute for the `Math.pow` a range reduction
+ * would otherwise reach for.
+ *
+ * A large negative exponent lands on zero instead of a subnormal, because the reciprocal is taken
+ * after the product overflows. That is `exp` underflowing to zero, which is where it was going.
+ */
+function pow2(exponent: number): number {
+  let remaining = exponent < 0 ? -exponent : exponent;
+  let result = 1;
+  let index = 0;
+  while (remaining > 0 && index < POW2.length) {
+    if ((remaining & 1) === 1) result *= POW2[index] as number;
+    remaining >>= 1;
+    index += 1;
+  }
+  return exponent < 0 ? 1 / result : result;
+}
+
+/** sin on [-π/4, π/4]. */
+function sinKernel(x: number): number {
+  const z = x * x;
+  const poly = S1 + z * (S2 + z * (S3 + z * (S4 + z * (S5 + z * S6))));
+  return x + x * z * poly;
+}
+
+/** cos on [-π/4, π/4]. */
+function cosKernel(x: number): number {
+  const z = x * x;
+  const poly = C1 + z * (C2 + z * (C3 + z * (C4 + z * (C5 + z * C6))));
+  return 1 - 0.5 * z + z * z * poly;
+}
+
+/**
+ * Fold an angle into [-π/4, π/4] and say which quadrant it came from.
+ *
+ * Cody-Waite: the multiple of π/2 is removed in pieces, so the subtraction that produces a small
+ * remainder from two large numbers does not lose the bits it is supposed to keep. One-piece
+ * reduction is accurate to about 1e-8 at an angle of a thousand radians, which for a simulation
+ * that accumulates rotation is the difference between an object facing forward and facing sideways
+ * after a few minutes.
+ */
+function reduce(x: number): { r: number; quadrant: number } {
+  const k = Math.round(x * TWO_OVER_PI);
+
+  /* The leading piece, whose product with `k` is exact for every `k` a simulation reaches. */
+  const head = x - k * PIO2_1;
+
+  /*
+   * The tail, in two halves. `head - tail` loses the bits below its own last place, and
+   * `PIO2_TAIL_LO - (head - r - tail)` is exactly those bits recovered — the same
+   * subtract-and-recover fdlibm uses on its two-iteration path.
+   */
+  const tail = k * PIO2_TAIL;
+  let r = head - tail;
+  const lost = k * PIO2_TAIL_LO - (head - r - tail);
+  r = r - lost;
+
+  return { r, quadrant: ((k % 4) + 4) % 4 };
+}
+
+/** `Math.sin`, reproducibly. NaN in, NaN out; an infinity answers NaN, as `Math.sin` does. */
+export function exactSin(x: number): number {
+  if (!Number.isFinite(x)) return Number.NaN;
+  const { r, quadrant } = reduce(x);
+  switch (quadrant) {
+    case 0:
+      return sinKernel(r);
+    case 1:
+      return cosKernel(r);
+    case 2:
+      return -sinKernel(r);
+    default:
+      return -cosKernel(r);
+  }
+}
+
+/** `Math.cos`, reproducibly. */
+export function exactCos(x: number): number {
+  if (!Number.isFinite(x)) return Number.NaN;
+  const { r, quadrant } = reduce(x);
+  switch (quadrant) {
+    case 0:
+      return cosKernel(r);
+    case 1:
+      return -sinKernel(r);
+    case 2:
+      return -cosKernel(r);
+    default:
+      return sinKernel(r);
+  }
+}
+
+/**
+ * `Math.exp`, reproducibly.
+ *
+ * Reduce by a multiple of ln 2 into [-ln2/2, ln2/2], sum the Taylor series there, and scale by a
+ * power of two. **A degree-14 series and not a shorter minimax**, because on that interval the
+ * fifteenth term is about 4e-20 — below the precision of a double — so the series is exact to the
+ * representation and there is nothing a fitted polynomial would buy.
+ */
+export function exactExp(x: number): number {
+  if (Number.isNaN(x)) return Number.NaN;
+  if (x === Number.POSITIVE_INFINITY) return Number.POSITIVE_INFINITY;
+  if (x === Number.NEGATIVE_INFINITY) return 0;
+  if (x > 709.782712893384) return Number.POSITIVE_INFINITY;
+  if (x < -745.1332191019411) return 0;
+
+  const k = Math.round(x * ONE_OVER_LN2);
+  const r = x - k * LN2_HI - k * LN2_LO;
+
+  /* Horner over 1/n!, highest term first. */
+  let sum = 1 / 87178291200; // 1/14!
+  sum = 1 / 6227020800 + r * sum; // 1/13!
+  sum = 1 / 479001600 + r * sum; // 1/12!
+  sum = 1 / 39916800 + r * sum; // 1/11!
+  sum = 1 / 3628800 + r * sum; // 1/10!
+  sum = 1 / 362880 + r * sum; // 1/9!
+  sum = 1 / 40320 + r * sum; // 1/8!
+  sum = 1 / 5040 + r * sum; // 1/7!
+  sum = 1 / 720 + r * sum; // 1/6!
+  sum = 1 / 120 + r * sum; // 1/5!
+  sum = 1 / 24 + r * sum; // 1/4!
+  sum = 1 / 6 + r * sum; // 1/3!
+  sum = 0.5 + r * sum;
+  sum = 1 + r * sum;
+  sum = 1 + r * sum;
+
+  return sum * pow2(k);
+}
+
+/* fdlibm's `log` polynomial in s², for log(1 + f) around f = 0 by way of s = f / (2 + f). */
+const LG1 = 6.66666666666673513e-1;
+const LG2 = 3.999999999940941908e-1;
+const LG3 = 2.857142874366239149e-1;
+const LG4 = 2.222219843214978396e-1;
+const LG5 = 1.818357216161805012e-1;
+const LG6 = 1.531383769920937332e-1;
+const LG7 = 1.479819860511658591e-1;
+const TWO54 = 1.8014398509481984e16;
+const SMALLEST_NORMAL = 2.2250738585072014e-308;
+
+/* A double's two words, for reading and setting an exponent; one view, reused. */
+const words = new DataView(new ArrayBuffer(8));
+
+/**
+ * `Math.log`, reproducibly: fdlibm's algorithm, which is also V8's.
+ *
+ * Take the power of two out as `k` and leave a significand in [√2/2, √2), so that `f = m - 1` is
+ * small either side of zero; then log(1 + f) = f - f²/2 + s·(f²/2 + R(s²)) with s = f/(2 + f), and
+ * `k·ln 2` added back in two parts so the large part loses nothing. The exponent is read and the
+ * significand rescaled through the double's own words — integer operations, not transcendentals.
+ */
+export function exactLog(x: number): number {
+  if (Number.isNaN(x) || x < 0) return Number.NaN;
+  if (x === 0) return Number.NEGATIVE_INFINITY;
+  if (x === Number.POSITIVE_INFINITY) return x;
+
+  let k = 0;
+  let value = x;
+  if (value < SMALLEST_NORMAL) {
+    k = -54;
+    value *= TWO54;
+  }
+  words.setFloat64(0, value);
+  let hx = words.getUint32(0);
+  k += (hx >>> 20) - 1023;
+  hx &= 0x000fffff;
+  /* Keep the significand at or above √2/2: past √2, halve it and count one more power of two. */
+  const i = (hx + 0x95f64) & 0x100000;
+  words.setUint32(0, hx | (i ^ 0x3ff00000));
+  k += i >>> 20;
+  const f = words.getFloat64(0) - 1;
+
+  if ((0x000fffff & (2 + hx)) < 3) {
+    /* |f| < 2^-20: two terms of the series are the whole answer. */
+    if (f === 0) return k === 0 ? 0 : k * LN2_HI + k * LN2_LO;
+    const r = f * f * (0.5 - 0.3333333333333333 * f);
+    return k === 0 ? f - r : k * LN2_HI - (r - k * LN2_LO - f);
+  }
+  const s = f / (2 + f);
+  const z = s * s;
+  const w = z * z;
+  const t1 = w * (LG2 + w * (LG4 + w * LG6));
+  const t2 = z * (LG1 + w * (LG3 + w * (LG5 + w * LG7)));
+  const r = t2 + t1;
+  /* Far enough from one that f²/2 is worth carrying apart from f. */
+  if (((hx - 0x6147a) | (0x6b851 - hx)) > 0) {
+    const half = 0.5 * f * f;
+    return k === 0
+      ? f - (half - s * (half + r))
+      : k * LN2_HI - (half - (s * (half + r) + k * LN2_LO) - f);
+  }
+  return k === 0 ? f - s * (f - r) : k * LN2_HI - (s * (f - r) - k * LN2_LO - f);
+}
+
+/** fdlibm's `asin` rational on `z = x²`, valid where `z` is small. */
+function asinRational(z: number): number {
+  const numerator = z * (P0 + z * (P1 + z * (P2 + z * (P3 + z * (P4 + z * P5)))));
+  const denominator = 1 + z * (Q1 + z * (Q2 + z * (Q3 + z * Q4)));
+  return numerator / denominator;
+}
+
+/**
+ * `Math.acos`, reproducibly. Outside [-1, 1] this answers NaN, as `Math.acos` does.
+ *
+ * Three branches rather than one, and the split at ±0.5 is the reason it is accurate near the ends:
+ * `acos` has infinite derivative at ±1, so a polynomial in `x` loses its footing there. Substituting
+ * `s = sqrt((1 ∓ x)/2)` moves the awkward point to zero, where a polynomial is comfortable — which
+ * is also why `sqrt` being exactly rounded matters here rather than being a convenience.
+ */
+export function exactAcos(x: number): number {
+  if (Number.isNaN(x) || x > 1 || x < -1) return Number.NaN;
+  if (x === 1) return 0;
+  if (x === -1) return PI;
+
+  if (x >= 0.5) {
+    const z = (1 - x) / 2;
+    const s = Math.sqrt(z);
+    return 2 * (s + s * asinRational(z));
+  }
+  if (x <= -0.5) {
+    const z = (1 + x) / 2;
+    const s = Math.sqrt(z);
+    return PI - 2 * (s + s * asinRational(z));
+  }
+  const z = x * x;
+  return HALF_PI - (x + x * asinRational(z));
+}

package/src/index.ts

@@ -116,6 +116,38 @@ export {
 } from './stallEscape.ts';
 export type { ClothOptions } from './cloth.ts';
 export { ClothBody, makeClothGrid } from './cloth.ts';
+/*
+ * Cloth anchored to a skeleton rather than a world: a garment. The CPU solver is the reference and
+ * runs under WebGL2 and in Node; `@driftengine/core` runs the same kernels on WebGPU.
+ */
+export { SkinnedCloth } from './skinnedCloth.ts';
+/*
+ * The schedule both solvers share — poses, whole steps, resets and the blend — and the device
+ * interface the GPU solver implements, with what it reads: the targets' matrices and colliders,
+ * and the set-up checked and batched exactly as the CPU solver checks and batches it.
+ */
+export { ClothControl } from './clothControl.ts';
+export type { ClothDevice } from './clothControl.ts';
+export type { ClothTargets } from './clothTargets.ts';
+export { validateClothSetup } from './skinnedClothSetup.ts';
+/*
+ * Transcendentals that give the same bits on every engine. Here rather than in core since 4.8.4,
+ * because the simulation needs them and this package imports nothing; core re-exports them with
+ * the rest of physics.
+ */
+export { exactAcos, exactCos, exactExp, exactLog, exactSin } from './exact.ts';
+export { batchesOf, colourConstraints } from './clothBatches.ts';
+export type { ClothBatches } from './clothBatches.ts';
+export type {
+  BendingConstraints,
+  ClothCollider,
+  ClothLimits,
+  DistanceConstraints,
+  ResolvedClothParameters,
+  SkinnedClothParameters,
+  SkinnedClothSetup,
+  TetherConstraints,
+} from './skinnedClothSetup.ts';
 export type { Collider, ColliderBytes, ColliderGroup } from './colliderSet.ts';
 export { ColliderSet, boxCollider, colliderFromShape } from './colliderSet.ts';
 export { fingerprintBodies, fingerprintColliders } from './fingerprint.ts';

package/src/ragdoll.ts

@@ -230,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. */
@@ -273,6 +278,10 @@ export function ragdollFromBones(
     });
     bodyOf[j] = body;
     halfOf[j] = length / 2;
+    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);
@@ -288,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,
@@ -321,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],
     });
   }
 
@@ -338,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,
@@ -352,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],
     });
   }
 
@@ -375,8 +447,9 @@ 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);
@@ -427,10 +500,32 @@ export function ragdollFromBones(
           copy4(WORLD_ROT, j * 4, out.rotation, j * 4);
         }
         if (p < 0) continue;
-        // 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;
+        /*
+         * **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;
@@ -544,6 +639,8 @@ 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);
@@ -721,6 +818,40 @@ function multiplyByConjugate(
   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,