cozyclay 3.0.0 → 3.0.2

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", "socket", "grasp"], 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

@@ -48,7 +48,7 @@ export const EXAMPLES = {
 };
 
 const UNITS = `World metres, +Y up; ${CONVENTIONS.yaw}; the character's left is +X at yaw 0. Angles in degrees.`;
-const NO_JUMP = "Without at/along it keeps its grab-frame offset to the palm: no jump.";
+const NO_JUMP = "Without at/along it keeps its grab-frame palm offset: no jump.";
 /** The objects example's carry: a grip prop and the object it holds. */
 const CARRY = { props: EXAMPLES.objects.props, objects: { cup: EXAMPLES.objects.objects.cup } };
 
@@ -64,13 +64,15 @@ 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.",
+		"An object anchor with grasp (power, pinch, hook, palm) takes the hand by a socket of its object and the compiler turns the hand: power and hook put the knuckle line along the socket's axis with the palm on it, pinch holds at the fingertips, palm presses flat on the nearest face. socket names one (object.grasp sockets the user or you stored, or a thin part by its id: a bar, a grip, a magazine); without it the socket nearest local, or the shoulder. Two hands on one carried object: each hand an object anchor with grasp on its part (a rifle's grip and magazine). reachGrip on such an anchor closes the fingers to the grasp. Never key the wrist for it; a wrist you key (wtwist/wflex) wins.",
+		"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.",
 		"reachGrip adds props.<anchor>Grip and its fit. Carry a scene object with objects.<id>.prop (topic objects)."],
 	objects: ["A hinge turns the object (a body or a group) about pivot/axis by the angle channel your keys set (degrees).",
-		"A carry follows the prop's hand: before grab the scene pose, grab..release in the hand, after release frozen where it was let go.",
+		"A carry follows the prop's hand: before grab the scene pose, grab..release in the hand, after release where it was let go, riding a body under it that keys or a hinge move.",
 		`No grab: in hand from frame 0; no release: to the end. ${NO_JUMP}`,
 		"A group (Empty) id moves all its parts; at/along pin a group's root to the palm too (an object.createKit kit). A carried object is an obstacle for the body and the scene.",
 		"A switch { visible?, level? } (no prop, no hinge field) moves nothing: it shows or hides any record (a part, a light, an effect) and sets its level, 0..4 light, glow and effect strength "
@@ -81,14 +83,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 +105,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

@@ -3,7 +3,7 @@
 // looks each field up here, and throws when one is missing, so a new field needs a type here.
 // Shared shapes are $refs into DEFS (describe.js adds the ones an answer uses).
 import { REF_KINDS, OBJECT_KEY_FIELDS } from "./fields.js";
-import { CONVENTIONS } from "../compiler/vocab.js";
+import { CONVENTIONS, GRASPS } from "../compiler/vocab.js";
 import { QA_LIMITS } from "../qa/checks.js";
 import { CAPSULES } from "../qa/geometry.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"), socket: str("a socket of the object"), grasp: { enum: GRASPS, description: "the hand takes it by a socket" },
 };
 
 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>",
 };

package/src/motion3/settle.js

