cozyclay 2.1.0 → 3.0.0

package/src/motion3/take.js

@@ -0,0 +1,63 @@
+// Take v3: what the compiler bakes and the player reads. Bone rotations are LOCAL quaternions
+// on the Mixamo control bones (the first depth-first bone of each name), so playback writes
+// them straight onto the rig; the hips also carry a position. Everything is expressed in the
+// character's placement frame (its base position and yaw), in metres, so moving or turning
+// the character carries the take with it. Scene objects the motion animates ride along in
+// 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.
+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";
+
+const TAKE_SCHEMA = "cozyclay.take.v3";
+
+/** out = compileMotion(...) result; placement = { position: [x,y,z], yaw } of the character. */
+export function bakeTake(sk, out, placement = { position: [0, 0, 0], yaw: 0 }, meta = {}) {
+	const F = out.frames.length, B = sk.names.length;
+	const rot = new Float32Array(F * B * 4), hips = new Float32Array(F * 3);
+	const unYaw = ry(-(placement.yaw ?? 0));
+	for (let f = 0; f < F; f++) {
+		const s = out.frames[f].s;
+		const local = { P: s.P.map(p => apply(unYaw, sub(p, placement.position))), R: s.R.map(R => mul(unYaw, R)) };
+		const { quats, hips: h } = toLocal(sk, local);
+		quats.forEach((q, b) => rot.set(q, (f * B + b) * 4));
+		hips.set(h, f * 3);
+	}
+	// one track per spec.objects key: a body, or a group root its parts ride (object-pose.js);
+	// `hold` marks the frames a carried record is in hand, and every frame of a follow entry (world
+	// space: object-travel.js cuts the carry of its own parents there); a switch bakes vis/lvl only
+	const objects = {}, f0 = out.f0 ?? 0;
+	for (const [id, spec] of Object.entries(out.ctx.spec.objects ?? {})) {
+		const carried = isCarried(spec), follows = isFollow(spec), rides = carried || follows, moves = !isSwitch(spec);
+		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];
+		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));
+			if (!moves) continue;
+			const o = rootPoseAt(out, id, f + f0);
+			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;
+		}
+		objects[id] = { ...(moves ? { pos, quat } : {}), ...(vis ? { vis } : {}), ...(hold ? { hold } : {}), ...(lvl ? { lvl } : {}) };
+	}
+	return { schema: TAKE_SCHEMA, fps: out.fps, frameCount: F, rig: sk.model, bones: sk.names.slice(), rot, hips, objects, placement, ...meta };
+}
+
+/** Local quaternion [x,y,z,w] of bone b at frame f (nearest frame, clamped). */
+export function takeQuat(take, f, b) {
+	const ff = Math.max(0, Math.min(take.frameCount - 1, Math.round(f))), i = (ff * take.bones.length + b) * 4;
+	return [take.rot[i], take.rot[i + 1], take.rot[i + 2], take.rot[i + 3]];
+}
+
+export function takeHips(take, f) {
+	const ff = Math.max(0, Math.min(take.frameCount - 1, Math.round(f))) * 3;
+	return [take.hips[ff], take.hips[ff + 1], take.hips[ff + 2]];
+}

package/src/motion3/timeline.js

