cozyclay 2.1.1 → 3.0.1

package/src/motion3/compiler/limbs.js

@@ -0,0 +1,197 @@
+// Two-bone limb IK, foot orientation, wrist and finger posing on a world-space state.
+// Every edit rotates a bone's subtree about that bone's own joint, so the result maps
+// exactly back to local quaternions (skeleton.js toLocal).
+import { add, sub, scale, dot, len, norm, cross, clamp, apply, T, align, axisRot, ry, rx } from "./math.js";
+import { rotateSubtree } from "./skeleton.js";
+
+/** Direction fixed to bone b that points along `restDir` in the rest pose. */
+export const carried = (sk, s, b, restDir) => apply(s.R[b], apply(T(sk.restWorldRot[b]), restDir));
+
+// Elbow flexion: degrees between the upper arm and the forearm (0 straight), read on the joints as QA
+// reads it (Arm->ForeArm against ForeArm->Hand). Active flexion ends near 145 deg (clinical norms
+// 140-150: AMA 140, Kendall 145, AAOS 150), where the forearm's muscle meets the upper arm's; the
+// passive fold stops a few degrees on. An arm IK follows its wrist target freely to ELBOW_FOLD, eases
+// onto ELBOW_STOP (armReach) and leaves a target nearer the shoulder as a residual (REACH), like one
+// out of reach. Before, twoBone folded an arm flat: the forearm lay in the upper arm and the bend plane
+// was any plane at all (session df6acdcc, 171 deg).
+export const ELBOW_FOLD = 145, ELBOW_STOP = 150;
+// Knee flexion, read on the joints as QA reads it (UpLeg->Leg against Leg->Foot, 0 straight). Active
+// flexion ends near 135-140 deg (AAOS 135); past it the knee folds only passively, under the body's
+// weight, until the thigh rests on the calf: a deep squat with the heels down reaches 150-160 deg, and
+// passive flexion stops near 160 (the heel at the buttock). A leg IK follows its ankle target freely to
+// KNEE_FOLD (the squats the sessions keyed bend 125-138 deg), eases onto KNEE_STOP as the thigh presses
+// on the calf, and leaves a target nearer the hip as a residual (REACH leg_miss). Before, twoBone folded
+// a knee flat: the shin went into the thigh.
+export const KNEE_FOLD = 150, KNEE_STOP = 160;
+/** The flexion (deg) that puts the wrist d metres from the shoulder of an arm with bones a, b (180 at |a - b| or nearer). */
+export const flexionAt = (a, b, d) => (Math.acos(clamp((d * d - a * a - b * b) / (2 * a * b), -1, 1)) * 180) / Math.PI;
+/** The shoulder-wrist distance of an arm with bones a, b folded `deg` degrees. */
+export const reachAt = (a, b, deg) => Math.sqrt(a * a + b * b + 2 * a * b * Math.cos((deg * Math.PI) / 180));
+/**
+ * The shoulder-wrist distance an arm with bones a, b takes for a wrist target d metres away: d while
+ * the elbow folds ELBOW_FOLD or less (d >= k), then d + (k - d)^2 / 4w (w = k - the ELBOW_STOP distance)
+ * down to d = k - 2w, and the stop beyond. The wrist slows at a constant rate (C1, no kink as it
+ * engages: half the peak deceleration of an exponential ease as wide) and sits on the stop once the
+ * target is 2w inside. A leg passes KNEE_FOLD and KNEE_STOP (the hip-ankle distance).
+ */
+export function armReach(a, b, d, fold = ELBOW_FOLD, stop = ELBOW_STOP) {
+	const k = reachAt(a, b, fold);
+	if (d >= k) return d;
+	const w = k - reachAt(a, b, stop);
+	return d > k - 2 * w ? d + ((k - d) * (k - d)) / (4 * w) : k - w;
+}
+/**
+ * The wrist point an arm (shoulder S, bones a, b) reaches for a wrist target T: T while the elbow
+ * folds ELBOW_FOLD or less, else the point armReach(|T - S|) from the shoulder on the ray from the fold
+ * centre C through T. No point can stand for every target inside the stop and still move smoothly (a
+ * ball has no continuous retraction onto its boundary): the nearest point (the ray from the shoulder)
+ * whips round the shoulder as a target passes near it (session df6acdcc: 120 deg in 2 frames). So C
+ * sits on the stop's sphere straight behind the shoulder (`back`, the chest's -Z), in the back, where
+ * no hand reaches, and a target passing in front of, above, below or beside the shoulder glides.
+ * A leg passes the knee's fold and stop, and `back` is the pelvis's up (upOf): no foot goes into the
+ * pelvis, and a squat's ankle target under the hip goes on down from it.
+ */
+export function foldPoint(S, T, a, b, back, fold = ELBOW_FOLD, stop = ELBOW_STOP) {
+	const k = reachAt(a, b, fold), d = len(sub(T, S));
+	if (d >= k) return T;
+	const r = armReach(a, b, d, fold, stop), m = scale(back, reachAt(a, b, stop)), C = add(S, m), e = sub(T, C);
+	const u = len(e) > 1e-9 ? norm(e) : scale(back, -1), em = dot(u, m);
+	return add(C, scale(u, -em + Math.sqrt(Math.max(0, em * em - dot(m, m) + r * r))));
+}
+/** The direction behind the shoulders on pose s (the chest bone's rest -Z), where foldPoint's rays start. */
+export const backOf = (sk, s) => carried(sk, s, sk.index.Spine2 ?? sk.index.Hips, [0, 0, -1]);
+/** The direction up from the hips on pose s (the pelvis's rest +Y), where a knee's foldPoint rays start. */
+const upOf = (sk, s) => carried(sk, s, sk.index.Hips, [0, 1, 0]);
+/** The flexion (deg) an arm with bones a, b takes when `deg` is asked (armReach as an angle). */
+export const elbowFold = (a, b, deg) => flexionAt(a, b, armReach(a, b, reachAt(a, b, deg)));
+/** The flexion (deg) a wrist target asks of the arm of `side` on pose s (a leg's ankle target: bones UpLeg, Leg, Foot). */
+export function askedFold(sk, s, side, target, [u, m, e] = ["Arm", "ForeArm", "Hand"]) {
+	const S = s.P[sk.index[`${side}${u}`]], E = s.P[sk.index[`${side}${m}`]], W = s.P[sk.index[`${side}${e}`]];
+	return flexionAt(len(sub(E, S)), len(sub(W, E)), len(sub(target, S)));
+}
+
+/** Ease an elbow folded past ELBOW_FOLD (an FK abend) back as the IK would (elbowFold), the forearm turning in its bend plane. */
+export function limitFold(sk, s, side) {
+	const a = sk.index[`${side}Arm`], fa = sk.index[`${side}ForeArm`], up = sub(s.P[fa], s.P[a]), down = sub(s.P[sk.index[`${side}Hand`]], s.P[fa]);
+	const deg = (Math.acos(clamp(dot(norm(up), norm(down)), -1, 1)) * 180) / Math.PI, n = cross(up, down);
+	if (deg > ELBOW_FOLD && len(n) > 1e-12) rotateSubtree(sk, s, fa, s.P[fa].slice(), axisRot(n, elbowFold(len(up), len(down), deg) - deg));
+}
+
+/** The stops twoBone keeps to: the free fold and the stop (deg), and the fold centre's direction on pose s. */
+const STOPS = { elbow: [ELBOW_FOLD, ELBOW_STOP, backOf], knee: [KNEE_FOLD, KNEE_STOP, upOf] };
+
+/** Solve root-mid-end so `end` lands on `target` (clamped to reach), bending toward `pole`.
+ * `pole0` is the limb's current bend reference carried by the upper bone. Returns the miss (m).
+ * `stop`: "elbow" or "knee", the mid joint folds no further than armReach allows with that joint's
+ * fold and stop (foldPoint), and the miss is the residual either way (out of reach, or nearer the
+ * shoulder or hip than the fold). */
+export function twoBone(sk, s, root, mid, end, target, pole, restBend, stop = null) {
+	const Rt = s.P[root], M = s.P[mid], E = s.P[end];
+	const a = len(sub(M, Rt)), b = len(sub(E, M)), lim = STOPS[stop];
+	// a joint folds no further than armReach lets it: the end goes to foldPoint, and misses the target by the rest
+	const W = lim ? foldPoint(Rt, target, a, b, lim[2](sk, s), lim[0], lim[1]) : target, inside = W === target ? 0 : len(sub(W, target));
+	const v = sub(W, Rt), d = len(v), u = scale(v, 1 / Math.max(d, 1e-9));
+	const dc = clamp(d, Math.abs(a - b) + 1e-4, (a + b) * 0.9995);
+	const l = (a * a - b * b + dc * dc) / (2 * dc), h = Math.sqrt(Math.max(a * a - l * l, 0));
+	const pv = norm(sub(pole, scale(u, dot(pole, u))));
+	const Mn = add(Rt, add(scale(u, l), scale(pv, h)));
+	const p0 = carried(sk, s, root, restBend);
+	rotateSubtree(sk, s, root, Rt.slice(), align(sub(M, Rt), p0, sub(Mn, Rt), pv));
+	const p1 = carried(sk, s, mid, restBend);
+	const Tn = add(Rt, scale(u, dc));
+	rotateSubtree(sk, s, mid, s.P[mid].slice(), align(sub(s.P[end], s.P[mid]), p1, sub(Tn, s.P[mid]), pv));
+	return inside || d - dc;
+}
+
+/**
+ * Aim a foot: Foot->ToeBase along yaw/pitch of its rest direction, sole kept level. With `tilt` (pose.js tiltFrame: a body
+ * turned well past upright) the yaw and pitch are read in that frame and the sole levels to its up, so a foot in a flip
+ * points with the shin instead of staying flat to the floor; no toe-off then (the toes are off the ground).
+ */
+export function orientFoot(sk, s, side, yawDeg, pitchDeg, tilt = null) {
+	const foot = sk.index[`${side}Foot`], toe = sk.index[`${side}ToeBase`];
+	const rest = sub(sk.restWorldPos[toe], sk.restWorldPos[foot]);
+	const want = tilt ? apply(tilt.R, apply(ry(yawDeg - tilt.yaw), apply(rx(pitchDeg), rest))) : apply(ry(yawDeg), apply(rx(pitchDeg), rest));
+	const up = tilt ? apply(tilt.R, [0, 1, 0]) : [0, 1, 0];
+	// level the sole: the foot's own carried up vector goes to world up (no roll from the leg IK)
+	rotateSubtree(sk, s, foot, s.P[foot].slice(), align(sub(s.P[toe], s.P[foot]), carried(sk, s, foot, [0, 1, 0]), want, up));
+	// Toe-off: bend the toe joint so the toes stay flat on the ground while the heel rises.
+	const tip = sk.index[`${side}Toe_End`];
+	if (!tilt && pitchDeg > 0 && tip !== undefined) {
+		const seg = sub(s.P[tip], s.P[toe]), flat = [seg[0], 0, seg[2]];
+		if (len(flat) > 1e-6) rotateSubtree(sk, s, toe, s.P[toe].slice(), align(seg, [0, 1, 0], flat, [0, 1, 0]));
+	}
+}
+
+export function palmAxes(sk, s, side) {
+	const h = sk.index[`${side}Hand`], m1 = sk.index[`${side}HandMiddle1`];
+	const d = norm(sub(s.P[m1], s.P[h]));
+	let l = sub(s.P[sk.index[`${side}HandIndex1`]], s.P[sk.index[`${side}HandPinky1`]]);
+	l = norm(sub(l, scale(d, dot(l, d))));
+	return { d, l, n: cross(d, l) };
+}
+
+/** Turn the elbow `deg` about the shoulder-wrist line: the hand keeps its place and its world turn. */
+export function swivelElbow(sk, s, side, deg) {
+	const a = sk.index[`${side}Arm`], h = sk.index[`${side}Hand`], R = axisRot(sub(s.P[h], s.P[a]), deg);
+	rotateSubtree(sk, s, a, s.P[a].slice(), R);
+	rotateSubtree(sk, s, h, s.P[h].slice(), T(R));
+}
+
+/** Wrist twist (about the forearm) and flex (about the knuckle line), degrees, clamped. */
+export function wrist(sk, s, side, twistDeg, flexDeg) {
+	if (!twistDeg && !flexDeg) return;
+	const h = sk.index[`${side}Hand`], fa = sk.index[`${side}ForeArm`];
+	const axT = norm(sub(s.P[h], s.P[fa]));
+	const { l } = palmAxes(sk, s, side);
+	const axF = norm(sub(l, scale(axT, dot(l, axT))));
+	rotateSubtree(sk, s, h, s.P[h].slice(), axisRot(axF, clamp(flexDeg, -70, 70)));
+	rotateSubtree(sk, s, h, s.P[h].slice(), axisRot(axT, clamp(twistDeg, -85, 85)));
+}
+
+// Finger curl presets, degrees per phalanx (1, 2, 3); thumb is [opposition, curl, curl]. A fist and a grip keep the
+// relaxed thumb here and close it with THUMB_WRAP: these thumb curls turn about the knuckle line and the hand's long axis,
+// which only swings a thumb out to the side (a fist read as a thumbs-up).
+const FINGER_PRESETS = {
+	relaxed: { Index: [12, 18, 10], Middle: [15, 20, 12], Ring: [18, 22, 12], Pinky: [20, 24, 14], Thumb: [15, 10, 8] },
+	fist: { Index: [80, 95, 60], Middle: [85, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [15, 10, 8] },
+	grip: { Index: [55, 60, 35], Middle: [60, 62, 35], Ring: [62, 62, 35], Pinky: [65, 62, 35], Thumb: [15, 10, 8] },
+	cigarette: { Index: [8, 10, 6], Middle: [10, 12, 8], Ring: [60, 75, 45], Pinky: [65, 80, 45], Thumb: [35, 25, 20] },
+	point: { Index: [0, 0, 0], Middle: [80, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [40, 30, 30] },
+};
+
+/** Blend presets by weight over `relaxed` and curl every finger toward the palm. */
+export function fingers(sk, s, side, weights) {
+	const base = FINGER_PRESETS.relaxed, sign = side === "Left" ? -1 : 1;
+	const curl = (f, k) => base[f][k] + Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * ((FINGER_PRESETS[p]?.[f]?.[k] ?? base[f][k]) - base[f][k]), 0);
+	for (const f of ["Index", "Middle", "Ring", "Pinky", "Thumb"]) {
+		for (let k = 0; k < 3; k++) {
+			const j = sk.index[`${side}Hand${f}${k + 1}`];
+			if (j === undefined) continue;
+			const { l, d } = palmAxes(sk, s, side);
+			const ax = f === "Thumb" && k === 0 ? d : l;
+			rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(ax, sign * curl(f, k)));
+		}
+	}
+	const wrap = [0, 1, 2, 3].map(i => Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * (THUMB_WRAP[p]?.[i] ?? 0), 0));
+	if (wrap.some(Boolean)) wrapThumb(sk, s, side, wrap);
+}
+
+// A closing hand's thumb, by preset weight after the relaxed one, degrees: turned in about the hand's long axis toward the
+// palm and across it, then flexed at its two joints about their own axes (bone x palm normal). The fist's thumb lies over
+// the index and middle fingers' middle phalanges; the grip's closes around a handle against the index finger. Searched on
+// both rigs within the joints' ranges (thumb tip to the index's middle phalanx: fist 8.4 -> 3.7 cm Y Bot, 6.9 -> 2.4 X Bot).
+const THUMB_WRAP = { fist: [-70, -5, 5, 80], grip: [-30, -30, 30, 10] };
+function wrapThumb(sk, s, side, [oppose, across, flex2, flex3]) {
+	const sign = side === "Left" ? -1 : 1, J = k => sk.index[`${side}HandThumb${k}`];
+	if (J(1) === undefined) return;
+	const { d, n } = palmAxes(sk, s, side);
+	rotateSubtree(sk, s, J(1), s.P[J(1)].slice(), axisRot(d, sign * oppose));
+	// n = d x l flips with the mirror, so the turn across the palm keeps its sign on both hands
+	rotateSubtree(sk, s, J(1), s.P[J(1)].slice(), axisRot(n, across));
+	for (const [k, deg] of [[2, flex2], [3, flex3]]) {
+		const ax = norm(cross(norm(sub(s.P[J(k + 1)], s.P[J(k)])), n));
+		rotateSubtree(sk, s, J(k), s.P[J(k)].slice(), axisRot(ax, sign * deg));
+	}
+}
+

