incanto 0.74.0 → 0.76.0

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

@@ -1,14 +1,14 @@
-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 buildSeaSpectrum, it as CharacterBody3D, mt as seaFftSupported, nt as rejectScale, ot as RigidBody3D, pt as SeaFft, rt as Area3D, st as StaticBody3D, tt as WaterCutout3D, vt as findHealth } from "./gameplay-Bfff_beb.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";
+import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CubeCamera, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, HalfFloatType, 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, WebGLCubeRenderTarget } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
 //#region src/3d/textures.ts
 /**
@@ -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,8 +2972,47 @@ const MOVEMENT_STATES = [
 	"walk",
 	"run",
 	"fastRun",
-	"airborne"
+	"airborne",
+	"swim",
+	"climb",
+	"crouch",
+	"sneak",
+	"dash"
 ];
+/**
+* What to play when the scene's `animations` map has no clip for a state.
+*
+* A missing entry used to leave whatever was playing BEFORE, which is never
+* what anyone meant: a character swimming across a bay in a frozen jump pose,
+* because `swim` was unmapped and the last state was `airborne`. Every state
+* added after the original five had this — `dash`, `climb`, `sneak`, `crouch`
+* — and no scene in the repo mapped any of them.
+*
+* Each chain ends at `idle`, so any map with one clip in it animates.
+*/
+const CLIP_FALLBACK = {
+	idle: [],
+	walk: ["idle"],
+	run: ["walk", "idle"],
+	fastRun: [
+		"run",
+		"walk",
+		"idle"
+	],
+	airborne: ["idle"],
+	swim: ["walk", "idle"],
+	climb: ["walk", "idle"],
+	crouch: ["idle"],
+	sneak: ["walk", "idle"],
+	dash: [
+		"fastRun",
+		"run",
+		"walk",
+		"idle"
+	]
+};
+/** How much of a swimmer's head rides clear of the water (m) — see `swimDepth`. */
+const HEAD_ABOVE_WATER = .15;
 /** Air control stands down this long after a wall kick, so the kick lands. */
 const WALL_LOCKOUT_SECONDS = .18;
 const ACC_DELTA_TIME = 8;
