incanto 0.25.4 → 0.27.0

package/dist/2d.js

@@ -1,5 +1,5 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-iYptFr-q.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-C0bPoURs.js";
 import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-CvpSUU3O.js";
 import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-DiVFFlH3.js";
 //#region src/2d/library-sprite.ts

package/dist/3d.d.ts

@@ -3,7 +3,7 @@ import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as Pro
 import { t as LoadSceneOptions } from "./loader-DILt9PGC.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
 import { n as PathGrid, s as SpatialPose } from "./pathfinding-RWYkNKx9.js";
-import { AnimationClip, BufferGeometry, Color, DirectionalLight, InstancedMesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from "three";
+import { AnimationClip, BufferGeometry, Color, DirectionalLight, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
 import * as RapierNs from "@dimforge/rapier3d-compat";
@@ -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'. */
@@ -2387,6 +2458,10 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   private readonly _scratchA;
   private readonly _scratchB;
   private readonly _bodies;
+  private readonly _cutouts;
+  /** Scratch for the cutout mask pass (no per-frame allocation). */
+  private readonly _maskMeshes;
+  private readonly _maskSaved;
   /** Scratch for the side-pass cull (no per-frame allocation). */
   private readonly _passHidden;
   private cubeTarget;
@@ -2428,6 +2503,16 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   /** The cheap lake ShaderMaterial — fresnel sky tint + ripple normals + sun
   * glint + edge fade, NO scene re-renders (see lake.ts). */
   private buildLakeMaterial;
+  /**
+  * Stamp every {@link WaterCutout3D} owner into the depth pre-pass.
+  *
+  * The cutout does not describe a hole in the water — it names a piece of
+  * geometry that holds the water back, and this pass re-draws exactly that
+  * geometry (clipped to the cutout box) at the near plane. The water's
+  * occlusion discard does the rest. The tree is walked live, so a cutout on a
+  * bobbing hull tracks it with no wiring.
+  */
+  private renderCutoutMasks;
   private syncFancy;
   /**
   * @internal Environment-sky sun hand-off (see {@link SunConsumer3D}): the
@@ -2454,6 +2539,59 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   private waveOffsetAt;
 }
 //#endregion
+//#region src/3d/nodes/water-cutout-3d.d.ts
+/**
+* A box the water does not enter.
+*
+* Water is ONE surface: it has no idea a boat has an inside. Float an open hull
+* and every wave crest that rises above its floor renders as sea sloshing
+* through the deck — correct for a plane cutting an open box, wrong for a boat.
+* Freeboard alone cannot fix it (a big enough swell always wins), so the fix is
+* to name the geometry that holds the water back. `Water3D` re-draws that
+* geometry — the part of it inside this box — into its depth pre-pass at the
+* near plane, and its ordinary occlusion discard then removes the water for
+* exactly the pixels the hull already covers.
+*
+* Park it as a CHILD of the thing it belongs to — a hull, a diving bell, a
+* dock's well, a cave mouth — and it follows along, rotation included.
+*
+* SAFE BY CONSTRUCTION: nothing is ever cut out of the water. The mask is the
+* owner's own silhouette, so water can only be hidden behind geometry the
+* player is already looking at. Size the box to the interior and err large —
+* an overlarge box just means more of this hull holds water back; it can never
+* punch a rectangle of bare ground into open water. (Needs the depth pre-pass:
+* `Water3D` in `fancy` quality. Skinned and instanced meshes are re-drawn at
+* their rest pose, so hang cutouts on ordinary geometry.)
+*
+* ```json
+* { "name": "Rowboat", "type": "RigidBody3D", "children": [
+*   { "name": "DryInside", "type": "WaterCutout3D",
+*     "props": { "size": [3.0, 1.2, 1.1], "position": [0, 0.4, 0] } } ] }
+* ```
+*
+* Cheap: a handful of these cost a few ALU per water pixel. `Water3D` reads the
+* nearest {@link WATER_CUTOUT_MAX} of them.
+*/
+declare class WaterCutout3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** Box extent in meters, centered on the node ([x, y, z]). */
+  size: number[];
+  /** Live toggle — a scuttled hull can start letting the sea in. */
+  enabled: boolean;
+  static validateJson(node: Node): void;
+  /**
+  * A cutout works by re-drawing its PARENT, so it has to have one. At the
+  * scene root it would hand the whole world a licence to erase water — the
+  * one failure this design exists to rule out — so that arrangement is a hard
+  * load error, not a silent no-op. (Checked here rather than in
+  * `validateJson`: the loader validates a node before attaching it.)
+  */
+  override onReady(): void;
+}
+/** How many cutouts one Water3D reads (the nearest ones win). */
+declare const WATER_CUTOUT_MAX = 4;
+//#endregion
 //#region src/3d/register.d.ts
 /**
 * Register the 3D node taxonomy (and the core nodes). Call once in your game
@@ -2761,4 +2899,4 @@ declare function createNavDebugNode(nav: TerrainNav, opts?: {
   name?: string;
 }): InstancedMesh3D;
 //#endregion
-export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type Game3D, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, River3D, type RiverHit, type RiverRing, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, setEnvironment3D, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type Game3D, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, River3D, type RiverHit, type RiverRing, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, setEnvironment3D, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };

package/dist/3d.js

@@ -1,9 +1,9 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { A as Water3D, F as StaticBody3D, I as Node3D, M as CharacterBody3D, N as PhysicsBody3D, P as RigidBody3D, j as Area3D, z as WATER_MAX_RIPPLES } from "./gameplay-BFzBVqhr.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-DyAPwm0j.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-CmtGqGSS.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-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-ob23XE0Y.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`
@@ -142,4 +142,4 @@ function createNavDebugNode(nav, opts) {
 	return node;
 }
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, StaticBody3D, TERRAIN_THEMES, Terrain3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, setEnvironment3D, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, StaticBody3D, TERRAIN_THEMES, Terrain3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, setEnvironment3D, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };

package/dist/{create-game-iYptFr-q.js → create-game-C0bPoURs.js}

@@ -3,7 +3,7 @@ import { _ as registerBehavior, n as loadScene, o as computeViewport, s as resol
 import { l as AudioPlayer, u as Engine } from "./register-nObreUQR.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
-import { n as registerGameplayBehaviors } from "./gameplay-BFzBVqhr.js";
+import { n as registerGameplayBehaviors } from "./gameplay-Ddk13pQ6.js";
 import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-CvpSUU3O.js";
 import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
 import { n as enablePhysics2D } from "./physics-2d-DiVFFlH3.js";

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

@@ -3,10 +3,10 @@ import { _ as registerBehavior, n as loadScene } from "./loader-BZqOKfI2.js";
 import { l as AudioPlayer, u as Engine } from "./register-nObreUQR.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
-import { I as Node3D, N as PhysicsBody3D, R as createCausticsQuad, n as registerGameplayBehaviors } from "./gameplay-BFzBVqhr.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-CmtGqGSS.js";
-import { n as enablePhysics3D } from "./physics-3d-ob23XE0Y.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/{gameplay-BFzBVqhr.js → gameplay-Ddk13pQ6.js}

@@ -2,7 +2,7 @@ import { _ as registerBehavior, f as Node, m as Behavior, n as loadScene } from
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as jsonClone } from "./json-BLk7H2Qa.js";
 import { r as effectiveOrder, t as duplicateNode } from "./duplicate-BgtFrFo4.js";
-import { Color, CubeCamera, DepthTexture, DoubleSide, FloatType, Frustum, HalfFloatType, LinearMipmapLinearFilter, MathUtils, Matrix4, Mesh, MeshDepthMaterial, Object3D, PerspectiveCamera, Plane, PlaneGeometry, Quaternion, ShaderMaterial, Sphere, Vector2, Vector3, Vector4, WebGLCubeRenderTarget, WebGLRenderTarget } from "three";
+import { Color, CubeCamera, DepthTexture, DoubleSide, Euler, FloatType, Frustum, HalfFloatType, LinearMipmapLinearFilter, MathUtils, Matrix4, Mesh, MeshDepthMaterial, Object3D, PerspectiveCamera, Plane, PlaneGeometry, Quaternion, ShaderMaterial, Sphere, Vector2, Vector3, Vector4, WebGLCubeRenderTarget, WebGLRenderTarget } from "three";
 //#region src/3d/frustum.ts
 const scratchFrustum = new Frustum();
 const scratchMatrix = new Matrix4();
@@ -1022,6 +1022,12 @@ uniform float uReflectivityMax;
 // Both cures are the same: filter the depth over its own texel footprint and
 // estimate gradients from those taps instead of from fwidth().
 uniform vec2 uScenePassTexel;
+// incanto CUTOUTS (a boat's inside, a diving bell, a well under a dock) are
+// NOT a fragment test — nothing here knows about them. A cutout stamps its
+// OWNER'S OWN geometry into the depth pre-pass at the near plane, so the
+// occlusion discard below removes the water for exactly the pixels that owner
+// already covers. That is what makes a hole in open sea impossible: this
+// shader can only ever hide water behind something the player is looking at.
 /** Shoreline dissolve width, in DEPTH TEXELS (≈2 screen px each). */
 const float SHORE_FADE_TEXELS = 11.0;
 /** Deepest water that can still be a shoreline (m) — past this the fade is off. */
@@ -1399,6 +1405,7 @@ void main() {
       depthMask = 1.0 - smoothstep(softDiscardStart, softDiscardEnd, depthDiff);
       // At border: 0 (fully transparent) ~ 1 (fully opaque)
     }
+
   }
 
   // Calculate vector from camera to the vertex