package/src/motion3/compiler/math.js

@@ -0,0 +1,72 @@
+// Small dependency-free vector / 3x3 / quaternion helpers for the motion3 compiler.
+// Vectors are [x, y, z]; matrices are row-major [[...],[...],[...]] acting on column
+// vectors (R v); quaternions are three.js order [x, y, z, w].
+
+export const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const scale = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+export const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+export const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+export const len = a => Math.hypot(a[0], a[1], a[2]);
+export const dist = (a, b) => len(sub(a, b));
+export function norm(a) {
+	const l = len(a);
+	return l > 1e-12 ? [a[0] / l, a[1] / l, a[2] / l] : [0, 0, 0];
+}
+export const clamp = (x, lo, hi) => Math.min(hi, Math.max(lo, x));
+const rad = d => d * Math.PI / 180;
+const deg = r => r * 180 / Math.PI;
+
+export const I3 = () => [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+export function mul(A, B) {
+	const C = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+	for (let i = 0; i < 3; i++) for (let j = 0; j < 3; j++) C[i][j] = A[i][0] * B[0][j] + A[i][1] * B[1][j] + A[i][2] * B[2][j];
+	return C;
+}
+export const apply = (R, v) => [R[0][0] * v[0] + R[0][1] * v[1] + R[0][2] * v[2], R[1][0] * v[0] + R[1][1] * v[1] + R[1][2] * v[2], R[2][0] * v[0] + R[2][1] * v[1] + R[2][2] * v[2]];
+export const T = R => [[R[0][0], R[1][0], R[2][0]], [R[0][1], R[1][1], R[2][1]], [R[0][2], R[1][2], R[2][2]]];
+const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];
+
+export function rx(d) { const t = rad(d), c = Math.cos(t), s = Math.sin(t); return [[1, 0, 0], [0, c, -s], [0, s, c]]; }
+export function ry(d) { const t = rad(d), c = Math.cos(t), s = Math.sin(t); return [[c, 0, s], [0, 1, 0], [-s, 0, c]]; }
+export function rz(d) { const t = rad(d), c = Math.cos(t), s = Math.sin(t); return [[c, -s, 0], [s, c, 0], [0, 0, 1]]; }
+
+/** Rotation by `d` degrees about unit-normalised axis `ax` (Rodrigues). */
+export function axisRot(ax, d) {
+	const [x, y, z] = norm(ax), t = rad(d), c = Math.cos(t), s = Math.sin(t), k = 1 - c;
+	return [[c + x * x * k, x * y * k - z * s, x * z * k + y * s], [y * x * k + z * s, c + y * y * k, y * z * k - x * s], [z * x * k - y * s, z * y * k + x * s, c + z * z * k]];
+}
+
+/** Orthonormal frame whose first column is d and second lies toward p. */
+function frame(d, p) {
+	const a = norm(d);
+	let b = sub(p, scale(a, dot(p, a)));
+	if (len(b) < 1e-9) b = sub([0, 1, 0], scale(a, a[1])), len(b) < 1e-9 && (b = sub([1, 0, 0], scale(a, a[0])));
+	b = norm(b);
+	return cols(a, b, cross(a, b));
+}
+
+/** Rotation taking frame (d0, p0) onto frame (d1, p1). */
+export const align = (d0, p0, d1, p1) => mul(frame(d1, p1), T(frame(d0, p0)));
+
+export function quatFromMat(R) {
+	const m00 = R[0][0], m11 = R[1][1], m22 = R[2][2], tr = m00 + m11 + m22;
+	let x, y, z, w;
+	if (tr > 0) { const s = 0.5 / Math.sqrt(tr + 1); w = 0.25 / s; x = (R[2][1] - R[1][2]) * s; y = (R[0][2] - R[2][0]) * s; z = (R[1][0] - R[0][1]) * s; }
+	else if (m00 > m11 && m00 > m22) { const s = 2 * Math.sqrt(1 + m00 - m11 - m22); w = (R[2][1] - R[1][2]) / s; x = 0.25 * s; y = (R[0][1] + R[1][0]) / s; z = (R[0][2] + R[2][0]) / s; }
+	else if (m11 > m22) { const s = 2 * Math.sqrt(1 + m11 - m00 - m22); w = (R[0][2] - R[2][0]) / s; x = (R[0][1] + R[1][0]) / s; y = 0.25 * s; z = (R[1][2] + R[2][1]) / s; }
+	else { const s = 2 * Math.sqrt(1 + m22 - m00 - m11); w = (R[1][0] - R[0][1]) / s; x = (R[0][2] + R[2][0]) / s; y = (R[1][2] + R[2][1]) / s; z = 0.25 * s; }
+	const l = Math.hypot(x, y, z, w);
+	return [x / l, y / l, z / l, w / l];
+}
+
+export function matFromQuat([x, y, z, w]) {
+	return [
+		[1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)],
+		[2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)],
+		[2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)],
+	];
+}
+
+/** Angle in degrees between two directions. */
+export const angle = (a, b) => deg(Math.acos(clamp(dot(norm(a), norm(b)), -1, 1)));

