incanto 0.68.0 → 0.70.0

package/dist/{gameplay-DM1eu_cV.js → gameplay-BfHkuzVb.js}

@@ -1,8 +1,146 @@
-import { O as Node, P as Behavior, _ as SaveSlots, k as diagnose, n as loadScene, w as effectiveOrder, z as registerBehavior } from "./loader-BC4PNtJX.js";
+import { t as jsonClone } from "./json-CfTjpvW8.js";
+import { K as Node, M as effectiveOrder, Q as Behavior, R as HudLayer, W as requireNumber, it as registerBehavior, n as SaveSlots, p as loadScene, q as diagnose, s as duplicateNode, u as rebuildOptions } from "./save-slots-BXVg148r.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { t as jsonClone } from "./json-CwwhxQgb.js";
-import { t as duplicateNode } from "./duplicate-IWIqk0HJ.js";
+import { t as Rng } from "./rng-CDOMybym.js";
+import { h as didYouMean } from "./touch-BnCyPA0G.js";
 import { Color, CubeCamera, DepthTexture, DoubleSide, Euler, FloatType, Frustum, HalfFloatType, LinearMipmapLinearFilter, MathUtils, Matrix4, Mesh, MeshDepthMaterial, Object3D, PerspectiveCamera, Plane, PlaneGeometry, Quaternion, ShaderMaterial, Sphere, Vector2, Vector3, Vector4, WebGLCubeRenderTarget, WebGLRenderTarget } from "three";
+//#region src/gameplay/spatial.ts
+/** Duck-type test: every spatial node (Node2D/Node3D) exposes `position: number[]`. */
+function hasPosition$1(node) {
+	return Array.isArray(node.position);
+}
+/**
+* Movement behaviors are dimension-agnostic — they read/write `this.node.position`
+* directly. Attaching one to a non-spatial node (no `position` array) would be a
+* silent no-op, so assert it at ready (engine philosophy: hard load-time errors).
+*/
+function requirePosition(behavior) {
+	const node = behavior.node;
+	if (!hasPosition$1(node)) {
+		const behaviorName = behavior.constructor.name;
+		throw new IncantoError("PROP_TYPE_MISMATCH", `${behaviorName} on '${node.getPath()}' needs a spatial node with a numeric 'position' array (a Node2D/Node3D subtype). '${node.name}' has none.`, { path: node.getPath() });
+	}
+	return node;
+}
+/** Euclidean distance between two position arrays (works for 2D and 3D). */
+function distance$1(a, b) {
+	let sum = 0;
+	const n = Math.max(a.length, b.length);
+	for (let i = 0; i < n; i++) {
+		const d = (a[i] ?? 0) - (b[i] ?? 0);
+		sum += d * d;
+	}
+	return Math.sqrt(sum);
+}
+/** Component-wise `a + b` (dimension = max of the two; missing components are 0). */
+function add(a, b) {
+	const n = Math.max(a.length, b.length);
+	const out = new Array(n);
+	for (let i = 0; i < n; i++) out[i] = (a[i] ?? 0) + (b[i] ?? 0);
+	return out;
+}
+/** Vector length. */
+function length(v) {
+	let sum = 0;
+	for (const c of v) sum += c * c;
+	return Math.sqrt(sum);
+}
+/** Unit vector (zero-length stays zero). */
+function normalize(v) {
+	const len = length(v);
+	if (len === 0) return v.map(() => 0);
+	return v.map((c) => c / len);
+}
+/**
+* Step `from` toward `to` by at most `maxStep`. Returns the new position and
+* whether the destination was reached this step (clamped — no overshoot).
+*/
+function moveToward(from, to, maxStep) {
+	const n = Math.max(from.length, to.length);
+	let sum = 0;
+	for (let i = 0; i < n; i++) {
+		const d = (to[i] ?? 0) - (from[i] ?? 0);
+		sum += d * d;
+	}
+	const dist = Math.sqrt(sum);
+	const position = new Array(n);
+	if (dist <= maxStep || dist === 0) {
+		for (let i = 0; i < n; i++) position[i] = to[i] ?? 0;
+		return {
+			position,
+			reached: true
+		};
+	}
+	const f = maxStep / dist;
+	for (let i = 0; i < n; i++) {
+		const c = from[i] ?? 0;
+		position[i] = c + ((to[i] ?? 0) - c) * f;
+	}
+	return {
+		position,
+		reached: false
+	};
+}
+/**
+* Frame-rate-independent lerp factor for an exponential chase. `smoothing` is a
+* 0..1 retention factor: 0 snaps instantly; higher values chase more slowly.
+* (60fps reference, matching Camera2D's `follow`.)
+*/
+function smoothingFactor(smoothing, dt) {
+	const s = Math.min(Math.max(smoothing, 0), .99);
+	return s <= 0 ? 1 : 1 - s ** (dt * 60);
+}
+/**
+* A node's position with every spatial ancestor's added in.
+*
+* The tree composes transforms for DRAWING — three does it for free — and every
+* piece of engine logic that reads `node.position` gets the LOCAL number
+* instead. Physics already knew (`worldPosition2D`/`worldPosition3D` in the
+* adapters); the camera did not, and neither did anything that chases a target.
+*
+* A camera parented to the player is the Godot and Phaser idiom, and the
+* authoring skill explicitly permits it — *"EVERY node type can hold children …
+* any node works as a grouping container"*. Measured on exactly that scene:
+*
+* ```
+* player world position : [1400, 900]
+* renderer view centre  : {"x":0,"y":0}
+* framing               : camera /Level/Player/Cam centred [1400, 900]
+*                         1 in view, 0 outside it
+* ```
+*
+* The renderer drew empty world 1600 px from the player while `framing` — the
+* instrument the skills tell you to trust before handing a game back —
+* certified the player on screen.
+*
+* Arity comes from the node itself: a 2D node has two components, a 3D node
+* three, and an ancestor that is neither contributes nothing.
+*/
+function worldPosition(node) {
+	const own = node.position;
+	if (!Array.isArray(own)) return [];
+	const out = own.slice();
+	for (let at = node.parent; at; at = at.parent) {
+		const p = at.position;
+		if (!Array.isArray(p)) continue;
+		for (let i = 0; i < out.length; i++) out[i] = (out[i] ?? 0) + (p[i] ?? 0);
+	}
+	return out;
+}
+/**
+* Turn a world position into the local one `node.position` has to hold for the
+* node to END UP there — the inverse of `worldPosition` for its parent chain.
+*/
+function localFromWorld(node, world) {
+	const out = world.slice();
+	for (let at = node.parent; at; at = at.parent) {
+		const p = at.position;
+		if (!Array.isArray(p)) continue;
+		for (let i = 0; i < out.length; i++) out[i] = (out[i] ?? 0) - (p[i] ?? 0);
+	}
+	return out;
+}
+//#endregion
 //#region src/3d/frustum.ts
 const scratchFrustum = new Frustum();
 const scratchMatrix = new Matrix4();
@@ -2204,12 +2342,29 @@ function simpleWaveHeight(x, z, time, waveHeight) {
 }
 //#endregion
 //#region src/3d/physics/collider-validate.ts
