cozyclay 3.0.0 → 3.0.1

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,7 +22,8 @@
 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;
@@ -76,9 +81,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 +184,15 @@ 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;
 }
 
 /** 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-pose.js

@@ -127,7 +127,7 @@ 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;
 		return now && g === f ? carriedOn(out, id, o, f, now.s) : carriedAt(out, id, o, g);
 	}

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/schema/fields.js

@@ -11,14 +11,14 @@ export const KEY_FIELDS = ["f", "set", "step", "src"];
 export const USE_FIELDS = ["skill", "args", "f0"];
 /** Anchor fields by anchor kind (besides `kind`). */
 export const ANCHOR_FIELDS = { world: ["p"], body: ["p"], bone: ["bone", "offset"], segment: ["from", "to", "t", "tMin", "offset", "reach"],
-	object: ["object", "local"], landmark: ["name"], prop: ["prop", "point", "offset"] };
+	object: ["object", "local"], landmark: ["name"], prop: ["prop", "point", "offset"], person: ["person", "bone", "offset"] };
 export const PROP_FIELDS = ["hand", "origin", "points"];
 export const FIT_FIELDS = ["side", "anchor", "effector", "offset", "orient"];
 /** spec.objects[id]: a hinge or a carry (a body or a group id), see C3; carry keys: C14; a switch (any record, C15) moves nothing; a follow (any record, C16) rides a point of the body; a free entry (C17) moves by keys and falls. */
 export const OBJECT_FIELDS = { hinge: ["pivot", "axis", "channel"], carry: ["prop", "at", "along", "visible", "level", "grab", "release", "keys", "fall"], switch: ["visible", "level"],
 	follow: ["follow", "offset", "aim", "visible", "level"], free: ["keys", "fall", "visible", "level"] };
-/** One spec.objects[id].fall entry (C17): the frame it starts to fall, what it lands on, how much it bounces. */
-export const FALL_FIELDS = ["at", "onto", "bounce"];
+/** One spec.objects[id].fall entry (C17): the frame it starts to fall, what it lands on, how much it bounces, whether it rolls to rest. */
+export const FALL_FIELDS = ["at", "onto", "bounce", "tumble"];
 /** One spec.objects[id].keys entry (C14): the held object's world pose at frame f; aim (+ roll) in place of rot (C16). */
 export const OBJECT_KEY_FIELDS = ["f", "pos", "rot", "aim", "roll", "lean"];
 export const WALK_FIELDS = ["type", "f0", "steps", "step", "period", "swing", "halfWidth", "lift", "heading", "turnDistance", "pelvisHigh", "pelvisLow", "firstStep", "armSwing", "vary"];
