cozyclay 3.0.0 → 3.0.2

package/src/motion3/free-motion.js

@@ -4,10 +4,14 @@
 //         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? } or a list   from where it is at frame `at` it drops straight down
-//         under gravity (G m/s^2, no tumbling) 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), bounces at most once (bounce:
-//         the restitution 0..0.6, default 0.25, never higher than BOUNCE_MAX m) and rests there.
+//   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.
@@ -18,13 +22,16 @@
 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 } from "./compiler/math.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 BOUNCE = 0.25;
+/** A support's top may sit this far above the lowest point of what rests on it (m). */
+export const 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. */
@@ -36,14 +43,14 @@ const restOf = (scene, id) => scene?.objects?.[id] ?? groupsOf(scene)[id] ?? nul
 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) {
+export 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]));
+export 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]; };
+export 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) {
@@ -76,9 +83,31 @@ export function landingOf(spec, scene, id, start, onto = null) {
 	return { ...best, h: Math.max(0, low - best.top) };
 }
 
-/** A fall from root pose `start` at (mapped) frame t0: its timing, its pose at a frame, where it rests. */
-function fallPlan(spec, scene, id, start, t0, fall, fps) {
-	const land = landingOf(spec, scene, id, start, fall.onto ?? null), h = land.h, tl = Math.sqrt(2 * h / G);
+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 => {
@@ -157,11 +186,21 @@ export function beforeGrab(ctx, id, o, f, grab) {
 	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. */
-export function afterRelease(ctx, id, o, f, release, releasePose) {
+/**
+ * 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
-	return events.length ? walk(events, f, releasePose, planner(ctx, id), false) : null;
+	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;
+}
+
+/** True when carry entry o falls at or after its release (absolute frame; afterRelease then moves it). */
+export function fallsAfter(ctx, o, release) {
+	const map = ctx.timeMap ?? (f => f);
+	return fallsOf(o).some(fl => map(fl.at) >= release);
 }
 
 /** The falls of entry `id` as planned under the current time map, for readers (timeline, tests): [{ t0, land, end, h, support, top }]. */

package/src/motion3/object-keys.js

@@ -4,7 +4,8 @@
 //   between keys    a cubic Hermite on pos and the same in rotation-vector space on rot (squad
 //                   like), Catmull-Rom tangents through inner keys, zero at the first and last key
 //   around the span the hand blends from the plain carry into the keyed span over KEY_BLEND frames
-//                   (inside grab..release; smoothstep), so nothing jumps
+//                   (inside grab..release; smoothstep), so nothing jumps; keys that start within KEY_BLEND frames
+//                   of the grab with a grip off where the hand is turn the hand onto it before (holdHook approach)
 //   the object leads the hand: compile.js asks holdHook for the palm frame the keys put the grip
 //                   at, palm = key o attach^-1, and pose.js solves the hand to it (compiler/hold.js)
 // The object itself is still drawn in the hand (object-pose.js): the residual is what the arm
@@ -20,11 +21,14 @@ import { polePlan, smoothPath, smoothed } from "./hold-plan.js";
 import { secondGrip, secondHold, gripGate } from "./second-hand.js";
 import { SIDES } from "./compiler/pose.js";
 import { chooseGrip, between, thinBody } from "./grip-choice.js";
+import { graspedBy } from "./compiler/socket-grip.js";
 
 /** Frames over which the hand blends into and out of the keyed span. */
 export const KEY_BLEND = 8;
 // the frames a hand takes to turn into a chosen grip before its grab and out of it after its release (grip-choice.js)
 const GRAB_EASE = 12;
+// how far (m, deg) the grip keys put the hand on at the grab may be from where the reach brought it before the hand turns onto it first
+const OFF_GRIP = { m: 0.01, deg: 5 };
 
 const smooth = x => x * x * (3 - 2 * x);
 /** [grab, release] in absolute frames of `out` (object-pose.js spanOf, kept here to stay out of its import cycle). */
@@ -108,8 +112,8 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	if (!held.length) return null;
 	const palmOf = (o, s) => carriedPose(sk, spec, s, { prop: o.prop }), attached = new WeakMap(), attaching = new Set();
 	const restAt = (id, f) => ctx.restingAt?.(id, f) ?? scene?.objects?.[id] ?? groupsOf(scene)[id];
-	// a keyed carry of a thin body (a cup, a can, a bar) whose grip is free (no at/along, no orient: false, no keyed wrist at
-	// the grab) keeps the grip its keyed path holds most comfortably (grip-choice.js), solved on the plain frames with the
+	// a keyed carry of a thin body (a cup, a can, a bar) whose grip is free (no at/along, no orient: false, no grasp fit, no keyed
+	// wrist at the grab) keeps the grip its keyed path holds most comfortably (grip-choice.js), solved on the plain frames with the
 	// body read at rest; a box keeps the grip grip.js gives it at the grab
 	const choices = new WeakMap(), mapped = f => (out.timeMap ? Math.round(out.timeMap(f)) : f);
 	// chosen once per compile (the first bake): the fixes' rebakes move the body a little, the carry's keys not at all
@@ -118,7 +122,7 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 		const cache = choices.get(out), o = spec.objects[id], k = spec.props?.[o.prop]?.hand, grab = spanIn(out, o)[0], b = out.baked ?? {};
 		if (cache.has(id)) return cache.get(id);
 		cache.set(id, null);
-		const free = k && o.at === undefined && o.along === undefined && (o.grab !== undefined || !scene?.objects?.[id]) && thinBody(scene, id) && !(spec.fits ?? []).some(fit => fit.side === k && fit.orient === false)
+		const free = k && o.at === undefined && o.along === undefined && (o.grab !== undefined || !scene?.objects?.[id]) && thinBody(scene, id) && !(spec.fits ?? []).some(fit => fit.side === k && fit.orient === false) && !graspedBy(spec, scene, id, k)
 			&& !["wtwist", "wflex"].some(ch => Math.abs(b[`${ch}_${k}`]?.[grab] ?? 0) > 1e-3)
 			// keys that start after the grab: the body rides the hand from where it rests, which only today's grip meets exactly
 			&& mapped(Math.min(...o.keys.map(key => key.f))) <= grab;
@@ -203,6 +207,33 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 		const h = heldAt(id, o, f);
 		return { w: 1, palm: h ? { pos: add(scale(grip.pos, 1 - h.w), scale(h.palm.pos, h.w)), R: between(grip.R, h.palm.R, h.w) } : grip, measure, pole };
 	};
+	// keys that lead from the grab frame, or from fewer than KEY_BLEND frames after it, put the hand on their grip at once (or
+	// within those frames: palm = first key o attach^-1). Where that grip is not where the hand would be at the first key (an
+	// at/along offset of the agent's choosing: bench session cb2503b5's cup, 13.6 cm in the grab frame; keys two frames after
+	// the grab: 7146050f's box), the hand turns onto it over the GRAB_EASE frames up to the first key instead, as onto a chosen
+	// grip (gripAround): before the grab with the object at rest, after it carrying the object there. A grip within OFF_GRIP
+	// of where the hand would be changes nothing.
+	const offGrips = new WeakMap();
+	const offGrip = (id, o, grip) => {
+		if (!offGrips.has(out.baked)) offGrips.set(out.baked, new Map());
+		const cache = offGrips.get(out.baked), had = cache.get(id);
+		if (had && had.map === out.timeMap) return had.off;
+		attaching.add(id);
+		let palm;
+		try { palm = palmOf(o, solvePlain(Math.max(spanIn(out, o)[0], Math.round(curveIn(out, id).t[0]))).s); } finally { attaching.delete(id); }
+		const turn = relative(palm, grip).R, deg = Math.acos(Math.min(1, Math.max(-1, (turn[0][0] + turn[1][1] + turn[2][2] - 1) / 2))) * 180 / Math.PI;
+		const off = Math.hypot(...sub(grip.pos, palm.pos)) > OFF_GRIP.m || deg > OFF_GRIP.deg;
+		cache.set(id, { map: out.timeMap, off });
+		return off;
+	};
+	const approach = (id, o, f) => {
+		const curve = curveIn(out, id), [grab, release] = spanIn(out, o), t0 = Math.max(grab, Math.round(curve.t[0]));
+		if (!(f < t0 && f >= t0 - GRAB_EASE) || t0 - grab >= KEY_BLEND || t0 > release) return null;
+		const grip = compose(keyedPose(curve, t0), invert(attach(id)));
+		if (!offGrip(id, o, grip)) return null;
+		const w = smooth(1 - (t0 - f) / GRAB_EASE);
+		return w > 1e-3 ? { w, palm: grip, measure: s => palmOf(o, s), pole: planOf(id, o).get(t0) } : null;
+	};
 	// a release within KEY_BLEND frames of the last key: the hands finish easing out of the keys after it (weight from the last
 	// key), the holding hand from the palm they gave it at the release (the object stays where it was let go), each hand with
 	// the elbow pole (and the second hand the roll) planned for the release frame
@@ -217,7 +248,7 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	// the hand that holds a keyed carry follows its keys
 	const lead = (k, f, s, c) => {
 		for (const [id, o] of held) {
-			const pre = spec.props?.[o.prop]?.hand === k ? gripAround(id, o, f) ?? easeOut(id, o, f) : null;
+			const pre = spec.props?.[o.prop]?.hand === k ? gripAround(id, o, f) ?? approach(id, o, f) ?? easeOut(id, o, f) : null;
 			if (pre) return pre;
 			const h = spec.props?.[o.prop]?.hand === k ? heldAt(id, o, f) : null;
 			if (h) return { ...h, pole: planOf(id, o).get(f) };

package/src/motion3/object-pose.js

@@ -14,7 +14,9 @@
 //   f < grab              the scene pose
 //   grab <= f <= release  follows the prop's hand; without at/along it keeps the transform it had
 //                         against the palm axes at grab (no jump); at/along pin an offset (a group: its root, C15)
-//   f > release           frozen at the release pose
+//   f > release           frozen at the release pose; let go over a body that moves on its own (a seat of a truck the spec
+//                         drives with keys, a hinged lid), it rides that body's mover from the release on, keeping its world
+//                         pose at the release (riderOf): a lighter put down in the cab leaves with the truck
 //   no grab: in hand from frame 0; no release: in hand to the end (PR #14 behaviour)
 //   keys (C14, object-keys.js): the object leads and the hand follows; the object is still drawn
 //                         in the hand, so what the hand cannot reach shows as a residual (QA)
@@ -29,7 +31,8 @@ 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 } from "./free-motion.js";
+import { isFree, freePoseAt, beforeGrab, afterRelease, fallsAfter, corners, topOf, under, TOUCH } from "./free-motion.js";
+import { add } from "./compiler/math.js";
 
 /**
  * Body ids that make up `id` in a motionScene: [id] for a body (plus any bodies parented under
@@ -68,7 +71,7 @@ export function spanOf(out, o) {
 /** Without at/along a grabbed body, and a group, keeps its grab-frame palm offset; at/along pin one (a kit root, C15). */
 const keepsOffset = (scene, id, o) => o.at === undefined && o.along === undefined && ((!scene?.objects?.[id] && !!groupsOf(scene)[id]) || o.grab !== undefined);
 
-const solved = new WeakMap(), poses = new WeakMap();
+const solved = new WeakMap(), poses = new WeakMap(), riders = new WeakMap();
 
 /** What free-motion.js reads of a compile result: the spec, the scene and the time map. */
 const freeCtx = out => ({ spec: out.ctx.spec, scene: out.ctx.scene, timeMap: out.timeMap });
@@ -84,8 +87,36 @@ export function restingAt(out, id, f) {
 	return root && (mover === id ? root : compose(root, relative(restPose(scene, mover), restPose(scene, id))));
 }
 
-/** The solved frame at absolute f: out.frames, or solved once on demand outside a window. */
-function frameAt(out, f) {
+/**
+ * The spec.objects key a carry `id` (entry o) rides after its release: the key that moves the highest body under the
+ * record's centre at the release frame, when that key moves on its own (keys, a fall or a hinge; never a hand or a follow)
+ * and is not the record itself. null when the carry falls after its release, is never let go, or nothing under it moves.
+ */
+export function riderOf(out, id) {
+	if (!riders.has(out)) riders.set(out, new Map());
+	const cache = riders.get(out);
+	if (cache.has(id)) return cache.get(id);
+	const { spec, scene } = out.ctx, o = spec.objects?.[id], rest = restPose(scene, id), parts = partsOf(scene, id);
+	let best = null;
+	if (isCarried(o) && o.release !== undefined && rest && parts.length) {
+		const release = spanOf(out, o)[1];
+		if (release < out.frameCount - 1 && !fallsAfter(freeCtx(out), o, release)) {
+			const at = carriedAt(out, id, o, release), pts = parts.flatMap(p => corners({ ...compose(at, relative(rest, scene.objects[p])), half: scene.objects[p].half }));
+			const low = Math.min(...pts.map(p => p[1])), c = pts.reduce((a, p) => add(a, p), [0, 0, 0]).map(v => v / pts.length);
+			for (const [k, body] of Object.entries(scene.objects)) {
+				const mover = parts.includes(k) ? null : moverOf(spec, scene, k), entry = spec.objects?.[mover];
+				if (!mover || mover === id || isCarried(entry) || isFollow(entry)) continue;
+				const box = { ...objectPoseAt(out, k, release), half: body.half }, top = topOf(box);
+				if (under(box, c) && top <= low + TOUCH && (!best || top > best.top)) best = { mover, top };
+			}
+		}
+	}
+	cache.set(id, best?.mover ?? null);
+	return best?.mover ?? null;
+}
+
+/** The solved frame at absolute f: out.frames, or solved once on demand outside a window (or ahead of the frame being solved). */
+export function frameAt(out, f) {
 	const own = out.frames[f - (out.f0 ?? 0)];
 	if (own) return own;
 	if (!solved.has(out)) solved.set(out, new Map());
@@ -127,8 +158,10 @@ export function rootPoseAt(out, id, f, now = null) {
 	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)) : null;
+		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;
 		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)); }
 		return now && g === f ? carriedOn(out, id, o, f, now.s) : carriedAt(out, id, o, g);
 	}
 	if (!rest) return null;

package/src/motion3/people.js

@@ -0,0 +1,82 @@
+// The other people in a compile: every other character with an installed take v3, sampled once per take frame into
+// world joint positions (the take's local rotations by FK, at the character's stage placement, as playback draws it).
+// scene.people[id] = { name, rig, frames, names, P: Float64Array(frames * names.length * 3) } (scene.js motionScene
+// leaves it out; commands/motion3.js adds it). QA measures the compiled body against theirs (qa/people-checks.js,
+// PERSON), an anchor can sit on one of their bones ({ kind: "person" }, compiler/anchors.js) and a ref can name one
+// (person:<id>.<Bone>, refs.js). Frames are timeline frames; past a take's end its last frame holds.
+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";
+
+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
+const keep = v => Math.round(v * 1e5) / 1e5;
+
+/** World joints of an installed take at a placement { position, yaw }, every frame (cached per take and placement). */
+function sampleTake(take, placement) {
+	const key = JSON.stringify(placement), hit = sampled.get(take);
+	if (hit?.key === key) return hit.value;
+	const sk = skeletonFor(take.rig), B = take.bones.length, n = take.frameCount, names = sk.names, J = names.length;
+	const order = names.map(name => take.bones.indexOf(name)), R = ry(placement.yaw), P = new Float64Array(n * J * 3);
+	for (let f = 0; f < n; f++) {
+		const quats = order.map(b => (b < 0 ? [0, 0, 0, 1] : Array.from(take.rot.subarray((f * B + b) * 4, (f * B + b) * 4 + 4))));
+		const s = fk(sk, quats, Array.from(take.hips.subarray(f * 3, f * 3 + 3)));
+		for (let j = 0; j < J; j++) P.set(add(placement.position, apply(R, s.P[j])).map(keep), (f * J + j) * 3);
+	}
+	const value = { rig: take.rig, frames: n, names, P };
+	sampled.set(take, { key, value });
+	return value;
+}
+
+/**
+ * scene.people for a compile of character `selfId`: characters = the cast ({ id, subject, model, x, y, z, rot, hidden }),
+ * takeOf(id) = its installed take v3 or nothing. Hidden characters and ones without a take are left out.
+ */
+export function peopleOf(characters, selfId, takeOf) {
+	const out = {};
+	for (const c of characters ?? []) {
+		if (!c || c.id === selfId || c.hidden) continue;
+		const take = takeOf(c.id);
+		if (take?.schema !== "cozyclay.take.v3" || !take.frameCount || !skeletonFor(take.rig)) continue;
+		out[c.id] = { name: c.subject || c.name || c.id, ...sampleTake(take, { position: [c.x ?? 0, c.y ?? 0, c.z ?? 0], yaw: c.rot ?? 0 }) };
+	}
+	return out;
+}
+
+/** The person's joint `bone` at timeline frame f as [x, y, z], or null (unknown person or bone). */
+export function personJoint(scene, id, bone, f) {
+	const p = scene?.people?.[id];
+	if (!p) return null;
+	const j = p.names.indexOf(resolveBone(skeletonFor(p.rig), bone).bone ?? "");
+	if (j < 0) return null;
+	const at = (Math.max(0, Math.min(p.frames - 1, Math.round(f))) * p.names.length + j) * 3;
+	return [p.P[at], p.P[at + 1], p.P[at + 2]];
+}
+
+/** The ids and names a person ref or anchor may name, for an error. */
+export const peopleList = scene => Object.entries(scene?.people ?? {}).map(([id, p]) => `${id} (${p.name})`).join(", ") || "none: no other character has an installed take";
+
+/**
+ * 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.
+ */
+export function keptPeople(scene, spec) {
+	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]));
+	};
+	const walk = (v, key) => {
+		if (typeof v === "string") { const m = /^person:([^.]+)(?:\.(.+))?$/.exec(v); if (m && (m[2] || key === "from")) keep(m[1], m[2] ?? "Hips"); }
+		else if (Array.isArray(v)) v.forEach(x => walk(x));
+		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 (!want.size) return null;
+	return Object.fromEntries([...want].map(([id, bones]) => {
+		const p = scene.people[id], names = [...bones], J = p.names.length, P = [];
+		for (let f = 0; f < p.frames; f++) for (const b of names) { const i = (f * J + p.names.indexOf(b)) * 3; P.push(p.P[i], p.P[i + 1], p.P[i + 2]); }
+		return [id, { name: p.name, rig: p.rig, frames: p.frames, names, P }];
+	}));
+}