@@ -0,0 +1,127 @@
+// C4. The compiled motion as beats, for the agent (output.timeline) and the beats contact sheet.
+// At most 12 entries, ordered by f[0]:
+//   { beat: skill name | "walk" | "keys", src: "use[i]" | "generators[i]" | "keys",
+//     f: [first, last] (inclusive, absolute frames),
+//     end: { root: [x,y,z], yaw, hand_l: [x,y,z], hand_r: [x,y,z], on_l: ref | null, on_r: ref | null },
+//     planted: { l: [[f0, f1], ...], r: [...] },   // at most 4 per foot
+//     events: [{ f, object, event: "grab" | "release" | "show" | "hide" }] }
+// Metres to 3 decimals, degrees to 1. Beats come from the skills expandUse ran (used), the
+// generators, and the runs of keys no skill or generator covers; a retime (out.timeMap) moves
+// them with the keys. end is the pose at f[1]: root = the Hips joint, hand_* = the wrists,
+// on_* = the "object:<id>" that hand holds there (object-pose.js inHandAt), else the
+// "anchor:<a>" whose w_<a>_<k> > 0.5 (the largest). planted = the heel or the ball below
+// QA_LIMITS.plantH over the ground (the floor or an object's top, qa/ground.js) and still (a foot on its ball, heel up, is planted), for 3 frames or more (the first, the last and the longest others
+// when there are more than 4). Events: grab/release when an object enters or leaves a hand,
+// show/hide when a visibility channel (a carry's or a switch's `visible`, or any *_vis channel)
+// crosses 0.5; `object` is the object id (one event per object the channel shows), or the
+// channel's name when no object owns it.
+import { QA_LIMITS } from "./qa/checks.js";
+import { groundSole } from "./qa/ground.js";
+import { inHandAt } from "./object-pose.js";
+
+const MAX_BEATS = 12, PER_FOOT = 4, MIN_PLANT = 3, STILL_Y = 0.0005;
+const r3 = v => Math.round(v * 1000) / 1000, r1 = v => Math.round(v * 10) / 10;
+const vec = p => p.map(r3);
+
+/** The beats' frame ranges before their poses are read: [{ beat, src, f }]. */
+function beatsOf(out, used, spec) {
+	const last = out.frameCount - 1, map = out.timeMap ?? (f => f);
+	const beats = used.map((u, i) => ({ beat: u.skill, src: `use[${i}]`, f: [u.f0, u.end ?? u.f0] }));
+	(spec.generators ?? []).forEach((g, i) => beats.push({ beat: g.type, src: `generators[${i}]`, f: [g.f0, g.f0 + 16 + (g.steps ?? 8) * (g.period ?? 20) + 18] }));
+	const covered = f => beats.some(b => f >= b.f[0] && f <= b.f[1]);
+	const loose = [...new Set((spec.keys ?? []).map(k => k.f))].filter(f => Number.isFinite(f) && !covered(f)).sort((a, b) => a - b);
+	let run = null;
+	for (const f of loose) {
+		if (run && !beats.some(b => b.src !== "keys" && b.f[1] > run.f[1] && b.f[0] < f)) run.f[1] = f;
+		else beats.push(run = { beat: "keys", src: "keys", f: [f, f] });
+	}
+	const clamp = f => Math.max(0, Math.min(last, Math.round(map(f))));
+	for (const b of beats) b.f = [clamp(b.f[0]), clamp(b.f[1])];
+	return beats.sort((a, b) => a.f[0] - b.f[0]).slice(0, MAX_BEATS);
+}
+
+/** planted[side][f]: the heel or the ball low and still at absolute frame f (false outside the window). */
+function plantedFlags(out) {
+	const n = out.frameCount, a = out.f0 ?? 0, flags = { l: new Uint8Array(n), r: new Uint8Array(n) };
+	for (const [k, S] of [["l", "Left"], ["r", "Right"]]) {
+		const sole = out.frames.map((fr, i) => (fr ? groundSole(out, i, S) : null));
+		sole.forEach((p, i) => {
+			const q = sole[i > 0 ? i - 1 : i + 1];
+			if (!p || !q) return;
+			const ok = ["heel", "ball"].some(key => p[key][1] < QA_LIMITS.plantH && Math.abs(p[key][1] - q[key][1]) < STILL_Y
+				&& Math.hypot(p[key][0] - q[key][0], p[key][2] - q[key][2]) <= QA_LIMITS.slide);
+			flags[k][a + i] = ok ? 1 : 0;
+		});
+	}
+	return flags;
+}
+
+function plantedIn(flags, [f0, f1]) {
+	const runs = [];
+	let start = null;
+	for (let f = f0; f <= f1 + 1; f++) {
+		const on = f <= f1 && flags[f] === 1;
+		if (on && start === null) start = f;
+		if (!on && start !== null) { if (f - start >= MIN_PLANT) runs.push([start, f - 1]); start = null; }
+	}
+	if (runs.length <= PER_FOOT) return runs;
+	const inner = runs.slice(1, -1).sort((x, y) => (y[1] - y[0]) - (x[1] - x[0]) || x[0] - y[0]).slice(0, PER_FOOT - 2);
+	return [runs[0], ...inner, runs[runs.length - 1]].sort((x, y) => x[0] - y[0]);
+}
+
+/** Every grab/release/show/hide of the take, by absolute frame. */
+function eventsOf(out, spec) {
+	const n = out.frameCount, events = [], objects = Object.entries(spec.objects ?? {});
+	for (const [id, o] of objects) for (let f = 1; f < n; f++) {
+		const was = inHandAt(o, f - 1), is = inHandAt(o, f);
+		if (is && !was) events.push({ f, object: id, event: "grab" });
+		if (was && !is) events.push({ f: f - 1, object: id, event: "release" });
+	}
+	// every object a channel shows (a carry's or a switch's visible) gets its own event
+	const owners = {};
+	for (const [id, o] of objects) if (typeof o?.visible === "string") (owners[o.visible] ??= []).push(id);
+	for (const ch of new Set([...Object.keys(owners), ...Object.keys(out.baked ?? {}).filter(c => c.endsWith("_vis"))])) {
+		const v = out.baked?.[ch];
+		if (!v) continue;
+		for (let f = 1; f < n; f++) {
+			const was = v[f - 1] > 0.5, is = v[f] > 0.5;
+			if (was !== is) for (const object of owners[ch] ?? [ch]) events.push({ f, object, event: is ? "show" : "hide" });
+		}
+	}
+	return events.sort((x, y) => x.f - y.f);
+}
+
+/** "object:<id>" held by hand k at f, else the "anchor:<a>" with the largest weight > 0.5, else null. */
+function onOf(spec, c, k, f) {
+	for (const [id, o] of Object.entries(spec.objects ?? {})) if (spec.props?.[o?.prop]?.hand === k && inHandAt(o, f)) return `object:${id}`;
+	let best = null, bw = 0.5;
+	for (const [ch, w] of Object.entries(c)) {
+		const m = /^w_(.+)_([lr])$/.exec(ch);
+		if (m && m[2] === k && w > bw) { best = m[1]; bw = w; }
+	}
+	return best && `anchor:${best}`;
+}
+
+function endOf(out, spec, f) {
+	const fr = out.frames[f - (out.f0 ?? 0)];
+	if (!fr) return null;
+	const { s, c } = fr, I = out.ctx.sk.index;
+	return { root: vec(s.P[I.Hips]), yaw: r1(c.yaw ?? 0), hand_l: vec(s.P[I.LeftHand]), hand_r: vec(s.P[I.RightHand]),
+		on_l: onOf(spec, c, "l", f), on_r: onOf(spec, c, "r", f) };
+}
+
+/**
+ * timelineOf(out, { used, spec }) -> entries
+ * @param {object} out  compileMotion result
+ * @param {{ used: { skill: string, f0: number, end: number }[], spec: object }} ctx  used = the
+ *   skills expandUse ran, spec = the expanded spec
+ * @returns {object[]}
+ */
+export function timelineOf(out, { used, spec }) {
+	const beats = beatsOf(out, used ?? [], spec);
+	if (!beats.length) return [];
+	const flags = plantedFlags(out), events = eventsOf(out, spec);
+	return beats.map(b => ({ ...b, end: endOf(out, spec, b.f[1]),
+		planted: { l: plantedIn(flags.l, b.f), r: plantedIn(flags.r, b.f) },
+		events: events.filter(e => e.f >= b.f[0] && e.f <= b.f[1]) }));
+}

