cozyclay 3.0.0 → 3.0.2

package/src/motion3/skills/impact.js

@@ -0,0 +1,109 @@
+// hitReaction: a body thrown by a hit (a car, a shove, a blow) and coming to rest on the floor, from the pose at f0.
+// Deterministic physics on the root: launched along the push at `speed` (m/s) and up (from the speed), it flies under gravity, lands
+// when the hips reach lying height, then slides to a stop on floor friction. The body turns to fall along the push
+// (on its back when pushed from the front, "land"), the trunk and head whip on a damped spring against the shove,
+// the arms flail and trail, the legs follow the hips (feet held off the floor) and the whole body lies still at the end.
+import { add, apply, ry, rx } from "../compiler/math.js";
+import { tiltFrame } from "../compiler/pose.js";
+import { personJoint } from "../people.js";
+import { skillError } from "./book.js";
+
+// LIE: the root's height lying on the back or face down, the trunk's skin just on the floor (X/Y Bot)
+const G = 9.81, FPS = 24, MU = 0.75, LIE = { back: 0.16, front: 0.11 }, TURN = 0.25, ONSET = 0.12, LIFT_OFF = 0.25;
+/** Distance covered by a speed that builds up over ONSET s (a hit pushes for about a tenth of a second, not one frame). */
+const ramp = t => t - ONSET * (1 - Math.exp(-t / ONSET));
+/** A foot held off the floor eases onto it (softplus over w m) instead of being cut at it. */
+const softFloor = (y, lie, w) => lie + w * Math.log1p(Math.exp((y - lie) / w));
+/** The landing: the fall stops over CUSHION s at one deceleration (spread over frames, not one), the trunk sinking SINK m
+ * into its own give past lying height, and springs back to it over SETTLE s. */
+const CUSHION = 3 / FPS, SINK = 0.03, SETTLE = 0.25;
+const smooth = x => { const t = Math.min(1, Math.max(0, x)); return t * t * t * (t * (6 * t - 15) + 10); };
+const wrap = d => ((d + 540) % 360) - 180;
+const r3 = v => v.map(x => Math.round(x * 1000) / 1000);
+const r1 = x => Math.round(x * 10) / 10;
+
+/** Where the earlier keys have a vec3 channel at frame f, read straight between the keys around it (state holds the last key). */
+function track(keys, ch, f) {
+	let a = null, b = null;
+	for (const k of keys) {
+		const v = k.set?.[ch];
+		if (!Array.isArray(v)) continue;
+		if (k.f <= f && (!a || k.f >= a.f)) a = { f: k.f, v };
+		if (k.f > f && (!b || k.f < b.f)) b = { f: k.f, v };
+	}
+	if (!a || !b) return a?.v;
+	const w = (f - a.f) / (b.f - a.f);
+	return a.v.map((x, i) => x + (b.v[i] - x) * w);
+}
+
+/** The push direction [x, z] (unit) from args.dir, or from args.from (object:<id> | person:<id>) toward the hips. */
+function pushOf(ctx, root) {
+	const { args, scene } = ctx;
+	let d = args.dir;
+	if (!d && typeof args.from === "string") {
+		const [kind, id] = args.from.split(/:(.*)/s);
+		const at = kind === "object" ? scene?.objects?.[id]?.pos : kind === "person" ? personJoint(scene, id, "Hips", ctx.f0) : null;
+		if (!at) skillError(ctx.tag, `args.from "${args.from}" must be object:<id> of a scene body or person:<id> of a character with an installed take`);
+		d = [root[0] - at[0], root[2] - at[2]];
+	}
+	if (!Array.isArray(d) || d.length !== 2 || !(Math.hypot(d[0], d[1]) > 1e-6)) skillError(ctx.tag, "needs args.dir: [x, z] (the way the body is thrown) or args.from: object:<id> | person:<id> (what hits it)");
+	const n = Math.hypot(d[0], d[1]);
+	return [d[0] / n, d[1] / n];
+}
+
+export function hitReaction(ctx) {
+	const { sk, args, state } = ctx, I = sk.index, P = sk.restWorldPos;
+	if (!state.root) skillError(ctx.tag, "needs a pose keyed before f0 (standIdle, a walk, ...)");
+	// the hit takes the body where the earlier motion has it at f0, a foot in the air going on at its speed
+	const root0 = track(ctx.keys, "root", ctx.f0) ?? state.root.slice(), from = {};
+	for (const k of ["l", "r"]) {
+		const at = track(ctx.keys, `foot_${k}`, ctx.f0), was = track(ctx.keys, `foot_${k}`, ctx.f0 - 1);
+		if (at) from[k] = { at, v: was ? at.map((x, i) => x - was[i]) : [0, 0, 0] };
+	}
+	const yaw0 = state.yaw ?? 0, [dx, dz] = pushOf(ctx, root0);
+	const speed = args.speed ?? 4;
+	if (!(Number.isFinite(speed) && speed > 0)) skillError(ctx.tag, `args.speed must be a launch speed above 0 m/s, got ${JSON.stringify(args.speed)}`);
+	const up = Math.min(2.5, Math.max(0.8, 0.3 * speed));
+	// pushed against the way it faces (a hit from the front) it lands on its back; "land" overrides
+	const facing = apply(ry(yaw0), [0, 0, 1]), back = (args.land ?? (dx * facing[0] + dz * facing[2] <= 0 ? "back" : "front")) === "back";
+	const head = Math.atan2(dx, dz) * 180 / Math.PI, yawT = back ? head + 180 : head, turn = wrap(yawT - yaw0), pitchT = back ? -90 : 90;
+	const lie = back ? LIE.back : LIE.front, y0 = root0[1], fall = t => y0 + up * ramp(t) - 0.5 * G * t * t, vel = t => up * (1 - Math.exp(-t / ONSET)) - G * t;
+	// the cushion starts at t1 where the fall, slowed evenly to rest over CUSHION, ends just at lying height
+	let lo = 0, hi = (up + Math.sqrt(up * up + 2 * G * Math.max(0, y0 - lie))) / G + 1;
+	for (let i = 0; i < 60; i++) { const m = (lo + hi) / 2; if (fall(m) + vel(m) * CUSHION / 2 > lie - SINK || vel(m) > 0) lo = m; else hi = m; }
+	const t1 = lo, v1 = Math.min(0, vel(t1)), y1 = fall(t1), T = t1 + CUSHION, tSlide = speed / (MU * G), tRest = T + tSlide;
+	const height = t => t < t1 ? fall(t) : t < T ? y1 + v1 * (t - t1) - v1 / (2 * CUSHION) * (t - t1) ** 2 : lie - SINK * (1 - smooth((t - T) / SETTLE));
+	const ankle = P[I.LeftFoot][1], hipsY = P[I.Hips][1], sign = back ? 1 : -1, LEG = 0.9 * Math.hypot(...[0, 1, 2].map(i => P[I.LeftFoot][i] - P[I.Hips][i]));
+	const end = ctx.f0 + Math.ceil((tRest + 0.6) * FPS), keys = [];
+	for (let f = ctx.f0; f <= end; f++) {
+		const t = (f - ctx.f0) / FPS, flying = t < T, ts = Math.min(Math.max(0, t - T), tSlide);
+		const run = flying ? speed * ramp(t) : speed * ramp(T) + speed * ts - 0.5 * MU * G * ts * ts;
+		const y = height(t);
+		const root = [root0[0] + dx * run, y, root0[2] + dz * run];
+		const tilt = Math.max(0.35, 0.9 * T), yaw = yaw0 + turn * smooth(t / Math.max(TURN, tilt)), pitch = pitchT * smooth(t / tilt), R = (v => apply(ry(yaw), apply(rx(pitch), v)));
+		// the trunk and head whip against the shove (a damped spring), the arms flail and trail, all settling by the rest
+		const ease = smooth(t / ONSET), whip = ease * Math.exp(-t / 0.18) * Math.sin(2 * Math.PI * t / 0.55), flail = smooth(t / 0.3) * Math.exp(-t / 0.45) * Math.sin(2 * Math.PI * t / 0.6);
+		const lying = smooth((t - T) / 0.3);
+		// legs bend in the air and lie out: on the back a little bent, knees up, toes up; face down straight, toes down
+		const legY = -(hipsY - ankle) + 0.06 * (1 - lying) + (back ? 0.03 : 0.01) * lying, off = smooth(t / LIFT_OFF);
+		// face down the feet ride a little off the floor while the body slides, so they are not taken for planted feet
+		const floor = ankle + 0.01 + (!back && !flying && ts < tSlide ? 0.04 : 0);
+		// on the back the heels stay below the hips (a soft cap), so the legs slope down to the feet and the knees bend up
+		const foot = (k, x, z) => { const p = add(root, R([x, legY, z])), cap = root[1] - 0.05; if (back) p[1] = cap - 0.05 * Math.log1p(Math.exp((cap - p[1]) / 0.05)); p[1] = softFloor(p[1], floor, 0.03); const o = from[k]; if (!o) return p; const q = o.at.map((x, i) => x + o.v[i] * (f - ctx.f0) * (1 - off)); q[1] = Math.max(o.at[1], q[1]); return reach(p.map((v, i) => q[i] + (v - q[i]) * off)); };
+		// a foot left behind is drawn in within the leg's reach of the hips (a soft cap, in as the foot lifts), so the leg is pulled, not torn
+		const reach = p => { const d = p.map((v, i) => v - root[i]), n = Math.hypot(...d), m = LEG - 0.02 * Math.log1p(Math.exp((LEG - n) / 0.02)); return n > 1e-9 ? root.map((v, i) => v + d[i] * (1 + (m / n - 1) * off)) : p; };
+		// the knee points along the body's forward pitched with it, square to the leg (no flip lying down); a pole is read
+		// in the yaw frame, tilted past 60 degrees of pitch (pose.js tiltFrame), so that tilt (lean) is taken back out of
+		// the knee poles (and half of it, face down, out of the foot pitch: the toes rest on the floor, not in it)
+		const tf = tiltFrame(0, pitch, 0), back0 = tf ? apply(tf.R, [0, 1, 0]) : [0, 1, 0], lean = Math.atan2(back0[2], back0[1]) * 180 / Math.PI;
+		const knee = apply(rx(-lean), [0, -Math.sin(pitch * Math.PI / 180), Math.max(0.05, Math.cos(pitch * Math.PI / 180))]);
+		const set = { root: r3(root), yaw: r1(yaw), pitch: r1(pitch), roll: 0,
+			foot_l: r3(foot("l", 0.11, 0.04 + 0.1 * flail * off - (back ? 0.1 : 0) * lying)), foot_r: r3(foot("r", -0.11, 0.04 - 0.1 * flail * off - (back ? 0.1 : 0) * lying)), fyaw_l: r1(yaw), fyaw_r: r1(yaw), fpitch_l: r1(back ? -50 * lying : -0.5 * lean), fpitch_r: r1(back ? -50 * lying : -0.5 * lean),
+			knee_l: r3([0.05, knee[1], knee[2]]), knee_r: r3([-0.05, knee[1], knee[2]]),
+			spine_pitch: r1(sign * 22 * whip * Math.min(1, speed / 4)), spine_yaw: 0, spine_roll: r1(10 * flail * (1 - lying)), head_pitch: r1(sign * 30 * whip * Math.min(1, speed / 4) + (back ? -8 : 8) * lying), head_roll: r1(12 * lying),
+			arm_rest: r1(72 - 22 * lying), aswing_l: r1(sign * 45 * flail + 8 * lying), aswing_r: r1(-sign * 35 * flail - 8 * lying), abend_l: r1(25 + 30 * flail * flail), abend_r: r1(30 + 25 * flail * flail) };
+		if (f === ctx.f0) Object.assign(set, { armw_l: 0, armw_r: 0, fingers_l: { relaxed: 1 }, fingers_r: { relaxed: 1 } });
+		keys.push({ f, set });
+	}
+	return { keys, end };
+}