package/src/motion3/qa/checks.js

@@ -58,11 +58,15 @@ export function generalChecks(sk, out, opts = {}) {
 		for (const [nm, p, r] of probes) { const d = headDepth(sk, s, p) + r; if (d > L.headAllow) push("FACE", `${nm} into head`, f, d, L.headAllow); }
 		if (segDist(s.P[I.LeftLeg], s.P[I.LeftFoot], s.P[I.RightLeg], s.P[I.RightFoot]) < 0.1 + L.self) push("SELF", "shins touch", f, 0.1, 0.1);
 		if (segDist(s.P[I.LeftUpLeg], s.P[I.LeftLeg], s.P[I.RightUpLeg], s.P[I.RightLeg]) < 0.135 + L.self) push("SELF", "thighs overlap", f, 0.135, 0.135);
+		const tilted = norm(sub(s.P[I.Spine], s.P[I.Hips]))[1] < 0.5;
 		for (const S of ["Left", "Right"]) {
 			const th = s.P[I[`${S}UpLeg`]], kn = s.P[I[`${S}Leg`]], an = s.P[I[`${S}Foot`]];
 			const bend = angle(sub(kn, th), sub(an, kn));
-			// the foot's heading on the ground; the toe sits below the ankle, which must not count
-			const toeDir = sub(s.P[I[`${S}ToeBase`]], an); toeDir[1] = 0;
+			// the foot's heading on the ground; the toe sits below the ankle, which must not count. With the pelvis turned past
+			// 60 deg from upright (a flip, a cartwheel, lying) the ground says nothing about the leg: the foot's front is the toe
+			// across the shin, which an upright leg reads the same way
+			let toeDir = sub(s.P[I[`${S}ToeBase`]], an);
+			if (tilted) { const shin = norm(sub(an, kn)); toeDir = sub(toeDir, scale(shin, dot(toeDir, shin))); } else toeDir[1] = 0;
 			const mid = sub(kn, [(th[0] + an[0]) / 2, (th[1] + an[1]) / 2, (th[2] + an[2]) / 2]);
 			if (bend > 3 && dot(mid, toeDir) < -0.002) push("KNEE", `${S} knee bends backward`, f, bend, 0);
 			// a knee folded past its stop puts the shin in the thigh (the solver stops at KNEE_STOP)

package/src/motion3/qa/hints-contact.js

@@ -8,6 +8,7 @@ import { kneeFoldHint, kneeWhy } from "./hints-knee.js";
 import { objectFrame } from "../compiler/anchors.js";
 import { bodyFor, bodyNormal, limbDepth } from "../body.js";
 import { footProbes, footDepths } from "./foot-checks.js";
+import { personCapsules } from "./people-checks.js";
 
 const MARGIN = 0.003;
 /** The most a foot hint lifts a foot over a body it went into through a side (a stair riser); higher, it backs out. */
@@ -19,7 +20,7 @@ function anchorFix(X, name, f, delta, k) {
 	const a = X.spec.anchors?.[name], path = field => `/anchors/${name}/${field}`;
 	if (a?.kind === "world") return { path: path("p"), delta };
 	if (a?.kind === "body") return { path: path("p"), delta: apply(ry(-(X.fr(f).c.yaw ?? 0)), delta) };
-	if (["bone", "segment", "prop"].includes(a?.kind)) return { path: path("offset"), delta };
+	if (["bone", "segment", "prop", "person"].includes(a?.kind)) return { path: path("offset"), delta };
 	if (a?.kind !== "object") return undefined;
 	// local is in the object's axes where that hand's target read it (anchors.js objectFrame)
 	const fr = X.fr(f), o = objectFrame(X.out.ctx, a, name, { ...fr, diag: { ...fr.diag, frame: f } }, k);
@@ -105,6 +106,21 @@ export const contactHints = {
 		}
 		return r;
 	},
+	/** PERSON "<part> x person:<id>": the part moves out of the other person's deepest capsule, along the line between their nearest points. */
+	PERSON(X, g) {
+		const [, part, id] = /^(\S+) x person:(.+)$/.exec(g.subject) ?? [], mine = capsule(part), p0 = X.out?.ctx?.scene?.people?.[id];
+		if (!mine || !p0) return null;
+		const f = g.worstFrame, { s } = X.fr(f), pts = segPoints(s.P[X.I[mine[1]]], s.P[X.I[mine[2]]]);
+		const near = ([other, C, D, q]) => {
+			const cd = sub(D, C), dd = Math.max(dot(cd, cd), 1e-12);
+			return pts.map(p => { const at = add(C, scale(cd, clamp(dot(sub(p, C), cd) / dd, 0, 1))); return { other, p, q: at, depth: mine[3] + q - len(sub(p, at)) }; })
+				.reduce((m, x) => (x.depth > m.depth ? x : m));
+		};
+		const hit = personCapsules(p0, f).map(near).reduce((m, x) => (x.depth > m.depth ? x : m));
+		const away = len(sub(hit.p, hit.q)) > 1e-6 ? norm(sub(hit.p, hit.q)) : norm([hit.p[0] - hit.q[0] || 1, 0, hit.p[2] - hit.q[2]]);
+		const r = moveHint(X, part, f, scale(away, g.worst - g.limit + MARGIN), ` (out of ${p0.name}'s ${hit.other})`);
+		return { ...r, hint: `${r.hint}; or, for a touch you mean, checks.allow [{ part: "${part}", object: "person:${id}", depth: ${m3(g.worst + MARGIN)} }]` };
+	},
 	CLEARANCE(X, g) {
 		const k = (X.spec.checks?.clearance ?? []).find(c => g.subject.startsWith(`${c.name}:`));
 		return k && boxHint(X, g, k.part, k.object, k.min - g.worst + MARGIN);

package/src/motion3/qa/index.js

@@ -1,13 +1,15 @@
 // Motion QA entry: general checks on every take, the checks the spec declares, the objects it
-// moves (object-checks.js), its goals (goals.js) and the style checks it opted into by naming
+// moves (object-checks.js), the other people in the scene (people-checks.js, PERSON), its goals (goals.js) and the style checks it opted into by naming
 // their limit (style.js; otherwise style is measured, not judged: observeMotion). Groups are
-// ranked by severity.js.
+// ranked by severity.js. total counts frame-level issues (a goal held on "all" frames adds one per failing frame); problems
+// counts the groups, which is what a person reads (src/qa-label.js).
 import { generalChecks, QA_LIMITS } from "./checks.js";
 import { styleChecks, floatChecks } from "./style.js";
 import { specChecks } from "./spec-checks.js";
 import { objectChecks } from "./object-checks.js";
 import { goalChecks } from "./goals.js";
 import { wristIssues } from "./wrist-checks.js";
+import { peopleChecks } from "./people-checks.js";
 import { explainGroups } from "./explain.js";
 import { LOW_IS_BAD, groupKey, rankGroups } from "./severity.js";
 
@@ -34,9 +36,9 @@ export function runMotionQa(sk, out, spec, opts = {}) {
 	const checks = spec.checks ?? {}, goals = goalChecks(out, spec.goals ?? []);
 	const issues = [...generalChecks(sk, out, { allow: checks.allow, limits: checks.limits, mouthPoints: checks.mouthPoints }), ...specChecks(out, checks),
 		...objectChecks(sk, out, spec), ...floatChecks(out, checks),
-		...styleChecks(sk, out, checks, { ...QA_LIMITS, ...checks.limits }), ...wristIssues(sk, out), ...goals.issues];
+		...styleChecks(sk, out, checks, { ...QA_LIMITS, ...checks.limits }), ...wristIssues(sk, out), ...peopleChecks(sk, out, checks), ...goals.issues];
 	if (out.f0) for (const i of issues) i.frame += out.f0;
 	const groups = summarizeIssues(issues);
 	if (opts.explain !== false) explainGroups(sk, out, spec, groups, { userSpec: opts.userSpec });
-	return { ok: issues.length === 0, total: issues.length, ...(spec.goals ? { goals: goals.results } : {}), groups };
+	return { ok: issues.length === 0, total: issues.length, problems: groups.length, ...(spec.goals ? { goals: goals.results } : {}), groups };
 }

package/src/motion3/qa/people-checks.js

@@ -0,0 +1,37 @@
+// PERSON: the compiled body against the other people in the scene (people.js), capsule against capsule (geometry.js
+// CAPSULES on both bodies, at the same timeline frame). "<part> x person:<id>": how deep the part goes into the
+// other body (its deepest capsule there; the hint names which), past QA_LIMITS.allow. An intended touch (a push, a hand
+// on a shoulder) is allowed like any contact: checks.allow [{ part, object: "person:<id>", depth }].
+import { segDist, CAPSULES } from "./geometry.js";
+import { allowance, QA_LIMITS } from "./checks.js";
+import { dist } from "../compiler/math.js";
+
+/** Two bodies whose hips are this far apart (m) cannot touch: a body is under 1 m from its hips to any skin. */
+const APART = 2.2;
+
+/** The person's capsule endpoints at timeline frame f: [part, A, B, r] with the joints read from P. */
+export function personCapsules(p, f) {
+	const at = Math.max(0, Math.min(p.frames - 1, f)) * p.names.length, J = name => { const j = p.names.indexOf(name), i = (at + j) * 3; return [p.P[i], p.P[i + 1], p.P[i + 2]]; };
+	return CAPSULES.map(([part, a, b, r]) => [part, J(a), J(b), r]);
+}
+
+/** PERSON issues of compile result out (frames indexed in out.frames; reported at their absolute frame by qa/index.js). */
+export function peopleChecks(sk, out, checks = {}) {
+	const people = Object.entries(out.ctx?.scene?.people ?? {}), issues = [];
+	if (!people.length) return issues;
+	const I = sk.index, f0 = out.f0 ?? 0, lim = { ...QA_LIMITS, ...checks.limits }.allow;
+	out.frames.forEach(({ s }, i) => {
+		const f = i + f0, mine = CAPSULES.map(([part, a, b, r]) => [part, s.P[I[a]], s.P[I[b]], r]);
+		for (const [id, p] of people) {
+			// a saved take keeps only the joints its anchors read (people.js keptPeople): no body to collide with there
+			if (!CAPSULES.every(([, a, b]) => p.names.includes(a) && p.names.includes(b))) continue;
+			const theirs = personCapsules(p, f), hips = theirs.find(c => c[0] === "hips")[1];
+			if (dist(s.P[I.Hips], hips) > APART) continue;
+			for (const [part, A, B, r] of mine) {
+				const depth = Math.max(...theirs.map(([, C, D, q]) => r + q - segDist(A, B, C, D))), allow = allowance(checks.allow, part, `person:${id}`) ?? lim;
+				if (depth > allow) issues.push({ kind: "PERSON", msg: `${part} x person:${id}`, frame: i, value: +depth.toFixed(4), limit: allow });
+			}
+		}
+	});
+	return issues;
+}

package/src/motion3/qa/style.js

@@ -10,7 +10,7 @@
 // See docs/motion-api-v3.1.md C13.
 import { add, sub, scale, len, dot, angle } from "../compiler/math.js";
 import { CAPSULES, segPoints, sdBox } from "./geometry.js";
-import { groundSole } from "./ground.js";
+import { groundSole, groundY } from "./ground.js";
 
 const SPEED_JOINTS = ["Hips", "Head", "LeftHand", "RightHand", "LeftFoot", "RightFoot", "LeftLeg", "RightLeg", "LeftForeArm", "RightForeArm"];
 const CORE = new Set(["Hips", "Head"]);
@@ -68,9 +68,12 @@ export function popChecks(sk, out, L, push) {
 	}
 }
 
-/** True when a declared support (checks.supports) carries the body at frame f. */
+/** Trunk capsules that rest a body on the floor (lying, sitting on it): within this of the floor, the floor carries it. */
+const FLOOR_REST = ["hips", "torso_lo", "torso_hi"], FLOOR_TOL = 0.04;
+/** True when the floor under the trunk or a declared support (checks.supports) carries the body at frame f. */
 function supported(out, f, supports) {
 	const { P } = out.frames[f].s, I = out.ctx.sk.index;
+	if (CAPSULES.some(([part, a, b, r]) => FLOOR_REST.includes(part) && Math.min(P[I[a]][1], P[I[b]][1]) - r < FLOOR_TOL)) return true;
 	return supports.some(sp => {
 		const box = out.objectsAt(f)[sp.object], cap = CAPSULES.find(c => c[0] === (sp.part ?? "hips"));
 		return box && cap && Math.min(...segPoints(P[I[cap[1]]], P[I[cap[2]]]).map(p => sdBox(p, box))) - cap[3] < (sp.tol ?? 0.04);
@@ -101,11 +104,18 @@ function balanceMargins(out, supports = []) {
 	});
 }
 
-/** Runs [a, b] (indexes of out.frames) with both soles 2 cm or more above the ground (ground.js) and no declared support. */
+/** True when a hand rests on the ground at frame f: its wrist or knuckles within HAND_DOWN of the ground under them. */
+const HAND_DOWN = 0.06;
+function handDown(out, f) {
+	const { P } = out.frames[f].s, I = out.ctx.sk.index;
+	return ["Left", "Right"].some(S => [`${S}Hand`, `${S}HandMiddle1`].some(j => I[j] !== undefined && P[I[j]][1] - groundY(out, f, P[I[j]]) < HAND_DOWN));
+}
+
+/** Runs [a, b] (indexes of out.frames) with both soles 2 cm or more above the ground (ground.js), no hand on it and no declared support. */
 function airRuns(out, supports = []) {
 	const n = out.frames.length, runs = [];
 	const air = out.frames.map((_, f) => !supported(out, f, supports)
-		&& ["Left", "Right"].every(S => { const sp = groundSole(out, f, S); return Math.min(sp.heel[1], sp.ball[1]) >= 0.02; }));
+		&& ["Left", "Right"].every(S => { const sp = groundSole(out, f, S); return Math.min(sp.heel[1], sp.ball[1]) >= 0.02; }) && !handDown(out, f));
 	for (let a = 0; a < n; a++) {
 		if (!air[a]) continue;
 		let b = a;

package/src/motion3/refs.js

@@ -4,6 +4,7 @@
 //   prop:<prop>.<point>                 a point of a held prop (spec.props; "origin" always exists)
 //   anchor:<name>                       a spec anchor, resolved as the compiler resolves it
 //   landmark:mouth                      the measured face landmark
+//   person:<id>.<Bone>                  another character's joint where its installed take has it (people.js)
 //   object:<id>[.center|.top|.base]     a body or a group (object-pose.js objectBoxesAt): the centre,
 //                                       top-face centre or bottom-face centre of the AABB of its
 //                                       part boxes' corners (default center)
@@ -17,8 +18,9 @@ import { bonePoint } from "./compiler/skeleton.js";
 import { didYouMean } from "./compiler/vocab.js";
 import { add, apply, sub, len } from "./compiler/math.js";
 import { sdBox } from "./qa/geometry.js";
+import { personJoint, peopleList } from "./people.js";
 
-const SYNTAX = { joint: "joint:<Bone>", bone: "bone:<Bone>", prop: "prop:<prop>.<point>", anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base]" };
+const SYNTAX = { joint: "joint:<Bone>", bone: "bone:<Bone>", prop: "prop:<prop>.<point>", anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base]", person: "person:<id>.<Bone>" };
 
 function parse(ref) {
 	const m = /^([a-z]+):(.+)$/s.exec(String(ref));
@@ -26,6 +28,7 @@ function parse(ref) {
 	const [, kind, rest] = m;
 	if (kind === "prop") { const [name, point] = rest.split("."); return { kind, name, point: point ?? "" }; }
 	if (kind === "object") { const o = /^(.+)\.(center|top|base)$/s.exec(rest); return { kind, name: o ? o[1] : rest, point: o ? o[2] : null }; }
+	if (kind === "person") { const dot = rest.lastIndexOf("."); return { kind, name: dot > 0 ? rest.slice(0, dot) : rest, point: dot > 0 ? rest.slice(dot + 1) : "" }; }
 	return { kind, name: rest, point: null };
 }
 
@@ -50,6 +53,7 @@ export function refPoint(out, f, ref) {
 		case "anchor": return out.ctx.spec.anchors?.[r.name] ? resolveAnchor(out.ctx, r.name, s, { ...diag, frame: f }, c) : null;
 		case "landmark": return sk.landmarks?.[r.name] ? bonePoint(s, sk.index.Head, sk.landmarks[r.name]) : null;
 		case "object": { const boxes = objectBoxesAt(out, r.name, f); return boxes ? boxesPoint(boxes, r.point) : null; }
+		case "person": return personJoint(out.ctx.scene, r.name, r.point, f);
 		default: return null;
 	}
 }
@@ -116,5 +120,10 @@ export function checkRef(spec, err, { sk, scene }, at, ref, kinds = REF_KINDS) {
 		if (r.name !== "mouth") err(`${tag}: the only landmark is "mouth"`);
 		return r.name === "mouth";
 	}
+	if (r.kind === "person") {
+		const ok = Boolean(personJoint(scene, r.name, r.point, 0));
+		if (!ok) err(`${tag}: no person "${r.name}" with joint "${r.point}" (people with an installed take: ${peopleList(scene)})`);
+		return ok;
+	}
 	return objectOk(err, scene, tag, r.name, { groups: true });
 }

package/src/motion3/scene.js

@@ -7,7 +7,8 @@
 // and scene.others (take-source.js), so the groups are rebuilt from the entries: groupsOf.
 // `others` lists the records with no box (an Empty, a light, an effect, a plane) by id with their
 // renderer and ancestors: a switch entry (C15) may name them, and a skill finds a kit's lit parts
-// there. A body that glows (record.glow) says so (`glow: true`).
+// there. A body that glows (record.glow) says so (`glow: true`); a record's grasp sockets (record.grasp,
+// ../object-grasp.js) ride along for the hand (sockets.js).
 import { objectSize } from "../object-size.js";
 import { mul, rx, ry, rz } from "./compiler/math.js";
 
@@ -50,11 +51,11 @@ export function motionScene(objects = []) {
 		if (!o || o.hidden) continue;
 		const size = objectSize(o), up = ancestorsOf(o, byId);
 		if (NO_BODY.has(o.renderer) || !(size.width > 0 && size.height > 0 && size.depth > 0)) {
-			others[o.id] = { renderer: o.renderer, ancestors: up.map(p => p.id) };
+			others[o.id] = { renderer: o.renderer, ancestors: up.map(p => p.id), ...(o.grasp ? { grasp: o.grasp } : {}) };
 			continue;
 		}
 		out[o.id] = { name: o.name, renderer: o.renderer, ...poseOf(o), half: [size.width / 2, size.height / 2, size.depth / 2],
-			ancestors: up.map(p => p.id), ...(up.length ? { ancestorPoses: up.map(poseOf) } : {}), ...(o.glow ? { glow: true } : {}) };
+			ancestors: up.map(p => p.id), ...(up.length ? { ancestorPoses: up.map(poseOf) } : {}), ...(o.glow ? { glow: true } : {}), ...(o.grasp ? { grasp: o.grasp } : {}) };
 	}
 	return { objects: out, groups: groupsOf({ objects: out }), others };
 }