package/src/motion3/views.js

@@ -0,0 +1,121 @@
+// C11 own views: the cameras of a verify_result contact_sheet with `views`. They are the
+// agent's own cameras around the subject, never the user's shot camera. A view stays at one
+// place for every frame of the sheet and frames what matters over those frames (the focus
+// refs, else the whole character, plus any trail), so a small action fills the tile and
+// motion reads as change inside one still frame. Pure over a compile result (compileSpec .out).
+//   front          in front of the character, 10 degrees up
+//   side           from the side the focus is on (the right when centred), 10 degrees up
+//   three-quarter  between front and that side, 25 degrees up
+//   top            straight down, the character's forward up the image
+// depthViews adds a view when the asked ones would hide depth (see APART below).
+import { refPoint } from "./refs.js";
+import { objectBoxesAt } from "./object-pose.js";
+import { resolveBone } from "./bones.js";
+import { add, sub, scale, dot, cross, norm, apply, quatFromMat } from "./compiler/math.js";
+
+export const VIEW_NAMES = ["front", "side", "three-quarter", "top"];
+// FOV is the widest lens; a deep subject (a body seen from above) moves the camera back until
+// its far side is at most DEPTH_RATIO times as far as its near side, and the lens narrows (down
+// to MIN_FOV) to fill the tile again, so perspective stays mild.
+const FOV = 35, MIN_FOV = 12, DEPTH_RATIO = 1.8, MARGIN = 1.12, PAD = 0.06, MIN_HALF = 0.15, MIN_DEPTH = 0.35, UP = [0, 1, 0];
+const ELEVATION = { front: 10, side: 10, "three-quarter": 25 };
+const BARE_OBJECT = /^object:(.+?)(\.(?:center|top|base))?$/s;
+const rad = d => (d * Math.PI) / 180;
+const mean = points => scale(points.reduce(add, [0, 0, 0]), 1 / Math.max(1, points.length));
+
+const jointsAt = (out, f) => out.frames?.[f - (out.f0 ?? 0)]?.s.P ?? [];
+const corners = b => [-1, 1].flatMap(x => [0, 2].flatMap(y => [-1, 1].map(z => add(b.pos, apply(b.R, [x * b.half[0], y * b.half[1], z * b.half[2]])))));
+
+/** World points of a ref at frame f: a bare object:<id> is its part boxes' corners, any other ref its point. */
+function refPoints(out, f, ref) {
+	const bare = BARE_OBJECT.exec(ref);
+	if (bare && !bare[2]) return (objectBoxesAt(out, bare[1], f) ?? []).flatMap(corners);
+	const p = refPoint(out, f, ref);
+	return p ? [p] : [];
+}
+
+/** The character's horizontal left and forward over the frames (the hip line, summed). */
+function facingOf(out, frames) {
+	const sk = out.ctx.sk, l = sk.index[resolveBone(sk, "LeftUpLeg").bone], r = sk.index[resolveBone(sk, "RightUpLeg").bone];
+	let v = [0, 0, 0];
+	for (const f of frames) { const P = jointsAt(out, f); if (P.length) { const d = sub(P[l], P[r]); v = add(v, [d[0], 0, d[2]]); } }
+	const left = Math.hypot(v[0], v[2]) > 1e-6 ? norm(v) : [1, 0, 0];
+	return { left, forward: cross(left, UP) };
+}
+
+/** Path of a ref over absolute frames lo..hi: [{ f, p }] where it is known. */
+export function trailPoints(out, ref, [lo, hi]) {
+	const points = [];
+	for (let f = lo; f <= hi; f++) { const p = refPoint(out, f, ref); if (p) points.push({ f, p }); }
+	return points;
+}
+
+/** A camera at `back` (unit, target to eye) whose frustum holds every point (with PAD) at MARGIN. */
+function fit(name, points, back, upHint, aspect) {
+	const right = norm(cross(upHint, back)), up = cross(back, right);
+	const c0 = mean(points), rel = points.map(p => sub(p, c0)), xs = rel.map(q => dot(q, right)), ys = rel.map(q => dot(q, up)), zs = rel.map(q => dot(q, back));
+	const cx = (Math.min(...xs) + Math.max(...xs)) / 2, cy = (Math.min(...ys) + Math.max(...ys)) / 2;
+	const target = add(c0, add(scale(right, cx), scale(up, cy)));
+	// The vertical half-angle tangent each point needs from distance d (x through the aspect).
+	const need = d => Math.max(...rel.map((q, i) => MARGIN * Math.max(Math.max(Math.abs(xs[i] - cx) + PAD, MIN_HALF) / aspect, Math.max(Math.abs(ys[i] - cy) + PAD, MIN_HALF)) / (d - zs[i])));
+	const near = Math.max(...zs), far = Math.min(...zs);
+	let d = Math.max(near + MIN_DEPTH, near + (near - far) / (DEPTH_RATIO - 1)), tanV = need(d);
+	if (tanV > Math.tan(rad(FOV / 2))) {
+		// Too close for the widest lens: back off at FOV until every point fits.
+		tanV = Math.tan(rad(FOV / 2));
+		d = Math.max(d, ...rel.map((q, i) => zs[i] + MARGIN * Math.max(Math.max(Math.abs(xs[i] - cx) + PAD, MIN_HALF) / aspect, Math.max(Math.abs(ys[i] - cy) + PAD, MIN_HALF)) / tanV));
+	} else tanV = Math.max(tanV, Math.tan(rad(MIN_FOV / 2)));
+	const eye = add(target, scale(back, d)), fovDeg = Math.round((2 * Math.atan(tanV) * 180 / Math.PI) * 100) / 100;
+	tanV = Math.tan(rad(fovDeg / 2));
+	const quaternion = quatFromMat([0, 1, 2].map(i => [right[i], up[i], back[i]]));
+	return { name, eye, target, quaternion, fovDeg, aspect, right, up, back, tanV, tanH: tanV * aspect };
+}
+
+/**
+ * One camera per view name over `frames`: framed on the focus refs' points at those frames
+ * (none, or none known there: every joint of the character) and every trail point. Answers
+ * [{ name, eye, target, quaternion [x,y,z,w], fovDeg, aspect, right, up, back, tanV, tanH }].
+ * Deterministic: the same compile, frames and arguments give the same cameras.
+ */
+export function viewCameras(out, { views, frames, focus = [], trails = [], aspect = 1 }) {
+	let points = frames.flatMap(f => focus.flatMap(ref => refPoints(out, f, ref)));
+	const body = frames.flatMap(f => jointsAt(out, f));
+	if (!points.length) points = body;
+	points = [...points, ...trails.flatMap(t => t.points.map(q => q.p))];
+	if (!points.length) return [];
+	const { left, forward } = facingOf(out, frames), hips = mean(frames.map(f => jointsAt(out, f)[out.ctx.sk.index.Hips]).filter(Boolean));
+	const side = focus.length && dot(sub(mean(points), hips), left) > 0.02 ? left : scale(left, -1);
+	return views.map(name => {
+		if (name === "top") return fit(name, points, UP, forward, aspect);
+		const e = rad(ELEVATION[name]), level = name === "front" ? forward : name === "side" ? side : norm(add(forward, side));
+		return fit(name, points, add(scale(level, Math.cos(e)), scale(UP, Math.sin(e))), UP, aspect);
+	});
+}
+
+// A picture hides distance along its own line of sight, so a sheet holds two views at least APART
+// degrees apart. Front and three-quarter (45 degrees apart) look along nearly one line: the
+// guitarist's right hand 20 cm in front of the guitar (session df388a9b) showed in neither.
+// LOOK is each view's nominal direction: azimuth from the character's forward, elevation.
+const LOOK = { front: [0, 10], side: [90, 10], "three-quarter": [45, 25], top: [0, 90] }, APART = 60;
+const lookDir = name => { const [a, e] = LOOK[name].map(rad); return [Math.cos(e) * Math.sin(a), Math.sin(e), Math.cos(e) * Math.cos(a)]; };
+const apartDeg = (a, b) => Math.round(Math.acos(Math.min(1, dot(lookDir(a), lookDir(b)))) * 180 / Math.PI);
+const spread = views => views.some((a, i) => views.slice(i + 1).some(b => apartDeg(a, b) >= APART));
+
+/**
+ * The views a sheet renders: the asked ones when two of them are APART degrees apart, else the
+ * asked ones plus the first of side, front and top that makes it so. Answers { views, added }:
+ * added is null, or { view, reason } for visualRefs.
+ */
+export function depthViews(views) {
+	if (spread(views)) return { views, added: null };
+	const view = ["side", "front", "top"].find(name => !views.includes(name) && spread([...views, name]));
+	const line = views.length > 1 ? `${views.join(" and ")} look along nearly one line (${apartDeg(views[0], views[1])} degrees apart)` : `${views[0]} alone looks along one line`;
+	return { views: [...views, view], added: { view, reason: `${line}, so a gap along it (toward or away from the camera) does not show; ${view} looks across it` } };
+}
+
+/** Pixel [x, y] of world point p in a width x height image of cam, y counted from the bottom row; null behind it. */
+export function projectPoint(cam, p, width, height) {
+	const rel = sub(p, cam.eye), depth = -dot(rel, cam.back);
+	if (depth < 0.05) return null;
+	return [((dot(rel, cam.right) / (depth * cam.tanH) + 1) / 2) * width, ((dot(rel, cam.up) / (depth * cam.tanV) + 1) / 2) * height];
+}

