cozyclay 2.0.0 → 2.1.0

package/src/shot-authoring.js

@@ -9,26 +9,62 @@ import { createShot } from "./cuts.js";
 import { normalizeStableItems } from "./stable-items.js";
 import { VIDEO_MODEL_PRESETS } from "./model-presets.js";
 import { elementByPath } from "./studio-elements.js";
+import { isImageAssetId } from "./scene-assets.js";
+import { createCharacterEntry } from "./scenes.js";
 
 const VIDEO_MODEL_IDS = new Set(VIDEO_MODEL_PRESETS.map((preset) => preset.id));
 const CAMERA_KEY_LIMITS = elementByPath("shot.cameraKeys");
 
-export const SHOT_AUTHORING_VERSION = 4;
-export const SHOT_AUTHORING_KEY = "cozyclay.shot-authoring.v4";
+export const SHOT_AUTHORING_VERSION = 5;
+export const SHOT_AUTHORING_KEY = "cozyclay.shot-authoring.v5";
 // The single-key alias points at the newest legacy body for older callers.
 // New readers should walk the list so a user can still arrive directly from v1.
-export const SHOT_AUTHORING_LEGACY_KEY = "cozyclay.shot-authoring.v3";
+export const SHOT_AUTHORING_LEGACY_KEY = "cozyclay.shot-authoring.v4";
 export const SHOT_AUTHORING_LEGACY_KEYS = Object.freeze([
 	SHOT_AUTHORING_LEGACY_KEY,
+	"cozyclay.shot-authoring.v3",
 	"cozyclay.shot-authoring.v2",
 	"cozyclay.shot-authoring.v1",
 ]);
-export const SHOT_AUTHORING_QUARANTINE_KEY = "cozyclay.shot-authoring.v4.quarantine";
+export const SHOT_AUTHORING_QUARANTINE_KEY = "cozyclay.shot-authoring.v5.quarantine";
+
+/** A still holds one picture for `endFrame - startFrame + 1` frames (24 fps). */
+export const STILL_HOLD_DEFAULT = 48;
+export const STILL_HOLD_MAX = 240;
+export const shotHold = (shot) => shot.endFrame - shot.startFrame + 1;
+
+/** Lay the stills end to end from frame 0 in their array order, each keeping
+ * its hold; camera keys travel with their still. Clip shots are untouched.
+ * The result is sorted by startFrame, the order the document stores. */
+export function reflowStillShots(shots) {
+	let cursor = 0;
+	return shots.map((shot) => {
+		if (shot.kind !== "still") return shot;
+		const hold = shotHold(shot), delta = cursor - shot.startFrame;
+		cursor += hold;
+		if (!delta) return shot;
+		return { ...shot, startFrame: shot.startFrame + delta, endFrame: shot.endFrame + delta,
+			cameraKeys: shot.cameraKeys.map((key) => ({ ...key, frame: key.frame + delta })) };
+	}).sort((a, b) => a.startFrame - b.startFrame);
+}
+
+/** The timeline length a reflowed document needs, unclamped so a caller can
+ * refuse a storyboard past STILL_FRAME_COUNT_MAX instead of truncating it. */
+export function stillFrameCount(shots) {
+	return Math.max(DEFAULT_FRAME_COUNT, ...shots.map((shot) => shot.endFrame + 1));
+}
+
+const SHOT_KINDS = new Set(["clip", "still"]);
+const CAPTION_MAX = 500;
+// Mirrors the cast posture vocabulary (POSTURES in src/scenes.js once the
+// proxy-figure work lands); kept local so this module does not wait on it.
+const POSTURES = new Set(["stand", "sit", "lie"]);
 
 /** clip length sanity bounds, frames @ 24 fps: 1 s .. 20 min */
 const FRAME_COUNT_MIN = 24;
 const FRAME_COUNT_MAX = 28800;
 const DEFAULT_FRAME_COUNT = 144;
+export const STILL_FRAME_COUNT_MAX = FRAME_COUNT_MAX;
 const RAIL_MAX_POINTS = 512;
 const finite = Number.isFinite;
 
