cozyclay 3.1.5 → 3.2.0

package/src/motion3/compiler/spring.js

@@ -0,0 +1,95 @@
+// Spring secondary motion for a carried or free object (spec.objects[id].spring = { length, stiffness, damping }): a damped
+// pendulum hung on the object's anchor lags the anchor's horizontal acceleration, swings and settles. Computed once at
+// compile time (object-pose.js rootPoseAt); playback, scrub and export read the baked track only.
+//
+// Determinism: a fixed step dt = 1 / fps from frame 0 on, semi-implicit Euler, and the solver update uses
+// only + - * / and Math.sqrt, so every engine computes the same bits. Only the last step, the swing angles to a turn,
+// goes through the quaternion helpers (quat.js), as every other baked rotation does.
+//
+// State: two swing angles th = [tx, tz] (rad), how far the object's far end swings toward world +X and +Z, and their
+// rates w. Per frame f: a = (p[f] - 2 p[f-1] + p[f-2]) * fps^2 (0 on frames 0 and 1), then
+//   w = (w + (-k th - a_h / L) dt) / (1 + c dt) ;  th += w dt ;  c = 2 d sqrt(k)
+// with k the stiffness (1/s^2), d the damping ratio (0..1, 1 critical) and L the pendulum length (m): spring.length, else
+// half the object's longest side (springLength). Without a stiffness k = G / L, a real pendulum's sqrt(g / L). The damping is
+// implicit, so no damping ratio makes it ring up (an explicit c dt > 1 diverged); the stiffness step stays stable while
+// sqrt(k) dt < 2, and the schema caps k at SPRING.stiffness.max (500) so that sqrt(k) dt <= 1 from 24 fps up.
+import { qexp, qmul, qnorm } from "./quat.js";
+import { quatFromMat, matFromQuat } from "./math.js";
+
+/** The schema's ranges and defaults (schema/types.js reads them; validate-objects.js checks them). No stiffness default: G / length. */
+export const SPRING = { length: { min: 0.05, max: 2 }, stiffness: { min: 0, max: 500 }, damping: { min: 0, max: 1, default: 0.5 } };
+/** Gravity, m/s^2 (qa/style.js and skills/impact.js use the same value). */
+const G = 9.81;
+/** The largest swing drawn, rad (60 degrees). */
+const SPRING_MAX = Math.PI / 3;
+/** The shortest pendulum, m: a tiny prop swings as if it were this long. */
+const SPRING_MIN_LENGTH = 0.05;
+
+const clampSwing = v => (v > SPRING_MAX ? SPRING_MAX : v < -SPRING_MAX ? -SPRING_MAX : v);
+
+/** The resting state: no swing, no anchor history. */
+export const springRest = () => ({ th: [0, 0], w: [0, 0], p1: null, p2: null });
+
+/**
+ * One frame: the state after anchor position p (world [x, y, z]) is fed to `state` (the state after the frame before).
+ * Pure: returns a new state. opts = { fps, stiffness, damping, length }.
+ */
+export function springStep(state, p, { fps, stiffness, damping, length }) {
+	const dt = 1 / fps, k = stiffness, c = 2 * damping * Math.sqrt(stiffness), L = length > SPRING_MIN_LENGTH ? length : SPRING_MIN_LENGTH;
+	let ax = 0, az = 0;
+	if (state.p1 && state.p2) {
+		const f2 = fps * fps;
+		ax = (p[0] - 2 * state.p1[0] + state.p2[0]) * f2;
+		az = (p[2] - 2 * state.p1[2] + state.p2[2]) * f2;
+	}
+	const wx = (state.w[0] + (-k * state.th[0] - ax / L) * dt) / (1 + c * dt);
+	const wz = (state.w[1] + (-k * state.th[1] - az / L) * dt) / (1 + c * dt);
+	return { th: [state.th[0] + wx * dt, state.th[1] + wz * dt], w: [wx, wz], p1: [p[0], p[1], p[2]], p2: state.p1 };
+}
+
+/**
+ * The solver options for spring entry `spring` ({ length?, stiffness?, damping? }) at `fps`: the length given, else
+ * `fallback` (springLength of the object); the stiffness given, else G / length; the damping given, else 0.5.
+ */
+export function springOpts(spring, fps, fallback = SPRING_MIN_LENGTH) {
+	const length = Math.max(SPRING_MIN_LENGTH, spring?.length ?? fallback);
+	return { fps, stiffness: spring?.stiffness ?? G / length, damping: spring?.damping ?? SPRING.damping.default, length };
+}
+
+/**
+ * The swing of every frame for anchor positions `anchors` (one world [x, y, z] per frame from frame 0):
+ * [[tx, tz], ...] rad, each clamped to +-60 degrees. A still anchor gives 0 on every frame. Defaults as springOpts.
+ */
+export function springAngles({ anchors, fps, stiffness, damping, length }) {
+	const opts = springOpts({ stiffness, damping, length }, fps), out = [];
+	let state = springRest();
+	for (const p of anchors) {
+		state = springStep(state, p, opts);
+		out.push([clampSwing(state.th[0]), clampSwing(state.th[1])]);
+	}
+	return out;
+}
+
+/** The clamped swing of a state. */
+export const swingOf = state => [clampSwing(state.th[0]), clampSwing(state.th[1])];
+
+/**
+ * Pose { pos, R } turned by swing th = [tx, tz] about its own base (position unchanged): +tx swings what hangs below
+ * toward +X (a turn about +Z), +tz toward +Z (a turn about -X). The turn is applied in world axes on top of R.
+ */
+export function swungPose(pose, th) {
+	if (th[0] === 0 && th[1] === 0) return pose;
+	const turn = qexp([-th[1], 0, th[0]]);
+	return { ...pose, pos: pose.pos, R: matFromQuat(qnorm(qmul(turn, quatFromMat(pose.R)))) };
+}
+
+/** Pendulum length of a body or group from its boxes [{ pos, R, half }]'s corners: half the longest side of their bounding box, at least 5 cm. */
+export function springLength(corners) {
+	if (!corners.length) return SPRING_MIN_LENGTH;
+	let longest = 0;
+	for (let i = 0; i < 3; i++) {
+		const vs = corners.map(c => c[i]);
+		longest = Math.max(longest, Math.max(...vs) - Math.min(...vs));
+	}
+	return Math.max(SPRING_MIN_LENGTH, longest / 2);
+}

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

