cozyclay 3.0.0 → 3.0.2

package/src/motion3/compiler/anchors.js

@@ -9,15 +9,22 @@
 //   { kind: "object",   object: "Car_Door_L", local: [x,y,z] }  point fixed to a scene object or group where it is at
 //                       that frame (hinged, carried, following; object-pose.js objectPoseAt), in its own axes
 //   { kind: "landmark", name: "mouth" }                     measured face landmark on the Head bone
-//   { kind: "prop",     prop: "cig", point: "tip", offset: [x,y,z] }  a point on a prop held by the other hand
+//   { kind: "prop",     prop: "cig", point: "tip", offset: [x,y,z] }  a point on a prop held by the other hand; while
+//                       that hand does not hold the object it carries, the point stays on that object (propOnCarry)
+//   { kind: "person",   person: "char-b", bone: "LeftArm", offset: [x,y,z] }  world offset from another character's joint
+//                       where its installed take has it at that frame (people.js)
 // spec.props = { name: { hand: "r", origin: ["RightHandIndex2", "RightHandMiddle2"],
 //                        points: { name: [d, l, n] } } }   offsets along the palm axes (m)
-import { add, sub, scale, len, apply, ry } from "./math.js";
+import { add, sub, scale, len, apply, ry, T } from "./math.js";
 import { bonePoint } from "./skeleton.js";
 import { palmAxes } from "./limbs.js";
 import { SIDES } from "./pose.js";
 import { HAND_CLEAR, keepOut } from "../body.js";
 import { groupsOf } from "../scene.js";
+import { personJoint, peopleList } from "../people.js";
+import { isCarried } from "../carried.js";
+import { socketsOf, socketNamed, socketWorld, socketDistance, faceFrom } from "../sockets.js";
+import { partsOf } from "../object-pose.js";
 
 function armReach(sk, k) {
 	const side = SIDES[k], P = sk.restWorldPos, I = sk.index;
@@ -78,17 +85,74 @@ function anchorPoint(ctx, a, name, s, diag, c, side) {
 			for (let t = a.t ?? 0.45; t >= (a.tMin ?? 0.15); t -= 0.01) if (len(sub(at(t), sh)) <= r) return at(t);
 			return at(a.tMin ?? 0.15);
 		}
-		case "object": { const o = objectFrame(ctx, a, name, { s, diag, c }, side); return add(o.pos, apply(o.R, a.local ?? [0, 0, 0])); }
+		case "object": {
+			if (a.grasp && a.local === undefined) return anchorSocket(ctx, name, s, diag, c, side).p;
+			const o = objectFrame(ctx, a, name, { s, diag, c }, side);
+			return add(o.pos, apply(o.R, a.local ?? [0, 0, 0]));
+		}
 		case "landmark": return bonePoint(s, I.Head, sk.landmarks[a.name] ?? (() => { throw new Error(`MOTION_SPEC_INVALID: unknown landmark "${a.name}"`); })());
 		case "prop": {
-			const p = diag.props?.[a.prop]?.[a.point];
+			const p = propOnCarry(ctx, a, name, diag?.frame) ?? diag.props?.[a.prop]?.[a.point];
 			if (!p) throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" needs prop ${a.prop}.${a.point}, which is held by an arm solved later`);
 			return add(p, a.offset ?? [0, 0, 0]);
 		}
+		case "person": {
+			const p = personJoint(ctx.scene, a.person, a.bone, diag?.frame ?? 0);
+			if (!p) throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" names person "${a.person}" bone "${a.bone}", which the scene does not have (people: ${peopleList(ctx.scene)})`);
+			return add(p, a.offset ?? [0, 0, 0]);
+		}
 		default: throw new Error(`MOTION_SPEC_INVALID: anchor "${name}" has unknown kind "${a.kind}"`);
 	}
 }
 
