cozyclay 2.1.1 → 3.0.1

package/src/motion3/fix/self.js

@@ -0,0 +1,211 @@
+// Self-collision auto-fix (spec.fix.self, on unless false): the arms keep out of the rest of the body,
+// on the fitted skin the BODY check measures (body.js, qa/body-checks.js). Wrist targets inside the
+// body already went out onto the skin when they were solved (compile.js keepOut); what is left here:
+//  - elbow: an upper arm or forearm inside the body turns the elbow about the shoulder-wrist line
+//    (ctx.swivel; the hand keeps its place and turn). The turn is planned over the whole take at once,
+//    absolute: each frame scores every turn in TURNS by the depth left, the size of the turn and how
+//    far the elbow rises past LOW under the shoulder (no chicken wing), plus the change from the frame before, and the cheapest
+//    path wins (Viterbi), so the elbow eases in and out instead of snapping;
+//  - hand: a hand or forearm still a little inside moves its wrist IK target out along the skin's
+//    normal (ctx.skinPush), at most STEP a pass and REACH in all, eased over neighbouring frames. Deeper hits, and the
+//    head and neck (a hand at the mouth is on purpose), stay for QA.
+// Frames whose arm is FK (armw 0) only get the elbow turn. The report says what moved.
+import { bodyFor, bodyNormal, limbDepth, segmentDepth } from "../body.js";
+import { add, sub, scale, len, apply, axisRot } from "../compiler/math.js";
+import { CAPSULES, segPoints, sdBox } from "../qa/geometry.js";
+import { round4 } from "./ease.js";
+import { turnWeight } from "../compiler/pose.js";
+import { allowance } from "../qa/checks.js";
+import { regionOf } from "../qa/body-checks.js";
+
+const TURNS = Array.from({ length: 19 }, (_, i) => -90 + i * 10);
+const PASSES = 3, EASE = 5, MARGIN = 0.003, ALLOW = 0.003, STEP = 0.03, REACH = 0.08;
+/** The most of a declared allowance the push leaves alone (m): a touch (a hand in a pocket), not a skill's leeway for a sweep it cannot avoid. */
+const TOUCH = 0.03;
+/** Plan weights: per cm^2 of depth, per (10 deg)^2 of turn, per cm^2 of elbow over the shoulder, per (10 deg)^2 of change a frame. */
+const DEEP = 40, TURN = 0.05, RISE = 4, CHANGE = 2;
+/** How far (m) under the shoulder the elbow may come before RISE counts. Where the spec declares a chicken-wing check
+ * on this elbow (checks.below, joint <Side>ForeArm under <Side>Arm: the smoke skill's), rising past its min costs
+ * WING_PRICE: a smoking elbow the turn raised past it broke that check once the wrist stopped at its limit (wrist-clamp.js). */
+const LOW = 0.09, WING_PRICE = 400;
+
+/** The spec's chicken-wing min (m) for the elbow of `side` on frame i (a below check on it at least half on), else null. */
+function wingMin(out, i, side) {
+	let min = null;
+	for (const b of out.ctx.spec.checks?.below ?? []) {
+		const joint = String(b.joint).replace(/^joint:/, ""), ref = String(b.ref).replace(/^joint:/, ""), f = out.f0 + i;
+		const on = Array.isArray(b.when) ? f >= b.when[0] && f <= b.when[1] : b.when ? (out.frames[i].c[b.when] ?? 0) > 0.5 : true;
+		if (on && joint === `${side}ForeArm` && ref === `${side}Arm` && Number.isFinite(b.min)) min = Math.max(min ?? 0, b.min);
+	}
+	return min;
+}
+/** The most the turn changes in one frame (deg): a fast arm turned faster than this pops. */
+const STEP_TURN = 10;
+const SIDES = { l: "Left", r: "Right" };
+
+/** How much hand k is on a measured target at channels c: a fit of its own (the mouth), or a fit of the
+ * other hand anchored to a prop k holds (the flame under k's cigarette). Such a hand is not moved. */
+export function fitWeight(spec, c, k) {
+	let w = 0;
+	for (const fit of spec.fits ?? []) {
+		const a = spec.anchors?.[fit.anchor], on = c[`w_${fit.anchor}_${fit.side}`] ?? 0;
+		if (fit.side === k || (a?.kind === "prop" && spec.props?.[a.prop]?.hand === k)) w = Math.max(w, on);
+	}
+	return Math.min(1, w);
+}
+
+const CAP = Object.fromEntries(CAPSULES.map(c => [c[0], c[3]]));
+/** How deep (m) segment A-B of radius r goes into the scene's boxes (QA's COLLIDE on the same capsules). */
+function sceneDepth(boxes, A, B, r) {
+	let worst = 0;
+	for (const box of boxes) worst = Math.max(worst, r - Math.min(...segPoints(A, B, 5).map(p => sdBox(p, box))));
+	return worst;
+}
+
+/** Deepest skin depth (m) of the upper arm and forearm with the elbow turned `deg` more about the shoulder-wrist line,
+ * and how deep they go into the scene's boxes (an elbow turned out of the body must not turn into a steering wheel). */
+function elbowDepth(body, sk, s, side, deg, boxes = []) {
+	const I = sk.index, a = I[`${side}Arm`], fa = I[`${side}ForeArm`], S = s.P[a], W = s.P[I[`${side}Hand`]];
+	const E = deg ? add(S, apply(axisRot(sub(W, S), deg), sub(s.P[fa], S))) : s.P[fa];
+	const worst = Math.max(segmentDepth(body, sk, s, a, S, E), segmentDepth(body, sk, s, fa, E, W));
+	const k = side === "Left" ? "l" : "r", scene = boxes.length ? Math.max(sceneDepth(boxes, S, E, CAP[`uarm_${k}`]), sceneDepth(boxes, E, W, CAP[`farm_${k}`])) : 0;
+	return { depth: worst, scene, rise: Math.max(0, E[1] - (S[1] - LOW)), under: S[1] - E[1] };
+}
+
+/** Shoulder to wrist at full stretch (m), at bind. */
+const armLength = (sk, side) => { const I = sk.index, P = sk.restWorldPos; return len(sub(P[I[`${side}ForeArm`]], P[I[`${side}Arm`]])) + len(sub(P[I[`${side}Hand`]], P[I[`${side}ForeArm`]])); };
+
+/** Absolute elbow turns (deg) for side k over the take, or null when no frame needs or has one. */
+function planTurns(out, body, k) {
+	const { sk } = out.ctx, side = SIDES[k], n = out.frames.length, now = out.ctx.swivel[k];
+	const cost = out.frames.map(({ s, c }, i) => {
+		const tw = turnWeight(c[`armw_${k}`] ?? 0), cur = (now.get(out.f0 + i) ?? 0) * tw;
+		if (!cur && elbowDepth(body, sk, s, side, 0).depth <= ALLOW) return null;
+		// only the boxes the arm can reach this frame (their bounding sphere within the arm's length of the shoulder)
+		const S = s.P[sk.index[`${side}Arm`]], reach = armLength(sk, side) + 0.15;
+		const boxes = Object.values(out.objectsAt(i)).filter(box => box.half && !box.ignore && len(sub(add(box.pos, apply(box.R, [0, box.half[1], 0])), S)) - len(box.half) < reach);
+		const base = elbowDepth(body, sk, s, side, -cur, boxes).scene, wmin = wingMin(out, i, side);
+		return TURNS.map(deg => {
+			const { depth, scene, rise, under } = elbowDepth(body, sk, s, side, deg * tw - cur, boxes), cm = Math.max(0, depth - ALLOW) * 100;
+			const wing = wmin === null ? 0 : Math.max(0, wmin - under);
+			// a box the arm was already in at no turn is QA's COLLIDE to report, not this plan's to avoid
+			const hit = Math.max(0, scene - Math.max(base, ALLOW)) * 100;
+			return DEEP * (cm * cm + hit * hit) + TURN * (deg / 10) ** 2 + RISE * (rise * 100) ** 2 + WING_PRICE * (wing * 100) ** 2;
+		});
+	});
+	if (cost.every(c => !c)) return null;
+	// a frame that needs no turn has none; the take may start already turned
+	const zero = TURNS.indexOf(0), still = TURNS.map((_, j) => (j === zero ? 0 : Infinity));
+	let acc = TURNS.map(() => 0);
+	const back = [];
+	for (let i = 0; i < n; i++) {
+		const here = cost[i] ?? still, prev = acc, from = [];
+		acc = here.map((h, j) => {
+			let best = Infinity, arg = zero;
+			for (let p = 0; p < TURNS.length; p++) {
+				if (Math.abs(TURNS[j] - TURNS[p]) > STEP_TURN) continue;
+				const v = prev[p] + CHANGE * ((TURNS[j] - TURNS[p]) / 10) ** 2;
+				if (v < best) { best = v; arg = p; }
+			}
+			from.push(arg);
+			return best + h;
+		});
+		back.push(from);
+	}
+	const path = new Array(n);
+	let j = acc.indexOf(Math.min(...acc));
+	for (let i = n - 1; i >= 0; i--) { path[i] = TURNS[j]; j = back[i][j]; }
+	// the 10-degree steps, smoothed
+	return path.map((_, i) => (path[Math.max(0, i - 1)] + 2 * path[i] + path[Math.min(n - 1, i + 1)]) / 4);
+}
+
+/** Per-frame wrist pushes for side k: a hand or forearm a little inside the skin (not the head or neck) goes out along its normal. */
+function handPushes(out, body, k, stats) {
+	const { sk } = out.ctx, side = SIDES[k], I = sk.index, n = out.frames.length, v = new Array(n).fill(null);
+	const face = [I.Head, I.Neck, I.HeadTop_End].filter(b => b !== undefined);
+	for (let i = 0; i < n; i++) {
+		const { s, c } = out.frames[i], f = out.f0 + i;
+		// a hand on a measured target (a fit's anchor: the mouth, the flame) stays where its goal needs it; on its way
+		// there the push fades out with the target's weight
+		const free = 1 - fitWeight(out.ctx.spec, c, k);
+		if (free < 0.05) continue;
+		// past what the spec allows (a hand in a pocket touches the hip: checks.allow), as QA's BODY measures it
+		let hit = null;
+		for (const b of [I[`${side}Hand`], I[`${side}ForeArm`]]) {
+			const h = limbDepth(body, sk, s, b);
+			if (h.into < 0 || face.includes(h.into)) continue;
+			const allowed = Math.min(TOUCH, allowance(out.ctx.spec.checks?.allow, regionOf(sk, b), regionOf(sk, h.into)) ?? 0), past = h.depth - Math.max(allowed, ALLOW);
+			if (past > 0 && (!hit || past > hit.past)) hit = { ...h, b, past };
+		}
+		if (!hit) continue;
+		if (!(c[`armw_${k}`] > 1e-4)) { stats.skipped++; continue; }
+		const done = len(out.ctx.skinPush[k].get(f) ?? [0, 0, 0]);
+		if (done >= REACH) { stats.deep++; continue; }
+		const nrm = bodyNormal(body, s, hit.p, new Set([...body.skip.get(hit.b), ...face]));
+		if (nrm) v[i] = scale(nrm, free * Math.min(STEP, REACH - done, hit.past + MARGIN));
+	}
+	// eased dilation: neighbours get the strongest nearby push, scaled down
+	const eased = new Array(n).fill(null);
+	v.forEach((p, i) => {
+		if (!p) return;
+		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(p, t * t * (3 - 2 * t));
+			if (!eased[j] || len(w) > len(eased[j])) eased[j] = w;
+		}
+	});
+	return eased;
+}
+
+export function selfClear(out, engine) {
+	const body = bodyFor(out.ctx.sk);
+	if (!body) return null;
+	const n = out.frames.length, stats = { skipped: 0, deep: 0 }, turned = new Set(), pushed = new Set();
+	let maxTurn = 0, maxPush = 0;
+	for (let pass = 0; pass < PASSES; pass++) {
+		let touched = new Set();
+		for (const k of ["r", "l"]) {
+			const plan = planTurns(out, body, k);
+			if (!plan) continue;
+			plan.forEach((deg, i) => {
+				const f = out.f0 + i, cur = out.ctx.swivel[k].get(f) ?? 0, next = Math.abs(deg) < 0.5 ? 0 : deg;
+				if (Math.abs(next - cur) < 0.5) return;
+				if (next) out.ctx.swivel[k].set(f, next); else out.ctx.swivel[k].delete(f);
+				maxTurn = Math.max(maxTurn, Math.abs(next)); if (next) turned.add(`${k}${i}`); touched.add(f);
+			});
+		}
+		if (touched.size) engine.solve([...touched]);
+		touched = new Set();
+		stats.skipped = 0; stats.deep = 0;
+		for (const k of ["r", "l"]) {
+			handPushes(out, body, k, stats).forEach((p, i) => {
+				if (!p) return;
+				const f = out.f0 + i, next = add(out.ctx.skinPush[k].get(f) ?? [0, 0, 0], p);
+				out.ctx.skinPush[k].set(f, next);
+				maxPush = Math.max(maxPush, len(next)); pushed.add(`${k}${i}`); touched.add(f);
+			});
+		}
+		if (!touched.size) break;
+		engine.solve([...touched]);
+	}
+	// the pushes add up pass by pass from frames that read their normals apart: smoothed over time, so the hand
+	// does not jerk (a 1-4-6-4-1 kernel, twice)
+	if (pushed.size) {
+		const touched = new Set();
+		for (const k of ["r", "l"]) {
+			const at = i => out.ctx.skinPush[k].get(out.f0 + i) ?? [0, 0, 0];
+			for (let pass = 0; pass < 2; pass++) {
+				const was = Array.from({ length: n }, (_, i) => at(i));
+				was.forEach((_, i) => {
+					const sm = [-2, -1, 0, 1, 2].reduce((acc, d, j) => add(acc, scale(was[Math.min(n - 1, Math.max(0, i + d))], [1, 4, 6, 4, 1][j] / 16)), [0, 0, 0]);
+					if (len(sm) < 1e-5 && !out.ctx.skinPush[k].has(out.f0 + i)) return;
+					out.ctx.skinPush[k].set(out.f0 + i, sm); touched.add(out.f0 + i);
+				});
+			}
+		}
+		if (touched.size) engine.solve([...touched]);
+	}
+	if (!turned.size && !pushed.size && !stats.skipped) return null;
+	return { elbowFrames: turned.size, maxTurn: Math.round(maxTurn), handFrames: pushed.size, maxPush: round4(maxPush), skipped: stats.skipped, tooDeep: stats.deep,
+		how: "elbow turned about the shoulder-wrist line; a hand a little inside pushed out along the skin" };
+}
+