package/src/motion3/walk-plan.js

@@ -0,0 +1,119 @@
+// walkTo { to, arrive }: the engine picks the cadence instead of the agent sweeping period and step by
+// hand. A use[i] walkTo with arrive (the frame the walk should end by, feet together: f0 + 16 + steps *
+// period + 18) and none of steps, period, step, swing gets them planned here, before the skills expand:
+//   candidates  every steps n and period p (frames per step) whose walk ends by arrive, the strides
+//               covering the distance from where the feet are at f0 to `to` (the first stride ~0.8 of
+//               the others, as walkTo's defaults), a stride at most STRIDE_MAX, the foot in the air
+//               SWING of the period;
+//   order       a person's walk ratio first (stride x cadence: stride m * period frames ~ WALK_RATIO, the
+//               default 0.5 m every 20 frames), then using the time given (a walk that ends long before
+//               arrive stands still the rest), and no stroll slower than SLOW m/s;
+//   checked     each candidate is compiled on a probe spec (the keys and skills up to the walk, the walk,
+//               nothing after it; no goals, checks or moving objects) and the first with no POP, REACH,
+//               SLIDE, FLOAT, FLIP or KNEE issue between f0 and its end wins (at most TRIALS compiles): the
+//               best on-time ones, then the top few again with a longer swing, a longer first stride or a
+//               lower lift (a quick walk often needs one of them), then the late ones, earliest first.
+// When no walk ends by arrive (the distance is too far for the frames), the earliest clean one is
+// taken and the note says the speed the request needs and the frame it ends. The spec keeps arrive (a
+// recompile plans the same walk again, cached); observations.planned reads what was chosen.
+import { expandUse } from "./skills/index.js";
+import { stateAt } from "./compiler/walk.js";
+
+const WALK_RATIO = 9.7, STRIDE_MIN = 0.25, STRIDE_MAX = 0.75, SWING = 0.88, SLOW = 0.5, TRIALS = 22, LATE = 4, FPS = 24;
+const PERIODS = Array.from({ length: 16 }, (_, i) => 9 + i);
+const PLANNED = ["steps", "period", "step", "swing"];
+const WALK_KINDS = new Set(["POP", "REACH", "SLIDE", "FLOAT", "FLIP", "KNEE"]);
+const cache = new Map();
+const r2 = x => Math.round(x * 100) / 100;
+
+/** The walkTo uses that plan their cadence: [{ i, u }]. */
+const toPlan = spec => (Array.isArray(spec?.use) ? spec.use : []).map((u, i) => ({ i, u }))
+	.filter(({ u }) => u?.skill === "walkTo" && Number.isInteger(u.args?.arrive) && Array.isArray(u.args?.to) && !PLANNED.some(k => u.args[k] !== undefined)
+		&& Object.values(u.args).every(v => !(v && typeof v === "object" && !Array.isArray(v))));
+
+/** The strides of an n-step walk over d m: { first, step } or null when no stride fits. */
+function strides(d, n) {
+	if (n === 2) return d >= STRIDE_MIN && d <= STRIDE_MAX ? { first: d, step: d } : null;
+	const first = Math.min(0.62, Math.max(0.3, (0.8 * d) / (n - 2 + 0.8))), step = (d - first) / (n - 2);
+	return step >= STRIDE_MIN && step <= STRIDE_MAX ? { first, step } : null;
+}
+
+/** Candidates for a walk of d m from f0, best first: on time (ending by arrive) by their score, then late ones by their end. */
+function candidates(d, f0, arrive) {
+	const all = [];
+	for (const period of PERIODS) for (let n = 2; n <= 40; n++) {
+		const s = strides(d, n);
+		if (!s) continue;
+		const end = f0 + 16 + n * period + 18, v = (s.step * FPS) / period;
+		const ratio = Math.abs(Math.log((s.step * period) / WALK_RATIO)), idle = Math.max(0, arrive - end) / Math.max(1, arrive - f0);
+		all.push({ args: { steps: n, period, swing: Math.round(SWING * period), step: r2(s.step), firstStep: r2(s.first) }, end, v, late: end > arrive,
+			score: ratio + 1.5 * idle + Math.max(0, SLOW - v) * 4 });
+	}
+	const onTime = all.filter(c => !c.late).sort((a, b) => a.score - b.score), late = all.filter(c => c.late).sort((a, b) => a.end - b.end || a.score - b.score);
+	return { onTime, late };
+}
+
+/** A quick walk's other shapes: a longer swing, with a longer first stride, a lower lift, or both. */
+function variants(c, d) {
+	const { steps: n, period } = c.args, swing = Math.round(0.8 * period), long = n > 2 && c.args.firstStep < 0.62 ? { firstStep: 0.62, step: r2((d - 0.62) / (n - 2)) } : null;
+	return [{}, long, { lift: 0.06 }, long && { ...long, lift: 0.06 }].filter(Boolean).map(x => ({ ...c, args: { ...c.args, swing, ...x } }))
+		.filter(v => v.args.step >= STRIDE_MIN && v.args.step <= STRIDE_MAX);
+}
+
+/** Issues in the walk's own frames (the kinds a cadence causes) of a compiled probe: a count. */
+const walkIssues = (qa, f0, end) => qa.groups.filter(g => WALK_KINDS.has(g.kind) && g.last >= f0 && g.first <= end).reduce((n, g) => n + g.count, 0);
+
+/**
+ * planWalks(spec, { sk, scene, trial }) -> [{ i, args, note }] for every walkTo with arrive (applyWalkPlans puts
+ * the args in). trial(spec) -> QA of a compile of that spec (pipeline.js), or throws.
+ */
+export function planWalks(spec, { sk, scene, trial }) {
+	const plans = [];
+	for (const { i, u } of toPlan(spec)) {
+		const key = JSON.stringify([spec.keys, spec.use.slice(0, i + 1), spec.anchors, spec.props, spec.fits, spec.fix, scene?.objects ?? null]);
+		if (cache.has(key)) { plans.push(cache.get(key)); continue; }
+		const before = spec.use.slice(0, i).filter(x => x.f0 < u.f0);
+		let state, ends = [];
+		try {
+			const { spec: exp, used } = expandUse({ ...spec, frames: 20000, use: before }, { sk, scene, lenient: true });
+			state = stateAt(exp.keys ?? [], u.f0); ends = used.map(x => x.end ?? 0);
+		} catch { state = null; }
+		if (!state?.foot_l || !state?.foot_r) continue;
+		const c0 = [(state.foot_l[0] + state.foot_r[0]) / 2, (state.foot_l[2] + state.foot_r[2]) / 2], to = u.args.to, d = Math.hypot(to[0] - c0[0], to[to.length - 1] - c0[1]);
+		const { onTime, late } = candidates(d, u.f0, u.args.arrive);
+		const probe = c => {
+			const frames = Math.max(c.end, ...ends) + 1;
+			return { schema: spec.schema, fps: spec.fps ?? FPS, frames, keys: (spec.keys ?? []).filter(k => k.f < frames), use: [...before, { ...u, args: { ...u.args, ...c.args } }],
+				...(spec.anchors ? { anchors: spec.anchors } : {}), ...(spec.props ? { props: spec.props } : {}), ...(spec.fits ? { fits: spec.fits } : {}), ...(spec.fix !== undefined ? { fix: spec.fix } : {}) };
+		};
+		let chosen = null, tried = 0, best = null, onTried = 0;
+		const order = [...onTime.slice(0, 6), ...onTime.slice(0, 3).flatMap(c => variants(c, d))].slice(0, TRIALS - LATE);
+		for (const c of [...order, ...late.slice(0, TRIALS - order.length)]) {
+			let issues;
+			try { issues = walkIssues(trial(probe(c)), u.f0, c.end); } catch { issues = Infinity; }
+			tried++; onTried += c.late ? 0 : 1;
+			if (!best || issues < best.issues) best = { c, issues };
+			if (issues === 0) { chosen = c; break; }
+		}
+		chosen ??= best?.issues < Infinity ? best.c : onTime[0] ?? late[0];
+		if (!chosen) continue;
+		const a = chosen.args, A = u.args.arrive;
+		const what = `use[${i}] walkTo arrive f${A}: steps ${a.steps}, period ${a.period}, swing ${a.swing}, step ${a.step} m, firstStep ${a.firstStep} m${a.lift ? `, lift ${a.lift} m` : ""} (${r2(chosen.v)} m/s), ends f${chosen.end}`;
+		const why = onTime.length ? `the ${onTried} walks tried that end by f${A} pop or miss a foot`
+			: `even the quickest walk over ${r2(d)} m (a step every ${PERIODS[0]} frames, strides up to ${STRIDE_MAX} m, 34 frames to start and stop) ends f${late[0]?.end}`;
+		const late1 = chosen.late ? `; f${A} is too soon: ${why}; give arrive >= f${chosen.end} or a shorter distance` : "";
+		const dirty = best && best.c === chosen && best.issues > 0 ? `; no candidate walked clean (${best.issues} issues in its frames)` : "";
+		const plan = { i, args: a, end: chosen.end, note: `${what}${late1}${dirty} (${tried} checked)` };
+		if (cache.size >= 64) cache.delete(cache.keys().next().value);
+		cache.set(key, plan);
+		plans.push(plan);
+	}
+	return plans;
+}
+
+/** The spec with every planned walk's args filled in (arrive leaves them: walkTo ignores it); the spec itself when there is none. */
+export function applyWalkPlans(spec, plans) {
+	if (!plans.length) return spec;
+	const use = spec.use.map((u, i) => { const p = plans.find(x => x.i === i); return p && u?.skill === "walkTo" ? { ...u, args: { ...u.args, ...p.args } } : u; });
+	return { ...spec, use };
+}

