incanto 0.1.0

package/dist/gameplay-Ccruc3Wd.js

@@ -0,0 +1,1501 @@
+import { _ as registerBehavior, m as Behavior } from "./loader-CGs_G-r0.js";
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { t as duplicateNode } from "./duplicate-DP2WPYom.js";
+//#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;
+}
+/** Component-wise `a - b`. */
+function sub(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 delta = sub(to, from);
+	const dist = length(delta);
+	if (dist <= maxStep || dist === 0) return {
+		position: [...to],
+		reached: true
+	};
+	const f = maxStep / dist;
+	return {
+		position: from.map((c, i) => c + (delta[i] ?? 0) * f),
+		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);
+}
+//#endregion
+//#region src/gameplay/chase.ts
+/**
+* Home in on a target node — the workhorse enemy AI. Each frame moves toward
+* `target.position` at `speed`, stopping once within `stopRange` (melee reach).
+* Dimension-agnostic.
+*
+* - `reachedTarget` fires once when it first enters `stopRange` (re-arms after
+*   it leaves), so wire it to an attack.
+* - `loseRange` (>0) gives up the chase when the target gets that far away,
+*   emitting `lostTarget` once.
+* - `moveParent` (default false) moves the parent node instead of this one.
+*   A node carries ONE behavior, so an enemy whose ROOT must hold `Health`
+*   (e.g. for `Health.freeOnDeath` clone-safe cleanup) puts `Chase` on a CHILD
+*   and sets `moveParent:true` — the AI child drives the whole entity. Distance
+*   is measured from the moved node (the parent).
+*/
+var Chase = class extends Behavior {
+	static props = {
+		/** NodePath of the node to chase (resolved from THIS behavior's node). */
+		target: { default: "" },
+		/** Units per second toward the target. */
+		speed: { default: 60 },
+		/** Stop (and emit reachedTarget) when within this distance. */
+		stopRange: { default: 0 },
+		/** Give up (emit lostTarget) beyond this distance (0 = never lose). */
+		loseRange: { default: 0 },
+		/** Move the parent node instead of this one (AI-on-a-child pattern). */
+		moveParent: { default: false }
+	};
+	static signals = ["reachedTarget", "lostTarget"];
+	target = "";
+	speed = 60;
+	stopRange = 0;
+	loseRange = 0;
+	moveParent = false;
+	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.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.`, {
+				prop: "moveParent",
+				path: this.node.getPath()
+			});
+		} else requirePosition(this);
+	}
+	update(dt) {
+		const mover = this.moveParent ? this.node.parent : this.node;
+		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);
+		if (this.loseRange > 0 && d > this.loseRange) {
+			if (!this.lost) {
+				this.lost = true;
+				this.inRange = false;
+				this.emit("lostTarget");
+			}
+			return;
+		}
+		this.lost = false;
+		if (this.stopRange > 0 && d <= this.stopRange) {
+			if (!this.inRange) {
+				this.inRange = true;
+				this.emit("reachedTarget");
+			}
+			return;
+		}
+		this.inRange = false;
+		const step = Math.min(this.speed * dt, this.stopRange > 0 ? d - this.stopRange : d);
+		const { position } = moveToward(mover.position, target.position, Math.max(0, step));
+		mover.position = position;
+	}
+};
+//#endregion
+//#region src/gameplay/collector.ts
+/**
+* A tally for the "collect N things" pattern, living on the collector itself
+* (usually the player). Adds its node to `group` at ready so Pickups whose
+* `collectorGroup` matches will count it as a collector.
+*
+* Wire a Pickup's `collected(value, other) → Collector.collect` (the value is
+* the first arg) — `total` accumulates and `totalChanged(total)` fires.
+* (Pickup also notifies a global ScoreKeeper; Collector is the per-actor tally,
+* e.g. for split-screen or "each player's coins".)
+*/
+var Collector = class extends Behavior {
+	static props = { 
+	/** Group this collector joins (Pickups match this against `collectorGroup`). */
+group: { default: "player" } };
+	static signals = ["totalChanged"];
+	group = "player";
+	/** Running sum of collected values. */
+	total = 0;
+	onReady() {
+		this.node.addToGroup(this.group);
+	}
+	/** Add `value` to the tally and emit `totalChanged`. */
+	collect(value) {
+		this.total += value;
+		this.emit("totalChanged", this.total);
+	}
+};
+//#endregion
+//#region src/gameplay/health.ts
+/**
+* Hit points with regeneration and post-hit invulnerability (i-frames) —
+* the universal "this thing can be hurt and can die" behavior.
+*
+* Other behaviors hurt it through `damage(n)` (e.g. `DamageOnContact` finds a
+* target's Health and calls it); games heal/kill via `heal(n)` / `kill()`.
+* Wire its `died` signal to a `ScoreKeeper.loseLife`, a respawn, etc.
+*
+* `freeOnDeath` (default false) `queueFree()`s the Health node itself when it
+* dies. Because it is NODE-LOCAL it clones perfectly — this is THE way to free
+* dying SPAWNED entities. Scene-level `connections` (e.g. `died → queueFree`)
+* are NOT copied onto Spawner/WaveSpawner clones, so a `died` connection only
+* ever wires the template, never the live clones; `freeOnDeath` needs no
+* connection and so works on every clone.
+*
+* Dimension-agnostic: no node geometry, just numbers — testable headlessly.
+*/
+var Health = class extends Behavior {
+	static props = {
+		/** Maximum hit points; `current` starts here. */
+		max: { default: 100 },
+		/** Hit points regained per second (0 = no regen). */
+		regenPerSec: { default: 0 },
+		/** 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 }
+	};
+	static signals = [
+		"damaged",
+		"healed",
+		"died"
+	];
+	max = 100;
+	regenPerSec = 0;
+	invulnerableFor = 0;
+	freeOnDeath = false;
+	/** Current hit points (set to `max` on ready). */
+	current = 0;
+	invulnTimer = 0;
+	dead = false;
+	/** True once `current` has hit 0 — `died` fires at most once per life. */
+	get isDead() {
+		return this.dead;
+	}
+	/** Seconds of i-frames remaining (0 = vulnerable). */
+	get invulnerableRemaining() {
+		return this.invulnTimer;
+	}
+	onReady() {
+		if (!(this.max > 0)) throw new IncantoError("PROP_TYPE_MISMATCH", `Health on '${this.node.getPath()}': "max" must be > 0, got ${this.max}.`, { prop: "max" });
+		if (this.regenPerSec < 0) throw new IncantoError("PROP_TYPE_MISMATCH", `Health on '${this.node.getPath()}': "regenPerSec" must be >= 0, got ${this.regenPerSec}.`, { prop: "regenPerSec" });
+		if (this.invulnerableFor < 0) throw new IncantoError("PROP_TYPE_MISMATCH", `Health on '${this.node.getPath()}': "invulnerableFor" must be >= 0, got ${this.invulnerableFor}.`, { prop: "invulnerableFor" });
+		this.current = this.max;
+	}
+	update(dt) {
+		if (this.invulnTimer > 0) this.invulnTimer = Math.max(0, this.invulnTimer - dt);
+		if (this.regenPerSec > 0 && !this.dead && this.current < this.max) this.setCurrent(this.current + this.regenPerSec * dt);
+	}
+	/** Apply `n` damage. No-op while invulnerable or already dead. Emits `damaged`. */
+	damage(n) {
+		if (this.dead || n <= 0) return;
+		if (this.invulnTimer > 0) return;
+		this.setCurrent(this.current - n);
+		this.emit("damaged", n, this.current);
+		if (this.invulnerableFor > 0) this.invulnTimer = this.invulnerableFor;
+		if (this.current <= 0) this.die();
+	}
+	/** Restore `n` hit points (clamped to `max`). No-op when dead. Emits `healed`. */
+	heal(n) {
+		if (this.dead || n <= 0) return;
+		this.setCurrent(this.current + n);
+		this.emit("healed", n, this.current);
+	}
+	/** Drop to 0 and die immediately (ignores i-frames). */
+	kill() {
+		if (this.dead) return;
+		this.setCurrent(0);
+		this.die();
+	}
+	setCurrent(value) {
+		this.current = Math.max(0, Math.min(this.max, value));
+	}
+	die() {
+		if (this.dead) return;
+		this.dead = true;
+		this.current = 0;
+		this.emit("died");
+		if (this.freeOnDeath) this.node.queueFree();
+	}
+};
+//#endregion
+//#region src/gameplay/trigger.ts
+/**
+* Subscribe a behavior to its own node's `triggerEnter(other)` signal, after
+* asserting the node can actually emit it — Pickup/DamageOnContact must sit on
+* an Area2D/Area3D (or any node declaring the unified collision signals).
+* Fails loudly (the engine philosophy) instead of silently never firing.
+*/
+function onTriggerEnter(behavior, fn) {
+	const node = behavior.node;
+	if (!node.declaredSignalNames().includes("triggerEnter")) {
+		const behaviorName = behavior.constructor.name;
+		throw new IncantoError("UNKNOWN_SIGNAL", `${behaviorName} on '${node.getPath()}' needs a node that emits 'triggerEnter' — attach it to an Area2D/Area3D (or another body that declares the collision signals). '${node.name}' declares: [${node.declaredSignalNames().join(", ")}].`, {
+			signal: "triggerEnter",
+			path: node.getPath()
+		});
+	}
+	node.on("triggerEnter", (other) => fn(other));
+}
+//#endregion
+//#region src/gameplay/damage-on-contact.ts
+/**
+* Deals damage to whatever it touches — projectiles, spikes, lava, enemy
+* hitboxes. Must sit on an Area2D/Area3D (listens to `triggerEnter`).
+*
+* On overlap it finds the contacted entity's `Health` behavior (see
+* `findHealth` for the exact search order) and calls `damage(amount)`, then
+* emits `dealtDamage(amount, targetNode)`.
+*
+* - `targetGroup` (default '' = anything) gates who can be hurt: only a target
+*   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).
+* - `destroySelf` frees the hazard after a hit (single-use projectiles).
+*
+* SCORING PATTERN (clone-safe): wire the KILLER's `dealtDamage` →
+* `ScoreKeeper.addScore`. The weapon is usually a non-cloned node (it lives on
+* the player), so a scene connection on it survives — unlike a connection on a
+* spawned enemy, which never clones.
+*/
+var DamageOnContact = class extends Behavior {
+	static props = {
+		/** Hit points to remove per contact. */
+		amount: { default: 10 },
+		/** Only damage targets whose Health-owner is in this group ('' = any). */
+		targetGroup: { default: "" },
+		/** Damage each distinct target at most once. */
+		oncePerTarget: { default: true },
+		/** queueFree() this node after the first successful hit. */
+		destroySelf: { default: false }
+	};
+	static signals = ["dealtDamage"];
+	amount = 10;
+	targetGroup = "";
+	oncePerTarget = true;
+	destroySelf = false;
+	hit = /* @__PURE__ */ new WeakSet();
+	onReady() {
+		onTriggerEnter(this, (other) => this.tryDamage(other));
+	}
+	tryDamage(other) {
+		if (this.oncePerTarget && this.hit.has(other)) return;
+		const found = findHealth(other);
+		if (!found) return;
+		if (this.targetGroup !== "" && !found.owner.isInGroup(this.targetGroup)) return;
+		if (this.oncePerTarget) this.hit.add(other);
+		found.health.damage(this.amount);
+		this.emit("dealtDamage", this.amount, found.owner);
+		if (this.destroySelf) this.node.queueFree();
+	}
+};
+/**
+* Find the nearest `Health` to a contacted node and the node that owns it.
+*
+* A real entity rarely carries Health on the exact collider that overlaps: the
+* Area/Body arrangement usually delivers a different node than the one holding
+* the Health behavior (e.g. Health on the entity ROOT, the overlapping collider
+* a child `Hitbox` Area). The search, in order of nearness:
+*
+*   1. the contacted node itself, then its DESCENDANTS (breadth-first), then
+*   2. each ANCESTOR node in turn (climbing toward the entity root) — the
+*      ancestor NODE only, NOT its other subtrees.
+*
+* Step 2 deliberately never descends into an ancestor's *sibling* branches:
+* doing so let a hazard collider whose ancestor chain reaches the scene root
+* find — and damage — an unrelated entity on the far side of the level (the
+* scene root's subtree contains every entity). Health belongs on the contacted
+* collider's own subtree or on a direct ancestor (the entity root) — both of
+* which this covers without ever crossing into another entity.
+*
+* The first `Health` found wins; its node is returned as `owner` (used for the
+* `targetGroup` check and the `dealtDamage` target). Returns null when no Health
+* exists in the contacted node's own subtree or ancestor chain.
+*/
+function findHealth(node) {
+	const queue = [node];
+	while (queue.length > 0) {
+		const n = queue.shift();
+		if (n.behavior instanceof Health) return {
+			health: n.behavior,
+			owner: n
+		};
+		queue.push(...n.children);
+	}
+	for (let n = node.parent; n; n = n.parent) if (n.behavior instanceof Health) return {
+		health: n.behavior,
+		owner: n
+	};
+	return null;
+}
+//#endregion
+//#region src/gameplay/follow-camera.ts
+/**
+* Make the node it sits on chase a target's position — THE camera-follow
+* behavior. Put it on a `Camera2D`/`Camera3D` (whose `position` is the view
+* center/eye) and point `target` at the player; every frame the camera lerps
+* toward `target.position + offset`.
+*
+* Dimension-agnostic: works on `[x,y]` (2D) and `[x,y,z]` (3D) positions.
+*
+* - `smoothing` (0..1) is a per-frame retention factor: 0 = instant snap,
+*   0.85–0.95 = smooth drag (frame-rate independent at a 60fps reference).
+* - `deadzone` keeps the camera still until the target drifts that far from the
+*   desired point — no jitter when the player makes tiny moves.
+*/
+var FollowCamera = class extends Behavior {
+	static props = {
+		/** NodePath of the node to follow (relative to this node, or absolute). */
+		target: { default: "" },
+		/** Constant offset added to the target's position ([x,y] or [x,y,z]). */
+		offset: { default: [] },
+		/** 0..1 retention factor: 0 = snap, higher = smoother chase. */
+		smoothing: { default: 0 },
+		/** Don't move until the target is at least this far from the desired point. */
+		deadzone: { default: 0 }
+	};
+	static signals = [];
+	target = "";
+	offset = [];
+	smoothing = 0;
+	deadzone = 0;
+	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" });
+		requirePosition(this);
+	}
+	update(dt) {
+		const cam = this.node;
+		if (!hasPosition$1(cam)) return;
+		const target = cam.getNodeOrNull(this.target);
+		if (!target || !hasPosition$1(target)) return;
+		const desired = add(target.position, this.offset);
+		if (this.deadzone > 0 && distance$1(cam.position, desired) <= this.deadzone) return;
+		const f = smoothingFactor(this.smoothing, dt);
+		if (f >= 1) {
+			cam.position = [...desired];
+			return;
+		}
+		cam.position = cam.position.map((c, i) => c + ((desired[i] ?? c) - c) * f);
+	}
+};
+//#endregion
+//#region src/gameplay/interactable.ts
+function hasPosition(node) {
+	return Array.isArray(node.position);
+}
+/** Euclidean distance between two position arrays (works for 2D [x,y] and 3D [x,y,z]). */
+function distance(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);
+}
+/**
+* A proximity-gated "press to use" — doors, levers, chests, NPCs. Each frame,
+* if an actor in `actorGroup` is within `range` (distance on `position` arrays,
+* 2D or 3D) and the `action` input was just pressed, emits
+* `interacted(actor)` (the nearest in-range actor).
+*
+* Wire `interacted → YourBehavior.someMethod`, or read it from a connection.
+*/
+var Interactable = class extends Behavior {
+	static props = {
+		/** Input action (button) that triggers interaction. */
+		action: { default: "interact" },
+		/** Maximum distance an actor may be to interact. */
+		range: { default: 2 },
+		/** Only nodes in this group can interact. */
+		actorGroup: { default: "player" }
+	};
+	static signals = ["interacted"];
+	action = "interact";
+	range = 2;
+	actorGroup = "player";
+	update() {
+		const engine = this.node.tree?.engine;
+		if (!engine?.scene) return;
+		if (!engine.input.justPressed(this.action)) return;
+		if (!hasPosition(this.node)) return;
+		const self = this.node.position;
+		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);
+			if (d <= this.range && d < nearestDist) {
+				nearest = actor;
+				nearestDist = d;
+			}
+		}
+		if (nearest) this.emit("interacted", nearest);
+	}
+};
+function collectGroup(node, group) {
+	const out = [];
+	const walk = (n) => {
+		if (n.isInGroup(group)) out.push(n);
+		for (const c of n.children) walk(c);
+	};
+	walk(node);
+	return out;
+}
+//#endregion
+//#region src/gameplay/lifetime.ts
+/**
+* Self-destruct after a fixed time — bullets, particles, temporary spawns,
+* pickups that vanish. Accumulates `dt`; on elapse emits `expired` then
+* `queueFree()`s its node.
+*
+* With `startOnSignal: true` the countdown is armed manually via `startTimer()`
+* (wire a signal → `startTimer`), so the lifetime begins on an event rather
+* than at spawn.
+*/
+var Lifetime = class extends Behavior {
+	static props = {
+		/** Seconds before the node frees itself. */
+		seconds: { default: 1 },
+		/** Defer the countdown until `startTimer()` is called (default: start at ready). */
+		startOnSignal: { default: false }
+	};
+	static signals = ["expired"];
+	seconds = 1;
+	startOnSignal = false;
+	elapsed = 0;
+	running = false;
+	fired = false;
+	onReady() {
+		if (!(this.seconds > 0)) throw new IncantoError("PROP_TYPE_MISMATCH", `Lifetime on '${this.node.getPath()}': "seconds" must be > 0, got ${this.seconds}.`, { prop: "seconds" });
+		this.running = !this.startOnSignal;
+	}
+	/** Arm (or re-arm) the countdown from zero. */
+	startTimer() {
+		this.elapsed = 0;
+		this.fired = false;
+		this.running = true;
+	}
+	update(dt) {
+		if (!this.running || this.fired) return;
+		this.elapsed += dt;
+		if (this.elapsed >= this.seconds) {
+			this.fired = true;
+			this.running = false;
+			this.emit("expired");
+			this.node.queueFree();
+		}
+	}
+};
+//#endregion
+//#region src/gameplay/tween.ts
+const EASE_NAMES = [
+	"linear",
+	"easeIn",
+	"easeOut",
+	"easeInOut"
+];
+/**
+* Map normalized time `t` through an easing curve to an eased progress in
+* `[0,1]`. `t` is clamped to `[0,1]` so callers never overshoot:
+* - `linear` — constant speed
+* - `easeIn` — quadratic, slow start (`t²`)
+* - `easeOut` — quadratic, slow end (`1-(1-t)²`)
+* - `easeInOut` — slow start AND end (smooth in/out)
+*/
+function ease(curve, t) {
+	const x = t < 0 ? 0 : t > 1 ? 1 : t;
+	switch (curve) {
+		case "linear": return x;
+		case "easeIn": return x * x;
+		case "easeOut": return 1 - (1 - x) * (1 - x);
+		case "easeInOut": return x < .5 ? 2 * x * x : 1 - (-2 * x + 2) ** 2 / 2;
+	}
+}
+//#endregion
+//#region src/gameplay/move-to.ts
+/**
+* Tween the node from where it starts to a fixed `to` position over `duration`
+* seconds, through an easing curve — opening doors, sliding platforms, UI
+* pop-ins, scripted moves. Emits `arrived` once at the end.
+*
+* `startOnSignal: true` arms it manually via `start()` (wire a signal → `start`)
+* so the move plays on an event; otherwise it begins at ready. Dimension-
+* agnostic (`[x,y]` / `[x,y,z]`).
+*/
+var MoveTo = class extends Behavior {
+	static props = {
+		/** Destination position ([x,y] or [x,y,z]). */
+		to: { default: [] },
+		/** Seconds the move takes. */
+		duration: { default: 1 },
+		/** Easing curve. */
+		ease: {
+			default: "easeInOut",
+			options: [...EASE_NAMES]
+		},
+		/** Defer the move until start() is called (default: begin at ready). */
+		startOnSignal: { default: false }
+	};
+	static signals = ["arrived"];
+	to = [];
+	duration = 1;
+	ease = "easeInOut";
+	startOnSignal = false;
+	from = [];
+	elapsed = 0;
+	running = false;
+	arrivedFired = false;
+	onReady() {
+		if (!(this.duration > 0)) throw new IncantoError("PROP_TYPE_MISMATCH", `MoveTo on '${this.node.getPath()}': "duration" must be > 0, got ${this.duration}.`, { prop: "duration" });
+		if (!EASE_NAMES.includes(this.ease)) throw new IncantoError("PROP_TYPE_MISMATCH", `MoveTo on '${this.node.getPath()}': "ease" must be one of [${EASE_NAMES.join(", ")}], got '${this.ease}'.`, { prop: "ease" });
+		const node = requirePosition(this);
+		this.from = [...node.position];
+		if (!this.startOnSignal) this.running = true;
+	}
+	/** Begin (or restart) the move from the node's CURRENT position. */
+	start() {
+		const node = this.node;
+		this.from = [...node.position];
+		this.elapsed = 0;
+		this.arrivedFired = false;
+		this.running = true;
+	}
+	update(dt) {
+		if (!this.running) return;
+		const node = this.node;
+		this.elapsed += dt;
+		const t = Math.min(1, this.elapsed / this.duration);
+		const k = ease(this.ease, t);
+		node.position = this.from.map((c, i) => c + ((this.to[i] ?? c) - c) * k);
+		if (t >= 1 && !this.arrivedFired) {
+			this.arrivedFired = true;
+			this.running = false;
+			this.emit("arrived");
+		}
+	}
+};
+//#endregion
+//#region src/gameplay/oscillate.ts
+const AXES = [
+	"x",
+	"y",
+	"z"
+];
+const MODES = [
+	"position",
+	"rotation",
+	"scale"
+];
+const AXIS_INDEX = {
+	x: 0,
+	y: 1,
+	z: 2
+};
+/**
+* Continuous sine motion around a value — floating platforms, bobbing pickups,
+* spinning/pulsing coins. Drives one `axis` of the node's `position`, `rotation`
+* (`mode: 'rotation'` — a "spin" when on z), or `scale` (a "pulse"):
+*
+*     value = start + amplitude · sin(2π · frequency · t)
+*
+* The baseline (`start`) is captured at ready, so it layers on top of authored
+* transforms. Dimension-agnostic; on a 2D node `rotation` is the scalar spin
+* (use `axis: 'z'`).
+*/
+var Oscillate = class extends Behavior {
+	static props = {
+		/** Which component to drive (rotation on a 2D node is 'z'). */
+		axis: {
+			default: "y",
+			options: [...AXES]
+		},
+		/** Peak displacement from the baseline. */
+		amplitude: { default: 1 },
+		/** Cycles per second. */
+		frequency: { default: 1 },
+		/** What to oscillate. */
+		mode: {
+			default: "position",
+			options: [...MODES]
+		}
+	};
+	static signals = [];
+	axis = "y";
+	amplitude = 1;
+	frequency = 1;
+	mode = "position";
+	base = 0;
+	time = 0;
+	onReady() {
+		if (!AXES.includes(this.axis)) throw new IncantoError("PROP_TYPE_MISMATCH", `Oscillate on '${this.node.getPath()}': "axis" must be one of [${AXES.join(", ")}], got '${this.axis}'.`, { prop: "axis" });
+		if (!MODES.includes(this.mode)) throw new IncantoError("PROP_TYPE_MISMATCH", `Oscillate on '${this.node.getPath()}': "mode" must be one of [${MODES.join(", ")}], got '${this.mode}'.`, { prop: "mode" });
+		this.base = this.readChannel();
+	}
+	update(dt) {
+		this.time += dt;
+		const offset = this.amplitude * Math.sin(2 * Math.PI * this.frequency * this.time);
+		this.writeChannel(this.base + offset);
+	}
+	/** Whether the target channel is the node's scalar 2D rotation. */
+	isScalarRotation() {
+		return this.mode === "rotation" && typeof this.node.rotation === "number";
+	}
+	readChannel() {
+		if (this.isScalarRotation()) return this.node.rotation;
+		const arr = this.node[this.mode];
+		if (!Array.isArray(arr)) throw new IncantoError("PROP_TYPE_MISMATCH", `Oscillate on '${this.node.getPath()}': node has no '${this.mode}' array to oscillate.`, { prop: "mode" });
+		return arr[AXIS_INDEX[this.axis]] ?? 0;
+	}
+	writeChannel(value) {
+		if (this.isScalarRotation()) {
+			this.node.rotation = value;
+			return;
+		}
+		const next = [...this.node[this.mode]];
+		next[AXIS_INDEX[this.axis]] = value;
+		this.node[this.mode] = next;
+	}
+};
+//#endregion
+//#region src/gameplay/patrol.ts
+/**
+* Walk the node along a fixed list of waypoints at constant speed — guards,
+* platforms, moving hazards. `points` are positions (`[x,y]` / `[x,y,z]`) OR
+* node paths whose `position` is read each frame (so you can author markers in
+* the scene). On arrival emits `reachedPoint(index)`; `pauseAt` holds at each
+* point before moving on.
+*
+* - `loop` (default) — after the last point, head back to the first.
+* - `mode: 'pingpong'` — reverse direction at each end instead of wrapping.
+*/
+var Patrol = class extends Behavior {
+	static props = {
+		/** Waypoints: array of position arrays OR node-path strings to read. */
+		points: { default: [] },
+		/** Units per second along the path. */
+		speed: { default: 60 },
+		/** Wrap to the first point after the last (ignored in pingpong). */
+		loop: { default: true },
+		/** 'loop' wraps; 'pingpong' reverses at the ends. */
+		mode: {
+			default: "loop",
+			options: ["loop", "pingpong"]
+		},
+		/** Seconds to wait at each reached point before continuing. */
+		pauseAt: { default: 0 }
+	};
+	static signals = ["reachedPoint"];
+	points = [];
+	speed = 60;
+	loop = true;
+	mode = "loop";
+	pauseAt = 0;
+	index = 0;
+	direction = 1;
+	pauseTimer = 0;
+	onReady() {
+		if (!Array.isArray(this.points) || this.points.length === 0) throw new IncantoError("PROP_TYPE_MISMATCH", `Patrol on '${this.node.getPath()}': "points" must be a non-empty array of position arrays or node paths.`, { prop: "points" });
+		if (this.mode !== "loop" && this.mode !== "pingpong") throw new IncantoError("PROP_TYPE_MISMATCH", `Patrol on '${this.node.getPath()}': "mode" must be 'loop' or 'pingpong', got '${this.mode}'.`, { prop: "mode" });
+		requirePosition(this);
+	}
+	update(dt) {
+		if (this.pauseTimer > 0) {
+			this.pauseTimer = Math.max(0, this.pauseTimer - dt);
+			return;
+		}
+		const node = this.node;
+		const target = this.pointAt(this.index);
+		if (!target) return;
+		const { position, reached } = moveToward(node.position, target, this.speed * dt);
+		node.position = position;
+		if (reached) {
+			this.emit("reachedPoint", this.index);
+			this.advance();
+			if (this.pauseAt > 0) this.pauseTimer = this.pauseAt;
+		}
+	}
+	/** Resolve waypoint `i` to a position, reading node paths live. */
+	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;
+		}
+		return null;
+	}
+	advance() {
+		const last = this.points.length - 1;
+		if (this.mode === "pingpong") {
+			if (this.index >= last) this.direction = -1;
+			else if (this.index <= 0) this.direction = 1;
+			this.index = Math.min(last, Math.max(0, this.index + this.direction));
+			return;
+		}
+		if (this.index < last) this.index += 1;
+		else if (this.loop) this.index = 0;
+	}
+};
+//#endregion
+//#region src/gameplay/pickup.ts
+/**
+* A collectible that vanishes when a collector overlaps it. Must sit on an
+* Area2D/Area3D (it listens to the unified `triggerEnter`).
+*
+* On overlap with a node in `collectorGroup`, emits `collected(value, other)`
+* then `queueFree()`s itself. Wire `collected → ScoreKeeper.addScore` (the
+* value is the first arg) or `collected → Collector.collect`.
+*/
+var Pickup = class extends Behavior {
+	static props = {
+		/** Worth of this pickup (passed as `collected`'s first arg). */
+		value: { default: 1 },
+		/** Free-form label for the kind of pickup ('coin', 'gem', 'key', …). */
+		kind: { default: "coin" },
+		/** Only nodes in this group collect it. */
+		collectorGroup: { default: "player" }
+	};
+	static signals = ["collected"];
+	value = 1;
+	kind = "coin";
+	collectorGroup = "player";
+	collectedAlready = false;
+	onReady() {
+		onTriggerEnter(this, (other) => this.tryCollect(other));
+	}
+	tryCollect(other) {
+		if (this.collectedAlready) return;
+		if (!other.isInGroup(this.collectorGroup)) return;
+		this.collectedAlready = true;
+		this.emit("collected", this.value, other);
+		this.node.queueFree();
+	}
+};
+//#endregion
+//#region src/gameplay/projectile.ts
+/**
+* Constant-velocity motion in a straight line — bullets, arrows, thrown rocks.
+* Pure movement by design: pair it with `DamageOnContact` (deal damage on hit),
+* `Lifetime` (auto-despawn), and an Area collider on the same node. Compose,
+* don't conflate.
+*
+* `direction` is either an explicit vector (`[x,y]` / `[x,y,z]`, normalized) or
+* the string `'forward'`, derived from the node's `rotation` (2D: degrees
+* clockwise, +x at 0). It is a union-typed prop, so its schema default is
+* `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.
+*/
+var Projectile = class extends Behavior {
+	static props = {
+		/** 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. */
+		gravity: { default: 0 }
+	};
+	static signals = [];
+	speed = 300;
+	direction = null;
+	gravity = 0;
+	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" });
+		const node = requirePosition(this);
+		const dir = this.resolveDirection();
+		this.velocity = dir.map((c) => c * this.speed);
+		while (this.velocity.length < node.position.length) this.velocity.push(0);
+	}
+	update(dt) {
+		const node = this.node;
+		if (this.gravity !== 0) this.velocity[1] = (this.velocity[1] ?? 0) + this.gravity * dt;
+		node.position = add(node.position, this.velocity.map((v) => v * dt));
+	}
+	/** 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" });
+	}
+	forwardFromRotation() {
+		const rot = this.node.rotation;
+		if (typeof rot === "number") {
+			const rad = rot * Math.PI / 180;
+			return [Math.cos(rad), Math.sin(rad)];
+		}
+		if (Array.isArray(rot)) {
+			const yaw = (rot[1] ?? 0) * Math.PI / 180;
+			const pitch = (rot[0] ?? 0) * Math.PI / 180;
+			return normalize([
+				-Math.sin(yaw) * Math.cos(pitch),
+				Math.sin(pitch),
+				-Math.cos(yaw) * Math.cos(pitch)
+			]);
+		}
+		return [1, 0];
+	}
+};
+//#endregion
+//#region src/gameplay/score-keeper.ts
+/**
+* The game's state hub — score, lives, and win/lose detection. Put it on the
+* Root/Game node and wire gameplay signals into its methods (e.g. a Pickup's
+* `collected → addScore`, a Health's `died → loseLife`).
+*
+* - `score` rises via `addScore` / `setScore`; reaching `scoreToWin` (>0)
+*   emits `won` once.
+* - `lives` (>0) shrinks via `loseLife`; reaching 0 emits `lost` once.
+*/
+var ScoreKeeper = class extends Behavior {
+	static props = {
+		/** Starting score. */
+		score: { default: 0 },
+		/** Starting lives (0 = lives disabled, loseLife is inert). */
+		lives: { default: 0 },
+		/** Score that triggers `won` (0 = disabled). */
+		scoreToWin: { default: 0 }
+	};
+	static signals = [
+		"scoreChanged",
+		"won",
+		"lost",
+		"lifeLost"
+	];
+	score = 0;
+	lives = 0;
+	scoreToWin = 0;
+	hasWon = false;
+	hasLost = false;
+	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" });
+	}
+	/** Add `n` to the score (negative subtracts), emit `scoreChanged`, check win. */
+	addScore(n) {
+		this.setScore(this.score + n);
+	}
+	/** Set the score to `value`, emit `scoreChanged`, check win. */
+	setScore(value) {
+		this.score = value;
+		this.emit("scoreChanged", this.score);
+		if (this.scoreToWin > 0 && !this.hasWon && this.score >= this.scoreToWin) {
+			this.hasWon = true;
+			this.emit("won");
+		}
+	}
+	/** Lose one life (no-op when lives disabled or already lost). Emits `lifeLost`, then `lost` at 0. */
+	loseLife() {
+		if (this.lives <= 0 || this.hasLost) return;
+		this.lives -= 1;
+		this.emit("lifeLost", this.lives);
+		if (this.lives <= 0) {
+			this.hasLost = true;
+			this.emit("lost");
+		}
+	}
+};
+//#endregion
+//#region src/gameplay/spawn-source.ts
+/**
+* Shared spawn mechanism for Spawner/WaveSpawner.
+*
+* A `prefab` is a node PATH to a TEMPLATE node in the scene (usually a hidden
+* `visible: false` child of the spawner). We `duplicateNode` it (the same
+* serialize→rebuild clone used by the editor — scripts and nested children come
+* along, the clone gets a fresh identity) and add it as a sibling-style child of
+* the spawner's node. Keeping spawning to clone-a-template makes it CORE-PURE
+* (no NetworkManager / scene registry, no three) and headlessly verifiable.
+*/
+var SpawnSource = class {
+	behavior;
+	/** Templates already resolved-and-detached, keyed by their prefab path. */
+	detached = /* @__PURE__ */ new Map();
+	constructor(behavior) {
+		this.behavior = behavior;
+	}
+	/**
+	* Resolve a template path to its node, hard-failing if it's missing, and
+	* DETACH it from the live tree so the template never updates or renders.
+	*
+	* A `visible:false` template is still a live node: its behaviors tick (e.g. a
+	* Chase walks the invisible template onto the player) and a renderer may set
+	* it up. Removing it from the tree on first resolution makes it inert — the
+	* detached node is held here purely as a clone source. Clones go INTO the
+	* tree; the template stays out. Idempotent and cached, so WaveSpawner's
+	* per-spawn re-resolution returns the same held template.
+	*/
+	resolveTemplate(prefab) {
+		const cached = this.detached.get(prefab);
+		if (cached) return cached;
+		const node = this.behavior.node;
+		const template = prefab === "" ? null : node.getNodeOrNull(prefab);
+		if (!template) {
+			const behaviorName = this.behavior.constructor.name;
+			throw new IncantoError("NODE_NOT_FOUND", `${behaviorName} on '${node.getPath()}': "prefab" '${prefab}' does not resolve to a template node. Point it at a (usually hidden) child node to clone.`, {
+				prop: "prefab",
+				path: node.getPath()
+			});
+		}
+		if (template.parent) template.parent.removeChild(template);
+		this.detached.set(prefab, template);
+		return template;
+	}
+	/**
+	* Clone `template`, make it visible, attach it under `parent` (defaults to the
+	* spawner's node), and return the clone.
+	*
+	* Placement: with no `at`, the clone keeps the template's authored position;
+	* with `at`, it spawns at the spawner's position plus `at` (a non-spatial
+	* spawner like a plain Node treats `at` as absolute).
+	*/
+	spawn(template, opts) {
+		const clone = duplicateNode(template);
+		const at = opts?.at;
+		if (at && at.length > 0 && hasPosition$1(clone)) clone.position = add(hasPosition$1(this.behavior.node) ? this.behavior.node.position : [], at);
+		if (typeof clone.visible === "boolean") clone.visible = true;
+		(opts?.parent ?? this.behavior.node).addChild(clone);
+		return clone;
+	}
+};
+//#endregion
+//#region src/gameplay/spawner.ts
+/**
+* Drip-feed clones of a template into the scene on a timer — enemy generators,
+* pickup fountains, particle emitters. `prefab` is a node PATH to a template
+* (usually a hidden `visible: false` child) that gets cloned each `interval`.
+*
+* - `max` caps LIVE instances (0 = unlimited); the count drops automatically as
+*   spawned children free themselves (e.g. via `Lifetime` or `Health.died`), so
+*   the spawner refills.
+* - `total` caps LIFETIME spawns (0 = infinite); on the last one it emits
+*   `finished` and stops.
+* - `autoStart` (default) begins ticking at ready; otherwise call `start()`.
+*
+* Emits `spawned(node)` per spawn. Methods: `spawn()`, `start()`, `stop()`.
+*/
+var Spawner = class extends Behavior {
+	static props = {
+		/** Node path of the template to clone. */
+		prefab: { default: "" },
+		/** Seconds between spawns. */
+		interval: { default: 1 },
+		/** Max LIVE instances (0 = unlimited). */
+		max: { default: 0 },
+		/** Offset/spawn point ([x,y(,z)]) added to the spawner's position. */
+		at: { default: [] },
+		/** Begin ticking at ready. */
+		autoStart: { default: true },
+		/** Total LIFETIME spawns (0 = infinite). */
+		total: { default: 0 }
+	};
+	static signals = ["spawned", "finished"];
+	prefab = "";
+	interval = 1;
+	max = 0;
+	at = [];
+	autoStart = true;
+	total = 0;
+	source = new SpawnSource(this);
+	template;
+	live = /* @__PURE__ */ new Set();
+	timer = 0;
+	running = false;
+	spawnedCount = 0;
+	done = false;
+	/** Live (un-freed) spawned instances. */
+	get liveCount() {
+		this.prune();
+		return this.live.size;
+	}
+	/** @internal The detached template node (test/debug only). */
+	_templateForTest() {
+		return this.template;
+	}
+	onReady() {
+		this.template = this.source.resolveTemplate(this.prefab);
+		this.running = this.autoStart;
+		this.timer = this.interval;
+	}
+	/** Begin (or resume) interval spawning. */
+	start() {
+		if (this.done) return;
+		this.running = true;
+	}
+	/** Pause interval spawning (spawn() still works). */
+	stop() {
+		this.running = false;
+	}
+	/** Spawn one immediately (ignores the timer; still respects max/total). */
+	spawn() {
+		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);
+		this.live.add(clone);
+		this.spawnedCount += 1;
+		this.emit("spawned", clone);
+		if (this.total > 0 && this.spawnedCount >= this.total) {
+			this.done = true;
+			this.running = false;
+			this.emit("finished");
+		}
+		return clone;
+	}
+	update(dt) {
+		if (!this.running) return;
+		this.timer -= dt;
+		if (this.timer > 0) return;
+		this.timer += this.interval;
+		this.spawn();
+	}
+	/** Drop instances that have been freed (parent cleared on free/queueFree). */
+	prune() {
+		for (const node of this.live) if (node.parent === null) this.live.delete(node);
+	}
+};
+//#endregion
+//#region src/gameplay/wander.ts
+/**
+* Aimless roaming inside a circle around the spawn point — idle critters,
+* ambient wildlife, restless guards. Picks a random destination within `radius`
+* of where it started, walks there at `speed`, then (every `changeEvery`
+* seconds, or on arrival) picks a new one. Uses `this.rng`, so a seeded engine
+* wanders identically every run (replayable, test-stable).
+*
+* Dimension-agnostic: roams in the plane of however many position components
+* the node has (2D `[x,y]`, 3D `[x,z]` ground plane keeping y).
+*/
+var Wander = class extends Behavior {
+	static props = {
+		/** Units per second while roaming. */
+		speed: { default: 40 },
+		/** Roam radius around the spawn point. */
+		radius: { default: 50 },
+		/** Seconds before forcibly choosing a new destination. */
+		changeEvery: { default: 2 }
+	};
+	static signals = [];
+	speed = 40;
+	radius = 50;
+	changeEvery = 2;
+	origin = [];
+	goal = [];
+	timer = 0;
+	onReady() {
+		if (!(this.radius > 0)) throw new IncantoError("PROP_TYPE_MISMATCH", `Wander on '${this.node.getPath()}': "radius" must be > 0, got ${this.radius}.`, { prop: "radius" });
+		const node = requirePosition(this);
+		this.origin = [...node.position];
+		this.goal = [...node.position];
+		this.pickGoal();
+	}
+	update(dt) {
+		const node = this.node;
+		this.timer -= dt;
+		const { position, reached } = moveToward(node.position, this.goal, this.speed * dt);
+		node.position = position;
+		if (reached || this.timer <= 0) this.pickGoal();
+	}
+	pickGoal() {
+		this.timer = this.changeEvery;
+		const dims = this.origin.length;
+		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);
+			if (distance$1(next, this.origin) <= this.radius) {
+				this.goal = next;
+				return;
+			}
+		}
+		this.goal = next.map((c, i) => {
+			const o = this.origin[i] ?? 0;
+			const d = distance$1(next, this.origin) || 1;
+			return o + (c - o) / d * this.radius;
+		});
+	}
+};
+//#endregion
+//#region src/gameplay/wave-spawner.ts
+/**
+* Sequenced enemy waves — the survivor/tower-defense backbone. Each entry in
+* `waves` is `{ prefab, count, interval, delayBefore }`: after `delayBefore`
+* seconds it spawns `count` clones of `prefab` (a hidden template path) one
+* every `interval` seconds, then waits until they're ALL cleared (freed) before
+* starting the next wave.
+*
+* Signals: `waveStarted(i)` when a wave begins spawning, `waveCleared(i)` when
+* its last instance frees, `allCleared` after the final wave clears.
+*/
+var WaveSpawner = class extends Behavior {
+	static props = {
+		/** Array of { prefab, count, interval, delayBefore }. */
+		waves: { default: [] },
+		/** Begin the first wave's countdown at ready. */
+		autoStart: { default: true }
+	};
+	static signals = [
+		"waveStarted",
+		"waveCleared",
+		"allCleared"
+	];
+	waves = [];
+	autoStart = true;
+	source = new SpawnSource(this);
+	parsed = [];
+	live = /* @__PURE__ */ new Set();
+	waveIndex = -1;
+	phase = "idle";
+	timer = 0;
+	spawnedThisWave = 0;
+	announced = false;
+	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));
+		for (const w of this.parsed) this.source.resolveTemplate(w.prefab);
+		if (this.autoStart) this.beginWave(0);
+	}
+	/** Start (or restart from) wave 0. */
+	start() {
+		this.beginWave(0);
+	}
+	update(dt) {
+		if (this.phase === "idle" || this.phase === "done") return;
+		const wave = this.parsed[this.waveIndex];
+		if (!wave) return;
+		if (!this.announced) {
+			this.announced = true;
+			this.emit("waveStarted", this.waveIndex);
+		}
+		if (this.phase === "delay") {
+			this.timer -= dt;
+			if (this.timer <= 0) {
+				this.phase = "spawning";
+				this.timer = 0;
+			}
+			return;
+		}
+		if (this.phase === "spawning") {
+			this.timer -= dt;
+			while (this.timer <= 0 && this.spawnedThisWave < wave.count) {
+				const clone = this.source.spawn(this.source.resolveTemplate(wave.prefab));
+				this.live.add(clone);
+				this.spawnedThisWave += 1;
+				this.timer += wave.interval;
+			}
+			if (this.spawnedThisWave >= wave.count) this.phase = "clearing";
+			return;
+		}
+		if (this.phase === "clearing") {
+			this.prune();
+			if (this.live.size === 0) {
+				this.emit("waveCleared", this.waveIndex);
+				const next = this.waveIndex + 1;
+				if (next < this.parsed.length) this.beginWave(next);
+				else {
+					this.phase = "done";
+					this.emit("allCleared");
+				}
+			}
+		}
+	}
+	beginWave(i) {
+		this.waveIndex = i;
+		this.spawnedThisWave = 0;
+		this.announced = false;
+		this.live.clear();
+		const wave = this.parsed[i];
+		if (!wave) return;
+		if (wave.delayBefore > 0) {
+			this.phase = "delay";
+			this.timer = wave.delayBefore;
+		} else {
+			this.phase = "spawning";
+			this.timer = 0;
+		}
+	}
+	prune() {
+		for (const node of this.live) if (node.parent === null) this.live.delete(node);
+	}
+	parseWave(raw, i) {
+		const w = raw;
+		const prefab = typeof w?.prefab === "string" ? w.prefab : "";
+		if (prefab === "") throw new IncantoError("PROP_TYPE_MISMATCH", `WaveSpawner on '${this.node.getPath()}': wave ${i} needs a "prefab" template path.`, { prop: "waves" });
+		return {
+			prefab,
+			count: typeof w?.count === "number" ? w.count : 1,
+			interval: typeof w?.interval === "number" ? w.interval : .5,
+			delayBefore: typeof w?.delayBefore === "number" ? w.delayBefore : 0
+		};
+	}
+};
+//#endregion
+//#region src/gameplay/zombie-ai.ts
+/**
+* The staple "zombie / monster" AI: SHAMBLE around on its own, then LOCK ON and
+* CHARGE a target (the player) once it wanders within `aggroRange` — giving up
+* again past `deAggroRange` (hysteresis, so it doesn't flicker at the boundary).
+* One behavior covers both phases so a single node can be a complete enemy
+* (`Wander` + `Chase` can't co-exist — a node carries ONE behavior).
+*
+* While NOT aggroed it roams: with `goalTarget` set it DRIFTS toward that node
+* (e.g. the objective the horde is marching on) with random lateral jitter, so it
+* reads as wandering yet still advances; without one it roams around its spawn.
+*
+* Emits `movementStateChanged('idle'|'walk'|'run')` on every change so a skin can
+* swap animation clips (shamble while roaming, sprint while charging), plus
+* `enteredAggro` / `exitedAggro` (wire to a growl, a glow, a speed-up).
+*
+* Dimension-agnostic; in 3D it moves only in the ground plane (x,z) and leaves
+* the up axis (y) to physics, so a CharacterBody3D settles on terrain.
+*
+* `moveParent` (default false) moves the parent instead of this node — the
+* AI-on-a-child pattern, so the entity ROOT can hold `Health` (clone-safe
+* `freeOnDeath`) while this child drives movement.
+*/
+var ZombieAI = class extends Behavior {
+	static props = {
+		/** NodePath of the node to charge once near (usually the player). */
+		aggroTarget: { default: "" },
+		/** Start charging when the target is within this distance. */
+		aggroRange: { default: 12 },
+		/** Give up the charge past this distance (0 = aggroRange × 1.5). */
+		deAggroRange: { default: 0 },
+		/** Units/second while charging the target. */
+		chaseSpeed: { default: 4 },
+		/** Units/second while roaming. */
+		wanderSpeed: { default: 1.4 },
+		/** Roam jitter radius (around spawn, or around the drift point). */
+		wanderRadius: { default: 8 },
+		/** Seconds before forcibly choosing a new roam goal. */
+		wanderChangeEvery: { default: 3 },
+		/** Optional NodePath to DRIFT toward while roaming (e.g. the objective). */
+		goalTarget: { default: "" },
+		/** Stop (and idle) this close to the active target. */
+		stopRange: { default: 1.2 },
+		/** Move the parent node instead of this one (AI-on-a-child pattern). */
+		moveParent: { default: false }
+	};
+	static signals = [
+		"enteredAggro",
+		"exitedAggro",
+		"movementStateChanged"
+	];
+	aggroTarget = "";
+	aggroRange = 12;
+	deAggroRange = 0;
+	chaseSpeed = 4;
+	wanderSpeed = 1.4;
+	wanderRadius = 8;
+	wanderChangeEvery = 3;
+	goalTarget = "";
+	stopRange = 1.2;
+	moveParent = false;
+	aggro = false;
+	started = false;
+	home = [];
+	goal = [];
+	timer = 0;
+	lastState = "";
+	/** The node we actually move (the parent under moveParent, else this one). */
+	mover() {
+		const n = this.moveParent ? this.node.parent : this.node;
+		return n && hasPosition$1(n) ? n : null;
+	}
+	effectiveDeAggro() {
+		return this.deAggroRange > 0 ? this.deAggroRange : this.aggroRange * 1.5;
+	}
+	onReady() {
+		if (this.moveParent) {
+			const parent = this.node.parent;
+			if (!parent || !hasPosition$1(parent)) throw new IncantoError("PROP_TYPE_MISMATCH", `ZombieAI on '${this.node.getPath()}': "moveParent" needs a spatial parent (a Node2D/Node3D) to move. '${this.node.name}' has none.`, {
+				prop: "moveParent",
+				path: this.node.getPath()
+			});
+		} else requirePosition(this);
+	}
+	update(dt) {
+		const mover = this.mover();
+		if (!mover) return;
+		if (!this.started) {
+			this.started = true;
+			this.home = [...mover.position];
+			this.pickGoal();
+		}
+		const target = this.aggroTarget ? this.node.getNodeOrNull(this.aggroTarget) : null;
+		const targetPos = target && hasPosition$1(target) ? target.position : null;
+		const aggroDist = targetPos ? this.groundDistance(mover.position, targetPos) : Number.POSITIVE_INFINITY;
+		if (!this.aggro && aggroDist <= this.aggroRange) {
+			this.aggro = true;
+			this.emit("enteredAggro");
+		} else if (this.aggro && aggroDist >= this.effectiveDeAggro()) {
+			this.aggro = false;
+			this.emit("exitedAggro");
+			this.pickGoal();
+		}
+		if (this.aggro && targetPos) {
+			const stopped = this.approach(mover, targetPos, this.chaseSpeed, dt);
+			this.setState(stopped ? "idle" : "run");
+			return;
+		}
+		this.timer -= dt;
+		const reached = this.approach(mover, this.goal, this.wanderSpeed, dt);
+		this.setState(reached ? "idle" : "walk");
+		if (reached || this.timer <= 0) this.pickGoal();
+	}
+	/** Move `mover` toward `to` in the GROUND PLANE; returns true once within
+	*  stopRange (no overshoot). Leaves the up axis (3D y) to physics. */
+	approach(mover, to, speed, dt) {
+		const cur = mover.position;
+		if (this.groundDistance(cur, to) <= this.stopRange) return true;
+		const up = cur.length >= 3 ? 1 : -1;
+		const goal = [...to];
+		if (up >= 0) goal[up] = cur[up] ?? 0;
+		const horiz = this.groundDistance(cur, goal);
+		const { position } = moveToward(cur, goal, Math.min(speed * dt, Math.max(0, horiz - this.stopRange)));
+		mover.position = position;
+		return false;
+	}
+	/** Distance ignoring the up axis in 3D (so terrain height never blocks aggro). */
+	groundDistance(a, b) {
+		if (a.length >= 3) {
+			const dx = (a[0] ?? 0) - (b[0] ?? 0);
+			const dz = (a[2] ?? 0) - (b[2] ?? 0);
+			return Math.hypot(dx, dz);
+		}
+		return distance$1(a, b);
+	}
+	setState(state) {
+		if (state === this.lastState) return;
+		this.lastState = state;
+		this.emit("movementStateChanged", state);
+	}
+	pickGoal() {
+		this.timer = this.wanderChangeEvery;
+		const mover = this.mover();
+		const cur = mover ? mover.position : this.home;
+		const up = cur.length >= 3 ? 1 : -1;
+		let basis = this.home;
+		const goalNode = this.goalTarget ? this.node.getNodeOrNull(this.goalTarget) : null;
+		if (goalNode && hasPosition$1(goalNode)) {
+			const gp = goalNode.position;
+			basis = cur.map((c, i) => c + ((gp[i] ?? 0) - c) * .4);
+		}
+		const next = [...basis];
+		for (let i = 0; i < next.length; i++) {
+			if (i === up) continue;
+			next[i] = (basis[i] ?? 0) + this.rng.range(-this.wanderRadius, this.wanderRadius);
+		}
+		if (up >= 0) next[up] = cur[up] ?? 0;
+		this.goal = next;
+	}
+};
+//#endregion
+//#region src/gameplay/index.ts
+/**
+* incanto/gameplay — batteries-included, JSON-wireable game logic.
+*
+* Ready-made `Behavior`s for the things every game re-invents: health, score,
+* pickups, lifetimes, contact damage, interaction. All pure logic (no `three`),
+* dimension-agnostic, composed through scene-JSON `script` blobs + `connections`.
+*
+* `createGame2D`/`createGame3D` auto-register these (before user behaviors, so
+* a same-named user behavior always wins). Opt out with `gameplay: false`, or
+* register a subset yourself via `registerBehavior(name, Class)`.
+*/
+/** Every built-in gameplay behavior, keyed by its registration name. */
+const GAMEPLAY_BEHAVIORS = {
+	Health,
+	Lifetime,
+	ScoreKeeper,
+	Pickup,
+	Collector,
+	DamageOnContact,
+	Interactable,
+	FollowCamera,
+	Patrol,
+	Chase,
+	Wander,
+	ZombieAI,
+	MoveTo,
+	Oscillate,
+	Spawner,
+	WaveSpawner,
+	Projectile
+};
+/**
+* Register all built-in gameplay behaviors. Idempotent and hot-reload tolerant
+* (`replace: true`) — calling it twice, or after a user already registered a
+* same-named behavior, is safe; pass `replace: false` to fail on conflicts.
+*/
+function registerGameplayBehaviors(opts) {
+	const replace = opts?.replace ?? true;
+	for (const [name, ctor] of Object.entries(GAMEPLAY_BEHAVIORS)) registerBehavior(name, ctor, { replace });
+}
+//#endregion
+export { Health as _, Wander as a, Projectile as c, Oscillate as d, MoveTo as f, DamageOnContact as g, FollowCamera as h, WaveSpawner as i, Pickup as l, Interactable as m, registerGameplayBehaviors as n, Spawner as o, Lifetime as p, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Patrol as u, Collector as v, Chase as y };