cozyclay 3.0.3 → 3.1.0

package/src/motion3/body.js

@@ -3,11 +3,43 @@
 // outside positive, metres) and, for the limbs, the skin radius along the bone. A limb collides as
 // spheres on its bone axis (limbProbes); bodyDistance is the nearest skin of every other bone but
 // the limb's own neighbours (SKIP), so an arm reads the torso, the head, the legs and the other arm.
-import yBody from "./rigs/y-bot-tpose-body.json" with { type: "json" };
-import xBody from "./rigs/x-bot-tpose-body.json" with { type: "json" };
 import { add, sub, scale, apply, T, len, dot, clamp } from "./compiler/math.js";
 
-const BODIES = { "y-bot-tpose": yBody, "x-bot-tpose": xBody };
+// The fits are ~0.5 MB of base64 grids, most of the editor's first-load JavaScript were they imported: each
+// is an asset file instead, read the first time a compile needs it. Node reads it from disk; a worker (or the
+// editor, should a compile run before preloadBodies has it) reads it synchronously over HTTP, so bodyFor
+// stays synchronous everywhere. The editor fetches both in the background after its first paint (main.jsx).
+const BODIES = {
+	"y-bot-tpose": new URL("./rigs/y-bot-tpose-body.json", import.meta.url),
+	"x-bot-tpose": new URL("./rigs/x-bot-tpose-body.json", import.meta.url),
+};
+const fits = new Map();
+
+function readFit(url) {
+	const fs = url.protocol === "file:" ? globalThis.process?.getBuiltinModule?.("node:fs") : null;
+	if (fs) return JSON.parse(fs.readFileSync(url, "utf8"));
+	const xhr = new XMLHttpRequest();
+	xhr.open("GET", url.href, false);
+	xhr.send();
+	if (xhr.status !== 200) throw new Error(`motion body fit ${url.pathname}: HTTP ${xhr.status}`);
+	return JSON.parse(xhr.responseText);
+}
+
+function fitOf(model) {
+	if (!fits.has(model)) fits.set(model, readFit(BODIES[model]));
+	return fits.get(model);
+}
+
+/** Fetches every rig's fit in the background, so a compile on this thread never waits on one. */
+export function preloadBodies() {
+	return Promise.all(Object.entries(BODIES).map(async ([model, url]) => {
+		if (fits.has(model)) return;
+		const response = await fetch(url);
+		if (!response.ok) throw new Error(`motion body fit ${url.pathname}: HTTP ${response.status}`);
+		const fit = await response.json();
+		if (!fits.has(model)) fits.set(model, fit);
+	}));
+}
 /** Distance read outside a grid: far enough that no probe counts it as touching. */
 const FAR = 0.1;
 const cache = new Map();
