incanto 0.74.0 → 0.76.0

package/dist/{register-DRQyZKGU.js → register-7E3P1gz6.js}

@@ -1,422 +1,11 @@
-import { J as Node, P as effectiveOrder, Y as diagnose } from "./save-slots-CEUGeLuB.js";
-import { M as translateOn, t as registerCoreNodes } from "./register-CjociOtt.js";
+import { $ as Node, et as diagnose, i as worldPosition, n as localFromWorld } from "./pose-ByFB_J3O.js";
+import { P as translateOn, t as registerCoreNodes } from "./register-B768Qedj.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { c as getNodeSchema, h as didYouMean, p as registerNode } from "./touch-CioTZB-y.js";
-import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimations, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-Bz3DHD_4.js";
-import { $ as localFromWorld, E as tolerateUnknownAction, O as effectRng, et as worldPosition } from "./gameplay-Bxe1sMVT.js";
+import { c as getNodeSchema, p as registerNode } from "./touch-CioTZB-y.js";
+import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimations, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-SQa5gIu2.js";
+import { Q as tolerateUnknownAction, V as effectRng, _ as Node2D, f as Area2D, g as StaticBody2D, h as RigidBody2D, m as PhysicsBody2D, p as CharacterBody2D, vt as findHealth } from "./gameplay-Bfff_beb.js";
 import { t as checkSheetGrid } from "./sheet-grid-Cea343VO.js";