package/src/motion3/skills/index.js

@@ -10,8 +10,10 @@ import { SKILL_INFO } from "./info.js";
 import { standIdle, walkTo, reachGrip } from "./basic.js";
 import { sitInSeat, exitCar } from "./car.js";
 import { smokeCigarette } from "./smoke.js";
+import { flip } from "./flip.js";
+import { hitReaction } from "./impact.js";
 
-const SKILLS = { standIdle, sitInSeat, exitCar, walkTo, reachGrip, smokeCigarette };
+const SKILLS = { standIdle, sitInSeat, exitCar, walkTo, reachGrip, smokeCigarette, flip, hitReaction };
 export const SKILL_NAMES = Object.keys(SKILLS);
 const bad = msg => { throw new Error(`MOTION_SPEC_INVALID: ${msg}`); };
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);

package/src/motion3/skills/info.js

@@ -34,10 +34,10 @@ export const SKILL_INFO = {
 	},
 	reachGrip: {
 		args: { anchor: str("not ending in _l/_r"), side: side("the hand"), reach: int("frames to reach", { default: 20 }), hold: int("frames held", { default: 22 }),
-			release: int("frames to let go", { default: 12 }), elbow: ref("vec3", "elbow pole"), fingers: { enum: FINGER_PRESETS, default: "grip" },
-			define: { type: "object", description: "an anchor (topic anchors) named args.anchor" }, orient: { type: "boolean", description: "false: no grip turn" } },
-		required: ["anchor", "side"], needs: "args.anchor in spec.anchors or args.define", frames: "reach + hold + release (54 by default)",
-		adds: ["props.<anchor>Grip (fingers point)", "fits: fingers onto the anchor", "checks.contacts \"fingers on <anchor>\"", "checks.allow hand on the anchor's object",
+			release: int("frames to let go", { default: 12 }), elbow: ref("vec3", "pole"), fingers: { enum: FINGER_PRESETS, default: "grip" },
+			define: { type: "object", description: "defines anchor args.anchor" }, orient: { type: "boolean", description: "false: no grip turn" } },
+		required: ["anchor", "side"], needs: "args.anchor in anchors or define", frames: "reach + hold + release (54)",
+		adds: ["props.<anchor>Grip (fingers point)", "fits: fingers on the anchor", "checks.contacts \"fingers on <anchor>\"", "checks.allow hand on its object",
 			"keys: w_<anchor>_<side>, fingers_<side>, armw_<side>"],
 		example: { f0: 10, args: { anchor: "bar", side: "r", define: { kind: "world", p: [-0.2, 1.2, 0.33] } } },
 		tune: { reach: 2, release: 2 },
@@ -53,6 +53,16 @@ export const SKILL_INFO = {
 		adds: ["objects: door and handle hinges", "anchors handle, lthigh, rthigh", "props.grip", "fits, checks.contacts, checks.allow"],
 		example: { f0: 0, args: { car: "Car" } },
 	},
+	flip: {
+		args: { kind: { enum: ["back", "front", "cartwheel"], default: "back", description: "a standing back or front tuck, or a cartwheel" },
+			travel: num("back/front: m along the heading at landing (default back -0.25, front 0.4)"),
+			side: side("cartwheel: toward the character's l (default) or r"), heading: num("degrees (yaw); default the keyed yaw") },
+		needs: "a standing pose keyed before f0", frames: "back/front 58 (one turn, the hips 0.5 m up); cartwheel 68",
+		adds: ["keys every frame: back/front crouch, push-off, a ballistic tucked flight turning the whole body (pitch to -360 back, +360 front) and a landing that stands up",
+			"cartwheel: a side step, then the whole body rolls 360 like a wheel on the straddled legs and the arms overhead, the hands planted in turn",
+			"whole-body pitch and roll take full turns in any key (no range); past 60 deg the knee and elbow poles and the feet turn with the body"],
+		example: { f0: 10, args: { kind: "back" } },
+	},
 	smokeCigarette: {
 		args: { until: int("hold to this frame; default the last frame; under f0+264 the beats are paced to fit"),
 			kit: { type: "object", properties: { cig: str("the cigarette kit's rootId (object.createKit)"), lighter: str("the lighter kit's rootId"), exhale: str("the exhale kit's rootId (or an effect): it follows the mouth") },
@@ -62,4 +72,9 @@ export const SKILL_INFO = {
 			"checks contacts, orient, below, appear, mouthPoints"],
 		example: { f0: 0, args: {} },
 	},
+	hitReaction: {
+		args: { dir: xz("[x, z] the way the body is thrown"), from: str("or what hits it: object:<id> | person:<id> (thrown away from it)"),
+			speed: num("launch speed, m/s (a shove 2, a car at 30 km/h about 8)", { default: 4, exclusiveMinimum: 0 }), land: { enum: ["back", "front"], description: "default: back when hit from the front" } },
+		needs: "a pose; dir or from", frames: "~40", adds: ["keys: thrown to rest"], example: { f0: 10, args: { dir: [0, -1], speed: 3 } },
+	},
 };

package/src/motion3/sockets.js

@@ -0,0 +1,104 @@
+// Grasp sockets (lane socket): where and how a hand takes hold of an object, so the agent names the part and the
+// grasp and the compiler turns the hand. The grasp is the object's (sessions 02263581, 38322b5d: the agent computed
+// the wrist by hand and held a barbell 90 deg off, the bar through the palm; a rifle's second hand was measured off
+// the first). A socket is, in its record's own axes (metres from the base pivot, as an object anchor's `local`):
+//   at     the point the fingers close on
+//   axis   the line that runs across the palm, the knuckle line along it (a bar, a handle, a grip); none: any
+//   from   the side the hand comes from: the palm faces against it; none: the roll the arm holds most easily
+//          (compiler/socket-grip.js), or on a body with no axis the face nearest the point
+//   thumb  the end of the axis the thumb takes; none: the end-state-comfort end (socketPalm)
+// A record stores named sockets in `grasp` (src/object-grasp.js); every thin body (two half sizes under THIN m: a
+// bar, a can, a handle) is one too, named by its id, through its centre along its long axis. An object anchor with
+// `grasp` (power, pinch, hook, palm) takes the hand by a socket of its object: `socket` names it, else the one
+// nearest the anchor's `local` point or, without one, nearest the shoulder of the hand, picked once per compile.
+import { add, sub, scale, norm, cross, dot, len, apply, ry, T } from "./compiler/math.js";
+import { partsOf } from "./object-pose.js";
+
+const THIN = 0.045, AXES = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+const flat = (v, n) => sub(v, scale(n, dot(v, n)));
+
+/** The long axis index of a thin body's half sizes, else -1. */
+function thinAxis(half) {
+	if (!half) return -1;
+	const long = [0, 1, 2].reduce((a, i) => (half[i] > half[a] ? i : a), 0);
+	return [0, 1, 2].filter(i => i !== long).every(i => half[i] < THIN) ? long : -1;
+}
+
+/** The record's stored sockets: a body's in scene.objects, a group's (an Empty) in scene.others. */
+const stored = (scene, id) => scene?.objects?.[id]?.grasp ?? scene?.others?.[id]?.grasp ?? null;
+
+/**
+ * Every socket of body or group `id`: [{ name, owner, at, axis?, from?, thumb? }], each in its owner's axes. The record's
+ * own sockets by name; a part's as "<part>.<name>"; a thin part's derived one by the part id.
+ */
+export function socketsOf(scene, id) {
+	const out = [], own = (owner, prefix) => Object.entries(stored(scene, owner) ?? {}).forEach(([name, s]) => out.push({ ...s, name: prefix + name, owner }));
+	own(id, "");
+	for (const part of partsOf(scene, id)) {
+		if (part !== id) own(part, `${part}.`);
+		const half = scene.objects[part].half, long = thinAxis(half);
+		if (long >= 0) out.push({ name: part, owner: part, at: [0, half[1], 0], axis: AXES[long] });
+	}
+	return out;
+}
+
+/** The socket of `id` named `name`, or undefined. */
+export const socketNamed = (scene, id, name) => socketsOf(scene, id).find(s => s.name === name);
+
+/** A socket in world space on its owner's pose { pos, R }: { p, axis?, from?, thumb? }. */
+export function socketWorld(socket, pose) {
+	const dir = v => (v ? norm(apply(pose.R, v)) : undefined);
+	return { p: add(pose.pos, apply(pose.R, socket.at ?? [0, 0, 0])), axis: dir(socket.axis), from: dir(socket.from), thumb: dir(socket.thumb) };
+}
+
+/** The outward normal of the face of the box (of boxes [{ pos, R, half }], base pivots) nearest world point p, or undefined. */
+export function faceFrom(boxes, p) {
+	let best;
+	for (const b of boxes) {
+		const q = apply(T(b.R), sub(p, add(b.pos, apply(b.R, [0, b.half[1], 0])))), out = [0, 1, 2].map(i => Math.abs(q[i]) - b.half[i]);
+		const i = [0, 1, 2].reduce((m, j) => (out[j] > out[m] ? j : m), 0), gap = Math.max(...out);
+		if (!best || gap < best.gap) best = { gap, n: scale([b.R[0][i], b.R[1][i], b.R[2][i]], q[i] < 0 ? -1 : 1) };
+	}
+	return best?.n;
+}
+
+/** How far world point q is from a world socket: from its axis line through p, else from p. */
+export function socketDistance(w, q) {
+	const v = sub(q, w.p);
+	return len(w.axis ? flat(v, w.axis) : v);
+}
+
+/**
+ * The palm frame (columns d, l, n of compiler/limbs.js palmAxes: d to the middle finger, l to the thumb side, n = d x
+ * l; the palm is -n on the right hand, +n on the left) a grasp of `type` takes on world socket w, the forearm along fwd,
+ * the body turned yawDeg. Along an axis (not a flat palm): with `from` the palm faces against it and the knuckle line
+ * runs along the axis; without, the fingers stay on the forearm's line across the axis (a power grip turns the forearm,
+ * not the wrist) and the palm closes on it. The thumb takes `thumb`'s end, else the end-state-comfort end (people take
+ * the grip that ends comfortable, Rosenbaum): up when the forearm is level, toward the midline when it points down or
+ * up. Without an axis the palm faces against `from` (anchorSocket gives a box face's), the fingers on the forearm's line.
+ */
+export function socketPalm(side, w, type, fwd, yawDeg = 0) {
+	const right = side === "Right", sign = v => (right ? v : scale(v, -1));
+	// a side along the axis leaves no knuckle line across it: the palm then just faces against the side (below)
+	if (w.axis && type !== "palm" && !(w.from && len(flat(w.axis, w.from)) < 1e-3)) {
+		if (w.from) {
+			const n = sign(w.from), l0 = norm(flat(w.axis, n)), pick = l => (w.thumb ? dot(l, w.thumb) : dot(cross(l, n), fwd));
+			const l = pick(l0) >= pick(scale(l0, -1)) ? l0 : scale(l0, -1);
+			return cols(cross(l, n), l, n);
+		}
+		const d = across(fwd, w.axis), medial = apply(ry(yawDeg), [right ? 1 : -1, 0, 0]), vy = Math.abs(d[1]);
+		const want = w.thumb ?? flat(add(scale([0, 1, 0], 1 - vy), scale(medial, vy)), d), l0 = norm(flat(w.axis, d));
+		const l = dot(l0, want) >= 0 ? l0 : scale(l0, -1);
+		return cols(d, l, cross(d, l));
+	}
+	const n = sign(w.from ?? scale(fwd, -1)), d = across(fwd, n);
+	return cols(d, cross(n, d), n);
+}
+
+/** fwd made perpendicular to v (unit); any perpendicular when fwd runs along v. */
+function across(fwd, v) {
+	const d = flat(fwd, v);
+	return norm(len(d) > 1e-3 ? d : flat(Math.abs(v[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0], v));
+}
+
+const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];

package/src/motion3/take-edit.js

@@ -148,7 +148,7 @@ export function renderTakeEdit(take) {
 		if (track.pos) { next.pos = new Float32Array(D * 3); at.forEach(({ i0, i1, t }, f) => lerp(next.pos, f * 3, track.pos, i0 * 3, track.pos, i1 * 3, t, 3)); }
 		if (track.quat) { next.quat = new Float32Array(D * 4); at.forEach(({ i0, i1, t }, f) => nlerp(next.quat, f * 4, track.quat, i0 * 4, track.quat, i1 * 4, t)); }
 		if (track.lvl) { next.lvl = new Float32Array(D); at.forEach(({ i0, i1, t }, f) => lerp(next.lvl, f, track.lvl, i0, track.lvl, i1, t, 1)); }
-		for (const key of ["vis", "hold"]) if (track[key]) { next[key] = new Uint8Array(D); at.forEach(({ near }, f) => { next[key][f] = track[key][near]; }); }
+		for (const key of ["vis", "hold", "world"]) if (track[key]) { next[key] = new Uint8Array(D); at.forEach(({ near }, f) => { next[key][f] = track[key][near]; }); }
 		return [id, next];
 	}));
 	return { ...take, frameCount: D, frames: D, rot, hips, objects, edit, editRendered: true };

