cozyclay 3.1.1 → 3.1.2

package/src/motion3/compiler/channels.js

@@ -12,7 +12,11 @@
 // flow is gone by the time the arm is a quarter of the way onto it: an arm's swing and bend by its
 // own armw, the spine (which carries the shoulders) and the head (the hands work near it) by the
 // larger of the two; a reach or a held prop lands as keyed. A hold (two equal keys in a row) stays
-// exactly flat either way.
+// exactly flat either way. Overlap (overlap.js) breaks each change along the chains on top of that: the
+// lower spine, the chest (chest_*: the top spine bone's share, baked beside spine_*), the head, the upper
+// arm, the forearm and the wrist each take a later delay, one side of the body trails the other, and the
+// arm's swing and bend overshoot and settle where they stop.
+import { overlapDelay, sideTrail, settleBump, ikGap, contactGap, OVERLAP_SLOPE } from "./overlap.js";
 
 function pchipSlopes(x, y) {
 	const n = y.length, m = new Array(n).fill(0);
@@ -37,18 +41,24 @@ function pchipEval(x, y, m, q) {
 	return (2 * t3 - 3 * t2 + 1) * y[i] + (t3 - 2 * t2 + t) * h * m[i] + (-2 * t3 + 3 * t2) * y[i + 1] + (t3 - t2) * h * m[i + 1];
 }
 
-const FLOW_SMOOTH = /^(spine|head)_(yaw|pitch|roll)$|^(aswing|abend)_[lr]$/;
+const FLOW_SMOOTH = /^(spine|chest|head)_(yaw|pitch|roll)$|^(aswing|abend)_[lr]$/;
 const FLOW_LAG = { spine: 0, head: 2, arms: 3 };
+const ARM = /^(hand|armw|elbow|aswing|abend|wflex|wtwist)_[lr]$/; // one side's arm: trails as one (overlap.js sideTrail)
 const OVER_FRAC = 0.15, OVER_MAX = 6; // a smooth segment's overshoot: at most this share of its change, and degrees
-const ikSides = ch => (/^(spine|head)_/.test(ch) ? ["l", "r"] : /^(aswing|abend)_([lr])$/.test(ch) ? [ch.slice(-1)] : []);
-const lagFamily = ch => (/^spine_/.test(ch) ? "spine" : /^head_/.test(ch) ? "head" : /^(aswing|abend)_[lr]$/.test(ch) ? "arms" : null);
+const ikSides = ch => (/^(spine|chest|head)_/.test(ch) ? ["l", "r"] : /^(aswing|abend|wflex|wtwist)_([lr])$/.test(ch) ? [ch.slice(-1)] : []);
+const lagFamily = ch => (/^(spine|chest)_/.test(ch) ? "spine" : /^head_/.test(ch) ? "head" : /^(aswing|abend)_[lr]$/.test(ch) ? "arms" : null);
 
-/** spec.flow -> { smooth, lag: { spine, head, arms } }: undefined is the default, false turns both off. */
-export function flowOptions(flow) {
-	if (flow === false) return { smooth: false, lag: { spine: 0, head: 0, arms: 0 } };
+/**
+ * spec.flow -> { smooth, lag: { spine, head, arms }, overlap, seed, hands }: undefined is the default, false turns all off.
+ * overlap: true (1) | false (0) | a scale of its delays and settle (overlap.js); seed (the spec's label) picks which side trails;
+ * hands: the frames each hand works on something (overlap.js handBusy), where a free IK hand's trail stops.
+ */
+export function flowOptions(flow, seed = "", hands = { l: [], r: [] }) {
+	if (flow === false) return { smooth: false, lag: { spine: 0, head: 0, arms: 0 }, overlap: 0, seed, hands };
 	const f = flow ?? {}, lag = f.lag === false ? 0 : f.lag;
 	const each = typeof lag === "number" ? { spine: lag, head: lag, arms: lag } : { ...FLOW_LAG, ...(lag ?? {}) };
-	return { smooth: f.smooth !== false, lag: each };
+	const overlap = f.overlap === false ? 0 : typeof f.overlap === "number" ? f.overlap : 1;
+	return { smooth: f.smooth !== false, lag: each, overlap, seed, hands };
 }
 
 /** Catmull-Rom slopes, flat at a hold and at the ends, each segment's overshoot bounded. */
@@ -78,11 +88,47 @@ export function bakeChannels(keys, frameCount, flow = flowOptions()) {
 	for (const key of [...keys].sort((a, b) => a.f - b.f)) {
 		for (const [ch, value] of Object.entries(key.set ?? {})) {
 			if (!byChannel.has(ch)) byChannel.set(ch, []);
-			byChannel.get(ch).push({ f: key.f, value, step: key.step?.includes(ch) });
+			byChannel.get(ch).push({ f: key.f, value, step: key.step?.includes(ch), src: key.src });
 		}
 	}
+	// the top spine bone's share breaks after the two below it (pose.js), so it is baked as its own channel
+	const overlap = flow.overlap ?? 0, entries = [...byChannel];
+	if (overlap > 0) for (const [ch, list] of byChannel) if (/^spine_/.test(ch)) entries.push([ch.replace("spine", "chest"), list]);
+	// an arm's IK weights first: a link's own delay runs out before an arm goes onto its IK and comes back after it
+	// leaves (overlap.js), so the fade below never snaps a delayed move onto its keyed frames. Before them where each
+	// hand touches: its anchor and fit weights (never delayed) and its carries and hand goals (flow.hands); a side's
+	// trail stops short of those
+	const pre = new Map(), near = new Map(), touch = {}, trails = {};
+	if (overlap > 0) {
+		for (const [ch, list] of entries) if (/^w_.+_[lr]$/.test(ch)) pre.set(ch, bakeOne(ch, list));
+		for (const k of ["l", "r"]) touch[k] = contactGap(flow.hands?.[k] ?? [], [...pre].filter(([ch]) => ch.endsWith(`_${k}`)).map(([, b]) => b.frames), frameCount);
+		// the whole arm of a side trails as one (overlap.js sideTrail), its FK swing with its IK weight, so a blend between
+		// them never sets a late weight over an on-time swing
+		for (const k of ["l", "r"]) trails[k] = sideTrail([...byChannel].filter(([ch]) => ARM.test(ch) && ch.endsWith(`_${k}`)).map(([ch, list]) => Object.assign([...list], { weight: /^armw_/.test(ch) })), k, overlap, flow.seed ?? "", touch[k]);
+		for (const [ch, list] of entries) if (/^armw_[lr]$/.test(ch)) pre.set(ch, bakeOne(ch, list));
+	}
+	const gapOf = ch => {
+		const sides = ikSides(ch).filter(k => pre.has(`armw_${k}`)), key = sides.join("");
+		if (!sides.length) return null;
+		if (!near.has(key)) near.set(key, ikGap(sides.map(k => pre.get(`armw_${k}`).frames), frameCount));
+		return near.get(key);
+	};
 	const out = {}, plain = {};
-	for (const [ch, list] of byChannel) {
+	for (const [ch, list] of entries) {
+		const baked = pre.get(ch) ?? bakeOne(ch, list, gapOf(ch));
+		out[ch] = baked.frames;
+		if (baked.plain) plain[ch] = baked.plain;
+	}
+	// flow fades out as the arm goes onto its IK (the spine with either arm)
+	for (const [ch, keyed] of Object.entries(plain)) {
+		const ws = ikSides(ch).map(k => out[`armw_${k}`]).filter(Boolean);
+		if (!ws.length) continue;
+		out[ch] = out[ch].map((v, f) => { const w = Math.min(1, 4 * Math.max(0, ...ws.map(a => a[f]))); return v + (keyed[f] - v) * w * (2 - w); });
+	}
+	return out;
+
+	/** One channel's frames (and, for a flowing body channel, its keyed frames: plain); gap: frames to the nearest IK frame. */
+	function bakeOne(ch, list, gap = null) {
 		// later keys at the same frame win
 		const pts = [...new Map(list.map(k => [k.f, k])).values()];
 		const shape = shapeOf(pts[0].value);
@@ -91,15 +137,24 @@ export function bakeChannels(keys, frameCount, flow = flowOptions()) {
 			: shape === "vec" ? Array.from({ length: comps }, (_, i) => pts.map(p => p.value[i]))
 				: [...new Set(pts.flatMap(p => Object.keys(p.value)))].map(name => ({ name, y: pts.map(p => p.value[name] ?? 0) }));
 		const x = pts.map(p => p.f), smooth = flow.smooth && FLOW_SMOOTH.test(ch), lag = flow.lag[lagFamily(ch)] ?? 0;
-		// the trail eases out over the last 2 * lag frames, so the take ends on the last value
-		const at = f => (lag > 0 ? f - lag * Math.min(1, (frameCount - 1 - f) / (2 * lag)) : f);
+		const delay = shape === "num" ? overlapDelay(ch, pts, overlap, flow.seed ?? "", gap) : null;
+		const trail = ARM.test(ch) ? trails[ch.slice(-1)] : null, most = lag + (delay?.max ?? 0);
+		const delayAt = f => (delay ? Math.min(delay.at(f), gap ? OVERLAP_SLOPE * gap[Math.round(f)] : Infinity) : 0);
+		const end = (f, d) => Math.min(1, (frameCount - 1 - f) / (2 * d));
+		// the trail eases out over the last 2 * (its most) frames, so the take ends on the last value (the side's trail over
+		// its own: a short ease there would quicken the arm's last move); the side's trail rides the keyed curve too (plain),
+		// which an arm on its IK goes back to
+		const keyedAt = f => (trail ? f - trail.at(f) * end(f, trail.max) : f);
+		const at = f => keyedAt(f) - (most > 0 ? (lag + delayAt(f)) * end(f, most) : 0);
+		// a settle near an arm's IK would be cut by the fade below: none within its span and a few frames
+		const clear = (a, b) => { if (!gap) return true; for (let f = Math.max(0, Math.floor(a)); f <= Math.min(frameCount - 1, Math.ceil(b + most)); f++) if (gap[f] < 2) return false; return true; };
 		const evalSeries = (y, flowing = true) => {
-			const m = smooth && flowing ? smoothSlopes(x, y) : pchipSlopes(x, y);
+			const m = smooth && flowing ? smoothSlopes(x, y) : pchipSlopes(x, y), bump = flowing && shape === "num" ? settleBump(ch, pts, y, overlap, frameCount - 1, clear) : null;
 			return q => {
-				const f = flowing ? at(q) : q;
+				const f = flowing ? at(q) : keyedAt(q);
 				// a step key holds the previous value right up to its frame
 				for (let i = 1; i < pts.length; i++) if (pts[i].step && f >= x[i - 1] && f < x[i]) return y[i - 1];
-				return pchipEval(x, y, m, f);
+				return pchipEval(x, y, m, f) + (bump ? bump(f) : 0);
 			};
 		};
 		const frames = new Array(frameCount);
@@ -109,16 +164,11 @@ export function bakeChannels(keys, frameCount, flow = flowOptions()) {
 			const es = series.map(({ name, y }) => [name, evalSeries(y)]);
 			for (let f = 0; f < frameCount; f++) frames[f] = Object.fromEntries(es.map(([n, e]) => [n, e(f)]));
 		}
-		out[ch] = frames;
-		if (shape === "num" && (smooth || lag > 0) && ikSides(ch).length) { const e = evalSeries(series[0], false); plain[ch] = Array.from({ length: frameCount }, (_, f) => e(f)); }
-	}
-	// flow fades out as the arm goes onto its IK (the spine with either arm)
-	for (const [ch, keyed] of Object.entries(plain)) {
-		const ws = ikSides(ch).map(k => out[`armw_${k}`]).filter(Boolean);
-		if (!ws.length) continue;
-		out[ch] = out[ch].map((v, f) => { const w = Math.min(1, 4 * Math.max(0, ...ws.map(a => a[f]))); return v + (keyed[f] - v) * w * (2 - w); });
+		if (!(shape === "num" && (smooth || most > 0) && ikSides(ch).length)) return { frames };
+		// an arm's own channels keep the side's trail on its IK too (plain), only the links' own delays and settle fade
+		const e = evalSeries(series[0], false);
+		return { frames, plain: Array.from({ length: frameCount }, (_, f) => e(f)) };
 	}
-	return out;
 }
 
 /** Frame f's channel dict. */

package/src/motion3/compiler/compile.js

@@ -26,6 +26,7 @@ import { pose, SIDES } from "./pose.js";
 import { graspAnchor } from "./socket-grip.js";
 import { gripHand } from "./grip.js";
 import { bakeChannels, channelsAt, flowOptions } from "./channels.js";
+import { handBusy } from "./overlap.js";
 import { idleLayer, withIdle, busyHands } from "./idle.js";
 import { resolveAnchor, measureProps, armReach } from "./anchors.js";
 import { expandGenerators } from "./walk.js";
@@ -208,7 +209,7 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	const engine = {
 		rebake(keys) {
 			out.keys = keys;
-			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow));
+			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow, spec.label ?? "", handBusy(spec)));
 			ctx.socketTurns = new Map();
 			ctx.graspPlans = new Map();
 			steadyHead(out.baked, keys, frameCount);

package/src/motion3/compiler/idle.js

@@ -109,5 +109,7 @@ export function withIdle(c, layer, f) {
 	if (!d) return c;
 	const out = { ...c };
 	for (const [ch, v] of Object.entries(d)) out[ch] = Array.isArray(v) ? (Array.isArray(c[ch]) ? c[ch].map((x, i) => x + v[i]) : c[ch]) : (Number(c[ch]) || 0) + v;
+	// the top spine bone's own share (chest_*, channels.js overlap) breathes and sways with the rest of the spine
+	for (const ch of ["chest_pitch", "chest_roll"]) if (c[ch] !== undefined && d[ch.replace("chest", "spine")] !== undefined) out[ch] = c[ch] + d[ch.replace("chest", "spine")];
 	return out;
 }

package/src/motion3/compiler/overlap.js

@@ -0,0 +1,180 @@
+// Overlap (spec.flow.overlap, on by default): a body does not start or stop all at once. A change breaks
+// along the chains one link after another: the lower spine, then the chest, then the head; the upper arm,
+// then the forearm, then the hand; each link starts later and settles later than the one it hangs from.
+// The agent keys five channels on one frame and both arms on the same frames (the user's tutorial take:
+// 7 of 7 parts within +-1 frame, observations.life sync 0.81), and a constant trail per family moves the
+// whole curve of a family at once, so every link of it still starts on one frame. Here each link takes its
+// own delay at each of its keys (LINK frames at 24 fps, less for a short move: LINK * h / FULL for a move
+// of h frames, so a quick flick is not smeared and a key pose is reached long before the next key), one
+// side of the body trails the other by SIDE frames chosen per key frame (a hash of the spec's label and the
+// key frame, so the same spec bakes the same take and both arms keyed on one frame part on different ones),
+// and the arm's swing and bend, the distal swing, overshoot a little where they stop and settle back
+// (SETTLE: a bounded hump, then exactly the keyed value, so a hold stays flat after it). Only the body's
+// own swing moves: the channels that place it (feet, root, yaw, hand targets and weights, poles, fingers,
+// objects) are untouched, so every contact lands as keyed; an arm on its IK loses it with the rest of
+// flow (channels.js), and a skill that times its own motion (a walk's rhythm, a flip, a hit) keeps its keys
+// on time: the delay is for the agent's keys (and standIdle's pose), easing in and out around the rest.
+// frames for a FULL-frame move; the arm's swing and bend also trail the body by flow.lag.arms (3), the wrist (no flow of
+// its own) here: after the forearm
+// its own) here: after the forearm. A free IK hand (hand target, IK weight and pole together: hand) takes no delay of its
+// own, only its side's trail, so both hands keyed on one frame part
+const LINK = { spine: 1, chest: 2.5, head: 3.5, aswing: 3, abend: 5, wrist: 9.5, hand: 0 };
+/** A hand keeps its keyed time within CONTACT frames of a contact: an anchor or fit weight on, a carry, a hand goal (handBusy). */
+const CONTACT = 6, SNAP = 6;
+const FULL = 24, SIDE = [1.5, 3];
+/** How fast a delay may change, frames a frame: under 1 time still runs forward; it also runs out this fast before an arm's IK. */
+export const OVERLAP_SLOPE = 0.5;
+const MOVE_SLOPE = 0.2, TRAIL_SLOPE = 0.15;
+const SETTLE = { frames: 8, min: 6, frac: 0.08, max: 3 };
+const SETTLES = /^(aswing|abend|wflex)_[lr]$/;
+// a skill times its own motion (a flip, a hit, a walk: walk.js tags its steps); standIdle only sets the pose the agent's keys start from
+const OWN_TIMING = /^use\[\d+\] (?!standIdle$)|\bwalk(To)? (start|step \d+|end)$/;
+
+const ownTiming = p => OWN_TIMING.test(p?.src ?? "");
+
+/** The chain link a channel moves, or null (a placement channel, or one overlap leaves alone). */
+function linkOf(ch) {
+	const m = /^(spine|chest|head)_(yaw|pitch|roll)$|^(aswing|abend|wflex|wtwist)_[lr]$|^(hand|armw|elbow)_[lr]$/.exec(ch);
+	if (!m) return null;
+	return m[1] ?? (m[4] ? "hand" : m[3] === "wflex" || m[3] === "wtwist" ? "wrist" : m[3]);
+}
+
+/** text -> a number in [-1, 1) (FNV-1a hash, then one mulberry32 step; gait-rhythm.js noiseOf). */
+function unit(text) {
+	let h = 2166136261;
+	for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
+	let t = Math.imul((h >>> 0) ^ ((h >>> 0) >>> 15), (h >>> 0) | 1);
+	t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+	return (((t ^ (t >>> 14)) >>> 0) / 4294967296) * 2 - 1;
+}
+
+/** A delay a key at a time, eased between keys: { max, at(q) }, or null when it is 0 throughout. */
+function delayCurve(x, lam, slope) {
+	const n = x.length;
+	for (let i = 1; i < n; i++) lam[i] = Math.min(lam[i], lam[i - 1] + slope(i - 1));
+	for (let i = n - 2; i >= 0; i--) lam[i] = Math.min(lam[i], lam[i + 1] + slope(i));
+	if (!lam.some(v => v > 0)) return null;
+	return {
+		max: Math.max(...lam),
+		at(q) {
+			if (q <= x[0]) return lam[0];
+			if (q >= x[n - 1]) return lam[n - 1];
+			let i = 0;
+			while (q > x[i + 1]) i++;
+			return lam[i] + ((lam[i + 1] - lam[i]) * (q - x[i])) / (x[i + 1] - x[i]);
+		},
+	};
+}
+
+/**
+ * The delay (frames) of a link, on top of its side's trail (sideTrail), at each frame, or null. pts: the channel's
+ * keys ({ f, value, src }); scale: flow.overlap (1 the default). A delay is set at each key (the move that leaves it:
+ * LINK for a FULL-frame move, less for a shorter one), 0 at (and into) a skill's own keys and at keys next to an arm's
+ * IK (gap: frames to the nearest IK frame per frame, ikGap), and eased between keys no steeper than OVERLAP_SLOPE
+ * frames a frame on a hold and MOVE_SLOPE across a move, so time still runs forward and a hold keeps its length.
+ */
+export function overlapDelay(ch, pts, scale, seed, gap = null) {
+	const link = linkOf(ch);
+	if (!link || !LINK[link] || !(scale > 0) || pts.length < 2) return null;
+	const x = pts.map(p => p.f), n = x.length;
+	const lam = x.map((f, i) => {
+		// a move on, into or out of an arm's IK keeps its keyed time (gap: frames to its IK, ikGap); the delay comes and goes on the holds around it
+		if (ownTiming(pts[i]) || ownTiming(pts[i + 1]) || (gap && [x[i - 1], f, x[i + 1]].some(g => g !== undefined && gap[g] < 2))) return 0;
+		return LINK[link] * Math.min(1, (i < n - 1 ? x[i + 1] - f : FULL) / FULL) * scale;
+	});
+	// a delay changes on a hold, where nothing shows it; across a move only by MOVE_SLOPE (its speed within about 20%)
+	return delayCurve(x, lam, i => (pts[i].value === pts[i + 1].value ? OVERLAP_SLOPE : MOVE_SLOPE) * (x[i + 1] - x[i]));
+}
+
+/**
+ * One side's trail: the whole arm of that side (its swing, bend and wrist, and as a free IK hand its target, IK weight
+ * and pole) runs this many frames late, so both arms keyed on one frame part, and the arm's FK and IK stay in step
+ * while it blends between them. keys: the keys of that arm's channels ({ f, src }). At each key frame the side
+ * that trails (a hash of seed and frame: both sides agree) takes SIDE[0]..SIDE[1] frames, no more than a third of the
+ * moves either side of the key; none at a snap (moves under SNAP frames: a trail changing across one bends it), at a
+ * skill's own keys, or within CONTACT frames of the hand's contacts (gap: contactGap). channels: each of the arm's
+ * channels' keys ({ f, value, src }), the IK weight's list marked weight: true.
+ */
+export function sideTrail(channels, side, scale, seed, gap = null) {
+	// one point a frame, a skill's own if any key on it is; the spans where some channel of the arm moves
+	const byFrame = new Map(), moves = [], same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+	for (const list of channels) {
+		for (const p of list) if (!byFrame.has(p.f) || ownTiming(p)) byFrame.set(p.f, p);
+		for (let i = 1; i < list.length; i++) if (!same(list[i - 1].value, list[i].value)) moves.push([list[i - 1].f, list[i].f, list.weight]);
+	}
+	const keyFrames = [...byFrame.values()].sort((a, b) => a.f - b.f);
+	if (!(scale > 0) || keyFrames.length < 2) return null;
+	const x = keyFrames.map(p => p.f), n = x.length;
+	const lam = x.map((f, i) => {
+		// the take starts on its keys
+		if (f === 0 || ownTiming(keyFrames[i]) || ownTiming(keyFrames[i + 1]) || (gap && [x[i - 1], f, x[i + 1]].some(g => g !== undefined && gap[g] < 2))) return 0;
+		const u = unit(`${seed}|${f}`), short = Math.min(i < n - 1 ? x[i + 1] - f : FULL, i > 0 ? f - x[i - 1] : FULL);
+		if ((u < 0 ? "l" : "r") !== side || short < SNAP) return 0;
+		return Math.min(SIDE[0] + (SIDE[1] - SIDE[0]) * Math.abs(u), short / 3) * Math.min(1, scale);
+	});
+	// the trail changes freely while the whole arm holds; across a move by TRAIL_SLOPE (its speed within about 15%), and
+	// never across a change of the IK weight: the blend of FK and IK there turns a changing trail into a pop of the hand
+	const across = i => moves.filter(([a, b]) => a < x[i + 1] && b > x[i]), h = i => x[i + 1] - x[i];
+	return delayCurve(x, lam, i => (!across(i).length ? OVERLAP_SLOPE : across(i).some(m => m[2]) ? 0 : TRAIL_SLOPE) * h(i));
+}
+
+const hump = u => (u <= 0 || u >= 1 ? 0 : 64 * (u * (1 - u)) ** 3);
+
+/**
+ * The distal swing's follow-through (the arm's swing and bend, the wrist's flex): a bump (degrees, by curve time) added where a move stops (a key whose
+ * next key holds its value, or the last key): it peaks SETTLE.frac of the move (SETTLE.max deg at most) past
+ * the key a quarter of the way in and is gone SETTLE.frames later (less, and smaller, for a short move or hold;
+ * none under SETTLE.min frames), with no
+ * step in speed or acceleration at either end, and never past the take's end frame. abend never goes past
+ * straight; a skill's own stop has none; clear(a, b) false leaves a bump over frames a..b out (an arm going onto its IK). null when there is none.
+ */
+export function settleBump(ch, pts, y, scale, end, clear = () => true) {
+	if (!SETTLES.test(ch) || !(scale > 0)) return null;
+	const bumps = [], x = pts.map(p => p.f);
+	for (let i = 1; i < x.length; i++) {
+		const d = y[i] - y[i - 1], next = x[i + 1];
+		if (Math.abs(d) < 1 || ownTiming(pts[i]) || ownTiming(pts[i - 1]) || (next !== undefined && y[i + 1] !== y[i])) continue;
+		const S = Math.min(SETTLE.frames, 0.5 * (x[i] - x[i - 1]), next === undefined ? Infinity : 0.5 * (next - x[i]));
+		// a shorter settle is a smaller one: its acceleration goes as A / S^2
+		let A = Math.sign(d) * Math.min(SETTLE.max * (S / SETTLE.frames) ** 2, SETTLE.frac * Math.abs(d)) * Math.min(1, scale);
+		if (/^abend/.test(ch) && y[i] + A < 0) A = Math.min(0, -y[i]);
+		// the take ends on its last value: a bump that would run past the end is left out
+		if (S >= SETTLE.min && Math.abs(A) > 1e-3 && x[i] + 0.75 * S <= end && clear(x[i] - S / 4, x[i] + 0.75 * S)) bumps.push([x[i] - S / 4, S, A]);
+	}
+	if (!bumps.length) return null;
+	return t => { let v = 0; for (const [a, S, A] of bumps) v += A * hump((t - a) / S); return v; };
+}
+
+/** Per frame, how many frames away the nearest frame is on which any of these IK weights is on (Infinity: none). */
+export function ikGap(weights, frameCount) {
+	const gap = new Array(frameCount).fill(Infinity);
+	for (let f = 0, last = -Infinity; f < frameCount; f++) { if (weights.some(w => w[f] > 1e-3)) last = f; gap[f] = f - last; }
+	for (let f = frameCount - 1, next = Infinity; f >= 0; f--) { if (weights.some(w => w[f] > 1e-3)) next = f; gap[f] = Math.min(gap[f], next - f); }
+	return gap;
+}
+
+/**
+ * Per side, the frames its hand works on something (a carry from its grab to its release, a near, above or still goal
+ * that names a hand over its frames), from the spec; channels.js adds the frames an anchor or fit weight of that hand is on. { l, r }: [[a, b]].
+ */
+export function handBusy(spec) {
+	const out = { l: [], r: [] }, end = Math.round(spec?.frames ?? 0);
+	for (const o of Object.values(spec?.objects ?? {})) {
+		const k = spec.props?.[o?.prop]?.hand;
+		if (Number.isFinite(o?.grab) && out[k]) out[k].push([o.grab, Number.isFinite(o.release) ? o.release : end]);
+	}
+	for (const g of spec?.goals ?? []) {
+		const at = Array.isArray(g?.at) ? g.at : null;
+		// a goal that puts a hand somewhere (near, above, still), not one that only measures it (speed, moved)
+		if (at?.length && ["near", "above", "still"].some(k => g[k] !== undefined) && /hand/i.test(JSON.stringify(g))) for (const k of ["l", "r"]) out[k].push([at[0], at[at.length - 1]]);
+	}
+	return out;
+}
+
+/** Per frame, how far a hand is from its contacts (handBusy spans and its own anchor weights), less margin (CONTACT): under 2 holds the keyed time. */
+export function contactGap(spans, weights, frameCount, margin = CONTACT) {
+	const busy = new Uint8Array(frameCount);
+	for (const [a, b] of spans) for (let f = Math.max(0, Math.floor(a)); f <= Math.min(frameCount - 1, Math.ceil(b)); f++) busy[f] = 1;
+	for (const w of weights) for (let f = 0; f < frameCount; f++) if (w[f] > 1e-3) busy[f] = 1;
+	return ikGap([busy], frameCount).map(g => Math.max(0, g - margin));
+}

package/src/motion3/compiler/pose.js

@@ -19,9 +19,8 @@ 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;
+/** Split a body-frame rotation over a chain of bones (k shares), each turning about its own joint. */
+function spread(sk, s, bones, yaw, pitch, roll, 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))));
@@ -117,7 +116,10 @@ export function pose(sk, c, hooks = {}) {
 		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));
