cozyclay 3.1.6 → 3.2.1

package/src/motion/fingertip-pick.js

@@ -0,0 +1,21 @@
+/**
+ * The fingertip a press grabs. Candidates are `{ id, gap, reach, ... }`: the
+ * press's pixel distance to the tip's projected centre, and how far the tip
+ * reaches on screen. In range tips are tried nearest first, and the first one
+ * `isExposed(candidate)` accepts wins, so a tip the body hides (behind the palm
+ * or other fingers) is skipped for the next visible one. Null when no exposed
+ * tip is in range: the press is left for the IK handles (#913).
+ */
+export function pickFingertip(candidates, isExposed) {
+	return candidates
+		.filter((candidate) => candidate.gap <= candidate.reach)
+		.sort((a, b) => a.gap - b.gap)
+		.find((candidate) => isExposed(candidate)) ?? null;
+}
+
+/** Pick for a pointerdown and claim the event only when a tip is picked; otherwise it passes on untouched. */
+export function claimFingertip(event, candidates, isExposed) {
+	const picked = pickFingertip(candidates, isExposed);
+	if (picked) { event.stopImmediatePropagation(); event.stopPropagation(); event.preventDefault(); }
+	return picked;
+}

package/src/motion/fix-collisions.js

@@ -287,7 +287,7 @@ function restPairOverlaps(rig, radii = null) {
 /** Closest points between two segments (Ericson, Real-Time Collision
  * Detection — the textbook segment/segment distance). Writes into outA/outB
  * and returns the squared distance. */
-function closestPointsSegmentSegment(p1, q1, p2, q2, outA, outB) {
+export function closestPointsSegmentSegment(p1, q1, p2, q2, outA, outB) {
 	const d1 = q1.clone().sub(p1);
 	const d2 = q2.clone().sub(p2);
 	const r = p1.clone().sub(p2);

package/src/motion/ik-drag.js

@@ -1,4 +1,10 @@
-import { createIkState, ikBakeKeyframe, ikTouch } from "./ik.js";
+import * as THREE from "three";
+import { clampIkTargetToFloor, createIkState, ikBakeKeyframe, ikTouch, MID_TRACKS, solveIk, solveMidJoint } from "./ik.js";
+import { buildCollisionCapsules } from "./fix-collisions.js";
+import { blockerCharacterId, characterBlockers } from "./collision-blockers.js";
+import { createContactProjector } from "./contact-project.js";
+import { allowance } from "../motion3/qa/checks.js";
+import { ko } from "../locale.js";
 
 /**
  * Per-drag bookkeeping for manual IK drags over a loaded motion.
@@ -16,6 +22,92 @@ export function ikDragRecord(current, frame) {
 	return current && current.frame === frame ? current : { frame, ids: new Set() };
 }
 
+// Told once per drag, the first time the projection moves the handle.
+const contactHint = () => ko("Stopped at the other character's body. Hold Alt while dragging to pass through",
+	"다른 인물의 몸에 닿아 멈췄어요. Alt를 누른 채 드래그하면 통과해요", "已停在另一个角色的身体上。按住 Alt 拖动即可穿过");
+// Studio capsule id -> the motion3 QA part an allow entry names (qa/geometry.js CAPSULES).
+const QA_PART = { UpperArm: "uarm", ForeArm: "farm", Hand: "hand", Thigh: "thigh", Shin: "shin", Foot: "foot" };
+const qaPart = (capsuleId) => capsuleId.replace(/^(left|right)(\w+)$/, (_, side, part) => `${QA_PART[part] ?? part}_${side[0]}`);
+
+/** The contact side of a drag, built once when it opens: the other cast members'
+ * capsules as they stand now (they do not move during a drag), the dragged
+ * chain's own capsules (upper arm, forearm, hand / thigh, shin, foot; no
+ * fingers) and the active take's person allowances (spec.checks.allow
+ * `{ part, object: "person:<id>", depth }`, read as QA reads them). */
+function openDragContact(kind, chain, { rigs, activeId, cast = null, allow = null, notify = null }) {
+	const blockers = characterBlockers(rigs, activeId, { characterIds: cast });
+	const own = blockers.length ? buildCollisionCapsules(chain.rig) : null;
+	if (!own) return null;
+	const capsules = [...own.values()].filter((c) => c.def.movable?.chain === chain.track.id && !c.def.handId && !c.def.optional);
+	const allowFor = (probeId, blockerId) => allowance(allow, qaPart(probeId), `person:${blockerCharacterId(blockerId)}`);
+	const reads = capsules.map((c) => ({ id: c.def.id, start: c.bones[0], end: c.bones[1] ?? c.bones[0], radius: c.radius, a: c.a.clone(), b: c.b.clone() }));
+	const contact = {
+		projector: createContactProjector({ blockers, allow: allowFor }),
+		pose: null, // this event's starting locals, set by clampDragTarget
+		// the limb's capsules as the drag will DISPLAY them with its handle at
+		// `candidate`: the drag's own solve, from this event's starting pose
+		probe: (candidate) => {
+			restorePose(chain, contact.pose);
+			solveDragTarget(kind, chain, candidate);
+			return contact.shown();
+		},
+		// the limb's capsules as they stand (the pose on screen at event start)
+		shown: () => {
+			for (const read of reads) { read.start.getWorldPosition(read.a); read.end.getWorldPosition(read.b); }
+			return reads;
+		},
+		handle: chain.bones[kind === "mid" ? 1 : 2],
+		lastGood: chain.bones[kind === "mid" ? 1 : 2].getWorldPosition(new THREE.Vector3()),
+		notify,
+	};
+	return contact;
+}
+
+function restorePose(chain, pose) {
+	chain.bones.forEach((bone, i) => bone.quaternion.copy(pose[i]));
+	chain.bones[0].updateMatrixWorld(true);
+}
+
+/** The solve a chain or mid drag applies toward its handle (domains/motion.js
+ * ikSolve). The contact probe runs this same call from the same starting pose,
+ * so the pose it checks is exactly the pose the drag displays. (A probe on a
+ * different solve, e.g. exactHinge, lands the elbow and hand elsewhere from a
+ * bent pose and passed targets whose displayed limb sat inside the other body.) */
+export function solveDragTarget(kind, chain, target) {
+	if (kind === "mid") solveMidJoint(chain, target);
+	else solveIk(chain, target);
+}
+
+/**
+ * Where a chain or mid drag may put its handle: on the floor with Body contact,
+ * then out of the other characters (contact-project.js). `open()` returns
+ * `{ rigs, activeId, cast, allow }` and is read once, on the first event of the
+ * drag (`record` keeps the result). `bypass` (Alt held) skips the contact
+ * projection for that event and leaves the side to keep untouched.
+ */
+export function clampDragTarget({ kind, trackId, targetWorld, bodyContact, chains, record = null, open = null, bypass = false }) {
+	const chain = chains?.get(kind === "mid" ? MID_TRACKS.find((t) => t.id === trackId)?.chain : trackId);
+	const heights = chain?.contactHeights ?? chains?.values().next().value?.contactHeights;
+	const floored = bodyContact ? clampIkTargetToFloor(trackId, targetWorld, 0, heights) : targetWorld;
+	if (!chain || !record || !open || (kind !== "chain" && kind !== "mid")) return floored;
+	if (record.contact === undefined) record.contact = openDragContact(kind, chain, open());
+	const contact = record.contact;
+	if (!contact || bypass) return floored;
+	// every probe starts from this event's pose, and the limb goes back to it
+	// so the caller's solveDragTarget starts there too
+	contact.pose = chain.bones.map((bone) => bone.quaternion.clone());
+	// the sweep starts from the limb as displayed, not from a re-solve toward lastGood
+	const from = { at: contact.handle.getWorldPosition(new THREE.Vector3()), capsules: contact.shown() };
+	const { target, depth } = contact.projector.project(floored, contact.probe, contact.lastGood, from);
+	restorePose(chain, contact.pose);
+	if (depth === 0) contact.lastGood = target.clone();
+	if (!target.equals(floored) && !contact.told) {
+		contact.told = true;
+		contact.notify?.(contactHint());
+	}
+	return target;
+}
+
 /** Mark `id` as written by this drag and touch it into the live layer. */
 export function ikDragTouch(ikState, record, id) {
 	ikTouch(ikState, id);

package/src/motion/ik-exposure.js

@@ -0,0 +1,48 @@
+import { Raycaster, Vector3 } from "three";
+import { ikControlIsExposed } from "./ik.js";
+
+/**
+ * Distance from the camera to the first opaque surface on the way to a control
+ * `targetDistance` away along `direction`, or undefined when nothing is in front.
+ * Static blockers are raycast; a skinned mesh is read off its cached cloud of
+ * skin-surface spheres ({ points, radius }), which keeps the animated silhouette
+ * without skinning every triangle once per control ray.
+ */
+export function blockerDistanceTo(ray, cameraPos, direction, targetDistance, staticBlockers, skinnedProxies) {
+	ray.set(cameraPos, direction);
+	ray.near = 0.001;
+	ray.far = Math.max(0.001, targetDistance - 0.001);
+	let blockerDistance = ray.intersectObjects(staticBlockers, false)[0]?.distance;
+	for (const proxy of skinnedProxies) {
+		const radiusSq = proxy.radius * proxy.radius;
+		for (const point of proxy.points) {
+			const dx = point.x - cameraPos.x, dy = point.y - cameraPos.y, dz = point.z - cameraPos.z;
+			const along = dx * direction.x + dy * direction.y + dz * direction.z;
+			if (along < 0 || along > targetDistance + proxy.radius) continue;
+			const perpendicularSq = dx * dx + dy * dy + dz * dz - along * along;
+			if (perpendicularSq > radiusSq) continue;
+			const distance = Math.max(0, along - Math.sqrt(radiusSq - perpendicularSq));
+			if (distance < (blockerDistance ?? Infinity)) blockerDistance = distance;
+		}
+	}
+	return blockerDistance;
+}
+
+/**
+ * An exposure probe over the blockers of the last IkHandles exposure pass:
+ * `(worldPoint, visibilityDepth) => boolean`, the same rule the IK controls use.
+ * A fingertip is smaller than the 4 cm skin-proxy spheres (neighbouring fingers
+ * read as blockers), so the probe raycasts the skinned meshes themselves; it runs
+ * once per press, not per frame. Before any pass nothing is in front: exposed.
+ */
+export function exposureProbe(camera, occluders) {
+	const ray = new Raycaster(), cameraPos = new Vector3(), direction = new Vector3();
+	ray.layers.set(0);
+	return (point, visibilityDepth) => {
+		camera.getWorldPosition(cameraPos);
+		const targetDistance = cameraPos.distanceTo(point);
+		direction.copy(point).sub(cameraPos).normalize();
+		const blockerDistance = blockerDistanceTo(ray, cameraPos, direction, targetDistance, occluders.current?.blockers ?? [], []);
+		return ikControlIsExposed(targetDistance, blockerDistance, visibilityDepth);
+	};
+}

package/src/motion/ik.js

@@ -1,5 +1,8 @@
 import * as THREE from "three";
 import { normalizeBoneName, POSE_BONES, DEFAULT_POSE } from "../poses.js";
+import { resolveFingers } from "./fingers.js";
+import { findBone } from "./find-bone.js";
+export { findBone };
 
 /**
  * Frame-based IK layer for direct character posing, following the DCC
@@ -412,16 +415,6 @@ const CHAINS = {
 	leg: (side) => [`mixamorig${side}UpLeg`, `mixamorig${side}Leg`, `mixamorig${side}Foot`],
 };
 
-export function findBone(root, name) {
-	const target = normalizeBoneName(name);
-	let found = null;
-	root.traverse((object) => {
-		if (found || !object.isBone) return;
-		const norm = normalizeBoneName(object.name);
-		if (norm === target || norm.endsWith(target)) found = object;
-	});
-	return found;
-}
 
 /**
  * Resolve the IK rig against a character: the four two-bone chains, plus
@@ -508,7 +501,7 @@ export function resolveIkRig(rig) {
 			})(),
 		});
 	}
-	return { chains: out, fkJoints, contactRadii, contactHeights: measureContactHeights(rig) };
+	return { chains: out, fkJoints, fingers: resolveFingers(rig, fkJoints), contactRadii, contactHeights: measureContactHeights(rig) };
 }
 
 /**

package/src/motion/timeline.css

@@ -1427,3 +1427,15 @@
 .v2-sequencer .objmo .sg { position: absolute; inset: 0; }
 .v2-sequencer .objmo .sg-head { padding: 3px 10px 2px; }
 .v2-sequencer .objmo .sg-body { min-height: 36px; margin: 0 0 6px; }
+
+/* The motion controls' Physics box (physics-toggle.jsx) */
+.v2-sequencer .tl-btn.physics {
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	cursor: pointer;
+}
+
+.v2-sequencer .tl-btn.physics input {
+	margin: 0;
+}

package/src/motion/timeline.jsx

@@ -10,7 +10,7 @@ import { insertPathMark, pathMarks, pathMetrics, pathProgressAt, MAX_PATH_LEAN }
 import { NumberField } from "../ui.jsx";
 import { flatTiming, timingIsFlat, envelopeDrag, insertCut, removeCut, CUT_MIN_GAP } from "../speed-envelope.js";
 import { checkShotAgainstPreset, presetById } from "../model-presets.js";
-import { TakeSegmentClips, TakeSegmentTools } from "./take-segments.jsx"; import { BeatBoard } from "./beat-board.jsx";
+import { TakeSegmentClips, TakeSegmentTools } from "./take-segments.jsx"; import { BeatBoard } from "./beat-board.jsx"; import { PhysicsToggle } from "../physics-toggle.jsx";
 import "./timeline.css";
 export { timelineTake } from "./take-segments.jsx";
 
@@ -1708,7 +1708,7 @@ export default function Timeline({
 						</div>
 						{onClearMotion && (
 							<div className="tl-head-group tl-motion-tools" role="group" aria-label={ko("Motion controls", "모션 컨트롤")}>
-								{motion?.segments && motionTools && <TakeSegmentTools motion={motion} frame={frame} />}
+								{motion?.segments && motionTools && <TakeSegmentTools motion={motion} frame={frame} />}{motionTools && <PhysicsToggle />}
 								<button
 									type="button"
 									className="tl-btn clear"

package/src/motion3/compile-job.js

@@ -65,8 +65,9 @@ export function runCompileJob({ model, scene, spec: asked, probes: sentProbes, c
 	// ms.repair: the whole repair's wall time, so a sweep that repairs every variant shows what it costs
 	const r = fixed.result, label = fixed.spec?.label ?? null, ms = fixed.repair ? { ...r.ms, repair: Math.round(performance.now() - t0) } : r.ms;
 	const take = bake ? bakeTake(sk, r.out, { position: bake.position, yaw: bake.yaw }, { spec: r.stored, prompt: ("prompt" in bake ? bake.prompt : label) ?? "" }) : undefined;
-	// a person anchor's joints ride with the take, so its saved source compiles the same without the others' takes (people.js)
-	const people = take && keptPeople(scene, [r.expanded, r.stored]);
+	// a person anchor's joints (and the bodies fix.person pushed an arm out of) ride with the take, so its saved source
+	// compiles the same without the others' takes (people.js)
+	const people = take && keptPeople(scene, [r.expanded, r.stored], r.out);
 	if (people) take.people = people;
 	return { stored: r.stored, qa: r.qa, observations: r.observations, used: r.used, fixed: r.fixed, search: r.search, timeline: r.timeline,
 		...(r.probes ? { probes: r.probes } : {}), ...(r.notes || corrected.length ? { notes: [...corrected, ...(r.notes ?? [])] } : {}), ms, frameCount: r.out.frameCount, label,

package/src/motion3/compiler/compile.js

@@ -20,7 +20,7 @@
 // ctx = { sk, scene: { objects: { id: { pos, R, half, ancestors } } } }; out.ctx.scene keeps the scene (object-pose.js)
 import { add, sub, scale, norm, len, dot, apply, axisRot } from "./math.js";
 import { isCarried, isFollow, hingePose, movesRecord, compose, relative } from "../carried.js";
-import { isFree, freePoseAt } from "../free-motion.js";
+import { isFree, freeSwungAt } from "../free-motion.js";
 import { groupsOf } from "../scene.js";
 import { pose, SIDES } from "./pose.js";
 import { graspAnchor } from "./socket-grip.js";
@@ -46,7 +46,7 @@ const REACH_SLACK = 0.02;
 
 /**
  * Scene boxes by frame. A body moves with its own spec.objects entry or its nearest group's (a
- * switch entry moves nothing; hinge: turned; free (C17): where its keys and falls put it, under the time map `mapOf()`;
+ * switch entry moves nothing; hinge: turned; free (C17): where its keys and falls put it, under the time map `mapOf()`, swung by its spring;
  * carry and follow: left at its scene pose and marked `carried` with the moving id). `obstacles` drops the carried
  * ones: QA, refs and object anchors read a carry where it rides (object-pose.js objectPoseAt, qa/object-checks.js);
  * a follow entry rides the body and is no obstacle.
@@ -63,7 +63,7 @@ function objectTracks(spec, scene, baked, mapOf = () => undefined) {
 			const mover = [id, ...(o.ancestors ?? [])].find(k => movesRecord(spec.objects?.[k])), entry = spec.objects?.[mover];
 			if (!entry) out[id] = o;
 			else if (isCarried(entry) || isFollow(entry)) out[id] = { ...o, carried: mover };
-			else if (isFree(entry)) out[id] = { ...o, ...compose(freePoseAt({ spec, scene, timeMap: map }, mover, f), relative(scene.objects[mover] ?? groupsOf(scene)[mover], o)) };
+			else if (isFree(entry)) out[id] = { ...o, ...compose(freeSwungAt({ spec, scene, timeMap: map }, mover, f), relative(scene.objects[mover] ?? groupsOf(scene)[mover], o)) };
 			else out[id] = { ...o, ...hingePose(entry, o, baked, f) };
 		}
 		cache.set(f, out);

package/src/motion3/compiler/head-lead.js

@@ -5,10 +5,12 @@
 // step, head-steady.js walkSpans) and around every turn of the trunk faster than TURN deg/frame (from LEAD + FADE
 // frames before it, so the head starts first), faded in and out over FADE frames, and never where the spec's own keys move
 // head_yaw during that span (keys on it, or on either side of it, that differ): a keyed look wins; a head held still
-// (a stance's head_yaw 0) leads.
+// (a stance's head_yaw 0) leads. A skill's own look that rides a turn (NOT_A_LOOK: exitCar's head as it swivels out of
+// the seat) is not a keyed look: the lead goes on top of it. The agent's keys, and every other skill's, still win.
 import { walkSpans } from "./head-steady.js";
 
 const MAX = 30, TURN = 0.3, FADE = 8, STRIDE = 33;
+const NOT_A_LOOK = /\bwalk(To)? (start|step \d+|end)$|^use\[\d+\] exitCar$/; // walk.js keys, OWN_LOOK skills (skills/car.js)
 
 /** Inside a walk the trunk's heading, its sway each step taken out: the median over about a stride keeps a turn's timing. */
 function heading(trunk, walks) {
@@ -45,7 +47,7 @@ function merged(spans) {
 
 /** The keys outside walks that move head_yaw during [f0, f1]: those in it and the nearest on either side differ. */
 function looked(keys, f0, f1) {
-	const looks = keys.filter(k => k.set?.head_yaw !== undefined && !/\bwalk(To)? (start|step \d+|end)$/.test(k.src ?? "")).sort((a, b) => a.f - b.f);
+	const looks = keys.filter(k => k.set?.head_yaw !== undefined && !NOT_A_LOOK.test(k.src ?? "")).sort((a, b) => a.f - b.f);
 	const near = [looks.filter(k => k.f < f0).at(-1), ...looks.filter(k => k.f >= f0 && k.f <= f1), looks.find(k => k.f > f1)].filter(Boolean);
 	return near.some(k => JSON.stringify(k.set.head_yaw) !== JSON.stringify(near[0].set.head_yaw));
 }

package/src/motion3/compiler/spring.js

@@ -0,0 +1,95 @@
+// Spring secondary motion for a carried or free object (spec.objects[id].spring = { length, stiffness, damping }): a damped
+// pendulum hung on the object's anchor lags the anchor's horizontal acceleration, swings and settles. Computed once at
+// compile time (object-pose.js rootPoseAt); playback, scrub and export read the baked track only.
+//
+// Determinism: a fixed step dt = 1 / fps from frame 0 on, semi-implicit Euler, and the solver update uses
+// only + - * / and Math.sqrt, so every engine computes the same bits. Only the last step, the swing angles to a turn,
+// goes through the quaternion helpers (quat.js), as every other baked rotation does.
+//
+// State: two swing angles th = [tx, tz] (rad), how far the object's far end swings toward world +X and +Z, and their
+// rates w. Per frame f: a = (p[f] - 2 p[f-1] + p[f-2]) * fps^2 (0 on frames 0 and 1), then
+//   w = (w + (-k th - a_h / L) dt) / (1 + c dt) ;  th += w dt ;  c = 2 d sqrt(k)
+// with k the stiffness (1/s^2), d the damping ratio (0..1, 1 critical) and L the pendulum length (m): spring.length, else
+// half the object's longest side (springLength). Without a stiffness k = G / L, a real pendulum's sqrt(g / L). The damping is
+// implicit, so no damping ratio makes it ring up (an explicit c dt > 1 diverged); the stiffness step stays stable while
+// sqrt(k) dt < 2, and the schema caps k at SPRING.stiffness.max (500) so that sqrt(k) dt <= 1 from 24 fps up.
+import { qexp, qmul, qnorm } from "./quat.js";
+import { quatFromMat, matFromQuat } from "./math.js";
+
+/** The schema's ranges and defaults (schema/types.js reads them; validate-objects.js checks them). No stiffness default: G / length. */
+export const SPRING = { length: { min: 0.05, max: 2 }, stiffness: { min: 0, max: 500 }, damping: { min: 0, max: 1, default: 0.5 } };
+/** Gravity, m/s^2 (qa/style.js and skills/impact.js use the same value). */
+const G = 9.81;
+/** The largest swing drawn, rad (60 degrees). */
+const SPRING_MAX = Math.PI / 3;
+/** The shortest pendulum, m: a tiny prop swings as if it were this long. */
+const SPRING_MIN_LENGTH = 0.05;
+
+const clampSwing = v => (v > SPRING_MAX ? SPRING_MAX : v < -SPRING_MAX ? -SPRING_MAX : v);
+
+/** The resting state: no swing, no anchor history. */
+export const springRest = () => ({ th: [0, 0], w: [0, 0], p1: null, p2: null });
+
+/**
+ * One frame: the state after anchor position p (world [x, y, z]) is fed to `state` (the state after the frame before).
+ * Pure: returns a new state. opts = { fps, stiffness, damping, length }.
+ */
+export function springStep(state, p, { fps, stiffness, damping, length }) {
+	const dt = 1 / fps, k = stiffness, c = 2 * damping * Math.sqrt(stiffness), L = length > SPRING_MIN_LENGTH ? length : SPRING_MIN_LENGTH;
+	let ax = 0, az = 0;
+	if (state.p1 && state.p2) {
+		const f2 = fps * fps;
+		ax = (p[0] - 2 * state.p1[0] + state.p2[0]) * f2;
+		az = (p[2] - 2 * state.p1[2] + state.p2[2]) * f2;
+	}
+	const wx = (state.w[0] + (-k * state.th[0] - ax / L) * dt) / (1 + c * dt);
+	const wz = (state.w[1] + (-k * state.th[1] - az / L) * dt) / (1 + c * dt);
+	return { th: [state.th[0] + wx * dt, state.th[1] + wz * dt], w: [wx, wz], p1: [p[0], p[1], p[2]], p2: state.p1 };
+}
+
+/**
+ * The solver options for spring entry `spring` ({ length?, stiffness?, damping? }) at `fps`: the length given, else
+ * `fallback` (springLength of the object); the stiffness given, else G / length; the damping given, else 0.5.
+ */
+export function springOpts(spring, fps, fallback = SPRING_MIN_LENGTH) {
+	const length = Math.max(SPRING_MIN_LENGTH, spring?.length ?? fallback);
+	return { fps, stiffness: spring?.stiffness ?? G / length, damping: spring?.damping ?? SPRING.damping.default, length };
+}
+
+/**
+ * The swing of every frame for anchor positions `anchors` (one world [x, y, z] per frame from frame 0):
+ * [[tx, tz], ...] rad, each clamped to +-60 degrees. A still anchor gives 0 on every frame. Defaults as springOpts.
+ */
+export function springAngles({ anchors, fps, stiffness, damping, length }) {
+	const opts = springOpts({ stiffness, damping, length }, fps), out = [];
+	let state = springRest();
+	for (const p of anchors) {
+		state = springStep(state, p, opts);
+		out.push([clampSwing(state.th[0]), clampSwing(state.th[1])]);
+	}
+	return out;
+}
+
+/** The clamped swing of a state. */
+export const swingOf = state => [clampSwing(state.th[0]), clampSwing(state.th[1])];
+
+/**
+ * Pose { pos, R } turned by swing th = [tx, tz] about its own base (position unchanged): +tx swings what hangs below
+ * toward +X (a turn about +Z), +tz toward +Z (a turn about -X). The turn is applied in world axes on top of R.
+ */
+export function swungPose(pose, th) {
+	if (th[0] === 0 && th[1] === 0) return pose;
+	const turn = qexp([-th[1], 0, th[0]]);
+	return { ...pose, pos: pose.pos, R: matFromQuat(qnorm(qmul(turn, quatFromMat(pose.R)))) };
+}
+
+/** Pendulum length of a body or group from its boxes [{ pos, R, half }]'s corners: half the longest side of their bounding box, at least 5 cm. */
+export function springLength(corners) {
+	if (!corners.length) return SPRING_MIN_LENGTH;
+	let longest = 0;
+	for (let i = 0; i < 3; i++) {
+		const vs = corners.map(c => c[i]);
+		longest = Math.max(longest, Math.max(...vs) - Math.min(...vs));
+	}
+	return Math.max(SPRING_MIN_LENGTH, longest / 2);
+}

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

@@ -9,7 +9,8 @@
 // or from its release on. Fields: schema/fields.js OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS. See validate.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 { OBJECT_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS, SPRING_FIELDS } from "../schema/fields.js";
+import { SPRING } from "./spring.js";
 import { isSwitch, isFollow, movesRecord } from "../carried.js";
 import { isFree } from "../free-motion.js";
 import { checkRef } from "../refs.js";
@@ -99,6 +100,18 @@ function validateFalls(err, unknown, at, o, { frames, scene, carry }) {
 	});
 }
 
+/** objects.<id>.spring: { length?, stiffness?, damping? }, each a number in its SPRING range (a larger stiffness would blow the fixed-step solver up). */
+function validateSpring(err, unknown, at, o) {
+	const sp = o.spring, SPR = "{ length?, stiffness?, damping? }";
+	if (!sp || typeof sp !== "object" || Array.isArray(sp)) return err(`${at}.spring must be ${SPR}, got ${fmt(sp)}`);
+	for (const k of Object.keys(sp)) if (!SPRING_FIELDS.includes(k)) unknown(`${at}.spring has unknown field "${k}"${didYouMean(k, SPRING_FIELDS)}; a spring is ${SPR}`);
+	const what = { length: "string or rod length, m", stiffness: "how fast it swings back, 1/s^2", damping: "how soon it settles, 1 = no overshoot" };
+	for (const k of SPRING_FIELDS) {
+		const v = sp[k], { min, max } = SPRING[k];
+		if (v !== undefined && !(Number.isFinite(v) && v >= min && v <= max)) err(`${at}.spring.${k} must be ${min}..${max} (${what[k]}), got ${fmt(v)}`);
+	}
+}
+
 /** 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) {
@@ -122,7 +135,8 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 		const at = `objects.${id}`, kind = o?.prop !== undefined ? "carry" : isFollow(o) ? "follow" : isFree(o) ? "free" : isSwitch(o) ? "switch" : "hinge", fields = OBJECT_FIELDS[kind];
 		// 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(", ")}`);
+		if (kind === "hinge" && o?.spring !== undefined) err(`${at}.spring: spring is not for hinged objects; a hinge turns only by its channel (give spring to a carry or a free entry)`);
+		for (const f of Object.keys(o ?? {})) if (!fields.includes(f) && !(kind === "hinge" && (f === "keys" || f === "fall" || f === "spring"))) 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);
@@ -137,6 +151,7 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 		if (kind === "free") {
 			if (o.keys !== undefined) validateKeys(err, unknown, at, o, frames, true);
 			if (o.fall !== undefined) validateFalls(err, unknown, at, o, { frames, scene, carry: false });
+			if (o.spring !== undefined) validateSpring(err, unknown, at, o);
 			channelsOk(err, at, o);
 			continue;
 		}
@@ -149,6 +164,7 @@ export function validateObjects(spec, err, { sk, scene, frames = spec.frames, un
 				&& o.grab !== undefined && o.release !== undefined && !(o.grab < o.release)) err(`${at}: grab (${o.grab}) must come before release (${o.release})`);
 			if (o.keys !== undefined) validateKeys(err, unknown, at, o, frames);
 			if (o.fall !== undefined) validateFalls(err, unknown, at, o, { frames, scene, carry: true });
+			if (o.spring !== undefined) validateSpring(err, unknown, at, o);
 			continue;
 		}
 		if (o?.keys !== undefined || o?.fall !== undefined) err(`${at}: a hinge turns by its channel "${o.channel}", keyed in spec.keys; keys and fall move an object with no pivot, axis or channel (C17), or a carried one (prop)`);

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

@@ -114,6 +114,7 @@ function validateChecks(spec, err, { sk, scene, frames, unknown = err, past = ""
 	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)}`);
+	if (fix && fix.person !== undefined && typeof fix.person !== "boolean") err(`spec.fix.person must be true (arms kept out of the other characters, the default) or false, got ${fmt(fix.person)}`);
 }
 
 /** opts = { sk, scene, frames, lenient, unknown: err for an unknown field (a no-op when lenient), past: the

package/src/motion3/compiler/vocab.js

@@ -27,7 +27,7 @@ const RANGES = [
 	[/^wflex_[lr]$/, -70, 70, "flex about the knuckle line, deg"],
 	[/^fpitch_[lr]$/, -60, 90, "toe-down pitch, deg: + lifts the heel (toes flat), - lifts the toes"],
 	// the whole-body pitch and roll have none: they turn in full (flips, cartwheels; pose.js tiltFrame)
-	[/^(spine_pitch|head_pitch)$/, -120, 120, "degrees, + bends forward"],
+	[/^(spine_pitch|head_pitch)$/, -120, 120, "deg, + bends forward"],
 	[/^(spine_roll|head_roll)$/, -90, 90, "degrees"],
 ];
 export const rangeOf = ch => RANGES.find(([re]) => re.test(ch)) ?? null;

package/src/motion3/fix/index.js

@@ -2,7 +2,7 @@
 // the baked channels or the per-frame IK offsets and re-solves only the frames it touched, so QA
 // still measures the final frames; every fix reports what it changed (counts, worst amount).
 //
-// spec.fix = { reach: true, slide: true, penetration: 0.02, self: true, retime: false } (false = all off)
+// spec.fix = { reach: true, slide: true, penetration: 0.02, self: true, retime: false, person: true } (false = all off)
 //   reach        wrist targets past the arm's reach go onto it through a soft knee (no snap);
 //                ankle targets past the leg's reach lower the hips just enough, eased in and out; a hand
 //                on a pinned target (a world or a scene object's anchor) that the straight arm misses brings
@@ -18,6 +18,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)
+//   person       arms out of the other characters (scene.people, their installed takes; QA PERSON): the wrist
+//                target moves out by the depth, back the side the hand came from, eased in and out (person.js)
 //   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";
@@ -28,15 +30,16 @@ import { liftSoles } from "./ground.js";
 import { pushOut } from "./push.js";
 import { retime } from "./retime.js";
 import { selfClear } from "./self.js";
+import { personOut } from "./person.js";
 
-const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance", "grasp"];
+const FIX_KEYS = ["reach", "slide", "penetration", "self", "retime", "stance", "grasp", "person"];
 export { FIX_KEYS };
 
 export function fixOptions(fix) {
-	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false, grasp: false };
+	if (fix === false) return { reach: false, slide: false, penetration: 0, self: false, retime: false, stance: false, grasp: false, person: 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, grasp: f.grasp !== 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, person: f.person !== false };
 }
 
 /** The slide report with the flat feet whose turn waited (turn.js): turns { frames, max deg }. */
@@ -55,6 +58,7 @@ export function applyFixes(out, fix, engine, { whole = true } = {}) {
 	if (fix.reach && fixed.slide?.pivots) put("reachLegs", mergeReach(fixed.reachLegs, lowerHips(out, engine)));
 	if (fix.penetration > 0) put("penetration", pushOut(out, engine, fix.penetration));
 	if (fix.self) put("self", selfClear(out, engine));
+	if (fix.person) put("person", personOut(out, engine));
 	if (fix.reach) put("reachArms", armReach(out));
 	return fixed;
 }