package/src/motion3/take.js

@@ -6,12 +6,13 @@
 // world space: one track per spec.objects key (a group: its root only). A switch entry (C15)
 // bakes only vis and lvl, no pos/quat: its record keeps its own place (object-travel.js). A follow
 // entry (C16) bakes pos/quat with hold on every frame: its track is world space throughout. A free entry
-// (C17) bakes pos/quat (and vis/lvl when it names them), world space, no hold.
+// (C17) bakes pos/quat (and vis/lvl when it names them), world space, no hold. A carry that rides a moving body after
+// its release (object-pose.js riderOf) marks those frames `world`: world space too, though no hand holds it.
 import { toLocal } from "./compiler/skeleton.js";
 import { sub, apply, ry, quatFromMat, mul } from "./compiler/math.js";
 import { isCarried, isFollow, isSwitch } from "./carried.js";
 import { isFree } from "./free-motion.js";
-import { rootPoseAt, spanOf } from "./object-pose.js";
+import { rootPoseAt, spanOf, riderOf } from "./object-pose.js";
 
 const TAKE_SCHEMA = "cozyclay.take.v3";
 
@@ -36,7 +37,7 @@ export function bakeTake(sk, out, placement = { position: [0, 0, 0], yaw: 0 }, m
 		const pos = moves ? new Float32Array(F * 3) : null, quat = moves ? new Float32Array(F * 4) : null;
 		const named = rides || !moves || isFree(spec), vis = named && spec.visible ? new Uint8Array(F) : null, hold = rides ? new Uint8Array(F) : null;
 		const lvl = named && spec.level ? new Float32Array(F) : null;
-		const [grab, release] = carried ? spanOf(out, spec) : [0, 0];
+		const [grab, release] = carried ? spanOf(out, spec) : [0, 0], world = carried && riderOf(out, id) ? new Uint8Array(F) : null;
 		for (let f = 0; f < F; f++) {
 			if (vis) vis[f] = (out.baked?.[spec.visible]?.[f + f0] ?? 0) > 0.5 ? 1 : 0;
 			if (lvl) lvl[f] = Math.max(0, Math.min(4, out.baked?.[spec.level]?.[f + f0] ?? 1));
@@ -45,8 +46,9 @@ export function bakeTake(sk, out, placement = { position: [0, 0, 0], yaw: 0 }, m
 			if (!o) continue;
 			pos.set(o.pos, f * 3); quat.set(quatFromMat(o.R), f * 4);
 			if (hold) hold[f] = follows || (f + f0 >= grab && f + f0 <= release) ? 1 : 0;
+			if (world) world[f] = f + f0 > release ? 1 : 0;
 		}
-		objects[id] = { ...(moves ? { pos, quat } : {}), ...(vis ? { vis } : {}), ...(hold ? { hold } : {}), ...(lvl ? { lvl } : {}) };
+		objects[id] = { ...(moves ? { pos, quat } : {}), ...(vis ? { vis } : {}), ...(hold ? { hold } : {}), ...(world ? { world } : {}), ...(lvl ? { lvl } : {}) };
 	}
 	return { schema: TAKE_SCHEMA, fps: out.fps, frameCount: F, rig: sk.model, bones: sk.names.slice(), rot, hips, objects, placement, ...meta };
 }