package/src/motion3/fix/slide.js

@@ -0,0 +1,70 @@
+// Planted-foot lock: while a heel or ball is planted (QA's own definition, over the ground under
+// it: the floor or an object's top, qa/ground.js) and drifts less than
+// 1 cm, the ankle target is shifted so the planted point stays where it landed. The foot pose
+// depends only on the ankle target, fyaw and fpitch, so the shift moves the sole rigidly.
+// A pivot (the planted point is the only one down: the heel is up over a planted ball, or the
+// ball over a planted heel) is held whatever the drift: fyaw and fpitch then turn the foot about
+// that point, as a batter's back foot turns on its ball, instead of about the ankle. A pivot that
+// held more than 1 cm keeps holding while its point stays under PIVOT_H (a hover, not a step) and
+// lets go no faster than EASE_STEP a frame.
+import { add, sub } from "../compiler/math.js";
+import { QA_LIMITS } from "../qa/checks.js";
+import { groundSole } from "../qa/ground.js";
+import { round4 } from "./ease.js";
+
+const MAX_DRIFT = 0.01, DECAY = 4, PIVOT_H = 0.03, EASE_STEP = 0.02;
+
+export function lockFeet(out, engine) {
+	const n = out.frames.length, H = QA_LIMITS.plantH;
+	let plants = 0, pivots = 0, worst = 0;
+	const touched = new Set();
+	for (const [k, S] of [["l", "Left"], ["r", "Right"]]) {
+		const ch = out.baked[`foot_${k}`];
+		if (!ch) continue;
+		const sole = out.frames.map((_, i) => groundSole(out, i, S));
+		const planted = (i, key) => sole[i][key][1] < H && sole[i - 1][key][1] < H && Math.abs(sole[i][key][1] - sole[i - 1][key][1]) < 0.0005;
+		const delta = Array.from({ length: n }, () => null);
+		for (let i = 1; i < n;) {
+			if (!planted(i, "ball") && !planted(i, "heel")) { i++; continue; }
+			// one contact run: the ball wins over the heel; a switch re-anchors on the new point
+			let key = null, ref = null, j = i, max = 0, last = [0, 0, 0], pivot = false;
+			const run = [];
+			const hold = jj => {
+				const d = sub(ref, sole[jj][key]); d[1] = 0;
+				last = d;
+				run.push([jj, d]);
+				max = Math.max(max, Math.hypot(d[0], d[2]));
+			};
+			for (; j < n && (planted(j, "ball") || planted(j, "heel")); j++) {
+				const kj = planted(j, "ball") ? "ball" : "heel";
+				pivot ||= sole[j][kj === "ball" ? "heel" : "ball"][1] >= H;
+				// on a switch the new point is anchored where the previous frame's shift put it
+				if (kj !== key) { key = kj; ref = add(sole[j - 1][key], last); }
+				hold(j);
+			}
+			if (pivot && max >= MAX_DRIFT) for (; j < n && sole[j][key][1] < PIVOT_H; j++) hold(j);
+			if (max > 2e-4 && (max < MAX_DRIFT || pivot)) {
+				plants++; worst = Math.max(worst, max);
+				if (max >= MAX_DRIFT) pivots++;
+				for (const [jj, d] of run) delta[jj] = d;
+				const decay = Math.max(DECAY, Math.ceil(Math.hypot(last[0], last[2]) / EASE_STEP));
+				for (let m = 1; m <= decay && j - 1 + m < n; m++) {
+					if (delta[j - 1 + m]) break;
+					const t = m / (decay + 1), e = 1 - t * t * (3 - 2 * t);
+					delta[j - 1 + m] = [last[0] * e, 0, last[2] * e];
+				}
+			}
+			i = j;
+		}
+		for (let i = 0; i < n; i++) {
+			if (!delta[i]) continue;
+			const f = out.f0 + i;
+			ch[f] = add(ch[f], delta[i]);
+			touched.add(f);
+		}
+	}
+	if (!plants) return null;
+	engine.solve([...touched]);
+	return { plants, ...(pivots ? { pivots } : {}), frames: touched.size, max: round4(worst),
+		how: pivots ? "planted heel/ball held in place; turning feet pivot on it" : "planted heel/ball held in place" };
+}