@@ -159,10 +195,36 @@ function repairShots(entries, frameCount, inheritedCamera = null, ids = new Set(
 			cameraKeys: repairKeys(entry.cameraKeys, startFrame, endFrame, ids),
 			camera: repairCamera(inheritedCamera ?? entry.camera),
 			...targetModel,
+			kind: SHOT_KINDS.has(entry.kind) ? entry.kind : "clip",
+			caption: repairCaption(entry.caption),
+			cast: repairCast(entry.cast),
+			stylizedAssetId: isImageAssetId(entry.stylizedAssetId) ? entry.stylizedAssetId : null,
 		};
 	});
 }
 
+function repairCaption(value) {
+	return typeof value === "string" ? Array.from(value.trim()).slice(0, CAPTION_MAX).join("") : "";
+}
+
+/** Per-shot placement overrides keyed by character id. An entry without a
+ * usable id or a finite x/z/rot is dropped; its valid siblings survive. */
+function repairCast(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+	const rows = [];
+	for (const [characterId, entry] of Object.entries(value)) {
+		if (!characterId.trim() || !entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+		if (!finite(entry.x) || !finite(entry.z) || !finite(entry.rot)) continue;
+		const row = { x: entry.x, z: entry.z, rot: entry.rot };
+		if (POSTURES.has(entry.posture)) row.posture = entry.posture;
+		const pose = createCharacterEntry({ pose: entry.pose }).pose;
+		if (pose) row.pose = pose;
+		rows.push([characterId, row]);
+	}
+	// fromEntries defines own properties, so a "__proto__" id stays data.
+	return Object.fromEntries(rows);
+}
+
 function repairWaypoints(entries, ids = new Set()) {
 	const byFrame = new Map();
 	for (const waypoint of normalizeStableItems(entries, "waypoint", ids)) {
@@ -313,8 +375,9 @@ export function readShotAuthoringDocument(raw) {
 	}
 	const ids = new Set();
 	return {
-		// A v3 body is structurally current but was authored on the old clock;
-		// it is rewritten, so it reports as migrated, not valid.
+		// A v3 body was authored on the old clock and a v4 body lacks the v5
+		// kind/caption/cast/stylizedAssetId defaults; both are rewritten, so they
+		// report as migrated, not valid.
 		status: version < SHOT_AUTHORING_VERSION ? "migrated" : "valid",
 		state: { ...repairShared(parsed, frameCount, ids), shots: repairShots(parsed.shots, effectiveFrameCount, null, ids) },
 	};

package/src/stable-items.js

@@ -18,7 +18,7 @@ function hash(value) {
 	return (result >>> 0).toString(36);
 }
 
-export class UnknownStableItemIdError extends Error {
+class UnknownStableItemIdError extends Error {
 	constructor(collection, id) {
 		super(`Unknown ${collection} ID: ${id}`);
 		this.name = "UnknownStableItemIdError";

package/src/stage-attach-frames.js

@@ -0,0 +1,169 @@
+import * as THREE from "three";
+import { SCENE_ATTACH_BONES } from "./scene-objects.js";
+import { TRAIL_EFFECTOR_JOINTS } from "./motion-trail.js";
+import { normalizeBoneName } from "./poses.js";
+
+/** The rig rows that ARE an attach frame: `rig.<track id>`, the same camel
+ * spellings SCENE_ATTACH_BONES uses. The group rows above them (rig.torso,
+ * rig.leftArm …) name a limb, not a frame, so they are deliberately absent. */
+export const ATTACH_BONE_ROWS = new Map(SCENE_ATTACH_BONES.map((bone) => [`rig.${bone}`, bone]));
+
+/** Attach track id -> the Mixamo bone carrying that frame on the shipped rigs.
+ * TRAIL_EFFECTOR_JOINTS names the cskel27 joint, and cskel27 and Mixamo agree
+ * everywhere except the spine, which sits one bone up the Mixamo chain (the
+ * same shift ardy/playback.js SKINNING_MAP makes). */
+export const ATTACH_BONE_NAMES = Object.fromEntries(SCENE_ATTACH_BONES.map((bone) => {
+	const joint = TRAIL_EFFECTOR_JOINTS[bone];
+	return [bone, joint === "Spine1" ? "Spine" : joint === "Spine2" ? "Spine1" : joint];
+}));
+
+// One scratch set for the whole module: resolving a frame runs per attached
+// prop per frame and must never allocate.
+export const attachPos = new THREE.Vector3();
+export const attachQuat = new THREE.Quaternion();
+export const attachScale = new THREE.Vector3();
+export const attachRootPos = new THREE.Vector3();
+export const attachRootQuat = new THREE.Quaternion();
+export const ATTACH_UNIT_SCALE = new THREE.Vector3(1, 1, 1);
+export const attachWorldMatrix = new THREE.Matrix4();
+export const attachLocalMatrix = new THREE.Matrix4();
+export const attachToMatrix = new THREE.Matrix4();
+export const attachInverseMatrix = new THREE.Matrix4();
+export const placePos = new THREE.Vector3();
+export const placeQuat = new THREE.Quaternion();
+export const placeScale = new THREE.Vector3();
+export const placeEuler = new THREE.Euler();
+
+/** The bone a rig offers under `mixamoName`, by the project's matching rule
+ * (normalised names equal, or one a suffix of the other; first depth-first
+ * match wins — poses.js and ardy/playback.js agree). Cached per rig: this is
+ * asked once per attached prop per rendered frame. */
+export const attachBoneCache = new WeakMap();
+export function attachBoneOf(rig, mixamoName) {
+	let byName = attachBoneCache.get(rig);
+	if (!byName) attachBoneCache.set(rig, (byName = new Map()));
+	if (byName.has(mixamoName)) return byName.get(mixamoName);
+	const target = normalizeBoneName(mixamoName);
+	let found = null;
+	rig.traverse((node) => {
+		if (found || !node.isBone) return;
+		const norm = normalizeBoneName(node.name);
+		if (norm === target || norm.endsWith(target)) found = node;
+	});
+	byName.set(mixamoName, found);
+	return found;
+}
+
+/**
+ * The LIVE world frame an attachment rides, or null when the rig (or that bone)
+ * is not there — a dangling attachment then renders where its numbers say,
+ * which is exactly what a detached prop does.
+ *
+ * The frame is deliberately UNSCALED. The shipped rigs are Mixamo centimetres
+ * scaled by 0.01 on the model, so a raw bone matrix would push a hundredfold
+ * into every carried prop's local numbers and leave the Inspector unreadable.
+ * A carried prop takes the bone's place and facing; its size stays its own.
+ *
+ * `bone === null` is the character's animated ROOT: the hips' travel (during
+ * playback the whole root trajectory lives in the bones — see
+ * ardy/playback.js) carried at the character's own yaw, so a prop dropped on
+ * the character walks with the body instead of rolling with the hips.
+ */
+export function attachFrameMatrix(rig, bone, out = new THREE.Matrix4()) {
+	if (!rig) return null;
+	const name = ATTACH_BONE_NAMES[bone ?? "hips"];
+	if (!name) return null;
+	const node = attachBoneOf(rig, name);
+	if (!node) return null;
+	// Ancestors included: the bones are written imperatively by playback and by
+	// the export, either of which can land before the renderer's own pass.
+	node.updateWorldMatrix(true, false);
+	node.matrixWorld.decompose(attachPos, attachQuat, attachScale);
+	if (bone != null) return out.compose(attachPos, attachQuat, ATTACH_UNIT_SCALE);
+	// The Character group carries the scene placement and the clip-to-scene yaw;
+	// the rig model hangs off it, so its parent IS that group.
+	const group = rig.parent ?? rig;
+	group.updateWorldMatrix(true, false);
+	group.matrixWorld.decompose(attachRootPos, attachRootQuat, attachScale);
+	return out.compose(attachPos, attachRootQuat, ATTACH_UNIT_SCALE);
+}
+
+/** A prop's placement as a matrix — the same compose props.jsx renders from
+ * (position, XYZ euler in degrees, per-axis scale). */
+export function sceneObjectMatrix(object, out = new THREE.Matrix4()) {
+	return out.compose(
+		placePos.set(object.x ?? 0, object.y ?? 0, object.z ?? 0),
+		placeQuat.setFromEuler(placeEuler.set(
+			(object.rotX ?? 0) * THREE.MathUtils.DEG2RAD,
+			(object.rot ?? 0) * THREE.MathUtils.DEG2RAD,
+			(object.rotZ ?? 0) * THREE.MathUtils.DEG2RAD,
+		)),
+		placeScale.set(object.scaleX ?? 1, object.scaleY ?? 1, object.scaleZ ?? 1),
+	);
+}
+
+/** …and back out into the nine authored channels, or null if the matrix could
+ * not be read as a placement at all (a singular frame inverts to zeros, and a
+ * zero matrix decomposes to NaN). Rounded, because a matrix round trip
+ * otherwise turns a typed 1.5 into 1.4999999999999998 in the Inspector the
+ * moment a prop is picked up and put down again. */
+export function sceneObjectPlacement(matrix) {
+	matrix.decompose(placePos, placeQuat, placeScale);
+	placeEuler.setFromQuaternion(placeQuat);
+	const round = (value) => Math.round(value * 1e6) / 1e6;
+	const placement = {
+		x: round(placePos.x), y: round(placePos.y), z: round(placePos.z),
+		rotX: round(placeEuler.x * THREE.MathUtils.RAD2DEG),
+		rot: round(placeEuler.y * THREE.MathUtils.RAD2DEG),
+		rotZ: round(placeEuler.z * THREE.MathUtils.RAD2DEG),
+		scaleX: round(placeScale.x), scaleY: round(placeScale.y), scaleZ: round(placeScale.z),
+	};
+	return Object.values(placement).every((value) => Number.isFinite(value)) ? placement : null;
+}
+
+/**
+ * The nine channels rewritten so a prop does not MOVE when it changes frames.
+ *
+ * `world` is where the prop actually IS — read off the live group in the scene
+ * graph, NOT recomputed from its numbers. That distinction is the whole point:
+ * an attach->attach drop would otherwise have to reconstruct the world
+ * transform through the frame the prop is leaving, and any disagreement
+ * between that reconstruction and what the renderer last drew (a rig posed a
+ * beat later than the last drawn frame, a frame that no longer resolves) lands
+ * on screen as a jump. Reading the group makes every drop the same one-frame
+ * conversion the world->attach and attach->world cases already were.
+ *
+ * Returns null when the frame it needs is missing — converting against a rig
+ * that is not on stage would be precisely the jump this exists to prevent —
+ * and the caller then refuses the whole drop rather than re-labelling numbers
+ * it could not convert.
+ */
+export function attachPlacementPatch(world, attach, frameOf) {
+	if (!world) return null;
+	if (!attach) return sceneObjectPlacement(attachLocalMatrix.copy(world));
+	const frame = frameOf(attach.characterId, attach.bone ?? null, attachToMatrix);
+	if (!frame) return null;
+	return sceneObjectPlacement(attachLocalMatrix.copy(world).premultiply(attachInverseMatrix.copy(frame).invert()));
+}
+
+/**
+ * Write a computed placement straight onto the record, around
+ * updateSceneObject. Deliberate, and the only call site allowed to: those
+ * limits are WORLD limits (y floors at the deck, x/z stay inside the room),
+ * and while a prop is attached its numbers are a LOCAL transform in a bone
+ * frame — a hand rides 1.3 m above the deck, so a carried prop's local y is
+ * routinely negative and clamping it to the floor IS the visual jump the
+ * conversion exists to prevent. Every value here comes out of a decomposed
+ * matrix, so the record shape is sound by construction.
+ */
+export function placeSceneObject(objects, id, placement) {
+	if (!placement) return objects;
+	let changed = false;
+	const next = objects.map((object) => {
+		if (object.id !== id) return object;
+		if (Object.entries(placement).every(([key, value]) => object[key] === value)) return object;
+		changed = true;
+		return { ...object, ...placement };
+	});
+	return changed ? next : objects;
+}