package/src/motion3/compiler/pose.js

@@ -0,0 +1,177 @@
+// One frame of the body: channel values -> world-space bone state.
+// Conventions (CozyClay): metres, +Y up, yaw 0 faces +Z, positive yaw turns toward +X,
+// the character's left is +X at yaw 0. Body-frame vectors (poles, body-local targets) are
+// rotated by the root yaw only.
+import { add, sub, scale, norm, len, apply, mul, rx, ry, rz } from "./math.js";
+import { restState, rotateSubtree } from "./skeleton.js";
+import { twoBone, orientFoot, wrist, fingers, limitFold, askedFold, swivelElbow, ELBOW_FOLD, KNEE_FOLD } from "./limbs.js";
+import { holdHand } from "./hold.js";
+import { clampWrist } from "./wrist-clamp.js";
+import { ELBOW_REST } from "./arm-orient.js";
+import { wristBody, bodyDistance } from "../body.js";
+
+export const SIDES = { l: "Left", r: "Right" };
+/** How much of an auto-fix elbow turn an arm at IK weight w takes (fix/self.js plans with the same). */
+export const turnWeight = w => { const x = Math.min(1, Math.max(0, w)); return x * x * (3 - 2 * x); };
+const KNEE_REST = [0, 0, 1], LEG = ["UpLeg", "Leg", "Foot"];
+
+const v3 = (x, d = [0, 0, 0]) => (Array.isArray(x) || ArrayBuffer.isView(x) ? [x[0], x[1], x[2]] : d);
+const num = (x, d = 0) => (typeof x === "number" && Number.isFinite(x) ? x : d);
+
+/** Split a body-frame rotation over a chain of bones, each turning about its own joint. */
+function spread(sk, s, bones, yaw, pitch, roll) {
+	const k = bones.length;
+	for (const name of bones) {
+		const b = sk.index[name];
+		rotateSubtree(sk, s, b, s.P[b].slice(), mul(ry(yaw / k), mul(rx(pitch / k), rz(roll / k))));
+	}
+}
+
+// Soft reach (spec.fix.reach): a wrist target up to 5 cm beyond the arm's reach is pulled onto
+// the reach sphere through a C1 soft knee, so the arm never snaps straight; the overshoot is
+// recorded. Farther targets are staging errors and stay for QA (REACH).
+const SOFT_KNEE = 0.99, SOFT_MAX = 0.9995;
+export const REACH_FIX_MAX = 0.05;
+function softReach(sk, s, a, fa, h, target, diag, k) {
+	const R = len(sub(s.P[fa], s.P[a])) + len(sub(s.P[h], s.P[fa])), v = sub(target, s.P[a]), d = len(v);
+	const k0 = SOFT_KNEE * R, w = (SOFT_MAX - SOFT_KNEE) * R;
+	if (d <= k0 || d - SOFT_MAX * R > REACH_FIX_MAX) return target;
+	const dc = k0 + w * (1 - Math.exp(-(d - k0) / w));
+	diag[`reach_over_${k}`] = Math.max(0, d - SOFT_MAX * R);
+	return add(s.P[a], scale(v, dc / d));
+}
+
+/**
+ * hooks.handTarget(side, s) -> { target:[x,y,z] } world wrist target before the FK/IK blend
+ * hooks.afterArm(side, s, diag) lets the caller measure props carried by that hand.
+ * hooks.push(side) -> [x,y,z] | undefined, a world offset added to the IK target (auto-fix); hooks.skinPush(side) the same
+ * for the self fix (fix/self.js), taken as far as the arm is on its IK.
+ * hooks.softReach clamps unreachable wrist targets smoothly (auto-fix).
+ * hooks.foldFree lets the arm IK fold past the elbow's stop (a fit's measuring passes, compile.js).
+ * hooks.hold(side, s) -> { w, palm, measure, pole?, second? } | null: a held object's keys lead the hand (hold.js).
+ * hooks.keepOut(side, s, target) -> target: the blended wrist target kept out of the body (auto-fix, compile.js).
+ * hooks.swivel(side) -> deg | undefined, an elbow turn about the shoulder-wrist line, the hand kept (auto-fix, fix/self.js).
+ * diag.arm_fold_<k>: the flexion (deg) the wrist target asked when past ELBOW_FOLD (arm_miss_<k> is then how far inside).
+ * diag.leg_fold_<k>: the knee flexion (deg) the ankle target asked when past KNEE_FOLD (leg_miss_<k> is then how far inside).
+ */
+// arm_hang (keyed by standIdle and the walk): a free FK forearm hangs plumb from the elbow, as a person's does,
+// instead of carrying on the upper arm's slant out from the body (the hands sat about 9 cm wider than a person's);
+// a working arm (on IK, or a hand that holds something: compile.js hangoff, idle.js busyHands) takes none of it. A rig whose thigh comes near (the X Bot) stops HANG_BACK
+// degrees short of the first angle that brings its forearm or hand within HANG_CLEAR of the skin standing, so the
+// walk's sway does not carry it into the thigh. Faded out as arm_rest raises the arms (none at 45); once per rig and rest.
+const HANG_CLEAR = 0.095, HANG_BACK = 2, hangs = new Map();
+function hangOf(sk, down) {
+	const key = `${sk.model}|${down}`;
+	if (hangs.has(key)) return hangs.get(key);
+	const full = (90 - down) * Math.min(1, Math.max(0, (down - 45) / 27)), wb = wristBody(sk);
+	const clearAt = h => {
+		const s = restState(sk);
+		return [["Left", -1], ["Right", 1]].every(([side, sg]) => {
+			const a = sk.index[`${side}Arm`], fa = sk.index[`${side}ForeArm`], hd = sk.index[`${side}Hand`], tip = sk.index[`${side}HandMiddle1`];
+			rotateSubtree(sk, s, a, s.P[a].slice(), rz(sg * down));
+			rotateSubtree(sk, s, fa, s.P[fa].slice(), rz(sg * h));
+			const pts = [0.5, 0.75, 1].map(t => add(s.P[fa], scale(sub(s.P[hd], s.P[fa]), t))).concat([s.P[tip]]);
+			return pts.every(p => bodyDistance(wb.body, s, p, wb.skip).d >= HANG_CLEAR);
+		});
+	};
+	let hang = full;
+	if (wb && full > 0) {
+		for (let h = 0; h <= full; h += 0.5) if (!clearAt(h)) { hang = Math.max(0, h - HANG_BACK); break; }
+	}
+	hangs.set(key, hang);
+	return hang;
+}
+
+/**
+ * The frame the knee and elbow poles and the feet are read in once the whole body turns well past upright (a flip, a
+ * cartwheel): the root's yaw, pitch and roll, the tilt eased in from TILT_FROM to TILT_FULL degrees (the larger of the
+ * wrapped pitch and roll). Under TILT_FROM it is null and the poles turn with the yaw only, as they always have, so an
+ * upright take is unchanged.
+ */
+const TILT_FROM = 60, TILT_FULL = 120;
+const wrap180 = a => a - 360 * Math.round(a / 360);
+export function tiltFrame(yaw, pitch, roll) {
+	const p = wrap180(pitch), r = wrap180(roll), u = (Math.max(Math.abs(p), Math.abs(r)) - TILT_FROM) / (TILT_FULL - TILT_FROM);
+	if (u <= 0) return null;
+	const w = u >= 1 ? 1 : u * u * (3 - 2 * u);
+	return { yaw, R: mul(ry(yaw), mul(rx(p * w), rz(r * w))) };
+}
+
+export function pose(sk, c, hooks = {}) {
+	const s = restState(sk);
+	const diag = {};
+	// Base: arms down from the bind T-pose (body frame, before everything else).
+	const down = num(c.arm_rest, 72), hang = num(c.arm_hang) && num(c.arm_hang) * hangOf(sk, down);
+	for (const [side, sg, k] of [["Left", -1, "l"], ["Right", 1, "r"]]) {
+		const a = sk.index[`${side}Arm`], fa = sk.index[`${side}ForeArm`], h = hang * (1 - Math.min(1, Math.max(0, num(c[`armw_${k}`]) + num(c[`hangoff_${k}`]))));
+		rotateSubtree(sk, s, a, s.P[a].slice(), rz(sg * down));
+		if (h) rotateSubtree(sk, s, fa, s.P[fa].slice(), rz(sg * h));
+	}
+	// FK arm swing (forward +) and elbow bend, body frame.
+	for (const [k, side] of Object.entries(SIDES)) {
+		const bd = num(c[`abend_${k}`]), sw = num(c[`aswing_${k}`]);
+		const fa = sk.index[`${side}ForeArm`], a = sk.index[`${side}Arm`];
+		// an FK bend past the fold eases to its stop like the IK (limbs.js elbowFold)
+		if (bd) { rotateSubtree(sk, s, fa, s.P[fa].slice(), rx(-bd)); limitFold(sk, s, side); }
+		if (sw) rotateSubtree(sk, s, a, s.P[a].slice(), rx(-sw));
+	}
+	spread(sk, s, ["Neck", "Head"], num(c.head_yaw), num(c.head_pitch), num(c.head_roll));
+	spread(sk, s, ["Spine", "Spine1", "Spine2"], num(c.spine_yaw), num(c.spine_pitch), num(c.spine_roll));
+	// Root: turn about the hips joint, then put the hips at `root`.
+	const hips = sk.index.Hips, yaw = num(c.yaw);
+	rotateSubtree(sk, s, hips, s.P[hips].slice(), mul(ry(yaw), mul(rx(num(c.pitch)), rz(num(c.roll)))));
+	const shift = sub(v3(c.root, s.P[hips]), s.P[hips]);
+	for (let j = 0; j < s.P.length; j++) s.P[j] = add(s.P[j], shift);
+	const tilt = tiltFrame(yaw, num(c.pitch), num(c.roll)), body = tilt?.R ?? ry(yaw);
+	// Legs: two-bone IK to the ankle targets, the knee no further folded than its stop (limbs.js KNEE_STOP), then aim the feet.
+	for (const [k, side] of Object.entries(SIDES)) {
+		if (!c[`foot_${k}`]) continue;
+		const target = v3(c[`foot_${k}`]);
+		diag[`leg_miss_${k}`] = twoBone(sk, s, sk.index[`${side}UpLeg`], sk.index[`${side}Leg`], sk.index[`${side}Foot`],
+			target, apply(body, v3(c[`knee_${k}`], KNEE_REST)), KNEE_REST, "knee");
+		// a target nearer the hip than the knee folds leaves a residual (leg_miss); leg_fold says what it asked
+		const fold = askedFold(sk, s, side, target, LEG);
+		if (fold > KNEE_FOLD) diag[`leg_fold_${k}`] = fold;
+		orientFoot(sk, s, side, num(c[`fyaw_${k}`], yaw), num(c[`fpitch_${k}`]), tilt);
+	}
+	// Arms: blend the FK hand toward the hook's target, poles blended the same way.
+	for (const k of hooks.armOrder ?? ["r", "l"]) {
+		const side = SIDES[k], w = num(c[`armw_${k}`]);
+		const a = sk.index[`${side}Arm`], fa = sk.index[`${side}ForeArm`], h = sk.index[`${side}Hand`];
+		const poleIk = norm(apply(body, v3(c[`elbow_${k}`], [0, -1, -0.3])));
+		diag[`arm_miss_${k}`] = 0;
+		if (w > 1e-4 && hooks.handTarget) {
+			const fkHand = s.P[h].slice();
+			const goal = hooks.handTarget(k, s, diag) ?? fkHand;
+			let target = add(fkHand, scale(sub(goal, fkHand), w));
+			if (hooks.keepOut) target = hooks.keepOut(k, s, target);
+			const push = hooks.push?.(k);
+			if (push) target = add(target, push);
+			// the self fix's push rides the IK as far as the arm is on it (an arm coming in from FK would jump)
+			const skinPush = hooks.skinPush?.(k);
+			if (skinPush) target = add(target, scale(skinPush, turnWeight(w)));
+			if (hooks.softReach) target = softReach(sk, s, a, fa, h, target, diag, k);
+			const poleFk = norm(sub(s.P[fa], scale(add(s.P[a], fkHand), 0.5)));
+			const pole = add(scale(poleFk, 1 - w), scale(poleIk, w));
+			// a target nearer the shoulder than the elbow folds leaves a residual too; arm_fold says what it asked
+			diag[`arm_miss_${k}`] = twoBone(sk, s, a, fa, h, target, pole, ELBOW_REST, hooks.foldFree ? null : "elbow");
+			const fold = askedFold(sk, s, side, target);
+			if (fold > ELBOW_FOLD && !hooks.foldFree) diag[`arm_fold_${k}`] = fold;
+		}
+		wrist(sk, s, side, num(c[`wtwist_${k}`]), num(c[`wflex_${k}`]));
+		fingers(sk, s, side, c[`fingers_${k}`]);
+		const held = hooks.hold?.(k, s);
+		// a keyed carry's hand follows its object; else a fit's hand takes a grip on the body under its anchor (grip.js),
+		// and while the keys only ease in (before the first key) the arm they ease from takes it too
+		if (!held || held.w < 1) hooks.grip?.(k, s, diag);
+		if (held) holdHand(sk, s, side, held, ELBOW_REST, diag, k);
+		// after a held object's grip, so its hand keeps the grip the hold solved; an arm coming in from FK turns
+		// no more than its IK weight (the IK elbow already lands somewhere else than the FK one)
+		const turn = hooks.swivel?.(k);
+		// the turn keeps the hand's world turn; a wrist it takes past its limits stops there and the hand turns with the elbow
+		// (wrist-clamp.js), unless keys lead what the hand holds: that hand keeps the object's grip (hold.js limits its wrist)
+		if (turn) { swivelElbow(sk, s, side, turn * turnWeight(w)); if (!held) clampWrist(sk, s, side); }
+		hooks.afterArm?.(k, s, diag);
+	}
+	return { s, diag };
+}

