incanto 0.26.0 → 0.27.0

package/dist/{register-CeWtdiCw.js → register-DcHXS1MA.js}

@@ -898,8 +898,15 @@ function themePatchTransfer(theme) {
 }
 //#endregion
 //#region src/3d/nodes/terrain-3d.ts
-/** Hard cap on grid segments per side (129×129 vertices ≈ the CPU budget). */
-const MAX_RESOLUTION = 128;
+/**
+* Hard cap on grid segments per side. 128 is the default and the right answer
+* for most maps; 256 (66k vertices) exists for terrain that has to hold
+* features finer than a cell — a 2 m creek bed on a 260 m map needs ~1 m
+* cells or the trench smooths away. The cost is CPU at build time (noise
+* octaves + carving per vertex), paid once per shaping change, so raise it
+* deliberately rather than by default.
+*/
+const MAX_RESOLUTION = 256;
 /**
 * Procedural heightfield terrain with biome texture splatting — seeded
 * simplex octaves displace a PlaneGeometry once on the CPU, per-vertex
@@ -982,6 +989,14 @@ var Terrain3D = class extends Node3D {
 	* bed to sit in, and the collider/heightAt/drape all see it. */
 	channels = [];
 	/**
+	* Trenches other NODES cut in this terrain — a `River3D` carving its own bed.
+	* Keyed by the node that owns each, so a moving or re-pathed river replaces
+	* its cut instead of stacking a new one. Runtime state, never serialized:
+	* the scene file says "there is a river here", not "here is the ditch it
+	* dug", and re-loading the scene digs it again.
+	*/
+	externalChannels = /* @__PURE__ */ new Map();
+	/**
 	* WET SAND band: `{ y, band? }` darkens + glosses the splat in a noisy,
 	* breathing band just above height `y` (a waterline) — the trace of the
 	* last swash runup. `band` is the max height above `y` that reads wet
@@ -1061,6 +1076,20 @@ var Terrain3D = class extends Node3D {
 		}
 		return this._heightmap().heightAt(x - ox, z - oz) + oy;
 	}
+	/**
+	* @internal Cut (spec) or release (null) a trench another node owns. A
+	* `River3D` calls this to dig its own bed; the heightmap, the collider,
+	* `heightAt`, the drape and the mesh all pick it up on their next rebuild.
+	*/
+	_setExternalChannel(owner, specs) {
+		if (specs === null || specs.length === 0) this.externalChannels.delete(owner);
+		else this.externalChannels.set(owner, specs);
+	}
+	/** Authored trenches plus the ones other nodes cut. */
+	allChannels() {
+		if (this.externalChannels.size === 0) return this.channels;
+		return [...this.channels, ...[...this.externalChannels.values()].flat()];
+	}
 	/** @internal The pure heightfield (lazily built — physics pulls this). */
 	_heightmap() {
 		const segs = this.segments();
@@ -1074,7 +1103,7 @@ var Terrain3D = class extends Node3D {
 			this.flatThreshold,
 			this.effectiveIslandEdge(),
 			this.basins,
-			this.channels
+			this.allChannels()
 		]);
 		if (!this.heightmap || key !== this.heightmapKey) {
 			this.heightmap = buildHeightmap({
@@ -1089,7 +1118,7 @@ var Terrain3D = class extends Node3D {
 				flatThreshold: this.flatThreshold,
 				islandEdge: this.effectiveIslandEdge(),
 				basins: this.basins,
-				channels: this.channels
+				channels: this.allChannels()
 			});
 			this.heightmapKey = key;
 		}
@@ -1124,7 +1153,8 @@ var Terrain3D = class extends Node3D {
 			this.islandEdge,
 			this.layers,
 			this.textureBase,
-			this.basins
+			this.basins,
+			this.allChannels()
 		]);
 		if (key === this.builtKey) return;
 		this.builtKey = key;
@@ -6430,6 +6460,22 @@ const PROFILE_SMOOTH = 3;
 const SLOPE_GAIN = 4;
 const SPEED_MIN = .05;
 const SPEED_MAX = 12;