+/**
+ * A point of a prop on a hand that carries an object, at a frame that hand does not hold it: where the point sits on
+ * the object at the grab (or the release) nearest in time, carried with the object (at rest before the grab, let go
+ * after the release). In hand the point rides the palm; before the grab the palm still turns into its grip (and after
+ * the release out of it), and a point held off it swept through the other arm's reach: session 02263581's barbell put
+ * the left hand on a point 55 cm off the right palm, and the left elbow jumped 28 cm in a frame at the grab and the
+ * release. Read off the object, the point is where the left hand takes the bar, and meets the palm's at the grab. null
+ * when no carry of that hand applies (the palm's point is used).
+ */
+function propOnCarry(ctx, a, name, f) {
+	const hand = ctx.spec.props?.[a.prop]?.hand;
+	if (!hand || f === undefined || !ctx.solvedAt || !ctx.carrySpan) return null;
+	let pick = null;
+	for (const [id, o] of Object.entries(ctx.spec.objects ?? {})) {
+		if (!isCarried(o) || ctx.spec.props?.[o.prop]?.hand !== hand) continue;
+		const [grab, release] = ctx.carrySpan(o);
+		if (f >= grab && f <= release) return null;
+		const at = f < grab ? grab : release;
+		if (!pick || Math.abs(f - at) < Math.abs(f - pick.at)) pick = { id, at };
+	}
+	if (!pick) return null;
+	const there = nested(ctx, name, pick.id, pick.at, () => ctx.solvedAt(pick.at).diag.props?.[a.prop]?.[a.point]);
+	const was = ctx.objectPose(pick.id, pick.at), now = ctx.objectPose(pick.id, f);
+	return there && was && now ? add(now.pos, apply(now.R, apply(T(was.R), sub(there, was.pos)))) : null;
+}
+
+/**
+ * The socket (../sockets.js) an object anchor with `grasp` takes the hand by, in world space on its object's pose that
+ * frame: { p, axis?, from?, thumb? }, p the anchor's point (its `local` when it has one). Its `socket`, else the one
+ * nearest its `local` point or, without one, nearest the shoulder of the hand: picked once per compile (ctx.sockets),
+ * so the hand does not hop between sockets. An object with no socket gives the bare point: the palm faces it.
+ */
+export function anchorSocket(ctx, name, s, diag, c, side) {
+	const a = ctx.spec.anchors[name], now = { s, diag, c }, poseOf = id => objectFrame(ctx, { ...a, object: id }, name, now, side);
+	const local = a.local && (o => add(o.pos, apply(o.R, a.local)))(poseOf(a.object));
+	ctx.sockets ??= new Map();
+	if (!ctx.sockets.has(name)) {
+		const all = socketsOf(ctx.scene, a.object), I = ctx.sk.index, near = local ?? s.P[I[side ? `${SIDES[side]}Arm` : "Hips"]];
+		const pick = a.socket ? socketNamed(ctx.scene, a.object, a.socket) : all.map(k => ({ k, d: socketDistance(socketWorld(k, poseOf(k.owner)), near) })).sort((x, y) => x.d - y.d)[0]?.k;
+		ctx.sockets.set(name, pick ?? null);
+	}
+	const sock = ctx.sockets.get(name), w = sock ? socketWorld(sock, poseOf(sock.owner)) : { p: local ?? poseOf(a.object).pos };
+	if (local) w.p = local;
+	// a socket with neither an axis nor a side (a box, a wall): the palm faces against the face of the body nearest the point
+	if (!w.axis && !w.from) w.from = faceFrom(partsOf(ctx.scene, a.object).map(id => ({ ...poseOf(id), half: ctx.scene.objects[id].half })), w.p);
+	return w;
+}
+
 /** Points of every prop held by hand k, in world space, written to diag.props. */
 export function measureProps(ctx, k, s, diag) {
 	const { sk } = ctx;

package/src/motion3/compiler/compile.js

@@ -33,7 +33,7 @@ import { fixOptions, applyFixes } from "../fix/index.js";
 import { fitWeight } from "../fix/self.js";
 import { holdHook } from "../object-keys.js";
 import { HAND_CLEAR, keepOut, wristBody } from "../body.js";
-import { objectPoseAt, handOf, restingAt } from "../object-pose.js";
+import { objectPoseAt, handOf, restingAt, frameAt, spanOf } from "../object-pose.js";
 
 const smooth = x => x * x * (3 - 2 * x);
 
@@ -180,10 +180,14 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	ctx.objectHand = (id, f) => handOf(out, id, f);
 	// a keyed carry's grab offset is taken where it rests at grab (object-keys.js; a fall before grab: where it landed)
 	ctx.restingAt = (id, f) => restingAt(out, id, f);
+	// a prop anchor outside its hand's carry reads the carry's grab (release) frame (anchors.js propOnCarry)
+	ctx.carrySpan = o => spanOf(out, o);
+	ctx.solvedAt = f => frameAt(out, f);
 	const engine = {
 		rebake(keys) {
 			out.keys = keys;
 			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow));
+			ctx.socketTurns = new Map();
 			steadyHead(out.baked, keys, frameCount);
 			// a held pose breathes and shifts its weight (idle.js): offsets solveFrame adds, contacts and out.baked stay as keyed
 			ctx.idle = idleLayer(out.baked, { spec, sk, frameCount });

package/src/motion3/compiler/grip.js

@@ -24,6 +24,7 @@
 // forearm's neutral roll. A thin body (a cup, a can) keeps the neutral offset: its aim keys pick the
 // roll the arm holds most easily from it, and the cylindrical grip measured worse on every bench cup.
 // Those frames read the carried body where it rested before the grab, never a pose the hand moves.
+// An anchor that takes a grasp (an object anchor with `grasp`) turns the hand by its socket instead (socket-grip.js).
 import { add, sub, scale, norm, cross, dot, len, apply, ry, mul, T, axisRot } from "./math.js";
 import { palmAxes, twoBone } from "./limbs.js";
 import { aimArm, orient } from "./hold.js";
@@ -31,6 +32,7 @@ import { ELBOW_REST, WRIST_COMFORT, wristNeed } from "./arm-orient.js";
 import { resolveAnchor } from "./anchors.js";
 import { sdBox } from "../qa/geometry.js";
 import { partsOf } from "../object-pose.js";
+import { graspAnchor, socketCarry, socketHand, keepSocketTurn, ownWrist } from "./socket-grip.js";
 
 const NEAR = 0.06, THIN = 0.045, ALIGN = 0.3, PREFER = 30, DEG = 180 / Math.PI, ITER = 2, UP = [0, 1, 0];
 const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];