@@ -0,0 +1,136 @@
+// How a falling object (C17, free-motion.js) comes to rest. It falls with its centre on a parabola, turning at the spin it
+// was let go with, and lands on its lowest point. Then it rolls about what touches the support. Landing on an edge or a
+// corner it rocks back onto the face nearest down, or falls over onto the face it leans to when it leans past that edge.
+// Then it goes over an edge onto a lower face while the landing has the energy (a share TIP of the drop; only one that hit
+// tilted or spinning, since a flat landing has nothing to tip it), or at once from a precarious face (one it can tilt less
+// than PRECARIOUS before its centre passes the edge). So a phone on its edge falls flat, a tilted box comes down on a face,
+// a can let go at a slant lies down, and a can or cup dropped upright stays upright. It only rolls onto a face that lowers
+// its centre by at least LOWER of its height, so a near cube stays the way it lands. The shape is the box around the
+// object's parts in its own frame, and its centre is the parts' volume-weighted centre. Every step is a rotation about a
+// pivot on the support, paced by gravity: closed form and deterministic.
+import { add, sub, scale, dot, cross, len, norm, mul, apply, axisRot, clamp } from "./compiler/math.js";
+import { G } from "./free-motion.js";
+
+/** The share of the drop height a landing spends tipping the object over an edge. */
+export const TIP = 0.3;
+const LOWER = 0.2, FLAT = 0.5, PRECARIOUS = 15, MIN_SPIN = 1, MAX_SPIN = 6 * Math.PI, MAX_STEPS = 3;
+const DOWN = [0, -1, 0];
+const AXES = [[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]];
+const deg = r => (r * 180) / Math.PI;
+
+/** The shape of part boxes { pos, R, half } given in the root frame: { com, lo, hi } (box around the corners); null without volume. */
+export function shapeOf(boxes) {
+	const solid = boxes.filter(b => b.half[0] * b.half[1] * b.half[2] > 1e-12);
+	if (!solid.length) return null;
+	let vol = 0, c = [0, 0, 0];
+	const corners = [];
+	for (const b of solid) {
+		const v = b.half[0] * b.half[1] * b.half[2];
+		vol += v;
+		c = add(c, scale(add(b.pos, apply(b.R, [0, b.half[1], 0])), v));
+		for (const x of [-1, 1]) for (const y of [0, 2]) for (const z of [-1, 1]) corners.push(add(b.pos, apply(b.R, [x * b.half[0], y * b.half[1], z * b.half[2]])));
+	}
+	return { com: scale(c, 1 / vol), lo: [0, 1, 2].map(i => Math.min(...corners.map(p => p[i]))), hi: [0, 1, 2].map(i => Math.max(...corners.map(p => p[i]))) };
+}
+
+const boxCorners = s => [0, 1, 2, 3, 4, 5, 6, 7].map(i => [i & 1 ? s.hi[0] : s.lo[0], i & 2 ? s.hi[1] : s.lo[1], i & 4 ? s.hi[2] : s.lo[2]]);
+const world = (pose, p) => add(pose.pos, apply(pose.R, p));
+const lowest = (s, pose) => Math.min(...boxCorners(s).map(p => world(pose, p)[1]));
+/** The pose moved up or down so its lowest corner sits on the support top. */
+const snap = (s, pose, top) => ({ pos: [pose.pos[0], pose.pos[1] + top - lowest(s, pose), pose.pos[2]], R: pose.R });
+const about = (pose, pivot, Q) => ({ pos: add(pivot, apply(Q, sub(pose.pos, pivot))), R: mul(Q, pose.R) });
+/** The face whose outward normal points most nearly down. */
+const downFace = R => AXES.reduce((best, n, k) => (dot(apply(R, n), DOWN) > dot(apply(R, AXES[best]), DOWN) ? k : best), 0);
+/** Where the plane of face k lies along its axis, and the centre's distance to it (its height when it rests on k). */
+const facePlane = (s, k) => { const a = k >> 1; return AXES[k][a] > 0 ? s.hi[a] : s.lo[a]; };
+const heightOn = (s, k) => Math.abs(facePlane(s, k) - s.com[k >> 1]);
+
+/** The spin (rad/s, world axis times rate) that takes rotation Ra to Rb in one frame at fps; capped at MAX_SPIN, none under MIN_SPIN (a hand's jitter). */
+export function spinOf(Ra, Rb, fps) {
+	const D = mul(Rb, [[Ra[0][0], Ra[1][0], Ra[2][0]], [Ra[0][1], Ra[1][1], Ra[2][1]], [Ra[0][2], Ra[1][2], Ra[2][2]]]);
+	const a = Math.acos(clamp((D[0][0] + D[1][1] + D[2][2] - 1) / 2, -1, 1));
+	if (a * fps < MIN_SPIN) return [0, 0, 0];
+	const axis = norm([D[2][1] - D[1][2], D[0][2] - D[2][0], D[1][0] - D[0][1]]), rate = Math.min(MAX_SPIN, a * fps);
+	return len(axis) > 0 ? scale(axis, rate) : [0, 0, 0];
+}
+
+/** The fall through the air from `start` onto the support top: { tl (s), at(t) } with the centre on a parabola, turning at `spin`. */
+export function airPath(s, start, spin, top, fps) {
+	const rate = len(spin), com0 = world(start, s.com);
+	const at = t => {
+		const R = rate > 0 ? mul(axisRot(spin, deg(rate * t)), start.R) : start.R;
+		return { pos: sub(add(com0, [0, -0.5 * G * t * t, 0]), apply(R, s.com)), R };
+	};
+	const h = Math.max(0, lowest(s, start) - top);
+	if (rate === 0) return { tl: Math.sqrt((2 * h) / G), at };
+	// spinning: the first sub-frame step whose lowest corner reaches the top, then halved down to the touch
+	const dt = 1 / (fps * 8), cap = Math.sqrt((2 * (h + len(sub(s.hi, s.lo)))) / G) + dt;
+	let a = 0, b = dt;
+	while (b < cap && lowest(s, at(b)) > top) { a = b; b += dt; }
+	for (let i = 0; i < 24 && b - a > 1e-7; i++) { const m = (a + b) / 2; if (lowest(s, at(m)) > top) a = m; else b = m; }
+	return { tl: b, at };
+}
+
+/** A step's duration (s): gravity-paced by the centre's height and the angle it rolls through. */
+const stepTime = (height, angle) => 0.12 + 0.9 * Math.sqrt(Math.max(height, 1e-4) / G) * Math.sqrt(angle / 90);
+
+/**
+ * From the pose it lands in, how it rolls to rest on the support top with `energy` (m of drop) to tip over edges:
+ * { steps: [{ from, pivot, axis, angle, time }], rest, time }. `lean` (horizontal) is the way a spin tips it: it gives a flat
+ * landing the energy and breaks a tie between edges.
+ */
+export function settlePath(s, impact, top, energy, lean = [0, 0, 0]) {
+	const steps = [];
+	let pose = snap(s, impact, top), time = 0;
+	const push = (pivot, axis, angle) => {
+		const height = world(pose, s.com)[1] - top, t = stepTime(height, angle);
+		steps.push({ from: pose, pivot, axis, angle, time: t });
+		pose = snap(s, about(pose, pivot, axisRot(axis, angle)), top);
+		time += t;
+	};
+	// landed on an edge or a corner: back onto the face nearest down, or over onto the face it leans to when it leans past
+	// that edge (more than the angle its centre needs to pass it), rolling about the corners on the support
+	let k = downFace(pose.R);
+	const tiltOf = j => deg(Math.acos(clamp(dot(apply(pose.R, AXES[j]), DOWN), -1, 1))), tilt = tiltOf(k);
+	if (tilt > FLAT) {
+		const side = [0, 1, 2, 3, 4, 5].filter(j => j >> 1 !== k >> 1).reduce((a, j) => (tiltOf(j) < tiltOf(a) ? j : a), k === 0 || k === 1 ? 2 : 0);
+		if (tilt > deg(Math.atan2(heightOn(s, side), heightOn(s, k)))) k = side;
+		const touching = boxCorners(s).map(p => world(pose, p)).filter(p => p[1] <= top + 1e-4);
+		const n = apply(pose.R, AXES[k]);
+		push(scale(touching.reduce(add, [0, 0, 0]), 1 / touching.length), norm(cross(n, DOWN)), tiltOf(k));
+	}
+	// over an edge onto a lower face while the landing has the energy, at once from a precarious face (or a centre past the
+	// edge); a flat landing with no spin has none
+	let left = tilt > FLAT || len(lean) > 0 ? energy : 0;
+	for (let i = 0; i < MAX_STEPS; i++) {
+		const com = world(pose, s.com), cK = com[1] - top;
+		let best = null;
+		for (let j = 0; j < 6; j++) {
+			if (j >> 1 === k >> 1) continue;
+			const out = apply(pose.R, AXES[j]), edge = world(pose, AXES[j].map((v, a) => (v ? facePlane(s, j) : a === k >> 1 ? facePlane(s, k) : s.com[a])));
+			const w = -dot(sub(com, edge), out), cJ = heightOn(s, j);
+			if (!(w < 0 || cJ < cK * (1 - LOWER))) continue;
+			const cost = w < 0 || deg(Math.atan2(w, cK)) < PRECARIOUS ? 0 : Math.hypot(cK, w) - cK, side = dot(out, lean);
+			if (!best || cost < best.cost - 1e-9 || (Math.abs(cost - best.cost) <= 1e-9 && side > best.side)) best = { j, out, edge, cost, side };
+		}
+		if (!best || best.cost > left) break;
+		left -= best.cost;
+		const touching = boxCorners(s).map(p => world(pose, p)).filter(p => p[1] <= top + 1e-4 && dot(sub(p, best.edge), best.out) >= -1e-4);
+		push(touching.length ? scale(touching.reduce(add, [0, 0, 0]), 1 / touching.length) : [best.edge[0], top, best.edge[2]], norm(cross(best.out, DOWN)), 90);
+		k = best.j;
+	}
+	return { steps, rest: pose, time };
+}
+
+/** The pose `u` seconds after it landed, along the settle path: each step rolls about its pivot, accelerating like a fall. */
+export function settledAt(path, u) {
+	let t = u;
+	for (const st of path.steps) {
+		if (t < st.time) { const s = t / st.time; return about(st.from, st.pivot, axisRot(st.axis, st.angle * s * s)); }
+		t -= st.time;
+	}
+	return path.rest;
+}
+
+/** The energy (m of drop) a spin adds: its kinetic energy over m g, for the box's radius of gyration about its centre. */
+export const spinEnergy = (s, spin) => (len(spin) ** 2 * ((s.hi[0] - s.lo[0]) ** 2 + (s.hi[1] - s.lo[1]) ** 2 + (s.hi[2] - s.lo[2]) ** 2)) / (24 * G);

