incanto 0.26.0 → 0.28.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-C0bPoURs.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-71TJjW1T.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

@@ -909,6 +909,12 @@ declare class Flowers3D extends Node3D {
   * draping entirely.
   */
   drape: boolean | null;
+  /**
+  * Keep plants out of standing and running water (default true) — a meadow a
+  * stream runs through has a bank of flowers, not flowers in the current.
+  * Set false for water lilies and marsh planting.
+  */
+  avoidWater: boolean;
   /** Drape target: a node path to the Terrain3D. Empty = auto-find the first
   * Terrain3D in the tree (the zero-config default when `drape` is on). */
   terrain: string;
@@ -1051,6 +1057,14 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   * a terrain appears), false disables draping entirely.
   */
   drape: boolean | null;
+  /**
+  * Keep blades out of standing and running water (default true). Grass does
+  * not grow in a stream: any instance whose ground sits under a `Water3D` or
+  * `River3D` surface is dropped, which is what stops a creek that cut its bed
+  * through a meadow from filling with waving blades. Set false for reeds and
+  * paddy fields, where the plant IS in the water.
+  */
+  avoidWater: boolean;
   /** Drape target: a node path to the Terrain3D. Empty = auto-find the first
   * Terrain3D in the tree (the zero-config default when `drape` is on). */
   terrain: string;
@@ -1119,6 +1133,14 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   * fraction of instances into a SECOND InstancedMesh of 5-vertex flower
   * heads (white/yellow/violet per instance).
   */
