incanto 0.71.0 → 0.73.0

package/dist/{gameplay-CNULJvwh.js → gameplay-CRte0OVf.js}

@@ -1,8 +1,8 @@
 import { t as jsonClone } from "./json-CfTjpvW8.js";
-import { B as HudLayer, J as Node, K as requireNumber, P as effectiveOrder, Y as diagnose, d as rebuildOptions, et as Behavior, f as rememberAuthoredPath, h as loadScene, n as SaveSlots, ot as registerBehavior, s as duplicateNode } from "./save-slots-Bvuh2p_r.js";
+import { B as HudLayer, J as Node, K as requireNumber, P as effectiveOrder, Y as diagnose, d as rebuildOptions, et as Behavior, f as rememberAuthoredPath, h as loadScene, n as SaveSlots, ot as registerBehavior, s as duplicateNode } from "./save-slots-CEUGeLuB.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-CDOMybym.js";
-import { h as didYouMean } from "./touch-BnCyPA0G.js";
+import { h as didYouMean } from "./touch-CioTZB-y.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[]`. */
@@ -2433,7 +2433,14 @@ var Node3D = class Node3D extends Node {
 				"overlay"
 			]
 		},
-		snapToGround: { default: null }
+		snapToGround: {
+			default: null,
+			kinds: [
+				"null",
+				"boolean",
+				"number"
+			]
+		}
 	};
 	position = [
 		0,
@@ -2698,9 +2705,27 @@ var PhysicsBody3D = class extends Node3D {
 	/** @internal Set by Physics3D when the body is created. */
 	_physics = null;
 };
-/** Immovable collider (ground, walls, platforms). */
+/**
+* Immovable collider (ground, walls, platforms).
+*
+* It also carries the SURFACE it is: `friction` and `restitution` used to
+* live on `RigidBody3D` alone, so a trampoline, an ice patch or a sticky
+* landing could not be written in scene JSON, and Rapier's AVERAGE rule
+* halved whatever a ball brought to a plain floor. A static body's authored
+* value WINS the pair — restitution above 0 combines by Max, friction below
+* the default by Min and above it by Max — so the pad decides, whatever lands
+* on it. Left at the defaults, nothing changes for any existing scene.
+*/
 var StaticBody3D = class extends PhysicsBody3D {
 	static typeName = "StaticBody3D";
+	static props = {
+		friction: { default: .5 },
+		restitution: { default: 0 }
+	};
+	/** 0.5 plain · 0 ice (slides on and on) · 1+ glue. Away from 0.5 it wins the pair. */
+	friction = .5;
+	/** 0 dead · 1 trampoline. Above 0 it wins the pair: a dead ball still bounces. */
+	restitution = 0;
 };
 /** Sensor volume emitting `triggerEnter(other)` / `triggerExit(other)`. */
 var Area3D = class extends PhysicsBody3D {
@@ -2754,13 +2779,32 @@ var RigidBody3D = class extends PhysicsBody3D {
 			0,
 			0,
 			0
-		] }
+		] },
+		linearDamping: {
+			default: 0,
+			range: { min: 0 }
+		},
+		angularDamping: {
+			default: 0,
+			range: { min: 0 }
+		}
 	};
 	mass = 1;
 	gravityScale = 1;
 	fixedRotation = false;
 	friction = .5;
 	restitution = 0;