package/src/object-catalog.jsx

@@ -7,6 +7,7 @@ const GROUP_LABELS_KO = {
 	"Set pieces": "세트 소품",
 	Lights: "조명",
 	Effects: "효과",
+	Text: "텍스트",
 };
 
 const OBJECT_LABELS_KO = {
@@ -24,6 +25,7 @@ const OBJECT_LABELS_KO = {
 	"Spot light": "스포트 조명",
 	Light: "조명",
 	Effect: "효과",
+	Text: "텍스트",
 };
 
 function displayObjectGroupName(name) {
@@ -73,7 +75,7 @@ export function CatalogueEntries({ onPick }) {
 					<span className={`add-object-swatch ${entry.kind}`} style={{ background: entry.color }} aria-hidden="true" />
 					<span>{displayObjectLabel(entry.label)}</span>
 					{/* An empty has no size to quote: say what it is instead of "0 × 0 m". */}
-					<small>{entry.light ? ko("practical light", "실제 조명") : entry.kind === EMPTY_KIND ? ko("node only", "노드 전용") : entry.kind === "effect" ? ko("smoke, fire, rain…", "연기, 불, 비…") : `${entry.footprint.width} × ${entry.footprint.depth} m`}</small>
+					<small>{entry.light ? ko("practical light", "실제 조명") : entry.kind === EMPTY_KIND ? ko("node only", "노드 전용") : entry.kind === "effect" ? ko("smoke, fire, rain…", "연기, 불, 비…") : entry.kind === "text" ? ko("words, signs, logos", "글자, 간판, 로고") : `${entry.footprint.width} × ${entry.footprint.depth} m`}</small>
 				</button>
 			))}
 		</div>