+  /**
+  * Drop the instances standing in water. The ground each blade drapes onto is
+  * already known here, so the test is one question per candidate — and only
+  * the ones a water surface actually covers pay for it.
+  */
+  private dryOnly;
+  /** This field's own world height (the bed sampler works in local Y). */
+  private worldY;
   private buildMeshField;
   /**
   * The meadow's flower sprinkle: ONE extra InstancedMesh of 5-vertex flower
@@ -1555,29 +1577,152 @@ declare class Particles3D extends Node3D {
   private syncParticles;
 }
 //#endregion
+//#region src/3d/terrain/heightmap.d.ts
+/**
+* A smooth radial depression carved into the terrain — a lake/pond bowl. x/z
+* are terrain-LOCAL centered meters (the same space `heightAt`/`slopeAt` use);
+* `radius`/`depth` are meters. The carve is a smoothstep bowl (0 slope at the
+* rim), so banks blend into the surrounding ground with no cliff.
+*/
+interface BasinSpec {
+  x: number;
+  z: number;
+  radius: number;
+  /** > 0 carves a bowl; < 0 RAISES a smooth dome mound of that height. */
+  depth: number;
+}
+/**
+* A river/road trench carved along a polyline: the line version of a basin.
+* `width` is the flat bed, `taper` the bank blend beyond it (default: the bed
+* width again, which is what makes a walkable V instead of a slot).
+*/
+interface ChannelSpec {
+  path: readonly (readonly number[])[];
+  width: number;
+  depth: number;
+  taper?: number;
+}
+interface HeightmapOptions {
+  /** Terrain extent in meters along x. */
+  width: number;
+  /** Terrain extent in meters along z. */
+  depth: number;
+  /** Grid segments along x (vertices = segsX+1). */
+  segsX: number;
+  /** Grid segments along z (vertices = segsZ+1). */
+  segsZ: number;
+  /** Height scale — realized heights land at roughly 3.5–8× this value. */
+  maxHeight: number;
+  /** Integer seed — same seed, same terrain, every machine. */
+  seed: number;
+  /** Detail persistence (amplitude falloff per detail octave). */
+  roughness?: number;
+  /** Detail octave count. */
+  detail?: number;
+  /** Snap-flatten heights within ±0.6 m of maxHeight·flatThreshold. */
+  flatThreshold?: number;
+  /** Curl the border down a quarter circle and floor it at edgeBottom. */
+  islandEdge?: boolean;
+  /** Quarter-circle radius in meters (clamped to [0, 45]). */
+  edgeWrapRadius?: number;
+  /** Floor y at the outermost ring once the wrap completes. */
+  edgeBottom?: number;
+  /** 0..1 — 1 rounds island corners fully, 0 keeps them square-ish. */
+  edgeCornerSmoothness?: number;
+  /** Smooth radial lake/pond bowls carved into the surface (interior basins). */
+  basins?: BasinSpec[];
+  /** River/road trenches carved along polylines (see {@link ChannelSpec}). */
+  channels?: ChannelSpec[];
+}
+interface Heightmap {
+  readonly width: number;
+  readonly depth: number;
+  readonly segsX: number;
+  readonly segsZ: number;
+  /**
+  * Vertex heights INCLUDING edge wrap, `(segsX+1)·(segsZ+1)` long, indexed
+  * `iz·(segsX+1)+ix` with x = -width/2 + ix·cell and z = -depth/2 + iz·cell —
+  * exactly a rotateX(-π/2) PlaneGeometry's vertex order.
+  */
+  readonly heights: Float32Array;
+  /** Realized height range EXCLUDING edge wrap — normalizes splat heights. */
+  readonly minHeight: number;
+  readonly maxHeight: number;
+  /** Bilinear height lookup in terrain-local centered meters (clamps outside). */
+  heightAt(x: number, z: number): number;
+  /** Analytic pipeline height WITHOUT edge wrap (splat domain), same coords. */
+  baseHeight(x: number, z: number): number;
+  /** Splat slope at a point: atan(|∇ baseHeight|) via central differences. */
+  slopeAt(x: number, z: number): number;
+}
+/** One splat layer: a texture plus the trapezoid ranges that place it. */
+interface TerrainLayer {
+  /** Base color texture URL. */
+  texture: string;
+  /** Optional tangent-space normal map URL. */
+  normalMap?: string;
+  /** World-UV tiling factor (UV = worldXZ · repeat · 0.1). Default 2. */
+  repeat?: number;
+  /** Normalized [min, max] over the realized height span. Default [0, 1]. */
+  heightRange?: [number, number];
+  /** [min, max] slope in radians (atan of gradient). Default [0, π/2]. */
+  slopeRange?: [number, number];
+  /** Linear falloff width OUTSIDE heightRange (fraction of span). Default 0.1. */
+  heightBlendRange?: number;
+  /** Linear falloff width outside slopeRange (radians). Default 0.1. */
+  slopeBlendRange?: number;
+  /** PBR roughness scalar for this layer. Default 1. */
+  roughness?: number;
+  /** PBR metalness scalar for this layer. Default 0. */
+  metalness?: number;
+  /** Anti-tiling UV jitter strength. Default 0.15. */
+  uvNoiseIntensity?: number;
+}
+/**
+* Build the deterministic heightfield. Heavy (one noise eval per vertex) —
+* call once and keep the result.
+*/
+declare function buildHeightmap(opts: HeightmapOptions): Heightmap;
+/**
+* Per-vertex splat weights for up to 4 layers. `height01` is the vertex
+* height normalized over the heightmap's realized (no-wrap) span, `slopeRad`
+* is `atan(|∇h|)`. Weight = heightTrapezoid · slopeTrapezoid, sharpened by
+* `pow(w, 1/blendingStrength)`, then normalized to sum 1 — when nothing
+* matches, layer 0 takes everything. Always returns exactly 4 entries
+* (missing layers weigh 0).
+*/
+declare function splatWeights(height01: number, slopeRad: number, layers: readonly TerrainLayer[], blendingStrength?: number): [number, number, number, number];
+//#endregion
 //#region src/3d/water/river.d.ts