@@ -39,6 +39,6 @@ export const GOAL_FIELDS = ["name", "near", "above", "moved", "still", "speed",
 /** One motion.compile probes entry (C5): exactly one of distance | position. */
 export const PROBE_FIELDS = ["name", "distance", "position", "frames", "every"];
 /** Point reference kinds (C2, refs.js). */
-export const REF_KINDS = ["joint", "bone", "prop", "anchor", "landmark", "object"];
+export const REF_KINDS = ["joint", "bone", "prop", "anchor", "landmark", "object", "person"];
 /** motion.describe topics (C9); examples: whole specs that compile (schema/spec-examples.js). */
 export const DESCRIBE_TOPICS = ["essentials", "spec", "skills", "anchors", "props", "objects", "checks", "goals", "probes", "channels", "refs", "fix", "examples"];

package/src/motion3/schema/topics.js

@@ -64,7 +64,8 @@ export const NOTES = {
 		"More: topics anchors, props, objects, checks, goals, probes, channels, refs, fix, skills."],
 	anchors: ["An anchor is a named point a hand can go to: key w_<anchor>_l / w_<anchor>_r from 0 to 1 with armw_<side> 1 (the IK arm).",
 		"An anchor name may not end in _l or _r.", "object anchors (a body or a group; local in its own axes) follow the object where it is (hinges, carries): put the other hand on a carried object with one; the carrying hand's own anchor stays where it took it. prop anchors are a point of a prop the other hand holds.",
-		"segment with reach slides from t toward tMin until the arm reaches it."],
+		"segment with reach slides from t toward tMin until the arm reaches it.",
+		"person { person: <character id>, bone, offset? } is another character's joint where its installed take has it that frame (a hand on a shoulder, a push on the chest): install that character's take first; reachGrip on it allows the hand to touch that person."],
 	props: ["A prop is a set of points fixed to one hand, [d, l, n] along the palm axes; prop:<prop>.origin is the mean of its origin bones.",
 		"fits: the hand target moves so the effector (a prop point or the mean of joints), not the wrist, lands on the anchor.",
 		"A fit on a scene body also turns the hand about the forearm into a grip: a thin body (a can, a bar, a handle, a neck) across the palm, else thumb up; never past a comfortable forearm turn. A wrist you turn (wtwist/wflex) wins; fit.orient: false (reachGrip args.orient: false) turns it off.",
@@ -81,14 +82,15 @@ export const NOTES = {
 			+ "a left hand on a prop anchor of it turns with it; "
 			+ `the hand eases in and out over ${KEY_BLEND} frames. A REACH group "<id>: n cm off its keys" is what the hand could not reach; `
 			+ "output.observations.held measures every key as drawn (deg off the asked +Y, cm off pos, the drawn +Y, the rot an aim key used).",
-		"free { keys?, fall? } moves what nobody holds: keys at any frame; fall drops it at frame at under gravity onto the still top below (onto: that one; else the floor), "
-			+ "one small bounce (0: none). A carry falls before grab or after release.",
+		"free { keys?, fall? } moves what nobody holds: keys at any frame; fall drops it at frame at onto the still top below (onto: that one; else the floor) "
+			+ "to rest on a stable face, one small bounce (0: none). A carry falls before grab or after release.",
 		"A follow { follow: <ref>, offset?, aim?, visible?, level? } puts any record (an effect, a light, a part) on a body point every frame: "
 			+ "aim sets its +Y (an effect emits along it): up (default), face (forward), a direction or a ref (toward it); offset is metres along its axes after aim. It is no obstacle.",
 		"The editor's motion.keyObject writes one key from a drag (a hinge: its channel key)."],
 	checks: ["Each entry adds QA groups: contacts CONTACT, orient ORIENT, below BELOW, clearance CLEARANCE, appear APPEAR; supports mark where a part rests on an object (no FLOAT, no balance there); a foot on an object's top is on the ground without one.",
 		"when: a weight channel (active above 0.99) or [f0, f1]; clearance uses frames.", "Check points take joint:, prop: and anchor: only; goals and probes take every ref (topic refs).",
 		"allow excuses a body part inside an object up to depth; limits override the QA limits. Unnamed entries are named by place, contacts[0].",
+		"Other characters with an installed take are bodies too: PERSON \"<part> x person:<id>\" is a part inside that person; a touch you mean (a push, a hug) is allow { part, object: \"person:<id>\", depth }.",
 		"Speed, acceleration, knee bend and balance are style: measured in output.observations, not judged. Naming speedCore/speedLimb, accCore/accLimb, knee or balance in limits makes it a check (SPEED, ACC, KNEE, BALANCE). observations.near: each hand's and foot's nearest object and gap (< 0 inside), measured, not judged.",
 		"motion.qa { checks } replaces every check for a re-measure."],
 	goals: ["Exactly one of near (distance <= tol), above (a.y - b.y >= by), moved (an object's base moved at least by from the scene pose; any other point ref, e.g. prop:bat.tip, at least by from where it is at at[0], at: [f0, f1]), still (stays within tol, default 0.01 m, of where moved measures from) or speed (the point reaches by m/s).",
@@ -102,7 +104,7 @@ export const NOTES = {
 		"Flow (spec.flow, on by default): the spine, head, arm swing/bend and wrist carry their speed through a key (a small overshoot) and trail the body (spine 1, head 2, arms 3 frames; lag: { spine, head, arms } or a number); feet, root, hand targets, weights, poles, fingers and objects land on their keys on time. flow: false turns it off; { smooth: false } or { lag: false } one part.",
 		"w_<anchor>_<side> (0..1) weights a hand onto an anchor; the weights of one hand add up to at most 1.",
 		"Any other numeric channel must come from spec.channels, a hinge (objects.<id>.channel), a check's when or a visible switch; names ending _vis are visibility switches (shown above 0.5)."],
-	refs: ["A ref names a point: joint:/bone:<Bone>, prop:<prop>.<point>, anchor:<name>, landmark:mouth, object:<id>[.center|.top|.base].",
+	refs: ["A ref names a point: joint:/bone:<Bone>, prop:<prop>.<point>, anchor:<name>, landmark:mouth, object:<id>[.center|.top|.base], person:<character id>.<Bone> (another character's joint in its installed take).",
 		"object:<id> takes a body or a group (the box around its parts); in a distance a bare object:<id> means its surface.",
 		"Goals and probes take every kind; spec.checks keep joint:, prop: and anchor:."],
 	fix: [`spec.fix keys: ${FIX_KEYS.join(", ")}; false turns all off. output.fixed reports what each one changed.`,

package/src/motion3/schema/types.js

@@ -64,11 +64,12 @@ export const ANCHOR_TYPES = {
 	from: str("bone"), to: str("bone"), t: num("0 = from .. 1 = to", { default: 0.5 }), tMin: num("with reach: the lowest t to slide back to", { default: 0.15 }),
 	reach: side("slide toward `from` until this arm reaches"), object: str("scene object id"), local: ref("vec3", "point in the object's frame, m"),
 	name: { const: "mouth" }, prop: str("a prop held by the other hand"), point: str("a point of that prop, or origin"),
+	person: str("a character id"),
 };
 
 const palm = d => ref("vec3", `${d} [d, l, n] on the palm axes (d to the middle finger, l to the thumb side, n = d x l), m`);
 /** Fields an anchor of each kind must have. */
-export const ANCHOR_REQUIRED = { world: ["p"], body: ["p"], bone: ["bone"], segment: ["from", "to"], object: ["object"], landmark: ["name"], prop: ["prop", "point"] };
+export const ANCHOR_REQUIRED = { world: ["p"], body: ["p"], bone: ["bone"], segment: ["from", "to"], object: ["object"], landmark: ["name"], prop: ["prop", "point"], person: ["person", "bone"] };
 
 export const PROP_TYPES = {
 	hand: side(), origin: { type: "array", items: { type: "string" }, minItems: 1, description: "bones whose mean is the prop origin" },
@@ -85,17 +86,17 @@ export const FIT_TYPES = {
 const OBJECT_KEY_TYPES = { f: int(), pos: ref("vec3"), rot: { type: "array", items: { type: "number" }, minItems: 4, maxItems: 4, description: "quat x, y, z, w" },
 	aim: ref("vec3", "or rot: +Y dir"), roll: num("deg about aim"), lean: num("aim tilt", { minimum: 0, maximum: 45 }) };
 
-const FALL = { type: "object", properties: { at: int(), onto: str(), bounce: num(null, { default: 0.25, minimum: 0, maximum: 0.6 }) }, required: ["at"], additionalProperties: false };
+const FALL = { type: "object", properties: { at: int(), onto: str(), bounce: num(null, { default: 0.25, minimum: 0, maximum: 0.6 }), tumble: { type: "boolean" } }, required: ["at"], additionalProperties: false };
 /** A free entry's keys and fall (C17) are a carry's, at any frame: said once, not twice. */
 const AS_CARRY = { description: "as carry; keys at any frame" };
 export const FREE_TYPES = { keys: AS_CARRY, fall: AS_CARRY };
 
 export const OBJECT_TYPES = {
-	pivot: ref("vec3", "world hinge point, m"), axis: ref("vec3", "default [0, 1, 0]"), channel: str("angle channel, deg"),
-	prop: str("spec.props name: it rides that hand"), at: ref("vec3", "palm offset [d, l, n], m"), along: ref("vec3", "its +Y on the palm, fixed"),
-	visible: str("channel: shown > 0.5"), level: str("channel: strength 0..4"), grab: int("the hand takes it", { default: 0 }), release: int("let go (else the end)"),
+	pivot: ref("vec3", "world hinge point"), axis: ref("vec3", "default +Y"), channel: str("angle channel, deg"),
+	prop: str("spec.props name: it rides that hand"), at: ref("vec3", "palm offset [d, l, n]"), along: ref("vec3", "+Y on the palm, fixed"),
+	visible: str("channel: shown > 0.5"), level: str("channel: strength 0..4"), grab: int("hand takes it", { default: 0 }), release: int("let go (else end)"),
 	keys: { type: "array", items: { type: "object", properties: Object.fromEntries(OBJECT_KEY_FIELDS.map(f => [f, OBJECT_KEY_TYPES[f]])), required: ["f", "pos"], additionalProperties: false },
-		description: "world pose at f, in hand; the hand follows" },
+		description: "world pose at f; hand follows" },
 	fall: { ...FALL, description: "or a list; topic objects" },
 	follow: ref("ref"), offset: ref("vec3"), aim: { oneOf: [{ enum: ["face", "up"] }, { $ref: "#/$defs/vec3" }, { $ref: "#/$defs/ref" }], default: "up" },
 };
@@ -142,6 +143,7 @@ export const FIX_TYPES = {
 };
 
 export const REF_DOCS = {
-	joint: "joint:<Bone>, the bone's joint", bone: "bone:<Bone>, as joint:", prop: "prop:<prop>.<point> (origin always exists)",
-	anchor: "anchor:<name>, a spec anchor", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base], a body or group (Empty); bare = its surface in a distance",
+	joint: "joint:<Bone>", bone: "bone:<Bone> (= joint:)", prop: "prop:<prop>.<point> (origin exists)",
+	anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base], a body or group; bare = its surface (distance)",
+	person: "person:<id>.<Bone>",
 };