package/src/motion3/compiler/quat.js

@@ -0,0 +1,49 @@
+// Quaternion helpers for the held-object keys (../object-keys.js) and the hand-from-object solve
+// (hold.js). Quaternions are three.js order [x, y, z, w], as math.js quatFromMat / matFromQuat;
+// a rotation vector is axis * radians.
+
+export const qmul = (a, b) => [
+	a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+	a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+	a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+	a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+];
+export const qconj = q => [-q[0], -q[1], -q[2], q[3]];
+export const qdot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+export function qnorm(q) {
+	const l = Math.hypot(q[0], q[1], q[2], q[3]);
+	return l > 1e-12 ? [q[0] / l, q[1] / l, q[2] / l, q[3] / l] : [0, 0, 0, 1];
+}
+
+/** Rotation vector of unit q, the short way round (|v| <= pi). */
+export function qlog(q) {
+	const sg = q[3] < 0 ? -1 : 1, x = q[0] * sg, y = q[1] * sg, z = q[2] * sg, w = q[3] * sg, s = Math.hypot(x, y, z);
+	if (s < 1e-12) return [2 * x, 2 * y, 2 * z];
+	const a = 2 * Math.atan2(s, w) / s;
+	return [x * a, y * a, z * a];
+}
+
+/** Unit quaternion of rotation vector v. */
+export function qexp(v) {
+	const a = Math.hypot(v[0], v[1], v[2]);
+	if (a < 1e-12) return qnorm([v[0] / 2, v[1] / 2, v[2] / 2, 1]);
+	const s = Math.sin(a / 2) / a;
+	return [v[0] * s, v[1] * s, v[2] * s, Math.cos(a / 2)];
+}
+
+/** Rotate vector v by unit q. */
+export const qrot = (q, v) => qmul(qmul(q, [v[0], v[1], v[2], 0]), qconj(q)).slice(0, 3);
+
+/** The shortest turn taking unit direction a onto unit direction b (half a turn about a normal of a when they are opposite). */
+export function arcQuat(a, b) {
+	const w = 1 + a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+	if (w > 1e-9) return qnorm([a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0], w]);
+	const n = Math.abs(a[0]) < 0.9 ? [0, a[2], -a[1]] : [-a[2], 0, a[0]], l = Math.hypot(...n);
+	return [n[0] / l, n[1] / l, n[2] / l, 0];
+}
+
+/** The turn by `deg` degrees about unit axis `u` (right-handed). */
+export const axisQuat = (u, deg) => { const h = deg * Math.PI / 360, s = Math.sin(h); return [u[0] * s, u[1] * s, u[2] * s, Math.cos(h)]; };
+
+/** a -> b by t along the short arc (t = 0: a, t = 1: b). */
+export const slerp = (a, b, t) => qmul(a, qexp(qlog(qmul(qconj(a), b)).map(c => c * t)));