package/src/object-grasp.js

@@ -0,0 +1,38 @@
+/**
+ * Grasp sockets on a record (`grasp`): where and how a hand takes hold of it, in the record's own axes, so they move
+ * with it and save with it. { <name>: { at: [x, y, z] m from the base pivot, axis?: the line across the palm (a bar,
+ * a handle), from?: the side the hand comes from (the palm faces against it), thumb?: the axis end the thumb takes } }.
+ * A motion spec's object anchor with `grasp` takes a hand by one (src/motion3/sockets.js), and a thin body is a socket
+ * of its own without one. At most MAX sockets, names of letters, digits, _ and -.
+ */
+const MAX = 8, NAME = /^[A-Za-z0-9_-]{1,32}$/, REACH = 10;
+
+const vec = (v, limit) => (Array.isArray(v) && v.length === 3 && v.every(Number.isFinite) && v.every(x => Math.abs(x) <= limit) ? v.map(x => Math.round(x * 1e4) / 1e4) : null);
+const dir = v => { const u = vec(v, 1e3), n = u && Math.hypot(...u); return n > 1e-6 ? u.map(x => Math.round((x / n) * 1e4) / 1e4) : null; };
+
+/** The repaired sockets of a record, or null for none (invalid entries are dropped). */
+function normalizeObjectGrasp(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const out = {};
+	for (const [name, s] of Object.entries(value)) {
+		if (Object.keys(out).length >= MAX || !NAME.test(name) || !s || typeof s !== "object") continue;
+		const at = vec(s.at, REACH);
+		if (!at) continue;
+		out[name] = { at };
+		for (const k of ["axis", "from", "thumb"]) { const d = dir(s[k]); if (d) out[name][k] = d; }
+	}
+	return Object.keys(out).length ? out : null;
+}
+
+/** The grasp field of a stored record (normalizeSceneObject): kept when it has a socket. */
+export function objectGraspFields(record) {
+	const grasp = normalizeObjectGrasp(record?.grasp);
+	return grasp ? { grasp } : {};
+}
+
+/** The grasp part of an object.update patch: the sockets replace the record's own; `grasp: null` removes them. Only a change is returned. */
+export function objectGraspPatch(object, patch) {
+	if (patch?.grasp === undefined) return {};
+	const next = patch.grasp === null ? null : normalizeObjectGrasp(patch.grasp);
+	return JSON.stringify(next) === JSON.stringify(object.grasp ?? null) ? {} : { grasp: next };
+}