+/** Terrain height under a LOCAL-frame point, in the same frame's meters. */
+type BedSampler = (x: number, z: number) => number;
+interface RiverCarveOptions {
+  /** Centreline in the TERRAIN'S local frame (that is where channels live). */
+  path: readonly (readonly number[])[];
+  /** Width profile source→mouth (one entry = constant). */
+  widths: readonly number[];
+  /** Water column at the centreline, meters. */
+  depth: number;
+  /** Terrain cell size in meters — a cut finer than this does not exist. */
+  cell: number;
+  /** Ground height BEFORE this river cut anything. */
+  groundAt: BedSampler;
+}
 /**
-* River centerline math — the CPU half of {@link River3D}.
-*
-* Everything here works in the river node's LOCAL frame (the caller hands in a
-* `bedAt(x, z)` sampler that has already been shifted into it), so this module
-* imports nothing from three and stays testable in plain node.
+* The trench a river digs for itself, as {@link ChannelSpec}s for Terrain3D.
 *
-* The shape of a river is NOT authored: it is derived. A path of control
-* points and a width profile is all a scene declares; the ground underneath
-* decides the rest —
+* Shared on purpose: `River3D` cuts this at load, and anything that has to
+* PLACE things against the result — a scene generator putting a player, a
+* bridge and a boulder field on the ground — computes the identical cut
+* instead of approximating it. A generator that guesses differently spawns the
+* player inside a hill.
 *
-* - the **surface profile** follows the bed's descending envelope, so the water
-*   runs downhill and never climbs (a rising bed dams it into a still pool);
-* - the **visible width** is whatever the terrain lets the water occupy: every
-*   vertex carries its own water column (`surfaceY − bed`), the shader fades to
-*   nothing where that reaches zero, so banks, gravel bars and half-drowned
-*   boulders carve the ribbon instead of a hand-authored outline;
-* - the **current** obeys continuity (narrow = fast) and grade (steep = fast),
-*   which is what makes rapids sit where a channel pinches or tips.
+* The floor only ever FALLS. Water does not climb, so a bed that climbs is a
+* river that stops and buries itself; carrying the running minimum downstream
+* digs through a rise instead, and the cap keeps that from turning a hill into
+* a canyon.
 */