@@ -2388,6 +2395,75 @@ var CharacterBody3D = class extends PhysicsBody3D {
 	}
 };
 //#endregion
+//#region src/3d/nodes/water-cutout-3d.ts
+/**
+* A box the water does not enter.
+*
+* Water is ONE surface: it has no idea a boat has an inside. Float an open hull
+* and every wave crest that rises above its floor renders as sea sloshing
+* through the deck — correct for a plane cutting an open box, wrong for a boat.
+* Freeboard alone cannot fix it (a big enough swell always wins), so the fix is
+* to name the geometry that holds the water back. `Water3D` re-draws that
+* geometry — the part of it inside this box — into its depth pre-pass at the
+* near plane, and its ordinary occlusion discard then removes the water for
+* exactly the pixels the hull already covers.
+*
+* Park it as a CHILD of the thing it belongs to — a hull, a diving bell, a
+* dock's well, a cave mouth — and it follows along, rotation included.
+*
+* SAFE BY CONSTRUCTION: nothing is ever cut out of the water. The mask is the
+* owner's own silhouette, so water can only be hidden behind geometry the
+* player is already looking at. Size the box to the interior and err large —
+* an overlarge box just means more of this hull holds water back; it can never
+* punch a rectangle of bare ground into open water. (Needs the depth pre-pass:
+* `Water3D` in `fancy` quality. Skinned and instanced meshes are re-drawn at
+* their rest pose, so hang cutouts on ordinary geometry.)
+*
+* ```json
+* { "name": "Rowboat", "type": "RigidBody3D", "children": [
+*   { "name": "DryInside", "type": "WaterCutout3D",
+*     "props": { "size": [3.0, 1.2, 1.1], "position": [0, 0.4, 0] } } ] }
+* ```
+*
+* Cheap: a handful of these cost a few ALU per water pixel. `Water3D` reads the
+* nearest {@link WATER_CUTOUT_MAX} of them.
+*/
+var WaterCutout3D = class extends Node3D {
+	static typeName = "WaterCutout3D";
+	static props = {
+		size: { default: [
+			2,
+			1,
+			1
+		] },
+		enabled: { default: true }
+	};
+	/** Box extent in meters, centered on the node ([x, y, z]). */
+	size = [
+		2,
+		1,
+		1
+	];
+	/** Live toggle — a scuttled hull can start letting the sea in. */
+	enabled = true;
+	static validateJson(node) {
+		const c = node;
+		if (!Array.isArray(c.size) || c.size.length !== 3 || c.size.some((v) => !(v > 0))) throw new IncantoError("BAD_FORMAT", `WaterCutout3D '${node.name}' size must be three positive meters [x, y, z], got ${JSON.stringify(c.size)}.`, { prop: "size" });
+	}
+	/**
+	* A cutout works by re-drawing its PARENT, so it has to have one. At the
+	* scene root it would hand the whole world a licence to erase water — the
+	* one failure this design exists to rule out — so that arrangement is a hard
+	* load error, not a silent no-op. (Checked here rather than in
+	* `validateJson`: the loader validates a node before attaching it.)
+	*/
+	onReady() {
+		if (!this.parent?.parent) throw new IncantoError("BAD_FORMAT", `WaterCutout3D '${this.name}' must be a CHILD of the object that holds the water back (a hull, a diving bell, a dock's well) — it re-draws that object to keep water out of it, so at the scene root it has nothing to stand in for.`, { prop: "parent" });
+	}
+};
+/** How many cutouts one Water3D reads (the nearest ones win). */
+const WATER_CUTOUT_MAX = 4;
+//#endregion
 //#region src/3d/nodes/water-3d.ts
 const WATER_QUALITIES = ["fancy", "simple"];
 const COLOR_KEYS = [
@@ -2869,6 +2945,10 @@ var Water3D = class Water3D extends Node3D {
 		z: 0
 	};
 	_bodies = [];
+	_cutouts = [];
+	/** Scratch for the cutout mask pass (no per-frame allocation). */
+	_maskMeshes = [];
+	_maskSaved = [];
 	/** Scratch for the side-pass cull (no per-frame allocation). */
 	_passHidden = [];
 	cubeTarget = null;
@@ -3052,6 +3132,7 @@ var Water3D = class Water3D extends Node3D {
 		restoreForWaterPass(this._passHidden);
 		ctx.scene.overrideMaterial = prevOverride;
 		ctx.scene.background = prevBackground;
+		this.renderCutoutMasks(ctx);
 		ctx.gl.setRenderTarget(prevTarget);
 		ctx.gl.autoClear = prevAutoClear;
 		ctx.gl.clippingPlanes = prevClippingPlanes;
@@ -3232,6 +3313,61 @@ var Water3D = class Water3D extends Node3D {
 			side: DoubleSide
 		});
 	}