package/src/motion3/skills/basic.js

@@ -4,6 +4,10 @@ import { add, apply, ry } from "../compiler/math.js";
 import { walk } from "../compiler/walk.js";
 import { keyBook, skillError } from "./book.js";
 import { walkEnd } from "./info.js";
+import { GRASP_FINGERS, GRASP_POINTS } from "../compiler/vocab.js";
+
+/** The fingers' point a reachGrip fits onto its anchor: the finger middles, or where a grasp holds the thing (the palm is -n on the right hand). */
+const graspPoint = (grasp, k) => (GRASP_POINTS[grasp] ? GRASP_POINTS[grasp].map((v, i) => (i === 2 && k === "r" ? -v : v)) : [0, 0, 0]);
 
 /** standIdle({ at: [x, z], heading = 0, until }): a neutral standing pose, arms down (FK). */
 export function standIdle(ctx) {
@@ -59,7 +63,9 @@ export function reachGrip(ctx) {
 	const { args, state } = ctx, k = args.side, name = args.anchor;
 	if (k !== "l" && k !== "r") skillError(ctx.tag, `args.side must be "l" or "r", got ${JSON.stringify(k)}`);
 	if (typeof name !== "string" || /_[lr]$/.test(name)) skillError(ctx.tag, "args.anchor must name an anchor (not ending in _l/_r)");
-	const reach = args.reach ?? 20, hold = args.hold ?? 22, release = args.release ?? 12, preset = args.fingers ?? "grip";
+	const reach = args.reach ?? 20, hold = args.hold ?? 22, release = args.release ?? 12;
+	// an anchor that takes a grasp closes the hand to that grasp's fingers (../sockets.js)
+	const grasp = (args.define ?? ctx.anchors?.[name])?.grasp, preset = args.fingers ?? GRASP_FINGERS[grasp] ?? "grip";
 	const w = `w_${name}_${k}`, fg = `fingers_${k}`, armw = `armw_${k}`, el = `elbow_${k}`, wasFk = !(state[armw] > 0.5);
 	// a take that ends after the hold but before the hand lets go cuts the release: the grip holds to the last frame
 	const last = ctx.frames - 1, cut = ctx.f0 + reach + hold <= last && ctx.f0 + reach + hold + release > last;
@@ -71,10 +77,11 @@ export function reachGrip(ctx) {
 	if (!cut) b.at(reach + hold + release, { [w]: 0, [fg]: { ...state[fg], [preset]: 0 }, ...(wasFk ? { [armw]: 0 } : {}) });
 	const S = k === "l" ? "Left" : "Right", prop = `${name}Grip`;
 	const def = args.define ? { [name]: args.define } : {};
-	const obj = args.define?.kind === "object" ? args.define.object : ctx.anchors?.[name]?.kind === "object" ? ctx.anchors[name].object : null;
+	// the hand may touch what it grips: an object, or the other person (people.js) whose joint the anchor is on
+	const a = args.define ?? ctx.anchors?.[name], obj = a?.kind === "object" ? a.object : a?.kind === "person" ? `person:${a.person}` : null;
 	return {
 		keys: b.keys, end: cut ? last : ctx.f0 + reach + hold + release, ...(cut ? { cut: `release cut at f${last} (hold to the end)` } : {}), anchors: def,
-		props: { [prop]: { hand: k, origin: [`${S}HandIndex2`, `${S}HandMiddle2`], points: { fingers: [0, 0, 0] } } },
+		props: { [prop]: { hand: k, origin: [`${S}HandIndex2`, `${S}HandMiddle2`], points: { fingers: graspPoint(grasp, k) } } },
 		fits: [{ side: k, anchor: name, effector: { prop, point: "fingers" }, ...(args.orient === false ? { orient: false } : {}) }],
 		checks: { contacts: [{ name: `fingers on ${name}`, point: `prop:${prop}.fingers`, target: `anchor:${name}`, tol: 0.04, when: w }],
 			allow: obj ? [{ part: "hand", object: obj, depth: 0.04 }] : [] },

package/src/motion3/skills/flip.js

@@ -0,0 +1,200 @@
+// flip: a standing back or front tuck, or a cartwheel, from the standing pose keyed before f0. The root and the feet (and
+// the cartwheel's hands) are keyed every frame from closed-form curves whose speeds join without a kink (no POP); the
+// arms, spine and head are keyed at the phase edges and the channels' own interpolation carries them between.
+// - back/front: crouch, push-off (the heels roll up over the balls), a ballistic flight (the hips on a parabola under
+//   gravity, so QA reads a jump, not a float) with the knees tucked to the chest while the whole body turns 360 deg a turn
+//   (pitch, - backward), a landing that absorbs the fall, and the stand.
+// - cartwheel: the lead foot steps out, then the body rolls 360 deg toward args.side like a wheel whose spokes are the
+//   straddled legs and the arms overhead: each frame the hips sit as high as the lowest spoke touching the floor allows,
+//   and a hand or foot whose spoke is down stays planted where it touched.
+// Both end with the turn's full angle and then 0 on the last two frames (the same pose), so a later key at 0 does not
+// unwind it. Poles are given so the knees and elbows bend toward the turning body's front (pose.js tiltFrame).
+import { add, sub, scale, apply, mul, rx, ry, rz, dist, T } from "../compiler/math.js";
+import { pivot } from "../compiler/walk-pelvis.js";
+import { tiltFrame } from "../compiler/pose.js";
+import { skillError } from "./book.js";
+
+const G = 9.81 / (24 * 24); // m per frame^2 at the timeline's 24 fps
+const CROUCH = 10, PUSH = 5, LAND = 6, RISE = 14, TOE_OFF = 50;
+const clamp01 = u => Math.min(1, Math.max(0, u));
+const ease = u => { const t = clamp01(u); return t * t * (3 - 2 * t); };
+const mix = (a, b, t) => a + (b - a) * t;
+const mix3 = (a, b, t) => a.map((v, i) => v + (b[i] - v) * t);
+const window = (u, a, b, c, d) => ease((u - a) / (b - a)) - ease((u - c) / (d - c));
+const SIDE = { l: 1, r: -1 };
+const bodyFrame = (h, pitch, roll) => mul(ry(h), mul(rx(pitch), rz(roll)));
+/** A pole the turning body (B) holds as `local`, written as the channel pose.js turns by its own frame. */
+const poleFor = (h, pitch, roll, B, local) => apply(T(tiltFrame(h, pitch, roll)?.R ?? ry(h)), apply(B, local));
+
+/**
+ * fyaw/fpitch that make pose.js aim the foot (orientFoot, in its tilt frame) where the turning body B holds it at fpitch
+ * `fp` in its own frame: the toe direction solved back through the frame pose.js reads the channels in (clamped to fpitch's
+ * range). Nearer upright pose.js reads them on the level, as for any foot, and they pass as they are.
+ */
+function footAim(b, k, pitch, roll, B, fp) {
+	const tilt = tiltFrame(b.h, pitch, roll);
+	if (!tilt) return { fyaw: b.h, fpitch: fp };
+	const rest = b.toe[k], want = apply(B, apply(rx(fp), rest)), d = apply(T(tilt.R), want);
+	const phi = Math.atan2(-rest[1], rest[2]), deg = 180 / Math.PI;
+	const p = Math.asin(Math.max(-1, Math.min(1, -d[1] / Math.hypot(...d)))) - phi;
+	return { fyaw: b.h + Math.atan2(d[0], d[2]) * deg, fpitch: Math.max(-60, Math.min(90, p * deg)) };
+}
+
+function base(ctx) {
+	const { sk, args, state } = ctx, I = sk.index, P = sk.restWorldPos;
+	if (!state.foot_l || !state.foot_r || !state.root) skillError(ctx.tag, "needs a standing pose keyed before f0 (use standIdle or another skill first)");
+	const h = args.heading ?? state.yaw ?? 0, R = ry(h), hips = P[I.Hips];
+	const leg = dist(P[I.LeftUpLeg], P[I.LeftLeg]) + dist(P[I.LeftLeg], P[I.LeftFoot]), arm = dist(P[I.LeftArm], P[I.LeftForeArm]) + dist(P[I.LeftForeArm], P[I.LeftHand]);
+	return { h, R, F: apply(R, [0, 0, 1]), L: apply(R, [1, 0, 0]), ank: P[I.LeftFoot][1], y0: hips[1] - 0.01, leg, arm,
+		feet: { l: state.foot_l.slice(), r: state.foot_r.slice() }, root: state.root.slice(),
+		hipOff: { l: sub(P[I.LeftUpLeg], hips), r: sub(P[I.RightUpLeg], hips) }, shoulder: { l: sub(P[I.LeftArm], hips), r: sub(P[I.RightArm], hips) },
+		toe: { l: sub(P[I.LeftToeBase], P[I.LeftFoot]), r: sub(P[I.RightToeBase], P[I.RightFoot]) } };
+}
+
+function tuck(ctx, b, kind) {
+	// one turn from a standing jump whose hips rise H at the top: the curves below are measured clean for that flip (a
+	// higher jump or more turns would need its own tuck timing, so the skill takes neither)
+	const { args } = ctx, s = kind === "back" ? -1 : 1, turn = s * 360, H = 0.5;
+	const travel = args.travel ?? (kind === "back" ? -0.25 : 0.4);
+	const yT = b.y0 + 0.05, yL = b.y0 - 0.02;                // the hips at take-off (toes pointed) and at touch-down
+	const Tf = Math.max(10, Math.round(Math.sqrt(2 * (H - 0.05) / G) + Math.sqrt(2 * (yT + H - 0.05 - yL) / G)));
+	const v0 = (yL - yT + (G * Tf * Tf) / 2) / Tf, vL = v0 - G * Tf, yc = yT - (v0 * PUSH) / 2, bottom = yL + (vL * LAND) / 2;
+	const vx = travel / (PUSH / 2 + Tf + LAND / 2);
+	const t0 = ctx.f0, tP = t0 + CROUCH, tA = tP + PUSH, tD = tA + Tf, tL = tD + LAND, tE = tL + RISE;
+	const land = k => add(b.feet[k], scale(b.F, travel)), ball = k => add(b.feet[k], apply(b.R, b.toe[k]));
+	const hipsAt = f => {
+		let y, x;
+		if (f <= tP) { y = mix(b.root[1], yc, ease((f - t0) / CROUCH)); x = 0; }
+		else if (f <= tA) { const t = f - tP; y = yc + (v0 / PUSH) * t * t / 2; x = (vx / PUSH) * t * t / 2; }
+		else if (f <= tD) { const t = f - tA; y = yT + v0 * t - (G * t * t) / 2; x = (vx * PUSH) / 2 + vx * t; }
+		else if (f <= tL) { const t = f - tD; y = yL + vL * t - (vL / LAND) * t * t / 2; x = (vx * PUSH) / 2 + vx * Tf + vx * t - (vx / LAND) * t * t / 2; }
+		else { y = mix(bottom, b.y0, ease((f - tL) / RISE)); x = travel; }
+		return add([b.root[0], y, b.root[2]], scale(b.F, x));
+	};
+	// the turn starts 2 frames before take-off and ends 3 after touch-down
+	const pitchAt = f => turn * ease((f - tA + 2) / (Tf + 5)), frameAt = f => bodyFrame(b.h, pitchAt(f), 0);
+	// in the air the feet ride the body: from where they left the floor, through the tuck, to where they land, all in its frame
+	const local = (f, p) => apply(T(frameAt(f)), sub(p, hipsAt(f)));
+	const offL = { l: local(tA, pivot(ball("l"), b.h, TOE_OFF, b.feet.l)), r: local(tA, pivot(ball("r"), b.h, TOE_OFF, b.feet.r)) };
+	const onL = { l: local(tD, land("l")), r: local(tD, land("r")) };
+	const keys = [];
+	for (let f = t0; f <= tE + 1; f++) {
+		const pitch = f > tE ? 0 : pitchAt(f), B = bodyFrame(b.h, pitch, 0), hips = hipsAt(f), u = (f - tA) / Tf;
+		const tk = f > tA && f < tD ? window(u, 0.12, 0.34, 0.6, 0.82) : 0;
+		const set = { root: hips, yaw: b.h, pitch, roll: 0, armw_l: 0, armw_r: 0, fyaw_l: b.h, fyaw_r: b.h };
+		for (const k of ["l", "r"]) {
+			let foot, fp;
+			if (f <= tP) { foot = b.feet[k]; fp = 0; }
+			else if (f <= tA) { fp = TOE_OFF * ease((f - tP) / PUSH); foot = pivot(ball(k), b.h, fp, b.feet[k]); }
+			else if (f < tD) {
+				const a = 1 - ease(u / 0.2), c = ease((u - 0.72) / 0.28);
+				const mid = add(b.hipOff[k], mix3([0, -b.leg * 0.97, 0], [SIDE[k] * 0.02, -0.24, 0.16], tk));
+				foot = add(hips, apply(B, add(add(scale(offL[k], a), scale(onL[k], c)), scale(mid, 1 - a - c))));
+				fp = mix(mix(TOE_OFF, 30, ease(u / 0.2)), 0, ease((u - 0.7) / 0.3));
+			} else { foot = land(k); fp = 0; }
+			const aim = f > tA && f < tD ? footAim(b, k, pitch, 0, B, fp) : { fyaw: b.h, fpitch: fp };
+			Object.assign(set, { [`foot_${k}`]: foot, [`fpitch_${k}`]: aim.fpitch, [`fyaw_${k}`]: aim.fyaw, [`knee_${k}`]: poleFor(b.h, pitch, 0, B, [SIDE[k] * 0.05, 0.5 * tk, 1]) });
+		}
+		keys.push({ f, set });
+	}
+	// the arms, spine and head at the phase edges: back in the crouch, overhead at take-off, to the shins in the tuck,
+	// forward for the landing, then down
+	const head = kind === "back" ? [-12, 18] : [10, 25];
+	for (const [f, sw, bd, sp, hd] of [[t0, 0, 0, 0, 0], [tP, -45, 15, 20, 0], [tA, 160, 5, -8, head[0]], [Math.round(tA + 0.3 * Tf), 55, 85, 32, head[1]],
+		[Math.round(tA + 0.62 * Tf), 55, 85, 32, head[1]], [tD, 75, 25, 22, 0], [tL, 70, 25, 28, 0], [tE, 0, 0, 0, 0]]) {
+		keys.push({ f, set: { aswing_l: sw, aswing_r: sw, abend_l: bd, abend_r: bd, spine_pitch: sp, head_pitch: hd } });
+	}
+	return { keys, end: tE + 1 };
+}
+
+function cartwheel(ctx, b) {
+	const { args } = ctx, dir = args.side === "r" ? -1 : 1, rs = -dir;   // toward the character's left the head goes to +x: roll -
+	const W = 12, ROT = 34, REC = 14, t0 = ctx.f0, tR = t0 + W, tC = tR + ROT, tE = tC + REC;
+	const lead = dir > 0 ? "l" : "r", trail = lead === "l" ? "r" : "l";
+	// spokes from the hips in the body's frame (x the body's left): the legs straddled, the arms overhead and apart
+	const spoke = { foot: k => add(b.hipOff[k], [SIDE[k] * 0.3, -b.leg * 0.93, 0]), hand: k => add(b.shoulder[k], [SIDE[k] * 0.32, b.arm * 0.88, 0]) };
+	const floor = { foot: b.ank, hand: 0.1 };
+	// the order the ends touch down rolling toward the lead side; the body pivots on each in turn like a wheel on its spokes
+	const order = [["foot", lead], ["hand", lead], ["hand", trail], ["foot", trail], ["foot", lead]];
+	const rollAt = f => f <= tR ? 0 : f <= tC ? rs * 360 * ease((f - tR) / ROT) : rs * 360;
+	const end = (f, hips, part, k) => add(hips, apply(bodyFrame(b.h, 0, rollAt(f)), spoke[part](k)));
+	// start: the trail foot stays, the lead foot steps out so both stand on their spokes; the hips over them
+	const B0 = bodyFrame(b.h, 0, 0), hips0 = sub(b.feet[trail], apply(B0, spoke.foot(trail))), stepTo = end(tR, hips0, "foot", lead);
+	stepTo[1] = b.ank;
+	const raw = [], plants = { foot: { l: [], r: [] }, hand: { l: [], r: [] } };
+	let at = 0, pivot = b.feet[lead].slice(), from = tR;
+	plants.foot[trail].push({ a: t0, b: tR, p: b.feet[trail] });
+	for (let f = t0; f <= tE + 1; f++) {
+		if (f <= tR) { raw.push(mix3(b.root, hips0, ease((f - t0) / W))); continue; }
+		if (f === tR + 1) pivot = stepTo.slice();
+		let hips = sub(pivot, apply(bodyFrame(b.h, 0, rollAt(f)), spoke[order[at][0]](order[at][1])));
+		const next = order[at + 1];
+		if (next && f <= tC) {
+			const e = end(f, hips, ...next);
+			if (e[1] <= floor[next[0]]) {
+				// the end touched between the frames: pivot where it crossed the floor, so the hips do not jump
+				const ep = end(f - 1, raw.at(-1), ...next), h1 = ep[1] - floor[next[0]], h2 = e[1] - floor[next[0]];
+				const cross = mix3(ep, e, h1 > 0 ? h1 / (h1 - h2) : 1);
+				plants[order[at][0]][order[at][1]].push({ a: from, b: f, p: pivot });
+				at++; from = f; pivot = [cross[0], floor[next[0]], cross[2]];
+				hips = sub(pivot, apply(bodyFrame(b.h, 0, rollAt(f)), spoke[next[0]](next[1])));
+			}
+		}
+		raw.push(hips);
+	}
+	plants[order[at][0]][order[at][1]].push({ a: from, b: tE + 1, p: pivot });
+	// the trail foot that landed stays down to the end too
+	const last = order[order.length - 2];
+	if (at >= order.length - 1) plants[last[0]][last[1]].at(-1).b = tE + 1;
+	// the pivot path turns at each touch-down: blurred over a few frames (the planted ends absorb it), then the stand
+	const blur = raw.map((p, i) => { let s = [0, 0, 0], w = 0; for (let d = -3; d <= 3; d++) { const j = Math.min(raw.length - 1, Math.max(0, i + d)), g = Math.exp(-(d * d) / 4); s = add(s, scale(raw[j], g)); w += g; } return scale(s, 1 / w); });
+	const hipsAt = f => f <= tC ? blur[f - t0] : add(blur[tC - t0], [0, (b.y0 - blur[tC - t0][1]) * ease((f - tC) / REC), 0]);
+	// a planted end the turning body has rolled away from is drawn toward its hip or shoulder until the limb reaches it
+	const reach = (p, from, n) => { const v = sub(p, from), d = Math.hypot(...v); return d > n ? add(from, scale(v, n / d)) : p; };
+	// a hand or foot near its plant: easing onto it over the 6 frames before, held, then let go by following the body from
+	// where it left the floor (its place in the body's frame then) toward its spoke, so it lifts without a jolt
+	const touch = (part, k, f, free) => {
+		for (const r of plants[part][k]) {
+			if (f >= r.a - 6 && f <= r.b) return mix3(free, r.p, ease((f - r.a + 6) / 6));
+			if (f > r.b && f <= r.b + 10) {
+				const at = bodyFrame(b.h, 0, rollAt(r.b)), left = apply(T(at), sub(r.p, hipsAt(r.b)));
+				const follow = add(hipsAt(f), apply(bodyFrame(b.h, 0, rollAt(f)), mix3(left, spoke[part](k), ease((f - r.b - 1) / 9))));
+				return mix3(r.p, follow, ease((f - r.b) / 8));
+			}
+		}
+		return free;
+	};
+	const planted = (part, k, f) => plants[part][k].some(r => f >= r.a && f <= r.b);
+	// where the feet stand after the roll: a planted one where it is, else under its spoke at the roll's end
+	const landed = Object.fromEntries(["l", "r"].map(k => { const p = planted("foot", k, tC) ? plants.foot[k].at(-1).p.slice() : end(tC, hipsAt(tC), "foot", k); p[1] = b.ank; return [k, p]; }));
+	const keys = [];
+	for (let f = t0; f <= tE + 1; f++) {
+		const roll = f === tE + 1 ? 0 : rollAt(f), B = bodyFrame(b.h, 0, rollAt(f)), hips = hipsAt(f);
+		const set = { root: hips, yaw: b.h, pitch: 0, roll };
+		for (const k of ["l", "r"]) {
+			let foot;
+			if (f <= tR && k === lead) { const w = ease((f - t0 - 1) / (W - 4)); foot = add(mix3(b.feet[k], stepTo, w), [0, 0.07 * Math.sin(Math.PI * w), 0]); }
+			else if (f > tC) foot = landed[k];
+			else {
+				const down = ease((f - tC + 4) / 4);
+				foot = reach(mix3(touch("foot", k, f, end(f, hips, "foot", k)), landed[k], down), add(hips, apply(B, b.hipOff[k])), b.leg * 0.995);
+			}
+			const aim = f > tR && f <= tC ? footAim(b, k, 0, rollAt(f), B, 0) : { fyaw: b.h, fpitch: 0 };
+			Object.assign(set, { [`foot_${k}`]: foot, [`fyaw_${k}`]: aim.fyaw, [`fpitch_${k}`]: aim.fpitch, [`knee_${k}`]: poleFor(b.h, 0, roll, B, [SIDE[k] * 0.05, 0, 1]),
+				[`hand_${k}`]: reach(f > tR && f <= tC ? touch("hand", k, f, end(f, hips, "hand", k)) : end(f, hips, "hand", k), add(hips, apply(B, b.shoulder[k])), b.arm * 0.995), [`elbow_${k}`]: poleFor(b.h, 0, roll, B, [SIDE[k] * 0.4, 0, -1]),
+				[`armw_${k}`]: f <= tR ? 0 : f <= tC ? ease((f - tR) / 6) : 1 - ease((f - tC) / 8) });
+		}
+		// the FK arms overhead along the hand spokes, so the hand eases onto its IK target without a jump
+		set.arm_rest = f <= tR ? mix(72, -56, ease((f - t0) / W)) : f <= tC ? -56 : mix(-56, 72, ease((f - tC) / REC));
+		keys.push({ f, set });
+	}
+	return { keys, end: tE + 1 };
+}
+
+/** flip({ kind: "back" | "front" | "cartwheel", travel, side, heading }) */
+export function flip(ctx) {
+	const kind = ctx.args.kind ?? "back";
+	if (!["back", "front", "cartwheel"].includes(kind)) skillError(ctx.tag, `kind must be "back", "front" or "cartwheel", got ${JSON.stringify(kind)}`);
+	const b = base(ctx);
+	return kind === "cartwheel" ? cartwheel(ctx, b) : tuck(ctx, b, kind);
+}