package/src/motion3/compiler/skeleton.js

@@ -0,0 +1,74 @@
+// Rig skeleton for the motion3 compiler: bind data from src/motion3/rigs/<model>.json
+// (extracted by tools/motion3/extract-rig.mjs), in METRES, rig root at the origin
+// facing +Z with +X on the character's left.
+import { apply, add, sub, mul, T, matFromQuat, quatFromMat } from "./math.js";
+
+const CM = 0.01;
+
+export function createSkeleton(rigJson) {
+	const bones = rigJson.bones;
+	const names = bones.map(b => b.name);
+	const index = Object.fromEntries(names.map((n, i) => [n, i]));
+	const parent = bones.map(b => b.parent);
+	const children = names.map(() => []);
+	parent.forEach((p, i) => { if (p >= 0) children[p].push(i); });
+	// subtree[i] = i and every descendant, parents before children
+	const subtree = names.map((_, i) => {
+		const out = [], stack = [i];
+		while (stack.length) { const j = stack.shift(); out.push(j); stack.unshift(...children[j]); }
+		return out;
+	});
+	const restLocalPos = bones.map(b => b.localPos.map(v => v * CM));
+	const restLocalRot = bones.map(b => matFromQuat(b.localQuat));
+	const restWorldPos = bones.map(b => b.worldPos.map(v => v * CM));
+	const restWorldRot = bones.map(b => matFromQuat(b.worldQuat));
+	const L = rigJson.landmarks;
+	const head = index.Head;
+	// Landmarks re-expressed in the Head bone's rest frame, so they ride the head.
+	const toHead = p => apply(T(restWorldRot[head]), sub(p.map(v => v * CM), restWorldPos[head]));
+	const landmarks = {
+		mouth: toHead(L.mouth),
+		headCentre: toHead(L.headEllipsoid.centre),
+		headRadii: L.headEllipsoid.radii.map(v => v * CM),
+		// how far the skin's sole lies below the ToeBase / Toe_End joints at bind (m; qa/geometry.js solePoints)
+		sole: { ball: (L.sole?.ball ?? 0) * CM, tip: (L.sole?.tip ?? 0) * CM },
+	};
+	return { model: rigJson.model, names, index, parent, children, subtree, restLocalPos, restLocalRot, restWorldPos, restWorldRot, landmarks };
+}
+
+/** Rest pose as a mutable world-space state { P, R }. */
+export function restState(sk) {
+	return { P: sk.restWorldPos.map(p => p.slice()), R: sk.restWorldRot.map(r => r.map(row => row.slice())) };
+}
+
+/** Rigidly rotate bone `b`'s subtree by world rotation R about world point `pivot`. */
+export function rotateSubtree(sk, s, b, pivot, R) {
+	for (const j of sk.subtree[b]) {
+		s.P[j] = add(pivot, apply(R, sub(s.P[j], pivot)));
+		s.R[j] = mul(R, s.R[j]);
+	}
+}
+
+/** World state -> per-bone LOCAL quaternions [x,y,z,w] plus the hips local position (m). */
+export function toLocal(sk, s) {
+	const quats = sk.names.map((_, j) => {
+		const p = sk.parent[j];
+		return quatFromMat(p < 0 ? s.R[j] : mul(T(s.R[p]), s.R[j]));
+	});
+	return { quats, hips: s.P[sk.index.Hips].slice() };
+}
+
+/** Forward kinematics from local quaternions + hips position back to a world state. */
+export function fk(sk, quats, hips) {
+	const P = [], R = [];
+	for (const j of sk.subtree[sk.index.Hips]) {
+		const p = sk.parent[j], Lr = matFromQuat(quats[j]);
+		if (p < 0) { R[j] = Lr; P[j] = hips.slice(); continue; }
+		R[j] = mul(R[p], Lr);
+		P[j] = add(P[p], apply(R[p], sk.restLocalPos[j]));
+	}
+	return { P, R };
+}
+
+/** Point fixed to a bone, given in that bone's own frame (e.g. a landmark). */
+export const bonePoint = (s, b, local) => add(s.P[b], apply(s.R[b], local));