+	/**
+	* Stamp every {@link WaterCutout3D} owner into the depth pre-pass.
+	*
+	* The cutout does not describe a hole in the water — it names a piece of
+	* geometry that holds the water back, and this pass re-draws exactly that
+	* geometry (clipped to the cutout box) at the near plane. The water's
+	* occlusion discard does the rest. The tree is walked live, so a cutout on a
+	* bobbing hull tracks it with no wiring.
+	*/
+	renderCutoutMasks(ctx) {
+		const list = this._cutouts;
+		list.length = 0;
+		let top = this;
+		while (top.parent) top = top.parent;
+		collectCutouts(top, list);
+		if (list.length === 0) return;
+		const u = cutoutMaskMaterial.uniforms;
+		const saved = this._maskSaved;
+		const meshes = this._maskMeshes;
+		const prevClip = ctx.gl.clippingPlanes;
+		ctx.gl.clippingPlanes = noClipPlanes;
+		let n = 0;
+		for (const cut of list) {
+			if (n >= 4) break;
+			const ownerObj = cutoutOwnerObject(cut);
+			if (!ownerObj) continue;
+			cut._syncObject3D();
+			const world = cut._ensureObject3D();
+			world.updateWorldMatrix(true, false);
+			world.getWorldPosition(cutoutPosScratch);
+			world.getWorldQuaternion(cutoutQuatScratch);
+			(u.uCenter?.value)?.copy(cutoutPosScratch);
+			(u.uHalf?.value)?.set((cut.size[0] ?? 1) / 2, (cut.size[1] ?? 1) / 2, (cut.size[2] ?? 1) / 2);
+			cutoutEulerScratch.setFromQuaternion(cutoutQuatScratch, "YXZ");
+			(u.uYaw?.value)?.set(Math.cos(cutoutEulerScratch.y), Math.sin(cutoutEulerScratch.y));
+			meshes.length = 0;
+			saved.length = 0;
+			collectMaskMeshes(ownerObj, meshes);
+			if (meshes.length === 0) continue;
+			for (const m of meshes) {
+				saved.push(m.material);
+				m.material = cutoutMaskMaterial;
+			}
+			ctx.gl.render(ownerObj, ctx.camera);
+			for (let i = 0; i < meshes.length; i++) {
+				const m = meshes[i];
+				const mat = saved[i];
+				if (m && mat) m.material = mat;
+			}
+			n++;
+		}
+		meshes.length = 0;
+		saved.length = 0;
+		ctx.gl.clippingPlanes = prevClip;
+	}
 	syncFancy(mesh) {
 		const u = mesh.material.uniforms;
 		const w = this.size[0] ?? 1;
@@ -3444,6 +3580,45 @@ var Water3D = class Water3D extends Node3D {
 		});
 	}
 };