package/src/object-look.js

@@ -194,3 +194,5 @@ export function withShadowCapWarnings(result, objects) {
 	const warnings = shadowCapWarnings(objects, result?.affectedIds ?? []);
 	return warnings.length ? { ...result, warnings: [...(result.warnings ?? []), ...warnings] } : result;
 }
+// A record's grasp sockets ride the same normalize and patch paths (object-grasp.js).
+export { objectGraspFields, objectGraspPatch } from "./object-grasp.js";

package/src/object-travel.js

@@ -115,12 +115,15 @@ export function trackLevel(id, frame, take) {
 }
 
 /**
- * True while a compiled take holds the record in a hand (a grabbed cup): its track is in world
- * space then, so the carry from its own parents (the table it stood on) is cut, like `attach`.
+ * True while a compiled take holds the record in a hand (a grabbed cup), or the record rides a
+ * moving body after its release (`world`, take.js): its track is in world space then, so the
+ * carry from its own parents (the table it stood on) is cut, like `attach`.
  */
 function held(id, frame, take) {
 	const track = take?.objectTracks?.get?.(id);
-	return !!track?.hold && track.hold[trackFrame(track, frame)] === 1;
+	if (!track) return false;
+	const at = trackFrame(track, frame);
+	return track.hold?.[at] === 1 || track.world?.[at] === 1;
 }
 
 /** The record's own route sample (or compiled track) as a matrix, or null when it does not travel. */

package/src/panels/ObjectLookPanel.jsx

@@ -5,11 +5,13 @@ import Foldout from "./Foldout.jsx";
 import { Field, Slider } from "../ui.jsx";
 import { ko } from "../locale.js";
 import { LIGHT_KIND, practicalShadows } from "../object-look.js";