package/src/object-catalog.jsx

@@ -5,6 +5,8 @@ import { EMPTY_KIND, OBJECT_MENU_ENTRIES } from "./scene-objects.js";
 const GROUP_LABELS_KO = {
 	Primitives: "기본 도형",
 	"Set pieces": "세트 소품",
+	Lights: "조명",
+	Effects: "효과",
 };
 
 const OBJECT_LABELS_KO = {
@@ -18,6 +20,10 @@ const OBJECT_LABELS_KO = {
 	Chair: "의자",
 	Car: "자동차",
 	"Plane (aircraft)": "비행기",
+	"Point light": "점 조명",
+	"Spot light": "스포트 조명",
+	Light: "조명",
+	Effect: "효과",
 };
 
 function displayObjectGroupName(name) {
@@ -67,7 +73,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.kind === EMPTY_KIND ? ko("node only", "노드 전용") : `${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.footprint.width} × ${entry.footprint.depth} m`}</small>
 				</button>
 			))}
 		</div>

package/src/object-colors.js

@@ -0,0 +1,98 @@
+/**
+ * The inspector's object colours: the blockout palette, what a typed colour
+ * means, and the per-browser memory of hand-mixed tints. Pure, so the record
+ * normalizers and the light/glow fields read the same hex rules.
+ */
+
+/** Blockout grey: what a primitive is until someone says otherwise. */
+export const GREY_BOX = "#c2c6c8";
+
+/** Blockout greys first, then the clay accents, then the blocking chromatics,
+ * for re-tinting from the inspector. The greys lead because a blockout starts
+ * grey; the saturated four exist so a shot can say "the red ball, the blue
+ * box" at a glance — the inspector had no way to say that at all (#88). They
+ * are muted off pure RGB so they still read as clay under the set's lighting.
+ * Any other colour is authored through the inspector's free colour input. */
+export const OBJECT_COLORS = [
+	"#e2e5e6",
+	GREY_BOX,
+	"#9aa1a5",
+	"#767d81",
+	"#d9b18c",
+	"#8fae9b",
+	"#d94a4a",
+	"#4a7bd9",
+	"#e2c04a",
+	"#4fa86a",
+];
+
+/** How many hand-mixed colours the inspector remembers. Six is one palette
+ * row: enough to keep a scene's custom tints reachable, short enough that the
+ * popover never turns into a second, unruly palette. */
+const RECENT_OBJECT_COLORS_MAX = 6;
+/** Session memory of hand-mixed tints; versioned like every other key here. */
+const RECENT_OBJECT_COLORS_KEY = "cozyclay.objectColors.recent";
+
+const HEX_SHORT = /^#?([0-9a-f]{3})$/i;
+const HEX_LONG = /^#?([0-9a-f]{6})$/i;
+
+/**
+ * What a colour input typed by a human means, or null if it means nothing.
+ *
+ * The hex field accepts what people actually type — `#f36`, `ff3366`, upper
+ * case, stray spaces — and folds it to the one form the record stores, so a
+ * colour typed by hand and the same colour picked from the native swatch are
+ * byte-identical (and therefore compare equal against the palette). Anything
+ * else returns null rather than throwing or guessing: a half-typed `#12` is a
+ * keystroke on the way somewhere, not an instruction to repaint the prop.
+ */
+export function normalizeObjectColor(value) {
+	if (typeof value !== "string") return null;
+	const text = value.trim();
+	const short = HEX_SHORT.exec(text);
+	if (short) return `#${short[1].toLowerCase().replace(/./g, (digit) => digit + digit)}`;
+	const long = HEX_LONG.exec(text);
+	return long ? `#${long[1].toLowerCase()}` : null;
+}
+
+/**
+ * The recent-colours list after mixing `hex`: newest first, no duplicates,
+ * capped, presets excluded.
+ *
+ * Pure so the list can be proved without a browser, and so a corrupt stored
+ * list is repaired on the way through instead of painting a swatch with junk.
+ * Presets are skipped because they are already one row up — remembering them
+ * would push the author's own colours off the end with colours they never
+ * mixed. Returns the SAME array when nothing changes, so a re-pick of an
+ * unchanged colour cannot trigger a storage write or a re-render.
+ */
+export function rememberObjectColor(list, hex) {
+	const clean = Array.isArray(list)
+		? list.map(normalizeObjectColor).filter((color, index, all) => color && all.indexOf(color) === index && !OBJECT_COLORS.includes(color))
+		: [];
+	const color = normalizeObjectColor(hex);
+	const next = color && !OBJECT_COLORS.includes(color) ? [color, ...clean.filter((entry) => entry !== color)] : clean;
+	const capped = next.slice(0, RECENT_OBJECT_COLORS_MAX);
+	const unchanged = Array.isArray(list) && capped.length === list.length && capped.every((entry, index) => entry === list[index]);
+	return unchanged ? list : capped;
+}
+
+/** Recent colours as last left by this browser; storage can be unavailable
+ * (private mode), and a corrupt body must not take the inspector down with
+ * it — either way the palette simply starts without a memory. */
+export function readStoredObjectColors(storage) {
+	try {
+		const parsed = JSON.parse(storage?.getItem(RECENT_OBJECT_COLORS_KEY) ?? "[]");
+		return rememberObjectColor(Array.isArray(parsed) ? parsed : [], null);
+	} catch {
+		return [];
+	}
+}
+
+export function writeStoredObjectColors(storage, list) {
+	try {
+		storage?.setItem(RECENT_OBJECT_COLORS_KEY, JSON.stringify(list));
+	} catch {
+		// Storage can be unavailable (private mode); the colours simply stop persisting.
+	}
+}