-/** Terrain height under a LOCAL-frame point, in the same frame's meters. */
-type BedSampler = (x: number, z: number) => number;
+declare function riverCarveChannels(opts: RiverCarveOptions): ChannelSpec[];
 /** One arc-length sample of the smoothed centerline. */
 interface PathSample {
   x: number;
@@ -1590,7 +1735,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 +1862,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 +1889,28 @@ 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;
+  /**
+  * @internal Water surface height over a world point, or null where this
+  * river does not run — the question scattered vegetation asks before it
+  * plants a blade (see {@link WetSurface}).
+  */
+  _waterYAt(x: number, z: number): number | null;
   /**
   * 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 +1938,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 +1955,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
@@ -1779,122 +1985,6 @@ declare class River3D extends Node3D implements SunConsumer3D {
   private sweepBodies;
 }
 //#endregion
-//#region src/3d/terrain/heightmap.d.ts
-/**
-* A smooth radial depression carved into the terrain — a lake/pond bowl. x/z
-* are terrain-LOCAL centered meters (the same space `heightAt`/`slopeAt` use);
-* `radius`/`depth` are meters. The carve is a smoothstep bowl (0 slope at the
-* rim), so banks blend into the surrounding ground with no cliff.
-*/
-interface BasinSpec {
-  x: number;
-  z: number;
-  radius: number;
-  /** > 0 carves a bowl; < 0 RAISES a smooth dome mound of that height. */
-  depth: number;
-}
-/**
-* A river/road trench carved along a polyline: the line version of a basin.
-* `width` is the flat bed, `taper` the bank blend beyond it (default: the bed
-* width again, which is what makes a walkable V instead of a slot).
-*/
-interface ChannelSpec {
-  path: readonly (readonly number[])[];
-  width: number;
-  depth: number;
-  taper?: number;
-}
-interface HeightmapOptions {
-  /** Terrain extent in meters along x. */
-  width: number;
-  /** Terrain extent in meters along z. */
-  depth: number;
-  /** Grid segments along x (vertices = segsX+1). */
-  segsX: number;
-  /** Grid segments along z (vertices = segsZ+1). */
-  segsZ: number;
-  /** Height scale — realized heights land at roughly 3.5–8× this value. */
-  maxHeight: number;
-  /** Integer seed — same seed, same terrain, every machine. */
-  seed: number;
-  /** Detail persistence (amplitude falloff per detail octave). */
-  roughness?: number;
-  /** Detail octave count. */
-  detail?: number;
-  /** Snap-flatten heights within ±0.6 m of maxHeight·flatThreshold. */
-  flatThreshold?: number;
-  /** Curl the border down a quarter circle and floor it at edgeBottom. */
-  islandEdge?: boolean;
-  /** Quarter-circle radius in meters (clamped to [0, 45]). */
-  edgeWrapRadius?: number;
-  /** Floor y at the outermost ring once the wrap completes. */
-  edgeBottom?: number;
-  /** 0..1 — 1 rounds island corners fully, 0 keeps them square-ish. */
-  edgeCornerSmoothness?: number;
-  /** Smooth radial lake/pond bowls carved into the surface (interior basins). */
-  basins?: BasinSpec[];
-  /** River/road trenches carved along polylines (see {@link ChannelSpec}). */
-  channels?: ChannelSpec[];
-}
-interface Heightmap {
-  readonly width: number;
-  readonly depth: number;
-  readonly segsX: number;
-  readonly segsZ: number;
-  /**
-  * Vertex heights INCLUDING edge wrap, `(segsX+1)·(segsZ+1)` long, indexed
-  * `iz·(segsX+1)+ix` with x = -width/2 + ix·cell and z = -depth/2 + iz·cell —
-  * exactly a rotateX(-π/2) PlaneGeometry's vertex order.
-  */
-  readonly heights: Float32Array;
-  /** Realized height range EXCLUDING edge wrap — normalizes splat heights. */
-  readonly minHeight: number;
-  readonly maxHeight: number;
-  /** Bilinear height lookup in terrain-local centered meters (clamps outside). */
-  heightAt(x: number, z: number): number;
-  /** Analytic pipeline height WITHOUT edge wrap (splat domain), same coords. */
-  baseHeight(x: number, z: number): number;
-  /** Splat slope at a point: atan(|∇ baseHeight|) via central differences. */
-  slopeAt(x: number, z: number): number;
-}
-/** One splat layer: a texture plus the trapezoid ranges that place it. */
-interface TerrainLayer {
-  /** Base color texture URL. */
-  texture: string;
-  /** Optional tangent-space normal map URL. */
-  normalMap?: string;
-  /** World-UV tiling factor (UV = worldXZ · repeat · 0.1). Default 2. */
-  repeat?: number;
-  /** Normalized [min, max] over the realized height span. Default [0, 1]. */
-  heightRange?: [number, number];
-  /** [min, max] slope in radians (atan of gradient). Default [0, π/2]. */
-  slopeRange?: [number, number];
-  /** Linear falloff width OUTSIDE heightRange (fraction of span). Default 0.1. */
-  heightBlendRange?: number;
-  /** Linear falloff width outside slopeRange (radians). Default 0.1. */
-  slopeBlendRange?: number;
-  /** PBR roughness scalar for this layer. Default 1. */
-  roughness?: number;
-  /** PBR metalness scalar for this layer. Default 0. */
-  metalness?: number;
-  /** Anti-tiling UV jitter strength. Default 0.15. */
-  uvNoiseIntensity?: number;
-}
-/**
-* Build the deterministic heightfield. Heavy (one noise eval per vertex) —
-* call once and keep the result.
-*/
-declare function buildHeightmap(opts: HeightmapOptions): Heightmap;
-/**
-* Per-vertex splat weights for up to 4 layers. `height01` is the vertex
-* height normalized over the heightmap's realized (no-wrap) span, `slopeRad`
-* is `atan(|∇h|)`. Weight = heightTrapezoid · slopeTrapezoid, sharpened by
-* `pow(w, 1/blendingStrength)`, then normalized to sum 1 — when nothing
-* matches, layer 0 takes everything. Always returns exactly 4 entries
-* (missing layers weigh 0).
-*/
-declare function splatWeights(height01: number, slopeRad: number, layers: readonly TerrainLayer[], blendingStrength?: number): [number, number, number, number];
-//#endregion
 //#region src/3d/terrain/themes.d.ts
 /** Valid `Terrain3D.theme` values — drives the prop options AND validateJson. */
 declare const TERRAIN_THEMES: readonly ["island", "alpine", "plains", "desert", "grassland", "forest", "savanna", "snow", "wetland", "volcanic", "custom"];
@@ -1965,6 +2055,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 +2087,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'. */
@@ -2463,6 +2569,13 @@ declare class Water3D extends Node3D implements RenderHook3D, SunConsumer3D {
   * the still-water level, which is what a caller comparing heights wants.
   */
   heightAt(x: number, z: number): number;
+  /**
+  * @internal Water surface height over a world point, or null outside this
+  * surface's footprint — what scattered vegetation asks before it plants a
+  * blade (see {@link WetSurface}). The STILL level, not the wave: grass does
+  * not come and go with the swash.
+  */
+  _waterYAt(x: number, z: number): number | null;
   /** Base wave height at world (x, z) — the CPU twin of the active shader.
   * Ripples are excluded on purpose: a splash must not re-trigger itself. */
   private waveOffsetAt;
@@ -2828,4 +2941,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_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 };
+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 RiverCarveOptions, 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, riverCarveChannels, 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 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 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-DEG-TP7D.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-BRgWpNsa.js";
+import { A as Joint3D, C as BoneLookAt3D, D as DEFAULT_TERRAIN_TEXTURE_BASE, E as Terrain3D, F as rigPose, M as cameraRelative, N as keyboardIntensity, O as TERRAIN_THEMES, P as movementState, S as Camera3D, T as Billboard3D, _ as DENSITY_PRESETS, a as Trail3D, b as FLOWER_VARIETIES, c as traceDownhillPath, d as LoftMesh3D, f as DirectionalLight3D, g as Foliage3D, h as MeshInstance3D, i as Tree3D, j as QUARTER_PITCH, k as terrainThemeLayers, l as Particles3D, m as InstancedMesh3D, n as VOXEL_PALETTE, o as River3D, p as OmniLight3D, r as VoxelGrid3D, s as riverCarveChannels, t as registerNodes3D, u as ModelInstance3D, v as Flowers3D, w as BoneAttachment3D, x as CharacterController3D, y as resolveFlowerDensity } from "./register-6R75AC7-.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--y5clE2j.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_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 };
+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, riverCarveChannels, setEnvironment3D, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };

