incanto 0.74.0 → 0.75.0

package/dist/{environment-presets-BkqlWewf.js → environment-presets-BP77Dl0K.js}

@@ -1,11 +1,11 @@
-import { Y as diagnose } from "./save-slots-CEUGeLuB.js";
-import { M as translateOn, t as registerCoreNodes } from "./register-CjociOtt.js";
+import { et as diagnose, h as rebuildOptions, i as worldPosition, v as buildNodeJson } 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 { t as Rng } from "./rng-CDOMybym.js";
 import { c as getNodeSchema, h as didYouMean, p as registerNode } from "./touch-CioTZB-y.js";
 import { t as createNoise2D } from "./noise-D3nPpmFg.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 { E as tolerateUnknownAction, G as PhysicsBody3D, H as rejectScale, J as Node3D, K as RigidBody3D, O as effectRng, Q as colliderFootDrop, U as Area3D, V as WaterCutout3D, W as CharacterBody3D, et as worldPosition, q as StaticBody3D, z as Water3D } from "./gameplay-Bxe1sMVT.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 { $ as Water3D, Q as tolerateUnknownAction, V as effectRng, at as PhysicsBody3D, ct as Node3D, ft as colliderFootDrop, ht as findHealth, it as CharacterBody3D, nt as rejectScale, ot as RigidBody3D, rt as Area3D, st as StaticBody3D, tt as WaterCutout3D } from "./gameplay-D-JuGura.js";
 import { t as checkSheetGrid } from "./sheet-grid-Cea343VO.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-BYgD5Edk.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, MathUtils, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, SpotLight, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
@@ -752,9 +752,14 @@ const matScratch = new Matrix4();
 *     "props": { "type": "spherical", "target": "%Anchor", "anchor": [0, -20] } }
 *
 * Types: `fixed` welds the bodies rigidly · `spherical` is a ball joint at the