-import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Color, DynamicDrawUsage, Group, InstancedMesh, MathUtils, Matrix4, Mesh, MeshBasicMaterial, NearestFilter, NormalBlending, Object3D, PlaneGeometry, SRGBColorSpace } 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.
-*/
-/**
-* Every key a 2D collider may carry.
-*
-* The shape was checked thoroughly and everything else let through, so
-* `{"shape": "circle", "radius": 8, "offest": [0, -24]}` loaded clean with its
-* hitbox at the body's origin — the exact defect `verify:playable` was written
-* for after it found hitboxes 155 px behind their own bodies in a starter.
-*/
-const COLLIDER_KEYS_2D = [
-	"shape",
-	"size",
-	"radius",
-	"height",
-	"offset",
-	"oneWay"
-];
-function validateCollider2D(collider, nodeName) {
-	const shape = collider.shape;
-	for (const key of Object.keys(collider)) {
-		if (COLLIDER_KEYS_2D.includes(key)) continue;
-		throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}' has an unknown key "${key}".` + didYouMean(key, COLLIDER_KEYS_2D) + ` A collider is [${COLLIDER_KEYS_2D.join(", ")}] — friction, restitution and mass are props of the BODY, not of its collider.`, {
-			prop: key,
-			validOptions: [...COLLIDER_KEYS_2D]
-		});
-	}
-	if (shape === void 0) return;
-	if (collider.oneWay !== void 0 && typeof collider.oneWay !== "boolean") throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}': "oneWay" must be a boolean (platforms you jump up through), got ${JSON.stringify(collider.oneWay)}.`);
-	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 },
-		static: { default: false },
-		scale: { default: [1, 1] },
-		renderOrder: { default: 0 },
-		orderGroup: {
-			default: "default",
-			options: [
-				"background",
-				"terrain",
-				"default",
-				"characters",
-				"effects",
-				"overlay"
-			]
-		},
-		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;
-	/** Frozen after first sync — see Node3D.static (same semantics in 2D). */
-	static = false;
-	scale = [1, 1];
-	/** Draw order among 2D drawables (higher = on top); matches 3D `renderOrder`. */
-	renderOrder = 0;
-	/** Named draw-order band; `renderOrder` is the fine offset inside it. */
-	orderGroup = "default";
-	/** What three actually sorts by: band base + renderOrder. */
-	get effectiveRenderOrder() {
-		return effectiveOrder(this.orderGroup, this.renderOrder, this.tree?.engine?.orderGroups);
-	}
-	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. */
-	/**
-	* Has this node produced the thing `static: true` is about to freeze?
-	*
-	* `static` latches after the first sync, and a textured node's first sync
-	* happens BEFORE its texture has decoded — `TextureLoader.load()` returns a
-	* `Texture` with `image === undefined` and fills it asynchronously, while
-	* `Renderer2D.render()` calls `assets.load()` and `syncTree2D()` in the same
-	* frame. So the state frozen was `visible = false`, forever. Measured on two
-	* identical sprites differing only in `static`:
-	*
-	* ```
-	* frame 1            Backdrop(static) visible: false   Control visible: false
-	* 600 frames later   Backdrop(static) visible: false width 1
-	*                    Control          visible: true  width 64
-	* ```
-	*
-	* Nothing throws: the texture loaded fine, so `assetErrors()` is empty,
-	* `stats().errors` is 0, and `framing` reads props rather than pixels and
-	* still calls the node on-screen. Overridden by the nodes that wait on an
-	* image; a node with nothing to wait for is ready by definition.
-	*/
-	_staticReady(_assets) {
-		return true;
-	}
-	_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: {},
-			variants: {
-				tag: "shape",
-				byTag: {
-					rect: {
-						shape: "rect",
-						size: [32, 32]
-					},
-					circle: {
-						shape: "circle",
-						radius: 16
-					},
-					capsule: {
-						shape: "capsule",
-						radius: 12,
-						height: 32
-					}
-				}
-			}
-		},
-		/**
-		* Whether this body's collider takes part in physics right now.
-		*
-		* A melee hitbox is off most of the time and live for a few frames of a
-		* swing, and there was no way to say so: games expressed it by REPLACING
-		* `collider` with `{}`, which tears the rigid body down and builds a new
-		* one twice per swing, and makes the engine warn `has no collider —
-		* physics skips it` about a scene that is correct. Keep the real collider
-		* and turn it off.
-		*
-		* Off means no contacts and no `triggerEnter`/`triggerExit`. The body
-		* itself stays, so nothing is rebuilt and re-arming is one call.
-		*/
-		enabled: { default: true }
-	};
-	/** The unified collision model: every collider participant can emit these. */
-	static signals = ["triggerEnter", "triggerExit"];
-	_collider = {};
-	/** @internal Physics resync flag — raised when `collider` is REPLACED. */
-	_colliderChanged = false;
-	_enabled = true;
-	/** @internal Physics resync flag — raised when `enabled` is written. */
-	_enabledChanged = false;
-	/**
-	* Collider shape prop. Change it by REPLACING the object
-	* (`body.collider = { shape: 'box', size: [...] }`) — physics rebuilds the
-	* body on replacement; in-place mutation of the old object is not watched.
-	*/
-	get collider() {
-		return this._collider;
-	}
-	set collider(value) {
-		this._collider = value;
-		this._colliderChanged = true;
-	}
-	/** See the `enabled` prop. Writing it arms or disarms the existing collider. */
-	get enabled() {
-		return this._enabled;
-	}
-	set enabled(value) {
-		if (value === this._enabled) return;
-		this._enabled = value;
-		this._enabledChanged = true;
-	}
-	/** 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).
-*
-* It also carries the SURFACE it is: `friction` and `restitution` used to
-* live on `RigidBody2D` 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 StaticBody2D = class extends PhysicsBody2D {
-	static typeName = "StaticBody2D";
-	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. 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";
-	/**
-	* Who is inside RIGHT NOW — the standing answer behind the enter/exit pair.
-	* See `Area3D.overlapping`. Empty in a scene with no physics world.
-	*/
-	overlapping(group = void 0) {
-		const all = this._physics?.overlapping(this) ?? [];
-		return group === void 0 ? all : all.filter((n) => n.isInGroup(group));
-	}
-};
-/** 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] },
-		angularVelocity: { default: 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. */
-	linearDamping = 0;
-	/** Rolling resistance, per second, on the spin — see `RigidBody3D.angularDamping`. */
-	angularDamping = 0;
-	/** px/s, y-down. Read back every step; write to launch. */
-	linearVelocity = [0, 0];
-	/**
-	* rad/s about the z axis — the same sign as `rotation`, which is CLOCKWISE
-	* in this y-down space. Read back every step; write to spin.
-	*
-	* `RigidBody3D` got its `angularVelocity` because "a puzzle builder could
-	* neither launch a spinning body nor read how fast a lever was swinging —
-	* only its angle, differenced by hand". Same sentence, same defect, other
-	* adapter: 2D had `linearVelocity` and no counterpart. `fixedRotation` pins
-	* it at zero.
-	*/
-	angularVelocity = 0;
-	/**
-	* The other name for `linearVelocity`, because it is the name every skill,
-	* every sibling node and every other engine uses.
-	*
-	* `body.velocity = [0, -400]` is what `incanto-physics-and-input.md` taught
-	* for years. On a plain TS class that assignment SUCCEEDS — it just writes a
-	* stray field nothing reads — so a jump that never happened produced no
-	* error, no warning and nothing to search for. `CharacterBody2D.velocity`
-	* next to `RigidBody2D.linearVelocity` is the kind of near-miss a builder
-	* cannot be expected to notice.
-	*
-	* Scene JSON still names the prop `linearVelocity` and rejects `velocity`
-	* loudly, with the valid keys listed — a hard error corrects itself.
-	*/
-	get velocity() {
-		return this.linearVelocity;
-	}
-	set velocity(v) {
-		this.linearVelocity = v;
-	}
-	/**
-	* Impulse in px·kg/s (y-down) — the 3D twin has had this since it shipped,
-	* and calling it here was a TypeError.
-	*/
-	applyImpulse(impulse) {
-		this._physics?.applyImpulse(this, impulse);
-	}
-};
-/**
-* 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] },
-		stickToGround: { default: true },
-		slopeLimitDeg: { default: 45 },
-		stepHeight: {
-			default: 35,
-			range: { min: 0 }
-		},
-		collideWithCharacters: { default: true }
-	};
-	/**
-	* Renamed to match the 3D body, where `snapToGround` had to give the name
-	* back to `Node3D`'s PLACEMENT prop. 2D has no placement prop, so nothing is
-	* ambiguous here and old scenes keep loading unchanged.
-	*/
-	static propAliases = { snapToGround: "stickToGround" };
-	/** px/s, y-down (up = -y). */
-	velocity = [0, 0];
-	/** Keep contact on slopes/steps while not moving upward. */
-	stickToGround = true;
-	/** Max climbable slope angle. */
-	slopeLimitDeg = 45;
-	/**
-	* How high a step this body walks up without jumping, in PIXELS.
-	*
-	* Rapier's character controller does not autostep unless it is asked, and in
-	* 2D nothing asked: a ledge of ANY height — measured, ONE pixel — stopped a
-	* walking body dead, while the mirrored `CharacterBody3D` has cleared 0.35 m
-	* by default since 0.63. The default here is that same 0.35 m at the 2D
-	* world's own scale (100 px = 1 m, which is why gravity defaults to 980).
-	* `0` restores the old behaviour.
-	*/
-	stepHeight = 35;
-	/** See CharacterBody3D.collideWithCharacters — off, a crowd ignores itself and costs nothing. */
-	collideWithCharacters = true;
-	/** @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);
-	}
-	/** @internal Set by the physics step from the KCC's resolved collisions. */
-	_onWall = 0;
-	/** @internal */
-	_onCeiling = false;
-	/**
-	* Touching a wall, and which side (-1 left, +1 right, 0 neither).
-	*
-	* Wall jump and wall slide are unbuildable without it — not awkward to build,
-	* impossible: `isOnFloor()` was the only surface a character could report, so
-	* even a hand-written behavior had nothing to ask.
-	*/
-	isOnWall() {
-		return this._onWall !== 0;
-	}
-	/** -1 the wall is to the left, +1 to the right, 0 no wall. */
-	wallSide() {
-		return this._onWall;
-	}
-	/** Head hit something — cut the jump short, the way every platformer does. */
-	isOnCeiling() {
-		return this._onCeiling;
-	}
-	isOnFloor() {
-		return this._grounded;
-	}
-};
-//#endregion
+import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Color, DynamicDrawUsage, Group, InstancedMesh, Matrix4, Mesh, MeshBasicMaterial, NearestFilter, NormalBlending, PlaneGeometry, SRGBColorSpace } from "three";
 //#region src/2d/nodes/joint-2d.ts
 /**
 * A physics joint linking its PARENT body to `target` (a node path to the
@@ -438,6 +27,7 @@ var Joint2D = class extends Node2D {
 			options: [
 				"fixed",
 				"revolute",
+				"prismatic",
 				"rope",
 				"spring"
 			]
@@ -449,6 +39,17 @@ var Joint2D = class extends Node2D {
 		},
 		anchor: { default: [0, 0] },
 		targetAnchor: { default: [0, 0] },
+		/** The line of a `prismatic` slide, in this body's local frame (y-down: `[0, -1]` is up). */
+		axis: { default: [0, 1] },
+		/** The stops: `[minDeg, maxDeg]` for a `revolute`, `[min, max]` px for a `prismatic`; empty = free. */
+		limits: { default: [] },
+		/** The motor's target speed — degrees a second (`revolute`) or px a second (`prismatic`); 0 = no motor. */
+		motorSpeed: { default: 0 },
+		/** How hard the motor holds its speed (acceleration per rad/s of error). */
+		motorStrength: {
+			default: 20,
+			range: { min: 0 }
+		},
 		length: { default: 0 },
 		stiffness: { default: 50 },
 		damping: { default: 5 },