package/src/motion3/fix/turn.js

@@ -0,0 +1,51 @@
+// A planted flat foot keeps its heading (lane Q1). While both its heel and its ball are planted
+// (QA's definition: under plantH over the ground, qa/ground.js, and still), the foot cannot turn without one of them sliding: a
+// flat foot under the body's weight grips the floor. A turn the channels ask for then (fyaw_<k>, or
+// the body's yaw when fyaw_<k> is not keyed) waits: the foot keeps the heading it planted with
+// until its heel or its toes come up or it lifts, and then eases onto the keyed heading at about
+// TURN_RATE degrees a frame. With the heel up it turns on its ball (slide.js holds the ball and
+// pivots the foot there), in the air it turns freely. Session 4db5d447: fyaw_r keyed 0 at f0 and
+// 30 at f37 turned the flat back foot 9 deg over the load (f10-19), and its heel slid 2.2 cm.
+// A foot that turns only while a heel or ball is up, and a flat foot that does not turn, are left
+// as they were.
+import { QA_LIMITS } from "../qa/checks.js";
+import { groundSole } from "../qa/ground.js";
+import { round4 } from "./ease.js";
+
+const TURN_RATE = 6, DECAY = 4, TOL = 1;
+const smooth = t => t * t * (3 - 2 * t);
+
+/** Holds the heading of flat planted feet (fyaw_<k>), eases it onto the keys once a heel or ball is up; re-solves those frames. */
+export function holdTurns(out, engine) {
+	const n = out.frames.length, H = QA_LIMITS.plantH, touched = new Set();
+	let worst = 0;
+	for (const [k, S] of [["l", "Left"], ["r", "Right"]]) {
+		const keyed = out.baked[`fyaw_${k}`] ?? out.baked.yaw;
+		if (!out.baked[`foot_${k}`] || !keyed) continue;
+		const sole = out.frames.map((_, i) => groundSole(out, i, S));
+		const down = (i, key) => sole[i][key][1] < H && sole[i - 1][key][1] < H && Math.abs(sole[i][key][1] - sole[i - 1][key][1]) < 0.0005;
+		const flat = i => i > 0 && i < n && down(i, "heel") && down(i, "ball");
+		const want = Array.from({ length: n }, (_, i) => keyed[out.f0 + i]), yaw = want.slice();
+		for (let i = 1; i < n; i++) {
+			if (!flat(i)) continue;
+			const held = yaw[i - 1];
+			let j = i, turn = 0;
+			for (; flat(j); j++) turn = Math.max(turn, Math.abs(yaw[j] - held));
+			// a turn within TOL degrees (the heel moves under 3 mm) is left as it is
+			if (turn <= TOL) { i = j; continue; }
+			worst = Math.max(worst, turn);
+			for (let m = i; m < j; m++) yaw[m] = held;
+			// then onto the keyed heading, as long as the foot does not plant flat again
+			const gap = j < n ? want[j] - held : 0, ease = Math.max(DECAY, Math.ceil(Math.abs(gap) / TURN_RATE));
+			for (let m = 0; gap && m < ease && j + m < n && !flat(j + m); m++) yaw[j + m] = want[j + m] - gap * (1 - smooth((m + 1) / (ease + 1)));
+			i = j;
+		}
+		const moved = yaw.map((v, i) => v !== want[i]);
+		if (!moved.some(Boolean)) continue;
+		const ch = (out.baked[`fyaw_${k}`] = keyed.slice());
+		moved.forEach((m, i) => { if (m) { ch[out.f0 + i] = yaw[i]; touched.add(out.f0 + i); } });
+	}
+	if (!touched.size) return null;
+	engine.solve([...touched]);
+	return { frames: touched.size, max: round4(worst) };
+}

