cozyclay 2.1.0 → 3.0.0

package/src/scene-light-place.js

@@ -0,0 +1,72 @@
+/**
+ * The per-frame half of practical lights and glow, kept free of React so the
+ * place pass can be exercised in Node: SceneObject calls `placeObjectLook`
+ * from its imperative place pass (and the recorder through it, for every
+ * frame it renders), and it writes the light's numbers and the glow for that
+ * frame only.
+ */
+
+import * as THREE from "three";
+import { LIGHT_INTENSITY_SCALE, flickerAt } from "./object-look.js";
+import { trackLevel } from "./object-travel.js";
+import { hasGlow, placeObjectGlow } from "./object-glow.js";
+
+const DEG = Math.PI / 180;
+/** A shadow camera's far plane when the light has no range of its own. */
+export const SHADOW_FAR = 40;
+
+const DOWN = new THREE.Vector3(0, -1, 0);
+const scratchDir = new THREE.Vector3();
+const scratchPos = new THREE.Vector3();
+const scratchQuat = new THREE.Quaternion();
+const scratchScale = new THREE.Vector3();
+
+function childWith(group, key) {
+	for (const child of group.children) if (child.userData?.[key]) return child;
+	return null;
+}
+
+/** Write the light's numbers for this frame. `gain` is level × flicker. */
+function placeSceneLight(group, object, gain) {
+	const light = childWith(group, "sceneLight");
+	if (!light) return;
+	const { color, intensity, range, angle, softness, aim } = object.light;
+	light.color.set(color);
+	light.intensity = intensity * LIGHT_INTENSITY_SCALE * gain;
+	light.distance = range;
+	if (light.castShadow && light.isPointLight) {
+		const far = range > 0 ? range : SHADOW_FAR;
+		if (light.shadow.camera.far !== far) {
+			light.shadow.camera.far = far;
+			light.shadow.camera.updateProjectionMatrix();
+		}
+	}
+	if (!light.isSpotLight) return;
+	light.angle = angle * DEG;
+	light.penumbra = softness;
+	// The target is kept outside the scene graph, in world space: an aim point
+	// is a place in the set, and the record's own -Y is where it hangs pointing.
+	group.updateWorldMatrix(true, false);
+	group.matrixWorld.decompose(scratchPos, scratchQuat, scratchScale);
+	if (aim) scratchDir.set(aim.x - scratchPos.x, aim.y - scratchPos.y, aim.z - scratchPos.z);
+	else scratchDir.copy(DOWN).applyQuaternion(scratchQuat);
+	if (scratchDir.lengthSq() < 1e-10) scratchDir.copy(DOWN).applyQuaternion(scratchQuat);
+	scratchDir.normalize();
+	light.target.position.copy(scratchPos).add(scratchDir);
+	light.target.updateMatrixWorld();
+	const cone = childWith(group, "lightMarker")?.children.find((child) => child.userData?.lightCone);
+	if (cone) cone.quaternion.setFromUnitVectors(DOWN, scratchDir.applyQuaternion(scratchQuat.invert()));
+}
+
+/**
+ * The per-frame look of one record: its light (if it is one) and its glow (if
+ * it has one), from the take's level at `frame` and the light's flicker. Pure
+ * in the frame number, so any frame can be drawn in any order.
+ */
+export function placeObjectLook(group, object, frame, take) {
+	if (!object.light && !object.glow && !hasGlow(group)) return;
+	const level = trackLevel(object.id, frame, take);
+	const gain = level * (object.light ? flickerAt(object.id, frame, object.light.flicker, take?.fps) : 1);
+	if (object.light) placeSceneLight(group, object, gain);
+	placeObjectGlow(group, object, gain);
+}

package/src/scene-lights.jsx