@@ -461,6 +62,27 @@ var Joint2D = class extends Node2D {
 	target = "";
 	anchor = [0, 0];
 	targetAnchor = [0, 0];
+	/**
+	* `[min, max]` in degrees for a `revolute` swing; `[]` = no stops. Measured
+	* as `angle` is: this body turned relative to the target, `rotation`'s sign.
+	*/
+	limits = [];
+	/** Degrees a second the motor drives the pin at; `0` = no motor (free). */
+	motorSpeed = 0;
+	/** The motor's gain — how quickly it reaches and holds `motorSpeed`. */
+	motorStrength = 20;
+	/**
+	* The pin's current angle in degrees — this body's rotation relative to the
+	* target, written by physics every step. `0` unless `revolute` and simulated.
+	*/
+	angle = 0;
+	/** The line of a `prismatic` slide (local to this body). */
+	axis = [0, 1];
+	/**
+	* A `prismatic` slide's current travel in px — this body's anchor along
+	* `axis` relative to the target's; `0` where the anchors coincide.
+	*/
+	travel = 0;
 	/** rope/spring rest length in px; 0 = measure body distance at creation. */
 	length = 0;
 	stiffness = 50;
@@ -493,6 +115,8 @@ var Joint2D = class extends Node2D {
 	onEnterTree() {
 		if (!(this.parent instanceof PhysicsBody2D)) throw new IncantoError("TREE_VIOLATION", `Joint2D '${this.name}' must be a child of a physics body (its body A); parent is '${this.parent?.name ?? "none"}'.`);
 		if (this.target === "") throw new IncantoError("BAD_FORMAT", `Joint2D '${this.name}' needs a "target" node path to the body it links to.`);
+		if (this.type === "prismatic" && !(Math.hypot(this.axis[0] ?? 0, this.axis[1] ?? 0) > 1e-6)) throw new IncantoError("BAD_FORMAT", `Joint2D '${this.name}': a prismatic joint needs a non-zero "axis" (got ${JSON.stringify(this.axis)}).`);
+		if ((this.type === "revolute" || this.type === "prismatic") && this.limits.length !== 0 && this.limits.length !== 2) throw new IncantoError("BAD_FORMAT", `Joint2D '${this.name}': "limits" is [minDeg, maxDeg] or [] (got ${JSON.stringify(this.limits)}).`);
 	}
 	/** @internal The two bodies, resolved (throws on a bad target at step time). */
 	_resolveBodies() {
@@ -749,7 +373,7 @@ var AnimatedSprite2D = class extends Sprite2D {
 * 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 {
+var Camera2D = class Camera2D extends Node2D {
 	static typeName = "Camera2D";
 	static props = {
 		follow: {
@@ -759,7 +383,15 @@ var Camera2D = class extends Node2D {
 		smoothing: { default: 0 },
 		zoom: { default: 1 },
 		limits: { default: [] },
-		current: { default: false }
+		current: { default: false },
+		/**
+		* Seconds the view FLIES from the last drawn centre and zoom to this camera
+		* when it becomes current (0 = a cut) — the 2D twin of `Camera3D.blendSeconds`.
+		*/
+		blendSeconds: {
+			default: 0,
+			range: { min: 0 }
+		}
 	};
 	/** NodePath of a Node2D to track. */
 	follow = "";
@@ -769,6 +401,25 @@ var Camera2D = class extends Node2D {
 	/** [minX, minY, maxX, maxY] world px; empty = unlimited. */
 	limits = [];
 	current = false;
+	/**
+	* Make THIS the scene's camera and no other: the renderer takes the first
+	* camera whose `current` is true in tree order, so setting your own without
+	* clearing the gameplay camera's changed nothing visible. A handler a
+	* connection can name — `triggerEnter → DoorCam.makeCurrent`.
+	*/
+	makeCurrent(blendSeconds = void 0) {
+		const root = this.tree?.root ?? this.getRoot();
+		const walk = (n) => {
+			if (n instanceof Camera2D) n.current = n === this;
+			for (const c of n.children) walk(c);
+		};
+		walk(root);
+		this.current = true;
+		this._blendRequest = blendSeconds;
+	}
+	blendSeconds = 0;
+	/** @internal `makeCurrent(seconds)` — read once by the renderer. */
+	_blendRequest = void 0;
 	/** `zoom` clamped to a positive floor — 0/negative zoom must never produce NaN views. */
 	get effectiveZoom() {
 		return Math.max(.01, this.zoom);
@@ -860,7 +511,8 @@ function clampCentered(v, lo, hi) {
 const DEFAULT_ACTIONS = {
 	moveAction: "move",
 	jumpAction: "jump",
-	dashAction: "dash"
+	dashAction: "dash",
+	crouchAction: "crouch"
 };
 var CharacterController2D = class extends Node {
 	static typeName = "CharacterController2D";
@@ -888,7 +540,25 @@ var CharacterController2D = class extends Node {
 		/** 0 = no wall slide. Terminal fall speed while against a wall (px/s). */
 		wallSlideSpeed: { default: 0 },
 		/** 0 = no wall jump. `[away, up]` impulse in px/s. */
-		wallJumpImpulse: { default: [0, 0] }
+		wallJumpImpulse: { default: [0, 0] },
+		/**
+		* The collider's height (px) while the crouch key is held — a rect's
+		* `size[1]`, a capsule's `height`; 0 = no crouch. The body drops by half
+		* the difference so the feet stay put, a gap lower than the standing body
+		* is ducked through, and a ceiling that will not let you stand keeps you
+		* down until you are out from under it. Platformer mode only.
+		*/
+		crouchHeight: {
+			default: 0,
+			range: { min: 0 }
+		},
+		/** Pace while crouched, as a fraction of the standing pace. */
+		crouchSpeedMultiplier: {
+			default: .5,
+			range: { min: 0 }
+		},
+		/** Held = crouch. Missing from the input map = the character never crouches. */
+		crouchAction: { default: "crouch" }
 	};
 	static signals = ["movementStateChanged"];
 	mode = "platformer";
@@ -904,6 +574,13 @@ var CharacterController2D = class extends Node {
 	dashSpeed = 0;
 	dashSeconds = .15;
 	dashAction = "dash";
+	crouchHeight = 0;
+	crouchSpeedMultiplier = .5;
+	crouchAction = "crouch";
+	/** Read-only: shorter right now — by the key, or by a ceiling. */
+	crouching = false;
+	/** The collider height to stand back up to. */
+	standingHeight = 0;
 	wallSlideSpeed = 0;
 	wallJumpImpulse = [0, 0];
 	/** What the character is doing — drive `AnimatedSprite2D.play(state)` off it. */
@@ -928,13 +605,20 @@ var CharacterController2D = class extends Node {
 			x: 0,
 			y: 0
 		}, "the character will not move");
+		const health = findHealth(body)?.health ?? null;
+		if (health?.staggered ?? false) {
+			dir.x = 0;
+			dir.y = 0;
+		}
+		const kick = health?.knocked ? health.kickVelocity : [];
+		const lift = health?.knocked ? health.takeLift() : 0;
 		if (this.mode === "topDown") {
-			body.velocity = [dir.x * this.maxSpeed, dir.y * this.maxSpeed];
+			body.velocity = kick.length > 0 ? [kick[0] ?? 0, kick[1] ?? 0] : [dir.x * this.maxSpeed, dir.y * this.maxSpeed];
 			body.moveAndSlide();
 			return;
 		}
 		const gravityY = (engine.scene.physics?.gravity)?.[1] ?? 980;
-		const grounded = body.isOnFloor();
+		const grounded = body.isOnFloor() && !(this.rising && (body.velocity[1] ?? 0) < 0);
 		const jumpImpulse = -Math.sqrt(2 * gravityY * this.jumpHeight);
 		if (this.dashLeft > 0) {
 			this.dashLeft -= dt;
@@ -953,7 +637,24 @@ var CharacterController2D = class extends Node {
 			this.setState("dash");
 			return;
 		}
-		body.velocity[0] = dir.x * this.maxSpeed;
+		body.velocity[0] = kick.length > 0 ? kick[0] ?? 0 : dir.x * this.maxSpeed;
+		const wantCrouch = this.crouchHeight > 0 && this.readAction("crouchAction", () => input.isPressed(this.crouchAction), false, "the character will never crouch");
+		if (!this.crouching) {
+			const standing = colliderHeight(body.collider);
+			if (wantCrouch && grounded && this.crouchHeight < standing) {
+				this.standingHeight = standing;
+				this.crouching = true;
+				setColliderHeight(body, this.crouchHeight, standing);
+			}
+		} else if (!wantCrouch) {
+			const rise = this.standingHeight - this.crouchHeight;
+			const top = (body.position[1] ?? 0) - halfExtent(body.collider) + 1;
+			if (!body._physics?.castRay([body.position[0] ?? 0, top], [0, -1], rise + 2, body)) {
+				this.crouching = false;
+				setColliderHeight(body, this.standingHeight, this.crouchHeight);
+			}
+		}
+		if (this.crouching) body.velocity[0] = (body.velocity[0] ?? 0) * this.crouchSpeedMultiplier;
 		if (grounded) {
 			this.coyoteLeft = this.coyoteSeconds;
 			this.jumpsUsed = 0;
@@ -964,7 +665,11 @@ var CharacterController2D = class extends Node {
 		const jumpEdge = this.readAction("jumpAction", () => input.justPressed(this.jumpAction), false, "the character will never jump");
 		if (jumpEdge) this.bufferLeft = Math.max(this.jumpBufferSeconds, 0);
 		else this.bufferLeft = Math.max(0, this.bufferLeft - dt);
-		const wantsJump = this.bufferLeft > 0 || jumpEdge;
+		let wantsJump = this.bufferLeft > 0 || jumpEdge;
+		if (this.crouching) {
+			wantsJump = false;
+			this.bufferLeft = 0;
+		}
 		const onWall = this.wallSlideSpeed > 0 || this.wallJumpImpulse.some((v) => v !== 0) ? body.isOnWall() : false;
 		if (wantsJump && onWall && !grounded && this.wallJumpImpulse.some((v) => v !== 0)) {
 			const away = -body.wallSide();
@@ -992,6 +697,10 @@ var CharacterController2D = class extends Node {
 			if ((body.velocity[1] ?? 0) >= 0) this.rising = false;
 			if (this.wallSlideSpeed > 0 && onWall && (body.velocity[1] ?? 0) > this.wallSlideSpeed) body.velocity[1] = this.wallSlideSpeed;
 		}
+		if (lift !== 0) {
+			body.velocity[1] = lift;
+			if (lift < 0) this.rising = true;
+		}
 		if (body.isOnCeiling() && (body.velocity[1] ?? 0) < 0) {
 			body.velocity[1] = 0;
 			this.rising = false;
@@ -999,8 +708,10 @@ var CharacterController2D = class extends Node {
 		body.moveAndSlide();
 		const vy = body.velocity[1] ?? 0;
 		if (this.wallSlideSpeed > 0 && !body.isOnFloor() && body.isOnWall() && vy > 0) this.setState("wallSlide");
-		else if (body.isOnFloor()) this.setState(Math.abs(dir.x) > .01 ? "run" : "idle");
-		else this.setState(vy < 0 ? "jump" : "fall");
+		else if (body.isOnFloor()) {
+			const moving = Math.abs(dir.x) > .01;
+			this.setState(this.crouching ? moving ? "sneak" : "crouch" : moving ? "run" : "idle");
+		} else this.setState(vy < 0 ? "jump" : "fall");
 	}
 	/**
 	* Emits `movementStateChanged(state)` on a change — the 3D sibling has had
@@ -1045,6 +756,40 @@ var CharacterController2D = class extends Node {
 		}, action, read, fallback);
 	}
 };
+/** The collider's height along y: a rect's size[1], a capsule's straight part; a circle cannot crouch (0). */
+function colliderHeight(c) {
+	if (c.shape === "rect") return c.size?.[1] ?? 0;
+	if (c.shape === "capsule") return c.height ?? 0;
+	return 0;
+}
+/** Half the collider's full extent along y — where its top and bottom edges are. */
+function halfExtent(c) {
+	if (c.shape === "rect") return (c.size?.[1] ?? 0) / 2;
+	if (c.shape === "capsule") return (c.height ?? 0) / 2 + (c.radius ?? 0);
+	return c.radius ?? 0;
+}
+/**
+* Swap the collider's height and keep the feet where they are: y-down, so a
+* shorter body's centre moves DOWN by half the difference (and back up on
+* standing). The adapter rebuilds the body at the new place next step.
+*/
+function setColliderHeight(body, next, from) {
+	const c = body.collider;
+	if (c.shape === "rect") {
+		const size = c.size ?? [32, from];
+		body.collider = {
+			...c,
+			size: [size[0] ?? 32, next]
+		};
+	} else if (c.shape === "capsule") body.collider = {
+		...c,
+		height: next
+	};
+	else return;
+	const d = (from - next) / 2;
+	const p = body.position;
+	body.position = [p[0] ?? 0, (p[1] ?? 0) + d];
+}
 //#endregion
 //#region src/2d/nodes/color-rect-2d.ts
 /** Shared unit quad (same discipline as sprites — never THREE.Sprite). */
@@ -1307,7 +1052,11 @@ var Particles2D = class Particles2D extends Node2D {
 			default: "add",
 			options: ["add", "normal"]
 		},
-		maxParticles: { default: 256 }
+		maxParticles: { default: 256 },
+		/** Half-extents (px) of a box the particles are born in, around the node; `[0,0]` = a point. */
+		emitBox: { default: [0, 0] },
+		/** A steady velocity (px/s, y+ = down) every particle is born with — wind on smoke. */
+		drift: { default: [0, 0] }
 	};
 	preset = "custom";
 	emitting = true;
@@ -1345,6 +1094,8 @@ var Particles2D = class Particles2D extends Node2D {
 	shimmer = 0;
 	blend = "add";
 	maxParticles = 256;
+	emitBox = [0, 0];
+	drift = [0, 0];
 	/** Loader hook: unknown presets and bad blends fail at LOAD. */
 	static validateJson(node) {
 		const p = node;
@@ -1377,7 +1128,17 @@ var Particles2D = class Particles2D extends Node2D {
 					0
 				],
 				drag: this.drag,
-				maxParticles: this.maxParticles
+				maxParticles: this.maxParticles,
+				emitBox: [
+					this.emitBox[0] ?? 0,
+					this.emitBox[1] ?? 0,
+					0
+				],
+				drift: [
+					this.drift[0] ?? 0,
+					this.drift[1] ?? 0,
+					0
+				]
 			}, rng);
 		}
 		return this.sim;
@@ -2125,4 +1886,4 @@ function registerNodes2D() {
 	registerNode(TileMap2D);
 }
 //#endregion
-export { RigidBody2D as _, parseCells as a, validateCollider2D as b, ColorRect2D as c, AnimatedSprite2D as d, Sprite2D as f, PhysicsBody2D as g, CharacterBody2D as h, mergeSolidRects as i, CharacterController2D as l, Area2D as m, UILayer as n, Particles2D as o, Joint2D as p, TileMap2D as r, Label as s, registerNodes2D as t, Camera2D as u, StaticBody2D as v, Node2D as y };
+export { parseCells as a, ColorRect2D as c, AnimatedSprite2D as d, Sprite2D as f, mergeSolidRects as i, CharacterController2D as l, UILayer as n, Particles2D as o, Joint2D as p, TileMap2D as r, Label as s, registerNodes2D as t, Camera2D as u };