+	// the top spine bone turns its share of chest_* when flow bakes one (channels.js overlap: it breaks after the two below)
+	const sy = num(c.spine_yaw), sp = num(c.spine_pitch), sr = num(c.spine_roll);
+	spread(sk, s, ["Spine", "Spine1"], sy, sp, sr, 3);
+	spread(sk, s, ["Spine2"], num(c.chest_yaw, sy), num(c.chest_pitch, sp), num(c.chest_roll, sr), 3);
 	// 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)))));

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

@@ -19,6 +19,7 @@ export function objectOk(err, scene, at, id, { groups = false } = {}) {
 	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 if (scene?.others?.[id]) err(`${at} names "${id}", a ${scene.others[id].renderer ?? "record"} with no body (no size to stand on, hold or hit); name a scene body${didYouMean(String(id), ids)}`);
 	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;
 }

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

@@ -56,7 +56,11 @@ function validateProps(spec, err, { sk, unknown = err }) {
 		if (!SIDE.has(fit?.side)) err(`${at}.side must be "l" or "r", got ${fmt(fit?.side)}`);
 		if (!spec.anchors?.[fit?.anchor]) err(`${at}.anchor "${fit?.anchor}" is not in spec.anchors${didYouMean(String(fit?.anchor), Object.keys(spec.anchors ?? {}))}`);
 		const e = fit?.effector;
-		if (e?.prop !== undefined) { if (!spec.props?.[e.prop]?.points?.[e.point]) err(`${at}.effector ${e.prop}.${e.point} is not a point of spec.props`); }
+		if (e?.prop !== undefined) {
+			const p = spec.props?.[e.prop];
+			if (!p) err(`${at}.effector.prop "${e.prop}" is not in spec.props${didYouMean(String(e.prop), Object.keys(spec.props ?? {}))}`);
+			else if (e.point !== "origin" && !p.points?.[e.point]) err(`${at}.effector ${e.prop}.${e.point} is not a point of spec.props.${e.prop} (points: ${[...Object.keys(p.points ?? {}), "origin"].join(", ")})`);
+		}
 		else if (Array.isArray(e?.joints)) e.joints.forEach(j => boneOk(err, sk, `${at}.effector`, j));
 		else err(`${at}.effector must be { prop, point } or { joints: [bone, ...] }`);
 		if (fit?.offset !== undefined && !isVec3(fit.offset)) err(`${at}.offset must be [x, y, z]`);

package/src/motion3/compiler/validate.js

@@ -1,14 +1,29 @@
 // Strict motion spec validation with exact messages, run before every compile through the
 // pipeline (after skills expand, with open parameters at a trial value). Every problem found is
-// listed at once, one per line, so the agent fixes them in one edit.
+// listed at once, one per line (problems that differ only in their first index share a line), so the
+// agent fixes them in one edit.
 import { VEC_CHANNELS, POLE_CHANNELS, NUM_CHANNELS, MAP_CHANNELS, FINGER_PRESETS, rangeOf, CONVENTIONS, didYouMean, suggestField, isVec3, fmt } from "./vocab.js";
 import { validateParts } from "./validate-parts.js";
 import { SPEC_FIELDS, KEY_FIELDS } from "../schema/fields.js";
-const MAX_ERRORS = 12;
+const MAX_ERRORS = 12, MAX_FOUND = 60;
+
+/**
+ * Problems that differ only in their first index (and its key frame) said once: "objects.box.keys[0].rot must be
+ * ..." and keys[3] with the same words become "objects.box.keys[0,3].rot must be ...", so every problem fits one answer.
+ */
+function mergeProblems(lines) {
+	const groups = new Map();
+	for (const line of lines) {
+		const m = /\[(\d+)\]( \(f(\d+)\))?/.exec(line), key = m ? `${line.slice(0, m.index)}[#]${m[2] ? " (f#)" : ""}${line.slice(m.index + m[0].length)}` : line;
+		if (!groups.has(key)) groups.set(key, { line, idx: [], fs: [] });
+		if (m) { groups.get(key).idx.push(m[1]); if (m[3]) groups.get(key).fs.push(`f${m[3]}`); }
+	}
+	return [...groups.entries()].map(([key, g]) => (g.idx.length > 1 ? key.replace("[#]", `[${g.idx.join(",")}]`).replace(" (f#)", ` (${g.fs.join(", ")})`) : g.line));
+}
 
 
 /** Channels other than the body's own: hinge channels, visible and level channels (C15), channels a check names, *_vis switches, spec.channels. */
-function customChannels(spec) {
+export function customChannels(spec) {
 	const out = new Set(spec.channels ?? []);
 	for (const o of Object.values(spec.objects ?? {})) for (const ch of [o?.channel, o?.visible, o?.level]) if (typeof ch === "string" && ch) out.add(ch);
 	const c = spec.checks ?? {};
@@ -88,15 +103,18 @@ function validateKeys(spec, err, frames, unknown, past = "") {
 }
 
 /**
- * Throws MOTION_SPEC_INVALID listing every problem; scene objects are checked when given.
+ * Throws MOTION_SPEC_INVALID listing every problem (problems: ones found before, listed first); scene objects are
+ * checked when given.
  * lenient (a saved take compiled again, take-source.js) ignores unknown fields.
  */
-/** spec.flow: false, or { smooth?: boolean, lag?: false | 0..6 frames | { spine?, head?, arms? } } (channels.js). */
+/** spec.flow: false, or { smooth?: boolean, lag?: false | 0..6 frames | { spine?, head?, arms? }, overlap?: boolean | 0..2 } (channels.js, overlap.js). */
 function validateFlow(flow, err, unknown) {
 	if (flow === undefined || flow === false) return;
-	if (!flow || typeof flow !== "object" || Array.isArray(flow)) return err(`spec.flow must be false or { smooth?, lag? }, got ${fmt(flow)}`);
-	for (const k of Object.keys(flow)) if (k !== "smooth" && k !== "lag") unknown(`spec.flow has unknown field "${k}" (fields: smooth, lag)`);
+	if (!flow || typeof flow !== "object" || Array.isArray(flow)) return err(`spec.flow must be false or { smooth?, lag?, overlap? }, got ${fmt(flow)}`);
+	for (const k of Object.keys(flow)) if (!["smooth", "lag", "overlap"].includes(k)) unknown(`spec.flow has unknown field "${k}" (fields: smooth, lag, overlap)`);
 	if (flow.smooth !== undefined && typeof flow.smooth !== "boolean") err(`spec.flow.smooth must be true or false, got ${fmt(flow.smooth)}`);
+	const o = flow.overlap;
+	if (o !== undefined && typeof o !== "boolean" && !(Number.isFinite(o) && o >= 0 && o <= 2)) err(`spec.flow.overlap must be true, false or a scale 0..2, got ${fmt(o)}`);
 	const frames = v => Number.isFinite(v) && v >= 0 && v <= 6, lag = flow.lag, LAG = "false, 0..6 frames or { spine?, head?, arms? }";
 	if (lag === undefined || lag === false || frames(lag)) return;
 	if (!lag || typeof lag !== "object" || Array.isArray(lag)) return err(`spec.flow.lag must be ${LAG}, got ${fmt(lag)}`);
@@ -106,8 +124,8 @@ function validateFlow(flow, err, unknown) {
 	}
 }
 
-export function validateSpec(spec, { sk, scene, lenient = false } = {}) {
-	const errors = [], err = m => { if (errors.length < MAX_ERRORS) errors.push(m); }, unknown = lenient ? () => {} : err;
+export function validateSpec(spec, { sk, scene, lenient = false, problems = [] } = {}) {
+	const errors = [...problems], err = m => { if (errors.length < MAX_FOUND) errors.push(m); }, unknown = lenient ? () => {} : err;
 	if (!spec || typeof spec !== "object") throw new Error("MOTION_SPEC_INVALID: spec must be an object");
 	if (spec.schema !== "cozyclay.motion-spec.v1") err(`spec.schema must be "cozyclay.motion-spec.v1", got ${fmt(spec.schema)}`);
 	for (const k of Object.keys(spec)) if (!SPEC_FIELDS.includes(k)) unknown(`spec.${k} is not a spec field${didYouMean(k, SPEC_FIELDS)} (fields: ${SPEC_FIELDS.join(", ")})`);
@@ -118,5 +136,7 @@ export function validateSpec(spec, { sk, scene, lenient = false } = {}) {
 	const past = Number.isInteger(frames) ? pastEndAdvice(spec, frames) : "";
 	validateKeys(spec, err, Number.isInteger(frames) ? frames : 20000, unknown, past);
 	validateParts(spec, err, { sk, scene, frames: Number.isInteger(frames) ? frames : 20000, lenient, unknown, past });
-	if (errors.length) throw new Error(`MOTION_SPEC_INVALID: ${errors.join("\n")}${errors.length >= MAX_ERRORS ? "\n(more problems not listed)" : ""}`);
+	if (!errors.length) return;
+	const lines = mergeProblems(errors), more = lines.length > MAX_ERRORS || errors.length >= MAX_FOUND;
+	throw new Error(`MOTION_SPEC_INVALID: ${lines.slice(0, MAX_ERRORS).join("\n")}${more ? `\n(${lines.length > MAX_ERRORS ? `${lines.length - MAX_ERRORS}` : "more"}${errors.length >= MAX_FOUND ? "+" : ""} more problems not listed)` : ""}`);
 }