package/dist/{create-game-C0bPoURs.js → create-game-71TJjW1T.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-Ddk13pQ6.js";
+import { n as registerGameplayBehaviors } from "./gameplay-DEG-TP7D.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-B_qBR65J.js → create-game-BRgWpNsa.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 { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-Ddk13pQ6.js";
+import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-DEG-TP7D.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 { S as Camera3D, f as DirectionalLight3D, t as registerNodes3D, u as ModelInstance3D } from "./register-6R75AC7-.js";
+import { n as enablePhysics3D } from "./physics-3d--y5clE2j.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-Ddk13pQ6.js → gameplay-DEG-TP7D.js}

@@ -3565,6 +3565,19 @@ var Water3D = class Water3D extends Node3D {
 		const center = worldTranslationOf(this, this._scratchA);
 		return center.y + this.waveOffsetAt(x, z, center);
 	}
+	/**
+	* @internal Water surface height over a world point, or null outside this
+	* surface's footprint — what scattered vegetation asks before it plants a
+	* blade (see {@link WetSurface}). The STILL level, not the wave: grass does
+	* not come and go with the swash.
+	*/
+	_waterYAt(x, z) {
+		const center = worldTranslationOf(this, this._scratchA);
+		const halfX = (this.size[0] ?? 0) / 2;
+		const halfZ = (this.size[1] ?? 0) / 2;
+		if (Math.abs(x - center.x) > halfX || Math.abs(z - center.z) > halfZ) return null;
+		return center.y;
+	}
 	/** Base wave height at world (x, z) — the CPU twin of the active shader.
 	* Ripples are excluded on purpose: a splash must not re-trigger itself. */
 	waveOffsetAt(x, z, center) {

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-Ddk13pQ6.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-DEG-TP7D.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 };

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.28.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 };