@@ -141,9 +143,13 @@ function comfortable(F, now, twist) {
  */
 export function gripHand(ctx, sk, s, side, k, c, f, diag) {
 	// a wrist the spec turns on this frame is the agent's (or a skill's) own; a neutral 0 asks for nothing
-	if (Math.abs(c[`wtwist_${k}`] ?? 0) > 1e-3 || Math.abs(c[`wflex_${k}`] ?? 0) > 1e-3) return;
-	const on = activeFit(ctx.spec, c, k);
+	// a hand that takes a grasp (socket-grip.js) yields only to the agent's own wrist keys, not to a skill's (a walk's swing)
+	const on = activeFit(ctx.spec, c, k), carry = socketCarry(ctx, k, f), grasp = on && on.w >= 1e-3 && graspAnchor(ctx.spec, on.fit.anchor);
+	if (carry || grasp ? ownWrist(ctx.spec, k) : Math.abs(c[`wtwist_${k}`] ?? 0) > 1e-3 || Math.abs(c[`wflex_${k}`] ?? 0) > 1e-3) return;
+	// a hand that holds what it carries by a socket keeps the grasp it took on the grab frame
+	if (carry && f > carry.grab) return carry.keyed ? undefined : keepSocketTurn(ctx, sk, s, side, k, carry);
 	if (!on || on.w < 1e-3) return;
+	if (grasp) return socketHand(ctx, sk, s, side, k, c, diag, on, st => effectorAt(sk, ctx.spec, st, side, on.fit.effector ?? {}));
 	// a hand that carries something on this frame holds that (its carry's grip), whatever its fit's anchor
 	if (Object.keys(ctx.spec.objects ?? {}).some(id => ctx.spec.objects[id]?.prop && ctx.objectHand?.(id, f) === k && ownGrip(ctx, id, k, f) === null)) return;
 	const now = { s, diag, c }, anchor = ctx.spec.anchors?.[on.fit.anchor];

package/src/motion3/compiler/limbs.js

@@ -103,16 +103,21 @@ export function twoBone(sk, s, root, mid, end, target, pole, restBend, stop = nu
 	return inside || d - dc;
 }
 
-/** Aim a foot: Foot->ToeBase along yaw/pitch of its rest direction, sole kept level. */
-export function orientFoot(sk, s, side, yawDeg, pitchDeg) {
+/**
+ * Aim a foot: Foot->ToeBase along yaw/pitch of its rest direction, sole kept level. With `tilt` (pose.js tiltFrame: a body
+ * turned well past upright) the yaw and pitch are read in that frame and the sole levels to its up, so a foot in a flip
+ * points with the shin instead of staying flat to the floor; no toe-off then (the toes are off the ground).
+ */
+export function orientFoot(sk, s, side, yawDeg, pitchDeg, tilt = null) {
 	const foot = sk.index[`${side}Foot`], toe = sk.index[`${side}ToeBase`];
 	const rest = sub(sk.restWorldPos[toe], sk.restWorldPos[foot]);
-	const want = apply(ry(yawDeg), apply(rx(pitchDeg), rest));
+	const want = tilt ? apply(tilt.R, apply(ry(yawDeg - tilt.yaw), apply(rx(pitchDeg), rest))) : apply(ry(yawDeg), apply(rx(pitchDeg), rest));
+	const up = tilt ? apply(tilt.R, [0, 1, 0]) : [0, 1, 0];
 	// level the sole: the foot's own carried up vector goes to world up (no roll from the leg IK)
-	rotateSubtree(sk, s, foot, s.P[foot].slice(), align(sub(s.P[toe], s.P[foot]), carried(sk, s, foot, [0, 1, 0]), want, [0, 1, 0]));
+	rotateSubtree(sk, s, foot, s.P[foot].slice(), align(sub(s.P[toe], s.P[foot]), carried(sk, s, foot, [0, 1, 0]), want, up));
 	// Toe-off: bend the toe joint so the toes stay flat on the ground while the heel rises.
 	const tip = sk.index[`${side}Toe_End`];
-	if (pitchDeg > 0 && tip !== undefined) {
+	if (!tilt && pitchDeg > 0 && tip !== undefined) {
 		const seg = sub(s.P[tip], s.P[toe]), flat = [seg[0], 0, seg[2]];
 		if (len(flat) > 1e-6) rotateSubtree(sk, s, toe, s.P[toe].slice(), align(seg, [0, 1, 0], flat, [0, 1, 0]));
 	}
@@ -144,11 +149,13 @@ export function wrist(sk, s, side, twistDeg, flexDeg) {
 	rotateSubtree(sk, s, h, s.P[h].slice(), axisRot(axT, clamp(twistDeg, -85, 85)));
 }
 
-// Finger curl presets, degrees per phalanx (1, 2, 3); thumb is [opposition, curl, curl].
+// Finger curl presets, degrees per phalanx (1, 2, 3); thumb is [opposition, curl, curl]. A fist and a grip keep the
+// relaxed thumb here and close it with THUMB_WRAP: these thumb curls turn about the knuckle line and the hand's long axis,
+// which only swings a thumb out to the side (a fist read as a thumbs-up).
 const FINGER_PRESETS = {
 	relaxed: { Index: [12, 18, 10], Middle: [15, 20, 12], Ring: [18, 22, 12], Pinky: [20, 24, 14], Thumb: [15, 10, 8] },
-	fist: { Index: [80, 95, 60], Middle: [85, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [45, 30, 35] },
-	grip: { Index: [55, 60, 35], Middle: [60, 62, 35], Ring: [62, 62, 35], Pinky: [65, 62, 35], Thumb: [40, 20, 20] },
+	fist: { Index: [80, 95, 60], Middle: [85, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [15, 10, 8] },
+	grip: { Index: [55, 60, 35], Middle: [60, 62, 35], Ring: [62, 62, 35], Pinky: [65, 62, 35], Thumb: [15, 10, 8] },
 	cigarette: { Index: [8, 10, 6], Middle: [10, 12, 8], Ring: [60, 75, 45], Pinky: [65, 80, 45], Thumb: [35, 25, 20] },
 	point: { Index: [0, 0, 0], Middle: [80, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [40, 30, 30] },
 };
@@ -166,5 +173,25 @@ export function fingers(sk, s, side, weights) {
 			rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(ax, sign * curl(f, k)));
 		}
 	}
+	const wrap = [0, 1, 2, 3].map(i => Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * (THUMB_WRAP[p]?.[i] ?? 0), 0));
+	if (wrap.some(Boolean)) wrapThumb(sk, s, side, wrap);
+}
+
+// A closing hand's thumb, by preset weight after the relaxed one, degrees: turned in about the hand's long axis toward the
+// palm and across it, then flexed at its two joints about their own axes (bone x palm normal). The fist's thumb lies over
+// the index and middle fingers' middle phalanges; the grip's closes around a handle against the index finger. Searched on
+// both rigs within the joints' ranges (thumb tip to the index's middle phalanx: fist 8.4 -> 3.7 cm Y Bot, 6.9 -> 2.4 X Bot).
+const THUMB_WRAP = { fist: [-70, -5, 5, 80], grip: [-30, -30, 30, 10] };
+function wrapThumb(sk, s, side, [oppose, across, flex2, flex3]) {
+	const sign = side === "Left" ? -1 : 1, J = k => sk.index[`${side}HandThumb${k}`];
+	if (J(1) === undefined) return;
+	const { d, n } = palmAxes(sk, s, side);
+	rotateSubtree(sk, s, J(1), s.P[J(1)].slice(), axisRot(d, sign * oppose));
+	// n = d x l flips with the mirror, so the turn across the palm keeps its sign on both hands
+	rotateSubtree(sk, s, J(1), s.P[J(1)].slice(), axisRot(n, across));
+	for (const [k, deg] of [[2, flex2], [3, flex3]]) {
+		const ax = norm(cross(norm(sub(s.P[J(k + 1)], s.P[J(k)])), n));
+		rotateSubtree(sk, s, J(k), s.P[J(k)].slice(), axisRot(ax, sign * deg));
+	}
 }
 

package/src/motion3/compiler/pose.js

@@ -82,6 +82,21 @@ function hangOf(sk, down) {
 	return hang;
 }
 
+/**
+ * The frame the knee and elbow poles and the feet are read in once the whole body turns well past upright (a flip, a
+ * cartwheel): the root's yaw, pitch and roll, the tilt eased in from TILT_FROM to TILT_FULL degrees (the larger of the
+ * wrapped pitch and roll). Under TILT_FROM it is null and the poles turn with the yaw only, as they always have, so an
+ * upright take is unchanged.
+ */
+const TILT_FROM = 60, TILT_FULL = 120;
+const wrap180 = a => a - 360 * Math.round(a / 360);
+export function tiltFrame(yaw, pitch, roll) {
+	const p = wrap180(pitch), r = wrap180(roll), u = (Math.max(Math.abs(p), Math.abs(r)) - TILT_FROM) / (TILT_FULL - TILT_FROM);
+	if (u <= 0) return null;
+	const w = u >= 1 ? 1 : u * u * (3 - 2 * u);
+	return { yaw, R: mul(ry(yaw), mul(rx(p * w), rz(r * w))) };
+}
+
 export function pose(sk, c, hooks = {}) {
 	const s = restState(sk);
 	const diag = {};
@@ -107,7 +122,7 @@ export function pose(sk, c, hooks = {}) {
 	rotateSubtree(sk, s, hips, s.P[hips].slice(), mul(ry(yaw), mul(rx(num(c.pitch)), rz(num(c.roll)))));
 	const shift = sub(v3(c.root, s.P[hips]), s.P[hips]);
 	for (let j = 0; j < s.P.length; j++) s.P[j] = add(s.P[j], shift);
-	const body = ry(yaw);
+	const tilt = tiltFrame(yaw, num(c.pitch), num(c.roll)), body = tilt?.R ?? ry(yaw);
 	// Legs: two-bone IK to the ankle targets, the knee no further folded than its stop (limbs.js KNEE_STOP), then aim the feet.
 	for (const [k, side] of Object.entries(SIDES)) {
 		if (!c[`foot_${k}`]) continue;
@@ -117,7 +132,7 @@ export function pose(sk, c, hooks = {}) {
 		// a target nearer the hip than the knee folds leaves a residual (leg_miss); leg_fold says what it asked
 		const fold = askedFold(sk, s, side, target, LEG);
 		if (fold > KNEE_FOLD) diag[`leg_fold_${k}`] = fold;
-		orientFoot(sk, s, side, num(c[`fyaw_${k}`], yaw), num(c[`fpitch_${k}`]));
+		orientFoot(sk, s, side, num(c[`fyaw_${k}`], yaw), num(c[`fpitch_${k}`]), tilt);
 	}
 	// Arms: blend the FK hand toward the hook's target, poles blended the same way.
 	for (const k of hooks.armOrder ?? ["r", "l"]) {

package/src/motion3/compiler/socket-grip.js

@@ -0,0 +1,107 @@
+// The hand of a fit whose anchor takes a grasp (an object anchor with `grasp`, ../sockets.js) holds the object by its
+// socket: the palm frame comes from the socket (the knuckle line along its axis, the palm against the side the hand
+// comes from), not from the forearm's roll rule (grip.js). With no side given, the hand rolls about the axis to where
+// the arm holds it most easily, and where the forearm cannot come across the axis the knuckle line tilts on it (an
+// oblique grip, priced, up to TILT deg). The fingers' point stays where the fit put it; the elbow swivels to the pole
+// that leaves the wrist least strained (arm-orient.js, as a held object's hand, hold.js), the forearm takes its share of
+// the turn and the wrist the rest within its limits. Weighted by the fit's weight, so the hand turns into the grasp on
+// the reach and out of it on the release.
+// A hand that carries what it holds by a socket without keys keeps, after the grab, the wrist turn it had on the grab
+// frame against the forearm (diag.socket_<k>.rel, measured on the plain forearm before the turn): the object rides the
+// palm as it was taken (object-pose.js keeps the grab-frame offset), so neither the hand nor the object turns back. A
+// keyed carry's hand follows the keys (hold.js), whose grab offset is taken on that same grasp (object-keys.js attach).
+import { sub, norm, mul, T, axisRot } from "./math.js";
+import { palmAxes, twoBone } from "./limbs.js";
+import { aimArm, orient } from "./hold.js";
+import { ELBOW_REST, swivel } from "./arm-orient.js";
+import { anchorSocket } from "./anchors.js";
+import { socketPalm } from "../sockets.js";
+import { partsOf } from "../object-pose.js";
+
+const ITER = 3, ROLLS = 12, TEMP = 0.05, PULL = 0.3, DEG = 180 / Math.PI, TILT = 40, SLANT = 1, STEADY = 0.3;
+const TILTS = [-TILT, -TILT / 2, 0, TILT / 2, TILT];
+
+/** The Boltzmann-weighted mean of [value, cost] pairs at a softer temperature (STEADY): it moves smoothly between them. */
+function mean(all) {
+	const low = Math.min(...all.map(x => x[1])), e = all.map(([a, c]) => [a, Math.exp(-(c - low) / STEADY)]);
+	return e.reduce((m, [a, x]) => m + a * x, 0) / e.reduce((m, [, x]) => m + x, 0);
+}
+
+/** The Boltzmann-weighted circular mean of ROLLS angles under cost(th) (second-hand.js softmin). */
+function softmin(cost) {
+	const all = Array.from({ length: ROLLS }, (_, i) => { const th = (2 * Math.PI * i) / ROLLS - Math.PI; return [th, cost(th)]; }), low = Math.min(...all.map(x => x[1]));
+	const m = all.reduce((acc, [th, v]) => { const e = Math.exp(-(v - low) / TEMP); return [acc[0] + e * Math.cos(th), acc[1] + e * Math.sin(th)]; }, [0, 0]);
+	return Math.atan2(m[1], m[0]);
+}
+const cols = ({ d, l, n }) => [[d[0], l[0], n[0]], [d[1], l[1], n[1]], [d[2], l[2], n[2]]];
+
+/** True when the anchor named `name` takes a grasp (an object anchor with `grasp`). */
+export const graspAnchor = (spec, name) => spec.anchors?.[name]?.kind === "object" && !!spec.anchors[name].grasp;
+
+/** True when the agent's own keys (spec.keys, not a skill's or a generator's) turn hand k's wrist (wtwist_<k>, wflex_<k>). */
+export const ownWrist = (spec, k) => (spec.keys ?? []).some(key => (!key.src || key.src.startsWith("keys[")) && (key.set?.[`wtwist_${k}`] !== undefined || key.set?.[`wflex_${k}`] !== undefined));
+
+/** True when a grasp fit of hand k is anchored on body or group `id` (on it, a part of it, or a group holding it). */
+export function graspedBy(spec, scene, id, k) {
+	const parts = new Set(partsOf(scene, id));
+	return (spec.fits ?? []).some(fit => {
+		if (fit.side !== k || !graspAnchor(spec, fit.anchor)) return false;
+		const at = spec.anchors[fit.anchor].object;
+		return at === id || parts.has(at) || partsOf(scene, at).some(p => parts.has(p));
+	});
+}
+
+/** The carry hand k holds at frame f by a socket (graspedBy): { id, grab, keyed } for that spec.objects carry, else null. */
+export function socketCarry(ctx, k, f) {
+	const { spec, scene } = ctx;
+	if (!ctx.objectHand || !(spec.fits ?? []).some(fit => fit.side === k && graspAnchor(spec, fit.anchor))) return null;
+	for (const [id, o] of Object.entries(spec.objects ?? {})) if (o?.prop && ctx.objectHand(id, f) === k && graspedBy(spec, scene, id, k)) return { id, grab: ctx.carrySpan(o)[0], keyed: !!o.keys?.length };
+	return null;
+}
+
+/**
+ * socketHand(ctx, sk, s, side, k, c, diag, on, effector): turn the hand of fit `on` ({ fit, w }) into its anchor's
+ * socket grasp (see above); effector(st) is the fit's effector point on a pose.
+ */
+export function socketHand(ctx, sk, s, side, k, c, diag, on, effector) {
+	const I = sk.index, a = I[`${side}Arm`], fa = I[`${side}ForeArm`], h = I[`${side}Hand`], plain = s.R[fa];
+	const w = anchorSocket(ctx, on.fit.anchor, s, diag, c, k), F = effector(s), fwd = norm(sub(s.P[h], s.P[fa]));
+	const type = ctx.spec.anchors[on.fit.anchor].grasp, base = socketPalm(side, w, type, fwd, c.yaw);
+	const measure = st => ({ pos: effector(st), R: cols(palmAxes(sk, st, side)) }), now = measure(s);
+	// free to roll about its axis (no `from`): the roll the arm holds most easily, the Boltzmann mean of ROLLS rolls pulled
+	// lightly toward the fingers on the forearm's line, so the hand closes on the bar from the side the arm comes from
+	// then the knuckle line tilts on the bar (an oblique grip) up to TILT deg, priced, where the forearm cannot come across it
+	const strain = R => { const t = aimArm(sk, s, side, { pos: F, R }, now, 1, "palm"); return swivel(sk, s, side, t.goal, t.wristAt(t.goal), t.plane, ELBOW_REST).cost; };
+	const col = (M, i) => [M[0][i], M[1][i], M[2][i]], turned = th => mul(axisRot(col(base, 1), th * DEG), base);
+	const free = w.axis && !w.from && type !== "palm", roll = free ? softmin(th => strain(turned(th)) + PULL * (1 - Math.cos(th))) : 0;
+	const rolled = turned(roll), tilted = a => mul(axisRot(col(rolled, 2), a), rolled);
+	const tilt = w.axis && type !== "palm" ? mean(TILTS.map(a => [a, strain(tilted(a)) + SLANT * (a / TILT) ** 2])) : 0;
+	const R = tilted(tilt);
+	const { goal, plane, wristAt } = aimArm(sk, s, side, { pos: F, R }, now, on.w, "palm");
+	const arm = swivel(sk, s, side, goal, wristAt(goal), plane, ELBOW_REST, { w: on.w });
+	let need = { twist: 0, flex: 0, dev: 0 };
+	for (let i = 0; i < ITER; i++) {
+		twoBone(sk, s, a, fa, h, wristAt(i ? s.R[h] : goal), arm.pole, ELBOW_REST, "elbow");
+		need = orient(sk, s, side, h, fa, goal);
+	}
+	diag[`grip_${k}`] = { w: on.w, socket: true, ...need };
+	diag[`socket_${k}`] = { rel: mul(T(plain), s.R[h]) };
+}
+
+/**
+ * The hand of a socket carry after its grab keeps the grab frame's wrist turn against the forearm (see above), read
+ * once per bake (ctx.socketTurns) off the grab frame solved without the keys: a keyed carry's curve is built on
+ * frames solved without keys, which come here, so the keyed solve of the grab frame would need that curve again.
+ */
+export function keepSocketTurn(ctx, sk, s, side, k, carry) {
+	const key = `${k}:${carry.grab}`;
+	ctx.socketTurns ??= new Map();
+	if (!ctx.socketTurns.has(key)) {
+		ctx.socketTurns.set(key, null);
+		ctx.socketTurns.set(key, (ctx.hold?.plainFrame ?? ctx.solvedAt)(carry.grab)?.diag?.[`socket_${k}`]?.rel ?? null);
+	}
+	const rel = ctx.socketTurns.get(key);
+	if (!rel) return;
+	const I = sk.index, fa = I[`${side}ForeArm`], h = I[`${side}Hand`];
+	orient(sk, s, side, h, fa, mul(s.R[fa], rel));
+}

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

@@ -15,7 +15,7 @@ import { isFree } from "../free-motion.js";
 import { checkRef } from "../refs.js";
 import { partsOf } from "../object-pose.js";
 
-const KEY = "{ f, pos: [x, y, z], rot: [x, y, z, w] } or { f, pos, aim: [x, y, z], roll? }", FALL = "{ at, onto?, bounce? }";
+const KEY = "{ f, pos: [x, y, z], rot: [x, y, z, w] } or { f, pos, aim: [x, y, z], roll? }", FALL = "{ at, onto?, bounce?, tumble? }";
 const isQuat = q => Array.isArray(q) && q.length === 4 && q.every(Number.isFinite) && Math.abs(Math.hypot(...q) - 1) <= 0.01;
 const isDir = v => isVec3(v) && Math.hypot(...v) > 1e-9;
 
@@ -77,7 +77,7 @@ function frameOk(err, at, v, frames) {
 	return false;
 }
 
-/** objects.<id>.fall (C17): { at, onto?, bounce? } or a list, each on its own frame; a carry falls only out of hand. */
+/** objects.<id>.fall (C17): { at, onto?, bounce?, tumble? } or a list, each on its own frame; a carry falls only out of hand. */
 function validateFalls(err, unknown, at, o, { frames, scene, carry }) {
 	const list = Array.isArray(o.fall) ? o.fall : [o.fall], seen = new Set();
 	if (!list.length) err(`${at}.fall is an empty list; give ${FALL} or a list of them`);
@@ -94,6 +94,7 @@ function validateFalls(err, unknown, at, o, { frames, scene, carry }) {
 		}
 		if (fl.onto !== undefined) objectOk(err, scene, `${fat}.onto`, fl.onto, { groups: true });
 		if (fl.bounce !== undefined && !(Number.isFinite(fl.bounce) && fl.bounce >= 0 && fl.bounce <= 0.6)) err(`${fat}.bounce must be 0..0.6 (the share of its landing speed it bounces back with; 0 lands dead), got ${fmt(fl.bounce)}`);
+		if (fl.tumble !== undefined && typeof fl.tumble !== "boolean") err(`${fat}.tumble must be true (it rolls to rest on a stable face, the default) or false (it drops straight down as it was), got ${fmt(fl.tumble)}`);
 	});
 }
 

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

@@ -1,13 +1,15 @@
 // Validation of the spec parts other than keys: anchors, props, fits, generators, checks and
 // fix; objects (validate-objects.js) and goals (validate-goals.js) run from here too. Unknown
 // fields go through opts.unknown, which ignores them on a lenient reload. See validate.js.
-import { didYouMean, suggestField, CONVENTIONS, isVec3, fmt } from "./vocab.js";
+import { didYouMean, suggestField, CONVENTIONS, isVec3, fmt, GRASPS } from "./vocab.js";
 import { FIX_KEYS } from "../fix/index.js";
 import { QA_LIMITS } from "../qa/checks.js";
 import { ANCHOR_FIELDS, PROP_FIELDS, FIT_FIELDS, WALK_FIELDS, CHECK_FIELDS, CHECK_ENTRY_FIELDS } from "../schema/fields.js";
 import { boneOk, objectOk, refOk } from "./validate-common.js";
 import { validateObjects } from "./validate-objects.js";
 import { validateGoals } from "./validate-goals.js";
+import { personJoint, peopleList } from "../people.js";
+import { socketsOf, socketNamed } from "../sockets.js";
 
 const SIDE = new Set(["l", "r"]);
 const isObject = v => Boolean(v) && typeof v === "object" && !Array.isArray(v);
@@ -28,7 +30,12 @@ function validateAnchors(spec, err, { sk, scene, unknown = err }) {
 		if ((a.kind === "world" || a.kind === "body") && a.p === undefined) err(`${at} (${a.kind}) needs p: [x, y, z]${a.kind === "body" ? `, ${CONVENTIONS.pole}` : ""}`);
 		if (a.kind === "bone") boneOk(err, sk, at, a.bone);
 		if (a.kind === "segment") { boneOk(err, sk, `${at}.from`, a.from); boneOk(err, sk, `${at}.to`, a.to); if (a.reach !== undefined && !SIDE.has(a.reach)) err(`${at}.reach must be "l" or "r"`); }
-		if (a.kind === "object") objectOk(err, scene, at, a.object, { groups: true });
+		if (a.kind === "object" && objectOk(err, scene, at, a.object, { groups: true })) {
+			if (a.grasp !== undefined && !GRASPS.includes(a.grasp)) err(`${at}.grasp must be one of ${GRASPS.join(", ")}, got ${fmt(a.grasp)}`);
+			if (a.socket !== undefined && scene?.objects && !socketNamed(scene, a.object, a.socket)) err(`${at}.socket: "${a.object}" has no socket ${fmt(a.socket)} (sockets: ${socketsOf(scene, a.object).map(k => k.name).join(", ") || "none"})`);
+			if (a.socket !== undefined && a.grasp === undefined) err(`${at}.socket needs grasp (${GRASPS.join(", ")}): the socket says how the hand takes it`);
+		}
+		if (a.kind === "person" && !personJoint(scene, a.person, a.bone ?? "", 0)) err(`${at} (person) needs person: the id of another character with an installed take (people: ${peopleList(scene)}) and bone: one of its joints, got ${fmt(a.person)} ${fmt(a.bone)}`);
 		if (a.kind === "landmark" && a.name !== "mouth") err(`${at}: the only landmark is "mouth", got ${fmt(a.name)}`);
 		if (a.kind === "prop" && !spec.props?.[a.prop]?.points?.[a.point] && a.point !== "origin") err(`${at} needs prop point ${a.prop}.${a.point}, which spec.props does not define`);
 	}

package/src/motion3/compiler/validate.js

@@ -23,10 +23,10 @@ function checkValue(err, at, ch, v) {
 		if (!isVec3(v)) return err(`${at} ${ch} must be [x, y, z] (3 finite numbers), got ${fmt(v)}`);
 		if (POLE_CHANNELS.has(ch)) {
 			const l = Math.hypot(...v);
-			if (l < 1e-6) return err(`${at} ${ch} = ${fmt(v)} has no direction; a pole is ${CONVENTIONS.pole}`);
-			if (ch.startsWith("knee") && v[2] < -0.7 * l) err(`${at} ${ch} = ${fmt(v)} points backward; knees bend toward +z. A pole is ${CONVENTIONS.pole}`);
+			if (l < 1e-6) return err(`${at} ${ch} = ${fmt(v)} has no direction; a pole is a ${CONVENTIONS.pole}`);
+			if (ch.startsWith("knee") && v[2] < -0.7 * l) err(`${at} ${ch} = ${fmt(v)} points backward; knees bend toward +z. A pole is a ${CONVENTIONS.pole}`);
 		}
-		if (ch.startsWith("foot") && v[1] < 0.04) err(`${at} ${ch} y = ${v[1]} puts the ankle into the floor; foot_* is ${CONVENTIONS.foot}`);
+		if (ch.startsWith("foot") && v[1] < 0.04) err(`${at} ${ch} y = ${v[1]} puts the ankle into the floor; foot_* is the ${CONVENTIONS.foot}`);
 		return;
 	}
 	if (MAP_CHANNELS.has(ch)) {

package/src/motion3/compiler/vocab.js

@@ -11,36 +11,43 @@ export const MAP_CHANNELS = new Set(sided(["fingers"]));
 // Channels the skills key (standIdle, walks): valid in a spec, left out of motion.describe so a first spec need not read them.
 export const SKILL_CHANNELS = new Set(["arm_hang"]);
 export const FINGER_PRESETS = ["relaxed", "fist", "grip", "cigarette", "point"];
+/** The grasps an object anchor takes a hand by (../sockets.js), and the finger preset each closes the hand to by default. */
+export const GRASPS = ["power", "pinch", "hook", "palm"];
+export const GRASP_FINGERS = { power: "grip", pinch: "cigarette", hook: "grip", palm: "relaxed" };
+/** Where the held thing sits in the hand, [d, l, n] on the palm axes from the finger middles (n toward the palm; m): a bar in a
+ * power grip or a hook lies across the palm under the finger middles, a pinch is held at the fingertips, a flat palm presses with its centre. */
+export const GRASP_POINTS = { power: [0, 0, 0.02], hook: [0, 0, 0.02], pinch: [0.025, 0, 0.01], palm: [-0.045, 0, 0.015] };
 
 // [min, max, convention] for numeric channels whose values have a hard range.
 const RANGES = [
-	[/^(armw)_[lr]$/, 0, 1, "0 = FK arm, 1 = IK to the hand target"],
+	[/^(armw)_[lr]$/, 0, 1, "0 FK, 1 IK to the hand target"],
 	[/^arm_hang$/, 0, 1, "1 = a free FK forearm hangs plumb"],
-	[/^w_.+_[lr]$/, 0, 1, "a hand-target weight; the weights of one hand add up to at most 1"],
-	[/^wtwist_[lr]$/, -85, 85, "wrist twist about the forearm in degrees"],
-	[/^wflex_[lr]$/, -70, 70, "wrist flex about the knuckle line in degrees"],
-	[/^fpitch_[lr]$/, -60, 90, "toe-down pitch in degrees: + lifts the heel (the toes stay flat), - lifts the toes"],
-	[/^(pitch|spine_pitch|head_pitch)$/, -120, 120, "degrees, + bends forward"],
-	[/^(roll|spine_roll|head_roll)$/, -90, 90, "degrees"],
+	[/^w_.+_[lr]$/, 0, 1, "hand-target weight; a hand's sum <= 1"],
+	[/^wtwist_[lr]$/, -85, 85, "twist about the forearm, deg"],
+	[/^wflex_[lr]$/, -70, 70, "flex about the knuckle line, deg"],
+	[/^fpitch_[lr]$/, -60, 90, "toe-down pitch, deg: + lifts the heel (toes flat), - lifts the toes"],
+	// the whole-body pitch and roll have none: they turn in full (flips, cartwheels; pose.js tiltFrame)
+	[/^(spine_pitch|head_pitch)$/, -120, 120, "degrees, + bends forward"],
+	[/^(spine_roll|head_roll)$/, -90, 90, "degrees"],
 ];
 export const rangeOf = ch => RANGES.find(([re]) => re.test(ch)) ?? null;
 
 export const CONVENTIONS = {
 	yaw: "yaw 0 faces +Z and + turns toward +X",
-	fyaw: "foot heading in degrees, as yaw",
-	pole: "a body-frame direction (turned by the root yaw only): +z forward, +x the character's left, +y up",
-	foot: "the ANKLE target in world metres (standing: 0.087 X Bot, 0.105 Y Bot)",
-	hand: "the WRIST target in world metres",
-	root: "the hips joint in world metres (standing: 1.03 X Bot, 0.99 Y Bot)",
+	fyaw: "foot heading, as yaw",
+	pole: "body-frame direction (root yaw): +z forward, +x its left, +y up",
+	foot: "ANKLE target, world m (standing 0.087 X Bot, 0.105 Y Bot)",
+	hand: "WRIST target, world m",
+	root: "hips joint, world m (standing 1.03 X Bot, 0.99 Y Bot)",
 };
 
 /** What each channel family means (a family drops the _l/_r side), for motion.describe "channels". */
 export const CHANNEL_DOCS = {
-	root: CONVENTIONS.root, yaw: `degrees; ${CONVENTIONS.yaw}`, pitch: "whole-body pitch, degrees", roll: "whole-body roll, degrees",
-	spine_yaw: "degrees", spine_pitch: "degrees, + bends forward", spine_roll: "degrees", head_yaw: "degrees", head_pitch: "degrees, + looks down", head_roll: "degrees",
-	arm_rest: "FK arms down from the T-pose (default 72)", arm_hang: "1 = a free FK forearm hangs plumb (standIdle and walks key it)", foot: CONVENTIONS.foot, fyaw: CONVENTIONS.fyaw, fpitch: "toe-down pitch, degrees, + heel up",
+	root: CONVENTIONS.root, yaw: `deg; ${CONVENTIONS.yaw}`, pitch: "degrees", roll: "degrees",
+	spine_yaw: "degrees", spine_pitch: "deg, + bends forward", spine_roll: "degrees", head_yaw: "degrees", head_pitch: "degrees, + looks down", head_roll: "degrees",
+	arm_rest: "FK arms down, deg, default 72", arm_hang: "1 = a free FK forearm hangs plumb (standIdle and walks key it)", foot: CONVENTIONS.foot, fyaw: CONVENTIONS.fyaw, fpitch: "toe-down pitch, degrees, + heel up",
 	knee: `knee pole, ${CONVENTIONS.pole}`, armw: "0 = FK arm, 1 = IK to hand_* / the anchors", hand: CONVENTIONS.hand, elbow: `elbow pole, ${CONVENTIONS.pole}`,
-	wtwist: "wrist twist, degrees", wflex: "wrist flex, degrees", aswing: "FK arm swing, degrees, + forward", abend: "FK elbow bend, degrees",
+	wtwist: "wrist twist, degrees", wflex: "wrist flex, degrees", aswing: "FK arm swing, deg, + forward", abend: "FK elbow bend, deg",
 	fingers: "{ preset: weight 0..1 }",
 };
 export const channelFamily = ch => ch.replace(/_[lr]$/, "");

package/src/motion3/describe.js

@@ -81,7 +81,7 @@ const SCHEMAS = {
 	probes: () => listOf({ ...objectOf(PROBE_FIELDS, PROBE_TYPES, "probes", ["name"]), ...oneOfRequired(["distance", "position"]) }, { maxItems: 16 }),
 	channels: () => ({ type: "object", description: "key.set: channel -> value",
 		properties: Object.fromEntries([...VEC_CHANNELS, ...NUM_CHANNELS, ...MAP_CHANNELS].filter(ch => !SKILL_CHANNELS.has(ch)).map(ch => [ch, channelSchema(ch)])),
-		patternProperties: { "^w_.+_[lr]$": { type: "number", minimum: 0, maximum: 1, description: rangeOf("w_a_l")[3] }, "_vis$": { type: "number", description: "shown above 0.5" } },
+		patternProperties: { "^w_.+_[lr]$": { type: "number", minimum: 0, maximum: 1, description: rangeOf("w_a_l")[3] }, "_vis$": { type: "number", description: "shown > 0.5" } },
 		additionalProperties: { type: "number", description: "spec.channels, an object's or a check's when" } }),
 	refs: () => ({ type: "string", oneOf: REF_KINDS.map(k => ({ pattern: `^${k}:`, description: typeOf(REF_DOCS, k, "refs") })) }),
 	fix: () => ({ oneOf: [{ const: false }, objectOf(FIX_KEYS, FIX_TYPES, "fix")] }),
@@ -103,6 +103,8 @@ function describeSkill(name) {
 const MEANT = { topics: ["objects", "channels"], skills: ["reachGrip"] };
 /** Topics no round-2 session needed for a first spec: essentials names their parts, the full topic has the fields. */
 const SHALLOW = ["checks"];
+/** Skills essentials leaves to topic skills: a flip or cartwheel is no first spec's need, and essentials has no room. */
+const FIRST_SPEC_SKIP = ["flip"];
 
 /** A shared shape whose fields are mostly a skill's args (walk, walkTo): its own fields and `...<skill> args`. */
 function shapeLine(d) {
@@ -134,7 +136,8 @@ function essentials() {
 	}
 	// use.skill without the enum: the skills list below names them
 	if (shared.use) shared.use = objectOf(USE_FIELDS, USE_TYPES, "use", ["skill", "f0"]);
-	const skills = SKILL_NAMES.map(n => {
+	// a skill no first spec needs (FIRST_SPEC_SKIP) is in topic skills only
+	const skills = SKILL_NAMES.filter(n => !FIRST_SPEC_SKIP.includes(n)).map(n => {
 		const { args, required = [], needs, frames, adds } = SKILL_INFO[n] ?? bad(`describe: skill ${n} has no entry in skills/info.js`);
 		return { name: n, args: briefType({ type: "object", properties: args, required }, { means: MEANT.skills.includes(n) }), needs, frames, adds };
 	});

package/src/motion3/docs.js

@@ -6,7 +6,7 @@ export const MOTION_ACTION_HELP = {
 		+ "Send spec, or base (an answered specId) + optional patch (JSON Patch); base alone or patch: [] re-measures (new probes). "
 		+ "spec = { schema: \"cozyclay.motion-spec.v1\", fps: 24, frames (number or \"auto\"), ... } (parts: motion.describe); any number may be { range: [lo, hi] } (searched). "
 		+ "probes (at most 16, request level; spec.probes: measured, not stored): { name, distance: [ref, ref] | position: ref, frames, every? }. "
-		+ "Refs need a prefix (joint: prop: anchor: landmark: object:; goals[].moved: a bare id too) and take loose bone names (any case); spec.checks need exact ones. "
+		+ "Refs need a prefix (joint: prop: anchor: landmark: object: person:; goals[].moved: a bare id too) and take loose bone names (any case); spec.checks need exact ones. "
 		+ "repair: { rounds } (1-8, default 4) applies group patches while severity drops. "
 		+ "qa judges only what is broken; speed, acceleration, balance, knee bend are observations unless checks.limits names them. "
 		+ "Answers frames, installed, specId, qa { ok, total, goals, groups (GOAL first, then severity; cause, hint, patch?) }, observations, delta (with base), repair, probes, timeline, fixed, search, skills. output.more: motion.report pages the rest.",