@@ -2820,13 +3020,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 +3067,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 +3116,115 @@ var CharacterController3D = class extends Node3D {
 		fallGravity: { default: 2.5 },
 		floatHeight: { default: .01 },
 		stepHeight: { default: .35 },
+		slopeLimitDeg: {
+			default: 55,
+			range: {
+				min: 0,
+				max: 90
+			}
+		},
+		/** 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: null,
+			kinds: ["null", "number"]
+		},
+		/** 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 +3236,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 +3258,7 @@ var CharacterController3D = class extends Node3D {
 			}
 		}
 	};
+	enabled = true;
 	view = "free";
 	camDistance = 4;
 	eyeHeight = .64;
@@ -2940,6 +3285,60 @@ 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;
+	/**
+	* How far the body's ORIGIN rides below the surface while swimming (m), or
+	* `null` (the default) to take it from the body: deep enough that the head
+	* rides 15 cm clear and the rest is in the water, which is what treading
+	* water looks like.
+	*
+	* The origin is the middle of the capsule, so a fixed number is only ever
+	* right for one character size. The 0.35 m this used to default to left the
+	* head of a standard 1.68 m rig 0.46 m clear of the surface — a person
+	* floating like a boat, chest and shoulders in the air.
+	*/
+	swimDepth = null;
+	/** 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
@@ -2958,13 +3357,29 @@ var CharacterController3D = class extends Node3D {
 	* 200 kg character does not move a seesaw a 70 kg crate tips.
 	*/
 	stepHeight = .35;
+	/**
+	* The steepest ground this character STANDS on, in degrees (0-90).
+	*
+	* At or under it the ground is ground: the character holds its place with no
+	* slide at all, however long you leave it there. Over it the ground stops
+	* counting as ground — no hover spring, no `grounded`, no jump reset — and
+	* the body slips off the face, which is what a slope limit means in every
+	* engine that has one.
+	*
+	* 55° is a person. A mountain goat is 80; something on wheels is 25. `90`
+	* turns the limit off — which is what this controller did before it had one,
+	* and why it slid down a 7° hillside.
+	*/
+	slopeLimitDeg = 55;
 	mouseLook = true;
 	zoomMin = 0;
 	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 +3404,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 +3471,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 +3564,33 @@ 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;
+	/** Slope of the ground under the character, degrees — 0 when there is none. */
+	groundSlopeDeg = 0;
+	/** Its outward normal, or null. `[0, 1, 0]` is flat ground. */
+	groundNormal = null;
+	/** 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;
@@ -3059,6 +3600,12 @@ var CharacterController3D = class extends Node3D {
 	jumping = false;
 	/** Seconds of air control still suppressed after a wall kick. */
 	wallLockout = 0;
+	/** What the anti-slide has learned it must keep paying to hold a slope. */
+	slideHold = 0;
+	/** Where the body stood last step, for the anti-slide's position error. */
+	slideFrom = null;
+	/** Seconds since the player last asked this character to move. */
+	stillFor = 0;
 	/** The outward normal of the wall being pressed into this step, if any. */
 	wallNormal = null;
 	get body() {
@@ -3068,6 +3615,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 +3633,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;
@@ -3093,6 +3650,8 @@ var CharacterController3D = class extends Node3D {
 		let toi = null;
 		/** What the probe landed on — the platform, when there is one. */
 		let ground = null;
+		/** …and which way its surface faces, for the slope limit and the spring. */
+		let normal = null;
 		for (const [ox, oz] of [
 			[0, 0],
 			[radius, 0],
@@ -3109,18 +3668,60 @@ 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;
 					ground = hit.node;
+					const n = hit.normal;
+					normal = n ? [
+						n[0] ?? 0,
+						n[1] ?? 1,
+						n[2] ?? 0
+					] : null;
 				}
 				if (ox === 0 && oz === 0) break;
 			}
 		}
-		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 upDot = normal ? Math.max(-1, Math.min(1, normal[1] ?? 1)) : 1;
+		const slopeDeg = toi === null ? 0 : Math.acos(Math.max(upDot, 0)) * 180 / Math.PI;
+		this.groundSlopeDeg = slopeDeg;
+		this.groundNormal = toi === null ? null : normal ?? [
+			0,
+			1,
+			0
+		];
+		const standable = slopeDeg <= this.slopeLimitDeg;
+		/** The spring's target: `floatHeight` of clearance PERPENDICULAR to the ground. */
+		const holdDis = floatingDis / Math.max(upDot, .35);
+		this.grounded = toi !== null && toi < holdDis * 2 && standable;
+		if (!this.grounded) {
+			this.slideHold = 0;
+			this.slideFrom = null;
+		}
+		const carry = this.groundCarry(standable ? ground : null, dt);
+		const footed = toi !== null && toi < holdDis * 1.3 && standable && (vel[1] ?? 0) <= .5;
+		const water = this.swimSpeed > 0 ? this.surfaceAt(pos[0], pos[2]) : null;
+		const surface = water === null ? null : water[0];
+		const swimDepth = this.swimDepth ?? Math.max(halfHeight + radius - HEAD_ABOVE_WATER, .05);
+		const waterline = surface === null ? null : surface - 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 + radius;
+		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 +3740,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 +3811,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 +3854,40 @@ 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
 		]);
