incanto 0.26.0 → 0.27.0

package/dist/3d.d.ts

@@ -1590,7 +1590,18 @@ interface PathSample {
 }
 /** A cross-section station: where the water is, how wide, how fast. */
 interface RiverRing extends PathSample {
+  /** The width the author ASKED for (half of it) — nominal, drives current. */
   halfWidth: number;
+  /** Wetted half-width to the left of the flow: where the ground rises to the
+  * surface. This, not {@link halfWidth}, is where the water actually ends. */
+  halfLeft: number;
+  /** Wetted half-width to the right of the flow. */
+  halfRight: number;
+  /** No bank on that side: the ground never came up to the surface, so the
+  * water is spilling out over it rather than being held. The ribbon thins to
+  * a film there instead of ending in a wall of water standing on nothing. */
+  spillLeft: boolean;
+  spillRight: boolean;
   /** Water surface height (local Y). */
   surfaceY: number;
   /** Downhill grade of the surface (dimensionless, ≥ 0). */
@@ -1706,6 +1717,18 @@ declare class River3D extends Node3D implements SunConsumer3D {
   sunIntensity: number;
   /** Drape target path; empty = auto-find the first Terrain3D in the tree. */
   terrain: string;
+  /**
+  * 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: boolean;
   /** How hard the current sweeps bodies downstream (0 = visual only). */
   flowForce: number;
   /**
@@ -1721,13 +1744,22 @@ declare class River3D extends Node3D implements SunConsumer3D {
   private sprayKey;
   private courseKey;
   private bedAt;
+  /** Whether the last course was fitted to real ground (see buildRiverRings). */
+  private fitted;
+  /** Everything standing in the current, rescanned on a slow timer. */
+  private rocks;
+  private rockScanAt;
   private world;
   private readonly _bodies;
   /** Loader hook: a malformed river fails at LOAD, not as an invisible ribbon. */
   static validateJson(node: Node): void;
   protected override _createObject3D(): Object3D;
+  override onReady(): void;
+  override onExitTree(): void;
   override update(dt: number): void;
   override _syncObject3D(): void;
+  /** Rocks are picked per FRAME (nearest to the eye), scanned on a timer. */
+  _onRender3D(ctx: RenderContext3D): void;
   /**
   * 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`
@@ -1755,6 +1787,14 @@ declare class River3D extends Node3D implements SunConsumer3D {
   _applySunDirection(dir: readonly [number, number, number]): void;
   override free(): void;
   private widthProfile;
+  /**
+  * 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.
+  */
+  private applyCarve;
   /** Resolve the drape terrain; an explicit path that misses is a hard error. */
   private resolveTerrain;
   /**
@@ -1764,6 +1804,21 @@ declare class River3D extends Node3D implements SunConsumer3D {
   private ensureCourse;
   private rebuildIfNeeded;
   private buildMaterial;
+  /**
+  * 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.
+  */
+  private scanRocks;
+  /** Write the nearest rocks into the shader, faded in by distance. */
+  private syncRocks;
   private syncUniforms;
   /**
   * Hang a mist plume on every fall. Runtime children (`__spray*`), rebuilt
@@ -1965,6 +2020,14 @@ declare class Terrain3D extends Node3D {
   * bed to sit in, and the collider/heightAt/drape all see it. */
   channels: ChannelSpec[];
   /**
+  * 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.
+  */
+  private readonly externalChannels;
+  /**
   * 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
@@ -1989,6 +2052,14 @@ declare class Terrain3D extends Node3D {
   * physics bodies follow).
   */
   heightAt(x: number, z: number): number;
+  /**
+  * @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: Node, specs: ChannelSpec[] | null): void;
+  /** Authored trenches plus the ones other nodes cut. */
+  private allChannels;
   /** @internal The pure heightfield (lazily built — physics pulls this). */
   _heightmap(): Heightmap;
   /** The splat layers in effect — theme preset, or `layers` for 'custom'. */

package/dist/3d.js

@@ -1,9 +1,9 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-Ddk13pQ6.js";
-import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-B_qBR65J.js";
-import { A as QUARTER_PITCH, C as BoneAttachment3D, D as TERRAIN_THEMES, E as DEFAULT_TERRAIN_TEXTURE_BASE, M as keyboardIntensity, N as movementState, O as terrainThemeLayers, P as rigPose, S as BoneLookAt3D, T as Terrain3D, _ as Flowers3D, a as Trail3D, b as CharacterController3D, c as Particles3D, d as DirectionalLight3D, f as OmniLight3D, g as DENSITY_PRESETS, h as Foliage3D, i as Tree3D, j as cameraRelative, k as Joint3D, l as ModelInstance3D, m as MeshInstance3D, n as VOXEL_PALETTE, o as River3D, p as InstancedMesh3D, r as VoxelGrid3D, s as traceDownhillPath, t as registerNodes3D, u as LoftMesh3D, v as resolveFlowerDensity, w as Billboard3D, x as Camera3D, y as FLOWER_VARIETIES } from "./register-CeWtdiCw.js";
+import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-DUAtTqID.js";
+import { A as QUARTER_PITCH, C as BoneAttachment3D, D as TERRAIN_THEMES, E as DEFAULT_TERRAIN_TEXTURE_BASE, M as keyboardIntensity, N as movementState, O as terrainThemeLayers, P as rigPose, S as BoneLookAt3D, T as Terrain3D, _ as Flowers3D, a as Trail3D, b as CharacterController3D, c as Particles3D, d as DirectionalLight3D, f as OmniLight3D, g as DENSITY_PRESETS, h as Foliage3D, i as Tree3D, j as cameraRelative, k as Joint3D, l as ModelInstance3D, m as MeshInstance3D, n as VOXEL_PALETTE, o as River3D, p as InstancedMesh3D, r as VoxelGrid3D, s as traceDownhillPath, t as registerNodes3D, u as LoftMesh3D, v as resolveFlowerDensity, w as Billboard3D, x as Camera3D, y as FLOWER_VARIETIES } from "./register-DcHXS1MA.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-Cd7Jl8w1.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-4mGzOZ2J.js";
 //#region src/3d/environment-runtime.ts
 /**
 * Live environment editing — the renderer re-applies `scene.environment`

package/dist/{create-game-B_qBR65J.js → create-game-DUAtTqID.js}

@@ -5,8 +5,8 @@ import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
 import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-Ddk13pQ6.js";
 import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
-import { d as DirectionalLight3D, l as ModelInstance3D, t as registerNodes3D, x as Camera3D } from "./register-CeWtdiCw.js";
-import { n as enablePhysics3D } from "./physics-3d-Cd7Jl8w1.js";
+import { d as DirectionalLight3D, l as ModelInstance3D, t as registerNodes3D, x as Camera3D } from "./register-DcHXS1MA.js";
+import { n as enablePhysics3D } from "./physics-3d-4mGzOZ2J.js";
 import { ACESFilmicToneMapping, AmbientLight, Box3, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, HalfFloatType, LineBasicMaterial, LineSegments, Matrix4, Mesh, PCFShadowMap, PMREMGenerator, PerspectiveCamera, PlaneGeometry, Quaternion, Raycaster, Scene, ShaderMaterial, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
 import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";

package/dist/env.d.ts

@@ -376,6 +376,12 @@ interface TerrainOptions {
   * theme ALWAYS ships its sea — without it the edge-wrap skirt is bare cliff.
   */
   water?: boolean;
+  /**
+  * Grid segments per side (default 128). Raise it when the map carries
+  * features finer than a cell — a 2 m creek on a 260 m terrain has to be cut
+  * into ~1 m cells (256) or the trench smooths away to nothing.
+  */
+  resolution?: number;
 }
 /**
 * The environment header that matches a generator theme — sky, horizon fog

package/dist/env.js

@@ -1419,7 +1419,7 @@ const TERRAIN_GENERATOR_THEMES = [
 	"volcanic"
 ];
 /** Terrain3D's default grid segments — the probe MUST match the runtime grid. */
-const TERRAIN_RESOLUTION = 128;
+const DEFAULT_TERRAIN_RESOLUTION = 128;
 /** Terrain3D edge wrap: the rim drops this many meters before the −50 m skirt. */
 const EDGE_WRAP_DROP = 20;
 /** Sea margin above the highest rim cliff (> the ~0.52 m wave-trough dip). */
@@ -1676,6 +1676,7 @@ function generateTerrain(opts) {
 		prop: "theme",
 		validOptions: [...TERRAIN_GENERATOR_THEMES]
 	});
