incanto 0.50.0 → 0.52.0

package/dist/{replay-j-m6lJ4W.js → replay-BicPOMX0.js}

@@ -1,4 +1,196 @@
-import { M as translationKey } from "./register-uvaZj1KX.js";
+import { E as behaviorSchema, w as parseNodePath } from "./loader-B-Gft32x.js";
+import { D as translationKey } from "./register-DVwlnZAZ.js";
+import { i as getNodeSchema } from "./registry-C7u42TID.js";
+//#region src/core/node-refs.ts
+/**
+* Node-path PROPS, resolved against scene JSON.
+*
+* `Chase.target`, `Camera2D.follow`, `Spawner.prefab`, `Joint3D.target`,
+* `CharacterController3D.skinPath`, `Foliage3D.terrain` … each holds a path to
+* another node, and nothing checked any of them. A connection whose end does not
+* resolve is a hard `DANGLING_CONNECTION` at load; a PROP that does not resolve
+* is nothing at all — `getNodeOrNull` returns null, the scene loads, the enemy
+* never chases, and no error is ever printed.
+*
+* That makes it exactly the class `auditScene` exists for: loads fine, plays
+* wrong. The editor uses the same resolver so the two cannot drift.
+*
+* The grammar comes from `parseNodePath` — the loader's own parser — so a path
+* this module accepts is one the engine accepts.
+*/
+function nodeAt(root, path) {
+	let node = root;
+	for (const index of path) {
+		node = node?.children?.[index];
+		if (!node) return null;
+	}
+	return node ?? null;
+}
+function byName(root, name) {
+	const found = [];
+	const walk = (node, at) => {
+		if (node.name === name) found.push(at);
+		(node.children ?? []).forEach((child, i) => {
+			walk(child, [...at, i]);
+		});
+	};
+	walk(root, []);
+	return found;
+}
+/**
+* Resolve `value` from the node at `owner`, the way the engine would.
+*
+* Note the asymmetry with connections, whose paths resolve from the SCENE ROOT:
+* a prop's path resolves from the node holding it, which is why `'../Skin'` is
+* the documented default of `CharacterController3D.skinPath` and would mean
+* nothing in a connection.
+*/
+function resolveRefInJson(root, owner, value) {
+	if (!root) return {
+		ok: false,
+		problem: {
+			kind: "noMatch",
+			name: value
+		}
+	};
+	let parsed;
+	try {
+		parsed = parseNodePath(value);
+	} catch (error) {
+		return {
+			ok: false,
+			problem: {
+				kind: "grammar",
+				message: error instanceof Error ? error.message : String(error)
+			}
+		};
+	}
+	if (parsed.kind === "unique") {
+		const found = byName(root, parsed.name);
+		if (found.length === 1) return {
+			ok: true,
+			path: found[0]
+		};
+		if (found.length === 0) return {
+			ok: false,
+			problem: {
+				kind: "noMatch",
+				name: parsed.name
+			}
+		};
+		return {
+			ok: false,
+			problem: {
+				kind: "ambiguous",
+				name: parsed.name,
+				count: found.length
+			}
+		};
+	}
+	let at;
+	let segments = parsed.segments;
+	if (parsed.kind === "absolute") {
+		const first = segments[0] ?? "";
+		if (first !== root.name && first !== "root") return {
+			ok: false,
+			problem: {
+				kind: "wrongRoot",
+				first,
+				root: String(root.name ?? "")
+			}
+		};
+		at = [];
+		segments = segments.slice(1);
+	} else at = [...owner];
+	for (const segment of segments) {
+		if (segment === "..") {
+			if (at.length === 0) return {
+				ok: false,
+				problem: { kind: "aboveRoot" }
+			};
+			at.pop();
+			continue;
+		}
+		const here = nodeAt(root, at);
+		const index = (here?.children ?? []).findIndex((child) => child.name === segment);
+		if (index < 0) return {
+			ok: false,
+			problem: {
+				kind: "noChild",
+				parent: String(here?.name ?? "?"),
+				segment
+			}
+		};
+		at.push(index);
+	}
+	return {
+		ok: true,
+		path: at
+	};
+}
+/** The problem in English, for `incanto-check` and as the editor's base text. */
+function describeRefProblem(problem, value) {
+	switch (problem.kind) {
+		case "grammar": return problem.message;
+		case "noMatch": return `'%${problem.name}' matches no node in this scene.`;
+		case "ambiguous": return `'%${problem.name}' matches ${problem.count} nodes — a %name must be unique.`;
+		case "wrongRoot": return `'${value}' starts at '${problem.first}', but the scene root is '${problem.root}' (or write '/root/…').`;
+		case "noChild": return `'${value}' leads nowhere — '${problem.parent}' has no child named '${problem.segment}'.`;
+		case "aboveRoot": return `'${value}' walks above the scene root.`;
+	}
+}
+/** Every prop on this node declared `nodePath: true`, per bag. */
+function refProps(node) {
+	const collect = (schema) => Object.entries(schema).filter(([, def]) => def?.nodePath).map(([key]) => key);
+	let props = [];
+	if (node.type) try {
+		props = collect(getNodeSchema(node.type));
+	} catch {}
+	const name = node.script?.name;
+	return {
+		props,
+		script: name ? collect(behaviorSchema(name)) : []
+	};
+}
+/**
+* Scene lints for node-path props that point at nothing.
+*
+* An EMPTY value is not reported: `''` is the default of most of these props and
+* means "not set", which is a choice rather than a typo.
+*/
+function nodeRefWarnings(scene) {
+	const root = scene.root;
+	if (!root) return [];
+	const warnings = [];
+	const walk = (node, at, path) => {
+		const keys = refProps(node);
+		const bags = [[
+			node.props,
+			keys.props,
+			""
+		], [
+			node.script?.props,
+			keys.script,
+			`${node.script?.name ?? "script"}.`
+		]];
+		for (const [bag, propKeys, prefix] of bags) {
+			if (!bag) continue;
+			for (const key of propKeys) {
+				const value = bag[key];
+				if (typeof value !== "string" || value === "") continue;
+				const result = resolveRefInJson(root, at, value);
+				if (result.ok) continue;
+				warnings.push(`${path}: ${prefix}${key} — ${describeRefProblem(result.problem, value)} The scene loads and the prop does nothing.`);
+			}
+		}
+		(node.children ?? []).forEach((child, i) => {
+			walk(child, [...at, i], `${path}/${child.name ?? "?"}`);
+		});
+	};
+	walk(root, [], String(root.name ?? "root"));
+	return warnings;
+}
+//#endregion
 //#region src/core/audit.ts
 const ANIMATED_TYPES = new Set([
 	"Particles2D",
@@ -31,6 +223,21 @@ const LIGHT_TYPES = new Set([
 	"OmniLight3D",
 	"SpotLight3D"
 ]);
+/**
+* Built-ins that put something in a save. A save is keyed by node uid, so one
+* of these on a node without one is state that silently goes nowhere: the save
+* comes back `{}` and the load reports a clean bill, because "nothing was
+* missing" is true of an empty save.
+*
+* A JSON walk cannot ask a behavior whether it serializes, so this is the list
+* of the ones that do. Your own behavior with a `serialize()` is caught at
+* runtime instead, by `captureState`.
+*/
+const SAVEABLE_SCRIPTS = new Set([
+	"Health",
+	"ScoreKeeper",
+	"Collector"
+]);
 /** Does the scene header light anything by itself (sky, hdri, ambient, preset)? */
 function isLit(environment) {
 	if (!environment) return false;
@@ -47,9 +254,12 @@ function auditScene(scene) {
 	let currentCameras = 0;
 	let cameras = 0;
 	let lights = 0;
+	const needUid = [];
 	const walk = (node, path, insideHud, staticRoot) => {
 		const type = node.type ?? "";
 		const props = node.props ?? {};
+		const script = node.script?.name;
+		if (script && SAVEABLE_SCRIPTS.has(script) && !node.uid) needUid.push(`${path} (${script})`);
 		if (type === "Camera2D" || type === "Camera3D") {
 			cameras += 1;
 			if (props.current === true) currentCameras += 1;
@@ -66,9 +276,11 @@ function auditScene(scene) {
 		for (const child of node.children ?? []) walk(child, `${path}/${child.name ?? "?"}`, nextHud, nextStatic);
 	};
 	walk(root, root.name ?? "root", false, root.props?.static === true ? root.name ?? "root" : null);
+	if (needUid.length > 0) warnings.push(`these carry state a save keeps and have no uid to key it under, so the save comes back EMPTY and the load reports no problem: ${needUid.join(", ")}. Give each one a "uid" from newUid().`);
 	if (cameras > 0 && currentCameras === 0) warnings.push("no camera has \"current\": true — the screen renders from a default view, probably not what you framed.");
 	if (currentCameras > 1) warnings.push(`${currentCameras} cameras claim "current": true — only the first found wins.`);
 	if (scene.dimension === "3d" && lights === 0 && !isLit(scene.environment)) warnings.push("nothing lights this 3D scene — no light node, no environment sky/hdri, and no ambient intensity. It will render black. Add a DirectionalLight3D, or an \"environment\": { \"sky\": { \"type\": \"atmosphere\" } } / { \"preset\": \"...\" }.");
+	for (const warning of nodeRefWarnings(scene)) warnings.push(warning);
 	for (const warning of auditStrings(scene)) warnings.push(warning);
 	return warnings;
 }
@@ -198,4 +410,4 @@ function replay(engine, recording, opts) {
 	}
 }
 //#endregion
-export { startRecording as n, auditScene as r, replay as t };
+export { nodeRefWarnings as a, describeRefProblem as i, startRecording as n, resolveRefInJson as o, auditScene as r, replay as t };