-* anchors · `rope` caps the anchor distance at `length` (m; 0 = measured at
-* creation) · `spring` pulls toward `length` with `stiffness`/`damping`.
-* Anchors are LOCAL meter offsets on each body.
+* anchors · `revolute` is a HINGE about `axis` (a door, a wheel, a lever) with
+* optional `limits` (degrees) and a `motorSpeed` (degrees a second) ·
+* `prismatic` is a SLIDE along `axis` (a portcullis, an elevator, a piston)
+* with `limits` in metres, a `motorSpeed` in metres a second and `travel`
+* read back · `rope`
+* caps the anchor distance at `length` (m; 0 = measured at creation) ·
+* `spring` pulls toward `length` with `stiffness`/`damping`. Anchors are LOCAL
+* meter offsets on each body; `angle` reads the hinge back.
 */
 var Joint3D = class extends Node3D {
 	static typeName = "Joint3D";
@@ -764,6 +769,8 @@ var Joint3D = class extends Node3D {
 			options: [
 				"fixed",
 				"spherical",
+				"revolute",
+				"prismatic",
 				"rope",
 				"spring"
 			]
@@ -783,6 +790,21 @@ var Joint3D = class extends Node3D {
 			0,
 			0
 		] },
+		/** The hinge axis of a `revolute`, or the line of a `prismatic`, in this body's local frame. */
+		axis: { default: [
+			0,
+			1,
+			0
+		] },
+		/** The stops: `[minDeg, maxDeg]` for a `revolute`, `[min, max]` metres for a `prismatic`; empty = free. */
+		limits: { default: [] },
+		/** The motor's target speed — degrees a second (`revolute`) or metres 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 },
@@ -792,6 +814,33 @@ var Joint3D = class extends Node3D {
 		}
 	};
 	type = "spherical";
+	/** Hinge axis of a `revolute`, or the line of a `prismatic` (local to this body). */
+	axis = [
+		0,
+		1,
+		0
+	];
+	/**
+	* `[min, max]` in degrees for a `revolute` swing; `[]` = no stops. Measured
+	* as `angle` is: this body turned about `axis`, relative to the target.
+	*/
+	limits = [];
+	/** Degrees a second the motor drives the hinge at; `0` = no motor (free). */
+	motorSpeed = 0;
+	/** The motor's gain — how quickly it reaches and holds `motorSpeed`. */
+	motorStrength = 20;
+	/**
+	* The hinge's current angle in degrees — this body's rotation about `axis`
+	* relative to the target, written by physics every step. `0` when the joint
+	* is not a `revolute` or is not simulated yet.
+	*/
+	angle = 0;
+	/**
+	* A `prismatic` slide's current travel in metres — this body's anchor along
+	* `axis` relative to the target's, written by physics every step. `0` where
+	* the two anchors coincide, which is where the scene loaded it.
+	*/
+	travel = 0;
 	target = "";
 	anchor = [
 		0,
@@ -835,6 +884,11 @@ var Joint3D = class extends Node3D {
 	onEnterTree() {
 		if (!(this.parent instanceof PhysicsBody3D)) throw new IncantoError("TREE_VIOLATION", `Joint3D '${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", `Joint3D '${this.name}' needs a "target" node path to the body it links to.`);
+		if (this.type === "revolute" || this.type === "prismatic") {
+			const [x, y, z] = this.axis;
+			if (!(Math.hypot(x ?? 0, y ?? 0, z ?? 0) > 1e-6)) throw new IncantoError("BAD_FORMAT", `Joint3D '${this.name}': a ${this.type} joint needs a non-zero "axis" (got ${JSON.stringify(this.axis)}).`);
+			if (this.limits.length !== 0 && this.limits.length !== 2) throw new IncantoError("BAD_FORMAT", `Joint3D '${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() {
@@ -852,6 +906,25 @@ var Joint3D = class extends Node3D {
 	}
 };
 //#endregion
+//#region src/3d/terrain/course.ts
+/** Is this a point either spelling accepts? */
+function isCoursePoint(p) {
+	if (!Array.isArray(p)) return false;
+	if (p.length === 2) return Number.isFinite(p[0]) && Number.isFinite(p[1]);
+	if (p.length === 3) return Number.isFinite(p[0]) && Number.isFinite(p[1]) && Number.isFinite(p[2]);
+	return false;
+}
+/** The `[x, z]` of a point in either spelling. Assumes `isCoursePoint`. */
+function coursePoint(p) {
+	return p.length === 3 ? [p[0] ?? 0, p[2] ?? 0] : [p[0] ?? 0, p[1] ?? 0];
+}
+/** A whole course, flattened to `[x, z]` whichever way it was written. */
+function course(path) {
+	return path.map((p) => coursePoint(p));
+}
+/** What to tell an author who wrote neither spelling. */
+const COURSE_SHAPE = "[x, z] — or [x, y, z], whose y is ignored";
+//#endregion
 //#region src/3d/terrain/splat-material.ts
 /** Splice `code` immediately AFTER `marker` — a missing marker is a hard error
 * (a silently unpatched terrain shader renders weight-colored vertex soup). */
@@ -1716,7 +1789,7 @@ var Terrain3D = class extends Node3D {
 		if (!Array.isArray(t.channels)) throw new IncantoError("BAD_FORMAT", `Terrain3D '${node.name}' channels must be an array of { path, width, depth, taper? }, got ${JSON.stringify(t.channels)}.`, { prop: "channels" });
 		t.channels.forEach((c, i) => {
 			const path = c.path;
-			if (!(c && typeof c === "object" && Array.isArray(path) && path.length >= 2 && path.every((p) => Array.isArray(p) && Number.isFinite(p[0]) && Number.isFinite(p[1])) && c.width > 0 && c.depth > 0 && (c.taper === void 0 || c.taper > 0))) throw new IncantoError("BAD_FORMAT", `Terrain3D '${node.name}' channels[${i}] needs a path of 2+ [x, z] points plus positive width and depth, got ${JSON.stringify(c)}.`, { prop: "channels" });
+			if (!(c && typeof c === "object" && Array.isArray(path) && path.length >= 2 && path.every(isCoursePoint) && c.width > 0 && c.depth > 0 && (c.taper === void 0 || c.taper > 0))) throw new IncantoError("BAD_FORMAT", `Terrain3D '${node.name}' channels[${i}] needs a path of 2+ ${COURSE_SHAPE} points plus positive width and depth, got ${JSON.stringify(c)}.`, { prop: "channels" });
 		});
 		if (t.theme === "custom") {
 			if (!Array.isArray(t.layers) || t.layers.length < 1 || t.layers.length > 4) throw new IncantoError("BAD_FORMAT", `Terrain3D '${node.name}' theme 'custom' needs 1–4 layers, got ${Array.isArray(t.layers) ? t.layers.length : typeof t.layers}.`, { prop: "layers" });
@@ -1759,10 +1832,17 @@ var Terrain3D = class extends Node3D {
 		else this.externalChannels.set(owner, specs);
 		this.externalRev++;
 	}
-	/** Authored trenches plus the ones other nodes cut. */
+	/**
+	* Authored trenches plus the ones other nodes cut — every course flattened to
+	* `[x, z]`, whichever spelling it was written in (see `course`).
+	*/
 	allChannels() {
-		if (this.externalChannels.size === 0) return this.channels;
-		return [...this.channels, ...[...this.externalChannels.values()].flat()];
+		const mine = this.channels.map((c) => ({
+			...c,
+			path: course(c.path)
+		}));
+		if (this.externalChannels.size === 0) return mine;
+		return [...mine, ...[...this.externalChannels.values()].flat()];
 	}
 	/** @internal The pure heightfield (lazily built — physics pulls this). */
 	_heightmap() {
@@ -2613,6 +2693,18 @@ var BoneLookAt3D = class extends Node3D {
 	lookedUpFor = "";
 	/** 0..1 engage blend — eases in/out so tracking never snaps. */
 	engage = 0;
+	/**
+	* How far the head is COMMITTED to the target, 0..1.
+	*
+	* `attachedBone` was a test hook for "did it find the bone"; this is the one
+	* for "is it watching" — the whole observable effect of the node, and it eased
+	* in and out where nothing could read it. A harness asking whether an NPC
+	* tracks the player, and lets go when the player walks behind it, has no other
+	* question to ask.
+	*/
+	get engaged() {
+		return this.engage;
+	}
 	/** Test hook. */
 	get attachedBone() {
 		return this.boneObj;
@@ -2679,7 +2771,7 @@ const parentScratch = new Quaternion();
 const quatScratch$1 = new Quaternion();
 //#endregion
 //#region src/3d/nodes/look-at.ts
-const RAD2DEG$1 = 180 / Math.PI;
+const RAD2DEG$5 = 180 / Math.PI;
 /** World up. The whole fix is that this argument exists. */
 const UP = new Vector3(0, 1, 0);
 const eyeScratch = new Vector3();
@@ -2722,20 +2814,22 @@ function aimAt(node, warned, what) {
 	lookScratch.lookAt(eyeScratch, targetScratch, UP);
 	eulerScratch$1.setFromRotationMatrix(lookScratch, "XYZ");
 	node.rotation = [
-		eulerScratch$1.x * RAD2DEG$1,
-		eulerScratch$1.y * RAD2DEG$1,
-		eulerScratch$1.z * RAD2DEG$1
+		eulerScratch$1.x * RAD2DEG$5,
+		eulerScratch$1.y * RAD2DEG$5,
+		eulerScratch$1.z * RAD2DEG$5
 	];
 	return warned;
 }
 //#endregion
 //#region src/3d/nodes/camera-3d.ts
+const DEG2RAD$1 = Math.PI / 180;
+const RAD2DEG$4 = 180 / Math.PI;
 /**
 * A perspective camera. Mark exactly one camera `current: true`; with none
 * marked, the renderer falls back to the first camera in tree order.
 * Aspect ratio is managed by the renderer on resize.
 */
-var Camera3D = class extends Node3D {
+var Camera3D = class Camera3D extends Node3D {
 	static typeName = "Camera3D";
 	static props = {
 		fov: {
@@ -2747,6 +2841,27 @@ var Camera3D = class extends Node3D {
 				exclusiveMax: true
 			}
 		},
+		/**
+		* The least the player must see ACROSS, in degrees. `0` = off.
+		*
+		* `fov` is the VERTICAL field of view and the aspect comes from the canvas,
+		* so a `fov: 60` camera shows 91° across a 16:9 window and **30° across a
+		* 390×844 phone** — the same game, down a keyhole, held in portrait. Ask
+		* for a width and the vertical fov widens until the screen carries it;
+		* a window already wider than that keeps the fov it was authored with, so
+		* this only ever ADDS view on a narrow screen.
+		*
+		* `65` is a good floor for a third-person game meant to be playable in one
+		* hand. Off by default: no existing scene's framing moves.
+		*/
+		minHorizontalFov: {
+			default: 0,
+			range: {
+				min: 0,
+				max: 180,
+				exclusiveMax: true
+			}
+		},
 		near: {
 			default: .1,
 			range: {
@@ -2765,6 +2880,17 @@ var Camera3D = class extends Node3D {
 		lookAt: {
 			default: "",
 			nodePath: true
+		},
+		/**
+		* Seconds the renderer FLIES from the last drawn pose to this camera when
+		* it becomes current (0 = a cut). Every switch used to be a cut — a
+		* cutscene's door camera, the return to play, a chase camera taking over.
+		* The camera nodes are untouched: picking, framing and the editor read
+		* the node; only the picture takes the long way round.
+		*/
+		blendSeconds: {
+			default: 0,
+			range: { min: 0 }
 		}
 	};
 	/** A frustum whose planes are the wrong way round draws nothing at all. */
@@ -2773,9 +2899,29 @@ var Camera3D = class extends Node3D {
 		if (self.near >= self.far) throw new IncantoError("PROP_TYPE_MISMATCH", `Camera3D '${node.name}' has an inverted depth range: near ${self.near} is not less than far ${self.far}. The near plane is the closest thing this camera can see and the far plane the furthest.`);
 	}
 	fov = 60;
+	minHorizontalFov = 0;
 	near = .1;
 	far = 1e3;
 	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 Camera3D) 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's sync. */
+	_blendRequest = void 0;
 	lookAt = "";
 	/**
 	* Aim, every frame, whenever `lookAt` names something — see `aimAt`, which
@@ -2789,11 +2935,26 @@ var Camera3D = class extends Node3D {
 	_createObject3D() {
 		return new PerspectiveCamera(this.fov, 1, this.near, this.far);
 	}
+	/**
+	* The vertical fov to actually render with at this aspect.
+	*
+	* Plain `fov` unless `minHorizontalFov` asks for more width than the screen
+	* carries, in which case it is widened until it does. Public because a game
+	* that wants to know what it is really showing — a harness, a debug overlay —
+	* could not otherwise ask, and the answer is not the authored number.
+	*/
+	viewFov(aspect) {
+		if (!(this.minHorizontalFov > 0) || !(aspect > 0)) return this.fov;
+		const half = this.minHorizontalFov / 2 * DEG2RAD$1;
+		const wanted = 2 * Math.atan(Math.tan(half) / aspect) * RAD2DEG$4;
+		return Math.min(179.9, Math.max(this.fov, wanted));
+	}
 	_syncObject3D() {
 		super._syncObject3D();
 		const cam = this._ensureObject3D();
-		if (cam.fov !== this.fov || cam.near !== this.near || cam.far !== this.far) {
-			cam.fov = this.fov;
+		const fov = this.viewFov(cam.aspect);
+		if (cam.fov !== fov || cam.near !== this.near || cam.far !== this.far) {
+			cam.fov = fov;
 			cam.near = this.near;
 			cam.far = this.far;
 			cam.updateProjectionMatrix();
@@ -2811,7 +2972,12 @@ const MOVEMENT_STATES = [
 	"walk",
 	"run",
 	"fastRun",
-	"airborne"
+	"airborne",
+	"swim",
+	"climb",
+	"crouch",
+	"sneak",
+	"dash"
 ];
 /** Air control stands down this long after a wall kick, so the kick lands. */
 const WALL_LOCKOUT_SECONDS = .18;
@@ -2820,13 +2986,27 @@ const DRAG_DAMPING = .15;
 const SPRING_K = 1.2;
 const SPRING_DAMPING = .08;
 const FALLING_MAX_VEL = -20;
+/** The swim spring: how hard the water returns the body to its waterline (1/s²) and damps it (1/s). */
+const SWIM_K = 30;
+const SWIM_DAMPING = 8;
+/** Lift cap while swimming, in g — water pushes back; it does not launch. */
+const SWIM_MAX_G = 3;
+const STANDARD_G = 9.81;
+/** A probe hit closer than this began inside the collider it hit. */
+const INSIDE_HIT = 1e-4;
+/** How fast a swimmer pulls themselves up onto a ledge (m/s). */
+const CLIMB_SPEED = 2;
+/** After letting go of a ladder, this long before it can be grabbed again (s). */
+const LADDER_LOCKOUT = .35;
+/** How often the controller re-scans the tree for Water3D nodes (fixed steps). */
+const WATER_SCAN_STEPS = 60;
 /** The schema's own default for an action prop — never a second copy of it. */
 function defaultActionOf(prop) {
 	const schema = CharacterController3D.props[prop];
 	return typeof schema?.default === "string" ? schema.default : "";
 }
 const LOOK_SPEED = .002;
-const RAD2DEG = 180 / Math.PI;
+const RAD2DEG$3 = 180 / Math.PI;
 /** Spring-arm camera collision: keep the camera this far in front of an obstacle. */
 const CAM_COLLISION_MARGIN = .3;
 /** Never pull the orbit camera closer to the eye than this (avoids clipping into the skin). */
@@ -2853,8 +3033,21 @@ const UP_VEC = new Vector3(0, 1, 0);
 */
 var CharacterController3D = class extends Node3D {
 	static typeName = "CharacterController3D";
-	static signals = ["movementStateChanged", "wallJumped"];
+	static signals = [
+		"movementStateChanged",
+		"wallJumped",
+		"lockChanged",
+		"dashed"
+	];
 	static props = {
+		/**
+		* Off = the controller lets go: no input, no forces, no camera, no
+		* animation — the body is an ordinary RigidBody3D until it is on again.
+		* The switch a game flips when the player gets into a car, sits in a
+		* cutscene or opens a menu; flip the body's `enabled`/`visible` beside it
+		* to park the character out of sight.
+		*/
+		enabled: { default: true },
 		view: {
 			default: "free",
 			options: [
@@ -2889,12 +3082,105 @@ var CharacterController3D = class extends Node3D {
 		fallGravity: { default: 2.5 },
 		floatHeight: { default: .01 },
 		stepHeight: { default: .35 },
+		/** Swimming pace (m/s) in water too deep to stand in; 0 = no swimming (the body sinks). */
+		swimSpeed: { default: 1.6 },
+		/** How far the body's origin rides BELOW the surface while swimming (m). */
+		swimDepth: { default: .35 },
+		/** Held: swim DOWN at `swimSpeed`. Absent from the input map = no diving. */
+		diveAction: { default: "dive" },
+		/** Ladder pace (m/s): push UP into an Area3D in `ladderGroup` and the body climbs it; 0 = no ladders. */
+		climbSpeed: { default: 1.5 },
+		/** Any Area3D in this group is a ladder. */
+		ladderGroup: { default: "ladder" },
+		/** On the way down from a jump, a ledge ahead no higher than this above the capsule's bottom is caught and pulled up onto (m); 0 = off. */
+		mantleHeight: {
+			default: 0,
+			range: { min: 0 }
+		},
+		/**
+		* The capsule's height while the crouch key is held (m); 0 = no crouch.
+		* The body sinks by half the difference so the feet stay put, a duct
+		* lower than the standing capsule is crawled through, and a ceiling that
+		* will not let you stand keeps you down until you are out from under it.
+		*/
+		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" },
+		/**
+		* A roll: this fast (m/s) for `dashSeconds`, where the stick points or —
+		* with no stick — where the skin faces; 0 = no dash. The velocity is held
+		* for the roll's frames (the controller brakes toward its own pace every
+		* step, so a single impulse dies), `state` reads `dash`, and `dashed`
+		* fires once per roll — hang the i-frames on it (`Health.protect`).
+		*/
+		dashSpeed: {
+			default: 0,
+			range: { min: 0 }
+		},
+		dashSeconds: {
+			default: .25,
+			range: { min: 0 }
+		},
+		/** Seconds after a roll ends before the next can start. */
+		dashCooldown: {
+			default: 0,
+			range: { min: 0 }
+		},
+		/** Pressed = roll. Missing from the input map = the character never dashes. */
+		dashAction: { default: "dash" },
+		/**
+		* With no stick, roll BACKWARD — away from where the skin faces — instead
+		* of forward: the Souls-like backstep a lock-on game wants (a neutral
+		* roll into the thing you are locked on is the wrong way).
+		*/
+		dashBackstep: { default: false },
 		mouseLook: { default: true },
 		zoomMin: { default: 0 },
 		zoomMax: { default: 0 },
 		pitchMin: { default: -1.3 },
 		pitchMax: { default: 1.5 },
+		/**
+		* Where the camera RESTS before anyone has looked around, in degrees.
+		* Negative looks down, which is what a third-person game usually wants.
+		*
+		* `pitch` is a radian field the mouse mutates, so the alternative was a
+		* behaviour whose only job is one line in `onReady`. On a phone it stops
+		* being a nicety: a portrait screen is very tall, so a level camera spends
+		* the top half on sky and the bottom on the ground at the player's feet,
+		* and a player with no mouse cannot fix it before they start dragging.
+		* Clamped by `pitchMin`/`pitchMax` like every other pitch. `0` is the old
+		* behaviour.
+		*/
+		pitchStart: {
+			default: 0,
+			range: {
+				min: -180,
+				max: 180
+			}
+		},
 		cameraCollision: { default: true },
+		/**
+		* Who owns the scene's camera: `'drive'` (default) is this controller, as
+		* it always has been — the rig behind the character, per `view`. `'none'`
+		* leaves the camera exactly where the scene puts it, for the whole shelf of
+		* games with a FIXED view: a board game, a bomb arena, an isometric puzzle,
+		* a fixed-angle horror. Those games could not use this controller at all,
+		* because it re-posed their camera every frame; now they pair it with an
+		* authored `Camera3D` (and a `FollowCamera` behaviour when the board
+		* scrolls).
+		*/
+		camera: {
+			default: "drive",
+			options: ["drive", "none"]
+		},
 		platformCarry: { default: true },
 		turnSpeed: { default: 100 },
 		camLerp: { default: 25 },
@@ -2906,6 +3192,20 @@ var CharacterController3D = class extends Node3D {
 			nodePath: true
 		},
 		skinYawOffset: { default: 0 },
+		/**
+		* The button that LOCKS ON: the camera yaw follows the nearest live member
+		* of `lockGroup` within `lockRange`, and the skin FACES it while the feet go
+		* anywhere — a locked player circling a brute shows it a face, not a
+		* shoulder, and a hitbox hung off the skin's yaw swings at it. Press again
+		* to let go; the lock lets go by itself when the target dies, leaves the
+		* tree, or gets 1.5 × `lockRange` away. '' = no lock-on.
+		*/
+		lockOnAction: { default: "" },
+		lockGroup: { default: "enemy" },
+		lockRange: {
+			default: 12,
+			range: { min: 0 }
+		},
 		animations: {
 			default: {},
 			asset: {
@@ -2914,6 +3214,7 @@ var CharacterController3D = class extends Node3D {
 			}
 		}
 	};
+	enabled = true;
 	view = "free";
 	camDistance = 4;
 	eyeHeight = .64;
@@ -2940,6 +3241,50 @@ var CharacterController3D = class extends Node3D {
 	fallGravity = 2.5;
 	floatHeight = .01;
 	/**
+	* Swimming pace in water too deep to stand in (m/s; `sprint` still
+	* multiplies). `0` turns swimming OFF and the body sinks to the bed, which
+	* is what a drowning pit wants and what every scene got before this.
+	*/
+	swimSpeed = 1.6;
+	/** Where the body's origin rides below the surface while swimming (m). */
+	swimDepth = .35;
+	/** Held: swim down at `swimSpeed`. Missing from the input map is fine. */
+	diveAction = "dive";
+	/**
+	* Ladder pace (m/s). A ladder is any `Area3D` in `ladderGroup`: push UP into
+	* it and the body climbs, gravity off, held to the rungs; at the top it
+	* pulls itself onto the ledge, down steps off at the bottom, `jump` lets go.
+	* `0` = no ladders (every scene before this).
+	*/
+	climbSpeed = 1.5;
+	ladderGroup = "ladder";
+	/**
+	* The pull-up, for any jump. A jump that falls a hand short of a ledge is
+	* the most common near-miss in a platformer, and every one handles it the
+	* same way: catch the edge, pull up. On the way down from a jump, a ledge
+	* ahead no higher than this above the capsule's bottom is taken — the same
+	* climb that takes a swimmer out of the water and a climber off a ladder.
+	* `0` (the default) = a jump near a wall feels exactly as it did.
+	*/
+	mantleHeight = 0;
+	crouchHeight = 0;
+	crouchSpeedMultiplier = .5;
+	crouchAction = "crouch";
+	dashSpeed = 0;
+	dashSeconds = .25;
+	dashCooldown = 0;
+	dashAction = "dash";
+	dashBackstep = false;
+	dashLeft = 0;
+	dashCooldownLeft = 0;
+	dashDir = [0, -1];
+	/** Read-only: shorter right now — by the key, or by a ceiling. */
+	crouching = false;
+	/** The capsule height to stand back up to. */
+	standingHeight = 0;
+	/** The skin's authored y offset, restored on standing. */
+	skinRest = null;
+	/**
 	* How high a step the PLAYER walks up without jumping (0 = off).
 	*
 	* The hover spring holds the capsule a fixed distance above whatever is
@@ -2963,8 +3308,10 @@ var CharacterController3D = class extends Node3D {
 	zoomMax = 0;
 	pitchMin = -1.3;
 	pitchMax = 1.5;
+	pitchStart = 0;
 	/** Spring-arm: pull the orbit camera in front of walls/ground instead of clipping. */
 	cameraCollision = true;
+	camera = "drive";
 	/**
 	* Ride whatever you are standing on.
 	*
@@ -2989,19 +3336,59 @@ var CharacterController3D = class extends Node3D {
 	* would fling the player on every step onto one.
 	*/
 	groundCarry(ground, dt) {
+		const body = this.parent;
+		const physics = body?._physics3d;
+		const me = body ? worldPosition(body) : [
+			0,
+			0,
+			0
+		];
 		if (!this.platformCarry || !this.grounded || !ground || dt <= 0) {
 			this.carriedBy = ground;
-			if (ground) this.carriedFrom = groundXZ(ground);
+			if (ground) {
+				this.carriedFrom = groundXZ(ground);
+				this.carriedRot = physics?.rotationOf(ground) ?? [
+					0,
+					0,
+					0,
+					1
+				];
+				this.carriedMe = [me[0] ?? 0, me[2] ?? 0];
+			}
 			return [0, 0];
 		}
 		const at = groundXZ(ground);
+		const rot = physics?.rotationOf(ground) ?? [
+			0,
+			0,
+			0,
+			1
+		];
 		const same = this.carriedBy === ground;
 		const was = this.carriedFrom;
+		const wasRot = this.carriedRot;
+		const wasMe = this.carriedMe;
 		this.carriedBy = ground;
 		this.carriedFrom = at;
+		this.carriedRot = rot;
+		this.carriedMe = [me[0] ?? 0, me[2] ?? 0];
 		if (!same) return [0, 0];
-		return [(at[0] - was[0]) / dt, (at[1] - was[1]) / dt];
-	}
+		let vx = (at[0] - was[0]) / dt;
+		let vz = (at[1] - was[1]) / dt;
+		const ox = wasMe[0] - was[0];
+		const oz = wasMe[1] - was[1];
+		const [rx, , rz] = rotateXZByDelta(rot, wasRot, ox, oz);
+		vx += (rx - ox) / dt;
+		vz += (rz - oz) / dt;
+		return [vx, vz];
+	}
+	carriedRot = [
+		0,
+		0,
+		0,
+		1
+	];
+	carriedMe = [0, 0];
 	turnSpeed = 100;
 	/** Camera smoothing rate (1-exp(-rate·dt)); side view uses 5. */
 	camLerp = 25;
@@ -3016,6 +3403,68 @@ var CharacterController3D = class extends Node3D {
 	* character facing away from the camera until it first moves).
 	*/
 	skinYawOffset = 0;
+	lockOnAction = "";
+	lockGroup = "enemy";
+	lockRange = 12;
+	/** What the character is locked onto, or null. */
+	lockTarget = null;
+	/** Lock onto `node`: the camera yaw and the skin follow it from now on. */
+	lock(node) {
+		if (node === this.lockTarget) return;
+		this.lockTarget = node;
+		this.emit("lockChanged", node);
+	}
+	/** Let go. */
+	unlock() {
+		if (!this.lockTarget) return;
+		this.lockTarget = null;
+		this.emit("lockChanged", null);
+	}
+	/** Lock the nearest live, visible member of `lockGroup` within `lockRange` — or let go if locked. */
+	toggleLock() {
+		if (this.lockTarget) {
+			this.unlock();
+			return;
+		}
+		const body = this.parent;
+		if (!body || !hasPositionArray(body)) return;
+		const me = worldPosition(body);
+		let best = null;
+		let bestD = this.lockRange;
+		for (const n of this.tree?.getNodesInGroup(this.lockGroup) ?? []) {
+			if (n === body || !hasPositionArray(n)) continue;
+			if (n.visible === false) continue;
+			if (findHealth(n)?.health.isDead) continue;
+			const p = worldPosition(n);
+			const d = Math.hypot((p[0] ?? 0) - (me[0] ?? 0), (p[2] ?? 0) - (me[2] ?? 0));
+			if (d < bestD) {
+				bestD = d;
+				best = n;
+			}
+		}
+		if (best) this.lock(best);
+	}
+	/** Player → target on the ground plane, unit; null when not locked (and lets go when the lock is stale). */
+	lockDirection() {
+		const t = this.lockTarget;
+		if (!t) return null;
+		const body = this.parent;
+		if (!t.tree || !body || !hasPositionArray(body) || !hasPositionArray(t) || findHealth(t)?.health.isDead) {
+			this.unlock();
+			return null;
+		}
+		const me = worldPosition(body);
+		const p = worldPosition(t);
+		const dx = (p[0] ?? 0) - (me[0] ?? 0);
+		const dz = (p[2] ?? 0) - (me[2] ?? 0);
+		const d = Math.hypot(dx, dz);
+		if (d > this.lockRange * 1.5) {
+			this.unlock();
+			return null;
+		}
+		if (d < .05) return null;
+		return [dx / d, dz / d];
+	}
 	/**
 	* Movement-state → animation asset map, applied to the `skinPath` model
 	* directly — no CharacterAnimator behavior needed:
@@ -3047,9 +3496,29 @@ var CharacterController3D = class extends Node3D {
 	/** Camera yaw/pitch in radians (mouse look mutates these). */
 	yaw = 0;
 	pitch = 0;
-	/** idle | walk | run | fastRun | airborne — drive animations from this. */
+	/** idle | walk | run | fastRun | airborne | swim — drive animations from this. */
 	state = "idle";
 	grounded = false;
+	/** In water too deep to stand in — held at the surface by the swim spring. */
+	swimming = false;
+	/** The head is under the surface (diving, or a wave over it). */
+	submerged = false;
+	/** Pulling up onto a ledge out of the water (see the climb in fixedUpdate). */
+	climbing = false;
+	/** On a ladder — an `Area3D` in `ladderGroup` the body overlaps and pushed up into. */
+	onLadder = false;
+	ladders = [];
+	ladderScanIn = 0;
+	ladderLockout = 0;
+	/** Every Water3D in the tree, re-scanned every {@link WATER_SCAN_STEPS}. */
+	waters = [];
+	waterScanIn = 0;
+	/**
+	* A hop out of the water is in progress: the spring may catch a ledge on
+	* the way down (the mantle) — a jump from land never gets that, or the
+	* spring would cushion every landing.
+	*/
+	swimHop = false;
 	/** @internal Feel timers — see the jump block for what each one buys. */
 	coyoteLeft = 0;
 	bufferLeft = 0;
@@ -3068,6 +3537,10 @@ var CharacterController3D = class extends Node3D {
 	}
 	onEnterTree() {
 		this.body;
+		if (this.pitchStart !== 0) {
+			const want = this.pitchStart * Math.PI / 180;
+			this.pitch = Math.min(Math.max(want, -this.pitchMax), -this.pitchMin);
+		}
 		if (this.skinPath !== "") {
 			const skin = this.getNodeOrNull(this.skinPath);
 			if (skin) skin.rotation = [
@@ -3082,9 +3555,15 @@ var CharacterController3D = class extends Node3D {
 		const physics = body._physics3d;
 		const input = this.tree?.engine?.input;
 		if (!physics || !input) return;
+		if (!this.enabled) {
+			this.readAction("moveAction", () => input.getVector(this.moveAction), null, "");
+			this.readAction("jumpAction", () => input.isPressed(this.jumpAction), false, "");
+			this.readAction("sprintAction", () => input.isPressed(this.sprintAction), false, "");
+			return;
+		}
 		const radius = body.collider.radius ?? .32;
 		const halfHeight = (body.collider.height ?? 1) / 2;
-		const pos = worldOf(body);
+		const pos = worldOf$1(body);
 		const vel = physics.velocityOf(body);
 		const mass = physics.massOf(body);
 		const floatingDis = radius + this.floatHeight;
@@ -3109,7 +3588,7 @@ var CharacterController3D = class extends Node3D {
 				-1,
 				0
 			], rayLen, body);
-			if (hit) {
+			if (hit && hit.distance > INSIDE_HIT) {
 				const d = hit.distance;
 				if (toi === null || d < toi) {
 					toi = d;
@@ -3121,6 +3600,26 @@ var CharacterController3D = class extends Node3D {
 		this.grounded = toi !== null && toi < floatingDis * 2;
 		const carry = this.groundCarry(ground, dt);
 		const footed = toi !== null && toi < floatingDis * 1.3 && (vel[1] ?? 0) <= .5;
+		const water = this.swimSpeed > 0 ? this.surfaceAt(pos[0], pos[2]) : null;
+		const surface = water === null ? null : water[0];
+		const waterline = surface === null ? null : surface - this.swimDepth;
+		const standY = toi === null ? null : originY - toi + floatingDis + halfHeight;
+		const swimming = waterline !== null && surface !== null && surface > pos[1] - halfHeight && waterline !== null && (standY === null || waterline > standY) && !(this.jumping && (vel[1] ?? 0) > .5);
+		this.swimming = swimming;
+		this.submerged = surface !== null && surface > pos[1] + halfHeight;
+		if (swimming) {
+			this.jumping = false;
+			this.rising = false;
+			this.jumpsUsed = 0;
+			this.coyoteLeft = 0;
+			this.swimHop = false;
+		}
+		const mantling = this.swimHop && (vel[1] ?? 0) <= .5;
+		if (this.lockOnAction !== "") {
+			if (this.readAction("lockOnAction", () => input.justPressed(this.lockOnAction), false, "Lock-on will not toggle.")) this.toggleLock();
+		}
+		const lockDir = this.lockDirection();
+		if (lockDir) this.yaw = Math.atan2(-lockDir[0], -lockDir[1]);
 		let mx = 0;
 		let mz = 0;
 		let moving = false;
@@ -3139,12 +3638,57 @@ var CharacterController3D = class extends Node3D {
 		} catch (error) {
 			this.reportMissingAction("moveAction", error, "The character will not move.");
 		}
+		const hitHealth = findHealth(this.parent)?.health ?? null;
+		const staggered = hitHealth?.staggered ?? false;
+		if (staggered) {
+			mx = 0;
+			mz = 0;
+			moving = false;
+		}
+		const kick = hitHealth?.knocked ? hitHealth.kickVelocity : [];
+		const lift = hitHealth?.knocked ? hitHealth.takeLift() : 0;
+		this.dashCooldownLeft = Math.max(0, this.dashCooldownLeft - dt);
+		if (!staggered && this.dashSpeed > 0 && this.readAction("dashAction", () => input.justPressed(this.dashAction), false, "The character will never dash.") && this.dashLeft <= 0 && this.dashCooldownLeft <= 0 && !this.onLadder && !this.crouching) {
+			this.dashLeft = this.dashSeconds;
+			this.dashCooldownLeft = this.dashSeconds + this.dashCooldown;
+			if (moving) this.dashDir = [mx, mz];
+			else {
+				const skin = this.skinPath !== "" ? this.getNodeOrNull(this.skinPath) : null;
+				if (skin) {
+					const yaw = ((skin.rotation[1] ?? 0) - this.skinYawOffset) * (Math.PI / 180);
+					const back = this.dashBackstep ? -1 : 1;
+					this.dashDir = [Math.sin(yaw) * back, Math.cos(yaw) * back];
+				}
+			}
+			this.emit("dashed");
+		}
+		const dashing = this.dashLeft > 0;
+		if (dashing) this.dashLeft -= dt;
+		const rawUp = -this.readAction("moveAction", () => input.getVector(this.moveAction).y, 0, "The character will not climb.");
 		const sprinting = this.readAction("sprintAction", () => input.isPressed(this.sprintAction), false, "Sprint will never engage.");
 		const intensity = keyboardIntensity(moving, sprinting);
 		const speedMultiplier = 1 + (this.sprintMultiplier - 1) * intensity;
-		const targetSpeed = moving ? this.maxSpeed * speedMultiplier : 0;
+		const walkMultiplier = 1 + (this.sprintMultiplier - 1) * keyboardIntensity(true, false);
+		const targetSpeed = !moving ? 0 : swimming ? this.swimSpeed * speedMultiplier / walkMultiplier : this.maxSpeed * speedMultiplier * (this.crouching ? this.crouchSpeedMultiplier : 1);
+		this.ladderLockout = Math.max(0, this.ladderLockout - dt);
+		const ladder = this.climbSpeed > 0 && !swimming && this.ladderLockout <= 0 ? this.ladderUnder(body) : null;
+		let onLadder = false;
+		if (ladder) {
+			const wantsUp = rawUp > .1;
+			const wantsDown = rawUp < -.1;
+			if (this.onLadder) onLadder = !(footed && wantsDown);
+			else if (wantsUp || wantsDown && !footed) onLadder = true;
+		}
+		this.onLadder = onLadder;
+		if (onLadder) {
+			this.jumping = false;
+			this.rising = false;
+			this.jumpsUsed = 0;
+			this.coyoteLeft = 0;
+			this.swimHop = false;
+		}
 		this.wallNormal = null;
-		if ((this.wallSlideSpeed > 0 || this.wallJumpImpulse.some((v) => v !== 0)) && !this.grounded && moving) {
+		if ((this.wallSlideSpeed > 0 || this.wallJumpImpulse.some((v) => v !== 0)) && !this.grounded && !swimming && !onLadder && moving) {
 			const r = body.collider.radius ?? .32;
 			const n = (this.tree?.engine?.physics?.castRay([
 				pos[0] ?? 0,
@@ -3165,7 +3709,42 @@ var CharacterController3D = class extends Node3D {
 			}
 		}
 		this.wallLockout = Math.max(0, this.wallLockout - dt);
-		const control = this.wallLockout > 0 ? 0 : this.grounded ? 1 : this.airControl;
+		let climbing = false;
+		const mantleReach = this.mantleHeight > 0 && this.jumping && (vel[1] ?? 0) <= .5;
+		const reach = mantleReach ? Math.max(this.mantleHeight, this.stepHeight) : this.stepHeight;
+		if (reach > 0 && moving && (swimming || mantling || onLadder || mantleReach || this.climbing)) {
+			const ahead = radius + .12;
+			const stepFrom = water === null ? originY : water[1];
+			const probeTop = stepFrom + reach + .2;
+			const ledge = physics.castRay([
+				pos[0] + mx * ahead,
+				probeTop,
+				pos[2] + mz * ahead
+			], [
+				0,
+				-1,
+				0
+			], reach + .2 + rayLen, body);
+			if (ledge && ledge.distance > INSIDE_HIT) {
+				const top = probeTop - ledge.distance;
+				const aboveTheBottom = top > originY - radius + .02;
+				const withinReach = top - stepFrom <= reach + .02;
+				const stillBelow = originY < top + floatingDis - .01;
+				if (aboveTheBottom && withinReach && stillBelow) climbing = true;
+			}
+		}
+		this.climbing = climbing;
+		if (climbing && (vel[1] ?? 0) < CLIMB_SPEED) body.applyImpulse([
+			0,
+			(CLIMB_SPEED - (vel[1] ?? 0)) * .5 * mass,
+			0
+		]);
+		if (onLadder && !climbing) body.applyImpulse([
+			-(vel[0] ?? 0) * .3 * mass,
+			(rawUp * this.climbSpeed - (vel[1] ?? 0)) * .5 * mass,
+			-(vel[2] ?? 0) * .3 * mass
+		]);
+		const control = this.wallLockout > 0 || onLadder && !climbing ? 0 : this.grounded || swimming || climbing ? 1 : this.airControl;
 		const ax = (mx * targetSpeed + carry[0] - vel[0]) / ACC_DELTA_TIME * control;
 		const az = (mz * targetSpeed + carry[1] - vel[2]) / ACC_DELTA_TIME * control;
 		body.applyImpulse([
@@ -3173,13 +3752,13 @@ var CharacterController3D = class extends Node3D {
 			0,
 			az * mass
 		]);
-		if (!moving && this.grounded) body.applyImpulse([
+		if (!moving && (this.grounded || swimming)) body.applyImpulse([
 			-(vel[0] - carry[0]) * DRAG_DAMPING * mass,
 			0,
 			-(vel[2] - carry[1]) * DRAG_DAMPING * mass
 		]);
 		let springToi = toi;
-		if (this.stepHeight > 0 && moving && toi !== null && !this.jumping && (vel[1] ?? 0) <= .5) {
+		if (this.stepHeight > 0 && moving && toi !== null && !this.jumping && !swimming && !climbing && (vel[1] ?? 0) <= .5) {
 			const ahead = radius + .12;
 			const probeTop = originY + this.stepHeight + .05;
 			const stepHit = physics.castRay([
@@ -3191,12 +3770,12 @@ var CharacterController3D = class extends Node3D {
 				-1,
 				0
 			], this.stepHeight + .05 + rayLen, body);
-			if (stepHit) {
+			if (stepHit && stepHit.distance > INSIDE_HIT) {
 				const rise = probeTop - stepHit.distance - (originY - toi);
 				if (rise > .02 && rise <= this.stepHeight + .02) springToi = toi - rise;
 			}
 		}
-		if (springToi !== null && springToi < floatingDis * 2 && !this.jumping && (vel[1] ?? 0) < 2) {
+		if (springToi !== null && springToi < floatingDis * 2 && (!this.jumping || mantling) && !swimming && !climbing && !onLadder && (vel[1] ?? 0) < 2) {
 			const spring = SPRING_K * (floatingDis - springToi) - vel[1] * SPRING_DAMPING;
 			body.applyImpulse([
 				0,
@@ -3204,21 +3783,94 @@ var CharacterController3D = class extends Node3D {
 				0
 			]);
 		}
+		const diving = this.swimSpeed > 0 && this.readAction("diveAction", () => input.isPressed(this.diveAction), false, "The character will never dive.");
+		if (swimming && !climbing && waterline !== null) {
+			const surfacing = this.submerged && this.readAction("jumpAction", () => input.isPressed(this.jumpAction), false, "The character will never surface by choice.");
+			const vy = vel[1] ?? 0;
+			let ay;
+			if (diving) ay = (-this.swimSpeed - vy) / ACC_DELTA_TIME / dt;
+			else if (surfacing) ay = (this.swimSpeed - vy) / ACC_DELTA_TIME / dt;
+			else ay = SWIM_K * (waterline - pos[1]) - SWIM_DAMPING * vy;
+			ay = Math.max(-3 * STANDARD_G, Math.min(SWIM_MAX_G * STANDARD_G, ay));
+			body.applyImpulse([
+				0,
+				ay * dt * mass,
+				0
+			]);
+		}
 		if (footed) {
 			this.coyoteLeft = this.coyoteSeconds;
 			this.jumpsUsed = 0;
 			this.rising = false;
 			this.jumping = false;
+			this.swimHop = false;
 		} else {
 			this.coyoteLeft = Math.max(0, this.coyoteLeft - dt);
-			if (!this.grounded && this.coyoteLeft <= 0 && this.jumpsUsed === 0) this.jumpsUsed = 1;
+			if (!this.grounded && !swimming && this.coyoteLeft <= 0 && this.jumpsUsed === 0) this.jumpsUsed = 1;
 		}
 		const pressedJump = this.readAction("jumpAction", () => input.justPressed(this.jumpAction), false, "The character will never jump.");
 		if (pressedJump) this.bufferLeft = Math.max(this.jumpBufferSeconds, 0);
 		else this.bufferLeft = Math.max(0, this.bufferLeft - dt);
-		const wantsJump = this.bufferLeft > 0 || pressedJump;
+		let wantsJump = this.bufferLeft > 0 || pressedJump;
+		if (staggered) wantsJump = false;
+		const wantCrouch = this.crouchHeight > 0 && this.readAction("crouchAction", () => input.isPressed(this.crouchAction), false, "The character will never crouch.");
+		if (!this.crouching) {
+			const standing = halfHeight * 2;
+			if (wantCrouch && this.grounded && this.crouchHeight < standing) {
+				this.standingHeight = standing;
+				this.crouching = true;
+				this.setHeight(body, this.crouchHeight, standing);
+			}
+		} else {
+			if (!wantCrouch) {
+				const rise = this.standingHeight - this.crouchHeight;
+				const top = pos[1] + this.crouchHeight / 2 + radius - .02;
+				if (!physics.castRay([
+					pos[0],
+					top,
+					pos[2]
+				], [
+					0,
+					1,
+					0
+				], rise + .06, body)) {
+					this.crouching = false;
+					this.setHeight(body, this.standingHeight, this.crouchHeight);
+				}
+			}
+			if (this.crouching) {
+				wantsJump = false;
+				this.bufferLeft = 0;
+			}
+		}
 		const wall = this.wallNormal;
-		if (wantsJump && !this.grounded && wall && this.wallJumpImpulse.some((v) => v !== 0)) {
+		if (wantsJump && onLadder && ladder) {
+			const at = worldOf$1(ladder);
+			let ax = pos[0] - at[0];
+			let az = pos[2] - at[2];
+			const len = Math.hypot(ax, az);
+			if (len > .001) {
+				ax /= len;
+				az /= len;
+			} else {
+				ax = -mx;
+				az = -mz;
+			}
+			body.linearVelocity = [
+				ax * 2,
+				2.5,
+				az * 2
+			];
+			vel[0] = ax * 2;
+			vel[1] = 2.5;
+			vel[2] = az * 2;
+			this.onLadder = false;
+			this.ladderLockout = LADDER_LOCKOUT;
+			this.bufferLeft = 0;
+			this.rising = false;
+			this.jumping = true;
+			this.jumpsUsed = this.maxJumps;
+		} else if (wantsJump && !this.grounded && wall && this.wallJumpImpulse.some((v) => v !== 0)) {
 			const away = this.wallJumpImpulse[0] ?? 0;
 			const up = this.wallJumpImpulse[1] ?? 0;
 			body.linearVelocity = [
@@ -3236,8 +3888,10 @@ var CharacterController3D = class extends Node3D {
 			this.jumping = true;
 			this.wallLockout = WALL_LOCKOUT_SECONDS;
 			this.emit("wallJumped", wall);
-		} else if (wantsJump && (footed || this.coyoteLeft > 0 || this.jumpsUsed < this.maxJumps)) {
-			const jumpVel = this.jumpVelocity * (1 + (this.sprintJumpMultiplier - 1) * intensity);
+		} else if (wantsJump && !onLadder && !(swimming && this.submerged) && (footed || swimming || this.coyoteLeft > 0 || this.jumpsUsed < this.maxJumps)) {
+			const hopVel = swimming ? Math.max(this.jumpVelocity, Math.sqrt(2 * this.sceneGravity() * (this.swimDepth + halfHeight + this.stepHeight + .05))) : 0;
+			const jumpVel = swimming ? hopVel : this.jumpVelocity * (1 + (this.sprintJumpMultiplier - 1) * intensity);
+			if (swimming) this.swimHop = true;
 			body.linearVelocity = [
 				vel[0],
 				jumpVel,
@@ -3265,6 +3919,7 @@ var CharacterController3D = class extends Node3D {
 			}
 		}
 		const sliding = this.wallSlideSpeed > 0 && !footed && this.wallNormal !== null && (vel[1] ?? 0) < 0;
+		const atSlideCap = sliding && (vel[1] ?? 0) <= -this.wallSlideSpeed + .01;
 		if (sliding && (vel[1] ?? 0) < -this.wallSlideSpeed) {
 			body.linearVelocity = [
 				vel[0],
@@ -3273,7 +3928,8 @@ var CharacterController3D = class extends Node3D {
 			];
 			vel[1] = -this.wallSlideSpeed;
 		}
-		if ((vel[1] ?? 0) < FALLING_MAX_VEL) body.gravityScale = 0;
+		if (swimming || climbing || atSlideCap || this.onLadder) body.gravityScale = 0;
+		else if ((vel[1] ?? 0) < FALLING_MAX_VEL) body.gravityScale = 0;
 		else if ((vel[1] ?? 0) < 0 && !footed) body.gravityScale = sliding ? 1 : this.fallGravity;
 		else body.gravityScale = 1;
 		if (this.view === "side" && Math.abs(pos[2]) > .01) body.position = [
@@ -3281,7 +3937,21 @@ var CharacterController3D = class extends Node3D {
 			body.position[1] ?? 0,
 			0
 		];
-		const next = movementState(!(this.jumping || !this.grounded), moving ? intensity : 0);
+		if (dashing && !swimming) body.linearVelocity = [
+			this.dashDir[0] * this.dashSpeed,
+			vel[1] ?? 0,
+			this.dashDir[1] * this.dashSpeed
+		];
+		if (kick.length > 0) {
+			const cur = body.linearVelocity;
+			body.linearVelocity = [
+				kick[0] ?? 0,
+				lift !== 0 ? lift : cur[1] ?? 0,
+				kick[2] ?? 0
+			];
+		}
+		const airborne = this.jumping || !this.grounded;
+		const next = dashing && !swimming ? "dash" : swimming ? "swim" : this.onLadder || climbing ? "climb" : this.crouching && !airborne ? moving ? "sneak" : "crouch" : movementState(!airborne, moving ? intensity : 0);
 		if (next !== this.state) {
 			this.state = next;
 			const clip = this.animations[next];
@@ -3291,13 +3961,15 @@ var CharacterController3D = class extends Node3D {
 			}
 			this.emit("movementStateChanged", next);
 		}
-		if (moving && this.skinPath !== "") {
+		if ((moving || lockDir) && this.skinPath !== "") {
 			const skin = this.getNodeOrNull(this.skinPath);
 			if (skin) {
-				const target = Math.atan2(mx, mz) * RAD2DEG + this.skinYawOffset;
+				const fx = lockDir ? lockDir[0] : mx;
+				const fz = lockDir ? lockDir[1] : mz;
+				const target = Math.atan2(fx, fz) * RAD2DEG$3 + this.skinYawOffset;
 				const current = skin.rotation[1] ?? 0;
 				let delta = (target - current + 540) % 360 - 180;
-				const step = this.turnSpeed * dt * RAD2DEG;
+				const step = this.turnSpeed * dt * RAD2DEG$3;
 				if (Math.abs(delta) > step) delta = Math.sign(delta) * step;
 				skin.rotation = [
 					skin.rotation[0] ?? 0,
@@ -3310,6 +3982,76 @@ var CharacterController3D = class extends Node3D {
 	/** Actions already reported missing, so a per-frame read says it once. */
 	reportedActions = /* @__PURE__ */ new Set();
 	/**
+	* The water over a world point — `[wave surface, still level]` — or null
+	* when no `Water3D`'s footprint covers it. The tree is re-scanned once a
+	* second, so a lake streamed in later is found; the wave height is the CPU
+	* twin of what is drawn, so a swimmer rides the swell the way a raft does.
+	*/
+	/** The ladder the body is overlapping, if any — an Area3D in `ladderGroup`. */
+	ladderUnder(body) {
+		const physics = body._physics3d;
+		if (!physics) return null;
+		if (this.ladderScanIn <= 0) {
+			this.ladders.length = 0;
+			collectAreas(this.getRoot(), this.ladderGroup, this.ladders);
+			this.ladderScanIn = WATER_SCAN_STEPS;
+		}
+		this.ladderScanIn -= 1;
+		for (const ladder of this.ladders) {
+			if (ladder.tree === null) continue;
+			if (physics.overlapping(ladder).includes(body)) return ladder;
+		}
+		return null;
+	}
+	/**
+	* Swap the capsule's height and keep the feet where they are: the body
+	* drops (or rises) by half the difference in the same step, the skin's
+	* authored offset moves the other way so the model's feet stay on the
+	* floor, and the adapter rebuilds the body at the new place next step.
+	*/
+	setHeight(body, next, from) {
+		body.collider = {
+			...body.collider,
+			height: next
+		};
+		const d = (from - next) / 2;
+		const p = body.position;
+		body.position = [
+			p[0] ?? 0,
+			(p[1] ?? 0) - d,
+			p[2] ?? 0
+		];
+		if (this.skinPath === "") return;
+		const skin = this.getNodeOrNull(this.skinPath);
+		if (!skin) return;
+		if (this.skinRest === null) this.skinRest = skin.position[1] ?? 0;
+		const lift = this.crouching ? (this.standingHeight - this.crouchHeight) / 2 : 0;
+		skin.position = [
+			skin.position[0] ?? 0,
+			this.skinRest + lift,
+			skin.position[2] ?? 0
+		];
+	}
+	sceneGravity() {
+		const g = this.tree?.engine?.scene?.physics?.gravity;
+		return Math.abs(g?.[1] ?? STANDARD_G) || STANDARD_G;
+	}
+	surfaceAt(x, z) {
+		if (this.waterScanIn <= 0) {
+			this.waters.length = 0;
+			collectWaters(this.getRoot(), this.waters);
+			this.waterScanIn = WATER_SCAN_STEPS;
+		}
+		this.waterScanIn -= 1;
+		for (const water of this.waters) {
+			if (water.tree === null) continue;
+			const still = water._waterYAt(x, z);
+			if (still === null) continue;
+			return [water.heightAt(x, z), still];
+		}
+		return null;
+	}
+	/**
 	* Read an input action this controller is allowed to be missing.
 	*
 	* Tolerated because a game may declare no sprint key and no jump; reported
@@ -3333,6 +4075,7 @@ var CharacterController3D = class extends Node3D {
 		}, void 0, consequence);
 	}
 	update(dt) {
+		if (!this.enabled) return;
 		const input = this.tree?.engine?.input;
 		if (!input) return;
 		if (this.mouseLook) {
@@ -3346,11 +4089,12 @@ var CharacterController3D = class extends Node3D {
 			const wheel = input.wheelDelta();
 			if (wheel !== 0 && this.zoomMax > this.zoomMin) this.camDistance = clamp(this.camDistance + wheel * LOOK_SPEED, this.zoomMin, this.zoomMax);
 		}
+		if (this.camera === "none") return;
 		const camera = this.findCamera();
 		if (!camera) return;
 		const body = this.parent instanceof RigidBody3D ? this.parent : null;
 		if (!body) return;
-		const playerPos = worldOf(body);
+		const playerPos = worldOf$1(body);
 		const pivotRate = this.view === "free" ? 11 : 1e3;
 		const pk = 1 - Math.exp(-pivotRate * dt);
 		const pivot = this.pivot ?? [
@@ -3404,9 +4148,9 @@ var CharacterController3D = class extends Node3D {
 			eulerScratch.setFromQuaternion(quatScratch, "XYZ");
 		}
 		camera.rotation = [
-			eulerScratch.x * RAD2DEG,
-			eulerScratch.y * RAD2DEG,
-			eulerScratch.z * RAD2DEG
+			eulerScratch.x * RAD2DEG$3,
+			eulerScratch.y * RAD2DEG$3,
+			eulerScratch.z * RAD2DEG$3
 		];
 	}
 	pivot = null;
@@ -3431,7 +4175,15 @@ var CharacterController3D = class extends Node3D {
 function clamp(v, lo, hi) {
 	return Math.min(hi, Math.max(lo, v));
 }
-function worldOf(node) {
+function collectAreas(node, group, out) {
+	if (node instanceof Area3D && node.isInGroup(group)) out.push(node);
+	for (const child of node.children) collectAreas(child, group, out);
+}
+function collectWaters(node, out) {
+	if (node instanceof Water3D) out.push(node);
+	for (const child of node.children) collectWaters(child, out);
+}
+function worldOf$1(node) {
 	let x = 0;
 	let y = 0;
 	let z = 0;
@@ -3460,6 +4212,344 @@ function groundXZ(node) {
 	const world = worldPosition(node);
 	return [world[0] ?? 0, world[2] ?? 0];
 }
+/** An XZ offset turned by the rotation that takes `qFrom` to `qNow` (quaternions `[x,y,z,w]`). */
+function rotateXZByDelta(qNow, qFrom, ox, oz) {
+	const [fx, fy, fz, fw] = [
+		-(qFrom[0] ?? 0),
+		-(qFrom[1] ?? 0),
+		-(qFrom[2] ?? 0),
+		qFrom[3] ?? 1
+	];
+	const [nx, ny, nz, nw] = [
+		qNow[0] ?? 0,
+		qNow[1] ?? 0,
+		qNow[2] ?? 0,
+		qNow[3] ?? 1
+	];
+	const dx = nw * fx + nx * fw + ny * fz - nz * fy;
+	const dy = nw * fy - nx * fz + ny * fw + nz * fx;
+	const dz = nw * fz + nx * fy - ny * fx + nz * fw;
+	const dw = nw * fw - nx * fx - ny * fy - nz * fz;
+	const oy = 0;
+	const cx = dy * oz - dz * oy;
+	const cy = dz * ox - dx * oz;
+	const cz = dx * oy - dy * ox;
+	return [
+		ox + 2 * (dw * cx + (dy * cz - dz * cy)),
+		oy + 2 * (dw * cy + (dz * cx - dx * cz)),
+		oz + 2 * (dw * cz + (dx * cy - dy * cx))
+	];
+}
+function hasPositionArray(n) {
+	return Array.isArray(n.position);
+}
+//#endregion
+//#region src/3d/nodes/flock-3d.ts
+const RAD2DEG$2 = 180 / Math.PI;
+/**
+* A flock — gulls over a harbor, fish under a boat, bats out of a cave — as
+* ONE instanced mesh that flies its own instances.
+*
+* ```json
+* { "name": "Gulls", "type": "Flock3D",
+*   "props": { "position": [0, 14, 0], "count": 40, "radius": 30, "height": 6,
+*              "mesh": "box", "size": [0.5, 0.08, 0.3], "follow": "/root/Boat" } }
+* ```
+*
+* Boids (Reynolds 1987): each instance steers away from neighbours closer
+* than `separation`, toward the average heading of those within `sight`
+* (`alignment`) and toward their centre (`cohesion`), turns back inside an
+* ellipsoid `radius` wide and `height` tall around this node — or around the
+* node at `follow`, offset by this node's position — and never turns faster
+* than `turn`. Every instance flies at `speed`, +z forward, so a mesh that is
+* longer along z reads as a body with a beak.
+*
+* No physics bodies, no behaviour per bird: forty birds cost one draw call
+* and forty-squared distance checks a frame. Seeded from `engine.rng`, so a
+* seeded run flies the same flight. `boids()` answers headless.
+*/
+var Flock3D = class extends InstancedMesh3D {
+	static typeName = "Flock3D";
+	static props = {
+		...InstancedMesh3D.props,
+		/** How many. Live — a change reseeds the flock. */
+		count: {
+			default: 30,
+			range: { min: 0 }
+		},
+		/** The bound they turn back from: half-width (m) around the centre… */
+		radius: {
+			default: 20,
+			range: { min: .1 }
+		},
+		/** …and half-height (m). A flat ellipsoid keeps fish under the surface. */
+		height: {
+			default: 8,
+			range: { min: .1 }
+		},
+		/** Every bird's pace (m/s). */
+		speed: {
+			default: 6,
+			range: { min: 0 }
+		},
+		/** The sharpest turn (rad/s) — lower is lazier, gull-like. */
+		turn: {
+			default: 2.5,
+			range: { min: 0 }
+		},
+		/** Closer than this (m) and two birds push apart. */
+		separation: {
+			default: 1.5,
+			range: { min: 0 }
+		},
+		/** How far (m) a bird sees its neighbours for alignment and cohesion. */
+		sight: {
+			default: 5,
+			range: { min: 0 }
+		},
+		/** Weight of matching the neighbours' heading (0 = none). */
+		alignment: {
+			default: 1,
+			range: { min: 0 }
+		},
+		/** Weight of drifting toward the neighbours' centre (0 = none). */
+		cohesion: {
+			default: 1,
+			range: { min: 0 }
+		},
+		/** A node the flock's centre follows, offset by this node's position; '' = this node. */
+		follow: {
+			default: "",
+			nodePath: true
+		}
+	};
+	count = 30;
+	radius = 20;
+	height = 8;
+	speed = 6;
+	turn = 2.5;
+	separation = 1.5;
+	sight = 5;
+	alignment = 1;
+	cohesion = 1;
+	follow = "";
+	px = new Float64Array(0);
+	py = new Float64Array(0);
+	pz = new Float64Array(0);
+	vx = new Float64Array(0);
+	vy = new Float64Array(0);
+	vz = new Float64Array(0);
+	rows = [];
+	static validateJson(node) {
+		InstancedMesh3D.validateJson(node);
+		if (node.collider !== null) throw new IncantoError("BAD_FORMAT", `Flock3D '${node.name}': birds are not solid — a flock takes no "collider" (it flies; a static hull would stay where the first frame put it).`, { prop: "collider" });
+	}
+	/** Every bird right now, in world metres and m/s. */
+	boids() {
+		const [ox, oy, oz] = worldOf(this);
+		const out = [];
+		for (let i = 0; i < this.px.length; i++) out.push({
+			x: (this.px[i] ?? 0) + ox,
+			y: (this.py[i] ?? 0) + oy,
+			z: (this.pz[i] ?? 0) + oz,
+			vx: this.vx[i] ?? 0,
+			vy: this.vy[i] ?? 0,
+			vz: this.vz[i] ?? 0
+		});
+		return out;
+	}
+	update(dt) {
+		const engine = this.tree?.engine;
+		if (!engine) return;
+		const n = Math.max(0, Math.floor(this.count));
+		if (this.px.length !== n) this.seed(engine.rng, n);
+		if (n === 0) {
+			if (this.transforms.length !== 0) this.transforms = [];
+			return;
+		}
+		const [cx, cy, cz] = this.centre();
+		const step = Math.min(dt, 1 / 20);
+		const sight2 = this.sight * this.sight;
+		const sep2 = this.separation * this.separation;
+		const maxTurn = this.turn * step;
+		const { px, py, pz, vx, vy, vz } = this;
+		for (let i = 0; i < n; i++) {
+			const x = px[i] ?? 0;
+			const y = py[i] ?? 0;
+			const z = pz[i] ?? 0;
+			let sx = 0;
+			let sy = 0;
+			let sz = 0;
+			let ax = 0;
+			let ay = 0;
+			let az = 0;
+			let mx = 0;
+			let my = 0;
+			let mz = 0;
+			let seen = 0;
+			for (let j = 0; j < n; j++) {
+				if (j === i) continue;
+				const dx = (px[j] ?? 0) - x;
+				const dy = (py[j] ?? 0) - y;
+				const dz = (pz[j] ?? 0) - z;
+				const d2 = dx * dx + dy * dy + dz * dz;
+				if (d2 > sight2) continue;
+				seen += 1;
+				ax += vx[j] ?? 0;
+				ay += vy[j] ?? 0;
+				az += vz[j] ?? 0;
+				mx += dx;
+				my += dy;
+				mz += dz;
+				if (d2 < sep2 && d2 > 1e-9) {
+					const inv = 1 / d2;
+					sx -= dx * inv;
+					sy -= dy * inv;
+					sz -= dz * inv;
+				}
+			}
+			let fx = sx * this.speed * 2;
+			let fy = sy * this.speed * 2;
+			let fz = sz * this.speed * 2;
+			if (seen > 0) {
+				fx += (ax / seen - (vx[i] ?? 0)) * this.alignment / .5;
+				fy += (ay / seen - (vy[i] ?? 0)) * this.alignment / .5;
+				fz += (az / seen - (vz[i] ?? 0)) * this.alignment / .5;
+				fx += mx / seen * this.cohesion * 2;
+				fy += my / seen * this.cohesion * 2;
+				fz += mz / seen * this.cohesion * 2;
+			}
+			const ex = (x - cx) / this.radius;
+			const ey = (y - cy) / this.height;
+			const ez = (z - cz) / this.radius;
+			const m = Math.sqrt(ex * ex + ey * ey + ez * ez);
+			if (m > .6) {
+				const k = (m - .6) / .4 * this.speed * 8;
+				const gx = ex / this.radius;
+				const gy = ey / this.height;
+				const gz = ez / this.radius;
+				const g = Math.hypot(gx, gy, gz) || 1;
+				fx -= gx / g * k;
+				fy -= gy / g * k;
+				fz -= gz / g * k;
+			}
+			let nx = (vx[i] ?? 0) + fx * step;
+			let ny = (vy[i] ?? 0) + fy * step;
+			let nz = (vz[i] ?? 0) + fz * step;
+			const ov = Math.hypot(vx[i] ?? 0, vy[i] ?? 0, vz[i] ?? 0) || 1;
+			const nv = Math.hypot(nx, ny, nz) || 1;
+			const cos = ((vx[i] ?? 0) * nx + (vy[i] ?? 0) * ny + (vz[i] ?? 0) * nz) / (ov * nv);
+			const angle = Math.acos(Math.max(-1, Math.min(1, cos)));
+			if (angle > maxTurn && angle > 1e-6) {
+				const t = maxTurn / angle;
+				nx = (vx[i] ?? 0) / ov * (1 - t) + nx / nv * t;
+				ny = (vy[i] ?? 0) / ov * (1 - t) + ny / nv * t;
+				nz = (vz[i] ?? 0) / ov * (1 - t) + nz / nv * t;
+			}
+			const len = Math.hypot(nx, ny, nz) || 1;
+			vx[i] = nx / len * this.speed;
+			vy[i] = ny / len * this.speed;
+			vz[i] = nz / len * this.speed;
+		}
+		for (let i = 0; i < n; i++) {
+			px[i] = (px[i] ?? 0) + (vx[i] ?? 0) * step;
+			py[i] = (py[i] ?? 0) + (vy[i] ?? 0) * step;
+			pz[i] = (pz[i] ?? 0) + (vz[i] ?? 0) * step;
+			let row = this.rows[i];
+			if (!row) {
+				row = [
+					0,
+					0,
+					0,
+					0,
+					1
+				];
+				this.rows[i] = row;
+			}
+			row[0] = px[i] ?? 0;
+			row[1] = py[i] ?? 0;
+			row[2] = pz[i] ?? 0;
+			row[3] = Math.atan2(vx[i] ?? 0, vz[i] ?? 0) * RAD2DEG$2;
+		}
+		this.transforms = this.rows;
+	}
+	/** The roam centre in this node's local frame: the followed node's offset, or the origin. */
+	centre() {
+		if (this.follow === "") return [
+			0,
+			0,
+			0
+		];
+		const target = this.getNodeOrNull(this.follow);
+		if (!(target instanceof Node3D)) return [
+			0,
+			0,
+			0
+		];
+		const [tx, ty, tz] = worldOf(target);
+		const [ox, oy, oz] = worldOf(this);
+		const [lx, ly, lz] = [
+			this.position[0] ?? 0,
+			this.position[1] ?? 0,
+			this.position[2] ?? 0
+		];
+		return [
+			tx - ox + lx,
+			ty - oy + ly,
+			tz - oz + lz
+		];
+	}
+	/** Scatter `n` birds through the bound with random headings — engine-seeded. */
+	seed(rng, n) {
+		this.px = new Float64Array(n);
+		this.py = new Float64Array(n);
+		this.pz = new Float64Array(n);
+		this.vx = new Float64Array(n);
+		this.vy = new Float64Array(n);
+		this.vz = new Float64Array(n);
+		this.rows.length = n;
+		const [cx, cy, cz] = this.centre();
+		for (let i = 0; i < n; i++) {
+			const u = rng.next();
+			const r = .6 * Math.cbrt(u);
+			const theta = rng.next() * Math.PI * 2;
+			const phi = Math.acos(2 * rng.next() - 1);
+			this.px[i] = cx + r * this.radius * Math.sin(phi) * Math.cos(theta);
+			this.py[i] = cy + r * this.height * Math.cos(phi);
+			this.pz[i] = cz + r * this.radius * Math.sin(phi) * Math.sin(theta);
+			const h = rng.next() * Math.PI * 2;
+			const pitch = (rng.next() - .5) * .4;
+			this.vx[i] = Math.cos(pitch) * Math.sin(h) * this.speed;
+			this.vy[i] = Math.sin(pitch) * this.speed;
+			this.vz[i] = Math.cos(pitch) * Math.cos(h) * this.speed;
+			this.rows[i] = [
+				this.px[i] ?? 0,
+				this.py[i] ?? 0,
+				this.pz[i] ?? 0,
+				h * RAD2DEG$2,
+				1
+			];
+		}
+		this.transforms = this.rows;
+	}
+};
+/** Translation-only world position (the engine's physics rule). */
+function worldOf(node) {
+	let x = 0;
+	let y = 0;
+	let z = 0;
+	for (let n = node; n; n = n.parent) {
+		if (!(n instanceof Node3D)) break;
+		x += n.position[0] ?? 0;
+		y += n.position[1] ?? 0;
+		z += n.position[2] ?? 0;
+	}
+	return [
+		x,
+		y,
+		z
+	];
+}
 //#endregion
 //#region src/3d/vegetation/grass-placement.ts
 const NOISE_SCALE = .15;
@@ -7625,7 +8715,19 @@ var Particles3D = class Particles3D extends Node3D {
 			options: ["add", "normal"]
 		},
 		depthTest: { default: true },
-		maxParticles: { default: 256 }
+		maxParticles: { default: 256 },
+		/** Half-extents (m) of a box the particles are born in, around the node — a cloud, a dusty field; `[0,0,0]` = a point. */
+		emitBox: { default: [
+			0,
+			0,
+			0
+		] },
+		/** A steady velocity (px/s, y+ = down like `gravity`) every particle is born with — wind on smoke. */
+		drift: { default: [
+			0,
+			0,
+			0
+		] }
 	};
 	preset = "custom";
 	emitting = true;
@@ -7682,6 +8784,20 @@ var Particles3D = class Particles3D extends Node3D {
 		});
 	}
 	sim = null;
+	emitBox = [
+		0,
+		0,
+		0
+	];
+	drift = [
+		0,
+		0,
+		0
+	];
+	/** @internal Forget the sim so the next update rebuilds it from the props (a preset or kind that changed). */
+	_rebuildSim() {
+		this.sim = null;
+	}
 	bursted = false;
 	finishedEmitted = false;
 	/** @internal */
@@ -7702,7 +8818,17 @@ var Particles3D = class Particles3D extends Node3D {
 				],
 				drag: this.drag,
 				maxParticles: this.maxParticles,
-				spreadZ: true
+				spreadZ: true,
+				emitBox: [
+					this.emitBox[0] ?? 0,
+					this.emitBox[1] ?? 0,
+					this.emitBox[2] ?? 0
+				],
+				drift: [
+					(this.drift[0] ?? 0) * PX_TO_M,
+					(this.drift[1] ?? 0) * PX_TO_M,
+					(this.drift[2] ?? 0) * PX_TO_M
+				]
 			}, rng);
 		}
 		return this.sim;
@@ -7824,9 +8950,24 @@ var Particles3D = class Particles3D extends Node3D {
 		}
 		return this.paletteCache;
 	}
+	/**
+	* The stamp every particle is drawn with — a soft round dot.
+	*
+	* A subclass overrides it to look like the thing it IS: `Weather3D`'s rain is
+	* a vertical STREAK, because 2,600 round dots read as a dirty lens and not as
+	* a downpour (measured in a browser at intensity 1). The material is rebuilt
+	* when this changes, so a node may return a different stamp over its life.
+	*/
+	sprite() {
+		return softSprite();
+	}
+	/** The stamp the current material was built with, so a change can rebuild it. */
+	builtSprite = null;
 	syncParticles() {
 		const sim = this._ensureSim();
-		if (!this.points || (this.positions?.length ?? 0) !== this.maxParticles * 3) {
+		const stamp = this.sprite();
+		if (!this.points || (this.positions?.length ?? 0) !== this.maxParticles * 3 || this.builtSprite !== stamp) {
+			this.builtSprite = stamp;
 			this.points?.removeFromParent();
 			this.positions = new Float32Array(this.maxParticles * 3);
 			this.colors = new Float32Array(this.maxParticles * 4);
@@ -7835,7 +8976,7 @@ var Particles3D = class Particles3D extends Node3D {
 			geometry.setAttribute("color", new BufferAttribute(this.colors, 4));
 			const material = new PointsMaterial({
 				size: (this.sizeStart + this.sizeEnd) / 2 * PX_TO_M,
-				map: softSprite(),
+				map: this.sprite(),
 				vertexColors: true,
 				transparent: true,
 				depthWrite: false,
@@ -7942,6 +9083,356 @@ function softSprite() {
 	return tex;
 }
 //#endregion
+//#region src/3d/nodes/ragdoll-3d.ts
+const RAD2DEG$1 = 180 / Math.PI;
+const DEG2RAD = Math.PI / 180;
+/**
+* The Mixamo rig every agent8 character wears, as ten capsules. Parents
+* come before children so a joint's target is already in the tree. A limb
+* whose `to` bone is missing is skipped — except the head, which becomes a
+* 0.2 m ball when the rig has no `HeadTop_End`.
+*/
+const RIG = [
+	{
+		name: "Torso",
+		from: "Hips",
+		to: "Neck",
+		radius: .14,
+		share: .32,
+		parent: null
+	},
+	{
+		name: "Head",
+		from: "Head",
+		to: "HeadTop_End",
+		radius: .1,
+		share: .08,
+		parent: "Torso"
+	},
+	{
+		name: "LeftUpperArm",
+		from: "LeftArm",
+		to: "LeftForeArm",
+		radius: .05,
+		share: .05,
+		parent: "Torso"
+	},
+	{
+		name: "LeftForearm",
+		from: "LeftForeArm",
+		to: "LeftHand",
+		radius: .045,
+		share: .04,
+		parent: "LeftUpperArm"
+	},
+	{
+		name: "RightUpperArm",
+		from: "RightArm",
+		to: "RightForeArm",
+		radius: .05,
+		share: .05,
+		parent: "Torso"
+	},
+	{
+		name: "RightForearm",
+		from: "RightForeArm",
+		to: "RightHand",
+		radius: .045,
+		share: .04,
+		parent: "RightUpperArm"
+	},
+	{
+		name: "LeftThigh",
+		from: "LeftUpLeg",
+		to: "LeftLeg",
+		radius: .08,
+		share: .12,
+		parent: "Torso"
+	},
+	{
+		name: "LeftShin",
+		from: "LeftLeg",
+		to: "LeftFoot",
+		radius: .06,
+		share: .07,
+		parent: "LeftThigh"
+	},
+	{
+		name: "RightThigh",
+		from: "RightUpLeg",
+		to: "RightLeg",
+		radius: .08,
+		share: .12,
+		parent: "Torso"
+	},
+	{
+		name: "RightShin",
+		from: "RightLeg",
+		to: "RightFoot",
+		radius: .06,
+		share: .07,
+		parent: "RightThigh"
+	}
+];
+const scratchM = new Matrix4();
+const scratchM2 = new Matrix4();
+const scratchQ = new Quaternion();
+const scratchE = new Euler();
+const scratchV = new Vector3();
+const scratchS = new Vector3(1, 1, 1);
+/**
+* A ragdoll for a skinned model — the death that falls.
+*
+* ```json
+* { "name": "Body", "type": "CharacterBody3D", "children": [
+*   { "name": "Skin", "type": "ModelInstance3D", "props": { "model": "$base" } },
+*   { "name": "Ragdoll", "type": "Ragdoll3D", "props": { "target": "../Skin", "lifetime": 8 } }
+* ] }
+* ```
+*
+* Idle it is nothing. `activate()` reads the skeleton at `target` (Mixamo
+* names, forgiving lookup), builds a capsule `RigidBody3D` per limb where the
+* bones are, joins each to its parent with a spherical `Joint3D`, gives them
+* the velocity of the body they fell out of, and from then on writes the
+* bones' world matrices from the limbs every frame — the model crumples,
+* slides, hangs off the ledge. Wire it from `Health.died`; turn the body's
+* collider and its controller off beside it. `reset()` puts the skeleton
+* back under the animation; `lifetime` does that on its own.
+*
+* Headless there is no skeleton: `activate(pose)` takes bone positions, so a
+* test can ask the same questions the game will.
+*/
+var Ragdoll3D = class extends Node3D {
+	static typeName = "Ragdoll3D";
+	static props = {
+		/** The ModelInstance3D whose skeleton this is. */
+		target: {
+			default: "../Skin",
+			nodePath: true
+		},
+		/** The whole body's mass (kg), shared out by limb. */
+		mass: {
+			default: 70,
+			range: { min: 0 }
+		},
+		/** Angular damping on every limb — how quickly the flailing dies. */
+		damping: {
+			default: 3,
+			range: { min: 0 }
+		},
+		/** Seconds before the ragdoll frees itself and hands the skeleton back; 0 = never. */
+		lifetime: {
+			default: 0,
+			range: { min: 0 }
+		},
+		/** Limbs collide with each other (adjacent ones never do). */
+		collide: { default: true }
+	};
+	static signals = ["activated", "reset"];
+	target = "../Skin";
+	mass = 70;
+	damping = 3;
+	lifetime = 0;
+	collide = true;
+	/** Read-only: built and driving the bones. */
+	active = false;
+	driven = [];
+	limbNodes = [];
+	left = 0;
+	/** Every limb built right now, empty while idle. */
+	limbs() {
+		return this.limbNodes.slice();
+	}
+	/**
+	* Build the ragdoll where the skeleton is (or where `pose` says the bones
+	* are, headless). Returns false when there is nothing to build from.
+	*/
+	activate(pose = void 0) {
+		if (this.active) return true;
+		const root = this.getRoot();
+		const model = this.getNodeOrNull(this.target);
+		const bones = /* @__PURE__ */ new Map();
+		const points = {};
+		if (pose) for (const [k, v] of Object.entries(pose)) points[k] = v;
+		else if (model && typeof model.findBone === "function") for (const spec of RIG) for (const name of [spec.from, spec.to]) {
+			if (points[name]) continue;
+			const bone = model.findBone(name);
+			if (!bone) continue;
+			bone.updateWorldMatrix(true, false);
+			scratchV.setFromMatrixPosition(bone.matrixWorld);
+			points[name] = [
+				scratchV.x,
+				scratchV.y,
+				scratchV.z
+			];
+			bones.set(name, bone);
+		}
+		if (!points.Hips) {
+			diagnose(this.tree?.engine, "warn", `[incanto] Ragdoll3D '${this.getPath()}': nothing to build from — '${this.target}' has no mounted skeleton (or no Hips bone), and no pose was given.`);
+			return false;
+		}
+		const velocity = this.hostVelocity();
+		const built = /* @__PURE__ */ new Map();
+		for (const spec of RIG) {
+			const from = points[spec.from];
+			if (!from) continue;
+			let to = points[spec.to];
+			if (!to) {
+				if (spec.name !== "Head") continue;
+				to = [
+					from[0],
+					from[1] + .2,
+					from[2]
+				];
+			}
+			const parent = spec.parent ? built.get(spec.parent) : null;
+			if (spec.parent && !parent) continue;
+			const dir = new Vector3(to[0] - from[0], to[1] - from[1], to[2] - from[2]);
+			const len = Math.max(dir.length(), .05);
+			dir.normalize();
+			const centre = new Vector3(from[0] + dir.x * (len / 2), from[1] + dir.y * (len / 2), from[2] + dir.z * (len / 2));
+			const rz = Math.asin(Math.max(-1, Math.min(1, -dir.x)));
+			const cz = Math.cos(rz);
+			const rx = cz > 1e-4 ? Math.atan2(dir.z / cz, dir.y / cz) : 0;
+			const quat = new Quaternion().setFromEuler(new Euler(rx, 0, rz, "XYZ"));
+			const radius = Math.min(spec.radius, len / 2 - .005);
+			const json = {
+				name: `${this.parent?.name ?? "Ragdoll"}${spec.name}`,
+				type: "RigidBody3D",
+				groups: ["ragdoll"],
+				props: {
+					position: [
+						centre.x,
+						centre.y,
+						centre.z
+					],
+					rotation: [
+						rx * RAD2DEG$1,
+						0,
+						rz * RAD2DEG$1
+					],
+					mass: Math.max(.5, this.mass * spec.share),
+					angularDamping: this.damping,
+					linearDamping: .3,
+					friction: .8,
+					collider: {
+						shape: "capsule",
+						radius,
+						height: Math.max(.02, len - 2 * radius)
+					},
+					linearVelocity: velocity
+				}
+			};
+			if (parent) {
+				const local = new Vector3(from[0], from[1], from[2]).sub(parent.centre);
+				local.applyQuaternion(parent.quat.clone().invert());
+				const children = [];
+				json.children = children;
+				children.push({
+					name: "Joint",
+					type: "Joint3D",
+					props: {
+						type: "spherical",
+						target: parent.node.getPath(),
+						anchor: [
+							0,
+							-len / 2,
+							0
+						],
+						targetAnchor: [
+							local.x,
+							local.y,
+							local.z
+						],
+						collide: false
+					}
+				});
+			}
+			const node = buildNodeJson(json, rebuildOptions(this));
+			root.addChild(node);
+			built.set(spec.name, {
+				node,
+				centre,
+				quat,
+				len
+			});
+			this.limbNodes.push({
+				name: spec.name,
+				body: node
+			});
+			const bone = bones.get(spec.from) ?? null;
+			const offset = new Matrix4();
+			if (bone) {
+				scratchM.compose(centre, quat, scratchS);
+				offset.copy(scratchM).invert().multiply(bone.matrixWorld);
+				bone.matrixWorldAutoUpdate = false;
+			}
+			this.driven.push({
+				body: node,
+				bone,
+				offset
+			});
+		}
+		if (this.limbNodes.length === 0) return false;
+		this.active = true;
+		this.left = this.lifetime;
+		this.emit("activated");
+		return true;
+	}
+	/** Free the limbs and hand the skeleton back to the animation. */
+	reset() {
+		if (!this.active) return;
+		for (const d of this.driven) {
+			if (d.bone) d.bone.matrixWorldAutoUpdate = true;
+			if (d.body.tree !== null) d.body.queueFree();
+		}
+		this.driven = [];
+		this.limbNodes = [];
+		this.active = false;
+		this.emit("reset");
+	}
+	update(dt) {
+		if (!this.active) return;
+		if (this.lifetime > 0) {
+			this.left -= dt;
+			if (this.left <= 0) {
+				this.reset();
+				return;
+			}
+		}
+		for (const d of this.driven) {
+			if (!d.bone) continue;
+			const p = d.body.position;
+			const r = d.body.rotation;
+			scratchV.set(p[0] ?? 0, p[1] ?? 0, p[2] ?? 0);
+			scratchQ.setFromEuler(scratchE.set((r[0] ?? 0) * DEG2RAD, (r[1] ?? 0) * DEG2RAD, (r[2] ?? 0) * DEG2RAD, "XYZ"));
+			scratchM.compose(scratchV, scratchQ, scratchS);
+			scratchM2.copy(scratchM).multiply(d.offset);
+			d.bone.matrixWorld.copy(scratchM2);
+		}
+	}
+	free() {
+		this.reset();
+		super.free();
+	}
+	/** The velocity of the body this ragdoll falls out of — the first body up the tree. */
+	hostVelocity() {
+		for (let n = this.parent; n; n = n.parent) {
+			const v = n.linearVelocity ?? n.velocity;
+			if (Array.isArray(v)) return [
+				v[0] ?? 0,
+				v[1] ?? 0,
+				v[2] ?? 0
+			];
+		}
+		return [
+			0,
+			0,
+			0
+		];
+	}
+};
+//#endregion
 //#region src/3d/water/river.ts
 /**
 * Self-carved bed. Sized off the WATER COLUMN, never off the width: a channel's
@@ -9386,7 +10877,7 @@ var River3D = class River3D extends Node3D {
 		if (!Array.isArray(r.path)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' path must be an array of [x, z] points, got ${JSON.stringify(r.path)}.`, { prop: "path" });
 		if (r.path.length > 0 && r.path.length < 2) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' path needs at least 2 points (source → mouth), got ${r.path.length}.`, { prop: "path" });
 		r.path.forEach((p, i) => {
-			if (!Array.isArray(p) || p.length < 2 || !Number.isFinite(p[0]) || !Number.isFinite(p[1])) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' path[${i}] must be [x, z] with finite numbers, got ${JSON.stringify(p)}.`, { prop: "path" });
+			if (!isCoursePoint(p)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' path[${i}] must be ${COURSE_SHAPE}, got ${JSON.stringify(p)}.`, { prop: "path" });
 		});
 		if (!(typeof r.width === "number" && r.width > 0)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' width must be a positive number of meters, got ${JSON.stringify(r.width)}.`, { prop: "width" });
 		if (!Array.isArray(r.widths) || r.widths.some((w) => !(typeof w === "number" && w > 0))) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' widths must be a list of positive meters (source→mouth), got ${JSON.stringify(r.widths)}.`, { prop: "widths" });
@@ -9420,8 +10911,14 @@ var River3D = class River3D extends Node3D {
 	onExitTree() {
 		findDrapeTerrain(this, this.terrain)?._setExternalChannel(this, null);
 	}
+	/** Said once when the node has no course to be a river along. */
+	warnedNoPath = false;
 	update(dt) {
 		this.time += dt;
+		if (!this.warnedNoPath && this.path.length === 0) {
+			this.warnedNoPath = true;
+			this.diagnose("warn", `[incanto] River3D '${this.name}' has no \`path\`, so there is no channel: it draws nothing, carves nothing and pushes nothing, whatever \`width\`, \`flowSpeed\` and \`flowForce\` say. Give it at least two [x, z] control points (source → mouth), in the node's own local frame.`);
+		}
 		this.ensureCourse();
 		this.syncSpray();
 		if (this.flowForce > 0 && this.rings.length > 1) this.sweepBodies(dt);
@@ -9552,7 +11049,7 @@ var River3D = class River3D extends Node3D {
 		const [tx, , tz] = worldXZY(terrain);
 		const hm = terrain._heightmap();
 		terrain._setExternalChannel(this, riverCarveChannels({
-			path: this.path.map((p) => [(p[0] ?? 0) + wx - tx, (p[1] ?? 0) + wz - tz]),
+			path: course(this.path).map((p) => [p[0] + wx - tx, p[1] + wz - tz]),
 			widths: this.widthProfile(),
 			depth: this.depth,
 			cell: (terrain.size[0] ?? 1) / Math.max(1, hm.segsX),
@@ -9597,7 +11094,7 @@ var River3D = class River3D extends Node3D {
 		this.fitted = terrain !== null;
 		const widths = this.widthProfile();
 		this.rings = buildRiverRings({
-			path: this.path,
+			path: course(this.path),
 			widths,
 			depth: this.depth,
 			flowSpeed: this.flowSpeed,
@@ -11615,6 +13112,8 @@ function paintVerticalGradient(geometry, base, darkest, brightest, rng) {
 }
 //#endregion
 //#region src/3d/nodes/tree-3d.ts
+/** How many times a wet draw is re-rolled before the tree is planted anyway. */
+const DRY_TRIES = 8;
 /** A whole forest in one node is still ≤6 draw calls — but keep it sane. */
 const MAX_TREE_COUNT = 500;
 /** Whole-grove triangle ceiling: count × tris-per-tree must stay under this. */
@@ -11770,6 +13269,7 @@ var Tree3D = class Tree3D extends Node3D {
 			default: null,
 			kinds: ["null", "boolean"]
 		},
+		avoidWater: { default: true },
 		terrain: {
 			default: "",
 			nodePath: true
@@ -11809,6 +13309,19 @@ var Tree3D = class Tree3D extends Node3D {
 	* it (keeps retrying until a terrain appears), false disables draping.
 	*/
 	drape = null;
+	/**
+	* Keep trunks out of standing and running water (default true) — a valley a
+	* rill runs through has a grove on its banks, not trees in the current.
+	*
+	* `Foliage3D` and `Flowers3D` have had this since they were written, with the
+	* same default and the same reason; the TREE — the tallest thing in a
+	* landscape and the one that most obviously does not grow midstream — did
+	* not. Measured on a river-valley game: two of twenty-two trunks stood in the
+	* rill.
+	*
+	* `false` is the mangrove, the cypress swamp and the flooded forest.
+	*/
+	avoidWater = true;
 	/** Node path to the Terrain3D to drape onto ('' = auto-find the first one). */
 	terrain = "";
 	/** Resolved drape target + the grove's world position, set per rebuild. */
@@ -12062,13 +13575,45 @@ var Tree3D = class Tree3D extends Node3D {
 		}, void 0, this.noteTextureError);
 	}
 	/** Per-instance placement + jitter — ONE rng draw order for both paths. */
+	/**
+	* Where every trunk of this grove stands, in WORLD coordinates.
+	*
+	* `drape` is the prop that puts a grove on the ground it grows from, and
+	* nothing could ask whether it had. `UiMinimap.markers()` and
+	* `HudLayer.focusables()` are the same accessor for the same reason: a
+	* feature whose effect no harness can read is a feature nobody checks.
+	*
+	* Recomputed from the seed rather than read back off the InstancedMesh, so it
+	* answers headless too — where there is no mesh at all.
+	*/
+	trunks() {
+		this.resolveDrape();
+		const out = [];
+		const [wx, wy, wz] = worldXZY(this);
+		this.scatter(new Rng(this.seed), (_i, matrix) => {
+			positionScratch.setFromMatrixPosition(matrix);
+			out.push([
+				positionScratch.x + wx,
+				positionScratch.y + wy,
+				positionScratch.z + wz
+			]);
+		});
+		return out;
+	}
 	scatter(rng, place) {
 		const halfX = (this.area[0] ?? 0) / 2;
 		const halfZ = (this.area[1] ?? 0) / 2;
+		const wet = this.avoidWater ? collectWetSurfaces(this) : [];
+		const [wx, wy, wz] = worldXZY(this);
 		for (let i = 0; i < this.count; i++) {
-			const lx = this.count === 1 ? 0 : rng.range(-halfX, halfX);
-			const lz = this.count === 1 ? 0 : rng.range(-halfZ, halfZ);
-			positionScratch.set(lx, this.drape ? this.bedY(lx, lz) : 0, lz);
+			let lx = this.count === 1 ? 0 : rng.range(-halfX, halfX);
+			let lz = this.count === 1 ? 0 : rng.range(-halfZ, halfZ);
+			if (wet.length > 0) for (let tries = 0; tries < DRY_TRIES; tries++) {
+				if (!isUnderWater(wet, lx + wx, lz + wz, this.bedY(lx, lz) + wy)) break;
+				lx = rng.range(-halfX, halfX);
+				lz = rng.range(-halfZ, halfZ);
+			}
+			positionScratch.set(lx, this.bedY(lx, lz), lz);
 			quaternionScratch.setFromAxisAngle(Y_AXIS, rng.range(0, Math.PI * 2));
 			const h = this.height * rng.range(HEIGHT_JITTER[0], HEIGHT_JITTER[1]);
 			const girth = h * rng.range(.9, 1.1);
@@ -12244,6 +13789,195 @@ const quaternionScratch = new Quaternion();
 const scaleScratch = new Vector3();
 const colorScratch = new Color();
 //#endregion
+//#region src/3d/nodes/vehicle-3d.ts
+const DEG = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+/**
+* A car in one node — Rapier's raycast vehicle under a `RigidBody3D` chassis.
+*
+* ```json
+* { "name": "Car", "type": "RigidBody3D",
+*   "props": { "mass": 800, "collider": { "shape": "box", "size": [1.8, 0.6, 4] } },
+*   "children": [
+*     { "name": "Drive", "type": "Vehicle3D", "props": { "wheels": [
+*         { "position": [-0.8, -0.1,  1.4], "steer": true },
+*         { "position": [ 0.8, -0.1,  1.4], "steer": true },
+*         { "position": [-0.8, -0.1, -1.4], "drive": true },
+*         { "position": [ 0.8, -0.1, -1.4], "drive": true } ] } },
+*     { "name": "Wheel0", "type": "Node3D", "props": { "position": [-0.8, -0.1, 1.4] },
+*       "children": [ { "name": "Hub", "type": "Node3D", "children": [ …the tyre mesh… ] } ] }
+*   ] }
+* ```
+*
+* The wheels are springs that never touch anything (a ray each), so a car
+* cannot catch a kerb on a wheel body or disagree with its axle; the throttle,
+* steer and brake come from the `move` vector and the `brake` button (or from
+* code, with `moveAction: ""`). Forward is +z, the +Z-forward rule. A child
+* named `Wheel<i>` is posed every step — it hangs on its spring and turns to
+* steer — and its child `Hub` spins as the wheel rolls.
+*/
+var Vehicle3D = class extends Node3D {
+	static typeName = "Vehicle3D";
+	static props = {
+		/** `[{ position, radius?, rest?, steer?, drive? }]` — at least one; defaults radius 0.35, rest 0.3. */
+		wheels: { default: [] },
+		/** Spring stiffness (N/m per kg-ish — 20 soft, 30 a car, 60 a kart). */
+		suspensionStiffness: { default: 30 },
+		suspensionCompression: { default: 2.3 },
+		suspensionRelaxation: { default: 3.5 },
+		/** How far a spring may compress from rest (m). */
+		maxTravel: { default: .3 },
+		/** Tyre grip along the wheel (higher = less spin-out). */
+		friction: { default: 2.5 },
+		/** Tyre grip across the wheel (lower = more drift). */
+		sideFriction: { default: 1 },
+		/** Full lock, degrees. */
+		maxSteerDeg: { default: 32 },
+		/** Force on each driven wheel at full throttle (N). */
+		engineForce: { default: 1500 },
+		/** Brake force on every wheel at full brake. */
+		brakeForce: { default: 40 },
+		/** The stick: up = throttle, down = reverse, left/right = steer. '' = code writes `throttle`/`steer`. */
+		moveAction: { default: "move" },
+		/** Held = full brake. */
+		brakeAction: { default: "brake" },
+		/**
+		* Off = parked: the throttle and steering read nothing and the brake is
+		* held, while the suspension still settles and the wheels still pose.
+		* The switch a game flips while nobody is behind the wheel — both the
+		* car and the character read `move`, so without it one press moves both.
+		*/
+		enabled: { default: true }
+	};
+	wheels = [];
+	suspensionStiffness = 30;
+	suspensionCompression = 2.3;
+	suspensionRelaxation = 3.5;
+	maxTravel = .3;
+	friction = 2.5;
+	sideFriction = 1;
+	maxSteerDeg = 32;
+	engineForce = 1500;
+	brakeForce = 40;
+	moveAction = "move";
+	brakeAction = "brake";
+	enabled = true;
+	/** Live inputs, −1..1 (throttle, steer) and 0..1 (brake) — the actions write these, or your code does. */
+	throttle = 0;
+	steer = 0;
+	brake = 0;
+	/** Forward speed, m/s (negative in reverse). */
+	speed = 0;
+	/** @internal Written by the physics adapter each step. */
+	_states = [];
+	reportedActions = /* @__PURE__ */ new Set();
+	/** What wheel `i` is doing. */
+	wheel(i) {
+		return this._states[i] ?? {
+			contact: false,
+			suspension: this.specs()[i]?.rest ?? .3,
+			rotation: 0,
+			steering: 0
+		};
+	}
+	/** The wheels with every default filled in. */
+	specs() {
+		return this.wheels.map((w) => {
+			const raw = w;
+			return {
+				position: [
+					raw.position?.[0] ?? 0,
+					raw.position?.[1] ?? 0,
+					raw.position?.[2] ?? 0
+				],
+				radius: raw.radius ?? .35,
+				rest: raw.rest ?? .3,
+				steer: raw.steer ?? false,
+				drive: raw.drive ?? false
+			};
+		});
+	}
+	get body() {
+		const parent = this.parent;
+		if (!(parent instanceof RigidBody3D)) throw new IncantoError("TREE_VIOLATION", `Vehicle3D '${this.name}' must be a child of a RigidBody3D — the chassis (parent is '${parent?.name ?? "none"}').`);
+		return parent;
+	}
+	onEnterTree() {
+		this.body;
+		if (!Array.isArray(this.wheels) || this.wheels.length === 0) throw new IncantoError("BAD_FORMAT", `Vehicle3D '${this.getPath()}': "wheels" must list at least one wheel — { "position": [x, y, z], "steer"?, "drive"? }.`);
+		this.wheels.forEach((w, i) => {
+			const p = w.position;
+			if (!Array.isArray(p) || p.length !== 3 || p.some((n) => typeof n !== "number" || !Number.isFinite(n))) throw new IncantoError("BAD_FORMAT", `Vehicle3D '${this.getPath()}': wheel ${i} needs a "position": [x, y, z] in the chassis's frame.`);
+		});
+	}
+	onExitTree() {
+		this.body._physics3d?._freeVehicle(this);
+	}
+	fixedUpdate(dt) {
+		const input = this.tree?.engine?.input;
+		const physics = this.body._physics3d;
+		if (input && this.moveAction !== "") {
+			const v = tolerateUnknownAction({
+				engine: this.tree?.engine,
+				who: this.getPath(),
+				reported: this.reportedActions,
+				consequence: "The car will not move.",
+				authored: this.moveAction !== "move"
+			}, this.moveAction, () => input.getVector(this.moveAction), {
+				x: 0,
+				y: 0
+			});
+			this.throttle = -v.y;
+			this.steer = v.x;
+			this.brake = tolerateUnknownAction({
+				engine: this.tree?.engine,
+				who: this.getPath(),
+				reported: this.reportedActions,
+				consequence: "The car will never brake.",
+				authored: this.brakeAction !== "brake"
+			}, this.brakeAction, () => input.isPressed(this.brakeAction) ? 1 : 0, 0);
+		}
+		if (!this.enabled) {
+			this.throttle = 0;
+			this.steer = 0;
+			this.brake = 1;
+		}
+		if (physics) physics._driveVehicle(this, dt);
+		this.poseWheels();
+	}
+	/** `Wheel<i>` hangs on its spring and turns to steer; its `Hub` spins. */
+	poseWheels() {
+		const specs = this.specs();
+		for (let i = 0; i < specs.length; i++) {
+			const spec = specs[i];
+			if (!spec) continue;
+			const wheel = this.parent?.getNodeOrNull(`Wheel${i}`);
+			if (!wheel || !(wheel instanceof Node3D)) continue;
+			const s = this.wheel(i);
+			wheel.position = [
+				spec.position[0],
+				spec.position[1] - s.suspension,
+				spec.position[2]
+			];
+			wheel.rotation = [
+				0,
+				s.steering * RAD2DEG,
+				0
+			];
+			const hub = wheel.getNodeOrNull("Hub");
+			if (hub && hub instanceof Node3D) hub.rotation = [
+				s.rotation * RAD2DEG,
+				hub.rotation[1] ?? 0,
+				hub.rotation[2] ?? 0
+			];
+		}
+	}
+	/** Full lock, radians. */
+	get maxSteer() {
+		return this.maxSteerDeg * DEG;
+	}
+};
+//#endregion
 //#region src/3d/nodes/voxel-grid-3d.ts
 /**
 * Face colors per tile (front,right,back,left,top,bottom) — the agent8
@@ -13282,6 +15016,213 @@ void main() {
 }
 `;
 //#endregion
+//#region src/3d/nodes/weather-3d.ts
+/**
+* Rain falls this fast (m/s); snow this slow. Sizes are in px like every
+* particle prop (×0.01 = world metres, attenuated with distance): a 3 px drop
+* is 3 cm, sub-pixel ten metres away and invisible against a bright sky —
+* measured on the rooftops — so a drop is a hand wide and a flake wider.
+*/
+const RAIN = {
+	speed: [10, 14],
+	size: 55,
+	color: "#eaf3ff",
+	alpha: .75,
+	rate: 1500,
+	spread: 4,
+	cap: 4e3
+};
+const SNOW = {
+	speed: [.6, 1.4],
+	size: 14,
+	color: "#ffffff",
+	alpha: .9,
+	rate: 500,
+	spread: 50,
+	cap: 6e3
+};
+const M_TO_PX = 100;
+/** How often the tree is re-scanned for the current camera (fixed steps). */
+const CAMERA_SCAN_STEPS = 60;
+/**
+* Weather — rain or snow that follows the camera.
+*
+* The scene format had a sky, a fog, a cloud deck and a sun, and no weather:
+* rain was forty lines of `Particles3D` tuning an author had to know, plus a
+* script to keep the emitter over the camera. One node now:
+*
+* ```json
+* { "name": "Rain", "type": "Weather3D", "props": { "kind": "rain", "intensity": 0.7, "wind": [2, 0] } }
+* ```
+*
+* The drops are born anywhere in a box `radius` wide and `height` above
+* whatever is followed (the current `Camera3D` unless `follow` names a node),
+* fall in world space, and stay where they fell when the camera moves on.
+* Every `Particles3D` prop is still here to override (a colour, a size), but
+* `kind` sets them all and `intensity` scales the rate live.
+*/
+/**
+* A raindrop's stamp: a vertical streak with soft ends, not a dot.
+*
+* Rain is drawn as point sprites, and a point sprite is SQUARE — so the streak
+* lives inside the texture: a thin bright column down the middle with
+* transparent sides. Measured before this existed: a downpour at intensity 1
+* put 2,600 round dots on screen and read as a dirty lens.
+*/
+let streakStamp = null;
+function streakSprite() {
+	if (streakStamp) return streakStamp;
+	const size = 64;
+	const data = new Uint8Array(size * size * 4);
+	const halfW = size * .055;
+	const centre = (size - 1) / 2;
+	for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+		const dx = Math.abs(x - centre) / halfW;
+		const along = Math.abs(y - centre) / centre;
+		const ends = Math.max(0, 1 - Math.max(0, along - .72) / .28);
+		const across = Math.max(0, 1 - dx * dx);
+		const i = (y * size + x) * 4;
+		data[i] = 255;
+		data[i + 1] = 255;
+		data[i + 2] = 255;
+		data[i + 3] = Math.round(Math.min(1, across * ends) * 255);
+	}
+	const texture = new DataTexture(data, size, size, RGBAFormat);
+	texture.needsUpdate = true;
+	streakStamp = texture;
+	return texture;
+}
+var Weather3D = class extends Particles3D {
+	static typeName = "Weather3D";
+	static props = {
+		/** `rain` — fast, straight, a shower; `snow` — slow, drifting flakes. */
+		kind: {
+			default: "rain",
+			options: ["rain", "snow"]
+		},
+		/** How much of it, 0..1 (scales the rate live; 0 = a dry sky). */
+		intensity: {
+			default: .6,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
+		/** Half-width (m) of the box the drops are born in, around the camera. */
+		radius: { default: 20 },
+		/** How far above the camera they are born (m). */
+		height: { default: 12 },
+		/** A steady drift, m/s, on the ground plane `[x, z]`. */
+		wind: { default: [0, 0] },
+		/** What to follow; '' = the current Camera3D. */
+		follow: {
+			default: "",
+			nodePath: true
+		}
+	};
+	kind = "rain";
+	intensity = .6;
+	radius = 20;
+	height = 12;
+	wind = [0, 0];
+	follow = "";
+	/** Rain is a streak; snow keeps the soft flake the particle system draws. */
+	sprite() {
+		return this.kind === "snow" ? super.sprite() : streakSprite();
+	}
+	tunedFor = "";
+	camera = null;
+	cameraScanIn = 0;
+	onEnterTree() {
+		super.onEnterTree?.();
+		this.tune();
+	}
+	/** Set the inherited particle props from `kind` — once, and again if it changes. */
+	tune() {
+		const t = this.kind === "snow" ? SNOW : RAIN;
+		this.worldSpace = true;
+		this.blend = "normal";
+		this.directionDeg = 90;
+		this.spreadDeg = t.spread;
+		this.speed = [(t.speed[0] ?? 1) * M_TO_PX, (t.speed[1] ?? 1) * M_TO_PX];
+		const fall = t.speed[0] ?? 1;
+		this.lifetime = [(this.height + 2) / fall, (this.height + 6) / fall];
+		this.gravity = [
+			0,
+			0,
+			0
+		];
+		this.drag = 0;
+		this.sizeStart = t.size;
+		this.sizeEnd = t.size;
+		this.colorStart = t.color;
+		this.colorEnd = t.color;
+		this.alphaStart = t.alpha;
+		this.alphaEnd = t.alpha * .8;
+		this.maxParticles = t.cap;
+		this.emitBox = [
+			this.radius,
+			.5,
+			this.radius
+		];
+		this.drift = [
+			(this.wind[0] ?? 0) * M_TO_PX,
+			0,
+			(this.wind[1] ?? 0) * M_TO_PX
+		];
+		this.rate = t.rate * this.intensity;
+		this.tunedFor = this.tuning();
+		this._rebuildSim();
+	}
+	tuning() {
+		return `${this.kind}/${this.radius}/${this.height}/${this.wind[0] ?? 0}/${this.wind[1] ?? 0}`;
+	}
+	followed() {
+		if (this.follow !== "") return this.getNodeOrNull(this.follow);
+		if (this.cameraScanIn <= 0 || !this.camera || this.camera.tree === null) {
+			this.camera = currentCamera(this.getRoot());
+			this.cameraScanIn = CAMERA_SCAN_STEPS;
+		}
+		this.cameraScanIn -= 1;
+		return this.camera;
+	}
+	update(dt) {
+		if (this.tunedFor !== this.tuning()) this.tune();
+		const t = this.kind === "snow" ? SNOW : RAIN;
+		this.rate = t.rate * Math.max(0, Math.min(1, this.intensity));
+		const target = this.followed();
+		if (target) {
+			const at = worldPosition(target);
+			const parentAt = this.parent ? worldPosition(this.parent) : [
+				0,
+				0,
+				0
+			];
+			this.position = [
+				(at[0] ?? 0) - (parentAt[0] ?? 0),
+				(at[1] ?? 0) + this.height - (parentAt[1] ?? 0),
+				(at[2] ?? 0) - (parentAt[2] ?? 0)
+			];
+		}
+		super.update(dt);
+	}
+};
+function currentCamera(root) {
+	let first = null;
+	const walk = (n) => {
+		if (n instanceof Camera3D) {
+			if (n.current) return n;
+			first ??= n;
+		}
+		for (const c of n.children) {
+			const hit = walk(c);
+			if (hit) return hit;
+		}
+		return null;
+	};
+	return walk(root) ?? first;
+}
+//#endregion
 //#region src/3d/register.ts
 /**
 * Register the 3D node taxonomy (and the core nodes). Call once in your game
@@ -13291,6 +15232,10 @@ function registerNodes3D() {
 	registerCoreNodes();
 	registerNode(Node3D);
 	registerNode(Particles3D);
+	registerNode(Weather3D);
+	registerNode(Flock3D);
+	registerNode(Ragdoll3D);
+	registerNode(Vehicle3D);
 	registerNode(MeshInstance3D);
 	registerNode(LoftMesh3D);
 	registerNode(Sprite3D);
@@ -13353,4 +15298,4 @@ function resolveEnvironmentHdri(env) {
 	return null;
 }
 //#endregion
-export { Billboard3D as A, cameraRelative as B, Flowers3D as C, Camera3D as D, CharacterController3D as E, Joint3D as F, acquireOwnTexture as G, movementState as H, InstancedMesh3D as I, acquireTexture as K, MeshInstance3D as L, DEFAULT_TERRAIN_TEXTURE_BASE as M, TERRAIN_THEMES as N, BoneLookAt3D as O, terrainThemeLayers as P, buildMeshGeometry as R, DENSITY_PRESETS as S, FLOWER_VARIETIES as T, rigPose as U, keyboardIntensity as V, TextureCache3D as W, LoftMesh3D as _, Tree3D as a, SpotLight3D as b, buildRiverRings as c, riverCarveChannels as d, riverStepFor as f, ModelInstance3D as g, Particles3D as h, VoxelGrid3D as i, Terrain3D as j, BoneAttachment3D as k, findRiverCoverageGaps as l, traceDownhillPath as m, registerNodes3D as n, Trail3D as o, smoothCourse as p, VOXEL_PALETTE as r, River3D as s, resolveEnvironmentHdri as t, projectToRiver as u, DirectionalLight3D as v, resolveFlowerDensity as w, Foliage3D as x, OmniLight3D as y, QUARTER_PITCH as z };
+export { CharacterController3D as A, InstancedMesh3D as B, SpotLight3D as C, resolveFlowerDensity as D, Flowers3D as E, Terrain3D as F, keyboardIntensity as G, buildMeshGeometry as H, DEFAULT_TERRAIN_TEXTURE_BASE as I, TextureCache3D as J, movementState as K, TERRAIN_THEMES as L, BoneLookAt3D as M, BoneAttachment3D as N, FLOWER_VARIETIES as O, Billboard3D as P, terrainThemeLayers as R, OmniLight3D as S, DENSITY_PRESETS as T, QUARTER_PITCH as U, MeshInstance3D as V, cameraRelative as W, acquireTexture as X, acquireOwnTexture as Y, Ragdoll3D as _, VoxelGrid3D as a, LoftMesh3D as b, Trail3D as c, findRiverCoverageGaps as d, projectToRiver as f, traceDownhillPath as g, smoothCourse as h, VOXEL_PALETTE as i, Camera3D as j, Flock3D as k, River3D as l, riverStepFor as m, registerNodes3D as n, Vehicle3D as o, riverCarveChannels as p, rigPose as q, Weather3D as r, Tree3D as s, resolveEnvironmentHdri as t, buildRiverRings as u, Particles3D as v, Foliage3D as w, DirectionalLight3D as x, ModelInstance3D as y, Joint3D as z };