package/src/motion3/compiler/validate-common.js

@@ -0,0 +1,32 @@
+// The checks every part of the validator shares: a bone, a scene object, a check point.
+// Messages are exact (the agent fixes them in one edit). See validate.js.
+import { didYouMean } from "./vocab.js";
+import { partsOf } from "../object-pose.js";
+
+export function boneOk(err, sk, at, bone) {
+	if (!sk || sk.index[bone] !== undefined) return true;
+	err(`${at} names unknown bone "${bone}"${didYouMean(String(bone), sk.names)}`);
+	return false;
+}
+
+/**
+ * A scene object id. A group (an Empty: no box of its own) passes only with { groups: true }
+ * (carry, hinge, object: refs and object anchors take groups, see C3); elsewhere the message lists its parts.
+ */
+export function objectOk(err, scene, at, id, { groups = false } = {}) {
+	const ids = Object.keys(scene?.objects ?? {});
+	if (!ids.length || ids.includes(id)) return true;
+	const parts = partsOf(scene, id);
+	if (parts.length && groups) return true;
+	if (parts.length) err(`${at} names "${id}", a group (Empty) with no body of its own; its parts are ${parts.join(", ")}. Name one part`);
+	else err(`${at} names object "${id}", which is not in the scene${didYouMean(String(id), [...new Set([...ids, ...ids.flatMap(k => scene.objects[k].ancestors ?? []), ...Object.keys(scene.others ?? {})])])}`);
+	return false;
+}
+
+export function refOk(spec, err, sk, at, ref) {
+	const [kind, rest] = String(ref).split(/:(.*)/s);
+	if (kind === "joint") return boneOk(err, sk, at, rest);
+	if (kind === "anchor") return spec.anchors?.[rest] ? true : err(`${at} "${ref}" names no anchor`);
+	if (kind === "prop") { const [p, pt] = (rest ?? "").split("."); return spec.props?.[p]?.points?.[pt] || pt === "origin" ? true : err(`${at} "${ref}" names no prop point`); }
+	err(`${at} "${ref}" must be joint:<Bone>, prop:<prop>.<point> or anchor:<name>`);
+}