package/src/motion3/follow.js

@@ -0,0 +1,39 @@
+// C16. Follow entries: spec.objects[id] = { follow: <ref>, offset?, aim?, visible?, level? } puts a
+// record (a body, a group root, or a record with no box: an effect, a light, an Empty) on a point
+// of the body at every frame. The ref is any point ref (refs.js): landmark:mouth, joint:<Bone>,
+// prop:<prop>.<point>, anchor:<name>, object:<id> (an object a follow entry does not move).
+//   aim     where the record's +Y points (effects emit along it): "up" (default, world up), "face"
+//           (the face's forward direction, the Head bone's rest +Z, as checks.orient "face"), a
+//           world direction [x, y, z], or a ref (toward that point). The record turns the shortest
+//           way from upright onto it.
+//   offset  metres along the record's own axes after aim (+Y along aim), from the ref point.
+// The take bakes a world-space track at every frame (take.js: pos, quat and hold on every frame,
+// so object-travel.js cuts the carry of the record's own parents), so the renderer and the effects
+// (born at the emitter's pose at the birth frame) see the moving path. A follow entry is not an
+// obstacle (compile.js marks its bodies carried) and QA checks it against nothing: it rides the body.
+import { refPoint } from "./refs.js";
+import { carried } from "./compiler/limbs.js";
+import { add, sub, apply, norm, len, matFromQuat } from "./compiler/math.js";
+import { arcQuat } from "./compiler/quat.js";
+
+const UP = [0, 1, 0];
+
+/** The unit direction aim gives at absolute frame f (inside the window), `from` the followed point. */
+function aimDir(out, f, aim = "up", from) {
+	if (Array.isArray(aim)) return norm(aim);
+	if (aim === "face") { const { sk } = out.ctx; return norm(carried(sk, out.frames[f - (out.f0 ?? 0)].s, sk.index.Head, [0, 0, 1])); }
+	const to = aim === "up" ? null : refPoint(out, f, aim), d = to ? sub(to, from) : UP;
+	return len(d) > 1e-9 ? norm(d) : UP;
+}
+
+/**
+ * World pose { pos, R } of the record follow entry o puts at absolute frame f of compile result
+ * out (a frame outside the compiled window takes the nearest one in it), or null when the ref
+ * has no point there.
+ */
+export function followPose(out, o, f) {
+	const lo = out.f0 ?? 0, ff = Math.max(lo, Math.min(lo + out.frames.length - 1, f)), p = refPoint(out, ff, o.follow);
+	if (!p) return null;
+	const R = matFromQuat(arcQuat(UP, aimDir(out, ff, o.aim, p)));
+	return { pos: add(p, apply(R, o.offset ?? [0, 0, 0])), R };
+}