+import { TEXT_KIND } from "../text/text-record.js";
 
 /**
- * Light and glow for the selected record: a practical light's type, colour,
- * brightness, reach, cone, shadow and flicker, and any record's glow. A drag is
- * one open transaction (one undo); a switch is one atomic edit.
+ * Words, light and glow for the selected record: a text's words and letter
+ * size, a practical light's type, colour, brightness, reach, cone, shadow and
+ * flicker, and any record's glow. A drag or a typing run is one open
+ * transaction (one undo); a switch is one atomic edit.
  */
 export default function ObjectLookPanel() {
 	const { selectedSceneObject: object, sceneObjects, beginSceneTransaction, endSceneTransaction } = useStudioShell();
@@ -35,6 +37,7 @@ export default function ObjectLookPanel() {
 	if (!object) return null;
 	const light = object.renderer === LIGHT_KIND ? object.light : null;
 	const glow = object.glow ?? null;
+	const text = object.renderer === TEXT_KIND ? object.text : null;
 	const capped = light?.shadow && practicalShadows(sceneObjects).capped.includes(object.id);
 	const ends = { onPointerUp: commit, onPointerCancel: commit, onKeyUp: commit, onBlur: commit };
 	const lightSlider = (field, label, min, max, step, unit = "") => (
@@ -42,6 +45,24 @@ export default function ObjectLookPanel() {
 	);
 	return (
 		<>
+			{text && (
+				<Foldout title={ko("Text", "텍스트")}>
+					<Field label={ko("Words", "글자")}>
+						<textarea rows={2} value={text.value} onChange={(event) => drag("text.value", { text: { value: event.target.value } })} onBlur={commit} />
+					</Field>
+					<div {...ends}>
+						<Slider label={ko("Letter height", "글자 높이")} min={0.02} max={3} step={0.01} unit=" m" softMax value={text.size} onChange={(value) => drag("text.size", { text: { size: value } })} />
+						<Slider label={ko("Depth (0 = flat)", "두께 (0 = 평면)")} min={0} max={0.5} step={0.005} unit=" m" softMax value={text.depth} onChange={(value) => drag("text.depth", { text: { depth: value } })} />
+						<Field label={ko("Align", "정렬")}>
+							<select value={text.align} onChange={(event) => set({ text: { align: event.target.value } })}>
+								<option value="left">{ko("Left", "왼쪽")}</option>
+								<option value="center">{ko("Centre", "가운데")}</option>
+								<option value="right">{ko("Right", "오른쪽")}</option>
+							</select>
+						</Field>
+					</div>
+				</Foldout>
+			)}
 			{light && (
 				<Foldout title={ko("Light", "조명")}>
 					<div {...ends}>

package/src/props.jsx

@@ -16,6 +16,8 @@ import { sceneObjectCarryMatrixAt, sceneObjectTravelMatrixAt, trackShown, travel
 import * as THREE from "three";
 import { GIZMO_LAYER } from "./dualview.jsx";
 import { CUTOUT_KIND, MESH_KIND, EMPTY_KIND, EMPTY_MARKER_SIZE, SCULPT_KIND } from "./scene-objects.js";
+import { TEXT_KIND } from "./text/text-record.js";
+import { TextObject } from "./text/text-object.jsx";
 import { buildSculptGroup, disposeSculptGroup } from "./sculpt-geometry.js";
 import { subscribeToAssetTexture } from "./scene-asset-cache.js";
 import { ImportedMesh } from "./imported-mesh.jsx";
@@ -199,8 +201,7 @@ const EMPTY_AXES = [
 function EmptyMarker() {
 	const half = EMPTY_MARKER_SIZE / 2;
 	const axes = useMemo(() => {
-		const positions = [];
-		const colors = [];
+		const positions = [], colors = [];
 		const color = new THREE.Color();
 		for (const axis of EMPTY_AXES) {
 			positions.push(-axis.to[0] * half, -axis.to[1] * half, -axis.to[2] * half, axis.to[0] * half, axis.to[1] * half, axis.to[2] * half);
@@ -213,9 +214,7 @@ function EmptyMarker() {
 		return geometry;
 	}, [half]);
 	useEffect(() => () => axes.dispose(), [axes]);
-	const onLayer = (node) => {
-		if (node) node.layers.set(GIZMO_LAYER);
-	};
+	const onLayer = (node) => node?.layers.set(GIZMO_LAYER);
 	return (
 		<group userData={{ emptyMarker: true }}>
 			<lineSegments ref={onLayer} geometry={axes} renderOrder={997} frustumCulled={false}>
@@ -242,6 +241,7 @@ function SceneObjectContent({ object, depthRank = 0 }) {
 	if (renderer === CUTOUT_KIND) return <Cutout object={object} />;
 	if (renderer === MESH_KIND) return <ImportedMesh object={object} />;
 	if (renderer === SCULPT_KIND) return <Sculpt object={object} depthRank={depthRank} />;
+	if (renderer === TEXT_KIND) return <TextObject object={object} />;
 	if (renderer === "car") return <Car color={autoColor ?? color} autoColor={autoColor} />;
 	if (renderer === "small-plane") return <SmallPlane autoColor={autoColor} />;
 	if (renderer === "chair") return <Chair autoColor={autoColor} />;

package/src/qa-label.js

@@ -0,0 +1,25 @@
+// How a QA result reads to a person. QA records one issue per frame and groups them by kind and subject (qa/index.js),
+// so one goal missed on 321 frames is 321 issues but one problem: the user saw "QA 549" for two long groups. People read
+// problems (the groups); qa.total stays the frame-level count the agent, repair and search work with.
+import { ko } from "./locale.js";
+
+/** Problems in a QA result: its groups (qa.problems from runMotionQa; an older result counts its groups). A failed result
+ * with neither, or with no groups, falls back to its frame-level count, so it never reads as clean. */
+export function qaProblems(qa) {
+	const n = qa?.problems ?? (Array.isArray(qa?.groups) ? qa.groups.length : 0);
+	return n || (qa?.ok ? 0 : (qa?.total ?? 0));
+}
+
+/** "QA clean" | "2 problems" ("QA 통과" | "문제 2개"). */
+export function qaLabel(qa) {
+	const n = qaProblems(qa);
+	if (qa?.ok || !n) return ko("QA clean", "QA 통과");
+	return ko(`${n} problem${n === 1 ? "" : "s"}`, `문제 ${n}개`);
+}
+
+/** A receipt's QA phrase: "clean" | "2 problems (321 frame issues)". */
+export function qaSay(qa) {
+	if (qa?.ok) return "clean";
+	const n = qaProblems(qa), total = qa?.total ?? 0;
+	return `${n} problem${n === 1 ? "" : "s"} (${total} frame issue${total === 1 ? "" : "s"})`;
+}

package/src/scene-objects.js

@@ -26,7 +26,8 @@ import { GREY_BOX } from "./object-colors.js";
 import { isEffectivelyHidden } from "./object-hidden.js";
 import { objectSize } from "./object-size.js";
 import { EFFECT_ENTRY, effectFields } from "./effects/effect-record.js";
-import { LIGHT_KIND, LIGHT_MENU_ENTRIES, lightLibraryEntry, objectLookFields, objectLookPatch } from "./object-look.js";
+import { TEXT_ENTRY, TEXT_KIND, textFields, textPatch } from "./text/text-record.js";
+import { LIGHT_KIND, LIGHT_MENU_ENTRIES, lightLibraryEntry, objectLookFields, objectLookPatch, objectGraspFields, objectGraspPatch } from "./object-look.js";
 export { OBJECT_COLORS, normalizeObjectColor, rememberObjectColor, readStoredObjectColors, writeStoredObjectColors } from "./object-colors.js";
 export { isEffectivelyHidden };
 
@@ -175,10 +176,10 @@ export function isEmptyObject(object) {
 	return object?.renderer === EMPTY_KIND || object?.renderer === LIGHT_KIND;
 }
 
-/** The catalogue grouped for the create menu: the library plus the empty, the
- * two practical lights and the effect emitter, which are creatable but have no
- * footprint to satisfy the library's contract. */
-export const OBJECT_MENU_ENTRIES = Object.freeze([EMPTY_ENTRY, ...OBJECT_LIBRARY, ...LIGHT_MENU_ENTRIES, EFFECT_ENTRY]);
+/** The catalogue grouped for the create menu: the library plus the empty, a
+ * text, the two practical lights and the effect emitter, which are creatable
+ * but have no fixed footprint to satisfy the library's contract. */
+export const OBJECT_MENU_ENTRIES = Object.freeze([EMPTY_ENTRY, ...OBJECT_LIBRARY, TEXT_ENTRY, ...LIGHT_MENU_ENTRIES, EFFECT_ENTRY]);
 
 /** Every kind that can exist in a scene: the catalogue you can create from,
  * plus the kinds that arrive by import and so are deliberately absent from the
@@ -190,6 +191,7 @@ function objectLibraryEntry(kind) {
 	if (kind === SCULPT_KIND) return SCULPT_ENTRY;
 	if (kind === EMPTY_KIND) return EMPTY_ENTRY;
 	if (kind === EFFECT_ENTRY.kind) return EFFECT_ENTRY;
+	if (kind === TEXT_KIND) return TEXT_ENTRY;
 	return OBJECT_LIBRARY.find((entry) => entry.kind === kind) ?? lightLibraryEntry(kind);
 }
 
@@ -300,8 +302,9 @@ export function sceneObjectIdFromHierarchy(hierarchyId) {
  * A fresh object of `kind`, named and identified uniquely against `existing`.
  * `placement` seeds the floor position (the caller drops it in front of the
  * camera); everything else starts neutral so the first drag is predictable.
+ * `text` seeds a text record's words (text-record.js); other kinds ignore it.
  */
-export function createSceneObject(kind, existing = [], placement = {}) {
+export function createSceneObject(kind, existing = [], placement = {}, text = undefined) {
 	// Cutouts and meshes come from an import, never from the catalogue:
 	// without an asset id the record has nothing to draw.
 	if (kind === CUTOUT_KIND || kind === MESH_KIND || kind === SCULPT_KIND) return null;
@@ -342,6 +345,8 @@ export function createSceneObject(kind, existing = [], placement = {}) {
 		supportY: Number.isFinite(entry.supportY) ? entry.supportY : entry.height,
 		...objectLookFields({}, entry),
 		...effectFields({ renderer: kind }),
+		// A text's words and the box measured from them (src/text/text-record.js).
+		...textFields({ renderer: kind, text }),
 	};
 }
 
@@ -547,11 +552,12 @@ const TRANSFORM_LIMITS = {
 /** The patch keys updateSceneObject reads for this object; any other key is
  * silently ignored there, so callers that must not be silent check against this. */
 export function objectPatchFields(object) {
-	const fields = [...Object.keys(TRANSFORM_LIMITS), "name", "color", "hidden", "opacity", "path", "glow"];
+	const fields = [...Object.keys(TRANSFORM_LIMITS), "name", "color", "hidden", "opacity", "path", "glow", "grasp"];
 	if (object?.renderer === LIGHT_KIND) fields.push("light");
 	if (object?.renderer === CUTOUT_KIND) fields.push("assetId", "sourceAssetId", "matteAssetId", "matteScale", "height", "aspect", "width", "stretch");
 	if (object?.renderer === MESH_KIND) fields.push("clay", "assetId", "height");
 	if (object?.renderer === SCULPT_KIND) fields.push("recipe");
+	if (object?.renderer === TEXT_KIND) fields.push("text");
 	return fields;
 }
 
@@ -856,8 +862,8 @@ export function updateSceneObject(objects, id, patch) {
 				Object.assign(update, sculptStandingBox(normalized.recipe));
 			}
 		}
-		// Light and glow merge over the record's own and are repaired (object-look.js).
-		Object.assign(update, objectLookPatch(object, patch));
+		// Light, glow and a text's words merge over the record's own and are repaired (object-look.js, text-record.js); grasp sockets replace (object-grasp.js).
+		Object.assign(update, objectLookPatch(object, patch), textPatch(object, patch), objectGraspPatch(object, patch));
 		if (!Object.keys(update).length) return object;
 		changed = true;
 		return { ...object, ...update };
@@ -1086,10 +1092,12 @@ export function normalizeSceneObject(record) {
 						height: Math.max(MESH_HEIGHT_MIN, pick(record.height, entry.height)),
 					}
 				: { footprint: { ...entry.footprint }, height: entry.height, supportY: Number.isFinite(entry.supportY) ? entry.supportY : entry.height }),
-		// A light's light, and a glow on any record (object-look.js).
-		...objectLookFields(record, entry),
+		// A light's light, and a glow on any record (object-look.js); grasp sockets (object-grasp.js).
+		...objectLookFields(record, entry), ...objectGraspFields(record),
 		// An effect record's emitter (src/effects/effect-record.js).
 		...effectFields(record),
+		// A text's words; its box is measured from them (src/text/text-record.js).
+		...textFields(record),
 	};
 }