@@ -0,0 +1,148 @@
+/**
+ * Practical lights in the set: a point or spot light a record carries, and its
+ * editor-only marker.
+ *
+ * The light itself lives on the default layer, so the viewport, the shot
+ * preview, capture_frame, contact sheets and the video export all light the
+ * set with it. The marker (a bulb, plus the cone for a spot) is editor
+ * furniture on GIZMO_LAYER, exactly like an Empty's axes: drawn in the working
+ * views, dropped by every recorded camera, and picked through the same
+ * `emptyPick` volume so the user can select and move the light.
+ *
+ * Everything that changes with time (take level, flicker, a spot's aim while
+ * the record travels) is written by `placeObjectLook` (scene-light-place.js),
+ * which SceneObject calls from its imperative place pass. The recorder runs
+ * that pass for every frame it renders, so a scrub or an export never sees a
+ * stale light.
+ */
+
+import { useEffect, useMemo } from "react";
+import { useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { GIZMO_LAYER } from "./dualview.jsx";
+import { EMPTY_MARKER_SIZE } from "./scene-objects.js";
+import { SHADOW_FAR } from "./scene-light-place.js";
+
+const DEG = Math.PI / 180;
+const BULB_RADIUS = 0.07;
+/** Drawn length of a spot's cone outline, metres (the light reaches further). */
+const CONE_LENGTH = 0.7;
+
+function makeLight(type, shadow) {
+	const light = type === "spot" ? new THREE.SpotLight() : new THREE.PointLight();
+	// three.js hangs a spot 1 m up (DEFAULT_UP) by default; a practical sits on its record's pivot.
+	light.position.set(0, 0, 0);
+	light.decay = 2;
+	light.castShadow = shadow;
+	light.userData.sceneLight = true;
+	if (shadow) {
+		const size = type === "spot" ? 1024 : 512;
+		light.shadow.mapSize.set(size, size);
+		light.shadow.bias = -0.0004;
+		light.shadow.normalBias = 0.02;
+		// A lighter a hand-width from a face must still shadow the hand.
+		light.shadow.camera.near = 0.03;
+		light.shadow.camera.far = SHADOW_FAR;
+		light.shadow.camera.updateProjectionMatrix();
+	}
+	return light;
+}
+
+/** Line pairs of a circle of `radius` in the plane spanned by axes a and b. */
+function circle(out, radius, a, b, y = 0, segments = 24) {
+	for (let i = 0; i < segments; i += 1) {
+		for (const k of [i, i + 1]) {
+			const t = (k / segments) * Math.PI * 2;
+			const p = [0, y, 0];
+			p[a] += Math.cos(t) * radius;
+			p[b] += Math.sin(t) * radius;
+			out.push(...p);
+		}
+	}
+	return out;
+}
+
+function lineGeometry(positions) {
+	const geometry = new THREE.BufferGeometry();
+	geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+	return geometry;
+}
+
+/** The bulb: three rings and a few short rays, so it reads as a light, not a ball. */
+function bulbGeometry() {
+	const out = [];
+	circle(out, BULB_RADIUS, 0, 2);
+	circle(out, BULB_RADIUS, 0, 1);
+	circle(out, BULB_RADIUS, 1, 2);
+	for (let i = 0; i < 8; i += 1) {
+		const t = (i / 8) * Math.PI * 2;
+		out.push(Math.cos(t) * BULB_RADIUS * 1.3, 0, Math.sin(t) * BULB_RADIUS * 1.3, Math.cos(t) * BULB_RADIUS * 2, 0, Math.sin(t) * BULB_RADIUS * 2);
+	}
+	return lineGeometry(out);
+}
+
+/** A spot's cone along local -Y: four edges and the rim at CONE_LENGTH. */
+function coneGeometry(angleDeg) {
+	const radius = CONE_LENGTH * Math.tan(angleDeg * DEG);
+	const out = circle([], radius, 0, 2, -CONE_LENGTH, 32);
+	for (let i = 0; i < 4; i += 1) {
+		const t = (i / 4) * Math.PI * 2;
+		out.push(0, 0, 0, Math.cos(t) * radius, -CONE_LENGTH, Math.sin(t) * radius);
+	}
+	return lineGeometry(out);
+}
+
+const onGizmoLayer = (node) => {
+	if (node) node.layers.set(GIZMO_LAYER);
+};
+
+function LightMarker({ type, angle, color }) {
+	const bulb = useMemo(() => bulbGeometry(), []);
+	const cone = useMemo(() => (type === "spot" ? coneGeometry(angle) : null), [type, angle]);
+	useEffect(() => () => bulb.dispose(), [bulb]);
+	useEffect(() => () => cone?.dispose(), [cone]);
+	return (
+		<group userData={{ lightMarker: true }}>
+			<lineSegments ref={onGizmoLayer} geometry={bulb} renderOrder={997} frustumCulled={false}>
+				<lineBasicMaterial color={color} depthTest={false} depthWrite={false} transparent opacity={0.95} />
+			</lineSegments>
+			{cone && (
+				<group userData={{ lightCone: true }}>
+					<lineSegments ref={onGizmoLayer} geometry={cone} renderOrder={997} frustumCulled={false}>
+						<lineBasicMaterial color={color} depthTest={false} depthWrite={false} transparent opacity={0.55} />
+					</lineSegments>
+				</group>
+			)}
+			{/* Never drawn, still raycast: the object picker's gizmo-layer pass
+			    finds it by `emptyPick` and selects the light's record. */}
+			<mesh ref={onGizmoLayer} visible={false} userData={{ emptyPick: true }}>
+				<sphereGeometry args={[EMPTY_MARKER_SIZE * 0.45, 12, 8]} />
+				<meshBasicMaterial />
+			</mesh>
+		</group>
+	);
+}
+
+/** A light record's content: the three.js light and its marker. Rebuilt only
+ * when the type or the shadow switch changes (both change the shader). */
+export function SceneLight({ object }) {
+	const { type, shadow, angle, color } = object.light;
+	const light = useMemo(() => makeLight(type, shadow), [type, shadow]);
+	useEffect(() => () => light.dispose(), [light]);
+	return (
+		<>
+			<primitive object={light} />
+			<LightMarker type={type} angle={angle} color={color} />
+		</>
+	);
+}
+
+/** Ask for a frame when the record's light or glow changes. Both are written by
+ * the place pass, which a demand frame loop runs only when something asks: an
+ * edit that changes no three.js prop would otherwise wait for the next orbit. */
+export function useLookRefresh(object) {
+	const invalidate = useThree((state) => state.invalidate);
+	useEffect(() => {
+		invalidate();
+	}, [invalidate, object.light, object.glow]);
+}

package/src/scene-objects.js

@@ -22,6 +22,13 @@ import { createObjectPath, translateObjectPath } from "./object-path.js";
 import { elementByPath } from "./studio-elements.js";
 import { MESH_DEFAULT_HEIGHT, MESH_HEIGHT_MIN } from "./scene-mesh.js";
 import { normalizeSculptRecipe, sculptStandingBox } from "./sculpt-recipe.js";
+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";
+export { OBJECT_COLORS, normalizeObjectColor, rememberObjectColor, readStoredObjectColors, writeStoredObjectColors } from "./object-colors.js";
+export { isEffectivelyHidden };
 
 export const DEFAULT_SCENE_OBJECTS = [];
 /** The persistence contract (plan §8.1): the version lives in the key AND in
@@ -60,7 +67,6 @@ const snapTo = (value, step) => Number((step > 0 ? Math.round(value / step) * st
  * else, and a tinted maquette reads as a finished prop. The hand-built set
  * pieces keep their clay colours because they ARE the thing they depict.
  */
-const GREY_BOX = "#c2c6c8";
 export const OBJECT_LIBRARY = [
 	{ kind: "cube", label: "Cube", group: "Primitives", footprint: { width: 1, depth: 1 }, height: 1, color: GREY_BOX },
 	{ kind: "sphere", label: "Sphere", group: "Primitives", footprint: { width: 1, depth: 1 }, height: 1, color: GREY_BOX },
@@ -75,96 +81,6 @@ export const OBJECT_LIBRARY = [
 	{ kind: "small-plane", label: "Plane (aircraft)", group: "Set pieces", footprint: { width: 3.4, depth: 3.6 }, height: 1.4, color: "#7896a4" },
 ];
 
-/** 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.
-	}
-}
-
 /**
  * A cutout is a standee: an imported image standing on a card. Its size is NOT
  * library data — the height is measured by the user and the width follows the
@@ -253,14 +169,16 @@ const EMPTY_ENTRY = {
 	color: "#ffffff",
 };
 
-/** True for a record that is only a node: no mesh, no collision, no surface. */
+/** True for a record that is only a node: no mesh, no collision, no surface.
+ * A practical light (object-look.js) is one too: it lights, it does not stand. */
 export function isEmptyObject(object) {
-	return object?.renderer === EMPTY_KIND;
+	return object?.renderer === EMPTY_KIND || object?.renderer === LIGHT_KIND;
 }
 
-/** The catalogue grouped for the create menu: the library plus the empty,
- * which is creatable but has no footprint to satisfy the library's contract. */
-export const OBJECT_MENU_ENTRIES = Object.freeze([EMPTY_ENTRY, ...OBJECT_LIBRARY]);
+/** 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]);
 
 /** 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
@@ -271,7 +189,8 @@ function objectLibraryEntry(kind) {
 	if (kind === MESH_KIND) return MESH_ENTRY;
 	if (kind === SCULPT_KIND) return SCULPT_ENTRY;
 	if (kind === EMPTY_KIND) return EMPTY_ENTRY;
-	return OBJECT_LIBRARY.find((entry) => entry.kind === kind) ?? null;
+	if (kind === EFFECT_ENTRY.kind) return EFFECT_ENTRY;
+	return OBJECT_LIBRARY.find((entry) => entry.kind === kind) ?? lightLibraryEntry(kind);
 }
 
 /** Return the authored walkable surface for mocap contact staging. */
@@ -397,9 +316,10 @@ export function createSceneObject(kind, existing = [], placement = {}) {
 	return {
 		id,
 		name,
-		renderer: kind,
+		// A light kind (point-light, spot-light) is a preset of the one light renderer.
+		renderer: entry.renderer ?? kind,
 		x: TRANSFORM_LIMITS.x(Number(placement.x) || 0),
-		y: 0,
+		y: entry.placeY ?? 0,
 		z: TRANSFORM_LIMITS.z(Number(placement.z) || 0),
 		rot: TRANSFORM_LIMITS.rot(Number(placement.rot) || 0),
 		rotX: 0,
@@ -420,6 +340,8 @@ export function createSceneObject(kind, existing = [], placement = {}) {
 		footprint: { ...entry.footprint },
 		height: entry.height,
 		supportY: Number.isFinite(entry.supportY) ? entry.supportY : entry.height,
+		...objectLookFields({}, entry),
+		...effectFields({ renderer: kind }),
 	};
 }
 
@@ -625,7 +547,8 @@ 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"];
+	const fields = [...Object.keys(TRANSFORM_LIMITS), "name", "color", "hidden", "opacity", "path", "glow"];
+	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");
@@ -653,36 +576,6 @@ export function descendantsOf(objects, id) {
 	return out;
 }
 
-/** True when this record, a parent above it, or a character carrying any of
- *  those records is hidden. A cycle in parent links ends the walk. When the
- *  id is in `objects`, that stored record is what the walk reads, so a display
- *  copy cannot disagree with the authored flag. Nothing in the lists is changed. */
-export function isEffectivelyHidden(entity, objects = [], characters = []) {
-	if (!entity || typeof entity !== "object") return false;
-	const byId = new Map();
-	for (const object of objects) {
-		if (object && typeof object.id === "string") byId.set(object.id, object);
-	}
-	const characterHidden = (id) => characters.some((item) => item && typeof item === "object" && item.id === id && item.hidden === true);
-	const seen = new Set();
-	let current = entity;
-	while (current && typeof current === "object") {
-		const id = typeof current.id === "string" ? current.id : null;
-		if (id) {
-			if (seen.has(id)) break;
-			seen.add(id);
-			if (byId.has(id)) current = byId.get(id);
-		}
-		if (current.hidden === true) return true;
-		const characterId = current.attach && typeof current.attach.characterId === "string" ? current.attach.characterId : null;
-		if (characterId && characterHidden(characterId)) return true;
-		const parentId = typeof current.parent === "string" ? current.parent : null;
-		if (!parentId) break;
-		current = byId.get(parentId) ?? null;
-	}
-	return false;
-}
-
 /** Float dust (6e-17 where 0 belongs) is snapped away, and everything else is
  * kept to 1e-9: fine enough that hundreds of small gizmo steps cannot drift a
  * carried child visibly, coarse enough that stored values stay readable. */
@@ -963,6 +856,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));
 		if (!Object.keys(update).length) return object;
 		changed = true;
 		return { ...object, ...update };
@@ -1126,7 +1021,7 @@ export function normalizeSceneObject(record) {
 	return {
 		id: record.id,
 		name: typeof record.name === "string" && record.name ? record.name : entry.label,
-		renderer: entry.kind,
+		renderer: entry.renderer ?? entry.kind,
 		x: TRANSFORM_LIMITS.x(pick(record.x, 0)),
 		y: TRANSFORM_LIMITS.y(pick(record.y, 0)),
 		z: TRANSFORM_LIMITS.z(pick(record.z, 0)),
@@ -1191,6 +1086,10 @@ 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),
+		// An effect record's emitter (src/effects/effect-record.js).
+		...effectFields(record),
 	};
 }
 
@@ -1315,14 +1214,7 @@ export function screenRotatePatch(start, viewAxis, deltaDeg, snap = ROTATE_SNAP)
 	};
 }
 
-/** The object's world size along each axis, for the gizmo and the plan board. */
-export function objectSize(object) {
-	return {
-		width: (object.footprint?.width ?? 1) * (object.scaleX ?? 1),
-		height: (object.height ?? 1) * (object.scaleY ?? 1),
-		depth: (object.footprint?.depth ?? 1) * (object.scaleZ ?? 1),
-	};
-}
+export { objectSize };
 /** The tolerance that keeps an edge-abutting footprint from counting as
  * overlap: a strict `<` against `max - EPS` makes a 0.5 - 0.5 touch false. */
 const OVERLAP_EPS = 1e-4;