@@ -9,7 +9,8 @@
 // or from its release on. Fields: schema/fields.js OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS. See validate.js.
 import { isVec3, fmt, didYouMean, GRASPS } from "./vocab.js";
 import { objectOk } from "./validate-common.js";
-import { OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS } from "../schema/fields.js";
+import { OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS, SPRING_FIELDS } from "../schema/fields.js";
+import { SPRING } from "./spring.js";
 import { isSwitch, isFollow, movesRecord } from "../carried.js";
 import { isFree } from "../free-motion.js";
 import { checkRef } from "../refs.js";
@@ -99,6 +100,18 @@ function validateFalls(err, unknown, at, o, { frames, scene, carry }) {
 	});
 }
 
+/** objects.<id>.spring: { length?, stiffness?, damping? }, each a number in its SPRING range (a larger stiffness would blow the fixed-step solver up). */
+function validateSpring(err, unknown, at, o) {
+	const sp = o.spring, SPR = "{ length?, stiffness?, damping? }";
+	if (!sp || typeof sp !== "object" || Array.isArray(sp)) return err(`${at}.spring must be ${SPR}, got ${fmt(sp)}`);
+	for (const k of Object.keys(sp)) if (!SPRING_FIELDS.includes(k)) unknown(`${at}.spring has unknown field "${k}"${didYouMean(k, SPRING_FIELDS)}; a spring is ${SPR}`);
+	const what = { length: "string or rod length, m", stiffness: "how fast it swings back, 1/s^2", damping: "how soon it settles, 1 = no overshoot" };
+	for (const k of SPRING_FIELDS) {
+		const v = sp[k], { min, max } = SPRING[k];
+		if (v !== undefined && !(Number.isFinite(v) && v >= min && v <= max)) err(`${at}.spring.${k} must be ${min}..${max} (${what[k]}), got ${fmt(v)}`);
+	}
+}
+
 /** A grasp that starts like the given one (4+ letters: "sphere" -> spherical), else the nearest by edit distance. */
 const prefixLen = (a, b) => { let i = 0; while (i < a.length && a[i] === b[i]) i += 1; return i; };
 function graspHint(given) {
@@ -122,7 +135,8 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 		const at = `objects.${id}`, kind = o?.prop !== undefined ? "carry" : isFollow(o) ? "follow" : isFree(o) ? "free" : isSwitch(o) ? "switch" : "hinge", fields = OBJECT_FIELDS[kind];
 		// a switch and a follow take any record (a light, an effect); the others a body or a group
 		if ((kind !== "switch" && kind !== "follow") || !scene?.others?.[id]) objectOk(err, scene, at, id, { groups: true });
-		for (const f of Object.keys(o ?? {})) if (!fields.includes(f) && !(kind === "hinge" && (f === "keys" || f === "fall"))) unknown(`${at} (${kind}) has unknown field "${f}"${didYouMean(f, fields)}; fields: ${fields.join(", ")}`);
+		if (kind === "hinge" && o?.spring !== undefined) err(`${at}.spring: spring is not for hinged objects; a hinge turns only by its channel (give spring to a carry or a free entry)`);
+		for (const f of Object.keys(o ?? {})) if (!fields.includes(f) && !(kind === "hinge" && (f === "keys" || f === "fall" || f === "spring"))) unknown(`${at} (${kind}) has unknown field "${f}"${didYouMean(f, fields)}; fields: ${fields.join(", ")}`);
 		massOk(err, at, o);
 		if (kind === "follow") {
 			validateFollow(spec, err, { sk, scene }, at, o);
@@ -137,6 +151,7 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 		if (kind === "free") {
 			if (o.keys !== undefined) validateKeys(err, unknown, at, o, frames, true);
 			if (o.fall !== undefined) validateFalls(err, unknown, at, o, { frames, scene, carry: false });
+			if (o.spring !== undefined) validateSpring(err, unknown, at, o);
 			channelsOk(err, at, o);
 			continue;
 		}
@@ -149,6 +164,7 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 				&& o.grab !== undefined && o.release !== undefined && !(o.grab < o.release)) err(`${at}: grab (${o.grab}) must come before release (${o.release})`);
 			if (o.keys !== undefined) validateKeys(err, unknown, at, o, frames);
 			if (o.fall !== undefined) validateFalls(err, unknown, at, o, { frames, scene, carry: true });
+			if (o.spring !== undefined) validateSpring(err, unknown, at, o);
 			continue;
 		}
 		if (o?.keys !== undefined || o?.fall !== undefined) err(`${at}: a hinge turns by its channel "${o.channel}", keyed in spec.keys; keys and fall move an object with no pivot, axis or channel (C17), or a carried one (prop)`);

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

