incanto 0.55.0 → 0.57.0

package/dist/{environment-presets-DAbEdEwh.js → environment-presets-CvvQr_bJ.js}

@@ -1,10 +1,12 @@
-import { t as registerCoreNodes } from "./register-p48lHE2o.js";
+import { C as diagnose } from "./loader-BcrRSjxB.js";
+import { t as registerCoreNodes } from "./register-Ch70uByv.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-C7u42TID.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
-import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-7qvUxF6Z.js";
-import { F as CharacterBody3D, I as PhysicsBody3D, L as RigidBody3D, N as WaterCutout3D, P as Area3D, R as StaticBody3D, U as colliderFootDrop, j as Water3D, z as Node3D } from "./gameplay-CZ2yq37J.js";
+import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-C0wXLBZJ.js";
+import { B as StaticBody3D, F as WaterCutout3D, G as colliderFootDrop, I as Area3D, L as CharacterBody3D, N as Water3D, R as PhysicsBody3D, V as Node3D, w as tolerateUnknownAction, z as RigidBody3D } from "./gameplay-BVphcxmE.js";
+import { t as checkSheetGrid } from "./sheet-grid-BT6N_Bjs.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
@@ -2175,8 +2177,41 @@ var AnimatedSprite3D = class extends Sprite3D {
 		}
 		this.currentFrame = this.frameList[this.frameIndex] ?? 0;
 	}