+	/**
+	* Drag, per second: velocity decays by `e^(-linearDamping·t)`. `0` = none.
+	* A body flying through nothing keeps its speed forever otherwise.
+	*/
+	linearDamping = 0;
+	/**
+	* Rolling resistance, per second, on the spin. Rapier has none by itself:
+	* friction only converts slip into spin, so a rolling ball is a wheel and a
+	* golf ball rolled to the edge of the world. `1`–`3` stops a ball on a green.
+	*/
+	angularDamping = 0;
 	/** m/s, y-up. Read back every step; write to launch. */
 	linearVelocity = [
 		0,
@@ -2815,7 +2859,8 @@ var CharacterBody3D = class extends PhysicsBody3D {
 		stepHeight: {
 			default: .35,
 			range: { min: 0 }
-		}
+		},
+		collideWithCharacters: { default: true }
 	};
 	/** m/s, y-up (up = +y). */
 	velocity = [
@@ -2837,6 +2882,16 @@ var CharacterBody3D = class extends PhysicsBody3D {
 	/** Max climbable slope angle. */
 	slopeLimitDeg = 45;
 	/**
+	* Whether OTHER characters are obstacles to this one. On (default), a
+	* character is a wall to every other character — Godot's answer, and what a
+	* few enemies want. Off, the controller ignores every other kinematic body
+	* and a crowd costs what the floor and the walls cost: eighty chasers around
+	* a player cost 64–286 ms a step with this on (each slide shape-casts
+	* against every neighbour, O(n²) in the crowd) and under a millisecond off.
+	* A survivor's horde overlaps itself and nobody minds.
+	*/
+	collideWithCharacters = true;
+	/**
 	* How high a step this body walks UP without jumping (0 = none).
 	*
 	* Rapier's character controller does not autostep unless asked, and nothing
@@ -3321,7 +3376,10 @@ var Water3D = class Water3D extends Node3D {
 		mirrorInterval: { default: 33 },
 		swellSteepness: { default: .35 },
 		foam: { default: true },
-		reflectivity: { default: null },
+		reflectivity: {
+			default: null,
+			kinds: ["null", "number"]
+		},
 		interaction: { default: true },
 		splash: { default: true },
 		sunDirection: { default: [
@@ -4739,11 +4797,23 @@ function moveBody(node, to, dt) {
 */
 var Chase = class extends Behavior {
 	static props = {
-		/** NodePath of the node to chase (resolved from THIS behavior's node). */
+		/** NodePath of the node to chase (resolved from THIS behavior's node). Optional beside `targetGroup`. */
 		target: {
 			default: "",
-			nodePath: true,
-			required: true
+			nodePath: true
+		},
+		/**
+		* The other way to name a target: the NEAREST member of this group, re-picked
+		* every `retargetEvery` seconds. `target: "%Player"` was the whole vocabulary,
+		* written for games with one hero — a guard in an RTS, a co-op, a survival
+		* game with allies could not chase "whichever of the six is closest".
+		* With no member in reach the chaser waits.
+		*/
+		targetGroup: { default: "" },
+		/** Seconds between nearest-of-group picks (`0` = every frame). */
+		retargetEvery: {
+			default: .25,
+			range: { min: 0 }
 		},
 		/** Units per second toward the target. */
 		speed: { default: 60 },
@@ -4753,20 +4823,46 @@ var Chase = class extends Behavior {
 		loseRange: { default: 0 },
 		/** Move the parent node instead of this one (AI-on-a-child pattern). */
 		moveParent: { default: false },
+		/**
+		* Chase along the GROUND — the target's height is not a direction.
+		*
+		* `null` (default) decides from the mover: a `CharacterBody3D` walks (the
+		* KCC's `slopeLimitDeg` and `stepHeight` say what it climbs, `stickToGround`
+		* keeps it on the surface), anything else — a 2D body, a plain node, a
+		* rigid body — chases in every axis. `true`/`false` overrides either way:
+		* a flying enemy on a kinematic capsule says `false`.
+		*
+		* Before this a chaser moved straight at `target.position` in all three
+		* axes, so a player on a ledge was met by enemies pushing diagonally up
+		* whatever face was in the way — a 70° cliff included — and the slope
+		* limit never got a say.
+		*/
+		ground: {
+			default: null,
+			kinds: ["null", "boolean"]
+		},
 		...FACING_PROPS
 	};
 	static signals = ["reachedTarget", "lostTarget"];
 	target = "";
+	targetGroup = "";
+	retargetEvery = .25;
 	speed = 60;
+	/** The group member currently chased (`targetGroup`), or null. */
+	picked = null;
+	sincePick = Number.POSITIVE_INFINITY;
 	stopRange = 0;
 	loseRange = 0;
 	moveParent = false;
+	ground = null;
 	facePath = "";
+	/** Signed fall speed accumulated while a ground chaser is off the floor. */
+	fall = 0;
 	turnSpeed = 100;
 	inRange = false;
 	lost = false;
 	onReady() {
-		if (this.target === "") throw new IncantoError("PROP_TYPE_MISMATCH", `Chase on '${this.node.getPath()}': "target" (a node path) is required.`, { prop: "target" });
+		if (this.target === "" && this.targetGroup === "") throw new IncantoError("PROP_TYPE_MISMATCH", `Chase on '${this.node.getPath()}': "target" (a node path) or "targetGroup" (a group name) is required.`, { prop: "target" });
 		if (this.moveParent) {
 			const parent = this.node.parent;
 			if (!parent || !hasPosition$1(parent)) throw new IncantoError("PROP_TYPE_MISMATCH", `Chase on '${this.node.getPath()}': "moveParent" needs a spatial parent (a Node2D/Node3D) to move. '${this.node.name}' has none.`, {
@@ -4775,12 +4871,66 @@ var Chase = class extends Behavior {
 			});
 		} else requirePosition(this);
 	}
+	/**
+	* A walker falls off what it walks off. `CharacterBody3D` applies no gravity
+	* of its own ("integrate velocity yourself"), and a chaser that ignores the
+	* target's height would otherwise walk off a ledge and keep its altitude —
+	* measured on tps-3d's 0.6 m Ramp, where the old chase glided down over five
+	* seconds only because the player happened to stand lower. Scene gravity
+	* (default 9.81), accumulated while `isOnFloor()` says no, reset when it says
+	* yes; the KCC's snap-to-ground handles the last 10 cm.
+	*/
+	fallStep(mover, dt) {
+		if (mover.isOnFloor?.() ?? true) {
+			this.fall = 0;
+			return 0;
+		}
+		const g = (this.node.tree?.engine?.scene?.physics?.gravity)?.[1] ?? (mover.position.length === 2 ? 980 : -9.81);
+		this.fall += g * dt;
+		return this.fall * dt;
+	}
+	/** Off the floor with nowhere to chase: still fall. */
+	dropIfAirborne(mover, dt) {
+		const drop = this.fallStep(mover, dt);
+		if (drop !== 0) {
+			const to = [...mover.position];
+			to[1] = (to[1] ?? 0) + drop;
+			moveBody(mover, to, dt);
+		}
+	}
+	/** The nearest live member of `targetGroup` — re-picked every `retargetEvery` seconds, never the mover itself. */
+	nearestOfGroup(mover, dt) {
+		this.sincePick += dt;
+		if (this.picked && this.picked.tree !== null && this.sincePick < this.retargetEvery) return this.picked;
+		this.sincePick = 0;
+		const here = worldPosition(mover);
+		let best = null;
+		let bestD = Number.POSITIVE_INFINITY;
+		for (const n of this.node.tree?.getNodesInGroup(this.targetGroup) ?? []) {
+			if (n === mover || n === this.node || !hasPosition$1(n)) continue;
+			const d = distance$1(here, worldPosition(n));
+			if (d < bestD) {
+				best = n;
+				bestD = d;
+			}
+		}
+		this.picked = best;
+		return best;
+	}
+	/** See `ground`: an explicit answer, else "is the mover a 3D kinematic capsule". */
+	walksTheGround(mover) {
+		if (this.ground !== null) return this.ground;
+		const kcc = mover;
+		return mover.position.length === 3 && typeof kcc.slopeLimitDeg === "number";
+	}
 	update(dt) {
 		const mover = this.moveParent ? this.node.parent : this.node;
 		if (!mover || !hasPosition$1(mover)) return;
-		const target = this.node.getNodeOrNull(this.target);
+		const target = this.targetGroup !== "" ? this.nearestOfGroup(mover, dt) : this.node.getNodeOrNull(this.target);
 		if (!target || !hasPosition$1(target)) return;
 		const targetPos = localFromWorld(mover, worldPosition(target));
+		const walks = this.walksTheGround(mover);
+		if (walks) targetPos[1] = mover.position[1] ?? 0;
 		const d = distance$1(mover.position, targetPos);
 		if (this.loseRange > 0 && d > this.loseRange) {
 			if (!this.lost) {
@@ -4788,6 +4938,7 @@ var Chase = class extends Behavior {
 				this.inRange = false;
 				this.emit("lostTarget");
 			}
+			if (walks) this.dropIfAirborne(mover, dt);
 			return;
 		}
 		this.lost = false;
@@ -4796,12 +4947,14 @@ var Chase = class extends Behavior {
 				this.inRange = true;
 				this.emit("reachedTarget");
 			}
+			if (walks) this.dropIfAirborne(mover, dt);
 			return;
 		}
 		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, targetPos, Math.max(0, step));
+		if (walks) position[1] = (position[1] ?? 0) + this.fallStep(mover, dt);
 		moveBody(mover, position, dt);
 		if (this.facePath !== "") {
 			const skin = this.node.getNodeOrNull(this.facePath);
@@ -4810,6 +4963,59 @@ var Chase = class extends Behavior {
 	}
 };
 //#endregion
+//#region src/gameplay/checkpoint.ts
+/**
+* A checkpoint: touch it and a `Respawn` puts you back HERE from now on.
+*
+* Sits on an `Area2D`/`Area3D` (listens to `triggerEnter`). `respawn` names the
+* `Respawn` node whose `to` becomes this checkpoint's world position, less
+* `dropBelow` so the character lands ON the flag rather than inside it.
+* `group` gates who can light it; `once` (default) lights it a single time.
+* Emits `activated(other)`.
+*
+* Built after a platformer built from the tarball wrote exactly this in nine
+* lines — the ninth being the one that found `Respawn.to` was read once at
+* ready. A checkpoint is the second most common thing a platformer has, and it
+* should be one node with two props, not a behaviour every game rewrites.
+*/
+var Checkpoint = class extends Behavior {
+	static props = {
+		/** Node path of the `Respawn` to redirect. */
+		respawn: {
+			default: "",
+			nodePath: true,
+			required: true
+		},
+		/** Only nodes in this group light it ('' = anything). */
+		group: { default: "player" },
+		/** Light it once; false re-fires `activated` on every entry. */
+		once: { default: true },
+		/** How far below the checkpoint's origin the respawn point sits. */
+		dropBelow: { default: 0 }
+	};
+	static signals = ["activated"];
+	respawn = "";
+	group = "player";
+	once = true;
+	dropBelow = 0;
+	/** True after the first activation. */
+	lit = false;
+	onReady() {
+		this.node.on("triggerEnter", (other) => {
+			const who = other;
+			if (this.group !== "" && !who.isInGroup(this.group)) return;
+			if (this.once && this.lit) return;
+			const catcher = this.node.getNodeOrNull(this.respawn);
+			if (!catcher || !Array.isArray(catcher.to)) return;
+			const to = [...worldPosition(this.node)];
+			if (to.length >= 2) to[1] = (to[1] ?? 0) - this.dropBelow;
+			catcher.to = to;
+			this.lit = true;
+			this.emit("activated", who);
+		});
+	}
+};
+//#endregion
 //#region src/gameplay/clickable.ts
 /**
 * Click and hover THIS node — the mouse as gameplay input.
@@ -5204,6 +5410,17 @@ var Health = class extends Behavior {
 		if (this.invulnerableFor > 0) this.invulnTimer = this.invulnerableFor;
 		if (this.current <= 0) this.die();
 	}
+	/**
+	* Be immune for `seconds` from NOW — a dodge roll, a spawn, a cutscene.
+	*
+	* `invulnerableFor` grants i-frames only AFTER a hit; this is the window
+	* before one. It extends a window already open and never shortens it, so a
+	* second dodge mid-window cannot expose you. Dead or not, it is harmless.
+	*/
+	protect(seconds) {
+		if (requireNumber(seconds, this.node, "Health.protect") < 0) throw new IncantoError("PROP_TYPE_MISMATCH", `Health.protect on '${this.node.getPath()}': seconds must be >= 0, got ${seconds}.`);
+		this.invulnTimer = Math.max(this.invulnTimer, seconds);
+	}
 	/** Restore `n` hit points (clamped to `max`). No-op when dead. Emits `healed`. */
 	heal(n) {
 		if (this.dead || requireNumber(n, this.node, "Health.heal") <= 0) return;
@@ -5351,8 +5568,10 @@ function onTriggerEnter(behavior, fn) {
 *   whose Health-owner node is in that group takes damage. This is how you stop
 *   enemies killing each other — give the player's weapon `targetGroup:'enemy'`
 *   and each enemy's contact hitbox `targetGroup:'player'`.
-* - `oncePerTarget` (default) prevents re-hitting the same node (a stationary
-*   hazard would otherwise drain a resting body every frame).
+* - `oncePerTarget` (default) prevents re-hitting the same node WHILE it stays
+*   in contact (a stationary hazard would otherwise drain a resting body every
+*   frame). It is per overlap, not per lifetime: leave and come back, or disarm
+*   the hitbox and arm it again over the same foe, and the hit lands again.
 * - `repeatEvery` (seconds, 0 = off) re-damages targets that STAY overlapped —
 *   lava pools, poison clouds, an enemy standing on you. Contact events fire
 *   only on entry/exit; this is the "and it keeps hurting" knob.
@@ -5396,6 +5615,7 @@ var DamageOnContact = class extends Behavior {
 		});
 		this.node.on("triggerExit", (other) => {
 			this.inside.delete(other);
+			this.hit.delete(other);
 		});
 	}
 	update(dt) {
@@ -6161,13 +6381,15 @@ var GameFlow = class GameFlow extends Behavior {
 		this.engine.timeScale = 1;
 	}
 	update() {
+		const pausePressed = this.readAction("pauseAction", "The pause key will do nothing.");
+		const restartPressed = this.readAction("restartAction", "The restart key will do nothing.");
 		if (this.state === "playing" || this.state === "paused") {
-			if (this.readAction("pauseAction", "The pause key will do nothing.")) if (this.state === "playing") this.pause();
+			if (pausePressed) if (this.state === "playing") this.pause();
 			else this.resume();
 			return;
 		}
 		if (this.state !== "gameover" && this.state !== "won") return;
-		if (this.readAction("restartAction", "The restart key will do nothing.")) this.restart();
+		if (restartPressed) this.restart();
 	}
 };
 /** The `HudLayer` a widget lives on, or null. */
@@ -6209,24 +6431,63 @@ var Interactable = class extends Behavior {
 		/** Maximum distance an actor may be to interact. */
 		range: { default: 2 },
 		/** Only nodes in this group can interact. */
-		actorGroup: { default: "player" }
+		actorGroup: { default: "player" },
+		/** What the actor sees on it — `Open drawer`. Read by whoever draws the "[E] …" prompt. */
+		prompt: { default: "" },
+		/**
+		* Which Interactable answers a press when several are in range. `any`:
+		* every one of them (the old rule). `nearest`: only the closest to the
+		* actor. `facing`: the closest inside `coneDeg` of the current camera's
+		* forward — the one the player is LOOKING at, pitch included, so a note
+		* on the desk and the drawer under it are two different looks (with no
+		* camera, the same as `nearest`).
+		*/
+		focus: {
+			default: "any",
+			options: [
+				"any",
+				"nearest",
+				"facing"
+			]
+		},
+		/** Full width of the `facing` cone, degrees — a generous crosshair. */
+		coneDeg: {
+			default: 40,
+			range: {
+				min: 1,
+				max: 360
+			}
+		}
 	};
-	static signals = ["interacted"];
+	static signals = [
+		"interacted",
+		"focused",
+		"unfocused"
+	];
 	action = "interact";
 	range = 2;
 	actorGroup = "player";
+	prompt = "";
+	focus = "any";
+	coneDeg = 40;
+	/**
+	* The actor this Interactable would answer RIGHT NOW, or null — updated every
+	* frame, with `focused(actor)` / `unfocused(actor)` on the edges. A HUD reads
+	* the focused one's `prompt`.
+	*/
+	focusedBy = null;
 	/** 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 (!tolerateUnknownAction({
+		const pressed = 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;
+		}, this.action, () => engine.input.justPressed(this.action), false);
 		if (!hasPosition(this.node)) return;
 		const self = worldPosition(this.node);
 		let nearest = null;
@@ -6240,9 +6501,89 @@ var Interactable = class extends Behavior {
 				nearestDist = d;
 			}
 		}
-		if (nearest) this.emit("interacted", nearest);
+		let holder = nearest;
+		if (holder && this.focus !== "any" && !this.claims(holder, self)) holder = null;
+		if (holder !== this.focusedBy) {
+			const was = this.focusedBy;
+			this.focusedBy = holder;
+			if (was) this.emit("unfocused", was);
+			if (holder) this.emit("focused", holder);
+		}
+		if (!pressed || !holder) return;
+		this.emit("interacted", holder);
+	}
+	/** Is THIS the Interactable `actor` means — the nearest (that it faces) of every one in reach? */
+	claims(actor, self) {
+		const eye = this.focus === "facing" ? cameraEye(this.node.getRoot()) : null;
+		const from = eye ? eye.at : worldPosition(actor);
+		const inCone = (target) => {
+			if (!eye) return true;
+			const dx = (target[0] ?? 0) - (from[0] ?? 0);
+			const dy = (target[1] ?? 0) - (from[1] ?? 0);
+			const dz = (target[2] ?? 0) - (from[2] ?? 0);
+			const len = Math.hypot(dx, dy, dz);
+			if (len < 1e-6) return true;
+			return dx / len * eye.fx + dy / len * eye.fy + dz / len * eye.fz >= Math.cos(this.coneDeg / 2 * (Math.PI / 180));
+		};
+		if (!inCone(self)) return false;
+		const mine = distance(from, self);
+		for (const other of interactablesIn(this.node.getRoot())) {
+			if (other === this || other.focus === "any" || other.actorGroup !== this.actorGroup) continue;
+			if (!hasPosition(other.node)) continue;
+			const there = worldPosition(other.node);
+			if (distance(worldPosition(actor), there) > other.range) continue;
+			if (!inCone(there)) continue;
+			if (distance(from, there) < mine) return false;
+		}
+		return true;
 	}
 };
+/** Every Interactable in the tree — walked on demand, only while an actor is in reach of one. */
+function interactablesIn(root) {
+	const out = [];
+	const walk = (n) => {
+		if (n.behavior instanceof Interactable) out.push(n.behavior);
+		for (const c of n.children) walk(c);
+	};
+	walk(root);
+	return out;
+}
+/**
+* Where the current camera is and which way it looks, or null when the tree
+* has no `Camera3D` (a 2D scene — `facing` then means `nearest`). Forward is
+* the camera's -z through its Euler XYZ rotation: the third basis column
+* negated, `(-sin ry, sin rx·cos ry, -cos rx·cos ry)`.
+*/
+function cameraEye(root) {
+	let first = null;
+	let current = null;
+	const walk = (n) => {
+		if (n.constructor.typeName === "Camera3D") {
+			first ??= n;
+			if (n.current) current ??= n;
+		}
+		for (const c of n.children) walk(c);
+	};
+	walk(root);
+	const cam = current ?? first;
+	if (!cam) return null;
+	const rot = cam.rotation ?? [
+		0,
+		0,
+		0
+	];
+	const rx = (rot[0] ?? 0) * Math.PI / 180;
+	const ry = (rot[1] ?? 0) * Math.PI / 180;
+	const fx = -Math.sin(ry);
+	const fy = Math.sin(rx) * Math.cos(ry);
+	const fz = -Math.cos(rx) * Math.cos(ry);
+	return {
+		at: worldPosition(cam),
+		fx,
+		fy,
+		fz
+	};
+}
 function collectGroup(node, group) {
 	const out = [];
 	const walk = (n) => {
@@ -6703,11 +7044,14 @@ var PathFollow = class extends Behavior {
 	static signals = ["waypointReached", "arrived"];
 	static props = {
 		speed: { default: 120 },
-		loop: { default: false }
+		loop: { default: false },
+		/** Move the parent node instead of this one — the AI-on-a-child pattern `Chase`/`Patrol`/`Wander` share. */
+		moveParent: { default: false }
 	};
 	/** Units per second (px in 2D, meters in 3D). */
 	speed = 120;
 	loop = false;
+	moveParent = false;
 	waypoints = [];
 	index = 0;
 	/** True while there is somewhere left to go. */
@@ -6725,24 +7069,37 @@ var PathFollow = class extends Behavior {
 	}
 	update(dt) {
 		if (!this.moving) return;
-		const node = requirePosition(this);
+		const node = this.mover();
 		let budget = this.speed * dt;
+		let at = [...node.position];
 		while (budget > 0 && this.index < this.waypoints.length) {
 			const target = this.waypoints[this.index];
-			const step = moveToward(node.position, target, budget);
-			const travelled = distanceBetween(node.position, step.position);
-			node.position = step.position;
+			const step = moveToward(at, target, budget);
+			const travelled = distanceBetween(at, step.position);
+			at = step.position;
 			budget -= travelled;
 			if (step.reached) {
 				this.node.emit("waypointReached", this.index);
 				this.index += 1;
 				if (this.index >= this.waypoints.length) if (this.loop && this.waypoints.length > 1) this.index = 0;
 				else {
+					moveBody(node, at, dt);
 					this.node.emit("arrived");
 					return;
 				}
-			} else return;
+			} else break;
 		}
+		moveBody(node, at, dt);
+	}
+	/** The node this walks: the parent under `moveParent`, else this one — both must be spatial. */
+	mover() {
+		if (!this.moveParent) return requirePosition(this);
+		const parent = this.node.parent;
+		if (!parent || !hasPosition$1(parent)) throw new IncantoError("PROP_TYPE_MISMATCH", `PathFollow on '${this.node.getPath()}': "moveParent" needs a spatial parent (a Node2D/Node3D) to move.`, {
+			prop: "moveParent",
+			path: this.node.getPath()
+		});
+		return parent;
 	}
 };
 function distanceBetween(a, b) {
@@ -7120,8 +7477,21 @@ var Projectile = class extends Behavior {
 		/** Units per second along `direction`. */
 		speed: { default: 300 },
 		/** A vector ([x,y(,z)]) OR the string 'forward' (null = 'forward', from rotation). */
-		direction: { default: null },
-		/** Constant +y (downward, 2D y-down) acceleration; 0 = straight line. */
+		direction: {
+			default: null,
+			kinds: [
+				"null",
+				"array",
+				"string"
+			]
+		},
+		/**
+		* Constant DOWNWARD acceleration in the scene's own convention — +y in 2D
+		* (y-down), −y in 3D (y-up) — so `9.81` pulls a 3D lob down. It used to add
+		* to +y regardless, the 2D convention, and `9.81` in a y-up scene LIFTED the
+		* shot (measured: 19 m up at 1.5 s); `Chase.ground` signs its fall the same
+		* way. 0 = straight line.
+		*/
 		gravity: { default: 0 }
 	};
 	static signals = [];
@@ -7180,7 +7550,7 @@ var Projectile = class extends Behavior {
 	update(dt) {
 		if (!this.armed) this.aim();
 		const node = this.node;
-		if (this.gravity !== 0) this.fall += this.gravity * dt;
+		if (this.gravity !== 0) this.fall += this.gravity * dt * (node.position.length === 3 ? -1 : 1);
 		const pos = node.position;
 		const n = Math.max(pos.length, this.velocity.length);
 		const next = new Array(n);
@@ -7429,6 +7799,17 @@ var ScoreKeeper = class extends Behavior {
 	scoreToWin = 0;
 	hasWon = false;
 	hasLost = false;
+	/**
+	* Whether the run is over — readable, not only heard. A stealth yard's HUD
+	* and a melee arena's both read `score.won` for their banner and got
+	* `undefined`, silently, because only the signals were public.
+	*/
+	get won() {
+		return this.hasWon;
+	}
+	get lost() {
+		return this.hasLost;
+	}
 	onReady() {
 		if (this.lives < 0) throw new IncantoError("PROP_TYPE_MISMATCH", `ScoreKeeper on '${this.node.getPath()}': "lives" must be >= 0, got ${this.lives}.`, { prop: "lives" });
 		if (this.scoreToWin < 0) throw new IncantoError("PROP_TYPE_MISMATCH", `ScoreKeeper on '${this.node.getPath()}': "scoreToWin" must be >= 0, got ${this.scoreToWin}.`, { prop: "scoreToWin" });
@@ -7563,8 +7944,12 @@ var SpawnSource = class {
 	*/
 	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);
+		const at = opts?.at ?? [];
+		const under = opts?.parent ?? this.behavior.node;
+		if (hasPosition$1(clone) && (at.length > 0 || under !== this.behavior.node)) {
+			const origin = under === this.behavior.node || !hasPosition$1(this.behavior.node) ? [] : sub(worldPosition(this.behavior.node), worldPosition(under));
+			clone.position = add(origin, at.length > 0 ? at : zeros(origin.length || clone.position.length));
+		}
 		if (typeof clone.visible === "boolean") clone.visible = true;
 		(opts?.parent ?? this.behavior.node).addChild(clone);
 		return clone;
@@ -7593,6 +7978,15 @@ function absolutePrefabPath(node, prefab) {
 	}
 	return parts.join("/");
 }
+function sub(a, b) {
+	const n = Math.max(a.length, b.length);
+	const out = [];
+	for (let i = 0; i < n; i++) out.push((a[i] ?? 0) - (b[i] ?? 0));
+	return out;
+}
+function zeros(n) {
+	return Array.from({ length: n }, () => 0);
+}
 //#endregion
 //#region src/gameplay/spawner.ts
 /**
@@ -7626,7 +8020,17 @@ var Spawner = class extends Behavior {
 		/** Begin ticking at ready. */
 		autoStart: { default: true },
 		/** Total LIFETIME spawns (0 = infinite). */
-		total: { default: 0 }
+		total: { default: 0 },
+		/**
+		* Where clones live: a node path, or '' for under the spawner itself. Clones
+		* of a spawner that MOVES ride along with it when they are its children —
+		* a gate a director slid to a new edge before each spawn dragged every
+		* enemy it had made — so a container makes the spawner just a place.
+		*/
+		into: {
+			default: "",
+			nodePath: true
+		}
 	};
 	static signals = ["spawned", "finished"];
 	prefab = "";
@@ -7635,6 +8039,7 @@ var Spawner = class extends Behavior {
 	at = [];
 	autoStart = true;
 	total = 0;
+	into = "";
 	source = new SpawnSource(this);
 	template;
 	live = /* @__PURE__ */ new Set();
@@ -7657,6 +8062,7 @@ var Spawner = class extends Behavior {
 	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);
+		if (this.into !== "") this.node.getNode(this.into);
 		this.running = this.autoStart;
 		this.timer = this.interval;
 	}
@@ -7674,7 +8080,11 @@ var Spawner = class extends Behavior {
 		this.prune();
 		if (this.done) return null;
 		if (this.max > 0 && this.live.size >= this.max) return null;
-		const clone = this.source.spawn(this.template, this.at.length > 0 ? { at: this.at } : void 0);
+		const parent = this.into === "" ? void 0 : this.node.getNode(this.into);
+		const clone = this.source.spawn(this.template, this.at.length > 0 || parent ? {
+			at: this.at,
+			parent
+		} : void 0);
 		this.live.add(clone);
 		this.spawnedCount += 1;
 		this.emit("spawned", clone);
@@ -7698,6 +8108,140 @@ var Spawner = class extends Behavior {
 	}
 };
 //#endregion
+//#region src/gameplay/turret.ts
+/**
+* The oldest verb in games: pick the nearest live member of `targetGroup`
+* within `range` and hit it every `cooldown` — a defense tower, a ship's gun,
+* a sentry, a trooper who fights what he meets.
+*
+* Two games in a row wrote these forty lines before it existed (an RTS's
+* trooper, a tower defense's tower): the engine had `Chase` for going TO a
+* target and `Projectile` for the bullet, and nothing that decides to shoot.
+*
+* - **Hitscan** by default: the target's `Health` (on it or a child, as
+*   `DamageOnContact` finds it) takes `damage(n)`.
+* - **Or a clone**: name a `shelf` (a `PrefabShelf`) and a `prefab` on it; each
+*   shot takes one, puts it at the turret plus `muzzle`, points its
+*   `Projectile` at the target and adds it under `into` (the turret's parent
+*   when empty). The clone does the hurting then — give it `DamageOnContact`.
+* - `facePath` turns a barrel toward the target at `turnSpeed`.
+*
+* Signals: `acquired(target)` when something comes in range, `fired(target)`
+* per shot, `lost()` when nothing live is in range any more.
+*/
+var Turret = class extends Behavior {
+	static props = {
+		/** Who it shoots: the nearest live member of this group. */
+		targetGroup: { default: "enemy" },
+		/** How far it reaches, in the scene's units. */
+		range: {
+			default: 6,
+			range: { min: 0 }
+		},
+		/** Hitscan damage per shot (ignored when a `prefab` does the hurting). */
+		damage: { default: 10 },
+		/** Seconds between shots. */
+		cooldown: {
+			default: .6,
+			range: { min: 0 }
+		},
+		/** A `PrefabShelf` to take each shot from (empty = hitscan). */
+		shelf: {
+			default: "",
+			nodePath: true
+		},
+		/** The template on that shelf. */
+		prefab: { default: "" },
+		/** Where clones start, relative to the turret. */
+		muzzle: { default: [] },
+		/** Where clones go; empty = the turret's parent. */
+		into: {
+			default: "",
+			nodePath: true
+		},
+		...FACING_PROPS
+	};
+	static signals = [
+		"acquired",
+		"fired",
+		"lost"
+	];
+	targetGroup = "enemy";
+	range = 6;
+	damage = 10;
+	cooldown = .6;
+	shelf = "";
+	prefab = "";
+	muzzle = [];
+	into = "";
+	facePath = "";
+	turnSpeed = 100;
+	/** What it is shooting at right now, or null. */
+	target = null;
+	/** Shots fired so far. */
+	shots = 0;
+	wait = 0;
+	onReady() {
+		if (this.shelf === "" !== (this.prefab === "")) throw new IncantoError("PROP_TYPE_MISMATCH", `Turret on '${this.node.getPath()}': "shelf" and "prefab" go together — name both for a projectile, neither for hitscan.`, {
+			prop: this.shelf === "" ? "shelf" : "prefab",
+			path: this.node.getPath()
+		});
+	}
+	update(dt) {
+		this.wait = Math.max(0, this.wait - dt);
+		if (!hasPosition$1(this.node)) return;
+		const here = worldPosition(this.node);
+		let best = null;
+		let bestD = this.range;
+		for (const n of this.node.tree?.getNodesInGroup(this.targetGroup) ?? []) {
+			if (n === this.node || !hasPosition$1(n)) continue;
+			if (findHealth(n)?.health.isDead) continue;
+			const d = distance$1(here, worldPosition(n));
+			if (d <= bestD) {
+				best = n;
+				bestD = d;
+			}
+		}
+		if (best !== this.target) {
+			const had = this.target;
+			this.target = best;
+			if (best) this.emit("acquired", best);
+			else if (had) this.emit("lost");
+		}
+		if (!best) return;
+		const dir = worldPosition(best).map((v, i) => v - (here[i] ?? 0));
+		if (this.facePath !== "") {
+			const barrel = this.node.getNodeOrNull(this.facePath);
+			if (barrel) faceTravel(barrel, dir, dt, this.turnSpeed);
+		}
+		if (this.wait > 0) return;
+		this.wait = this.cooldown;
+		this.shots += 1;
+		if (this.shelf !== "") this.launch(best, here, dir);
+		else findHealth(best)?.health.damage(this.damage);
+		this.emit("fired", best);
+	}
+	/** One clone from the shelf, at the muzzle, aimed at the target, into the container. */
+	launch(target, here, dir) {
+		const shelf = this.node.getNodeOrNull(this.shelf)?.behavior;
+		if (!shelf || typeof shelf.make !== "function") throw new IncantoError("NODE_NOT_FOUND", `Turret on '${this.node.getPath()}': "shelf" '${this.shelf}' is not a PrefabShelf.`, {
+			prop: "shelf",
+			path: this.node.getPath()
+		});
+		const clone = shelf.make(this.prefab);
+		if (!hasPosition$1(clone)) return;
+		const container = this.into !== "" ? this.node.getNodeOrNull(this.into) : this.node.parent;
+		if (!container) return;
+		const len = Math.hypot(...dir) || 1;
+		const unit = dir.map((v) => v / len);
+		const containerAt = hasPosition$1(container) ? worldPosition(container) : here.map(() => 0);
+		clone.position = here.map((v, i) => v + (this.muzzle[i] ?? 0) - (containerAt[i] ?? 0));
+		const shot = clone.behavior;
+		if (shot && "direction" in shot) shot.direction = unit;
+		container.addChild(clone);
+	}
+};
+//#endregion
 //#region src/gameplay/wander.ts
 /**
 * Aimless roaming inside a circle around the spawn point — idle critters,
@@ -7793,6 +8337,14 @@ var WaveSpawner = class extends Behavior {
 	parsed = [];
 	live = /* @__PURE__ */ new Set();
 	waveIndex = -1;
+	/** The wave now running or being cleared, 1-based — what a HUD prints as `wave 2 / 5`. `0` before the first. */
+	get wave() {
+		return this.waveIndex < 0 ? 0 : Math.min(this.parsed.length, this.waveIndex + 1);
+	}
+	/** How many waves were declared. */
+	get waveCount() {
+		return this.parsed.length;
+	}
 	phase = "idle";
 	timer = 0;
 	spawnedThisWave = 0;
@@ -8105,6 +8657,8 @@ const GAMEPLAY_BEHAVIORS = {
 	PathFollow,
 	Health,
 	Lifetime,
+	Checkpoint,
+	Turret,
 	ScoreKeeper,
 	Currency,
 	Pickup,
@@ -8138,4 +8692,4 @@ function registerGameplayBehaviors(opts) {
 	for (const [name, ctor] of Object.entries(GAMEPLAY_BEHAVIORS)) registerBehavior(name, ctor, { replace });
 }
 //#endregion
-export { DayNight as A, rejectScale as B, goToScene as C, effectRng as D, FollowCamera as E, Collector as F, StaticBody3D as G, CharacterBody3D as H, Chase as I, createCausticsQuad as J, Node3D as K, Water3D as L, DamageOnContact as M, Health as N, FloatAway as O, Currency as P, worldPosition as Q, WATER_CUTOUT_MAX as R, GameFlow as S, tolerateUnknownAction as T, PhysicsBody3D as U, Area3D as V, RigidBody3D as W, colliderFootDrop as X, WATER_MAX_RIPPLES as Y, localFromWorld as Z, CameraShake as _, Wander as a, screenFlash as b, SavePoint as c, Pickup as d, Patrol as f, Lifetime as g, MoveTo as h, WaveSpawner as i, phaseOf as j, FaceTarget as k, Projectile as l, Oscillate as m, registerGameplayBehaviors as n, Spawner as o, PathFollow as p, validateCollider3D as q, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, PrefabShelf as u, Cooldown as v, restartScene as w, Interactable as x, hitStop as y, WaterCutout3D as z };
+export { localFromWorld as $, FaceTarget as A, WATER_CUTOUT_MAX as B, GameFlow as C, FollowCamera as D, tolerateUnknownAction as E, Currency as F, PhysicsBody3D as G, rejectScale as H, Collector as I, Node3D as J, RigidBody3D as K, Checkpoint as L, phaseOf as M, DamageOnContact as N, effectRng as O, Health as P, colliderFootDrop as Q, Chase as R, Interactable as S, restartScene as T, Area3D as U, WaterCutout3D as V, CharacterBody3D as W, createCausticsQuad as X, validateCollider3D as Y, WATER_MAX_RIPPLES as Z, Lifetime as _, Wander as a, hitStop as b, ScoreKeeper as c, PrefabShelf as d, worldPosition as et, Pickup as f, MoveTo as g, Oscillate as h, WaveSpawner as i, DayNight as j, FloatAway as k, SavePoint as l, PathFollow as m, registerGameplayBehaviors as n, Turret as o, Patrol as p, StaticBody3D as q, ZombieAI as r, Spawner as s, GAMEPLAY_BEHAVIORS as t, Projectile as u, CameraShake as v, goToScene as w, screenFlash as x, Cooldown as y, Water3D as z };