+/** Every key a 3D collider may carry — see the 2D twin for what this closes. */
+const COLLIDER_KEYS_3D = [
+	"shape",
+	"size",
+	"radius",
+	"height",
+	"offset",
+	"vertices",
+	"indices"
+];
 /**
 * Hard-validate a 3D collider prop at LOAD time (see the 2D twin for rationale).
 * An EMPTY collider is allowed — a body without a collider is work in progress.
 */
 function validateCollider3D(collider, nodeName) {
 	const shape = collider.shape;
+	for (const key of Object.keys(collider)) {
+		if (COLLIDER_KEYS_3D.includes(key)) continue;
+		throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}' has an unknown key "${key}".` + didYouMean(key, COLLIDER_KEYS_3D) + ` A collider is [${COLLIDER_KEYS_3D.join(", ")}] — friction, restitution and mass are props of the BODY, not of its collider.`, {
+			prop: key,
+			validOptions: [...COLLIDER_KEYS_3D]
+		});
+	}
 	if (shape === void 0) return;
 	if (shape === "box") {
 		const size = collider.size;
@@ -2414,6 +2569,22 @@ var Node3D = class Node3D extends Node {
 	*  error rather than a silent per-node decode; overrides that do not need it
 	*  simply keep the one-argument signature. Null in a headless test or a
 	*  detached probe, where the node falls back to loading uncached. */
+	/**
+	* Is there anything left to wait for before this node can be FROZEN?
+	*
+	* The static latch fired unconditionally, while `Renderer3D.render()` calls
+	* `assets.load()` and `syncTree()` in the SAME frame — so a
+	* `ModelInstance3D` frozen by its own or an ancestor group's `static` never
+	* mounted its GLB at all, permanently and silently: the asset loaded fine, so
+	* `assetErrors()` is empty and `stats().errors` is 0, and `framing` reads
+	* props rather than pixels and still calls the node on-screen.
+	*
+	* The 2D adapter already had exactly this gate (`Node2D._staticReady`); this
+	* is its twin. A node with nothing to wait for is ready by definition.
+	*/
+	_staticReady(_assets) {
+		return true;
+	}
 	_syncObject3D(alpha = 1, _assets = null) {
 		const o = this._ensureObject3D();
 		const prev = this._interpPrev;
@@ -2560,7 +2731,7 @@ var Area3D = class extends PhysicsBody3D {
 	*
 	* Empty in a scene with no physics world.
 	*/
-	overlapping(group) {
+	overlapping(group = void 0) {
 		const all = this._physics?.overlapping(this) ?? [];
 		return group === void 0 ? all : all.filter((n) => n.isInGroup(group));
 	}
@@ -2608,6 +2779,17 @@ var RigidBody3D = class extends PhysicsBody3D {
 		0,
 		0
 	];
+	/**
+	* The other name for `linearVelocity` — see `RigidBody2D.velocity`. On a
+	* plain TS class `body.velocity = [...]` succeeds silently and does nothing,
+	* and that is the spelling the physics skill taught.
+	*/
+	get velocity() {
+		return this.linearVelocity;
+	}
+	set velocity(v) {
+		this.linearVelocity = v;
+	}
 	/** @internal set by Physics3D */
 	_physics3d = null;
 	/** World-space impulse (kg·m/s) — the floating-capsule controller's verb. */
@@ -2693,6 +2875,37 @@ var CharacterBody3D = class extends PhysicsBody3D {
 		if (!this._physics) throw new IncantoError("TREE_VIOLATION", this.collider.shape === void 0 ? `CharacterBody3D '${this.name}' has no collider — set a collider prop (physics skips collider-less bodies).` : `CharacterBody3D '${this.name}' has no physics world — await enablePhysics3D(engine) first.`);
 		this._physics.moveAndSlide(this);
 	}
+	/** @internal Set by the physics step from the KCC's resolved collisions. */
+	_onWall = null;
+	/** @internal */
+	_onCeiling = false;
+	/**
+	* Touching a wall.
+	*
+	* `CharacterBody2D` has had this since wall jump and wall slide turned out to
+	* be not merely awkward to write in 2D but IMPOSSIBLE — `isOnFloor()` was the
+	* only surface a character could report, so even a hand-written behavior had
+	* nothing to ask. 3D was left with exactly that problem: a 3D platformer
+	* could not wall-jump, and nothing said why.
+	*/
+	isOnWall() {
+		return this._onWall !== null;
+	}
+	/**
+	* The wall's normal, pointing AWAY from it (toward the character) — the
+	* vector a wall jump pushes along. `null` when not touching one.
+	*
+	* 2D answers this as `wallSide()`, a -1/+1 scalar, because a 2D character
+	* has only two horizontal directions. In three dimensions the honest answer
+	* is the normal itself.
+	*/
+	wallNormal() {
+		return this._onWall === null ? null : [...this._onWall];
+	}
+	/** Head hit something — cut the jump short, the way every platformer does. */
+	isOnCeiling() {
+		return this._onCeiling;
+	}
 	isOnFloor() {
 		return this._grounded;
 	}
@@ -3087,7 +3300,13 @@ var Water3D = class Water3D extends Node3D {
 	static props = {
 		size: { default: [40, 40] },
 		color: { default: "#2a6fbe" },
-		opacity: { default: .8 },
+		opacity: {
+			default: .8,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		renderOrder: { default: 1 },
 		waveHeight: { default: .04 },
 		waveSpeed: { default: 1 },
@@ -3111,11 +3330,20 @@ var Water3D = class Water3D extends Node3D {
 			.3
 		] },
 		sunColor: { default: "#fff5d6" },
-		sunIntensity: { default: 1 },
-		detailStrength: { default: .26 },
+		sunIntensity: {
+			default: 1,
+			range: { min: 0 }
+		},
+		detailStrength: {
+			default: .26,
+			range: { min: 0 }
+		},
 		absorption: { default: .15 },
 		refraction: { default: true },
-		underwater: { default: true },
+		underwater: {
+			default: true,
+			kinds: ["boolean", "object"]
+		},
 		swell: { default: 0 },
 		swellDirectionDeg: { default: 0 },
 		swellWavelength: { default: 30 },
@@ -4321,10 +4549,18 @@ var Buoyancy = class extends Behavior {
 	wet = false;
 	/** Said once: a body that cannot be pushed will never start being able to. */
 	reportedNoImpulse = false;
+	/** Said once: there was no water to float on when this first looked. */
+	reportedNoWater = false;
 	update(dt) {
 		if (dt <= 0) return;
 		const water = this.resolveWater();
-		if (!water) return;
+		if (!water) {
+			if (!this.reportedNoWater) {
+				this.reportedNoWater = true;
+				diagnose(this.node.tree?.engine ?? null, "warn", `[incanto] ${this.node.getPath()}: Buoyancy found no Water3D in the tree, so this body is not floating. It keeps looking, so a water added later is fine — otherwise add one, or name it with "water".`);
+			}
+			return;
+		}
 		const node = this.node;
 		if (!node.applyImpulse) {
 			if (!this.reportedNoImpulse) {
@@ -4333,11 +4569,14 @@ var Buoyancy = class extends Behavior {
 			}
 			return;
 		}
-		const [x, y, z] = [
-			node.position[0] ?? 0,
-			node.position[1] ?? 0,
-			node.position[2] ?? 0
-		];
+		const [x, y, z] = (() => {
+			const w = worldPosition(node);
+			return [
+				w[0] ?? 0,
+				w[1] ?? 0,
+				w[2] ?? 0
+			];
+		})();
 		const half = [(this.size[0] ?? 1) / 2, (this.size[1] ?? 1) / 2];
 		const points = this.samplePoints(x, z, half[0], half[1]);
 		const mass = node.mass ?? 1;
@@ -4480,143 +4719,6 @@ function moveBody(node, to, dt) {
 	body.moveAndSlide();
 }
 //#endregion
-//#region src/gameplay/spatial.ts
-/** Duck-type test: every spatial node (Node2D/Node3D) exposes `position: number[]`. */
-function hasPosition$1(node) {
-	return Array.isArray(node.position);
-}
-/**
-* Movement behaviors are dimension-agnostic — they read/write `this.node.position`
-* directly. Attaching one to a non-spatial node (no `position` array) would be a
-* silent no-op, so assert it at ready (engine philosophy: hard load-time errors).
-*/
-function requirePosition(behavior) {
-	const node = behavior.node;
-	if (!hasPosition$1(node)) {
-		const behaviorName = behavior.constructor.name;
-		throw new IncantoError("PROP_TYPE_MISMATCH", `${behaviorName} on '${node.getPath()}' needs a spatial node with a numeric 'position' array (a Node2D/Node3D subtype). '${node.name}' has none.`, { path: node.getPath() });
-	}
-	return node;
-}
-/** Euclidean distance between two position arrays (works for 2D and 3D). */
-function distance$1(a, b) {
-	let sum = 0;
-	const n = Math.max(a.length, b.length);
-	for (let i = 0; i < n; i++) {
-		const d = (a[i] ?? 0) - (b[i] ?? 0);
-		sum += d * d;
-	}
-	return Math.sqrt(sum);
-}
-/** Component-wise `a + b` (dimension = max of the two; missing components are 0). */
-function add(a, b) {
-	const n = Math.max(a.length, b.length);
-	const out = new Array(n);
-	for (let i = 0; i < n; i++) out[i] = (a[i] ?? 0) + (b[i] ?? 0);
-	return out;
-}
-/** Vector length. */
-function length(v) {
-	let sum = 0;
-	for (const c of v) sum += c * c;
-	return Math.sqrt(sum);
-}
-/** Unit vector (zero-length stays zero). */
-function normalize(v) {
-	const len = length(v);
-	if (len === 0) return v.map(() => 0);
-	return v.map((c) => c / len);
-}
-/**
-* Step `from` toward `to` by at most `maxStep`. Returns the new position and
-* whether the destination was reached this step (clamped — no overshoot).
-*/
-function moveToward(from, to, maxStep) {
-	const n = Math.max(from.length, to.length);
-	let sum = 0;
-	for (let i = 0; i < n; i++) {
-		const d = (to[i] ?? 0) - (from[i] ?? 0);
-		sum += d * d;
-	}
-	const dist = Math.sqrt(sum);
-	const position = new Array(n);
-	if (dist <= maxStep || dist === 0) {
-		for (let i = 0; i < n; i++) position[i] = to[i] ?? 0;
-		return {
-			position,
-			reached: true
-		};
-	}
-	const f = maxStep / dist;
-	for (let i = 0; i < n; i++) {
-		const c = from[i] ?? 0;
-		position[i] = c + ((to[i] ?? 0) - c) * f;
-	}
-	return {
-		position,
-		reached: false
-	};
-}
-/**
-* Frame-rate-independent lerp factor for an exponential chase. `smoothing` is a
-* 0..1 retention factor: 0 snaps instantly; higher values chase more slowly.
-* (60fps reference, matching Camera2D's `follow`.)
-*/
-function smoothingFactor(smoothing, dt) {
-	const s = Math.min(Math.max(smoothing, 0), .99);
-	return s <= 0 ? 1 : 1 - s ** (dt * 60);
-}
-/**
-* A node's position with every spatial ancestor's added in.
-*
-* The tree composes transforms for DRAWING — three does it for free — and every
-* piece of engine logic that reads `node.position` gets the LOCAL number
-* instead. Physics already knew (`worldPosition2D`/`worldPosition3D` in the
-* adapters); the camera did not, and neither did anything that chases a target.
-*
-* A camera parented to the player is the Godot and Phaser idiom, and the
-* authoring skill explicitly permits it — *"EVERY node type can hold children …
-* any node works as a grouping container"*. Measured on exactly that scene:
-*
-* ```
-* player world position : [1400, 900]
-* renderer view centre  : {"x":0,"y":0}
-* framing               : camera /Level/Player/Cam centred [1400, 900]
-*                         1 in view, 0 outside it
-* ```
-*
-* The renderer drew empty world 1600 px from the player while `framing` — the
-* instrument the skills tell you to trust before handing a game back —
-* certified the player on screen.
-*
-* Arity comes from the node itself: a 2D node has two components, a 3D node
-* three, and an ancestor that is neither contributes nothing.
-*/
-function worldPosition(node) {
-	const own = node.position;
-	if (!Array.isArray(own)) return [];
-	const out = own.slice();
-	for (let at = node.parent; at; at = at.parent) {
-		const p = at.position;
-		if (!Array.isArray(p)) continue;
-		for (let i = 0; i < out.length; i++) out[i] = (out[i] ?? 0) + (p[i] ?? 0);
-	}
-	return out;
-}
-/**
-* Turn a world position into the local one `node.position` has to hold for the
-* node to END UP there — the inverse of `worldPosition` for its parent chain.
-*/
-function localFromWorld(node, world) {
-	const out = world.slice();
-	for (let at = node.parent; at; at = at.parent) {
-		const p = at.position;
-		if (!Array.isArray(p)) continue;
-		for (let i = 0; i < out.length; i++) out[i] = (out[i] ?? 0) - (p[i] ?? 0);
-	}
-	return out;
-}
-//#endregion
 //#region src/gameplay/chase.ts
 /**
 * Home in on a target node — the workhorse enemy AI. Each frame moves toward
@@ -4678,7 +4780,8 @@ var Chase = class extends Behavior {
 		if (!mover || !hasPosition$1(mover)) return;
 		const target = this.node.getNodeOrNull(this.target);
 		if (!target || !hasPosition$1(target)) return;
-		const d = distance$1(mover.position, target.position);
+		const targetPos = localFromWorld(mover, worldPosition(target));
+		const d = distance$1(mover.position, targetPos);
 		if (this.loseRange > 0 && d > this.loseRange) {
 			if (!this.lost) {
 				this.lost = true;
@@ -4698,7 +4801,7 @@ var Chase = class extends Behavior {
 		this.inRange = false;
 		const step = Math.min(this.speed * dt, this.stopRange > 0 ? d - this.stopRange : d);
 		const from = [...mover.position];
-		const { position } = moveToward(mover.position, target.position, Math.max(0, step));
+		const { position } = moveToward(mover.position, targetPos, Math.max(0, step));
 		moveBody(mover, position, dt);
 		if (this.facePath !== "") {
 			const skin = this.node.getNodeOrNull(this.facePath);
@@ -4732,12 +4835,23 @@ var Chase = class extends Behavior {
 * elsewhere is not a click. `hovered`/`unhovered` bracket the cursor being over
 * it.
 */
+/**
+* Frames of no pointer before this is a mistake rather than a still cursor.
+*
+* Two seconds at 60 Hz: long enough that a player who has not moved the mouse
+* yet is not told their game is broken, short enough to be on screen before
+* anyone starts reading the source.
+*/
+const QUIET_BEFORE_COMPLAINING = 120;
 var Clickable = class extends Behavior {
 	static props = {
 		/** Mouse button: 0 left, 1 middle, 2 right. */
 		button: { default: 0 },
-		/** Ignore clicks further away than this (0 = any distance). */
-		maxDistance: { default: 0 }
+		/** Ignore clicks further than this from the CURRENT CAMERA (0 = any). */
+		maxDistance: {
+			default: 0,
+			range: { min: 0 }
+		}
 	};
 	static signals = [
 		"clicked",
@@ -4749,17 +4863,24 @@ var Clickable = class extends Behavior {
 	/** True while the cursor is over this node — read it to tint a hover state. */
 	hovering = false;
 	pressedHere = false;
+	/** Frames in a row with nothing to click WITH — see the complaint below. */
+	silentFrames = 0;
 	update() {
 		const engine = this.node.tree?.engine;
 		if (!engine) return;
 		const picker = engine.picker;
 		const pointer = engine.input.pointerPosition();
 		if (!picker || !pointer) {
+			if (picker) {
+				this.silentFrames += 1;
+				if (this.silentFrames === QUIET_BEFORE_COMPLAINING) diagnose(engine, "error", `[incanto] Clickable on '${this.node.getPath()}' has had no pointer for ${QUIET_BEFORE_COMPLAINING} frames, so it can never fire. Nothing is feeding the cursor: pass \`pointer: true\` to createGame2D/3D, or call \`engine.input.attachPointer(canvas)\` on a manual boot.`);
+			}
 			if (this.hovering) this.setHover(false);
 			return;
 		}
+		this.silentFrames = 0;
 		const hit = engine.pickAt(pointer.x, pointer.y);
-		const over = hit !== null && this.isSelfOrDescendant(hit) && this.withinRange(hit);
+		const over = hit !== null && this.isSelfOrDescendant(hit) && this.withinRange();
 		if (over !== this.hovering) this.setHover(over);
 		if (engine.input.mouseJustPressed(this.button)) this.pressedHere = over;
 		if (engine.input.mouseJustReleased(this.button)) {
@@ -4776,19 +4897,65 @@ var Clickable = class extends Behavior {
 		for (let n = hit; n; n = n.parent) if (n === this.node) return true;
 		return false;
 	}
-	withinRange(hit) {
+	/**
+	* Is this node close enough to the camera to be worth clicking?
+	*
+	* It used to measure `distance(this.node, hit)` — and `hit` is always this
+	* node or a DESCENDANT of it, since `isSelfOrDescendant` runs first. So the
+	* prop documented as "ignore clicks further than this" gated on WHICH PART of
+	* the node you clicked: a chest 500 px away measured 0 and was allowed, while
+	* its own lid 200 px up measured 200 and was refused. The unused local named
+	* `camera`, assigned the scene ROOT, is where the intent got lost.
+	*/
+	withinRange() {
 		if (this.maxDistance <= 0) return true;
-		if (!this.node.tree?.engine?.scene?.root) return true;
-		const a = this.node.position;
-		const b = hit.position;
-		if (!Array.isArray(a) || !Array.isArray(b)) return true;
+		const camera = this.currentCamera();
+		if (!camera) {
+			if (!this.warnedNoCamera) {
+				this.warnedNoCamera = true;
+				diagnose(this.node.tree?.engine ?? null, "error", `[incanto] Clickable on '${this.node.getPath()}' has maxDistance ${this.maxDistance}, which is a range FROM THE CAMERA — and this scene has no camera to measure from, so every click is accepted. Add one, or drop the prop.`);
+			}
+			return true;
+		}
+		const from = worldPosition(camera);
+		const to = worldPosition(this.node);
+		if (from.length === 0 || to.length === 0) return true;
 		let sum = 0;
-		for (let i = 0; i < Math.max(a.length, b.length); i++) {
-			const d = (a[i] ?? 0) - (b[i] ?? 0);
+		for (let i = 0; i < Math.max(from.length, to.length); i++) {
+			const d = (from[i] ?? 0) - (to[i] ?? 0);
 			sum += d * d;
 		}
 		return Math.sqrt(sum) <= this.maxDistance;
 	}
+	warnedNoCamera = false;
+	camera = null;
+	/**
+	* The camera this scene is drawn from — `current` first, then the first one.
+	*
+	* The same order `describeFraming` and both renderers use. Re-resolved when
+	* the cached one leaves the tree, so a scene swap does not measure from a
+	* camera that is gone.
+	*/
+	currentCamera() {
+		if (this.camera?.tree && this.camera.current === true) return this.camera;
+		const root = this.node.tree?.root;
+		if (!root) return null;
+		let first = null;
+		const walk = (node) => {
+			const type = node.constructor.typeName ?? "";
+			if (type === "Camera2D" || type === "Camera3D") {
+				if (node.current === true) return node;
+				first ??= node;
+			}
+			for (const child of node.children) {
+				const found = walk(child);
+				if (found) return found;
+			}
+			return null;
+		};
+		this.camera = walk(root) ?? first;
+		return this.camera;
+	}
 };
 //#endregion
 //#region src/gameplay/collector.ts
@@ -4826,6 +4993,10 @@ group: { default: "player" } };
 		const d = data;
 		if (typeof d.total === "number") this.total = d.total;
 	}
+	/** The counter on screen. `collect(0)` used to be the only way to repaint it. */
+	announce() {
+		this.emit("totalChanged", this.total);
+	}
 };
 //#endregion
 //#region src/gameplay/currency.ts
@@ -4859,10 +5030,15 @@ var Currency = class extends Behavior {
 	max = 0;
 	/** Can this be paid right now? */
 	canAfford(cost) {
+		if (cost <= 0) return true;
 		return cost <= this.amount;
 	}
 	/** Pay `cost` if it is there. Returns whether it went through. */
 	spend(cost) {
+		if (requireNumber(cost, this.node, "Currency.spend") <= 0) {
+			this.refuseNonsense("spend", cost);
+			return true;
+		}
 		if (!this.canAfford(cost)) {
 			this.emit("refused", cost);
 			return false;
@@ -4874,13 +5050,31 @@ var Currency = class extends Behavior {
 	}
 	/** Take payment in. */
 	earn(gain) {
+		if (requireNumber(gain, this.node, "Currency.earn") <= 0) {
+			this.refuseNonsense("earn", gain);
+			return;
+		}
 		this.amount = this.max > 0 ? Math.min(this.max, this.amount + gain) : this.amount + gain;
 		this.emit("earned", gain);
 		this.emit("changed", this.amount);
 	}
+	/** What has already been complained about, so a loop says it once. */
+	complained = /* @__PURE__ */ new Set();
+	/**
+	* A zero is ordinary; a NEGATIVE is a caller that flipped a sign.
+	*
+	* Reported rather than thrown: this is called from game code inside a frame,
+	* and a throw here quarantines the node holding the player's money.
+	*/
+	refuseNonsense(what, n) {
+		if (n === 0 || this.complained.has(what)) return;
+		this.complained.add(what);
+		diagnose(this.node.tree?.engine ?? null, "error", `[incanto] Currency.${what}(${n}) on '${this.node.getPath()}' — a negative amount is a sign flip in the caller, never an offer. Ignored: ${what === "spend" ? "spending a negative used to PAY you" : "earning a negative used to TAKE from you"}.`);
+	}
 	/** Set it outright (a shop that grants, a cheat, a restore). */
 	setAmount(next) {
-		this.amount = this.max > 0 ? Math.min(this.max, next) : next;
+		const n = requireNumber(next, this.node, "Currency.setAmount");
+		this.amount = this.max > 0 ? Math.min(this.max, n) : n;
 		this.emit("changed", this.amount);
 	}
 	serialize() {
@@ -4890,6 +5084,10 @@ var Currency = class extends Behavior {
 		const d = data;
 		if (typeof d.amount === "number") this.amount = d.amount;
 	}
+	/** The wallet on screen — `setAmount`'s own doc comment already named a restore. */
+	announce() {
+		this.emit("changed", this.amount);
+	}
 };
 //#endregion
 //#region src/gameplay/free-target.ts
@@ -4953,7 +5151,15 @@ var Health = class extends Behavior {
 		/** Seconds of immunity after taking a hit (0 = no i-frames). */
 		invulnerableFor: { default: 0 },
 		/** queueFree() this node when it dies (clone-safe spawned-entity cleanup). */
-		freeOnDeath: { default: false }
+		freeOnDeath: { default: false },
+		/**
+		* …the PARENT, for the composition every other despawning behaviour
+		* supports. A node carries ONE script, so an enemy that walks and can be
+		* hurt splits `Patrol` and `Health` across children — and then the Health
+		* child froze itself and left an IMMORTAL body walking, which is the exact
+		* failure `Lifetime` and `DamageOnContact` got this prop for.
+		*/
+		...FREE_PARENT_PROP
 	};
 	static signals = [
 		"damaged",
@@ -4966,6 +5172,7 @@ var Health = class extends Behavior {
 	regenPerSec = 0;
 	invulnerableFor = 0;
 	freeOnDeath = false;
+	freeParent = false;
 	/** Current hit points (set to `max` on ready). */
 	current = 0;
 	invulnTimer = 0;
@@ -4990,7 +5197,7 @@ var Health = class extends Behavior {
 	}
 	/** Apply `n` damage. No-op while invulnerable or already dead. Emits `damaged`. */
 	damage(n) {
-		if (this.dead || n <= 0) return;
+		if (this.dead || requireNumber(n, this.node, "Health.damage") <= 0) return;
 		if (this.invulnTimer > 0) return;
 		this.setCurrent(this.current - n);
 		this.emit("damaged", n, this.current);
@@ -4999,7 +5206,7 @@ var Health = class extends Behavior {
 	}
 	/** Restore `n` hit points (clamped to `max`). No-op when dead. Emits `healed`. */
 	heal(n) {
-		if (this.dead || n <= 0) return;
+		if (this.dead || requireNumber(n, this.node, "Health.heal") <= 0) return;
 		this.setCurrent(this.current + n);
 		this.emit("healed", n, this.current);
 	}
@@ -5033,11 +5240,11 @@ var Health = class extends Behavior {
 	* A no-op on the living — reviving someone who never died would silently
 	* refill their health, which is a different feature and not this one.
 	*/
-	revive(hp) {
+	revive(hp = this.max) {
 		if (!this.dead) return;
 		this.dead = false;
 		this.current = 0;
-		this.setCurrent(hp === void 0 ? this.max : hp);
+		this.setCurrent(hp);
 		this.invulnTimer = this.invulnerableFor;
 		this.emit("revived", this.current);
 	}
@@ -5086,7 +5293,7 @@ var Health = class extends Behavior {
 		this.dead = true;
 		this.setCurrent(0);
 		this.emit("died");
-		if (this.freeOnDeath) this.node.queueFree();
+		if (this.freeOnDeath) freeOwner(this, this.freeParent, "Health");
 	}
 	/** Current HP and whether death already fired — `max` comes back from JSON. */
 	serialize() {
@@ -5100,6 +5307,16 @@ var Health = class extends Behavior {
 		if (typeof d.current === "number") this.current = Math.min(this.max, Math.max(0, d.current));
 		if (typeof d.dead === "boolean") this.dead = d.dead;
 	}
+	/**
+	* Repaint the bar. Not `died` — a save is being read, nobody just died.
+	*
+	* This one needed the hook most: `setCurrent` is private AND early-returns
+	* when the value is unchanged, so no call a game could make would repaint a
+	* restored bar. It read 100 at 38 HP until the next hit teleported it to 37.
+	*/
+	announce() {
+		this.emit("healthChanged", this.current, this.max);
+	}
 };
 //#endregion
 //#region src/gameplay/trigger.ts
@@ -5274,6 +5491,27 @@ var DayNight = class extends Behavior {
 	baseAmbient = .3;
 	baseExposure = 1;
 	captured = false;
+	/** Said once: there was no sky to move when this first looked. */
+	reportedNoSky = false;
+	/**
+	* What time it is. A save that forgets it returns you at dawn.
+	*
+	* `startHour` is the scene's opening, not the run's clock: a fresh `onReady`
+	* cannot know that this player has been out all night. `paused` goes with it
+	* because a game that stops the clock for a cutscene must not resume ticking
+	* on load.
+	*/
+	serialize() {
+		return {
+			hour: this.hour,
+			paused: this.paused
+		};
+	}
+	deserialize(data) {
+		const d = data ?? {};
+		if (typeof d.hour === "number" && Number.isFinite(d.hour)) this.hour = (d.hour % 24 + 24) % 24;
+		if (typeof d.paused === "boolean") this.paused = d.paused;
+	}
 	onReady() {
 		this.hour = this.startHour;
 	}
@@ -5292,7 +5530,13 @@ var DayNight = class extends Behavior {
 	applyHour() {
 		const engine = this.node.tree?.engine;
 		const env = engine?.scene?.environment;
-		if (!engine || !env?.sky) return;
+		if (!engine || !env?.sky) {
+			if (engine && !this.reportedNoSky) {
+				this.reportedNoSky = true;
+				diagnose(engine, "warn", `[incanto] ${this.node.getPath()}: DayNight drives environment.sky, and this scene has no \`sky\` — the clock runs and nothing on screen changes. It keeps looking, so a sky added later is fine; otherwise add \`"sky": { "type": "atmosphere" }\` to the scene environment.`);
+			}
+			return;
+		}
 		if (!this.captured) {
 			this.captured = true;
 			this.baseAmbient = env.ambient?.intensity ?? .3;
@@ -5480,7 +5724,8 @@ var FloatAway = class extends Behavior {
 		const t = Math.min(1, this.elapsed / life);
 		const next = [...this.start];
 		const eased = 1 - (1 - t) * (1 - t);
-		next[1] = (this.start[1] ?? 0) + this.rise * eased;
+		const up = this.start.length === 2 ? -1 : 1;
+		next[1] = (this.start[1] ?? 0) + up * this.rise * eased;
 		if (this.drift !== 0) next[0] = (this.start[0] ?? 0) + this.drift * eased;
 		node.position = next;
 		if (node.opacity !== void 0) {
@@ -5494,6 +5739,46 @@ var FloatAway = class extends Behavior {
 	}
 };
 //#endregion
+//#region src/core/effect-rng.ts
+/**
+* A random stream for something DECORATIVE, derived from the engine's seed.
+*
+* Particle emitters drew from `engine.rng` — the stream game logic reads — and
+* they spawn a number of particles that depends on `dt`. Measured on one scene
+* and one seed over the same simulated two seconds, comparing the world's own
+* draws by update index:
+*
+* ```
+* particles off:  60fps and 30fps identical
+* particles ON :  they diverge at update 2
+* ```
+*
+* A purely visual effect changed the game's random decisions, and the PLAYER'S
+* FRAME RATE decided them: the same seed gives a different game on a slower
+* machine, and a replay recorded at 60 fps does not reproduce on a laptop that
+* dropped to 30.
+*
+* Derived from `engine.seed` and the node's PATH, so it is:
+*
+* - **stable** — the same emitter in the same scene gets the same stream every
+*   run, which is what a screenshot diff and a replay need;
+* - **distinct** — two emitters do not march in lockstep;
+* - **separate** — nothing it draws is a value the game will not draw.
+*
+* Falls back to a fixed constant with no engine, which is what the emitters
+* already did when they had no tree.
+*/
+function effectRng(node, salt = 0) {
+	const engine = node.tree?.engine;
+	const path = node.getPath();
+	let hash = (engine?.seed ?? 4660) >>> 0;
+	for (let i = 0; i < path.length; i++) {
+		hash ^= path.charCodeAt(i);
+		hash = Math.imul(hash, 16777619) >>> 0;
+	}
+	return new Rng((hash ^ Math.imul(salt + 1, 2654435769)) >>> 0);
+}
+//#endregion
 //#region src/gameplay/follow-camera.ts
 /**
 * Make the node it sits on chase a target's position — THE camera-follow
@@ -5537,6 +5822,7 @@ var FollowCamera = class extends Behavior {
 	offset = [];
 	smoothing = 0;
 	deadzone = 0;
+	shakeRng = null;
 	onReady() {
 		if (this.target === "") throw new IncantoError("PROP_TYPE_MISMATCH", `FollowCamera on '${this.node.getPath()}': "target" (a node path) is required.`, { prop: "target" });
 		if (this.deadzone < 0) throw new IncantoError("PROP_TYPE_MISMATCH", `FollowCamera on '${this.node.getPath()}': "deadzone" must be >= 0, got ${this.deadzone}.`, { prop: "deadzone" });
@@ -5564,13 +5850,14 @@ var FollowCamera = class extends Behavior {
 			else cam.position = localFromWorld(cam, here.map((c, i) => c + ((desired[i] ?? c) - c) * f));
 		}
 		if (this.shakeT > 0) {
-			this.shakeT -= dt;
+			this.shakeT -= this.engine?.unscaledDelta || dt;
 			const k = this.shakeMag * Math.max(0, this.shakeT) / this.shakeFalloff;
 			if (this.shakeT <= 0) this.shakeMag = 0;
 			const jolted = cam.position.slice();
+			this.shakeRng ??= effectRng(this.node);
 			for (let i = 0; i < jolted.length; i++) {
 				const scale = jolted.length >= 3 && i === 1 ? .5 : 1;
-				jolted[i] = (jolted[i] ?? 0) + (this.engine.rng.next() * 2 - 1) * k * scale;
+				jolted[i] = (jolted[i] ?? 0) + (this.shakeRng.next() * 2 - 1) * k * scale;
 			}
 			cam.position = jolted;
 		}
@@ -5582,8 +5869,14 @@ var FollowCamera = class extends Behavior {
 * Read an input action that a game is ALLOWED not to declare — and say so once
 * when it is missing.
 *
-* `CharacterController3D` and `GameFlow` wrap every input read in a bare
-* `catch {}`. The tolerance is right: a game with no sprint key should not
+* `CharacterController3D` and `GameFlow` wrapped every input read in a bare
+* `catch {}` — and they were not the only readers, which is a mistake this
+* comment made for a year by naming them. `CharacterController2D` and
+* `Interactable` read bare, so a top-down game with no `jump` and a
+* point-and-click with no `interact` had the whole NODE quarantined: the
+* character could not move, the NPC stopped answering.
+* `every-action-a-game-may-not-declare.test.ts` reads the sources and fails on
+* the next one. The tolerance is right: a game with no sprint key should not
 * crash, and `pause()` stays an API even with no pause action. What was wrong is
 * that the tolerance is indistinguishable from a TYPO. Write
 * `"moveAction": "movement"` and the character stands still, forever, while
@@ -5608,27 +5901,80 @@ function tolerateUnknownAction(ctx, action, read, fallback) {
 //#endregion
 //#region src/gameplay/game-flow.ts
 /**
+* Build a scene the way the game BOOTED it — resolver included.
+*
+* Both reload paths called `loadScene(clone, { engine })` and nothing else, so
+* the `resolveScene` `createGame2D/3D` was given at boot was dropped on every
+* restart and every scene change. A game using the documented `instance:`
+* sub-scenes therefore booted fine and threw `UNRESOLVED_INSTANCE` on its FIRST
+* restart — inside `GameFlow.update`, which took the restart key with it for the
+* rest of the run. The engine remembers it now; this is where it comes back.
+*/
+function reload(engine, source) {
+	return loadScene(jsonClone(source), {
+		engine,
+		...engine.resolveScene ? { resolveScene: engine.resolveScene } : {}
+	});
+}
+/**
 * Reload the CURRENT scene from its source JSON — fresh nodes, reset physics,
 * rewired input. The restart primitive every game-over screen wants.
 */
 function restartScene(engine) {
 	const source = engine.scene?.source;
 	if (!source) return;
-	engine.setScene(loadScene(jsonClone(source)));
+	engine.setScene(reload(engine, source));
+	engine.ensurePhysics();
 }
 /**
+* Engines with a travel in flight. One door at a time, and the scene you are
+* LEAVING stops simulating while the screen is black.
+*
+* A `WeakSet` rather than a field, so this stays a free function and an engine
+* that is garbage collected mid-fade takes its entry with it.
+*/
+const travelling = /* @__PURE__ */ new WeakSet();
+/**
 * Swap to another scene behind a black fade (title→game→next level).
 * Headless (no DOM) the swap is immediate. Restores timeScale to 1.
+*
+* ONE AT A TIME. A door is usually a trigger, and a player who walks along a
+* wall of them fires several inside one fade. Measured on three doorways passed
+* in about a second:
+*
+* ```
+* setScene calls: 3 | order: ["crypt","garden","forge"]
+* final scene   : forge
+* ```
+*
+* Three complete scenes loaded and the player landed in the third — a level
+* they never walked to, from a door they never reached. Further calls while a
+* travel is in flight are IGNORED rather than queued: you already went through
+* a door, and the second one is the same input arriving twice.
+*
+* The outgoing scene also stops while the screen is black. It kept simulating
+* through the fade, so a player who triggered the door mid-fall died in the
+* level they were leaving — and the checkpoint that death wrote was for the
+* level they had left.
 */
 function goToScene(engine, sceneJson, opts) {
+	if (travelling.has(engine)) return;
 	const fade = opts?.fadeSeconds ?? .4;
 	const swap = () => {
-		engine.setScene(loadScene(jsonClone(sceneJson)));
+		engine.setScene(reload(engine, sceneJson));
+		engine.ensurePhysics();
 	};
 	if (typeof document === "undefined" || fade <= 0) {
 		swap();
 		return;
 	}
+	travelling.add(engine);
+	const wasTimeScale = engine.timeScale;
+	engine.timeScale = 0;
+	const arrive = () => {
+		travelling.delete(engine);
+		if (wasTimeScale !== 0) engine.timeScale = wasTimeScale;
+	};
 	const id = "incanto-scene-fade";
 	let el = document.getElementById(id);
 	if (!el) {
@@ -5640,11 +5986,17 @@ function goToScene(engine, sceneJson, opts) {
 	el.style.transition = `opacity ${fade / 2}s`;
 	el.style.opacity = "1";
 	setTimeout(() => {
-		swap();
-		const out = document.getElementById(id);
-		if (out) {
-			out.style.opacity = "0";
-			setTimeout(() => out.remove(), fade * 500 + 60);
+		try {
+			swap();
+		} catch (e) {
+			diagnose(engine, "error", `[incanto] goToScene: the destination scene did not load — staying in '${engine.scene?.name ?? "?"}'.`, e);
+		} finally {
+			arrive();
+			const out = document.getElementById(id);
+			if (out) {
+				out.style.opacity = "0";
+				setTimeout(() => out.remove(), fade * 500 + 60);
+			}
 		}
 	}, fade * 500 + 30);
 }
@@ -5725,12 +6077,40 @@ var GameFlow = class GameFlow extends Behavior {
 	onReady() {
 		this.syncPausePanel();
 	}
-	/** The panel follows the state; nothing else may own its visibility. */
+	/**
+	* The panel follows the state; nothing else may own its visibility.
+	*
+	* …and while it is up, the layer it lives on takes ARROW KEYS AND THE PAD.
+	* `HudLayer.focusNavigation` is off by default and rightly so — a game whose
+	* HUD happens to contain a button must not lose its arrow keys the moment one
+	* exists — and `incanto-hud.md` says "turn it on for the screens that ARE
+	* menus and off again when play resumes". A pause panel IS that screen, and
+	* this is the one place in the engine that knows when it opens and closes, so
+	* every game with a pause menu was writing the same two lines or shipping a
+	* menu no controller could reach.
+	*
+	* The layer's own value is remembered and put back: a game that turned
+	* navigation on for its own reasons keeps it after a pause.
+	*/
 	syncPausePanel() {
 		if (this.pausePanelPath === "") return;
 		const panel = this.node.getNodeOrNull(this.pausePanelPath);
-		if (panel && "visible" in panel) panel.visible = this.state === "paused";
+		if (!panel || !("visible" in panel)) return;
+		const paused = this.state === "paused";
+		panel.visible = paused;
+		const layer = layerAbove(panel);
+		if (!layer) return;
+		if (paused) {
+			if (this.navigationWas === null) this.navigationWas = layer.focusNavigation;
+			layer.focusNavigation = true;
+			layer.focus(firstFocusable(layer));
+		} else if (this.navigationWas !== null) {
+			if (layer.focusNavigation) layer.focusNavigation = this.navigationWas;
+			this.navigationWas = null;
+		}
 	}
+	/** The layer's own `focusNavigation`, while this flow is borrowing it. */
+	navigationWas = null;
 	gameOver(text = "GAME OVER", color = "#ef4444") {
 		this.transition("gameover", text, color);
 	}
@@ -5756,7 +6136,7 @@ var GameFlow = class GameFlow extends Behavior {
 		restartScene(this.engine);
 	}
 	/** Fade to another scene (next level, back to title). */
-	goToScene(sceneJson, opts) {
+	goToScene(sceneJson, opts = void 0) {
 		this.thaw();
 		goToScene(this.engine, sceneJson, opts);
 	}
@@ -5790,6 +6170,15 @@ var GameFlow = class GameFlow extends Behavior {
 		if (this.readAction("restartAction", "The restart key will do nothing.")) this.restart();
 	}
 };
+/** The `HudLayer` a widget lives on, or null. */
+function layerAbove(node) {
+	for (let at = node; at; at = at.parent) if (at instanceof HudLayer) return at;
+	return null;
+}
+/** Where the ring starts: opening a menu should land somewhere, not nowhere. */
+function firstFocusable(layer) {
+	return layer.focusables()[0] ?? null;
+}
 //#endregion
 //#region src/gameplay/interactable.ts
 function hasPosition(node) {
@@ -5826,18 +6215,26 @@ var Interactable = class extends Behavior {
 	action = "interact";
 	range = 2;
 	actorGroup = "player";
+	/** Actions already reported missing, so a per-frame read says it once. */
+	reportedActions = /* @__PURE__ */ new Set();
 	update() {
 		const engine = this.node.tree?.engine;
 		if (!engine?.scene) return;
-		if (!engine.input.justPressed(this.action)) return;
+		if (!tolerateUnknownAction({
+			engine,
+			who: this.node.getPath(),
+			reported: this.reportedActions,
+			consequence: "nothing here can be interacted with",
+			authored: this.action !== "interact"
+		}, this.action, () => engine.input.justPressed(this.action), false)) return;
 		if (!hasPosition(this.node)) return;
-		const self = this.node.position;
+		const self = worldPosition(this.node);
 		let nearest = null;
 		let nearestDist = Number.POSITIVE_INFINITY;
 		const actors = this.node.tree?.getNodesInGroup(this.actorGroup) ?? collectGroup(this.node.getRoot(), this.actorGroup);
 		for (const actor of actors) {
 			if (!hasPosition(actor)) continue;
-			const d = distance(self, actor.position);
+			const d = distance(self, worldPosition(actor));
 			if (d <= this.range && d < nearestDist) {
 				nearest = actor;
 				nearestDist = d;
@@ -5901,13 +6298,14 @@ var Cooldown = class {
 };
 const SHAKE_FALLOFF_SECONDS = .28;
 /** File the effect with the engine, if this one is attached to a running game. */
-function recordEffect(engine, kind, name, from, amount) {
+function recordEffect(engine, kind, name, from, amount, wiredAs) {
 	engine?.effects.record({
 		kind,
 		name,
 		from,
 		amount,
-		at: engine.time
+		at: engine.time,
+		wiredAs
 	});
 }
 /**
@@ -5926,6 +6324,19 @@ var CameraShake = class extends Behavior {
 	t = 0;
 	prev = [];
 	/**
+	* Decoration draws from its OWN stream — see `effectRng`.
+	*
+	* A shake drew from `engine.rng`, the stream game logic reads and
+	* `captureState` saves, once per axis per RENDERED frame. So the player's
+	* frame rate decided the game's random numbers, and toggling the
+	* `reduceMotion` accessibility switch changed the rolls: a replay recorded at
+	* 60 fps does not reproduce on a laptop that dropped to 30, and two players
+	* with the same seed diverge because one of them was hit. The particle
+	* siblings were moved off `engine.rng` for exactly this; both camera shakes
+	* were left behind.
+	*/
+	shakeRng = null;
+	/**
 	* Start a shake — unless the player asked for no motion.
 	*
 	* `settings.reduceMotion` is an accessibility switch, and camera movement the
@@ -5937,11 +6348,11 @@ var CameraShake = class extends Behavior {
 	* for 80 ms is feedback, not motion, and removing it would change what the
 	* game is rather than how it moves.
 	*/
-	shake(magnitude, seconds) {
+	shake(magnitude, seconds = this.falloff) {
 		if (this.engine?.settings.get("reduceMotion") === true) return;
 		this.magnitude = Math.max(this.magnitude, magnitude);
-		this.t = seconds ?? this.falloff;
-		recordEffect(this.engine, "shake", "", this.node?.getPath() ?? "engine", magnitude);
+		this.t = seconds;
+		recordEffect(this.engine, "shake", "", this.node?.getPath() ?? "engine", magnitude, this.node?.wiringPath());
 	}
 	update(dt) {
 		const node = requirePosition(this);
@@ -5954,14 +6365,15 @@ var CameraShake = class extends Behavior {
 			}
 			return;
 		}
-		this.t -= dt;
+		this.t -= this.engine?.unscaledDelta || dt;
 		const k = this.magnitude * Math.max(0, this.t) / this.falloff;
 		if (this.t <= 0) this.magnitude = 0;
 		const next = pos.slice();
 		if (this.prev.length !== next.length) this.prev = new Array(next.length).fill(0);
 		for (let i = 0; i < next.length; i++) {
 			const scale = next.length >= 3 && i === 1 ? .5 : 1;
-			this.prev[i] = (this.engine.rng.next() * 2 - 1) * k * scale;
+			this.shakeRng ??= effectRng(this.node);
+			this.prev[i] = (this.shakeRng.next() * 2 - 1) * k * scale;
 			next[i] = (next[i] ?? 0) + this.prev[i];
 		}
 		node.position = next;
@@ -6008,19 +6420,21 @@ function hitStop(engine, seconds = .08) {
 		state.until = Math.max(state.until, engine.unscaledTime + seconds);
 		return;
 	}
-	const restore = engine.timeScale;
+	const restore = engine.timeScale === 0 ? 1 : engine.timeScale;
 	const entry = {
 		startedAt: engine.unscaledTime,
 		until: engine.unscaledTime + seconds,
 		restore,
-		release: () => {}
+		release: () => {},
+		ownedAt: 0
 	};
 	hitStops.set(engine, entry);
 	engine.timeScale = 0;
+	entry.ownedAt = engine.timeScaleWrites;
 	entry.release = engine.updated.connect(() => {
 		if (!liveHitStop(engine)) return;
 		if (engine.unscaledTime < entry.until) return;
-		engine.timeScale = entry.restore;
+		if (engine.timeScaleWrites === entry.ownedAt) engine.timeScale = entry.restore;
 		entry.release();
 		hitStops.delete(engine);
 	});
@@ -6047,7 +6461,7 @@ function liveHitStop(engine) {
 	entry.release();
 	hitStops.delete(engine);
 }
-const hitStops = /* @__PURE__ */ new Map();
+const hitStops = /* @__PURE__ */ new WeakMap();
 //#endregion
 //#region src/gameplay/lifetime.ts
 /**
@@ -6452,13 +6866,40 @@ var Patrol = class extends Behavior {
 		const raw = this.points[i];
 		diagnose(this.node.tree?.engine ?? null, "error", `[incanto] ${this.node.getPath()}: waypoint ${i} (${JSON.stringify(raw)}) resolves to nothing — the patrol stops here and never moves again.`);
 	}
-	/** Resolve waypoint `i` to a position, reading node paths live. */
+	/**
+	* Resolve waypoint `i` to a position in the MOVER's frame, reading node paths
+	* live.
+	*
+	* A node-path waypoint used to return the marker's raw `position`, which is
+	* parent-relative — and it was then fed to `moveToward(mover.position, …)`,
+	* i.e. read in the MOVER's frame. So a walker and its markers under different
+	* parents walked a shifted copy of the path, silently, with the marker nodes
+	* sitting right there in the scene. Measured on a tower-defence lane
+	* organised the ordinary way (markers under `/root/Path`, spawns under a
+	* container at [-50, 90]): every creep stacked motionless 90 px below and
+	* 72 px short of the keep, `incanto-check` `1/1 scene(s) valid`, zero errors,
+	* zero warnings, and the wave could be neither won nor lost.
+	*
+	* `Chase` has converted through world space since the identical bug was found
+	* there ("comparing two nodes' raw `position` only worked while they happened
+	* to share a parent"), and a `FollowCamera` aimed at a node uses its world
+	* position too. Patrol was the outlier.
+	*
+	* A LITERAL array stays local, because that is the only frame an author can
+	* mean when they type numbers into a behaviour's props.
+	*
+	* `reportDeadWaypoint` could not see this: it fires when a path resolves to
+	* NOTHING, and a path that resolves into the wrong frame resolves fine.
+	*/
 	pointAt(i) {
 		const raw = this.points[i];
 		if (Array.isArray(raw)) return raw;
 		if (typeof raw === "string") {
 			const marker = this.node.getNodeOrNull(raw);
-			return Array.isArray(marker?.position) ? marker.position : null;
+			if (!marker || !hasPosition$1(marker)) return null;
+			const mover = this.moveParent ? this.node.parent : this.node;
+			if (!mover || !hasPosition$1(mover)) return null;
+			return localFromWorld(mover, worldPosition(marker));
 		}
 		return null;
 	}
@@ -6556,6 +6997,26 @@ function findCollector(node, group) {
 * `null` (the engine's "any JSON" escape hatch) and `null` means `'forward'`.
 * `gravity` adds a constant downward (+y, the 2D y-down convention) pull, for
 * lobbed/arcing shots.
+*
+* **Every prop here is live.** `speed` and `direction` re-bake the heading when
+* written, and the heading is resolved on the FIRST STEP rather than at
+* `onReady` — because `onReady` is before the one place a game aims a spawned
+* bullet. `SpawnSource.spawn` ends with `parent.addChild(clone)` and `Spawner`
+* emits `spawned(node)` after that, so a handler that sets a rotation or a
+* direction was always too late. Measured at speed 100 over 60 frames:
+*
+* ```
+* A rotation 0  direction [0,1]     -> pos [  0, 100]   authored: obeyed
+* B rotation 90 direction "forward" -> pos [  0, 100]   authored: obeyed
+* C rotation 90 set after addChild  -> pos [100,   0]   IGNORED
+* D direction [0,1] set after add   -> pos [100,   0]   IGNORED — and it read
+*                                                       back [0,1] while
+*                                                       travelling +x
+* ```
+*
+* What is deliberately NOT live is `rotation` after that first step: a
+* projectile that spins for looks would have its spin become its trajectory.
+* Call `aim()` to re-derive from the current rotation on purpose.
 */
 var Projectile = class extends Behavior {
 	static props = {
@@ -6567,31 +7028,76 @@ var Projectile = class extends Behavior {
 		gravity: { default: 0 }
 	};
 	static signals = [];
-	speed = 300;
-	direction = null;
+	_speed = 300;
+	_direction = null;
 	gravity = 0;
+	/** The straight-line part, `direction × speed`. Empty until the first step. */
 	velocity = [];
-	onReady() {
-		if (this.speed === 0 && this.gravity === 0) throw new IncantoError("PROP_TYPE_MISMATCH", `Projectile on '${this.node.getPath()}': a projectile with "speed" 0 and "gravity" 0 never moves — set one of them.`, { prop: "speed" });
+	/**
+	* The +y accumulated by `gravity`, kept APART from `velocity`.
+	*
+	* Re-aiming replaces the straight-line part; the fall is a fact about the
+	* world, not about the shot, so an arrow re-aimed halfway down keeps falling
+	* rather than snapping back to level.
+	*/
+	fall = 0;
+	/** Units per second along `direction`. Writable at any time. */
+	get speed() {
+		return this._speed;
+	}
+	set speed(value) {
+		this._speed = value;
+		if (this.armed) this.aim();
+	}
+	/** A vector (`[x,y(,z)]`) or `'forward'`. Writable at any time. */
+	get direction() {
+		return this._direction;
+	}
+	set direction(value) {
+		this._direction = value;
+		if (this.armed) this.aim();
+		else if (this.node) this.resolveDirection();
+	}
+	get armed() {
+		return this.velocity.length > 0;
+	}
+	/**
+	* Re-derive the heading from `direction` (or, for `'forward'`, from the
+	* node's CURRENT rotation) and bake it into the velocity.
+	*
+	* This is what a `spawned(node)` handler calls after turning the clone, and
+	* the only way a `'forward'` projectile ever re-reads its rotation.
+	*/
+	aim(direction = void 0) {
+		if (direction !== void 0) this._direction = direction;
 		const node = requirePosition(this);
 		const dir = this.resolveDirection();
-		this.velocity = dir.map((c) => c * this.speed);
+		this.velocity = dir.map((c) => c * this._speed);
 		while (this.velocity.length < node.position.length) this.velocity.push(0);
 	}
+	onReady() {
+		if (this.speed === 0 && this.gravity === 0) throw new IncantoError("PROP_TYPE_MISMATCH", `Projectile on '${this.node.getPath()}': a projectile with "speed" 0 and "gravity" 0 never moves — set one of them.`, { prop: "speed" });
+		requirePosition(this);
+		this.resolveDirection();
+	}
 	update(dt) {
+		if (!this.armed) this.aim();
 		const node = this.node;
-		if (this.gravity !== 0) this.velocity[1] = (this.velocity[1] ?? 0) + this.gravity * dt;
+		if (this.gravity !== 0) this.fall += this.gravity * dt;
 		const pos = node.position;
 		const n = Math.max(pos.length, this.velocity.length);
 		const next = new Array(n);
-		for (let i = 0; i < n; i++) next[i] = (pos[i] ?? 0) + (this.velocity[i] ?? 0) * dt;
+		for (let i = 0; i < n; i++) {
+			const v = (this.velocity[i] ?? 0) + (i === 1 ? this.fall : 0);
+			next[i] = (pos[i] ?? 0) + v * dt;
+		}
 		node.position = next;
 	}
 	/** Resolve `direction` to a unit vector, deriving 'forward' from rotation. */
 	resolveDirection() {
-		if (Array.isArray(this.direction)) return normalize(this.direction);
-		if (this.direction === null || this.direction === "forward") return this.forwardFromRotation();
-		throw new IncantoError("PROP_TYPE_MISMATCH", `Projectile on '${this.node.getPath()}': "direction" must be a vector or 'forward', got ${JSON.stringify(this.direction)}.`, { prop: "direction" });
+		if (Array.isArray(this._direction)) return normalize(this._direction);
+		if (this._direction === null || this._direction === "forward") return this.forwardFromRotation();
+		throw new IncantoError("PROP_TYPE_MISMATCH", `Projectile on '${this.node.getPath()}': "direction" must be a vector or 'forward', got ${JSON.stringify(this._direction)}.`, { prop: "direction" });
 	}
 	forwardFromRotation() {
 		const rot = this.node.rotation;
@@ -6658,6 +7164,7 @@ var SavePoint = class extends Behavior {
 	};
 	static signals = [
 		"saved",
+		"saveFailed",
 		"restored",
 		"noSave",
 		"hasSave"
@@ -6741,9 +7248,16 @@ var SavePoint = class extends Behavior {
 	*/
 	save() {
 		const engine = this.engine;
+		const state = engine.captureState();
+		const failures = engine.lastCaptureFailures;
+		if (failures.length > 0) {
+			engine.log.error(`[incanto] SavePoint '${this.slot}' REFUSED to write: ${failures.length} behavior(s) threw out of serialize(), so this save is missing their run and would overwrite the slot that is not. First: ${failures[0]}`);
+			this.emit("saveFailed", this.slot);
+			return;
+		}
 		this.store().write(this.slot, {
 			scene: this.scene || (engine.scene?.source.name ?? ""),
-			state: engine.captureState(),
+			state,
 			label: this.label,
 			savedAt: Date.now(),
 			playtime: Math.round(this.elapsed)
@@ -6768,6 +7282,9 @@ var SavePoint = class extends Behavior {
 			return;
 		}
 		const report = this.engine.restoreState(slot.state);
+		const here = this.engine?.scene?.name;
+		if (here && slot.scene && slot.scene !== here) diagnose(this.engine, "error", `[incanto] SavePoint '${this.slot}': this slot was saved in scene '${slot.scene}' and you are in '${here}'. Load that scene first — a save is restored INTO the scene it came from (incanto-save-slots.md).`);
+		else if (report.expected > 0 && report.restored === 0) diagnose(this.engine, "error", `[incanto] SavePoint '${this.slot}': restored 0 of ${report.expected} saveable behaviour(s)` + (report.missing.length > 0 ? ` — ${report.missing.length} uid(s) in the save are not in this scene, starting with '${report.missing[0]}'. That save is from an older build, or from another scene.` : ". Nothing in the save matched a node here."));
 		this.emit("restored", report.restored);
 	}
 	/** Forget this slot — a "delete save" button. */
@@ -6807,7 +7324,8 @@ var ScoreKeeper = class extends Behavior {
 		"scoreChanged",
 		"won",
 		"lost",
-		"lifeLost"
+		"lifeLost",
+		"livesChanged"
 	];
 	score = 0;
 	lives = 0;
@@ -6820,11 +7338,11 @@ var ScoreKeeper = class extends Behavior {
 	}
 	/** Add `n` to the score (negative subtracts), emit `scoreChanged`, check win. */
 	addScore(n) {
-		this.setScore(this.score + n);
+		this.setScore(this.score + requireNumber(n, this.node, "ScoreKeeper.addScore"));
 	}
 	/** Set the score to `value`, emit `scoreChanged`, check win. */
 	setScore(value) {
-		this.score = value;
+		this.score = requireNumber(value, this.node, "ScoreKeeper.setScore");
 		this.emit("scoreChanged", this.score);
 		if (this.scoreToWin > 0 && !this.hasWon && this.score >= this.scoreToWin) {
 			this.hasWon = true;
@@ -6836,6 +7354,7 @@ var ScoreKeeper = class extends Behavior {
 		if (this.lives <= 0 || this.hasLost) return;
 		this.lives -= 1;
 		this.emit("lifeLost", this.lives);
+		this.emit("livesChanged", this.lives);
 		if (this.lives <= 0) {
 			this.hasLost = true;
 			this.emit("lost");
@@ -6857,6 +7376,17 @@ var ScoreKeeper = class extends Behavior {
 		if (typeof d.hasWon === "boolean") this.hasWon = d.hasWon;
 		if (typeof d.hasLost === "boolean") this.hasLost = d.hasLost;
 	}
+	/**
+	* The score line and the lives counter. NOT `won`/`lost`.
+	*
+	* Re-firing those on load is how a Continue lands straight on the game-over
+	* screen it was loaded to escape — the flags come back through `hasWon` /
+	* `hasLost` and the game reads them, rather than being told again.
+	*/
+	announce() {
+		this.emit("scoreChanged", this.score);
+		this.emit("livesChanged", this.lives);
+	}
 };
 //#endregion
 //#region src/gameplay/spawn-source.ts
@@ -6892,6 +7422,12 @@ var SpawnSource = class {
 		const cached = this.detached.get(prefab);
 		if (cached) return cached;
 		const node = this.behavior.node;
+		const claim = absolutePrefabPath(node, prefab);
+		const shared = claim ? node.tree?._templates.get(claim) ?? null : null;
+		if (shared) {
+			this.detached.set(prefab, shared);
+			return shared;
+		}
 		const template = prefab === "" ? null : node.getNodeOrNull(prefab);
 		if (!template) {
 			const behaviorName = this.behavior.constructor.name;
@@ -6900,6 +7436,7 @@ var SpawnSource = class {
 				path: node.getPath()
 			});
 		}
+		if (claim) node.tree?._templates.set(claim, template);
 		if (template.parent) template.parent.removeChild(template);
 		this.detached.set(prefab, template);
 		return template;
@@ -6926,8 +7463,8 @@ var SpawnSource = class {
 	* The scene loads, the spawner spawns, the clone is alive and visible — it is
 	* just somewhere else in the level, and nothing has anything to report.
 	*/
-	spawn(template, opts) {
-		const clone = duplicateNode(template);
+	spawn(template, opts = void 0) {
+		const clone = duplicateNode(template, rebuildOptions(this.behavior.node));
 		const at = opts?.at;
 		if (at && at.length > 0 && hasPosition$1(clone)) clone.position = add((opts?.parent ?? this.behavior.node) === this.behavior.node || !hasPosition$1(this.behavior.node) ? [] : this.behavior.node.position, at);
 		if (typeof clone.visible === "boolean") clone.visible = true;
@@ -6935,6 +7472,29 @@ var SpawnSource = class {
 		return clone;
 	}
 };
+/**
+* The absolute path a relative prefab reference points at, resolved against the
+* spawner's own position — the key two spawners can agree on.
+*
+* Returns null for a form there is no single answer for (`%Unique` names a node
+* by identity, not by place), in which case the template is simply not shared —
+* which is the behaviour that already existed.
+*/
+function absolutePrefabPath(node, prefab) {
+	if (prefab === "" || prefab.startsWith("%")) return null;
+	if (prefab.startsWith("/")) return prefab;
+	const parts = node.getPath().split("/");
+	for (const step of prefab.split("/")) {
+		if (step === "" || step === ".") continue;
+		if (step === "..") {
+			if (parts.length <= 1) return null;
+			parts.pop();
+			continue;
+		}
+		parts.push(step);
+	}
+	return parts.join("/");
+}
 //#endregion
 //#region src/gameplay/spawner.ts
 /**
@@ -6993,7 +7553,11 @@ var Spawner = class extends Behavior {
 	_templateForTest() {
 		return this.template;
 	}
+	onEnterTree() {
+		this.template = this.source.resolveTemplate(this.prefab);
+	}
 	onReady() {
+		if (!(this.interval > 0) && this.max <= 0 && this.total <= 0) throw new IncantoError("PROP_TYPE_MISMATCH", `Spawner on '${this.node.getPath()}': "interval" ${this.interval} spawns a clone every FRAME and neither "max" (live cap) nor "total" (lifetime cap) is set, so the scene grows without bound. Give it an interval, or a cap.`, { prop: "interval" });
 		this.template = this.source.resolveTemplate(this.prefab);
 		this.running = this.autoStart;
 		this.timer = this.interval;
@@ -7080,9 +7644,10 @@ var Wander = class extends Behavior {
 	pickGoal() {
 		this.timer = this.changeEvery;
 		const dims = this.origin.length;
+		const up = dims === 3 ? 1 : -1;
 		const next = new Array(dims);
 		for (let attempt = 0; attempt < 8; attempt++) {
-			for (let i = 0; i < dims; i++) next[i] = (this.origin[i] ?? 0) + this.rng.range(-this.radius, this.radius);
+			for (let i = 0; i < dims; i++) next[i] = i === up ? this.origin[i] ?? 0 : (this.origin[i] ?? 0) + this.rng.range(-this.radius, this.radius);
 			if (distance$1(next, this.origin) <= this.radius) {
 				this.goal = next;
 				return;
@@ -7132,6 +7697,13 @@ var WaveSpawner = class extends Behavior {
 	timer = 0;
 	spawnedThisWave = 0;
 	announced = false;
+	onEnterTree() {
+		if (!Array.isArray(this.waves) || this.waves.length === 0) return;
+		for (const raw of this.waves) {
+			const prefab = raw.prefab;
+			if (typeof prefab === "string" && prefab !== "") this.source.resolveTemplate(prefab);
+		}
+	}
 	onReady() {
 		if (!Array.isArray(this.waves) || this.waves.length === 0) throw new IncantoError("PROP_TYPE_MISMATCH", `WaveSpawner on '${this.node.getPath()}': "waves" must be a non-empty array of { prefab, count, interval, delayBefore }.`, { prop: "waves" });
 		this.parsed = this.waves.map((raw, i) => this.parseWave(raw, i));
@@ -7142,6 +7714,38 @@ var WaveSpawner = class extends Behavior {
 	start() {
 		this.beginWave(0);
 	}
+	/**
+	* Which wave you were on — and nothing else.
+	*
+	* `behaviorsWithoutSave` is documented as "the list to read before shipping",
+	* and nobody had read it against this repo's own examples. Five of them put a
+	* `WaveSpawner` at the centre of the game (`fps-3d`, `tps-3d`, `tps-3d-neon`,
+	* `tps-3d-ruins`, `dogfight-3d`), and every one of them saved a run on wave 3
+	* and continued it on wave 1 — silently, because a save reloads the scene
+	* from source and a fresh `onReady` honestly starts at the beginning.
+	*
+	* The wave RESTARTS rather than resuming mid-spawn, which is the same
+	* checkpoint rule the rest of the save system follows: spawned entities are
+	* never restored, so resuming "four enemies into wave 3" would mean resuming
+	* a wave whose enemies do not exist. `waveStarted` fires again for the HUD.
+	*/
+	serialize() {
+		return {
+			wave: this.waveIndex,
+			done: this.phase === "done"
+		};
+	}
+	deserialize(data) {
+		const d = data ?? {};
+		if (d.done === true) {
+			this.phase = "done";
+			this.waveIndex = this.parsed.length - 1;
+			return;
+		}
+		if (typeof d.wave !== "number" || !Number.isInteger(d.wave)) return;
+		const wave = Math.max(0, Math.min(d.wave, this.parsed.length - 1));
+		this.beginWave(wave);
+	}
 	update(dt) {
 		if (this.phase === "idle" || this.phase === "done") return;
 		const wave = this.parsed[this.waveIndex];
@@ -7312,7 +7916,7 @@ var ZombieAI = class extends Behavior {
 			this.pickGoal();
 		}
 		const target = this.aggroTarget ? this.node.getNodeOrNull(this.aggroTarget) : null;
-		const targetPos = target && hasPosition$1(target) ? target.position : null;
+		const targetPos = target && hasPosition$1(target) ? localFromWorld(mover, worldPosition(target)) : null;
 		const aggroDist = targetPos ? this.groundDistance(mover.position, targetPos) : Number.POSITIVE_INFINITY;
 		if (!this.aggro && aggroDist <= this.aggroRange) {
 			this.aggro = true;
@@ -7432,4 +8036,4 @@ function registerGameplayBehaviors(opts) {
 	for (const [name, ctor] of Object.entries(GAMEPLAY_BEHAVIORS)) registerBehavior(name, ctor, { replace });
 }
 //#endregion
-export { DamageOnContact as A, rejectScale as B, restartScene as C, FaceTarget as D, FloatAway as E, localFromWorld as F, StaticBody3D as G, CharacterBody3D as H, worldPosition as I, createCausticsQuad as J, Node3D as K, Water3D as L, Currency as M, Collector as N, DayNight as O, Chase as P, WATER_CUTOUT_MAX as R, goToScene as S, FollowCamera as T, PhysicsBody3D as U, Area3D as V, RigidBody3D as W, colliderFootDrop as X, WATER_MAX_RIPPLES as Y, Cooldown as _, Wander as a, Interactable as b, SavePoint as c, Patrol as d, PathFollow as f, CameraShake as g, Lifetime as h, WaveSpawner as i, Health as j, phaseOf as k, Projectile as l, MoveTo as m, registerGameplayBehaviors as n, Spawner as o, Oscillate as p, validateCollider3D as q, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Pickup as u, hitStop as v, tolerateUnknownAction as w, GameFlow as x, screenFlash as y, WaterCutout3D as z };
+export { phaseOf as A, Area3D as B, restartScene as C, FloatAway as D, effectRng as E, Chase as F, Node3D as G, PhysicsBody3D as H, Water3D as I, WATER_MAX_RIPPLES as J, validateCollider3D as K, WATER_CUTOUT_MAX as L, Health as M, Currency as N, FaceTarget as O, Collector as P, WaterCutout3D as R, goToScene as S, FollowCamera as T, RigidBody3D as U, CharacterBody3D as V, StaticBody3D as W, localFromWorld as X, colliderFootDrop as Y, worldPosition as Z, Cooldown as _, Wander as a, Interactable as b, SavePoint as c, Patrol as d, PathFollow as f, CameraShake as g, Lifetime as h, WaveSpawner as i, DamageOnContact as j, DayNight as k, Projectile as l, MoveTo as m, registerGameplayBehaviors as n, Spawner as o, Oscillate as p, createCausticsQuad as q, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Pickup as u, hitStop as v, tolerateUnknownAction as w, GameFlow as x, screenFlash as y, rejectScale as z };