+	/**
+	* Does the grid fit the image, and does any animation run off the end?
+	*
+	* The same floor-division as the 2D twin, and for a long time the same
+	* division with none of its checking — the checker sat one directory away in
+	* 2d/ where this node could not see it.
+	*/
+	checkGrid(width, height) {
+		if (this.gridChecked === this.sheet) return;
+		this.gridChecked = this.sheet;
+		let highest = 0;
+		for (const [name, entry] of Object.entries(this.animations)) {
+			if (typeof entry === "string") continue;
+			try {
+				for (const frame of resolveFrames(entry.frames, name)) if (frame > highest) highest = frame;
+			} catch {
+				return;
+			}
+		}
+		const problem = checkSheetGrid(this.sheet, this.frameWidth, this.frameHeight, width, height, highest);
+		if (problem) diagnose(this.tree?.engine ?? null, "error", problem);
+	}
+	/** Reported once per sheet, so a bad grid says so on the first draw only. */
+	gridChecked = "";
+	/** Reported once, so a sheet with no frame size does not shout every frame. */
+	sizeReported = false;
 	resolveTexture(assets) {
-		if (!this.sheet || this.frameWidth <= 0 || this.frameHeight <= 0) return null;
+		if (!this.sheet) return null;
+		if (this.frameWidth <= 0 || this.frameHeight <= 0) {
+			if (!this.sizeReported) {
+				this.sizeReported = true;
+				diagnose(this.tree?.engine ?? null, "error", `[incanto] AnimatedSprite3D '${this.name}' has a sheet ('${this.sheet}') but frameWidth/frameHeight are 0 — it draws nothing. Set both to one frame's pixel size (bunx incanto-assets info <name> prints it for a built-in).`);
+			}
+			return null;
+		}
 		if (this.loadedSheetRef !== this.sheet) {
 			this.sheetTexture?.dispose();
 			this.loadedSheetRef = this.sheet;
@@ -2186,6 +2221,7 @@ var AnimatedSprite3D = class extends Sprite3D {
 		if (!tex) return null;
 		const image = tex.image;
 		if (!image?.width || !image.height) return tex;
+		this.checkGrid(image.width, image.height);
 		const cols = Math.max(1, Math.floor(image.width / this.frameWidth));
 		const col = this.currentFrame % cols;
 		const row = Math.floor(this.currentFrame / cols);
@@ -2319,10 +2355,14 @@ var BoneAttachment3D = class extends Node3D {
 			this.lookedUpFor = key;
 			this.boneObj = null;
 			const source = this.getNodeOrNull(this.target);
+			this.source = source;
 			if (source && typeof source.findBone === "function") this.boneObj = source.findBone(this.bone);
 		}
 		const boneObj = this.boneObj;
-		if (!boneObj) return;
+		if (!boneObj) {
+			this.reportMissingBone();
+			return;
+		}
 		const obj = this._ensureObject3D();
 		const parent = obj.parent;
 		if (!parent) return;
@@ -2339,6 +2379,28 @@ var BoneAttachment3D = class extends Node3D {
 		this.boneObj = null;
 		super.free();
 	}
+	/** The model this attachment last looked in. */
+	source = null;
+	reportedBone = "";
+	/**
+	* Say when the bone NAME is wrong, without accusing a model that is still
+	* loading.
+	*
+	* The lookup retries every frame on purpose — a GLB mounts async — so the
+	* node can never conclude on its own that the name is bad. But once the model
+	* HAS bones and this one is not among them, it is a typo, and the list that
+	* would fix it is sitting in `boneNames()` right next to `findBone`. Until
+	* now a misspelled bone left the sword at the mount node's authored position
+	* while the character animated away from it, forever, in silence.
+	*/
+	reportMissingBone() {
+		if (this.reportedBone === this.bone) return;
+		const names = this.source?.boneNames?.() ?? [];
+		if (names.length === 0) return;
+		this.reportedBone = this.bone;
+		const shown = names.slice(0, 8).join(", ");
+		diagnose(this.tree?.engine ?? null, "error", `[incanto] ${this.getPath()}: '${this.target}' has no bone '${this.bone}'. It has ${names.length}: [${shown}${names.length > 8 ? ", …" : ""}].`);
+	}
 };
 const offsetScratch = new Matrix4();
 const boneScratch = new Matrix4();
@@ -2506,6 +2568,11 @@ const DRAG_DAMPING = .15;
 const SPRING_K = 1.2;
 const SPRING_DAMPING = .08;
 const FALLING_MAX_VEL = -20;
+/** The schema's own default for an action prop — never a second copy of it. */
+function defaultActionOf(prop) {
+	const schema = CharacterController3D.props[prop];
+	return typeof schema?.default === "string" ? schema.default : "";
+}
 const LOOK_SPEED = .002;
 const RAD2DEG = 180 / Math.PI;
 /** Spring-arm camera collision: keep the camera this far in front of an obstacle. */
@@ -2706,8 +2773,10 @@ var CharacterController3D = class extends Node3D {
 			const len = Math.hypot(dir[0], dir[2]) || 1;
 			mx = dir[0] / len;
 			mz = dir[2] / len;
-		} catch {}
-		const sprinting = safePressed(input, this.sprintAction);
+		} catch (error) {
+			this.reportMissingAction("moveAction", error, "The character will not move.");
+		}
+		const sprinting = this.readAction("sprintAction", () => input.isPressed(this.sprintAction), false, "Sprint will never engage.");
 		const intensity = keyboardIntensity(moving, sprinting);
 		const speedMultiplier = 1 + (this.sprintMultiplier - 1) * intensity;
 		const targetSpeed = moving ? this.maxSpeed * speedMultiplier : 0;
@@ -2741,7 +2810,7 @@ var CharacterController3D = class extends Node3D {
 			this.coyoteLeft = Math.max(0, this.coyoteLeft - dt);
 			if (!this.grounded && this.coyoteLeft <= 0 && this.jumpsUsed === 0) this.jumpsUsed = 1;
 		}
-		const pressedJump = safeJustPressed(input, this.jumpAction);
+		const pressedJump = this.readAction("jumpAction", () => input.justPressed(this.jumpAction), false, "The character will never jump.");
 		if (pressedJump) this.bufferLeft = Math.max(this.jumpBufferSeconds, 0);
 		else this.bufferLeft = Math.max(0, this.bufferLeft - dt);
 		if ((this.bufferLeft > 0 || pressedJump) && (footed || this.coyoteLeft > 0 || this.jumpsUsed < this.maxJumps)) {
@@ -2761,7 +2830,7 @@ var CharacterController3D = class extends Node3D {
 		}
 		if (this.rising) {
 			if ((vel[1] ?? 0) <= 0) this.rising = false;
-			else if (this.jumpCutMultiplier < 1 && !safePressed(input, this.jumpAction)) {
+			else if (this.jumpCutMultiplier < 1 && !this.readAction("jumpAction", () => input.isPressed(this.jumpAction), false, "The character will never jump.")) {
 				const cut = (vel[1] ?? 0) * this.jumpCutMultiplier;
 				body.linearVelocity = [
 					vel[0],
@@ -2806,6 +2875,31 @@ var CharacterController3D = class extends Node3D {
 			}
 		}
 	}
+	/** Actions already reported missing, so a per-frame read says it once. */
+	reportedActions = /* @__PURE__ */ new Set();
+	/**
+	* Read an input action this controller is allowed to be missing.
+	*
+	* Tolerated because a game may declare no sprint key and no jump; reported
+	* because otherwise a TYPO looks exactly like a deliberate omission, and the
+	* engine has already thrown the sentence that fixes it.
+	*/
+	readAction(prop, read, fallback, consequence) {
+		const action = this[prop];
+		return tolerateUnknownAction({
+			engine: this.tree?.engine,
+			who: this.getPath(),
+			reported: this.reportedActions,
+			consequence,
+			authored: action !== defaultActionOf(prop)
+		}, action, read, fallback);
+	}
+	/** Report a throw the caller already caught (the move read has its own try). */
+	reportMissingAction(prop, error, consequence) {
+		this.readAction(prop, () => {
+			throw error;
+		}, void 0, consequence);
+	}
 	update(dt) {
 		const input = this.tree?.engine?.input;
 		if (!input) return;
@@ -2921,28 +3015,14 @@ function worldOf(node) {
 		z
 	];
 }
-function safePressed(input, action) {
-	try {
-		return input.isPressed(action);
-	} catch {
-		return false;
-	}
-}
 /**
 * The EDGE, not the level.
 *
 * Jump used to read `isPressed`, so holding the button re-jumped on every frame
 * the raycast found ground — an auto-hop nobody asked for, and one that makes
 * coyote time incoherent (a held button would re-fire through the whole
-* window). Same undeclared-action tolerance as `safePressed`.
+* window). Undeclared actions are tolerated, and reported once.
 */
-function safeJustPressed(input, action) {
-	try {
-		return input.justPressed(action);
-	} catch {
-		return false;
-	}
-}
 //#endregion
 //#region src/3d/vegetation/grass-placement.ts
 const NOISE_SCALE = .15;
@@ -3668,6 +3748,7 @@ var Flowers3D = class extends Node3D {
 			this.height,
 			this.clustering,
 			this.drape,
+			this.avoidWater,
 			this.terrain
 		]);
 		if (key === this.fieldKey) return;
@@ -5222,6 +5303,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 			this.colorA,
 			this.colorB,
 			this.coverage,
+			this.avoidWater,
 			this.flowers,
 			this.seed,
 			this.drape,
@@ -5737,6 +5819,18 @@ var Label3D = class extends Sprite3D {
 	font = "sans-serif";
 	outline = "#000000";
 	billboard = "full";
+	/**
+	* A `texture` on a label is a mistake, and a loud one.
+	*
+	* The prop is inherited from `Sprite3D` and cannot be un-inherited (schemas
+	* merge up the chain), so a URL set here would be silently ignored — this
+	* node draws its own text. Silent is the failure mode these rounds keep
+	* finding; naming it costs one check at load.
+	*/
+	static validateJson(node) {
+		const label = node;
+		if (label.texture) throw new IncantoError("BAD_FORMAT", `Label3D '${label.name}' has a "texture" — a label draws its own text, so the image would never be used. Set "text" instead, or use a Sprite3D.`, { prop: "texture" });
+	}
 	canvas = null;
 	/** The rasterised text. Named apart from Sprite3D's `texture` URL prop, which
 	*  this node ignores — the text IS the picture. */

package/dist/{frame-report-njybhZon.js → frame-report-BSMny7oe.js}

@@ -1,4 +1,4 @@
-//#region src/3d/frame-report.ts
+//#region src/core/frame-report.ts
 /** Rec. 709 relative luminance of an 8-bit triple, 0..1. */
 function luma(r, g, b) {
 	return (.2126 * r + .7152 * g + .0722 * b) / 255;

package/dist/{frame-report-DZ70IY26.d.ts → frame-report-DCnHFmto.d.ts}

@@ -1,4 +1,4 @@
-//#region src/3d/frame-report.d.ts
+//#region src/core/frame-report.d.ts
 /**
 * What the frame looks like, as something worth saying.
 *

package/dist/{gameplay-CZ2yq37J.js → gameplay-BVphcxmE.js}

@@ -1,7 +1,7 @@
-import { A as registerBehavior, T as Behavior, b as effectiveOrder, f as Node, n as loadScene, p as SaveSlots } from "./loader-BTkHYrQn.js";
+import { A as registerBehavior, C as diagnose, S as Node, T as Behavior, f as SaveSlots, n as loadScene, y as effectiveOrder } from "./loader-BcrRSjxB.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as jsonClone } from "./json-BLk7H2Qa.js";
-import { t as duplicateNode } from "./duplicate-MNLMAcbz.js";
+import { t as duplicateNode } from "./duplicate-BPLZDZpd.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/3d/frustum.ts
 const scratchFrustum = new Frustum();
@@ -4172,12 +4172,20 @@ var Buoyancy = class extends Behavior {
 	size = [1, 1];
 	surface = null;
 	wet = false;
+	/** Said once: a body that cannot be pushed will never start being able to. */
+	reportedNoImpulse = false;
 	update(dt) {
 		if (dt <= 0) return;
 		const water = this.resolveWater();
 		if (!water) return;
 		const node = this.node;
-		if (!node.applyImpulse) return;
+		if (!node.applyImpulse) {
+			if (!this.reportedNoImpulse) {
+				this.reportedNoImpulse = true;
+				diagnose(this.node.tree?.engine ?? null, "error", `[incanto] ${this.node.getPath()}: Buoyancy needs a body it can push — this node has no applyImpulse, so it will never float. Put it on a RigidBody3D.`);
+			}
+			return;
+		}
 		const [x, y, z] = [
 			node.position[0] ?? 0,
 			node.position[1] ?? 0,
@@ -4891,6 +4899,78 @@ function phaseOf(hour) {
 	return "dusk";
 }
 //#endregion
+//#region src/gameplay/float-away.ts
+/**
+* Rise, fade, and be gone — the second half of a damage number.
+*
+* `Label3D` gave a game text standing in the world; every game then writes the
+* same eight lines to move it up and fade it out, and the interesting part is
+* not the eight lines, it is the three things they all get wrong: the node is
+* freed on the frame it becomes invisible rather than a second later, the fade
+* fights whatever else writes `opacity`, and a hundred numbers a fight each
+* leave a node behind because nothing ever frees them.
+*
+* ```json
+* { "name": "Hit", "type": "Label3D",
+*   "props": { "text": "12", "height": 0.35, "color": "#ff5a5a" },
+*   "script": { "name": "FloatAway", "props": { "rise": 1.2, "seconds": 0.7 } } }
+* ```
+*
+* Spawning one is then `duplicateNode` + set `text` + `position` — no per-frame
+* code of your own, and no cleanup to forget.
+*
+* It writes `opacity` and the node's own `position`, so it composes with
+* anything that does not. Works on any node with those props: a `Label3D`, a
+* `Sprite3D` pickup puff, a 2D `Label`.
+*/
+var FloatAway = class extends Behavior {
+	static props = {
+		/** World units travelled over the whole life (negative sinks). */
+		rise: { default: 1 },
+		/** How long the whole thing takes. */
+		seconds: { default: .7 },
+		/** Fraction of the life spent at full opacity before the fade starts. */
+		hold: { default: .3 },
+		/** Sideways drift, so ten numbers at once do not stack into one. */
+		drift: { default: 0 },
+		/** Free the node when it finishes. Off for something you re-use. */
+		freeOnEnd: { default: true }
+	};
+	rise = 1;
+	seconds = .7;
+	hold = .3;
+	drift = 0;
+	freeOnEnd = true;
+	elapsed = 0;
+	start = [];
+	done = false;
+	onReady() {
+		const node = this.node;
+		this.start = [...node.position ?? []];
+	}
+	update(dt) {
+		if (this.done) return;
+		const node = this.node;
+		if (!node.position) return;
+		this.elapsed += dt;
+		const life = Math.max(.001, this.seconds);
+		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;
+		if (this.drift !== 0) next[0] = (this.start[0] ?? 0) + this.drift * eased;
+		node.position = next;
+		if (node.opacity !== void 0) {
+			const holdFor = Math.min(.99, Math.max(0, this.hold));
+			node.opacity = t <= holdFor ? 1 : 1 - (t - holdFor) / (1 - holdFor);
+		}
+		if (t >= 1) {
+			this.done = true;
+			if (this.freeOnEnd) this.node.queueFree();
+		}
+	}
+};
+//#endregion
 //#region src/gameplay/follow-camera.ts
 /**
 * Make the node it sits on chase a target's position — THE camera-follow
@@ -4964,6 +5044,35 @@ var FollowCamera = class extends Behavior {
 	}
 };
 //#endregion
+//#region src/core/optional-action.ts
+/**
+* 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
+* 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
+* `InputMap` has already thrown the exact sentence that would fix it —
+* `Unknown input action 'movement'. Declared actions: [move, jump].` — and the
+* catch discards it.
+*
+* Reported once per node and action, so a per-frame read does not shout.
+*/
+function tolerateUnknownAction(ctx, action, read, fallback) {
+	try {
+		return read();
+	} catch (error) {
+		if (ctx.authored && !ctx.reported.has(action)) {
+			ctx.reported.add(action);
+			const detail = error instanceof Error ? error.message : String(error);
+			diagnose(ctx.engine ?? null, "error", `[incanto] ${ctx.who}: ${detail} ${ctx.consequence}`);
+		}
+		return fallback;
+	}
+}
+//#endregion
 //#region src/gameplay/game-flow.ts
 /**
 * Reload the CURRENT scene from its source JSON — fresh nodes, reset physics,
@@ -5023,7 +5132,7 @@ function goToScene(engine, sceneJson, opts) {
 * through a `%Banner` UiBanner when one exists; otherwise states are silent
 * (drive your own UI off the `flowChanged` signal).
 */
-var GameFlow = class extends Behavior {
+var GameFlow = class GameFlow extends Behavior {
 	static signals = ["flowChanged"];
 	static props = {
 		restartAction: { default: "restart" },
@@ -5049,6 +5158,28 @@ var GameFlow = class extends Behavior {
 	* fine and means pause is API-only).
 	*/
 	pauseAction = "pause";
+	/** Actions already reported missing, so a per-frame poll says it once. */
+	reportedActions = /* @__PURE__ */ new Set();
+	/**
+	* Poll an action this flow is allowed to be missing, and say so once when the
+	* author named one that does not exist.
+	*
+	* Tolerated because `pause()` and `restart()` stay API-only in a game with no
+	* such key. Reported because a typed-out `"restartAction": "retry"` that is
+	* never declared leaves a frozen game-over screen that answers nothing, and
+	* the engine has already thrown the sentence that fixes it.
+	*/
+	readAction(prop, consequence) {
+		const action = this[prop];
+		const schema = GameFlow.props[prop];
+		return tolerateUnknownAction({
+			engine: this.engine,
+			who: this.node.getPath(),
+			reported: this.reportedActions,
+			consequence,
+			authored: action !== (typeof schema?.default === "string" ? schema.default : "")
+		}, action, () => this.engine.input.justPressed(action), false);
+	}
 	/**
 	* A node shown while paused and hidden otherwise — a `UiPanel` of buttons in
 	* practice. '' turns the whole thing off.
@@ -5120,16 +5251,12 @@ var GameFlow = class extends Behavior {
 	}
 	update() {
 		if (this.state === "playing" || this.state === "paused") {
-			try {
-				if (this.engine.input.justPressed(this.pauseAction)) if (this.state === "playing") this.pause();
-				else this.resume();
-			} catch {}
+			if (this.readAction("pauseAction", "The pause key will do nothing.")) if (this.state === "playing") this.pause();
+			else this.resume();
 			return;
 		}
 		if (this.state !== "gameover" && this.state !== "won") return;
-		try {
-			if (this.engine.input.justPressed(this.restartAction)) this.restart();
-		} catch {}
+		if (this.readAction("restartAction", "The restart key will do nothing.")) this.restart();
 	}
 };
 //#endregion
@@ -5698,7 +5825,10 @@ var Patrol = class extends Behavior {
 		}
 		const node = this.node;
 		const target = this.pointAt(this.index);
-		if (!target) return;
+		if (!target) {
+			this.reportDeadWaypoint(this.index);
+			return;
+		}
 		const { position, reached } = moveToward(node.position, target, this.speed * dt);
 		moveBody(node, position, dt);
 		if (reached) {
@@ -5707,6 +5837,24 @@ var Patrol = class extends Behavior {
 			if (this.pauseAt > 0) this.pauseTimer = this.pauseAt;
 		}
 	}
+	/** Waypoints already reported dead, so a per-frame stall says it once. */
+	reportedDead = /* @__PURE__ */ new Set();
+	/**
+	* Say which waypoint the route died on.
+	*
+	* A `points` entry can be a node path, and a misspelled one stops the
+	* patroller the moment the index reaches it — `advance()` is never called, so
+	* it never moves again — with nothing printed. `points` is an ARRAY, so it
+	* cannot carry `nodePath: true`, and `nodeRefWarnings` only inspects string
+	* props: every other node-path prop in the engine is covered by that lint and
+	* this one is invisible to it.
+	*/
+	reportDeadWaypoint(i) {
+		if (this.reportedDead.has(i)) return;
+		this.reportedDead.add(i);
+		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. */
 	pointAt(i) {
 		const raw = this.points[i];
@@ -6636,7 +6784,8 @@ const GAMEPLAY_BEHAVIORS = {
 	Spawner,
 	WaveSpawner,
 	Projectile,
-	Buoyancy
+	Buoyancy,
+	FloatAway
 };
 /**
 * Register all built-in gameplay behaviors. Idempotent and hot-reload tolerant
@@ -6648,4 +6797,4 @@ function registerGameplayBehaviors(opts) {
 	for (const [name, ctor] of Object.entries(GAMEPLAY_BEHAVIORS)) registerBehavior(name, ctor, { replace });
 }
 //#endregion
-export { Chase as A, validateCollider3D as B, restartScene as C, DamageOnContact as D, phaseOf as E, CharacterBody3D as F, WATER_MAX_RIPPLES as H, PhysicsBody3D as I, RigidBody3D as L, WATER_CUTOUT_MAX as M, WaterCutout3D as N, Health as O, Area3D as P, StaticBody3D as R, goToScene as S, DayNight as T, colliderFootDrop as U, createCausticsQuad as V, 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, Water3D as j, Collector as k, Projectile as l, MoveTo as m, registerGameplayBehaviors as n, Spawner as o, Oscillate as p, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Pickup as u, hitStop as v, FollowCamera as w, GameFlow as x, screenFlash as y, Node3D as z };
+export { Health as A, StaticBody3D as B, restartScene as C, DayNight as D, FloatAway as E, WaterCutout3D as F, colliderFootDrop as G, validateCollider3D as H, Area3D as I, CharacterBody3D as L, Chase as M, Water3D as N, phaseOf as O, WATER_CUTOUT_MAX as P, PhysicsBody3D as R, goToScene as S, FollowCamera as T, createCausticsQuad as U, Node3D as V, WATER_MAX_RIPPLES as W, 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, Collector as j, DamageOnContact as k, Projectile as l, MoveTo as m, registerGameplayBehaviors as n, Spawner as o, Oscillate as p, 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, RigidBody3D as z };

package/dist/gameplay.d.ts

@@ -1,4 +1,4 @@
-import { At as Node, b as Engine, d as PropSchema, n as BehaviorCtor, t as Behavior } from "./behavior-CyQoSu4n.js";
+import { At as Node, b as Engine, d as PropSchema, n as BehaviorCtor, t as Behavior } from "./behavior-l08AEbq9.js";
 import { c as JsonValue, s as JsonObject } from "./schema-CFeioQRE.js";
 
 //#region src/gameplay/chase.d.ts
@@ -318,6 +318,19 @@ declare class Patrol extends Behavior {
   private pauseTimer;
   override onReady(): void;
   override update(dt: number): void;
+  /** Waypoints already reported dead, so a per-frame stall says it once. */
+  private readonly reportedDead;
+  /**
+  * Say which waypoint the route died on.
+  *
+  * A `points` entry can be a node path, and a misspelled one stops the
+  * patroller the moment the index reaches it — `advance()` is never called, so
+  * it never moves again — with nothing printed. `points` is an ARRAY, so it
+  * cannot carry `nodePath: true`, and `nodeRefWarnings` only inspects string
+  * props: every other node-path prop in the engine is covered by that lint and
+  * this one is invisible to it.
+  */
+  private reportDeadWaypoint;
   /** Resolve waypoint `i` to a position, reading node paths live. */
   private pointAt;
   private advance;
@@ -678,6 +691,60 @@ declare class DayNight extends Behavior {
 }
 declare function phaseOf(hour: number): DayPhase;
 //#endregion
+//#region src/gameplay/float-away.d.ts
+/**
+* Rise, fade, and be gone — the second half of a damage number.
+*
+* `Label3D` gave a game text standing in the world; every game then writes the
+* same eight lines to move it up and fade it out, and the interesting part is
+* not the eight lines, it is the three things they all get wrong: the node is
+* freed on the frame it becomes invisible rather than a second later, the fade
+* fights whatever else writes `opacity`, and a hundred numbers a fight each
+* leave a node behind because nothing ever frees them.
+*
+* ```json
+* { "name": "Hit", "type": "Label3D",
+*   "props": { "text": "12", "height": 0.35, "color": "#ff5a5a" },
+*   "script": { "name": "FloatAway", "props": { "rise": 1.2, "seconds": 0.7 } } }
+* ```
+*
+* Spawning one is then `duplicateNode` + set `text` + `position` — no per-frame
+* code of your own, and no cleanup to forget.
+*
+* It writes `opacity` and the node's own `position`, so it composes with
+* anything that does not. Works on any node with those props: a `Label3D`, a
+* `Sprite3D` pickup puff, a 2D `Label`.
+*/
+declare class FloatAway extends Behavior {
+  static override readonly props: {
+    /** World units travelled over the whole life (negative sinks). */rise: {
+      default: number;
+    }; /** How long the whole thing takes. */
+    seconds: {
+      default: number;
+    }; /** Fraction of the life spent at full opacity before the fade starts. */
+    hold: {
+      default: number;
+    }; /** Sideways drift, so ten numbers at once do not stack into one. */
+    drift: {
+      default: number;
+    }; /** Free the node when it finishes. Off for something you re-use. */
+    freeOnEnd: {
+      default: boolean;
+    };
+  };
+  rise: number;
+  seconds: number;
+  hold: number;
+  drift: number;
+  freeOnEnd: boolean;
+  private elapsed;
+  private start;
+  private done;
+  override onReady(): void;
+  override update(dt: number): void;
+}
+//#endregion
 //#region src/gameplay/game-flow.d.ts
 /**
 * Reload the CURRENT scene from its source JSON — fresh nodes, reset physics,
@@ -721,6 +788,18 @@ declare class GameFlow extends Behavior {
   * fine and means pause is API-only).
   */
   pauseAction: string;
+  /** Actions already reported missing, so a per-frame poll says it once. */
+  private readonly reportedActions;
+  /**
+  * Poll an action this flow is allowed to be missing, and say so once when the
+  * author named one that does not exist.
+  *
+  * Tolerated because `pause()` and `restart()` stay API-only in a game with no
+  * such key. Reported because a typed-out `"restartAction": "retry"` that is
+  * never declared leaves a frozen game-over screen that answers nothing, and
+  * the engine has already thrown the sentence that fixes it.
+  */
+  private readAction;
   /**
   * A node shown while paused and hidden otherwise — a `UiPanel` of buttons in
   * practice. '' turns the whole thing off.
@@ -869,4 +948,4 @@ declare function registerGameplayBehaviors(opts?: {
   replace?: boolean;
 }): void;
 //#endregion
-export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, DayNight, type DayPhase, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, phaseOf, registerGameplayBehaviors, restartScene, screenFlash };
+export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, DayNight, type DayPhase, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, phaseOf, registerGameplayBehaviors, restartScene, screenFlash };

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { A as Chase, C as restartScene, D as DamageOnContact, E as phaseOf, O as Health, S as goToScene, T as DayNight, _ as Cooldown, a as Wander, b as Interactable, c as SavePoint, d as Patrol, f as PathFollow, g as CameraShake, h as Lifetime, i as WaveSpawner, k as Collector, l as Projectile, m as MoveTo, n as registerGameplayBehaviors, o as Spawner, p as Oscillate, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Pickup, v as hitStop, w as FollowCamera, x as GameFlow, y as screenFlash } from "./gameplay-CZ2yq37J.js";
-export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, DayNight, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, phaseOf, registerGameplayBehaviors, restartScene, screenFlash };
+import { A as Health, C as restartScene, D as DayNight, E as FloatAway, M as Chase, O as phaseOf, S as goToScene, T as FollowCamera, _ as Cooldown, a as Wander, b as Interactable, c as SavePoint, d as Patrol, f as PathFollow, g as CameraShake, h as Lifetime, i as WaveSpawner, j as Collector, k as DamageOnContact, l as Projectile, m as MoveTo, n as registerGameplayBehaviors, o as Spawner, p as Oscillate, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Pickup, v as hitStop, x as GameFlow, y as screenFlash } from "./gameplay-BVphcxmE.js";
+export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, DayNight, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, phaseOf, registerGameplayBehaviors, restartScene, screenFlash };