@@ -114,6 +114,7 @@ function validateChecks(spec, err, { sk, scene, frames, unknown = err, past = ""
 	if (fix !== undefined && fix !== false && (typeof fix !== "object" || fix === null)) err(`spec.fix must be false or { ${FIX_KEYS.join(", ")} }`);
 	else for (const k of Object.keys(fix || {})) if (!FIX_KEYS.includes(k)) unknown(`spec.fix.${k} is not a fix${didYouMean(k, FIX_KEYS)} (fixes: ${FIX_KEYS.join(", ")})`);
 	if (fix && fix.grasp !== undefined && typeof fix.grasp !== "boolean") err(`spec.fix.grasp must be true (fingers close on what a hand holds, the default) or false (the preset grip, the object at its grab-frame offset), got ${fmt(fix.grasp)}`);
+	if (fix && fix.person !== undefined && typeof fix.person !== "boolean") err(`spec.fix.person must be true (arms kept out of the other characters, the default) or false, got ${fmt(fix.person)}`);
 }
 
 /** opts = { sk, scene, frames, lenient, unknown: err for an unknown field (a no-op when lenient), past: the

package/src/motion3/compiler/vocab.js

@@ -27,7 +27,7 @@ const RANGES = [
 	[/^wflex_[lr]$/, -70, 70, "flex about the knuckle line, deg"],
 	[/^fpitch_[lr]$/, -60, 90, "toe-down pitch, deg: + lifts the heel (toes flat), - lifts the toes"],
 	// the whole-body pitch and roll have none: they turn in full (flips, cartwheels; pose.js tiltFrame)
-	[/^(spine_pitch|head_pitch)$/, -120, 120, "degrees, + bends forward"],
+	[/^(spine_pitch|head_pitch)$/, -120, 120, "deg, + bends forward"],
 	[/^(spine_roll|head_roll)$/, -90, 90, "degrees"],
 ];
 export const rangeOf = ch => RANGES.find(([re]) => re.test(ch)) ?? null;

package/src/motion3/fix/index.js

@@ -2,7 +2,7 @@
 // the baked channels or the per-frame IK offsets and re-solves only the frames it touched, so QA
 // still measures the final frames; every fix reports what it changed (counts, worst amount).
 //
-// spec.fix = { reach: true, slide: true, penetration: 0.02, self: true, retime: false } (false = all off)
+// spec.fix = { reach: true, slide: true, penetration: 0.02, self: true, retime: false, person: true } (false = all off)
 //   reach        wrist targets past the arm's reach go onto it through a soft knee (no snap);
 //                ankle targets past the leg's reach lower the hips just enough, eased in and out; a hand
 //                on a pinned target (a world or a scene object's anchor) that the straight arm misses brings
@@ -18,6 +18,8 @@
 //   retime       speed spikes get more frames, borrowed from the neighbouring keys
 //   stance       a standIdle stance whose legs, feet or hips are in a scene body slides out of it, the least
 //                distance (skills/stance.js; applied when the skills expand, reported in observations.placed)
+//   person       arms out of the other characters (scene.people, their installed takes; QA PERSON): the wrist
+//                target moves out by the depth, back the side the hand came from, eased in and out (person.js)
 //   grasp        a holding hand's fingers close on what it holds and the object rests in the hand (#816);
 //                false keeps the preset grip and the grab-frame offset
 import { lowerHips, armReach } from "./reach.js";
@@ -28,15 +30,16 @@ import { liftSoles } from "./ground.js";
 import { pushOut } from "./push.js";
 import { retime } from "./retime.js";
 import { selfClear } from "./self.js";
+import { personOut } from "./person.js";
 
-const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance", "grasp"];
+const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance", "grasp", "person"];
 export { FIX_KEYS };
 
 export function fixOptions(fix) {
-	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false, grasp: false };
+	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false, grasp: false, person: false };
 	const f = fix ?? {};
 	const pen = f.penetration === true ? 0.02 : Math.min(0.05, Math.max(0, Number(f.penetration) || 0));
-	return { reach: f.reach !== false, slide: f.slide !== false, penetration: pen, self: f.self !== false, retime: f.retime === true, stance: f.stance !== false, grasp: f.grasp !== false };
+	return { reach: f.reach !== false, slide: f.slide !== false, penetration: pen, self: f.self !== false, retime: f.retime === true, stance: f.stance !== false, grasp: f.grasp !== false, person: f.person !== false };
 }
 
 /** The slide report with the flat feet whose turn waited (turn.js): turns { frames, max deg }. */
@@ -55,6 +58,7 @@ export function applyFixes(out, fix, engine, { whole = true } = {}) {
 	if (fix.reach && fixed.slide?.pivots) put("reachLegs", mergeReach(fixed.reachLegs, lowerHips(out, engine)));
 	if (fix.penetration > 0) put("penetration", pushOut(out, engine, fix.penetration));
 	if (fix.self) put("self", selfClear(out, engine));
+	if (fix.person) put("person", personOut(out, engine));
 	if (fix.reach) put("reachArms", armReach(out));
 	return fixed;
 }

package/src/motion3/fix/person.js

@@ -0,0 +1,110 @@
+// Person push-out (spec.fix.person, on by default): an arm capsule (upper arm, forearm, hand) inside another character
+// (scene.people, their installed take; qa/people-checks.js PERSON) moves its wrist IK target out by the depth plus a margin,
+// eased over neighbouring frames, the same way push.js takes a hand out of a box. No depth limit: a hand keyed deep into
+// someone comes out too. The escape keeps the side the hand came from: a normal that points the opposite way from the
+// previous frame's (the first frame of a pass: from their hips to mine, level), or away from my side of them (that level
+// line), is replaced by the previous one, so a hand past their axis is pulled back the way it came instead of out through
+// their back (the previous frame alone lets the normal turn a little each frame until it points through them). Fixed passes and fixed order (people by id, their
+// capsules in CAPSULES order), no time or random cut-off: the same spec gives the same take. Frames where that arm is FK
+// (armw 0) cannot be pushed and are counted as skipped. An intended touch (checks.allow { part, object: "person:<id>",
+// depth }) may go that deep.
+import { add, sub, scale, dot, len, clamp } from "../compiler/math.js";
+import { QA_LIMITS, allowance } from "../qa/checks.js";
+import { CAPSULES, segPoints } from "../qa/geometry.js";
+import { personCapsules } from "../qa/people-checks.js";
+import { round4 } from "./ease.js";
+
+const EASE = 4, MARGIN = 0.004, PASSES = 6, APART = 2.2;
+const ARM_PARTS = { l: CAPSULES.filter(c => /^(uarm|farm|hand)_l$/.test(c[0])), r: CAPSULES.filter(c => /^(uarm|farm|hand)_r$/.test(c[0])) };
+
+/** The closest points of segment PQ (sampled as qa/geometry.js segDist does, so the depth is QA's) and segment CD. */
+function closest(P, Q, C, D) {
+	const d2 = sub(D, C), dd = dot(d2, d2);
+	let best = null;
+	for (const a of segPoints(P, Q)) {
+		const u = dd < 1e-12 ? 0 : clamp(dot(sub(a, C), d2) / dd, 0, 1), b = add(C, scale(d2, u)), d = len(sub(a, b));
+		if (!best || d < best.d) best = { a, b, d };
+	}
+	return best;
+}
+
+/** Level unit vector from a to b (their hips to mine), or null when they are on top of each other. */
+function level(a, b) {
+	const v = [b[0] - a[0], 0, b[2] - a[2]], l = len(v);
+	return l > 1e-6 ? scale(v, 1 / l) : null;
+}
+
+/** The bodies to keep out of: [id, person] sorted by id, only those whose take has every capsule joint. */
+function bodies(out) {
+	return Object.entries(out.ctx?.scene?.people ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+		.filter(([, p]) => CAPSULES.every(([, a, b]) => p.names.includes(a) && p.names.includes(b)));
+}
+
+/** Per-frame push vectors for side k: the escape (side-kept normal * (depth past what is allowed + margin)) summed over people. */
+function needs(out, k, people, lim, allow, stats) {
+	const { sk } = out.ctx, I = sk.index, n = out.frames.length, f0 = out.f0 ?? 0, v = Array.from({ length: n }, () => null);
+	const prev = new Map();
+	for (let i = 0; i < n; i++) {
+		const { s, c } = out.frames[i];
+		let sum = null;
+		for (const [id, p] of people) {
+			const theirs = personCapsules(p, i + f0), hips = theirs.find(t => t[0] === "hips")[1];
+			if (len(sub(s.P[I.Hips], hips)) > APART) continue;
+			let best = null;
+			for (const [part, a, b, r] of ARM_PARTS[k]) {
+				const meant = allowance(allow, part, `person:${id}`), limit = meant ?? lim, A = s.P[I[a]], B = s.P[I[b]];
+				for (const [, C, D, q] of theirs) {
+					const hit = closest(A, B, C, D), depth = r + q - hit.d;
+					if (depth > limit && (!best || depth - (meant ?? 0) > best.need)) best = { need: depth - (meant ?? 0), hit };
+				}
+			}
+			if (!best) continue;
+			const side = level(hips, s.P[I.Hips]) ?? [0, 0, 0], ref = prev.get(id) ?? side;
+			let nrm = best.hit.d > 1e-6 ? scale(sub(best.hit.a, best.hit.b), 1 / best.hit.d) : ref;
+			if (dot(nrm, ref) < 0 || dot(nrm, side) < 0) nrm = ref;
+			prev.set(id, nrm);
+			sum = add(sum ?? [0, 0, 0], scale(nrm, best.need + MARGIN));
+		}
+		if (!sum) continue;
+		if (!(c[`armw_${k}`] > 1e-4)) { stats.skipped++; continue; }
+		v[i] = sum;
+	}
+	return v;
+}
+
+export function personOut(out, engine) {
+	const people = bodies(out);
+	if (!people.length) return null;
+	const { checks = {} } = out.ctx.spec, lim = { ...QA_LIMITS, ...checks.limits }.allow, n = out.frames.length, stats = { skipped: 0 };
+	const hit = new Set();
+	let max = 0, passes = 0;
+	for (let pass = 0; pass < PASSES; pass++) {
+		stats.skipped = 0;
+		const touched = new Set();
+		for (const k of ["l", "r"]) {
+			const v = needs(out, k, people, lim, checks.allow, stats), push = out.ctx.push[k];
+			// eased dilation of the vectors: neighbours get the strongest nearby push, scaled down (push.js)
+			const eased = Array.from({ length: n }, () => null);
+			for (let i = 0; i < n; i++) {
+				if (!v[i]) continue;
+				hit.add(`${k}${i}`);
+				for (let j = Math.max(0, i - EASE - 1); j <= Math.min(n - 1, i + EASE + 1); j++) {
+					const t = 1 - Math.abs(i - j) / (EASE + 1), w = scale(v[i], t * t * (3 - 2 * t));
+					if (!eased[j] || len(w) > len(eased[j])) eased[j] = w;
+				}
+			}
+			for (let i = 0; i < n; i++) {
+				if (!eased[i]) continue;
+				const f = out.f0 + i, next = add(push.get(f) ?? [0, 0, 0], eased[i]);
+				push.set(f, next);
+				max = Math.max(max, len(next));
+				touched.add(f);
+			}
+		}
+		if (!touched.size) break;
+		passes++;
+		engine.solve([...touched]);
+	}
+	if (!hit.size && !stats.skipped) return null;
+	return { frames: hit.size, max: round4(max), passes, skipped: stats.skipped, how: "hand pushed out of the other person, back the way it came" };
+}

package/src/motion3/free-motion.js

@@ -25,6 +25,7 @@ import { curveOf, keyedPose } from "./object-keys.js";
 import { add, apply, sub, T, quatFromMat, I3 } from "./compiler/math.js";
 import { shapeOf, airPath, settlePath, settledAt, spinOf, spinEnergy, TIP } from "./settle.js";
 import { fallVelocity, moves, flightTime, drift, landingWith } from "./flight.js";
+import { springRest, springStep, swingOf, swungPose, springLength, springOpts } from "./compiler/spring.js";
 
 /** Gravity, m/s^2. */
 export const G = 9.8;
@@ -138,24 +139,28 @@ function eventsOf(o, map, from = -Infinity, to = Infinity) {
 	return events;
 }
 
-/** The pose events give at mapped frame f, starting from pose `start`; `keep` caches each fall's plan on its event. */
-function walk(events, f, start, plan, keep = true) {
-	let pose = start;
+/**
+ * The pose events give at mapped frame f, starting from pose `start`, and whether f is on or past a fall's landing with no
+ * key lifting it since (landed: it rests and hangs from nothing): { pose, landed }. `keep` caches each fall's plan on its event.
+ */
+function walkLanded(events, f, start, plan, keep = true) {
+	let pose = start, landed = false;
 	for (const e of events) {
 		if (e.run) {
 			const { t } = e.curve;
-			if (f < t[0]) return pose;
-			if (f <= t[t.length - 1]) return keyedPose(e.curve, f);
-			pose = keyedPose(e.curve, t[t.length - 1]);
+			if (f < t[0]) return { pose, landed };
+			if (f <= t[t.length - 1]) return { pose: keyedPose(e.curve, f), landed: false };
+			pose = keyedPose(e.curve, t[t.length - 1]); landed = false;
 		} else {
-			if (f < e.fall.t) return pose;
+			if (f < e.fall.t) return { pose, landed };
 			const p = keep ? (e.plan ??= plan(pose, e.fall)) : plan(pose, e.fall);
-			if (f < p.end) return p.at(f);
-			pose = p.rest;
+			if (f < p.end) return { pose: p.at(f), landed: f >= p.land };
+			pose = p.rest; landed = true;
 		}
 	}
-	return pose;
+	return { pose, landed };
 }
+const walk = (events, f, start, plan, keep = true) => walkLanded(events, f, start, plan, keep).pose;
 
 const timelines = new WeakMap();
 /** The events of entry o under time map `map`, cached per scene, entry and span (key curves built once). */
@@ -182,6 +187,34 @@ export function freePoseAt(ctx, id, f) {
 	return walk(timelineOf(ctx, id, o, ctx.timeMap, "all"), f, { pos: rest.pos, R: rest.R }, planner(ctx, id));
 }
 
+const swings = new WeakMap();
+/**
+ * freePoseAt turned by the entry's spring (spec.objects[id].spring, compiler/spring.js), else freePoseAt: the pendulum
+ * walks frames 0..f of the unswung pose and stops dead on a fall's landing (landedAt), cached per spec, entry and time map. The one swing of a free entry: the take and
+ * refs (object-pose.js rootPoseAt) and the obstacle boxes QA and fixes read (compiler/compile.js objectTracks).
+ */
+export function freeSwungAt(ctx, id, f) {
+	const pose = freePoseAt(ctx, id, f), o = ctx.spec.objects?.[id];
+	if (!pose || !o?.spring) return pose;
+	if (!swings.has(ctx.spec)) swings.set(ctx.spec, new Map());
+	const cache = swings.get(ctx.spec);
+	let c = cache.get(id);
+	if (!c || c.map !== ctx.timeMap || c.o !== o) cache.set(id, c = { map: ctx.timeMap, o, states: [], length: springLength(partsIn(ctx.scene, id).flatMap(p => corners(ctx.scene.objects[p]))) });
+	const opts = springOpts(o.spring, ctx.spec.fps ?? 30, c.length);
+	for (let k = c.states.length; k <= f; k++) {
+		const s = springStep(k ? c.states[k - 1] : springRest(), (k === f ? pose : freePoseAt(ctx, id, k)).pos, opts);
+		// landed, it rests on its face and hangs from nothing: no swing, and none carried on (its corners stay on the surface)
+		c.states[k] = landedAt(ctx, id, k) ? { ...s, th: [0, 0], w: [0, 0] } : s;
+	}
+	return swungPose(pose, swingOf(c.states[f]));
+}
+
+/** True when free entry `id` at absolute f is on or past a fall's landing and no key has lifted it since (walkLanded). */
+function landedAt(ctx, id, f) {
+	const rest = restOf(ctx.scene, id);
+	return walkLanded(timelineOf(ctx, id, ctx.spec.objects[id], ctx.timeMap, "all"), f, { pos: rest.pos, R: rest.R }, planner(ctx, id)).landed;
+}
+
 /** Where carry `id` (entry o) is before its grab at absolute f: its scene pose, or where a fall before grab left it. */
 export function beforeGrab(ctx, id, o, f, grab) {
 	const rest = restOf(ctx.scene, id);
@@ -194,10 +227,15 @@ export function beforeGrab(ctx, id, o, f, grab) {
  * `beforePose` (a frame before the release) gives the spin it is let go with to a fall that starts right at the release.
  */
 export function afterRelease(ctx, id, o, f, release, releasePose, beforePose = null) {
+	return releaseFall(ctx, id, o, f, release, releasePose, beforePose)?.pose ?? null;
+}
+
+/** afterRelease and whether f is on or past a landing of those falls (walkLanded): { pose, landed }, or null as afterRelease. */
+export function releaseFall(ctx, id, o, f, release, releasePose, beforePose = null) {
 	const events = fallsOf(o).length ? timelineOf({ ...ctx, release }, id, o, ctx.timeMap, "after") : [];
 	// the release pose comes from the solved body, which a rebake changes: plan these falls afresh
 	const plan = (start, fall) => fallPlan(ctx.spec, ctx.scene, id, start, fall.t, fall, ctx.spec.fps ?? 30, fall.t <= release + 1 ? beforePose : null);
-	return events.length ? walk(events, f, releasePose, plan, false) : null;
+	return events.length ? walkLanded(events, f, releasePose, plan, false) : null;
 }
 
 /** True when carry entry o falls at or after its release (absolute frame; afterRelease then moves it). */

package/src/motion3/object-pose.js

@@ -32,8 +32,9 @@ import { groupsOf } from "./scene.js";
 import { solveFrame } from "./compiler/compile.js";
 import { channelsAt } from "./compiler/channels.js";
 import { resolveBone } from "./bones.js";
-import { isFree, freePoseAt, beforeGrab, afterRelease, fallsAfter, corners, topOf, under, TOUCH } from "./free-motion.js";
+import { isFree, freePoseAt, freeSwungAt, beforeGrab, afterRelease, releaseFall, fallsAfter, corners, topOf, under, TOUCH } from "./free-motion.js";
 import { add } from "./compiler/math.js";
+import { springRest, springStep, swingOf, swungPose, springLength, springOpts } from "./compiler/spring.js";
 
 /**
  * Body ids that make up `id` in a motionScene: [id] for a body (plus any bodies parented under
@@ -161,12 +162,53 @@ function carriedAt(out, id, o, f) {
  * solved frame, so the carrying hand must already be solved (compiler/anchors.js).
  */
 export function rootPoseAt(out, id, f, now = null) {
+	const o = out.ctx.spec.objects?.[id];
+	if (o?.spring && isFree(o)) return freeSwungAt(freeCtx(out), id, f);
+	const pose = basePoseAt(out, id, f, now);
+	return o?.spring && pose && isCarried(o) ? swungPose(pose, springAt(out, id, o, f, now ? pose : null)) : pose;
+}
+
+const springs = new WeakMap();
+
+/**
+ * The swing [tx, tz] of spring carry `id` at absolute f (compiler/spring.js): the solver walks frames 0..f of the
+ * record's unswung pose (its anchor). Each frame's state is cached with the solved frame it was read on, and reused
+ * while frames 0..k are still those frames (a fix that re-solves a frame starts the walk again there). `nowPose`: the
+ * unswung pose of frame f while it is being solved (not cached).
+ */
+function springAt(out, id, o, f, nowPose) {
+	if (!springs.has(out)) springs.set(out, new Map());
+	const cache = springs.get(out), f0 = out.f0 ?? 0, fps = out.fps ?? out.ctx.spec.fps ?? 30, { scene } = out.ctx;
+	if (!cache.has(id)) cache.set(id, { states: [], keys: [], length: springLength(partsOf(scene, id).flatMap(p => corners(scene.objects[p]))) });
+	const c = cache.get(id), opts = springOpts(o.spring, fps, c.length), release = spanOf(out, o)[1];
+	const end = nowPose ? f - 1 : f;
+	let k = 0;
+	while (k <= end && k < c.states.length && c.keys[k] === (out.frames[k - f0] ?? null)) k += 1;
+	c.states.length = k; c.keys.length = k;
+	// let go and fallen (free-motion.js releaseFall): from its landing it rests and hangs from nothing, no swing carried on
+	const step = (prev, j, pose) => {
+		const fell = j > release ? releaseFall(...releaseArgs(out, id, o, j, release)) : null, s = springStep(prev, (pose ?? fell?.pose ?? basePoseAt(out, id, j)).pos, opts);
+		return fell?.landed ? { ...s, th: [0, 0], w: [0, 0] } : s;
+	};
+	for (; k <= end; k++) {
+		c.states[k] = step(k ? c.states[k - 1] : springRest(), k, null);
+		c.keys[k] = out.frames[k - f0] ?? null;
+	}
+	const last = end >= 0 ? c.states[end] : springRest();
+	return swingOf(nowPose ? step(last, f, nowPose) : last);
+}
+
+/** The arguments of free-motion.js afterRelease / releaseFall for carry `id` (entry o) at f past its release frame. */
+const releaseArgs = (out, id, o, f, release) => [freeCtx(out), id, o, f, release, carriedAt(out, id, o, release), release > 0 ? carriedAt(out, id, o, release - 1) : null];
+
+/** rootPoseAt before a spring swings it: where the keys and the hand put it (qa/key-checks.js measures the keys on it). */
+export function basePoseAt(out, id, f, now = null) {
 	const { spec, scene } = out.ctx, o = movesRecord(spec.objects?.[id]) ? spec.objects[id] : undefined, rest = restPose(scene, id);
 	if (isFollow(o)) return followPose(now ? { ...out, f0: f, frames: [now] } : out, o, f);
 	if (isCarried(o) && (rest || !keepsOffset(scene, id, o))) {
 		const [grab, release] = spanOf(out, o), g = Math.max(grab, Math.min(f, release));
 		if (f < grab && rest) return restingAt(out, id, f);
-		const after = f > release ? afterRelease(freeCtx(out), id, o, f, release, carriedAt(out, id, o, release), release > 0 ? carriedAt(out, id, o, release - 1) : null) : null;
+		const after = f > release ? afterRelease(...releaseArgs(out, id, o, f, release)) : null;
 		if (after) return after;
 		const by = f > release ? riderOf(out, id) : null;
 		if (by) { const at = carriedAt(out, id, o, release); return compose(rootPoseAt(out, by, f), relative(rootPoseAt(out, by, release), at)); }

package/src/motion3/people.js

@@ -8,6 +8,8 @@ import { skeletonFor } from "./rigs/index.js";
 import { fk } from "./compiler/skeleton.js";
 import { add, apply, ry } from "./compiler/math.js";
 import { resolveBone } from "./bones.js";
+import { CAPSULES } from "./qa/geometry.js";
+import { APART } from "./qa/people-checks.js";
 
 const sampled = new WeakMap();
 // joints are kept to 1e-5 m: what a saved take keeps of them (keptPeople) is then exactly what its compile read
@@ -61,8 +63,10 @@ export const peopleList = scene => Object.entries(scene?.people ?? {}).map(([id,
  * What a take keeps of the people so that its saved source compiles the same again without the others' takes
  * (take-source.js): only the joints its person anchors and refs name (anywhere in the spec: anchors, a skill's
  * define, goals, probes; a bare person:<id> in a skill's from is that person's Hips), as plain arrays (a saved project is JSON), or null.
+ * When fix.person moved an arm (out.fixed.person.frames), every capsule joint (qa/geometry.js CAPSULES) of each person whose
+ * hips came within APART of mine is kept too, so the saved source pushes the same arm out again (fix/person.js).
  */
-export function keptPeople(scene, spec) {
+export function keptPeople(scene, spec, out) {
 	const want = new Map(), keep = (id, b) => {
 		const p = scene?.people?.[id], bone = p && resolveBone(skeletonFor(p.rig), b).bone;
 		if (bone) want.set(id, new Set([...(want.get(id) ?? []), bone]));
@@ -73,6 +77,17 @@ export function keptPeople(scene, spec) {
 		else if (v && typeof v === "object") { if (v.kind === "person") keep(v.person, v.bone); for (const [k, x] of Object.entries(v)) walk(x, k); }
 	};
 	walk(spec);
+	if (out?.fixed?.person?.frames > 0) {
+		const H = out.ctx.sk.index.Hips, f0 = out.f0 ?? 0, joints = CAPSULES.flatMap(([, a, b]) => [a, b]);
+		for (const [id, p] of Object.entries(scene?.people ?? {})) {
+			const j = p.names.indexOf(CAPSULES.find(c => c[0] === "hips")[1]), J = p.names.length;
+			const near = j >= 0 && out.frames.some(({ s }, i) => {
+				const at = (Math.max(0, Math.min(p.frames - 1, i + f0)) * J + j) * 3, h = s.P[H];
+				return Math.hypot(h[0] - p.P[at], h[1] - p.P[at + 1], h[2] - p.P[at + 2]) <= APART;
+			});
+			if (near) for (const b of joints) if (p.names.includes(b)) keep(id, b);
+		}
+	}
 	if (!want.size) return null;
 	return Object.fromEntries([...want].map(([id, bones]) => {
 		const p = scene.people[id], names = [...bones], J = p.names.length, P = [];

package/src/motion3/physics-frames.js

@@ -0,0 +1,72 @@
+// The frames QA measured, rebuilt from an installed take v3 (take.js bakeTake), for the physics overlay
+// (physics-view.js). A take keeps local bone turns and the hips in the character's placement frame, plus world
+// tracks of the objects it moves; QA read the compiler's `out`: world joint positions per frame, the skeleton and
+// the obstacle boxes per frame. takeOut gives that shape back, so the overlay calls QA's own functions (qa/com.js,
+// qa/ground.js, qa/style.js) on the pose the viewport plays, and its verdicts are QA's.
+//   frames[f].s   { P, R }: fk of the take's frame f, turned by the placement yaw and moved to its position
+//   objectsAt(f)  the authored records as motion boxes (scene.js), the way compile.js objectTracks lays them out:
+//                 a record a carry or a follow moves is not an obstacle; one a free or hinge entry moves stands
+//                 where the take's track puts its mover
+// Pure: the take and the records in, numbers out; cached per take and records.
+import { skeletonFor } from "./rigs/index.js";
+import { fk } from "./compiler/skeleton.js";
+import { add, apply, mul, ry, matFromQuat } from "./compiler/math.js";
+import { motionScene, groupsOf } from "./scene.js";
+import { isCarried, isFollow, movesRecord, compose, relative } from "./carried.js";
+import { expandUse } from "./skills/index.js";
+
+const cache = new WeakMap();
+
+/** The take's spec with its skills expanded (the checks and objects QA read), or the spec as stored when it cannot expand. */
+function expandedSpec(take, sk, scene) {
+	try { return expandUse(take.spec ?? {}, { sk, scene, lenient: true }).spec; } catch { return take.spec ?? {}; }
+}
+
+/** World pose { pos, R } of track `track` at frame f, or null when it has none there. */
+export function trackPose(track, f) {
+	if (!track?.pos || !track.quat || f < 0 || (f + 1) * 3 > track.pos.length) return null;
+	const p = track.pos, q = track.quat;
+	return { pos: [p[f * 3], p[f * 3 + 1], p[f * 3 + 2]], R: matFromQuat([q[f * 4], q[f * 4 + 1], q[f * 4 + 2], q[f * 4 + 3]]) };
+}
+
+/** The obstacle boxes of frame f (compile.js objectTracks obstacles, the movers read from the take's tracks). */
+function obstaclesAt(take, spec, scene, f) {
+	const out = {}, groups = groupsOf(scene);
+	for (const [id, o] of Object.entries(scene.objects)) {
+		const mover = [id, ...(o.ancestors ?? [])].find(k => movesRecord(spec.objects?.[k])), entry = spec.objects?.[mover];
+		if (!entry) { out[id] = o; continue; }
+		if (isCarried(entry) || isFollow(entry)) continue;
+		const pose = trackPose(take.objects?.[mover], f), rest = scene.objects[mover] ?? groups[mover];
+		out[id] = pose && rest ? { ...o, ...compose(pose, relative(rest, o)) } : o;
+	}
+	return out;
+}
+
+/**
+ * takeOut(take, objects) -> { frames, ctx: { sk, spec, scene }, objectsAt, fps, f0, frameCount } | null: the `out`
+ * QA reads, from take v3 `take` over the authored records `objects`. null for another take or a body motion3 cannot
+ * drive. spec is the take's spec with its skills expanded.
+ */
+export function takeOut(take, objects = []) {
+	if (take?.schema !== "cozyclay.take.v3" || !(take.frameCount > 0)) return null;
+	const kept = cache.get(take);
+	if (kept && kept.objects === objects) return kept.out;
+	const sk = skeletonFor(take.rig);
+	if (!sk) return null;
+	const B = take.bones.length, slot = take.bones.map(name => sk.index[name]), yaw = ry(take.placement?.yaw ?? 0), at = take.placement?.position ?? [0, 0, 0];
+	const frames = [];
+	for (let f = 0; f < take.frameCount; f++) {
+		const quats = sk.names.map(() => [0, 0, 0, 1]);
+		for (let b = 0; b < B; b++) if (slot[b] !== undefined) quats[slot[b]] = Array.from(take.rot.subarray((f * B + b) * 4, (f * B + b) * 4 + 4));
+		const local = fk(sk, quats, Array.from(take.hips.subarray(f * 3, f * 3 + 3)));
+		frames.push({ s: { P: local.P.map(p => p && add(at, apply(yaw, p))), R: local.R.map(R => R && mul(yaw, R)) } });
+	}
+	const scene = motionScene(objects), spec = expandedSpec(take, sk, scene), boxes = new Map();
+	const objectsAt = f => {
+		if (!boxes.has(f)) boxes.set(f, obstaclesAt(take, spec, scene, Math.max(0, Math.min(take.frameCount - 1, f))));
+		return boxes.get(f);
+	};
+	const out = { frames, ctx: { sk, spec, scene }, objectsAt, fps: take.fps ?? 24, f0: 0, frameCount: take.frameCount };
+	cache.set(take, { objects, out });
+	return out;
+}