+		this.stillFor = moving ? 0 : this.stillFor + dt;
+		if (this.grounded && !swimming && !climbing && !onLadder && !this.jumping) {
+			const n = this.groundNormal;
+			const nx = n?.[0] ?? 0;
+			const nz = n?.[2] ?? 0;
+			const sinSlope = Math.hypot(nx, nz);
+			if (sinSlope > .001) {
+				const ux = nx / sinSlope;
+				const uz = nz / sinSlope;
+				const drift = (vel[0] - carry[0]) * ux + (vel[2] - carry[1]) * uz;
+				if (this.stillFor < .1) {
+					this.slideHold = 0;
+					this.slideFrom = null;
+				} else {
+					const from = this.slideFrom;
+					const moved = from === null ? 0 : (pos[0] - from[0]) * ux + (pos[2] - from[1]) * uz;
+					this.slideFrom = [pos[0], pos[2]];
+					this.slideHold = Math.max(-2, Math.min(2, this.slideHold + moved / dt * .5));
+					const hold = drift + this.slideHold;
+					if (hold !== 0) body.applyImpulse([
+						-hold * ux * mass,
+						0,
+						-hold * uz * 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,34 +3899,107 @@ 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) {
-			const spring = SPRING_K * (floatingDis - springToi) - vel[1] * SPRING_DAMPING;
+		if (springToi !== null && springToi < floatingDis * 2 && (!this.jumping || mantling) && !swimming && !climbing && !onLadder && (vel[1] ?? 0) < 2) {
+			const spring = SPRING_K * (holdDis - springToi) - vel[1] * SPRING_DAMPING;
 			body.applyImpulse([
 				0,
 				spring * mass,
 				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 +4017,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.effectiveSwimDepth() + 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 +4048,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 +4057,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,23 +4066,46 @@ 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];
+			let clip = this.animations[next];
+			if (!clip) for (const alt of CLIP_FALLBACK[next]) {
+				const c = this.animations[alt];
+				if (c) {
+					clip = c;
+					break;
+				}
+			}
 			if (clip && this.skinPath !== "") {
 				const skin = this.getNodeOrNull(this.skinPath);
 				if (skin && "animation" in skin) skin.animation = clip;
 			}
 			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 +4118,84 @@ 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;
+	}
+	/** `swimDepth`, or what it is derived to be for this body (see the prop). */
+	effectiveSwimDepth() {
+		if (this.swimDepth !== null) return this.swimDepth;
+		const body = this.parent;
+		const radius = body?.collider?.radius ?? .32;
+		const halfHeight = (body?.collider?.height ?? 1) / 2;
+		return Math.max(halfHeight + radius - HEAD_ABOVE_WATER, .05);
+	}
+	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 +4219,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 +4233,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 +4292,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;
@@ -3428,9 +4316,368 @@ var CharacterController3D = class extends Node3D {
 		return this.cameraCache;
 	}
 };
-function clamp(v, lo, hi) {
-	return Math.min(hi, Math.max(lo, v));
-}
+function clamp(v, lo, hi) {
+	return Math.min(hi, Math.max(lo, v));
+}
+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;
+	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
+	];
+}
+/**
+* The EDGE, not the level.
+*
+* Jump used to read `isPressed`, so holding the button re-jumped on every frame
+* the raycast found ground — an auto-hop nobody asked for, and one that makes
+* coyote time incoherent (a held button would re-fire through the whole
+* window). Undeclared actions are tolerated, and reported once.
+*/
+/** A node's world x/z — the platform may itself be parented to something. */
+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;
@@ -3447,19 +4694,6 @@ function worldOf(node) {
 		z
 	];
 }
-/**
-* The EDGE, not the level.
-*
-* Jump used to read `isPressed`, so holding the button re-jumped on every frame
-* the raycast found ground — an auto-hop nobody asked for, and one that makes
-* coyote time incoherent (a held button would re-fire through the whole
-* window). Undeclared actions are tolerated, and reported once.
-*/
-/** A node's world x/z — the platform may itself be parented to something. */
-function groundXZ(node) {
-	const world = worldPosition(node);
-	return [world[0] ?? 0, world[2] ?? 0];
-}
 //#endregion
 //#region src/3d/vegetation/grass-placement.ts
 const NOISE_SCALE = .15;
@@ -7625,7 +8859,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 +8928,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 +8962,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 +9094,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 +9120,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 +9227,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
@@ -8894,6 +10529,15 @@ uniform float uRippleStrength;
 uniform float uFlowRate;
 uniform float uSparkle;
 uniform float uFresnelScale;
+// the river's own sky cube (river-3d.ts): what the surface mirrors instead of
+// the painted three-colour gradient, which stays as the headless fallback
+uniform samplerCube uEnvironmentMap;
+uniform float uUseEnvironmentMap;
+// the live ripple layer (fft-gpu.ts), a 6 m patch in the ribbon's own frame
+uniform float uRippleOn;
+uniform sampler2D uRippleNormal;
+uniform float uRipplePatch;
+uniform float uRippleGain;
 /**
  * Rocks standing in the current: xz = centre, z = radius, w = how much of the
  * water they break (0 = drowned and quiet, 1 = the crest stands proud).
@@ -8936,6 +10580,32 @@ float riverStreak(vec2 p) {
   return riverNoise(q) * 0.5 + riverNoise(q * 3.3 + 7.3) * 0.5;
 }
 
+/** water-that-reads-as-water: the FINE wavelets — the two ripple octaves are
+ * a hand-span and up, so at the range a player actually stands from a creek
+ * the surface tilted in soft blobs and nothing on it could ever face the sun
+ * (the gel read). A third, much shorter field, differenced at its own step
+ * (the ripple's 0.35 step is wider than these wavelets), gives the normal the
+ * facets that glitter and that shatter the reflection; it fades out where a
+ * pixel would integrate it into speckle. Squeezed downstream like the rest. */
+// Karis' split-sum fit: what a ROUGH surface reflects at this angle — see the
+// sea-state fresnel note in shaders.ts. A river at a grazing view is a field
+// of wavelets, not a mirror, and the flat-Schlick sheet of sky it used to wear
+// is the plastic look this replaces.
+vec2 envBRDFApprox(float roughness, float NoV) {
+  const vec4 c0 = vec4(-1.0, -0.0275, -0.572, 0.022);
+  const vec4 c1 = vec4(1.0, 0.0425, 1.04, -0.04);
+  vec4 r = roughness * c0 + c1;
+  float a004 = min(r.x * r.x, exp2(-9.28 * NoV)) * r.x + r.y;
+  return vec2(-1.04, 1.04) * a004 + r.zw;
+}
+
+vec2 riverFineSlope(vec2 p) {
+  vec2 q = vec2(p.x * 10.7, p.y * 3.6) + 5.7;
+  const float e = 0.08;
+  float h = riverNoise(q);
+  return vec2(riverNoise(q + vec2(e, 0.0)) - h, riverNoise(q + vec2(0.0, e)) - h) / e;
+}
+
 void main() {
   float speed = vRiver.x;
   float column = vRiver.y;
@@ -9009,7 +10679,26 @@ void main() {
   // the gradient is a NOISE slope, not a water slope: clamp it before it tilts
   // the normal past a real wavelet (an over-driven normal throws fresnel to its
   // maximum everywhere and the river turns into a sheet of white sky)
-  vec2 slopeXY = clamp(ripple.yz * uRippleStrength * lively, vec2(-0.5), vec2(0.5));
+  float camDist = length(cameraPosition - vWorldPosition);
+  float fineFade = (1.0 - smoothstep(6.0, 34.0, camDist)) * lively;
+  vec2 fine = vec2(0.0);
+  if (fineFade > 0.01) {
+    vec2 fineA = riverFineSlope(base - vec2(travel * pA, 0.0));
+    vec2 fineB = riverFineSlope(base - vec2(travel * pB, 0.0));
+    // under the ripple FFT the noise keeps only the sub-pixel flash
+    fine = mix(fineA, fineB, blend) *
+      (0.028 * fineFade * (0.5 + 0.5 * uSparkle) * (uRippleOn > 0.5 ? 0.45 : 1.0));
+  }
+  // the ripple FFT, carried downstream in the ribbon's metres with the same
+  // dual-phase crossfade the noise uses (a field scrolled at a speed that
+  // varies along the river smears; two half-period copies do not)
+  if (uRippleOn > 0.5) {
+    float travelM = speed / max(uFlowRate, 0.001);
+    vec2 rA = texture2D(uRippleNormal, (vFlowUv - vec2(travelM * pA, 0.0)) / uRipplePatch, -1.0).xy;
+    vec2 rB = texture2D(uRippleNormal, (vFlowUv - vec2(travelM * pB, 0.0)) / uRipplePatch, -1.0).xy;
+    fine += mix(rA, rB, blend) * (uRippleGain * lively);
+  }
+  vec2 slopeXY = clamp(ripple.yz * uRippleStrength * lively + fine, vec2(-0.5), vec2(0.5));
   vec3 normal = normalize(vSurfaceNormal - dir3 * slopeXY.x - perp3 * slopeXY.y);
 
   vec3 viewDir = normalize(cameraPosition - vWorldPosition);
@@ -9113,31 +10802,53 @@ void main() {
   // eye is near the water — hold its dark tone well past the horizon line
   vec3 sky = mix(uBankColor, uHorizonColor, smoothstep(0.05, 0.34, reflectDir.y));
   sky = mix(sky, uSkyColor, smoothstep(0.34, 0.85, reflectDir.y));
-  float fresnel = clamp(
-    uFresnelScale * pow(1.0 - clamp(dot(normal, viewDir), 0.0, 1.0), 5.0),
-    0.0,
-    0.82
-  );
+  if (uUseEnvironmentMap > 0.5) {
+    // the REAL sky, from the river's own cube — near-clipped, so the lowest
+    // rays (which meet the bank a few metres off) keep the bank tone
+    vec3 lifted = vec3(reflectDir.x, max(reflectDir.y, 0.06), reflectDir.z);
+    vec3 cube = min(textureCube(uEnvironmentMap, lifted).rgb, vec3(2.5));
+    sky = mix(uBankColor, cube, smoothstep(0.02, 0.2, reflectDir.y));
+  }
+  float rough = clamp(0.045 + 0.28 * smoothstep(8.0, 140.0, camDist), 0.04, 0.35);
+  float NoVf = clamp(dot(normal, viewDir), 0.0, 1.0);
+  float fresnel = uFresnelScale * (0.02 + 0.98 * pow(1.0 - NoVf, 5.0));
+  {
+    vec2 fRough = envBRDFApprox(rough, NoVf);
+    vec2 fSmooth = envBRDFApprox(0.02, NoVf);
+    fresnel *= clamp((0.02 * fRough.x + fRough.y) / max(0.02 * fSmooth.x + fSmooth.y, 1e-3), 0.0, 1.35);
+  }
+  fresnel = clamp(fresnel, 0.0, 0.82);
 
   vec3 sunDir = normalize(uSunDirection);
   vec3 halfVec = normalize(sunDir + viewDir);
-  float ndh = max(dot(normal, halfVec), 0.0);
-  // Two lobes: a tight glitter spark, plus a whisper of broad sheen so the
-  // river still READS as a moving surface from across the valley, where the
-  // sparkle is smaller than a pixel.
-  //
-  // The broad lobe is the dangerous one. At exponent 18 it stays near 1 across
-  // a huge stretch of a near-flat surface, and at 0.22 · 1.6 that is a third of
-  // full white ADDED to every one of those fragments — a sheet of white lying
-  // over the water that reads as fog and swallows the bed, the foam and the
-  // rocks alike. Narrow it and cut its weight; the sparkle carries the sun.
-  float spec = (pow(ndh, 160.0) + pow(ndh, 34.0) * 0.07) * uSunIntensity;
-  // glitter: the same advected field gates the highlight so it breaks into
-  // travelling sparks instead of one smooth sheen
-  float glint = smoothstep(0.55, 0.95, ripple.x);
-  spec *= 0.45 + 0.55 * glint * uSparkle;
+  // ── the sun as a microfacet highlight ──────────────────────────────────
+  // water-that-reads-as-water: the two Blinn-Phong lobes (160 + a whisper of
+  // 34) were a hand-shaped sheen gated by the ripple field, capped at 1.2 —
+  // a running creek under a 40°-high sun showed no sun at all. One GGX lobe
+  // over the wavelet normal: resolved facets near the eye flash (the glitter
+  // a riffle throws), and with distance the roughness grows so the same lobe
+  // widens into the soft sheen a river shows from across the valley. HDR by
+  // design — the sun's reflection is the brightest thing on the water and
+  // the bloom pass reads it. RIVER_SUN_RADIANCE scales the sun against the
+  // unit-ish sky gradient this shader mirrors.
+  const float RIVER_SUN_RADIANCE = 30.0;
+  float NoL = clamp(dot(normal, sunDir), 0.0, 1.0);
+  float NoV = max(dot(normal, viewDir), 1e-3);
+  float NoH = clamp(dot(normal, halfVec), 0.0, 1.0);
+  float LoH = clamp(dot(sunDir, halfVec), 0.0, 1.0);
+  float a2 = rough * rough;
+  float dD = NoH * NoH * (a2 - 1.0) + 1.0;
+  float D = a2 / (3.14159265 * dD * dD);
+  float gV = NoL * sqrt(NoV * NoV * (1.0 - a2) + a2);
+  float gL = NoV * sqrt(NoL * NoL * (1.0 - a2) + a2);
+  float Vis = 0.5 / max(gV + gL, 1e-4);
+  float Fh = 0.02 + 0.98 * pow(1.0 - LoH, 5.0);
+  float spec = D * Vis * Fh * NoL * RIVER_SUN_RADIANCE * uSunIntensity;
+  spec *= 0.5 + 0.5 * uSparkle; // the ripples dial still tunes how much sun the water throws
   spec *= 1.0 - foam * 0.85; // froth is rough — it kills the mirror
-  spec = min(spec, 1.2); // a highlight, never a white-out
+  // a facet under a pixel aliases into a lone flash: the roughness ramp
+  // widens the lobe out there, the cap catches the last isolated ones
+  spec = min(spec, mix(5.0, 1.2, smoothstep(30.0, 200.0, camDist)));
 
   fresnel *= 1.0 - 0.85 * fall; // froth scatters; it does not reflect
   vec3 color = mix(body, sky, fresnel);
@@ -9237,6 +10948,21 @@ const FOAM_COLOR = "#e9f2ef";
 /** Per-frame scratch (no allocation in the render path). */
 const rockCamScratch = new Vector3();
 /** Fixed look constants — the props stay intent-level, these carry the craft. */
+/** The river's own sky: a slow cube of the world beyond its banks (the sky,
+* the far hills), refreshed every couple of seconds — what the surface
+* mirrors instead of a painted three-colour gradient. Near-clipped so the
+* banks themselves, metres away, never smear across it. */
+const RIVER_SKY_RESOLUTION = 128;
+const RIVER_SKY_INTERVAL = 2e3;
+const RIVER_SKY_NEAR = 60;
+/** The live ripple layer (see Water3D): a 6 m spectrum patch advected with
+* the current in the ribbon's own frame. */
+const RIVER_RIPPLE_SIZE = 128;
+const RIVER_RIPPLE_PATCH = 6;
+const RIVER_RIPPLE_FETCH = 150;
+const RIVER_RIPPLE_SEED = 4242;
+/** Ripple rms slope per unit of `ripples`. */
+const RIVER_RIPPLE_SLOPE = .07;
 const LOOK = {
 	/** Pattern units per meter of flow space. */
 	rippleScale: .85,
@@ -9379,6 +11105,12 @@ var River3D = class River3D extends Node3D {
 		0
 	];
 	_bodies = [];
+	cubeTarget = null;
+	cubeCamera = null;
+	lastSkyAt = 0;
+	rippleFft = null;
+	rippleSpectrum = null;
+	fftUnsupported = false;
 	/** Loader hook: a malformed river fails at LOAD, not as an invisible ribbon. */
 	static validateJson(node) {
 		rejectScale(node, "the flow query and its collider both");
@@ -9386,7 +11118,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 +11152,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);
@@ -9439,8 +11177,68 @@ var River3D = class River3D extends Node3D {
 			this.rockScanAt = this.time;
 			this.scanRocks();
 		}
-		const u = this._ensureObject3D().material.uniforms;
+		const mesh = this._ensureObject3D();
+		const u = mesh.material.uniforms;
 		this.syncRocks(u, ctx.camera.getWorldPosition(rockCamScratch));
+		if (typeof ctx.gl?.extensions?.has === "function") {
+			this.syncSky(ctx, mesh, u);
+			this.syncRipple(ctx, u);
+		}
+	}
+	/** The sky cube: the world beyond the banks, from above the channel's middle. */
+	syncSky(ctx, mesh, u) {
+		if (!this.cubeTarget) {
+			this.cubeTarget = new WebGLCubeRenderTarget(RIVER_SKY_RESOLUTION, {
+				generateMipmaps: true,
+				minFilter: LinearMipmapLinearFilter,
+				type: HalfFloatType
+			});
+			this.cubeCamera = new CubeCamera(RIVER_SKY_NEAR, 4e3, this.cubeTarget);
+			this.lastSkyAt = 0;
+		}
+		const now = Date.now();
+		if (this.lastSkyAt === 0 || now - this.lastSkyAt >= RIVER_SKY_INTERVAL) {
+			this.lastSkyAt = now;
+			const b = this.ringBounds();
+			const [wx, wy, wz] = this.world;
+			const cam = this.cubeCamera;
+			cam.position.set(wx + (b.minX + b.maxX) / 2, wy + 3, wz + (b.minZ + b.maxZ) / 2);
+			const wasVisible = mesh.visible;
+			mesh.visible = false;
+			cam.update(ctx.gl, ctx.scene);
+			mesh.visible = wasVisible;
+		}
+		if (u.uEnvironmentMap) u.uEnvironmentMap.value = this.cubeTarget.texture;
+		if (u.uUseEnvironmentMap) u.uUseEnvironmentMap.value = 1;
+	}
+	/** The ripple FFT, advected by the fragment in the ribbon's own frame. */
+	syncRipple(ctx, u) {
+		if (this.fftUnsupported) return;
+		if (!this.rippleFft) {
+			if (!seaFftSupported(ctx.gl)) {
+				this.fftUnsupported = true;
+				return;
+			}
+			this.rippleFft = new SeaFft(RIVER_RIPPLE_SIZE, RIVER_RIPPLE_PATCH);
+			this.rippleSpectrum = buildSeaSpectrum({
+				size: RIVER_RIPPLE_SIZE,
+				patch: RIVER_RIPPLE_PATCH,
+				wind: 3,
+				windDirectionDeg: 90,
+				seed: RIVER_RIPPLE_SEED,
+				choppiness: .3,
+				fetch: RIVER_RIPPLE_FETCH,
+				modes: 0
+			});
+			this.rippleFft.setSpectrum(this.rippleSpectrum);
+		}
+		this.rippleFft.update(ctx.gl, this.time);
+		if (u.uRippleNormal) u.uRippleNormal.value = this.rippleFft.normal;
+		if (u.uRippleOn) u.uRippleOn.value = 1;
+		if (u.uRippleGain && this.rippleSpectrum) {
+			const rms = this.rippleSpectrum.rmsSlope;
+			u.uRippleGain.value = rms > 0 ? RIVER_RIPPLE_SLOPE * this.ripples / rms : 0;
+		}
 	}
 	/**
 	* @internal Water surface height over a world point, or null where this
@@ -9529,6 +11327,11 @@ var River3D = class River3D extends Node3D {
 		const mesh = this._ensureObject3D();
 		mesh.geometry?.dispose();
 		mesh.material?.dispose?.();
+		this.cubeTarget?.dispose();
+		this.cubeTarget = null;
+		this.cubeCamera = null;
+		this.rippleFft?.dispose();
+		this.rippleFft = null;
 		super.free();
 	}
 	widthProfile() {
@@ -9552,7 +11355,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 +11400,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,
@@ -9688,6 +11491,12 @@ var River3D = class River3D extends Node3D {
 				uRockCount: { value: 0 },
 				uRocks: { value: Array.from({ length: ROCK_SLOTS }, () => new Vector4()) },
 				uFresnelScale: { value: LOOK.fresnelScale },
+				uEnvironmentMap: { value: null },
+				uUseEnvironmentMap: { value: 0 },
+				uRippleOn: { value: 0 },
+				uRippleNormal: { value: null },
+				uRipplePatch: { value: RIVER_RIPPLE_PATCH },
+				uRippleGain: { value: 0 },
 				uStandingAmp: { value: LOOK.standingAmp },
 				uGlideAmp: { value: LOOK.glideAmp }
 			},
@@ -11615,6 +13424,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 +13581,7 @@ var Tree3D = class Tree3D extends Node3D {
 			default: null,
 			kinds: ["null", "boolean"]
 		},
+		avoidWater: { default: true },
 		terrain: {
 			default: "",
 			nodePath: true
@@ -11809,6 +13621,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 +13887,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 +14101,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 +15328,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 +15544,10 @@ function registerNodes3D() {
 	registerCoreNodes();
 	registerNode(Node3D);
 	registerNode(Particles3D);
+	registerNode(Weather3D);
+	registerNode(Flock3D);
+	registerNode(Ragdoll3D);
+	registerNode(Vehicle3D);
 	registerNode(MeshInstance3D);
 	registerNode(LoftMesh3D);
 	registerNode(Sprite3D);
@@ -13353,4 +15610,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 };