+/** Taps per side when reading the cross-section (rim height, wetted edge). */
+const SECTION_TAPS = 14;
+/** How far out a station looks for the bank that holds it, as a multiple of
+* its half-width and of its depth. Wider than the water on purpose: a river
+* running down the middle of a broad channel is held by walls it never
+* touches, and a scan that stopped at the waterline would call that a spill. */
+const SCAN_WIDTHS = 3;
+const SCAN_DEPTHS = 5;
+/** Thinnest water a reach keeps when the ground refuses to hold any (m). */
+const MIN_FILM = .04;
+/** Half-window (stations) the wetted widths are box-smoothed over. */
+const WIDTH_SMOOTH = 2;
+/** How far a station looks sideways for the bank that holds its water. */
+function scanReach(halfWidth, depth) {
+	return Math.max(halfWidth * SCAN_WIDTHS, halfWidth + depth * SCAN_DEPTHS);
+}
 /**
 * Smooth the control path and walk it at even arc-length steps. The step is
 * nudged so the last sample lands exactly on the mouth — an odd short segment
@@ -6549,26 +6595,102 @@ function buildRiverRings(opts) {
 		const s = smoothed[i];
 		profile[i] = i === 0 ? s : Math.min(s, profile[i - 1]);
 	}
+	const fit = opts.fit === true;
+	const levels = new Array(samples.length);
+	const rims = new Array(samples.length);
+	for (let i = 0; i < samples.length; i++) {
+		const s = samples[i];
+		const wanted = profile[i] + opts.depth;
+		if (!fit) {
+			rims[i] = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+			levels[i] = wanted;
+			continue;
+		}
+		const reach = scanReach(halfWidths[i], opts.depth);
+		const px = -s.tz;
+		const pz = s.tx;
+		let rimL = Number.NEGATIVE_INFINITY;
+		let rimR = Number.NEGATIVE_INFINITY;
+		for (let k = 1; k <= SECTION_TAPS; k++) {
+			const d = k / SECTION_TAPS * reach;
+			rimL = Math.max(rimL, opts.bedAt(s.x + px * d, s.z + pz * d));
+			rimR = Math.max(rimR, opts.bedAt(s.x - px * d, s.z - pz * d));
+		}
+		rims[i] = [rimL, rimR];
+		levels[i] = Math.min(wanted, rimL, rimR);
+	}
+	for (let i = 0; i < levels.length; i++) {
+		let v = levels[i];
+		if (fit) v = Math.max(v, bed[i] + MIN_FILM);
+		if (i > 0) v = Math.min(v, levels[i - 1]);
+		const rim = rims[i];
+		v = Math.min(v, Math.max(Math.min(rim[0], rim[1]), bed[i] + MIN_FILM));
+		levels[i] = v;
+	}
+	const wetted = samples.map((s, i) => {
+		const half = halfWidths[i];
+		if (!fit) return [half, half];
+		const reach = scanReach(half, opts.depth);
+		const level = levels[i];
+		const px = -s.tz;
+		const pz = s.tx;
+		const edge = (side) => {
+			for (let k = 1; k <= SECTION_TAPS; k++) {
+				const d = k / SECTION_TAPS * reach;
+				if (opts.bedAt(s.x + px * d * side, s.z + pz * d * side) >= level) return d;
+			}
+			return -half;
+		};
+		return [edge(1), edge(-1)];
+	});
+	const smoothWetted = wetted.map((_, i) => {
+		let l = 0;
+		let r = 0;
+		let n = 0;
+		for (let k = -2; k <= WIDTH_SMOOTH; k++) {
+			const w = wetted[Math.min(Math.max(i + k, 0), wetted.length - 1)];
+			l += Math.abs(w[0]);
+			r += Math.abs(w[1]);
+			n++;
+		}
+		const raw = wetted[i];
+		return [Math.min(l / n, Math.abs(raw[0])), Math.min(r / n, Math.abs(raw[1]))];
+	});
 	const meanHalf = halfWidths.reduce((a, b) => a + b, 0) / halfWidths.length || 1;
 	return samples.map((s, i) => {
-		const surfaceY = profile[i] + opts.depth;
+		const surfaceY = levels[i];
 		const prev = Math.max(0, i - 1);
 		const next = Math.min(samples.length - 1, i + 1);
 		const run = samples[next].along - samples[prev].along;
-		const drop = (profile[prev] + opts.depth - (profile[next] + opts.depth)) / (run || 1);
+		const drop = (levels[prev] - levels[next]) / (run || 1);
 		const slope = Math.max(0, drop);
 		const halfWidth = halfWidths[i];
+		const wet = smoothWetted[i];
 		const speed = Math.min(Math.max(opts.flowSpeed * Math.sqrt(meanHalf / halfWidth) * (1 + SLOPE_GAIN * slope), SPEED_MIN), SPEED_MAX);
+		const rawWet = wetted[i];
 		return {
 			...s,
 			halfWidth,
+			halfLeft: Math.max(wet[0], .05),
+			halfRight: Math.max(wet[1], .05),
+			spillLeft: rawWet[0] < 0,
+			spillRight: rawWet[1] < 0,
 			surfaceY,
 			slope,
 			speed
 		};
 	});
 }
-/** Ribbon mesh for the stations — flat across, draped along, attribute-rich. */
+/**
+* Ribbon mesh for the stations: level across the channel, draped along it, and
+* attribute-rich.
+*
+* Level across ONLY while the ground holds it. Where a bank has fallen away —
+* the outside of a bend, a reach traversing a hillside, the lip above a fall —
+* a level ribbon would hang in the air, so those vertices drop to follow the
+* ground down instead. Water pouring over a lip is a sheet on the rock; it is
+* never a slab of blue floating over the grass.
+*/
 function buildRiverGeometry(rings, opts) {
 	const across = Math.max(1, Math.round(opts.acrossSegments));
 	const perRing = across + 1;
@@ -6582,6 +6704,7 @@ function buildRiverGeometry(rings, opts) {
 	const indices = new Uint32Array(quads * 6);
 	for (let r = 0; r < rings.length; r++) {
 		const ring = rings[r];
+		const columnCap = Math.max(ring.surfaceY - sampleBed(opts, ring.x, ring.z), MIN_FILM);
 		const px = -ring.tz;
 		const pz = ring.tx;
 		const nLen = Math.hypot(ring.slope, 1);
@@ -6590,12 +6713,15 @@ function buildRiverGeometry(rings, opts) {
 		const nz = ring.tz * ring.slope / nLen;
 		for (let c = 0; c <= across; c++) {
 			const t = c / across * 2 - 1;
-			const offset = t * ring.halfWidth * opts.bankOvershoot;
+			const offset = t * (t < 0 ? ring.halfRight : ring.halfLeft) * opts.bankOvershoot;
 			const x = ring.x + px * offset;
 			const z = ring.z + pz * offset;
 			const i = r * perRing + c;
+			const bed = sampleBed(opts, x, z);
+			const cap = (t < 0 ? ring.spillRight : ring.spillLeft) ? columnCap + (MIN_FILM - columnCap) * Math.abs(t) : columnCap;
+			const y = Math.min(ring.surfaceY, bed + cap);
 			positions[i * 3] = x;
-			positions[i * 3 + 1] = ring.surfaceY;
+			positions[i * 3 + 1] = y;
 			positions[i * 3 + 2] = z;
 			normals[i * 3] = nx;
 			normals[i * 3 + 1] = ny;
@@ -6605,7 +6731,7 @@ function buildRiverGeometry(rings, opts) {
 			flow[i * 2] = ring.tx;
 			flow[i * 2 + 1] = ring.tz;
 			river[i * 4] = ring.speed;
-			river[i * 4 + 1] = Math.max(0, ring.surfaceY - sampleBed(opts, x, z));
+			river[i * 4 + 1] = Math.max(0, y - bed);
 			river[i * 4 + 2] = ring.slope;
 			river[i * 4 + 3] = t * opts.bankOvershoot;
 		}
@@ -6689,8 +6815,10 @@ function hitFrom(a, b, t, x, z, capped) {
 	const tl = Math.hypot(tx, tz) || 1;
 	tx /= tl;
 	tz /= tl;
-	const halfWidth = a.halfWidth + (b.halfWidth - a.halfWidth) * t;
-	const across = ((x - cx) * -tz + (z - cz) * tx) / (halfWidth || 1);
+	const signed = (x - cx) * -tz + (z - cz) * tx;
+	const lerp = (u, v) => u + (v - u) * t;
+	const halfWidth = signed < 0 ? lerp(a.halfRight, b.halfRight) : lerp(a.halfLeft, b.halfLeft);
+	const across = signed / (halfWidth || 1);
 	return {
 		inside: !capped && Math.abs(across) <= 1,
 		across,
@@ -6726,7 +6854,7 @@ function detectFalls(rings, opts = {}) {
 			topY: lip.surfaceY,
 			baseY: base.surfaceY,
 			drop,
-			halfWidth: base.halfWidth,
+			halfWidth: (base.halfLeft + base.halfRight) / 2,
 			dirX: base.tx,
 			dirZ: base.tz,
 			speed: base.speed
@@ -6930,6 +7058,15 @@ uniform float uRippleStrength;
 uniform float uFlowRate;
 uniform float uSparkle;
 uniform float uFresnelScale;
+/**
+ * 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).
+ * The water does not flow AROUND them in any simulated sense — it is told
+ * where they are and paints what a current does when it meets one: a bow
+ * cushion upstream, a broken wake downstream, and a bent surface between.
+ */
+uniform int uRockCount;
+uniform vec4 uRocks[8];
 
 varying vec3 vWorldPosition;
 varying vec3 vSurfaceNormal;
@@ -6970,6 +7107,53 @@ void main() {
   float across = vRiver.w;
 
   vec2 dir = normalize(vFlow + vec2(1e-5, 0.0));
+
+  // ── rocks in the current ────────────────────────────────────────────────
+  // Three things happen where a stream meets a boulder, and all three are
+  // read off the same geometry: the flow BENDS around it (a doublet, the
+  // textbook potential flow past a cylinder), it piles into a bow cushion on
+  // the upstream face, and it tears into a broken wake behind. Everything is
+  // in flow space, so a rock in a bend behaves like a rock in a straight.
+  vec2 bend = vec2(0.0);
+  float bow = 0.0;
+  float wake = 0.0;
+  float shed = 0.0;
+  for (int i = 0; i < 8; i++) {
+    if (i >= uRockCount) break;
+    vec4 rock = uRocks[i];
+    float R = max(rock.z, 0.02);
+    vec2 rel = vWorldPosition.xz - rock.xy;
+    float d = length(rel);
+    if (d > R * 6.0) continue;
+    float breaks = rock.w;
+    // flow-space: +s downstream of the rock, t across it
+    float s = dot(rel, dir);
+    float t = dot(rel, vec2(-dir.y, dir.x));
+    // the doublet: strength falls as 1/r², and inside the rock it is capped
+    // so the field never explodes at the centre
+    float rr = max(d, R);
+    // the BEND is not whitewater: even a drowned stone turns the sheen
+    // around itself, so it never fades out with how proud the rock stands
+    bend += (rel / rr) * (R * R / (rr * rr)) * max(breaks, 0.55);
+    // BOW: a cushion of piled water on the upstream face, brightest dead
+    // ahead of the stone and gone by its shoulders
+    float upstream = smoothstep(0.0, -R * 1.1, s);
+    bow += upstream * (1.0 - smoothstep(R * 0.9, R * 2.0, d)) *
+           (1.0 - smoothstep(R * 0.7, R * 1.6, abs(t))) * breaks;
+    // WAKE: a V opening downstream, fading over a few radii
+    float len = R * 5.0;
+    float along = clamp(s / len, 0.0, 1.0);
+    float halfWake = R * (0.5 + 1.3 * along);
+    wake += step(0.0, s) * (1.0 - along) * (1.0 - along) *
+            (1.0 - smoothstep(halfWake * 0.45, halfWake, abs(t))) * breaks;
+    // the SHOULDERS shed water fastest — that is where the white tears off
+    shed += (1.0 - smoothstep(R * 0.8, R * 1.7, d)) *
+            smoothstep(R * 0.35, R * 0.95, abs(t)) * step(-R * 0.6, s) * breaks;
+  }
+  // a bent surface, not a bent texture: rotating the frame the ripple normal
+  // is built in is what makes the sheen sweep around a stone
+  dir = normalize(dir + clamp(bend, vec2(-1.2), vec2(1.2)));
+
   vec3 dir3 = vec3(dir.x, 0.0, dir.y);
   vec3 perp3 = vec3(-dir.y, 0.0, dir.x);
 
@@ -7036,6 +7220,17 @@ void main() {
   float foam = smoothstep(0.74 - 0.45 * drive, 1.02 - 0.24 * drive, streak) * min(drive, 1.0);
   // crest froth: the tops of standing waves in a real rapid always carry white
   foam = max(foam, smoothstep(0.68, 0.96, ripple.x) * smoothstep(0.4, 1.0, rapids) * uFoam * 0.5);
+
+  // rock whitewater: the cushion is a smooth pile (white but soft-edged), the
+  // wake and the shoulders are TORN, so they ride the advected noise and boil
+  // instead of sitting there as a painted decal
+  float boil = 0.5 + 0.5 * sin(uTime * 3.1 + vFlowUv.x * 2.7);
+  float rockFoam = clamp(bow * 1.6, 0.0, 1.0) * (0.62 + 0.38 * boil);
+  rockFoam = max(rockFoam, clamp(wake * 1.5, 0.0, 1.0) * smoothstep(0.24, 0.72, streak) * 1.3);
+  rockFoam = max(rockFoam, clamp(shed * 1.5, 0.0, 1.0) * smoothstep(0.32, 0.8, streak));
+  // a boulder in a millpond barely whitens; the same boulder in a chute tears
+  foam = max(foam, clamp(rockFoam, 0.0, 1.0) * smoothstep(0.15, 0.9, speed) * uFoam);
+
   // froth can never be more present than the water carrying it
   foam = clamp(foam, 0.0, 1.0) * smoothstep(0.02, 0.14, column);
 
@@ -7132,6 +7327,38 @@ const METERS_PER_ACROSS_SEGMENT = 1.5;
 * flow over it, wide enough that terrain grain does not fizz the whole river. */
 const COLUMN_BLUR_PER_HALF_WIDTH = .35;
 const COLUMN_BLUR_MAX = 1.2;
+/**
+* Self-carved bed. The cut is sized off the WATER COLUMN, not off the width:
+* a channel's banks are as steep as its banks are, and a taper scaled to width
+* turns a wide river into a shallow saucer the water floods far past its edge.
+*
+* `depth` is the trench in water columns; `bank` the smoothstep blend beyond
+* the flat bed, also in columns. The waterline crosses that blend at
+* {@link CARVE_WATERLINE_T} of its width (smoothstep(t) = 1 − 1/depth), which
+* is what lets the floor be narrowed so the WATER ends up the authored width.
+*/
+const CARVE_DEPTH = 2.2;
+const CARVE_BANK = 2;
+const CARVE_WATERLINE_T = .52;
+/** Never cut the floor away entirely, however steep the bank works out. */
+const CARVE_FLOOR_MIN = .3;
+/** A trench thinner than this many terrain cells cannot survive the grid it is
+* sampled on — it smooths away to nothing and the creek is back on raw ground.
+* Widening it is the honest failure: better a bed too wide than no bed. */
+const CARVE_MIN_CELLS = 1.5;
+/** Deepest the bed may be cut, in water columns — the budget for digging
+* THROUGH a rise so the water keeps flowing, before it would read as a canyon. */
+const CARVE_MAX_DEPTH = 7;
+/** The fall the carved floor keeps even where the ground does not (m per m). */
+const CARVE_MIN_GRADE = .004;
+/** Rocks the shader can carry at once (the nearest ones win). */
+const ROCK_SLOTS = 8;
+/** How often the tree is re-scanned for things standing in the water (s). */
+const ROCK_RESCAN = .5;
+/** A rock stops mattering past this many of its own radii from the camera —
+* never sooner than ROCK_FADE_MIN, or a pebble would blink out at arm's reach. */
+const ROCK_FADE_RADII = 42;
+const ROCK_FADE_MIN = 26;
 /** How hard the current drags a body toward the water's own velocity (1/s at
 * `flowForce: 1`). Drag, not thrust: nothing ever outruns the river. Tuned
 * against CharacterController3D, whose stand-still damping fights it — at this
@@ -7150,6 +7377,8 @@ const DEFAULT_COLORS = {
 	bank: "#465447"
 };
 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. */
 const LOOK = {
 	/** Pattern units per meter of flow space. */
@@ -7205,6 +7434,7 @@ var River3D = class River3D extends Node3D {
 		sunColor: { default: "#fff6e0" },
 		sunIntensity: { default: 1 },
 		terrain: { default: "" },
+		carve: { default: true },
 		flowForce: { default: 1 },
 		spray: { default: 1 }
 	};
@@ -7240,6 +7470,18 @@ var River3D = class River3D extends Node3D {
 	sunIntensity = 1;
 	/** Drape target path; empty = auto-find the first Terrain3D in the tree. */
 	terrain = "";
+	/**
+	* Cut the bed. Real water arrives on a hillside and erodes itself a channel;
+	* a ribbon laid on raw ground has nothing holding it and reads as a strip of
+	* blue hovering over the grass. With this on, the river trenches its own
+	* course into the terrain it drapes on — banks the player can walk into, a
+	* collider and `heightAt` that agree with it, and splat that paints the cut.
+	*
+	* Off means you carve it yourself with `Terrain3D.channels` (or the reach is
+	* genuinely a flat flood plain). Either way the surface is FITTED to
+	* whatever ground it finds: it can never stand above its own banks.
+	*/
+	carve = true;
 	/** How hard the current sweeps bodies downstream (0 = visual only). */
 	flowForce = 1;
 	/**
@@ -7255,6 +7497,11 @@ var River3D = class River3D extends Node3D {
 	sprayKey = "";
 	courseKey = "";
 	bedAt = null;
+	/** Whether the last course was fitted to real ground (see buildRiverRings). */
+	fitted = false;
+	/** Everything standing in the current, rescanned on a slow timer. */
+	rocks = [];
+	rockScanAt = -1;
 	world = [
 		0,
 		0,
@@ -7295,6 +7542,12 @@ var River3D = class River3D extends Node3D {
 	_createObject3D() {
 		return new Mesh(new BufferGeometry(), this.buildMaterial());
 	}
+	onReady() {
+		this.ensureCourse();
+	}
+	onExitTree() {
+		findDrapeTerrain(this, this.terrain)?._setExternalChannel(this, null);
+	}
 	update(dt) {
 		this.time += dt;
 		this.ensureCourse();
@@ -7307,6 +7560,16 @@ var River3D = class River3D extends Node3D {
 		this.rebuildIfNeeded(mesh);
 		this.syncUniforms(mesh);
 	}
+	/** Rocks are picked per FRAME (nearest to the eye), scanned on a timer. */
+	_onRender3D(ctx) {
+		if (this.rings.length === 0) return;
+		if (this.rockScanAt < 0 || this.time - this.rockScanAt > ROCK_RESCAN) {
+			this.rockScanAt = this.time;
+			this.scanRocks();
+		}
+		const u = this._ensureObject3D().material.uniforms;
+		this.syncRocks(u, ctx.camera.getWorldPosition(rockCamScratch));
+	}
 	/**
 	* Where a WORLD point sits in the channel — the query gameplay scripts run
 	* (steer a raft, drown a torch, decide a ford is too fast to cross). `null`
@@ -7359,6 +7622,63 @@ var River3D = class River3D extends Node3D {
 	widthProfile() {
 		return this.widths.length > 0 ? this.widths : [this.width];
 	}
+	/**
+	* Cut (or release) this river's trench in the terrain it drapes on.
+	*
+	* Runs at ready as well as on every course rebuild: the heightfield collider
+	* is built before the first render sync, so a bed cut only at draw time
+	* would leave the player walking on ground that is no longer there.
+	*/
+	applyCarve(terrain) {
+		if (!terrain) return;
+		if (!this.carve || this.path.length < 2) {
+			terrain._setExternalChannel(this, null);
+			return;
+		}
+		terrain._setExternalChannel(this, null);
+		const [wx, , wz] = worldXZY(this);
+		const [tx, , tz] = worldXZY(terrain);
+		const widths = this.widthProfile();
+		const hm = terrain._heightmap();
+		const cell = (terrain.size[0] ?? 1) / Math.max(1, hm.segsX);
+		const line = resamplePath(this.path.map((p) => [(p[0] ?? 0) + wx - tx, (p[1] ?? 0) + wz - tz]), Math.max(cell, this.depth));
+		if (line.length < 2) {
+			terrain._setExternalChannel(this, null);
+			return;
+		}
+		const total = line[line.length - 1].along || 1;
+		const ground = line.map((s) => terrain._heightmap().heightAt(s.x, s.z));
+		const baseCut = this.depth * CARVE_DEPTH;
+		const maxCut = this.depth * CARVE_MAX_DEPTH;
+		const floor = new Array(line.length);
+		for (let i = 0; i < line.length; i++) {
+			const wanted = ground[i] - baseCut;
+			if (i === 0) {
+				floor[i] = wanted;
+				continue;
+			}
+			const run = line[i].along - line[i - 1].along;
+			const carried = floor[i - 1] - run * CARVE_MIN_GRADE;
+			floor[i] = Math.max(Math.min(wanted, carried), ground[i] - maxCut);
+		}
+		const specs = [];
+		for (let i = 1; i < line.length; i++) {
+			const a = line[i - 1];
+			const b = line[i];
+			const cut = Math.max((ground[i - 1] + ground[i]) / 2 - (floor[i - 1] + floor[i]) / 2, 0);
+			if (cut <= .001) continue;
+			const half = widthAlong(widths, a.along / total) / 2;
+			const bank = Math.max(this.depth * CARVE_BANK, cell * CARVE_MIN_CELLS);
+			const floorHalf = Math.max(half - bank * CARVE_WATERLINE_T, half * CARVE_FLOOR_MIN, cell * .5);
+			specs.push({
+				path: [[a.x, a.z], [b.x, b.z]],
+				width: floorHalf * 2,
+				depth: cut,
+				taper: bank
+			});
+		}
+		terrain._setExternalChannel(this, specs);
+	}
 	/** Resolve the drape terrain; an explicit path that misses is a hard error. */
 	resolveTerrain() {
 		const terrain = findDrapeTerrain(this, this.terrain);
@@ -7378,6 +7698,7 @@ var River3D = class River3D extends Node3D {
 			this.widths,
 			this.depth,
 			this.flowSpeed,
+			this.carve,
 			terrain ? terrain.name : "",
 			world
 		]);
@@ -7385,6 +7706,7 @@ var River3D = class River3D extends Node3D {
 		this.courseKey = key;
 		this.world = world;
 		this.bedAt = null;
+		this.applyCarve(terrain);
 		if (this.path.length < 2) {
 			this.rings = [];
 			this.falls = [];
@@ -7392,6 +7714,7 @@ var River3D = class River3D extends Node3D {
 		}
 		const [wx, wy, wz] = world;
 		this.bedAt = terrain ? (lx, lz) => terrain.heightAt(lx + wx, lz + wz) - wy : () => -this.depth;
+		this.fitted = terrain !== null;
 		const widths = this.widthProfile();
 		const narrow = Math.min(...widths);
 		this.rings = buildRiverRings({
@@ -7400,7 +7723,8 @@ var River3D = class River3D extends Node3D {
 			depth: this.depth,
 			flowSpeed: this.flowSpeed,
 			step: Math.min(Math.max(narrow * STEP_PER_WIDTH, STEP_MIN), STEP_MAX),
-			bedAt: this.bedAt
+			bedAt: this.bedAt,
+			fit: this.fitted
 		});
 		this.falls = detectFalls(this.rings);
 		return true;
@@ -7419,7 +7743,7 @@ var River3D = class River3D extends Node3D {
 		const wide = Math.max(...widths);
 		const data = buildRiverGeometry(this.rings, {
 			acrossSegments: Math.min(ACROSS_MAX, Math.max(ACROSS_MIN, Math.round(wide / METERS_PER_ACROSS_SEGMENT))),
-			bankOvershoot: BANK_OVERSHOOT,
+			bankOvershoot: this.fitted ? 1 : BANK_OVERSHOOT,
 			bedBlur: Math.min(narrow / 2 * COLUMN_BLUR_PER_HALF_WIDTH, COLUMN_BLUR_MAX),
 			bedAt: this.bedAt
 		});
@@ -7462,6 +7786,8 @@ var River3D = class River3D extends Node3D {
 				uRippleStrength: { value: LOOK.rippleStrength * this.ripples },
 				uFlowRate: { value: LOOK.flowRate },
 				uSparkle: { value: this.ripples },
+				uRockCount: { value: 0 },
+				uRocks: { value: Array.from({ length: ROCK_SLOTS }, () => new Vector4()) },
 				uFresnelScale: { value: LOOK.fresnelScale },
 				uStandingAmp: { value: LOOK.standingAmp },
 				uGlideAmp: { value: LOOK.glideAmp }
@@ -7472,6 +7798,88 @@ var River3D = class River3D extends Node3D {
 			side: DoubleSide
 		});
 	}
+	/**
+	* Find everything standing in the current.
+	*
+	* A boulder in a creek is not a physics problem — it is a thing the water
+	* has to be TOLD about, or the stream runs through it as if it were painted
+	* on. Any mesh whose footprint lands inside the wetted channel and whose top
+	* reaches near the surface counts, `InstancedMesh3D` rows included (a rock
+	* scatter is one node with fifty stones in it).
+	*
+	* Scanned on a slow timer rather than per frame: rocks do not move often,
+	* and a river with a hundred of them still writes only the nearest few.
+	*/
+	scanRocks() {
+		const found = [];
+		const [wx, wy, wz] = this.world;
+		/** Keep a candidate if it actually stands IN the water column. */
+		const consider = (x, z, radius, bottom, top) => {
+			if (radius <= .02) return;
+			const hit = projectToRiver(this.rings, x - wx, z - wz);
+			if (!hit || !hit.inside) return;
+			const surface = hit.surfaceY + wy;
+			if (bottom > surface) return;
+			const bed = surface - this.depth;
+			if (top < bed) return;
+			const breaks = Math.min(Math.max((top - bed) / Math.max(this.depth, .05), .2), 1);
+			found.push({
+				x,
+				z,
+				radius,
+				breaks
+			});
+		};
+		let root = this;
+		while (root.parent) root = root.parent;
+		const walk = (node) => {
+			if (node instanceof InstancedMesh3D) {
+				const [sx, sy, sz] = node.size;
+				const [ox, oy, oz] = worldXZY(node);
+				for (const row of node.transforms) {
+					const scale = row[4] ?? 1;
+					const x = ox + (row[0] ?? 0);
+					const y = oy + (row[1] ?? 0);
+					const z = oz + (row[2] ?? 0);
+					const half = (sy ?? 1) * scale / 2;
+					consider(x, z, Math.max(sx, sz) * scale / 2, y - half, y + half);
+				}
+			} else if (node instanceof MeshInstance3D) {
+				const [sx, sy, sz] = node.size;
+				const [x, y, z] = worldXZY(node);
+				const half = (sy ?? 1) / 2;
+				consider(x, z, Math.max(sx, sz) / 2, y - half, y + half);
+			}
+			for (const child of node.children) walk(child);
+		};
+		walk(root);
+		this.rocks = found;
+	}
+	/** Write the nearest rocks into the shader, faded in by distance. */
+	syncRocks(u, camera) {
+		const slots = u.uRocks?.value;
+		const count = u.uRockCount;
+		if (!slots || !count) return;
+		if (this.rocks.length === 0) {
+			count.value = 0;
+			return;
+		}
+		const near = [...this.rocks].map((r) => ({
+			r,
+			d: (r.x - camera.x) ** 2 + (r.z - camera.z) ** 2
+		})).sort((a, b) => a.d - b.d).slice(0, ROCK_SLOTS);
+		let n = 0;
+		for (const { r, d } of near) {
+			const far = Math.max(r.radius * ROCK_FADE_RADII, ROCK_FADE_MIN);
+			const t = Math.min(Math.sqrt(d) / far, 1);
+			const k = Math.min(Math.max((t - .6) / .4, 0), 1);
+			const fade = 1 - k * k * (3 - 2 * k);
+			if (fade <= .01) continue;
+			slots[n]?.set(r.x, r.z, r.radius, r.breaks * fade);
+			n++;
+		}
+		count.value = n;
+	}
 	syncUniforms(mesh) {
 		const u = mesh.material.uniforms;
 		const set = (key, value) => {

package/dist/test.js

@@ -6,7 +6,7 @@ import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
 import { i as getNodeSchema, s as mergeStaticProps } from "./registry-BVJ2HbCn.js";
 import { n as registerGameplayBehaviors } from "./gameplay-Ddk13pQ6.js";
 import { t as registerNodes2D } from "./register-CvpSUU3O.js";
-import { t as registerNodes3D } from "./register-CeWtdiCw.js";
+import { t as registerNodes3D } from "./register-DcHXS1MA.js";
 import { t as registerNodesNet } from "./register-BFFE1Mh1.js";
 //#region src/test/index.ts
 /**
@@ -127,7 +127,7 @@ async function runScript(json, opts) {
 		const { enablePhysics2D } = await import("./physics-2d-DiVFFlH3.js").then((n) => n.r);
 		await enablePhysics2D(engine);
 	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
-		const { enablePhysics3D } = await import("./physics-3d-Cd7Jl8w1.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-4mGzOZ2J.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const failures = [];
@@ -232,7 +232,7 @@ async function createPlaySession(json, opts = {}) {
 		const { enablePhysics2D } = await import("./physics-2d-DiVFFlH3.js").then((n) => n.r);
 		await enablePhysics2D(engine);
 	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
-		const { enablePhysics3D } = await import("./physics-3d-Cd7Jl8w1.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-4mGzOZ2J.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const stepMs = 1e3 / (opts.fixedHz ?? 60);