incanto 0.1.0

package/dist/register-DPEV9_9t.js

@@ -0,0 +1,851 @@
+import { f as Node } from "./loader-CGs_G-r0.js";
+import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-DYuSUxvK.js";
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { t as Rng } from "./rng-DP-SR7eg.js";
+import { t as registerCoreNodes } from "./register-BuUV1_KB.js";
+import { i as getNodeSchema, l as registerNode } from "./registry-BVJ2HbCn.js";
+import { AdditiveBlending, CanvasTexture, Color, DynamicDrawUsage, Group, InstancedMesh, MathUtils, Matrix4, Mesh, MeshBasicMaterial, NormalBlending, Object3D, PlaneGeometry } from "three";
+//#region src/2d/physics/collider-validate.ts
+/**
+* Hard-validate a 2D collider prop — called at LOAD time (via the loader's
+* static validateJson hook) so bad shapes fail when the scene is authored,
+* not minutes later when physics starts. An EMPTY collider is fine: a body
+* without a collider is a work-in-progress node, not an error.
+*/
+function validateCollider2D(collider, nodeName) {
+	const shape = collider.shape;
+	if (shape === void 0) return;
+	if (shape === "rect") {
+		const size = collider.size;
+		if (!Array.isArray(size) || size.length !== 2 || size.some((v) => typeof v !== "number")) throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}': rect needs "size": [width, height].`);
+		return;
+	}
+	if (shape === "circle") {
+		if (typeof collider.radius !== "number") throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}': circle needs "radius".`);
+		return;
+	}
+	if (shape === "capsule") {
+		if (typeof collider.radius !== "number" || typeof collider.height !== "number") throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}': capsule needs "radius" and "height".`);
+		return;
+	}
+	throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}': "shape" must be 'rect', 'circle', or 'capsule', got ${JSON.stringify(shape)}.`);
+}
+//#endregion
+//#region src/2d/nodes/node-2d.ts
+/**
+* Base of every 2D node. Convention (Phaser/Godot prior):
+* **1 unit = 1 px, +y DOWN, (0,0) top-left, positive rotation = clockwise.**
+* Internally mapped onto three's y-up space by negating y and the z-spin.
+*/
+var Node2D = class extends Node {
+	static typeName = "Node2D";
+	static props = {
+		position: { default: [0, 0] },
+		rotation: { default: 0 },
+		scale: { default: [1, 1] },
+		renderOrder: { default: 0 },
+		visible: { default: true }
+	};
+	/** Legacy alias: old 2D scenes (and `zIndex`-trained agents) keep loading —
+	* `zIndex` resolves to `renderOrder` at load. The schema exposes only
+	* `renderOrder` so 2D and 3D share ONE render-order name. */
+	static propAliases = { zIndex: "renderOrder" };
+	/** Pixels, y-down. */
+	position = [0, 0];
+	/** Degrees, clockwise. */
+	rotation = 0;
+	scale = [1, 1];
+	/** Draw order among 2D drawables (higher = on top); matches 3D `renderOrder`. */
+	renderOrder = 0;
+	visible = true;
+	_object2D = null;
+	/** @internal The backing three object (lazily created). */
+	_ensureObject2D() {
+		if (!this._object2D) {
+			this._object2D = this._createObject2D();
+			this._object2D.userData.incantoNode = this;
+		}
+		return this._object2D;
+	}
+	/** @internal Override point. */
+	_createObject2D() {
+		return new Object3D();
+	}
+	/** @internal Push JSON props onto the backing object. Called every frame. */
+	_syncObject2D(_assets) {
+		const o = this._ensureObject2D();
+		o.position.set(this.position[0] ?? 0, -(this.position[1] ?? 0), 0);
+		o.rotation.z = -MathUtils.degToRad(this.rotation);
+		o.scale.set(this.scale[0] ?? 1, this.scale[1] ?? 1, 1);
+		o.visible = this.visible;
+	}
+	free() {
+		super.free();
+		this._object2D?.removeFromParent();
+		this._object2D = null;
+	}
+};
+//#endregion
+//#region src/2d/nodes/bodies-2d.ts
+/**
+* Shared base for physics-backed 2D nodes. Colliders are NODE PROPS:
+* `{shape:'rect', size:[w,h]}` · `{shape:'circle', radius}` ·
+* `{shape:'capsule', radius, height}` — never child shape nodes.
+*/
+var PhysicsBody2D = class extends Node2D {
+	static props = { collider: { default: {} } };
+	/** The unified collision model: every collider participant can emit these. */
+	static signals = ["triggerEnter", "triggerExit"];
+	collider = {};
+	/** Loader hook: bad collider shapes fail at LOAD, not at physics start. */
+	static validateJson(node) {
+		validateCollider2D(node.collider, node.name);
+	}
+	/** @internal Set by Physics2D when the body is created. */
+	_physics = null;
+};
+/** Immovable collider (ground, walls, platforms). */
+var StaticBody2D = class extends PhysicsBody2D {
+	static typeName = "StaticBody2D";
+};
+/**
+* Sensor volume. Emits `triggerEnter(other)` / `triggerExit(other)` — the
+* unified collision model (solid bodies emit the same signals on contact).
+*/
+var Area2D = class extends PhysicsBody2D {
+	static typeName = "Area2D";
+};
+/** Dynamic simulated body. */
+var RigidBody2D = class extends PhysicsBody2D {
+	static typeName = "RigidBody2D";
+	static props = {
+		mass: { default: 1 },
+		gravityScale: { default: 1 },
+		fixedRotation: { default: false },
+		friction: { default: .5 },
+		restitution: { default: 0 },
+		linearVelocity: { default: [0, 0] }
+	};
+	mass = 1;
+	gravityScale = 1;
+	fixedRotation = false;
+	friction = .5;
+	restitution = 0;
+	/** px/s, y-down. Read back every step; write to launch. */
+	linearVelocity = [0, 0];
+};
+/**
+* Kinematic body on Rapier's character controller. Gravity is NOT applied
+* automatically (Godot semantics) — integrate `velocity` yourself, then call
+* `moveAndSlide()` from `fixedUpdate`.
+*/
+var CharacterBody2D = class extends PhysicsBody2D {
+	static typeName = "CharacterBody2D";
+	static props = {
+		velocity: { default: [0, 0] },
+		snapToGround: { default: true },
+		slopeLimitDeg: { default: 45 }
+	};
+	/** px/s, y-down (up = -y). */
+	velocity = [0, 0];
+	/** Keep contact on slopes/steps while not moving upward. */
+	snapToGround = true;
+	/** Max climbable slope angle. */
+	slopeLimitDeg = 45;
+	/** @internal Updated by Physics2D.moveAndSlide. */
+	_grounded = false;
+	moveAndSlide() {
+		if (!this._physics) throw new IncantoError("TREE_VIOLATION", this.collider.shape === void 0 ? `CharacterBody2D '${this.name}' has no collider — set a collider prop (physics skips collider-less bodies).` : `CharacterBody2D '${this.name}' has no physics world — await enablePhysics2D(engine) first.`);
+		this._physics.moveAndSlide(this);
+	}
+	isOnFloor() {
+		return this._grounded;
+	}
+};
+//#endregion
+//#region src/2d/nodes/sprite-2d.ts
+/** Shared unit quad — sprites are sized via the quad's scale, never THREE.Sprite. */
+const UNIT_PLANE$2 = new PlaneGeometry(1, 1);
+/**
+* A textured quad. The drawable is an inner mesh child of the node's backing
+* object, so node children never inherit the texture-size scaling.
+*/
+var Sprite2D = class extends Node2D {
+	static typeName = "Sprite2D";
+	static props = {
+		texture: { default: "" },
+		anchor: { default: [.5, .5] },
+		flipX: { default: false },
+		flipY: { default: false },
+		tint: { default: "#ffffff" },
+		opacity: { default: 1 }
+	};
+	/** `'$assetKey'` texture reference. Empty = hidden. */
+	texture = "";
+	/** [0,0] = top-left on the origin … [1,1] = bottom-right on the origin. */
+	anchor = [.5, .5];
+	flipX = false;
+	flipY = false;
+	tint = "#ffffff";
+	opacity = 1;
+	quadMesh = null;
+	/** @internal The drawable quad (lazily created, attached under the backing object). */
+	_quad() {
+		if (!this.quadMesh) {
+			this.quadMesh = new Mesh(UNIT_PLANE$2, new MeshBasicMaterial({
+				transparent: true,
+				depthWrite: false
+			}));
+			this._ensureObject2D().add(this.quadMesh);
+		}
+		return this.quadMesh;
+	}
+	_createObject2D() {
+		return super._createObject2D();
+	}
+	/** Override point: AnimatedSprite2D substitutes its frame window here. */
+	resolveTexture(assets) {
+		if (!this.texture || !assets) return null;
+		const texture = assets.getTexture(this.texture);
+		const image = texture.image;
+		if (!image?.width || !image.height) return null;
+		return {
+			texture,
+			width: image.width,
+			height: image.height
+		};
+	}
+	_syncObject2D(assets) {
+		super._syncObject2D(assets);
+		const quad = this._quad();
+		const mat = quad.material;
+		const resolved = this.resolveTexture(assets);
+		if (!resolved) {
+			quad.visible = false;
+			return;
+		}
+		quad.visible = true;
+		if (mat.map !== resolved.texture) {
+			mat.map = resolved.texture;
+			mat.needsUpdate = true;
+		}
+		const w = resolved.width;
+		const h = resolved.height;
+		quad.scale.set(this.flipX ? -w : w, this.flipY ? -h : h, 1);
+		const ax = this.anchor[0] ?? .5;
+		const ay = this.anchor[1] ?? .5;
+		quad.position.set((.5 - ax) * w, (ay - .5) * h, 0);
+		quad.renderOrder = this.renderOrder;
+		mat.color.set(this.tint);
+		mat.opacity = this.opacity;
+	}
+};
+//#endregion
+//#region src/2d/nodes/animated-sprite-2d.ts
+/**
+* Spritesheet animation: pure-JSON animation map, frame selection via a UV
+* window on the node's own texture clone. Frames advance in `update(dt)` —
+* deterministic and headless-testable.
+*/
+var AnimatedSprite2D = class extends Sprite2D {
+	static typeName = "AnimatedSprite2D";
+	static signals = ["animationFinished"];
+	static props = {
+		sheet: { default: "" },
+		animations: { default: {} },
+		autoplay: { default: "" }
+	};
+	/** `'$assetKey'` of a spritesheet asset. */
+	sheet = "";
+	animations = {};
+	autoplay = "";
+	playing = false;
+	/** Absolute frame index within the sheet. */
+	currentFrame = 0;
+	currentAnimation = "";
+	frameList = [];
+	frameIndex = 0;
+	frameTime = 0;
+	ownTexture = null;
+	loadedSheetRef = "";
+	play(name) {
+		const def = this.animations[name];
+		if (!def) throw new IncantoError("UNKNOWN_ANIMATION", `No animation '${name}' on '${this.name}'. Available: [${Object.keys(this.animations).join(", ")}].`);
+		this.currentAnimation = name;
+		this.frameList = resolveFrames(def.frames, name);
+		this.frameIndex = 0;
+		this.currentFrame = this.frameList[0] ?? 0;
+		this.frameTime = 0;
+		this.playing = true;
+	}
+	stop() {
+		this.playing = false;
+	}
+	onReady() {
+		if (this.autoplay) this.play(this.autoplay);
+	}
+	update(dt) {
+		if (!this.playing || this.currentAnimation === "") return;
+		const def = this.animations[this.currentAnimation];
+		if (!def || !Number.isFinite(def.fps) || def.fps <= 0) return;
+		const perFrame = 1 / def.fps;
+		this.frameTime += dt;
+		while (this.frameTime >= perFrame) {
+			this.frameTime -= perFrame;
+			this.frameIndex += 1;
+			if (this.frameIndex >= this.frameList.length) if (def.loop) this.frameIndex = 0;
+			else {
+				this.frameIndex = this.frameList.length - 1;
+				this.playing = false;
+				this.emit("animationFinished", this.currentAnimation);
+				break;
+			}
+		}
+		this.currentFrame = this.frameList[this.frameIndex] ?? 0;
+	}
+	resolveTexture(assets) {
+		if (!this.sheet || !assets) return null;
+		const info = assets.getSheet(this.sheet);
+		if (this.loadedSheetRef !== this.sheet) {
+			this.ownTexture = info.texture.clone();
+			this.ownTexture.needsUpdate = true;
+			this.loadedSheetRef = this.sheet;
+		}
+		const tex = this.ownTexture;
+		const image = info.texture.image;
+		if (!image?.width || !image.height) return null;
+		const cols = Math.max(1, Math.floor(image.width / info.frameWidth));
+		const col = this.currentFrame % cols;
+		const row = Math.floor(this.currentFrame / cols);
+		tex.repeat.set(info.frameWidth / image.width, info.frameHeight / image.height);
+		tex.offset.set(col * info.frameWidth / image.width, 1 - (row + 1) * info.frameHeight / image.height);
+		return {
+			texture: tex,
+			width: info.frameWidth,
+			height: info.frameHeight
+		};
+	}
+};
+function resolveFrames(frames, name) {
+	if (!Array.isArray(frames) || frames.length === 0) throw new IncantoError("BAD_FORMAT", `Animation '${name}': "frames" must be a non-empty array.`);
+	if (frames.length === 2) {
+		const [start, end] = frames;
+		if (end >= start) {
+			const out = [];
+			for (let f = start; f <= end; f++) out.push(f);
+			return out;
+		}
+	}
+	return [...frames];
+}
+//#endregion
+//#region src/2d/nodes/camera-2d.ts
+/**
+* 2D camera: its `position` is the view CENTER. `follow` tracks a node path
+* with exponential smoothing; `limits [minX,minY,maxX,maxY]` clamp the view
+* rect inside a world region (applied by the renderer via `clampedCenter`).
+*/
+var Camera2D = class extends Node2D {
+	static typeName = "Camera2D";
+	static props = {
+		follow: { default: "" },
+		smoothing: { default: 0 },
+		zoom: { default: 1 },
+		limits: { default: [] },
+		current: { default: false }
+	};
+	/** NodePath of a Node2D to track. */
+	follow = "";
+	/** 0 = snap; 0.85–0.95 = smooth chase (per-frame retention at 60fps). */
+	smoothing = 0;
+	zoom = 1;
+	/** [minX, minY, maxX, maxY] world px; empty = unlimited. */
+	limits = [];
+	current = false;
+	/** `zoom` clamped to a positive floor — 0/negative zoom must never produce NaN views. */
+	get effectiveZoom() {
+		return Math.max(.01, this.zoom);
+	}
+	update(dt) {
+		if (!this.follow) return;
+		const target = this.getNodeOrNull(this.follow);
+		if (!(target instanceof Node2D)) return;
+		const tx = target.position[0] ?? 0;
+		const ty = target.position[1] ?? 0;
+		const s = Math.min(Math.max(this.smoothing, 0), .99);
+		const f = s <= 0 ? 1 : 1 - s ** (dt * 60);
+		const px = this.position[0] ?? 0;
+		const py = this.position[1] ?? 0;
+		this.position = [px + (tx - px) * f, py + (ty - py) * f];
+	}
+	/** View center after clamping the (vw×vh)/zoom view rect inside `limits`. */
+	clampedCenter(vw, vh) {
+		let cx = this.position[0] ?? 0;
+		let cy = this.position[1] ?? 0;
+		if (this.limits.length !== 0 && this.limits.length !== 4) throw new IncantoError("BAD_FORMAT", `Camera2D '${this.name}' limits must be [] or [minX,minY,maxX,maxY], got length ${this.limits.length}.`);
+		if (this.limits.length === 4) {
+			const [minX, minY, maxX, maxY] = this.limits;
+			const halfW = vw / (2 * this.effectiveZoom);
+			const halfH = vh / (2 * this.effectiveZoom);
+			cx = clampCentered(cx, minX + halfW, maxX - halfW);
+			cy = clampCentered(cy, minY + halfH, maxY - halfH);
+		}
+		return {
+			x: cx,
+			y: cy
+		};
+	}
+};
+function clampCentered(v, lo, hi) {
+	if (lo > hi) return (lo + hi) / 2;
+	return Math.min(hi, Math.max(lo, v));
+}
+//#endregion
+//#region src/2d/nodes/character-controller-2d.ts
+/**
+* Preset controller: drives its PARENT CharacterBody2D from the engine
+* InputMap — JSON-only games get a playable character with zero TypeScript.
+*
+* - `platformer`: x movement + gravity (from the scene `physics.gravity[1]`,
+*   default 980) + jump (`jumpHeight` px → impulse √(2·g·h))
+* - `topDown`: full-axis movement, no gravity
+*/
+var CharacterController2D = class extends Node {
+	static typeName = "CharacterController2D";
+	static props = {
+		mode: {
+			default: "platformer",
+			options: ["platformer", "topDown"]
+		},
+		maxSpeed: { default: 220 },
+		jumpHeight: { default: 64 },
+		moveAction: { default: "move" },
+		jumpAction: { default: "jump" }
+	};
+	mode = "platformer";
+	maxSpeed = 220;
+	/** Pixels (platformer mode). */
+	jumpHeight = 64;
+	moveAction = "move";
+	jumpAction = "jump";
+	onReady() {
+		if (!(this.parent instanceof CharacterBody2D)) throw new IncantoError("TREE_VIOLATION", `CharacterController2D '${this.name}' must be a child of a CharacterBody2D (parent is '${this.parent?.name ?? "none"}').`);
+		if (this.mode !== "platformer" && this.mode !== "topDown") throw new IncantoError("PROP_TYPE_MISMATCH", `CharacterController2D.mode must be 'platformer' or 'topDown', got '${this.mode}'.`);
+	}
+	fixedUpdate(dt) {
+		const engine = this.tree?.engine;
+		if (!engine?.scene) return;
+		const body = this.parent;
+		if (!(body instanceof CharacterBody2D)) return;
+		const input = engine.input;
+		const dir = input.getVector(this.moveAction);
+		if (this.mode === "topDown") {
+			body.velocity = [dir.x * this.maxSpeed, dir.y * this.maxSpeed];
+			body.moveAndSlide();
+			return;
+		}
+		const gravityY = (engine.scene.physics?.gravity)?.[1] ?? 980;
+		body.velocity[0] = dir.x * this.maxSpeed;
+		if (body.isOnFloor()) {
+			const jumped = input.justPressed(this.jumpAction);
+			body.velocity[1] = jumped ? -Math.sqrt(2 * gravityY * this.jumpHeight) : 20;
+		} else body.velocity[1] = (body.velocity[1] ?? 0) + gravityY * dt;
+		body.moveAndSlide();
+	}
+};
+//#endregion
+//#region src/2d/nodes/color-rect-2d.ts
+/** Shared unit quad (same discipline as sprites — never THREE.Sprite). */
+const UNIT_PLANE$1 = new PlaneGeometry(1, 1);
+/**
+* A solid-colored rectangle — no texture, no asset file. The prototyping
+* workhorse: paddles, walls, platforms, flashes, fade overlays. Swap in a
+* Sprite2D when art arrives.
+*/
+var ColorRect2D = class extends Node2D {
+	static typeName = "ColorRect2D";
+	static props = {
+		size: { default: [100, 100] },
+		color: { default: "#ffffff" },
+		opacity: { default: 1 },
+		anchor: { default: [.5, .5] }
+	};
+	/** [width, height] in world px. */
+	size = [100, 100];
+	color = "#ffffff";
+	opacity = 1;
+	/** [0,0] = top-left on the origin … [1,1] = bottom-right on the origin. */
+	anchor = [.5, .5];
+	quadMesh = null;
+	/** @internal The drawable quad (lazily created under the backing object). */
+	_quad() {
+		if (!this.quadMesh) {
+			this.quadMesh = new Mesh(UNIT_PLANE$1, new MeshBasicMaterial({
+				transparent: true,
+				depthWrite: false
+			}));
+			this._ensureObject2D().add(this.quadMesh);
+		}
+		return this.quadMesh;
+	}
+	_syncObject2D(assets) {
+		super._syncObject2D(assets);
+		const quad = this._quad();
+		const w = this.size[0] ?? 0;
+		const h = this.size[1] ?? 0;
+		quad.visible = w > 0 && h > 0 && this.opacity > 0;
+		quad.scale.set(w, h, 1);
+		const ax = this.anchor[0] ?? .5;
+		const ay = this.anchor[1] ?? .5;
+		quad.position.set((.5 - ax) * w, (ay - .5) * h, 0);
+		quad.renderOrder = this.renderOrder;
+		const mat = quad.material;
+		mat.color.set(this.color);
+		mat.opacity = this.opacity;
+	}
+};
+//#endregion
+//#region src/2d/nodes/label.ts
+const LABEL_PLANE = new PlaneGeometry(1, 1);
+/**
+* CanvasTexture-backed text (zero deps, WebGL-safe). Re-rasterizes only when
+* text props change. Headless-safe: without a DOM it simply stays hidden —
+* all prop/serialization logic still works.
+*/
+var Label = class extends Node2D {
+	static typeName = "Label";
+	static props = {
+		text: { default: "" },
+		fontSize: { default: 16 },
+		color: { default: "#ffffff" },
+		font: { default: "monospace" },
+		align: { default: "left" }
+	};
+	text = "";
+	fontSize = 16;
+	color = "#ffffff";
+	font = "monospace";
+	/** 'left' | 'center' | 'right' — anchor of the text block on the node origin. */
+	align = "left";
+	quadMesh = null;
+	canvas = null;
+	lastKey = "";
+	/** @internal */
+	_quad() {
+		if (!this.quadMesh) {
+			this.quadMesh = new Mesh(LABEL_PLANE, new MeshBasicMaterial({
+				transparent: true,
+				depthWrite: false
+			}));
+			this._ensureObject2D().add(this.quadMesh);
+		}
+		return this.quadMesh;
+	}
+	_syncObject2D(assets) {
+		super._syncObject2D(assets);
+		const quad = this._quad();
+		if (typeof document === "undefined" || this.text === "") {
+			quad.visible = false;
+			return;
+		}
+		const key = `${this.text}\0${this.fontSize}\0${this.color}\0${this.font}\0${this.align}`;
+		if (key !== this.lastKey) {
+			this.lastKey = key;
+			this.rasterize();
+		}
+		quad.visible = true;
+		quad.renderOrder = this.renderOrder;
+	}
+	rasterize() {
+		const dpr = Math.min(globalThis.devicePixelRatio ?? 1, 2);
+		this.canvas ??= document.createElement("canvas");
+		const ctx = this.canvas.getContext("2d");
+		if (!ctx) return;
+		const fontSpec = `${this.fontSize * dpr}px ${this.font}`;
+		ctx.font = fontSpec;
+		const metrics = ctx.measureText(this.text);
+		const w = Math.max(1, Math.ceil(metrics.width));
+		const h = Math.ceil(this.fontSize * dpr * 1.4);
+		this.canvas.width = w;
+		this.canvas.height = h;
+		ctx.font = fontSpec;
+		ctx.fillStyle = this.color;
+		ctx.textBaseline = "middle";
+		ctx.fillText(this.text, 0, h / 2);
+		const quad = this._quad();
+		const mat = quad.material;
+		mat.map?.dispose();
+		mat.map = new CanvasTexture(this.canvas);
+		mat.needsUpdate = true;
+		const cssW = w / dpr;
+		const cssH = h / dpr;
+		quad.scale.set(cssW, cssH, 1);
+		const ax = this.align === "center" ? .5 : this.align === "right" ? 1 : 0;
+		quad.position.set((.5 - ax) * cssW, 0, 0);
+	}
+};
+//#endregion
+//#region src/2d/nodes/particles-2d.ts
+const UNIT_PLANE = new PlaneGeometry(1, 1);
+/**
+* GPU-instanced particle emitter with predefined looks: set `preset` to
+* `'fire' | 'smoke' | 'sparks' | 'fireworks' | 'explosion' | 'flash' |
+* 'lightning' | 'rain' | 'snow' | 'magic'` and every prop snaps to that
+* look's baseline — any prop you write in the scene overrides it. `rate: 0`
+* + `burst` makes a one-shot that emits `finished` (queueFree it there).
+* Simulation is deterministic under the engine seed.
+*/
+var Particles2D = class Particles2D extends Node2D {
+	static typeName = "Particles2D";
+	static signals = ["finished"];
+	static props = {
+		preset: {
+			default: "custom",
+			options: ["custom", ...PARTICLE_PRESET_NAMES]
+		},
+		emitting: { default: true },
+		rate: { default: 40 },
+		burst: { default: 0 },
+		lifetime: { default: [.6, 1.2] },
+		speed: { default: [40, 120] },
+		directionDeg: { default: -90 },
+		spreadDeg: { default: 30 },
+		gravity: { default: [0, 0] },
+		drag: { default: 0 },
+		sizeStart: { default: 8 },
+		sizeEnd: { default: 2 },
+		colorStart: { default: "#ffffff" },
+		colorEnd: { default: "#ffffff" },
+		paletteColors: { default: [] },
+		alphaStart: { default: 1 },
+		alphaEnd: { default: 0 },
+		shimmer: { default: 0 },
+		blend: {
+			default: "add",
+			options: ["add", "normal"]
+		},
+		maxParticles: { default: 256 }
+	};
+	preset = "custom";
+	emitting = true;
+	rate = 40;
+	burst = 0;
+	lifetime = [.6, 1.2];
+	speed = [40, 120];
+	directionDeg = -90;
+	spreadDeg = 30;
+	gravity = [0, 0];
+	drag = 0;
+	sizeStart = 8;
+	sizeEnd = 2;
+	colorStart = "#ffffff";
+	colorEnd = "#ffffff";
+	/** Per-particle base colours sampled by the particle's stable seed (multi-
+	* colour confetti). Empty → the colorStart→colorEnd ramp is used unchanged. */
+	paletteColors = [];
+	alphaStart = 1;
+	alphaEnd = 0;
+	/** Per-particle alpha twinkle frequency in Hz (0 = off) — a seed-phased sine
+	* over the particle's age, so each sparkle glitters on its own rhythm. */
+	shimmer = 0;
+	blend = "add";
+	maxParticles = 256;
+	/** Loader hook: unknown presets and bad blends fail at LOAD. */
+	static validateJson(node) {
+		const p = node;
+		if (p.preset !== "custom" && !PARTICLE_PRESET_NAMES.includes(p.preset)) throw new IncantoError("BAD_FORMAT", `Particles2D '${node.name}' preset must be 'custom' or one of [${PARTICLE_PRESET_NAMES.join(", ")}], got '${p.preset}'.`, {
+			prop: "preset",
+			validOptions: PARTICLE_PRESET_NAMES
+		});
+		if (p.blend !== "add" && p.blend !== "normal") throw new IncantoError("BAD_FORMAT", `Particles2D '${node.name}' blend must be 'add' or 'normal', got '${p.blend}'.`, {
+			prop: "blend",
+			validOptions: ["add", "normal"]
+		});
+	}
+	sim = null;
+	bursted = false;
+	finishedEmitted = false;
+	/** @internal Lazily applies the preset + builds the deterministic sim. */
+	_ensureSim() {
+		if (!this.sim) {
+			applyParticlePreset(this, this.preset, getNodeSchema(Particles2D.typeName));
+			const rng = this.tree?.engine?.rng ?? new Rng(4660);
+			this.sim = new ParticleSim({
+				rate: this.emitting ? this.rate : 0,
+				lifetime: [this.lifetime[0] ?? 1, this.lifetime[1] ?? 1],
+				speed: [this.speed[0] ?? 0, this.speed[1] ?? 0],
+				directionDeg: this.directionDeg,
+				spreadDeg: this.spreadDeg,
+				gravity: [
+					this.gravity[0] ?? 0,
+					this.gravity[1] ?? 0,
+					0
+				],
+				drag: this.drag,
+				maxParticles: this.maxParticles
+			}, rng);
+		}
+		return this.sim;
+	}
+	update(dt) {
+		const sim = this._ensureSim();
+		if (this.burst > 0 && !this.bursted) {
+			this.bursted = true;
+			sim.burst(this.burst);
+		}
+		sim.update(dt);
+		if ((!this.emitting || this.rate === 0) && this.bursted && sim.done && !this.finishedEmitted) {
+			this.finishedEmitted = true;
+			this.emit("finished");
+		}
+	}
+	/** Restart a one-shot (re-burst + allow finished to fire again). */
+	replay() {
+		this.bursted = false;
+		this.finishedEmitted = false;
+	}
+	mesh = null;
+	/** Parsed `paletteColors`, reused; rebuilt only when the hex list changes. */
+	paletteCache = [];
+	paletteCacheKey = "";
+	/** Parse `paletteColors` into a reused `Color[]`, rebuilt only on change;
+	* null when empty so the caller uses the colorStart→colorEnd ramp. */
+	refreshPalette() {
+		const list = this.paletteColors;
+		if (list.length === 0) return null;
+		const key = list.join("|");
+		if (key !== this.paletteCacheKey) {
+			this.paletteCacheKey = key;
+			for (let i = 0; i < list.length; i++) {
+				let c = this.paletteCache[i];
+				if (!c) {
+					c = new Color();
+					this.paletteCache[i] = c;
+				}
+				c.set(list[i]);
+			}
+			this.paletteCache.length = list.length;
+		}
+		return this.paletteCache;
+	}
+	_syncObject2D(assets) {
+		super._syncObject2D(assets);
+		const sim = this._ensureSim();
+		if (!this.mesh || this.mesh.count !== this.maxParticles) {
+			if (this.mesh) this.mesh.removeFromParent();
+			const material = new MeshBasicMaterial({
+				transparent: true,
+				depthWrite: false,
+				blending: this.blend === "add" ? AdditiveBlending : NormalBlending
+			});
+			this.mesh = new InstancedMesh(UNIT_PLANE, material, this.maxParticles);
+			this.mesh.instanceMatrix.setUsage(DynamicDrawUsage);
+			this.mesh.frustumCulled = false;
+			this._ensureObject2D().add(this.mesh);
+		}
+		const mesh = this.mesh;
+		const palette = this.refreshPalette();
+		const start = palette ? null : colorScratchA.set(this.colorStart);
+		const end = colorScratchB.set(this.colorEnd);
+		const shimmerHz = this.shimmer;
+		let index = 0;
+		sim.forEach((p) => {
+			const size = this.sizeStart + (this.sizeEnd - this.sizeStart) * p.t;
+			matrixScratch.makeScale(size, size, 1);
+			matrixScratch.setPosition(p.x, -p.y, 0);
+			mesh.setMatrixAt(index, matrixScratch);
+			const base = palette ? palette[Math.floor(p.seed * palette.length)] : start;
+			let alpha = Math.max(0, this.alphaStart + (this.alphaEnd - this.alphaStart) * p.t);
+			if (shimmerHz > 0) alpha *= .5 + .5 * Math.sin(2 * Math.PI * (p.age * shimmerHz + p.seed));
+			colorScratchC.copy(base).lerp(end, p.t).multiplyScalar(alpha);
+			mesh.setColorAt(index, colorScratchC);
+			index += 1;
+		});
+		mesh.count = index;
+		mesh.instanceMatrix.needsUpdate = true;
+		if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
+		mesh.renderOrder = this.renderOrder;
+	}
+};
+const matrixScratch = new Matrix4();
+const colorScratchA = new Color();
+const colorScratchB = new Color();
+const colorScratchC = new Color();
+//#endregion
+//#region src/2d/nodes/ui-layer.ts
+const ANCHORS = [
+	"top-left",
+	"top",
+	"top-right",
+	"left",
+	"center",
+	"right",
+	"bottom-left",
+	"bottom",
+	"bottom-right"
+];
+/**
+* Screen-space container (Godot CanvasLayer): 2D descendants render in a
+* separate pass that ignores the world camera — HUDs, scores, menus.
+*
+* `anchor` pins the layer's origin to a screen corner/edge/center, so HUD
+* coordinates stay tiny offsets that survive any canvas size: a Label at
+* [-16, 16] under a 'top-right' layer hugs the top-right corner everywhere.
+*/
+var UILayer = class extends Node {
+	static typeName = "UILayer";
+	static props = { anchor: {
+		default: "top-left",
+		options: ANCHORS
+	} };
+	anchor = "top-left";
+	group = null;
+	/** @internal The three group all descendants mount under (lazily created). */
+	_ensureGroup() {
+		if (!this.group) {
+			this.group = new Group();
+			this.group.userData.incantoNode = this;
+		}
+		return this.group;
+	}
+	/** Loader hook: a misspelled anchor fails at LOAD, listing the valid set. */
+	static validateJson(node) {
+		const anchor = node.anchor;
+		if (!ANCHORS.includes(anchor)) throw new IncantoError("BAD_FORMAT", `UILayer '${node.name}' anchor must be one of [${ANCHORS.join(", ")}], got '${anchor}'.`, {
+			prop: "anchor",
+			validOptions: ANCHORS
+		});
+	}
+	/** @internal Anchor origin in y-down ui px for a given ui size. */
+	_anchorOrigin(width, height) {
+		const a = this.anchor;
+		return {
+			x: a.includes("right") ? width : a === "top" || a === "center" || a === "bottom" ? width / 2 : 0,
+			y: a.includes("bottom") ? height : a === "left" || a === "center" || a === "right" ? height / 2 : 0
+		};
+	}
+};
+//#endregion
+//#region src/2d/register.ts
+/**
+* Register the 2D node taxonomy (and the core nodes). Call once in your game
+* entry before loading a 2D scene. Explicit — never an import side effect.
+*/
+function registerNodes2D() {
+	registerCoreNodes();
+	registerNode(Node2D);
+	registerNode(Sprite2D);
+	registerNode(ColorRect2D);
+	registerNode(Particles2D);
+	registerNode(AnimatedSprite2D);
+	registerNode(Camera2D);
+	registerNode(Label);
+	registerNode(UILayer);
+	registerNode(StaticBody2D);
+	registerNode(RigidBody2D);
+	registerNode(Area2D);
+	registerNode(CharacterBody2D);
+	registerNode(CharacterController2D);
+}
+//#endregion
+export { ColorRect2D as a, AnimatedSprite2D as c, CharacterBody2D as d, PhysicsBody2D as f, validateCollider2D as g, Node2D as h, Label as i, Sprite2D as l, StaticBody2D as m, UILayer as n, CharacterController2D as o, RigidBody2D as p, Particles2D as r, Camera2D as s, registerNodes2D as t, Area2D as u };