+const cutoutPosScratch = new Vector3();
+const cutoutQuatScratch = new Quaternion();
+const cutoutEulerScratch = new Euler();
+/** Every enabled water cutout in the tree, nearest-first is not needed: the
+* cap is small and scenes rarely exceed it. */
+function collectCutouts(node, out) {
+	if (node instanceof WaterCutout3D && node.enabled && node.visible) out.push(node);
+	for (const child of node.children) collectCutouts(child, out);
+}
+/**
+* The three object of the thing a cutout hangs on — its PARENT, the hull that
+* holds the water back. A cutout parented to the scene root has no owner and
+* does nothing (the loader rejects that arrangement outright): masking a whole
+* scene's geometry is how you get a hole in open water, which is the one thing
+* this design must never allow.
+*/
+function cutoutOwnerObject(cut) {
+	const owner = cut.parent;
+	if (!(owner instanceof Node3D) || !owner.parent) return null;
+	const obj = owner._ensureObject3D();
+	return typeof obj?.traverse === "function" ? obj : null;
+}
+/** Node types that never stand in for water, however they are parented. */
+const NEVER_MASKS = new Set([
+	"Terrain3D",
+	"Water3D",
+	"River3D"
+]);
+/** Visible meshes of a cutout owner, the ones the mask pass re-draws. */
+function collectMaskMeshes(root, out) {
+	root.traverse((obj) => {
+		const mesh = obj;
+		if (!mesh.isMesh || !mesh.visible || !mesh.material) return;
+		const type = (obj.userData?.incantoNode)?.constructor?.typeName;
+		if (type && NEVER_MASKS.has(type)) return;
+		out.push(mesh);
+	});
+	return out;
+}
 /** Bodies that can splash: kinematic characters and dynamic rigid bodies. */
 function collectBodies(node, out) {
 	if (node instanceof CharacterBody3D || node instanceof RigidBody3D) out.push(node);
@@ -3517,6 +3692,8 @@ const mirrorClipPlane = new Plane(new Vector3(0, 1, 0), 0);
 const mirrorClipPlanes = [mirrorClipPlane];
 const grabClipPlane = new Plane(new Vector3(0, -1, 0), 0);
 const grabClipPlanes = [grabClipPlane];
+/** No clipping — the cutout mask pass wants the submerged geometry back. */
+const noClipPlanes = [];
 /** Keep-above twin for the depth-completion pass: normal (0,1,0) keeps
 * y > −constant — set per render to waterY − slack (overlapping the grab). */
 const depthOnlyClipPlane = new Plane(new Vector3(0, 1, 0), 0);
@@ -3524,6 +3701,56 @@ const depthOnlyClipPlanes = [depthOnlyClipPlane];
 /** Shared override for the depth-completion pass — writes depth, never color. */
 const depthOnlyMaterial = new MeshDepthMaterial();
 depthOnlyMaterial.colorWrite = false;
+/**
+* The cutout mask material — the whole of {@link WaterCutout3D}'s mechanism.
+*
+* It is drawn over the cutout OWNER'S OWN meshes into the water's depth
+* pre-pass, and does exactly two things: throw away everything outside the
+* cutout box, and stamp what is left at the NEAR PLANE. The water's existing
+* occlusion discard then reads "something solid is in front of me here" and
+* removes itself — for exactly the pixels the owner's geometry already covers.
+*
+* Screen position is untouched (only clip-space z is rewritten), so the mask
+* is pixel-identical to the owner's silhouette. THAT is the safety property:
+* water can only ever be hidden behind the hull the player is looking at, so
+* an oversized box degrades into "more of this boat holds water back" and can
+* never carve a rectangle of bare seabed out of open water.
+*/
+const cutoutMaskMaterial = new ShaderMaterial({
+	uniforms: {
+		uCenter: { value: new Vector3() },
+		uHalf: { value: new Vector3(1, 1, 1) },
+		uYaw: { value: new Vector2(1, 0) }
+	},
+	vertexShader: `
+    uniform vec3 uCenter;
+    uniform vec2 uYaw;
+    varying vec3 vCutLocal;
+    void main() {
+      vec3 world = (modelMatrix * vec4(position, 1.0)).xyz;
+      vec3 rel = world - uCenter;
+      vCutLocal = vec3(rel.x * uYaw.x + rel.z * uYaw.y, rel.y, -rel.x * uYaw.y + rel.z * uYaw.x);
+      vec4 clip = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+      // pull the DEPTH to the near plane and nothing else — scaling the view
+      // position would slide the silhouette under perspective, and a silhouette
+      // that grows past its owner is exactly the hole this design forbids
+      clip.z = -clip.w * 0.99;
+      gl_Position = clip;
+    }
+  `,
+	fragmentShader: `
+    uniform vec3 uHalf;
+    varying vec3 vCutLocal;
+    void main() {
+      if (any(greaterThan(abs(vCutLocal), uHalf))) discard;
+      gl_FragColor = vec4(0.0);
+    }
+  `,
+	colorWrite: false,
+	depthWrite: true,
+	depthTest: false,
+	side: DoubleSide
+});
 //#endregion
 //#region src/gameplay/buoyancy.ts
 /** Gravity the float is sized against (m/s²) — the cap is expressed in g. */
@@ -5640,4 +5867,4 @@ function registerGameplayBehaviors(opts) {
 	for (const [name, ctor] of Object.entries(GAMEPLAY_BEHAVIORS)) registerBehavior(name, ctor, { replace });
 }
 //#endregion
-export { Water3D as A, colliderFootDrop as B, FollowCamera as C, Health as D, DamageOnContact as E, StaticBody3D as F, Node3D as I, validateCollider3D as L, CharacterBody3D as M, PhysicsBody3D as N, Collector as O, RigidBody3D as P, createCausticsQuad as R, restartScene as S, phaseOf as T, hitStop as _, Wander as a, GameFlow as b, Projectile as c, PathFollow as d, Oscillate as f, Cooldown as g, CameraShake as h, WaveSpawner as i, Area3D as j, Chase as k, Pickup as l, Lifetime as m, registerGameplayBehaviors as n, Spawner as o, MoveTo as p, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Patrol as u, screenFlash as v, DayNight as w, goToScene as x, Interactable as y, WATER_MAX_RIPPLES as z };
+export { Water3D as A, createCausticsQuad as B, FollowCamera as C, Health as D, DamageOnContact as E, PhysicsBody3D as F, colliderFootDrop as H, RigidBody3D as I, StaticBody3D as L, WaterCutout3D as M, Area3D as N, Collector as O, CharacterBody3D as P, Node3D as R, restartScene as S, phaseOf as T, WATER_MAX_RIPPLES as V, hitStop as _, Wander as a, GameFlow as b, Projectile as c, PathFollow as d, Oscillate as f, Cooldown as g, CameraShake as h, WaveSpawner as i, WATER_CUTOUT_MAX as j, Chase as k, Pickup as l, Lifetime as m, registerGameplayBehaviors as n, Spawner as o, MoveTo as p, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Patrol as u, screenFlash as v, DayNight as w, goToScene as x, Interactable as y, validateCollider3D as z };

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { C as FollowCamera, D as Health, E as DamageOnContact, O as Collector, S as restartScene, T as phaseOf, _ as hitStop, a as Wander, b as GameFlow, c as Projectile, d as PathFollow, f as Oscillate, g as Cooldown, h as CameraShake, i as WaveSpawner, k as Chase, l as Pickup, m as Lifetime, n as registerGameplayBehaviors, o as Spawner, p as MoveTo, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as screenFlash, w as DayNight, x as goToScene, y as Interactable } from "./gameplay-BFzBVqhr.js";
+import { C as FollowCamera, D as Health, E as DamageOnContact, O as Collector, S as restartScene, T as phaseOf, _ as hitStop, a as Wander, b as GameFlow, c as Projectile, d as PathFollow, f as Oscillate, g as Cooldown, h as CameraShake, i as WaveSpawner, k as Chase, l as Pickup, m as Lifetime, n as registerGameplayBehaviors, o as Spawner, p as MoveTo, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as screenFlash, w as DayNight, x as goToScene, y as Interactable } from "./gameplay-Ddk13pQ6.js";
 export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, DayNight, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, phaseOf, registerGameplayBehaviors, restartScene, screenFlash };