package/src/motion3/free-motion.js

@@ -0,0 +1,204 @@
+// C17. Objects nobody holds (a can inside a machine, a box on a shelf) move by keys and fall.
+// spec.objects[id] with no prop, follow or hinge field, for a body or a group (its root):
+//   keys  [{ f, pos, rot | aim (+ roll) }]   the world pose of its root (a body's base pivot, a group's
+//         origin) at frame f, on the curve held keys use (object-keys.js keyedPose, C14). aim turns the
+//         scene pose's +Y onto aim, then roll degrees about it. Before the first key of a run it stays
+//         where it was (its scene pose, or where it landed), after the last it holds the last key.
+//   fall  { at, onto?, bounce?, tumble? } or a list   from where it is at frame `at` it falls under gravity
+//         (G m/s^2) onto the top of the highest still body under the centre of its parts (onto: that object's
+//         top; nothing below: the floor, y 0) and comes to rest on a stable face (settle.js): it lands on its
+//         lowest point, turning at the spin it was let go with, rolls flat and over an edge onto a lower face
+//         while the drop has the energy (a phone falls flat, a can lies down). tumble: false drops it straight
+//         down as it was, bouncing at most once (bounce: the restitution 0..0.6, default 0.25, never higher
+//         than BOUNCE_MAX m); one that lands on a stable face as it falls bounces the same way, and one that
+//         rolls spends its landing on the roll and does not bounce (bounce is not read for it).
+// Keys and falls chain in frame order: a fall starts from the pose the keys before it leave (a key on the
+// fall's own frame comes first), keys after a fall take over at their first frame.
+// A carry (C3) takes fall too: before its grab (the hand finds it where it landed) or from its release on.
+// A free object moves like a hinged one (compiler/compile.js objectTracks): an obstacle at its pose that
+// frame, read through object-pose.js by refs, goals, probes, observations.near and QA. Pure over the spec,
+// the scene and the time map (a retime moves its keys and falls with the body's keys): the body never
+// moves it, and nothing it lands on moves (bodies a spec.objects entry moves are no support).
+import { isCarried, compose, relative, movesRecord } from "./carried.js";
+import { groupsOf } from "./scene.js";
+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";
+
+/** Gravity, m/s^2. */
+export const G = 9.8;
+/** The highest a bounce goes, metres. */
+export const BOUNCE_MAX = 0.03;
+const BOUNCE = 0.25, TOUCH = 0.005;
+const HELD_OR_HINGED = ["prop", "follow", "pivot", "axis", "channel"];
+
+/** A free entry (C17): no prop, follow or hinge field, and keys or fall. */
+export const isFree = o => !!o && typeof o === "object" && !Array.isArray(o) && HELD_OR_HINGED.every(k => o[k] === undefined) && (o.keys !== undefined || o.fall !== undefined);
+/** The falls of an entry (fall is one or a list), as given. */
+const fallsOf = o => (o?.fall === undefined ? [] : Array.isArray(o.fall) ? o.fall : [o.fall]);
+
+const restOf = (scene, id) => scene?.objects?.[id] ?? groupsOf(scene)[id] ?? null;
+const partsIn = (scene, id) => Object.keys(scene?.objects ?? {}).filter(k => k === id || scene.objects[k].ancestors?.includes(id));
+
+/** The 8 corners of a base-pivot box { pos, R, half }. */
+function corners(box) {
+	const out = [];
+	for (const x of [-1, 1]) for (const y of [0, 2]) for (const z of [-1, 1]) out.push(add(box.pos, apply(box.R, [x * box.half[0], y * box.half[1], z * box.half[2]])));
+	return out;
+}
+const topOf = box => Math.max(...corners(box).map(p => p[1]));
+/** True when the vertical through x/z point p crosses the footprint of box. */
+const under = (box, p) => { const q = apply(T(box.R), sub([p[0], box.pos[1] + box.half[1], p[2]], box.pos)); return Math.abs(q[0]) <= box.half[0] && Math.abs(q[2]) <= box.half[2]; };
+
+/** Bodies a spec.objects entry moves (itself or a group above it): they hold nothing up. */
+function moversIn(spec, scene) {
+	const out = new Set();
+	for (const [id, o] of Object.entries(scene?.objects ?? {})) if ([id, ...(o.ancestors ?? [])].some(k => movesRecord(spec.objects?.[k]))) out.add(id);
+	return out;
+}
+
+/** The part boxes of `id` with its root at world pose `root`. */
+function boxesAtRoot(scene, id, root) {
+	const rest = restOf(scene, id);
+	return partsIn(scene, id).map(p => ({ id: p, ...compose(root, relative(rest, scene.objects[p])), half: scene.objects[p].half }));
+}
+
+/** What `id` lands on from pose `start`: { support (a body id, or null for the floor), top, h (the drop, m) }. */
+export function landingOf(spec, scene, id, start, onto = null) {
+	const boxes = boxesAtRoot(scene, id, start), own = new Set(boxes.map(b => b.id)), movers = moversIn(spec, scene);
+	if (!boxes.length) return { support: null, top: 0, h: 0 };
+	const low = Math.min(...boxes.flatMap(b => corners(b).map(p => p[1])));
+	const c = boxes.flatMap(corners).reduce((s, p) => add(s, p), [0, 0, 0]).map(v => v / (boxes.length * 8));
+	const pool = (onto ? partsIn(scene, onto) : Object.keys(scene.objects)).filter(k => !own.has(k) && !movers.has(k));
+	let best = null;
+	for (const k of pool) {
+		const box = scene.objects[k], top = topOf(box);
+		if (under(box, c) && top <= low + TOUCH && (!best || top > best.top)) best = { support: k, top };
+	}
+	// onto an object that is not right below: its highest top, the agent placed it
+	if (!best && onto) for (const k of pool) { const top = topOf(scene.objects[k]); if (top <= low + TOUCH && (!best || top > best.top)) best = { support: k, top }; }
+	best ??= { support: null, top: 0 };
+	return { ...best, h: Math.max(0, low - best.top) };
+}
+
+const shapes = new WeakMap();
+/** The shape of `id` in its root frame (settle.js), once per scene. */
+function shapeIn(scene, id) {
+	if (!shapes.has(scene)) shapes.set(scene, new Map());
+	const cache = shapes.get(scene);
+	if (!cache.has(id)) cache.set(id, shapeOf(boxesAtRoot(scene, id, { pos: [0, 0, 0], R: I3() })));
+	return cache.get(id);
+}
+
+/**
+ * A fall from root pose `start` at (mapped) frame t0: its timing, its pose at a frame, where it rests. `before` is its pose
+ * a frame earlier (a release from the hand), for the spin it is let go with.
+ */
+function fallPlan(spec, scene, id, start, t0, fall, fps, before = null) {
+	const land = landingOf(spec, scene, id, start, fall.onto ?? null), shape = fall.tumble === false ? null : shapeIn(scene, id);
+	if (shape) {
+		const spin = before ? spinOf(before.R, start.R, fps) : [0, 0, 0], air = airPath(shape, start, spin, land.top, fps);
+		// a spin tips it the way its top moves (spin x up); a spin about the vertical tips nothing
+		const path = settlePath(shape, air.at(air.tl), land.top, TIP * land.h + spinEnergy(shape, spin), [-spin[2], 0, spin[0]]);
+		if (path.steps.length || spin.some(v => v)) {
+			const at = f => { const t = (f - t0) / fps; return t <= 0 ? start : t <= air.tl ? air.at(t) : settledAt(path, t - air.tl); };
+			return { t0, land: t0 + air.tl * fps, end: t0 + (air.tl + path.time) * fps, h: land.h, support: land.support, top: land.top, at, rest: path.rest };
+		}
+	}
+	const h = land.h, tl = Math.sqrt(2 * h / G);
+	const e = Math.min(0.6, Math.max(0, fall.bounce ?? BOUNCE)), vb = Math.min(e * G * tl, Math.sqrt(2 * G * BOUNCE_MAX)), tb = 2 * vb / G;
+	const rest = { pos: [start.pos[0], start.pos[1] - h, start.pos[2]], R: start.R };
+	const at = f => {
+		const t = (f - t0) / fps;
+		if (t <= 0) return start;
+		const dy = t <= tl ? -0.5 * G * t * t : t <= tl + tb ? -h + vb * (t - tl) - 0.5 * G * (t - tl) ** 2 : -h;
+		return { pos: [start.pos[0], start.pos[1] + Math.min(0, dy), start.pos[2]], R: start.R };
+	};
+	return { t0, land: t0 + tl * fps, end: t0 + (tl + tb) * fps, h, support: land.support, top: land.top, at, rest };
+}
+
+/** The events of an entry's falls and key runs in frame order (keys split into runs by the falls between them). */
+function eventsOf(o, map, from = -Infinity, to = Infinity) {
+	// a carry's keys pose it in hand (C14); only its falls are free
+	const keys = isCarried(o) ? [] : [...(o.keys ?? [])].sort((a, b) => a.f - b.f);
+	const falls = fallsOf(o).map(fl => ({ ...fl, t: map(fl.at) })).filter(fl => fl.t >= from && fl.t < to).sort((a, b) => a.t - b.t);
+	const events = [];
+	let run = [], i = 0;
+	for (const k of keys) {
+		while (i < falls.length && falls[i].t < map(k.f)) { if (run.length) events.push({ run }); run = []; events.push({ fall: falls[i++] }); }
+		run.push(k);
+	}
+	if (run.length) events.push({ run });
+	while (i < falls.length) events.push({ fall: falls[i++] });
+	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;
+	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]);
+		} else {
+			if (f < e.fall.t) return pose;
+			const p = keep ? (e.plan ??= plan(pose, e.fall)) : plan(pose, e.fall);
+			if (f < p.end) return p.at(f);
+			pose = p.rest;
+		}
+	}
+	return pose;
+}
+
+const timelines = new WeakMap();
+/** The events of entry o under time map `map`, cached per scene, entry and span (key curves built once). */
+function timelineOf(ctx, id, o, map, part) {
+	if (!timelines.has(ctx.scene)) timelines.set(ctx.scene, new Map());
+	const cache = timelines.get(ctx.scene), key = `${id}|${part}|${ctx.grab}|${ctx.release}`, had = cache.get(key);
+	if (had && had.map === map && had.o === o && had.spec === ctx.spec) return had.events;
+	const rest = restOf(ctx.scene, id), m = map ?? (f => f), [from, to] = part === "before" ? [-Infinity, ctx.grab] : part === "after" ? [ctx.release, Infinity] : [-Infinity, Infinity];
+	const events = eventsOf(o, m, from, to);
+	for (const e of events) if (e.run) e.curve = curveOf({ keys: e.run }, m, () => quatFromMat(rest.R), null);
+	cache.set(key, { map, o, spec: ctx.spec, events });
+	return events;
+}
+
+const planner = (ctx, id) => (start, fall) => fallPlan(ctx.spec, ctx.scene, id, start, fall.t, fall, ctx.spec.fps ?? 30);
+
+/**
+ * World pose { pos, R } of the root of free entry `id` at absolute frame f (ctx = { spec, scene,
+ * timeMap }): keys and falls (C17) from its scene pose. null for an id the scene does not know.
+ */
+export function freePoseAt(ctx, id, f) {
+	const rest = restOf(ctx.scene, id), o = ctx.spec.objects?.[id];
+	if (!rest || !o) return null;
+	return walk(timelineOf(ctx, id, o, ctx.timeMap, "all"), f, { pos: rest.pos, R: rest.R }, planner(ctx, id));
+}
+
+/** 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);
+	if (!rest || !fallsOf(o).length) return rest && { pos: rest.pos, R: rest.R };
+	return walk(timelineOf({ ...ctx, grab }, id, o, ctx.timeMap, "before"), f, { pos: rest.pos, R: rest.R }, planner(ctx, id));
+}
+
+/**
+ * Where carry `id` (entry o) is at absolute f after its release, from its release pose; null without a fall from the release on.
+ * `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) {
+	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;
+}
+
+/** The falls of entry `id` as planned under the current time map, for readers (timeline, tests): [{ t0, land, end, h, support, top }]. */
+export function fallPlans(ctx, id) {
+	const o = ctx.spec.objects?.[id];
+	if (!isFree(o)) return [];
+	freePoseAt(ctx, id, Infinity);
+	return timelineOf(ctx, id, o, ctx.timeMap, "all").filter(e => e.plan).map(({ plan: { t0, land, end, h, support, top } }) => ({ t0, land, end, h, support, top }));
+}