@@ -28,9 +60,9 @@ function skipOf(sk, b) {
 
 /** The fitted body of skeleton sk, or null for a rig without one. */
 export function bodyFor(sk) {
-	const fit = BODIES[sk.model];
-	if (!fit) return null;
+	if (!BODIES[sk.model]) return null;
 	if (cache.has(sk.model)) return cache.get(sk.model);
+	const fit = fitOf(sk.model);
 	const grids = Object.entries(fit.grids).map(([name, g]) => {
 		const half = g.dims.map(d => ((d - 1) * fit.step) / 2), centre = g.min.map((m, k) => m + half[k]);
 		return { b: sk.index[name], min: g.min, dims: g.dims, data: decode(g.data), centre, reach: len(half) };

package/src/motion3/carried.js

@@ -8,6 +8,7 @@
 import { palmAxes } from "./compiler/limbs.js";
 import { SIDES } from "./compiler/pose.js";
 import { add, scale, norm, sub, dot, cross, apply, mul, T, axisRot, I3 } from "./compiler/math.js";
+import { bonePoint } from "./compiler/skeleton.js";
 
 export const isCarried = o => typeof o?.prop === "string";
 /** A follow entry { follow: <ref>, offset?, aim?, visible?, level? } (C16, follow.js): the record rides a point of the body. */
@@ -23,9 +24,16 @@ export function propOrigin(sk, spec, s, o) {
 	return scale(prop.origin.map(b => s.P[sk.index[b]]).reduce((a, p) => add(a, p), [0, 0, 0]), 1 / prop.origin.length);
 }
 
-/** World { pos, R } of a carried record on pose s (at/along offset, PR #14). */
-export function carriedPose(sk, spec, s, o) {
-	const ax = palmAxes(sk, s, SIDES[spec.props[o.prop].hand]), origin = propOrigin(sk, spec, s, o);
+/** The prop origin carried by its hand's bone on pose s, where the bind pose has it against the hand: closing fingers do not move it (#816). */
+function handOrigin(sk, prop, s) {
+	const h = sk.index[`${SIDES[prop.hand]}Hand`], P = sk.restWorldPos;
+	const mean = scale(prop.origin.map(b => P[sk.index[b]]).reduce((a, p) => add(a, p), [0, 0, 0]), 1 / prop.origin.length);
+	return bonePoint(s, h, apply(T(sk.restWorldRot[h]), sub(mean, P[h])));
+}
+
+/** World { pos, R } of a carried record on pose s (at/along offset, PR #14); `fixed`: the origin rides the hand bone (seat.js). */
+export function carriedPose(sk, spec, s, o, fixed = false) {
+	const ax = palmAxes(sk, s, SIDES[spec.props[o.prop].hand]), origin = fixed ? handOrigin(sk, spec.props[o.prop], s) : propOrigin(sk, spec, s, o);
 	const palm = v => add(scale(ax.d, v[0]), add(scale(ax.l, v[1]), scale(ax.n, v[2])));
 	const y = norm(palm(o.along ?? [0, 0, 1]));
 	let x = sub(ax.d, scale(y, dot(ax.d, y)));

package/src/motion3/compile-job.js

@@ -1,6 +1,6 @@
 // One motion compile as a job of plain data, the same in the compile worker (compile-worker.js) and on
 // the calling thread (commands/motion3-compile.js, where no worker runs: Node, tests): the rig by model
-// name, the motion scene (scene.js motionScene of the editor's objects: boxes only), the spec as sent, and
+// name, the motion scene (scene.js motionScene of the editor's objects: oriented boxes; shapes.js reads a sphere or a cylinder round from them), the spec as sent, and
 // what to do with it (probes, checks, lenient, repair, bake). The answer is plain data and typed arrays
 // only (the compiler's out holds closures), so it crosses a worker boundary: QA, observations, the stored
 // spec, and the baked take when asked.

package/src/motion3/compiler/compile.js

@@ -35,6 +35,8 @@ import { fitWeight } from "../fix/self.js";
 import { holdHook } from "../object-keys.js";
 import { HAND_CLEAR, keepOut, wristBody } from "../body.js";
 import { objectPoseAt, handOf, restingAt, frameAt, spanOf } from "../object-pose.js";
+import { heldFor } from "./finger-close.js";
+import { sagOf } from "../load.js";
 
 const smooth = x => x * x * (3 - 2 * x);
 // how far past the straight arm a grasp fit's wrist target may end before it counts as wound up (solveFrame), m
@@ -136,6 +138,10 @@ function hooksFor(ctx, c, f, inFit = false, lead = true, fitSide = null) {
 		afterArm: (k, s, diag) => measureProps(ctx, k, s, diag),
 		// a fit's passes only place the wrist; the final pose (and a plain one) turns the hand onto the body
 		grip: inFit ? undefined : (k, s, diag) => gripHand(ctx, sk, s, SIDES[k], k, c, f, diag),
+		// a carry's weight lowers a plain IK hand's target, on the final pose only (load.js)
+		sag: inFit ? undefined : (k, s, target) => sagOf(ctx, k, f, s, target, (1 - fitWeight(ctx.spec, c, k)) * Math.min(1, Math.max(0, c[`armw_${k}`] ?? 0))),
+		// fingers close on what the hand holds, on the final pose only (finger-close.js)
+		heldShapes: inFit || !ctx.grasp ? undefined : (k, s) => heldFor(ctx, c, f, k, s),
 	};
 }
 
@@ -186,7 +192,7 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	if (!(frameCount >= 1 && frameCount <= 20000)) throw new Error("MOTION_SPEC_INVALID: frames must be 1..20000");
 	const fix = fixOptions(spec.fix);
 	const [a, b] = opts.window ? [Math.max(0, opts.window[0]), Math.min(frameCount - 1, opts.window[1])] : [0, frameCount - 1];
-	const ctx = { sk, spec, scene, softReach: fix.reach, push: { l: new Map(), r: new Map() }, swivel: { l: new Map(), r: new Map() }, skinPush: { l: new Map(), r: new Map() }, keepOut: fix.self ? wristBody(sk) : null };
+	const ctx = { sk, spec, scene, grasp: fix.grasp, softReach: fix.reach, push: { l: new Map(), r: new Map() }, swivel: { l: new Map(), r: new Map() }, skinPush: { l: new Map(), r: new Map() }, keepOut: fix.self ? wristBody(sk) : null };
 	const out = { ctx, fps: spec.fps ?? 30, frameCount, f0: a, frames: [] };
 	// object anchors read the pose refs read (object-pose.js), on the frame being solved
 	ctx.objectPose = (id, f, now) => objectPoseAt(out, id, f, now);

package/src/motion3/compiler/finger-close.js

@@ -0,0 +1,137 @@
+// Fingers close on what the hand holds (#816). A preset curls each phalanx a fixed angle, which fits one size: on a
+// ball the index and middle sank 3 cm into it while the little finger stayed in the air (session 7f15b4ae). After the
+// arm, the hold and the elbow's swivel have placed the hand (pose.js), each finger closes phalanx by phalanx, from the
+// knuckle out: the joint turns further about the axis it curls on until the rest of the finger first touches a held
+// shape (shapes.js; its skin within TOUCH m of the surface), never past the fist's curl; a finger that cannot reach it
+// keeps the preset's curl (closing on air would curl it into whatever lies under the palm). The thumb keeps the preset's
+// turn at its base and flexes its outer joints the same way. Found by bisection (STEPS evaluations a joint) on the joints' positions,
+// then turned once; weighted by how far the hand holds (a fit's weight), so the fingers close over the reach and open
+// on the release. A joint the preset curled into the body straightens when that leaves the finger shallower; a
+// joint whose sub-chain already touches stays, and the next joint out closes on: the finger wraps the body.
+import { add, sub, scale, norm, cross, apply, axisRot } from "./math.js";
+import { rotateSubtree } from "./skeleton.js";
+import { palmAxes, fingerCurl, fistCurl } from "./limbs.js";
+import { capsuleDepth } from "../shapes.js";
+import { partsOf } from "../object-pose.js";
+import { seatsInHand } from "../seat.js";
+
+const PHALANX = 0.009, TOUCH = 0.002, STEPS = 8, THUMB_FLEX = 70;
+const FINGERS = ["Index", "Middle", "Ring", "Pinky"];
+// the hand stays open for most of a reach and closes as it arrives: from OPEN_UNTIL of the fit's weight to CLOSED_AT
+const OPEN_UNTIL = 0.6, CLOSED_AT = 0.9;
+const closing = w => { const t = Math.min(1, Math.max(0, (w - OPEN_UNTIL) / (CLOSED_AT - OPEN_UNTIL))); return t * t * (3 - 2 * t); };
+
+function chainDepth(points, entries) {
+	let depth = -Infinity;
+	for (let i = 0; i + 1 < points.length; i++) for (const e of entries) depth = Math.max(depth, capsuleDepth(e, points[i], points[i + 1], PHALANX));
+	return depth;
+}
+
+/** The turn (deg, 0..limit) about unit `axis` at `pivot` at which the chain first touches: 0 when it already does, null when it never does. */
+function touchTurn(points, pivot, axis, limit, entries) {
+	if (limit <= 0 || chainDepth(points, entries) >= -TOUCH) return 0;
+	const at = deg => { const R = axisRot(axis, deg); return points.map(p => add(pivot, apply(R, sub(p, pivot)))); };
+	if (chainDepth(at(limit), entries) < -TOUCH) return null;
+	let lo = 0, hi = limit;
+	for (let i = 0; i < STEPS; i++) { const mid = (lo + hi) / 2; if (chainDepth(at(mid), entries) >= -TOUCH) hi = mid; else lo = mid; }
+	return hi;
+}
+
+/** The turn (deg, 0..limit) back about `axis` that takes a chain inside the body just out of it (0 when it is out, or when
+ * no opening leaves it shallower). */
+function clearTurn(points, pivot, axis, limit, entries) {
+	if (chainDepth(points, entries) < -TOUCH) return 0;
+	const at = deg => { const R = axisRot(axis, -deg); return points.map(p => add(pivot, apply(R, sub(p, pivot)))); };
+	// a chain that stays in the body however far it opens opens only if that leaves it shallower
+	if (chainDepth(at(limit), entries) >= -TOUCH) return chainDepth(at(limit), entries) < chainDepth(points, entries) ? limit : 0;
+	let lo = 0, hi = limit;
+	for (let i = 0; i < STEPS; i++) { const mid = (lo + hi) / 2; if (chainDepth(at(mid), entries) < -TOUCH) hi = mid; else lo = mid; }
+	return hi;
+}
+
+/** Turns joint j by the touching turn about `axis` (or `limit` when it never touches, unless `air` is false), weighted; true when it touched. */
+function closeJoint(sk, s, j, chain, axis, limit, entries, weight, air = true) {
+	const turn = touchTurn(chain.map(i => s.P[i]), s.P[j], axis, limit, entries), deg = turn ?? (air ? limit : 0);
+	if (deg > 0) rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(axis, deg * weight));
+	return turn !== null;
+}
+
+/**
+ * closeOnShape(sk, s, side, { entries, weight, preset }): the hand on pose s ("Left" | "Right") closes on the shape
+ * entries (motion-scene entries at this frame) by `weight` 0..1; `preset` is the hand's finger weights (its fingers_<k>
+ * channel), from which each joint may close as far as the fist's curl. Answers { touched: the fingers that reached it }.
+ */
+export function closeOnShape(sk, s, side, { entries: held, stops = [], weight, preset }) {
+	if (!held?.length || !(weight > 0)) return { touched: [] };
+	// a finger stops on what it holds or on what that rests against (a table under a ball)
+	const entries = [...held, ...stops];
+	const sign = side === "Left" ? -1 : 1, J = name => sk.index[`${side}Hand${name}`], touched = [];
+	for (const f of FINGERS) {
+		const joints = [1, 2, 3, 4].map(i => J(`${f}${i}`));
+		if (joints.some(j => j === undefined)) continue;
+		let tip = false;
+		// a finger the preset curled into the body straightens, joint by joint, when the straight finger is shallower (a
+		// finger lying across a box would go deeper); each joint then closes until the finger touches
+		const pts = joints.map(i => s.P[i]), l0 = scale(palmAxes(sk, s, side).l, sign);
+		const straight = [0, 1, 2].reduce((p, k) => { const R = axisRot(l0, -fingerCurl(preset, f, k)); return p.map((q, i) => (i > k ? add(p[k], apply(R, sub(q, p[k]))) : q)); }, pts);
+		const opens = chainDepth(pts, held) >= -TOUCH && chainDepth(straight, held) < chainDepth(pts, held);
+		for (let k = 0; k < 3; k++) {
+			const axis = scale(palmAxes(sk, s, side).l, sign), curl = fingerCurl(preset, f, k), open = opens ? curl : 0;
+			if (open > 0) rotateSubtree(sk, s, joints[k], s.P[joints[k]].slice(), axisRot(axis, -open * weight));
+			tip = closeJoint(sk, s, joints[k], joints.slice(k), axis, Math.max(0, fistCurl(f, k) - curl + open), entries, weight, false);
+		}
+		if (tip) touched.push(f);
+	}
+	const thumb = [1, 2, 3, 4].map(i => J(`Thumb${i}`));
+	if (thumb.every(j => j !== undefined)) {
+		// the thumb keeps the preset's turn at its base (wrapThumb); its two outer joints back out of the body when the
+		// preset wrapped them into it, then flex until the thumb touches (one that cannot reach it keeps the preset's flex)
+		const { n } = palmAxes(sk, s, side);
+		let reached = false;
+		for (const k of [1, 2]) {
+			const axis = scale(norm(cross(norm(sub(s.P[thumb[k + 1]], s.P[thumb[k]])), n)), sign);
+			const out = clearTurn(thumb.slice(k).map(i => s.P[i]), s.P[thumb[k]], axis, THUMB_FLEX, entries);
+			if (out > 0) rotateSubtree(sk, s, thumb[k], s.P[thumb[k]].slice(), axisRot(axis, -out * weight));
+			reached = closeJoint(sk, s, thumb[k], thumb.slice(k), axis, THUMB_FLEX, entries, weight, false);
+		}
+		if (reached) touched.push("Thumb");
+	}
+	return { touched };
+}
+
+/**
+ * What hand k closes on at frame f with channels c: the object of its heaviest fit on an object anchor with grasp, while
+ * that object is not in its hand yet (a carry's hand holds it by its seat, seat.js), as { entries, weight, preset }; null
+ * when it reaches for nothing.
+ */
+export function heldFor(ctx, c, f, k, s) {
+	let best = null;
+	for (const fit of ctx.spec.fits ?? []) {
+		const a = ctx.spec.anchors?.[fit.anchor], w = c[`w_${fit.anchor}_${k}`] ?? 0;
+		if (fit.side !== k || a?.kind !== "object" || !a.grasp || !(w > 1e-4) || (best && best.weight >= w) || ctx.objectHand(a.object, f) === k) continue;
+		// a disc's rim socket (a steering wheel) is a ring the scene draws as a solid disc: the hand keeps its rim grip
+		if (ctx.sockets?.get(fit.anchor)?.rim) continue;
+		const at = ctx.objectsAt(f), entries = partsOf(ctx.scene, a.object).map(p => at[p]).filter(Boolean);
+		// as far as the skill has the hand closing (reachGrip keys its grip late in the reach: skills/reach-human.js)
+		const grip = Math.min(1, Object.entries(c[`fingers_${k}`] ?? {}).reduce((acc, [p, v]) => acc + (p === "relaxed" ? 0 : v || 0), 0));
+		if (entries.length) best = { entries, weight: closing(w) * grip, preset: c[`fingers_${k}`] };
+	}
+	return best ?? carriedFor(ctx, c, f, k, s);
+}
+
+/** A carry on the grasp path hand k holds at frame f, at its seat on pose s (seat.js), as { entries, weight, preset }. */
+function carriedFor(ctx, c, f, k, s) {
+	const { spec, scene } = ctx;
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		if (!seatsInHand(spec, o, scene, id) || spec.props?.[o.prop]?.hand !== k || !s) continue;
+		// the hand holds it from the grab on (the object eases into its seat meanwhile, settleAt)
+		const [grab, release] = ctx.carrySpan(o), weight = 1;
+		// while the keyed offset is being taken (its grab frame solved without the keys) the hand has nothing seated yet
+		if (f < grab || f > release || ctx.hold?.attaching(id)) continue;
+		// where it is on this pose (object-pose.js: easing into its seat over the settle, as it is drawn), not the full seat
+		const entries = partsOf(scene, id).map(p => ({ ...scene.objects[p], ...ctx.objectPose(p, f, { s }) }));
+		const near = Object.entries(ctx.objectsAt(f)).filter(([key, e]) => !partsOf(scene, id).includes(key) && e.half && !e.carried && entries.some(h => Math.hypot(...h.pos.map((v, i) => v - e.pos[i])) < 0.25 + Math.hypot(...e.half))).map(([, e]) => e);
+		if (entries.length) return { entries, stops: near, weight, preset: c[`fingers_${k}`] };
+	}
+	return null;
+}

package/src/motion3/compiler/limbs.js

@@ -158,12 +158,27 @@ const FINGER_PRESETS = {
 	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] },
+	spherical: { Index: [35, 40, 25], Middle: [38, 42, 25], Ring: [40, 42, 25], Pinky: [42, 44, 25], Thumb: [15, 10, 8] },
 };
+// A ball's fingers fan out round it (#816): each finger turns about the palm normal at its knuckle, degrees toward the
+// thumb side (+), by preset weight; the index leads the thumb round one side, the little finger the other.
+const SPREAD = { spherical: { Index: 9, Middle: 2, Ring: -5, Pinky: -12 } };
+
+/** Degrees phalanx k (0..2) of finger f curls at preset weights `weights` (blended over relaxed). */
+export function fingerCurl(weights, f, k) {
+	const base = FINGER_PRESETS.relaxed;
+	return base[f][k] + Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * ((FINGER_PRESETS[p]?.[f]?.[k] ?? base[f][k]) - base[f][k]), 0);
+}
+/** The fist's curl of phalanx k of finger f: as far as a finger closes. */
+export const fistCurl = (f, k) => FINGER_PRESETS.fist[f][k];
 
 /** Blend presets by weight over `relaxed` and curl every finger toward the palm. */
 export function fingers(sk, s, side, weights) {
-	const base = FINGER_PRESETS.relaxed, sign = side === "Left" ? -1 : 1;
-	const curl = (f, k) => base[f][k] + Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * ((FINGER_PRESETS[p]?.[f]?.[k] ?? base[f][k]) - base[f][k]), 0);
+	const sign = side === "Left" ? -1 : 1, curl = (f, k) => fingerCurl(weights, f, k);
+	for (const f of ["Index", "Middle", "Ring", "Pinky"]) {
+		const spread = Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * (SPREAD[p]?.[f] ?? 0), 0), j = sk.index[`${side}Hand${f}1`];
+		if (spread && j !== undefined) rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(palmAxes(sk, s, side).n, spread));
+	}
 	for (const f of ["Index", "Middle", "Ring", "Pinky", "Thumb"]) {
 		for (let k = 0; k < 3; k++) {
 			const j = sk.index[`${side}Hand${f}${k + 1}`];
@@ -181,7 +196,7 @@ export function fingers(sk, s, side, weights) {
 // 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] };
+const THUMB_WRAP = { fist: [-70, -5, 5, 80], grip: [-30, -30, 30, 10], spherical: [-40, -20, 20, 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;

package/src/motion3/compiler/pose.js

@@ -6,6 +6,7 @@ import { add, sub, scale, norm, len, apply, mul, rx, ry, rz } from "./math.js";
 import { restState, rotateSubtree } from "./skeleton.js";
 import { twoBone, orientFoot, wrist, fingers, limitFold, askedFold, swivelElbow, ELBOW_FOLD, KNEE_FOLD } from "./limbs.js";
 import { holdHand } from "./hold.js";
+import { closeOnShape } from "./finger-close.js";
 import { clampWrist } from "./wrist-clamp.js";
 import { ELBOW_REST } from "./arm-orient.js";
 import { wristBody, bodyDistance } from "../body.js";
@@ -147,6 +148,9 @@ export function pose(sk, c, hooks = {}) {
 			if (hooks.keepOut) target = hooks.keepOut(k, s, target);
 			const push = hooks.push?.(k);
 			if (push) target = add(target, push);
+			// what the hand carries weighs it down (load.js)
+			const sag = hooks.sag?.(k, s, target);
+			if (sag) target = add(target, sag);
 			// the self fix's push rides the IK as far as the arm is on it (an arm coming in from FK would jump)
 			const skinPush = hooks.skinPush?.(k);
 			if (skinPush) target = add(target, scale(skinPush, turnWeight(w)));
@@ -171,6 +175,8 @@ export function pose(sk, c, hooks = {}) {
 		// the turn keeps the hand's world turn; a wrist it takes past its limits stops there and the hand turns with the elbow
 		// (wrist-clamp.js), unless keys lead what the hand holds: that hand keeps the object's grip (hold.js limits its wrist)
 		if (turn) { swivelElbow(sk, s, side, turn * turnWeight(w)); if (!held) clampWrist(sk, s, side); }
+		const grasped = hooks.heldShapes?.(k, s);
+		if (grasped) diag[`closed_${k}`] = closeOnShape(sk, s, side, grasped).touched;
 		hooks.afterArm?.(k, s, diag);
 	}
 	return { s, diag };

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

@@ -7,7 +7,7 @@
 // of the body. A free entry { keys?, fall?, visible?, level? } (C17: no prop, no follow, no hinge field) moves a body or a
 // group on its own: world pose keys over the whole take, and gravity falls; a carry takes fall too, before its grab
 // or from its release on. Fields: schema/fields.js OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS. See validate.js.
-import { isVec3, fmt, didYouMean } from "./vocab.js";
+import { isVec3, fmt, didYouMean, GRASPS } from "./vocab.js";
 import { objectOk } from "./validate-common.js";
 import { OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS } from "../schema/fields.js";
 import { isSwitch, isFollow, movesRecord } from "../carried.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?, tumble? }";
+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?, v? }";
 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;
 
@@ -94,10 +94,23 @@ 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.v !== undefined && !((carry && fl.v === "hand") || isVec3(fl.v))) err(`${fat}.v must be [vx, vy, vz] m/s (the velocity it leaves with)${carry ? " or \"hand\" (the velocity the hand gives it at the release)" : ""}, got ${fmt(fl.v)}`);
 		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)}`);
 	});
 }
 
+/** A grasp that starts like the given one (4+ letters: "sphere" -> spherical), else the nearest by edit distance. */
+const prefixLen = (a, b) => { let i = 0; while (i < a.length && a[i] === b[i]) i += 1; return i; };
+function graspHint(given) {
+	const text = String(given), best = GRASPS.reduce((a, b) => (prefixLen(b, text) > prefixLen(a, text) ? b : a));
+	return prefixLen(best, text) >= 4 ? `; did you mean "${best}"?` : didYouMean(text, GRASPS);
+}
+
+/** mass (kg): what the object weighs, for the arm that holds it (#816). */
+function massOk(err, at, o) {
+	if (o.mass !== undefined && !(Number.isFinite(o.mass) && o.mass >= 0.01 && o.mass <= 60)) err(`${at}.mass must be kg in 0.01..60, got ${fmt(o.mass)}`);
+}
+
 /** visible and level name channels (C15): visible shows the record above 0.5, level scales its light, glow and effect rate. */
 function channelsOk(err, at, o) {
 	if (o.visible !== undefined && (typeof o.visible !== "string" || !o.visible)) err(`${at}.visible must name a channel (shown above 0.5)`);
@@ -110,6 +123,7 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 		// a switch and a follow take any record (a light, an effect); the others a body or a group
 		if ((kind !== "switch" && kind !== "follow") || !scene?.others?.[id]) objectOk(err, scene, at, id, { groups: true });
 		for (const f of Object.keys(o ?? {})) if (!fields.includes(f) && !(kind === "hinge" && (f === "keys" || f === "fall"))) unknown(`${at} (${kind}) has unknown field "${f}"${didYouMean(f, fields)}; fields: ${fields.join(", ")}`);
+		massOk(err, at, o);
 		if (kind === "follow") {
 			validateFollow(spec, err, { sk, scene }, at, o);
 			channelsOk(err, at, o);
@@ -129,6 +143,7 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 		if (kind === "carry") {
 			if (!spec.props?.[o.prop]) err(`${at}.prop "${o.prop}" is not in spec.props`);
 			for (const f of ["at", "along"]) if (o[f] !== undefined && !isVec3(o[f])) err(`${at}.${f} must be [d, l, n] along the palm axes, got ${fmt(o[f])}`);
+			if (o.grasp !== undefined && !GRASPS.includes(o.grasp)) err(`${at}.grasp must be one of ${GRASPS.join(", ")}${graspHint(o.grasp)}, got ${fmt(o.grasp)}`);
 			channelsOk(err, at, o);
 			if (frameOk(err, `${at}.grab`, o.grab, frames) && frameOk(err, `${at}.release`, o.release, frames)
 				&& o.grab !== undefined && o.release !== undefined && !(o.grab < o.release)) err(`${at}: grab (${o.grab}) must come before release (${o.release})`);

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

@@ -107,8 +107,9 @@ function validateChecks(spec, err, { sk, scene, frames, unknown = err, past = ""
 	each("allow");
 	for (const name of Object.keys(c.limits ?? {})) if (!(name in QA_LIMITS)) unknown(`checks.limits.${name} is not a QA limit${didYouMean(name, Object.keys(QA_LIMITS))}`);
 	const fix = spec.fix;
-	if (fix !== undefined && fix !== false && (typeof fix !== "object" || fix === null)) err("spec.fix must be false or { reach, slide, penetration, self, retime }");
+	if (fix !== undefined && fix !== false && (typeof fix !== "object" || fix === null)) err(`spec.fix must be false or { ${FIX_KEYS.join(", ")} }`);
 	else for (const k of Object.keys(fix || {})) if (!FIX_KEYS.includes(k)) unknown(`spec.fix.${k} is not a fix${didYouMean(k, FIX_KEYS)} (fixes: ${FIX_KEYS.join(", ")})`);
+	if (fix && fix.grasp !== undefined && typeof fix.grasp !== "boolean") err(`spec.fix.grasp must be true (fingers close on what a hand holds, the default) or false (the preset grip, the object at its grab-frame offset), got ${fmt(fix.grasp)}`);
 }
 
 /** opts = { sk, scene, frames, lenient, unknown: err for an unknown field (a no-op when lenient), past: the

package/src/motion3/compiler/vocab.js

@@ -10,13 +10,13 @@ export const NUM_CHANNELS = new Set(["yaw", "pitch", "roll", "spine_yaw", "spine
 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"];
+export const FINGER_PRESETS = ["relaxed", "fist", "grip", "cigarette", "point", "spherical"];
 /** 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" };
+export const GRASPS = ["power", "pinch", "hook", "palm", "spherical"];
+export const GRASP_FINGERS = { power: "grip", pinch: "cigarette", hook: "grip", palm: "relaxed", spherical: "spherical" };
 /** 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] };
+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], spherical: [-0.015, 0, 0.035] };
 
 // [min, max, convention] for numeric channels whose values have a hard range.
 const RANGES = [

package/src/motion3/describe.js

@@ -103,8 +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"];
+/** Skills essentials leaves to topic skills: a flip, a cartwheel or a body thrown by a hit is no first spec's need, and essentials has no room. */
+const FIRST_SPEC_SKIP = ["flip", "hitReaction", "throwObject", "catchObject"];
 
 /** A shared shape whose fields are mostly a skill's args (walk, walkTo): its own fields and `...<skill> args`. */
 function shapeLine(d) {

package/src/motion3/fix/index.js

@@ -16,6 +16,8 @@
 //   retime       speed spikes get more frames, borrowed from the neighbouring keys
 //   stance       a standIdle stance whose legs, feet or hips are in a scene body slides out of it, the least
 //                distance (skills/stance.js; applied when the skills expand, reported in observations.placed)
+//   grasp        a holding hand's fingers close on what it holds and the object rests in the hand (#816);
+//                false keeps the preset grip and the grab-frame offset
 import { lowerHips, armReach } from "./reach.js";
 import { lockFeet } from "./slide.js";
 import { holdTurns } from "./turn.js";
@@ -24,14 +26,14 @@ import { pushOut } from "./push.js";
 import { retime } from "./retime.js";
 import { selfClear } from "./self.js";
 
-const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance"];
+const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance", "grasp"];
 export { FIX_KEYS };
 
 export function fixOptions(fix) {
-	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false };
+	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false, grasp: false };
 	const f = fix ?? {};
 	const pen = f.penetration === true ? 0.02 : Math.min(0.05, Math.max(0, Number(f.penetration) || 0));
-	return { reach: f.reach !== false, slide: f.slide !== false, penetration: pen, self: f.self !== false, retime: f.retime === true, stance: f.stance !== false };
+	return { reach: f.reach !== false, slide: f.slide !== false, penetration: pen, self: f.self !== false, retime: f.retime === true, stance: f.stance !== false, grasp: f.grasp !== false };
 }
 
 /** The slide report with the flat feet whose turn waited (turn.js): turns { frames, max deg }. */

package/src/motion3/flight.js

@@ -0,0 +1,38 @@
+// A fall that leaves with a velocity (#816): a thrown thing. fall.v is the velocity its root leaves with, m/s, or "hand"
+// on a carry: the velocity the hand gives it at the release, its pose a frame after minus a frame before, x fps (the
+// frames beforePose gives the spin from, free-motion.js afterRelease). Without v, and with v zero, a fall is as before.
+// It flies on a parabola (G of free-motion.js) and lands on the first surface its path comes down onto: the highest top
+// whose point under the path at that height lies on that body (closed form per top, no stepping).
+import { add, scale, sub } from "./compiler/math.js";
+
+const ZERO = [0, 0, 0];
+
+/** The velocity fall leaves with from root pose `start` (`before`: its pose a frame earlier, a hand's release), m/s. */
+export function fallVelocity(fall, start, before, fps) {
+	if (Array.isArray(fall?.v)) return fall.v;
+	if (fall?.v === "hand" && before) return scale(sub(start.pos, before.pos), fps);
+	return ZERO;
+}
+
+export const moves = v0 => v0.some(v => v !== 0);
+
+/** Seconds until a point h m above its landing, leaving upward at vy m/s, comes down to it (G m/s^2). */
+export const flightTime = (h, vy, G) => (vy + Math.sqrt(vy * vy + 2 * G * Math.max(0, h))) / G;
+
+/** The x/z drift of a flight t s in (at most tl s, where it lands). */
+export const drift = (v0, t, tl) => { const u = Math.min(t, tl); return [v0[0] * u, 0, v0[2] * u]; };
+
+/**
+ * landingOf (free-motion.js) for a fall from `start` leaving at v0: { support, top, h } under where it comes down. `land`
+ * is landingOf(spec, scene, id, pose, onto), `tops` the heights of the bodies it may come down on, G gravity. Coming down,
+ * it meets the highest surface whose point under its path at that height is on that surface: each top from the highest
+ * down, the drift to that height, and the support there kept when it is that top (else the next lower; the floor last).
+ */
+export function landingWith(land, start, v0, G, tops = []) {
+	const here = land(start), low = here.top + here.h, at = top => ({ pos: add(start.pos, drift(v0, flightTime(low - top, v0[1], G), Infinity)), R: start.R });
+	for (const top of [...new Set(tops)].filter(t => t <= low).sort((a, b) => b - a)) {
+		const there = land(at(top));
+		if (Math.abs(there.top - top) < 1e-9) return there;
+	}
+	return land(at(0));
+}

package/src/motion3/free-motion.js

@@ -24,6 +24,7 @@ import { groupsOf } from "./scene.js";
 import { curveOf, keyedPose } from "./object-keys.js";
 import { add, apply, sub, T, quatFromMat, I3 } from "./compiler/math.js";
 import { shapeOf, airPath, settlePath, settledAt, spinOf, spinEnergy, TIP } from "./settle.js";
+import { fallVelocity, moves, flightTime, drift, landingWith } from "./flight.js";
 
 /** Gravity, m/s^2. */
 export const G = 9.8;
@@ -97,24 +98,26 @@ function shapeIn(scene, id) {
  * 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);
+	// a throw (fall.v, flight.js) lands where it comes down
+	const v0 = fallVelocity(fall, start, before, fps), thrown = moves(v0), landAt = pose => landingOf(spec, scene, id, pose, fall.onto ?? null);
+	const land = thrown ? landingWith(landAt, start, v0, G, Object.values(scene.objects).map(topOf)) : landAt(start), 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);
+		const spin = before ? spinOf(before.R, start.R, fps) : [0, 0, 0], air = airPath(shape, start, spin, land.top, fps, v0);
 		// 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)) {
+		if (path.steps.length || spin.some(v => v) || thrown) {
 			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 h = land.h, tl = thrown ? flightTime(h, v0[1], G) : Math.sqrt(2 * h / G), off = drift(v0, Infinity, tl);
 	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 rest = { pos: [start.pos[0] + off[0], start.pos[1] - h, start.pos[2] + off[2]], R: start.R };
 	const at = f => {
 		const t = (f - t0) / fps;
 		if (t <= 0) return start;
-		const dy = t <= tl ? -0.5 * G * t * t : t <= tl + tb ? -h + vb * (t - tl) - 0.5 * G * (t - tl) ** 2 : -h;
-		return { pos: [start.pos[0], start.pos[1] + Math.min(0, dy), start.pos[2]], R: start.R };
+		const dy = t <= tl ? (thrown ? v0[1] * t : 0) - 0.5 * G * t * t : t <= tl + tb ? -h + vb * (t - tl) - 0.5 * G * (t - tl) ** 2 : -h, d = drift(v0, t, tl);
+		return { pos: [start.pos[0] + d[0], start.pos[1] + (thrown ? dy : Math.min(0, dy)), start.pos[2] + d[2]], R: start.R };
 	};
 	return { t0, land: t0 + tl * fps, end: t0 + (tl + tb) * fps, h, support: land.support, top: land.top, at, rest };
 }