+	const TERRAIN_RESOLUTION = Math.max(2, Math.round(opts.resolution ?? DEFAULT_TERRAIN_RESOLUTION));
 	let maxHeight = opts.maxHeight || spec.maxHeight;
 	const rng = new Rng(seed);
 	const isIsland = theme === "island";
@@ -1714,7 +1715,8 @@ function generateTerrain(opts) {
 				seed,
 				theme: spec.splat,
 				...spec.roughness !== void 0 ? { roughness: spec.roughness } : {},
-				...spec.detail !== void 0 ? { detail: spec.detail } : {}
+				...spec.detail !== void 0 ? { detail: spec.detail } : {},
+				...TERRAIN_RESOLUTION !== DEFAULT_TERRAIN_RESOLUTION ? { resolution: TERRAIN_RESOLUTION } : {}
 			}
 		}]
 	}];
@@ -1799,9 +1801,10 @@ function borderMaxHeight(hm) {
 	let borderMax = Number.NEGATIVE_INFINITY;
 	const hw = hm.width / 2;
 	const hd = hm.depth / 2;
-	for (let i = 0; i <= TERRAIN_RESOLUTION; i++) {
-		const x = -hw + i / TERRAIN_RESOLUTION * hm.width;
-		const z = -hd + i / TERRAIN_RESOLUTION * hm.depth;
+	const steps = hm.segsX;
+	for (let i = 0; i <= steps; i++) {
+		const x = -hw + i / steps * hm.width;
+		const z = -hd + i / steps * hm.depth;
 		borderMax = Math.max(borderMax, hm.baseHeight(x, -hd), hm.baseHeight(x, hd), hm.baseHeight(-hw, z), hm.baseHeight(hw, z));
 	}
 	return borderMax;

package/dist/index.js

@@ -295,6 +295,6 @@ function newUid() {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.26.0";
+const VERSION = "0.27.0";
 //#endregion
 export { AudioBuses, AudioPlayer, Behavior, CONST_REF_KEY, Engine, HudLayer, IncantoError, InputMap, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, Scene, SceneTree, SfxEngine, Signal, Timer, TouchControls, UiBanner, UiBar, UiButton, UiDialogue, UiText, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, startRecording, synthSfx };

package/dist/{physics-3d-Cd7Jl8w1.js → physics-3d-4mGzOZ2J.js}

@@ -2,7 +2,7 @@ import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { F as PhysicsBody3D, I as RigidBody3D, N as Area3D, P as CharacterBody3D, R as Node3D, z as validateCollider3D } from "./gameplay-Ddk13pQ6.js";
 import { n as registerDebugSource } from "./debug-draw-CZmOYjL2.js";
-import { T as Terrain3D, k as Joint3D } from "./register-CeWtdiCw.js";
+import { T as Terrain3D, k as Joint3D } from "./register-DcHXS1MA.js";
 import { Euler, Quaternion } from "three";
 //#region src/3d/physics/physics-3d.ts
 var physics_3d_exports = /* @__PURE__ */ __exportAll({

package/dist/react.js

@@ -156,7 +156,7 @@ function IncantoCanvas(props) {
 				pointer: latest.pointer,
 				...keyboard !== void 0 ? { keyboard } : {}
 			};
-			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-B_qBR65J.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-C0bPoURs.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-DUAtTqID.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-C0bPoURs.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;