incanto 0.11.0 → 0.13.0

package/README.md

@@ -3,6 +3,28 @@
 **Vibe-coding-first web game engine SDK.** Every scene, character, event, and multiplayer
 rule is JSON an AI agent can read, diff, and rewrite — rendered by three.js.
 
+## Start with a whole game
+
+```bash
+bunx incanto-new my-game        # Beacon Isle — the flagship 3D template
+cd my-game && bun install && bun run dev
+```
+
+One command scaffolds a complete island action-adventure: a **generated
+golden-hour world** (terrain, sea, groves, grass — `bun run world` re-rolls the
+whole island deterministically), a quest NPC with dialogue and choices, enemies
+that **hunt you across the terrain** via grid navigation, melee with a sword
+riding the character's hand bone, bloom + color-grade, touch controls on
+phones, win fireworks and a death/respawn loop — in ~2 files of game code, the
+rest declared in JSON. `bun run verify` plays the entire quest **headlessly**
+and replays recorded input bit-identically: the agent loop is author → verify →
+fix, no browser needed.
+
+`bunx incanto-new --list` shows the other starters (third-person shooter,
+quest vignette).
+
+## Or wire the engine yourself
+
 ```bash
 bun add incanto three
 ```

package/bin/incanto-new.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * incanto-new — scaffold a ready-to-run incanto game from a shipped template:
+ *
+ *   bunx incanto-new my-game                       # Beacon Isle (3D flagship)
+ *   bunx incanto-new my-game --template tps-3d     # third-person shooter
+ *   bunx incanto-new --list
+ *
+ * Copies the template, names the package after the directory, prints the
+ * three commands that get you playing. Templates are real npm consumers —
+ * no monorepo, no aliases.
+ */
+import { cpSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const TEMPLATES_DIR = join(PKG, 'templates-app');
+
+const DESCRIPTIONS = {
+  'beacon-isle-3d':
+    '3D island action-adventure (the flagship): generated world, quest NPC, terrain-nav enemies, melee',
+  'village-quest-3d': '3D quest vignette: dialogue, scene transitions, patrol AI, sword combat',
+  'tps-3d': 'third-person arena shooter: GLB soldier, hitscan rifle, enemy waves',
+};
+
+function listTemplates() {
+  if (!existsSync(TEMPLATES_DIR)) return [];
+  return readdirSync(TEMPLATES_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+const argv = process.argv.slice(2);
+if (argv.includes('--list') || argv.includes('-l')) {
+  for (const t of listTemplates()) {
+    console.log(`  ${t.padEnd(20)} ${DESCRIPTIONS[t] ?? ''}`);
+  }
+  process.exit(0);
+}
+
+let target;
+let template = 'beacon-isle-3d';
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--template' || argv[i] === '-t') template = argv[++i];
+  else if (!argv[i].startsWith('-') && !target) target = argv[i];
+}
+
+if (!target) {
+  console.error('usage: incanto-new <dir> [--template <name>] | --list');
+  process.exit(1);
+}
+
+const templates = listTemplates();
+if (!templates.includes(template)) {
+  console.error(`unknown template '${template}'. Available: ${templates.join(', ')}`);
+  process.exit(1);
+}
+
+const dest = resolve(process.cwd(), target);
+if (existsSync(dest)) {
+  console.error(`refusing to scaffold: '${dest}' already exists.`);
+  process.exit(1);
+}
+
+cpSync(join(TEMPLATES_DIR, template), dest, { recursive: true });
+
+const pkgPath = join(dest, 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+pkg.name = basename(dest)
+  .toLowerCase()
+  .replace(/[^a-z0-9-]/g, '-');
+writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+
+console.log(`
+  ${template} → ${target}
+
+  cd ${target}
+  bun install        # or: npm install
+  bun run dev        # play it
+  bun run verify     # prove it plays, headlessly
+  bun run check      # validate the scene JSON
+
+  Vibe-coding? Install the agent skills too:
+  bunx incanto-skills claude   # or: opencode
+`);

package/dist/2d.d.ts

@@ -1,6 +1,6 @@
 import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-Bod1AyJS.js";
-import { t as LoadSceneOptions } from "./loader-BcUDfNHn.js";
+import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-CPibUfnH.js";
+import { t as LoadSceneOptions } from "./loader-DILt9PGC.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CdWhP6ve.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-BD6zgrv_.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-DweTURFt.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-Ct86zczq.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-Djwckzgx.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BiIdl51r.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset

package/dist/3d.d.ts

@@ -1,8 +1,8 @@
 import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-Bod1AyJS.js";
-import { t as LoadSceneOptions } from "./loader-BcUDfNHn.js";
+import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-CPibUfnH.js";
+import { t as LoadSceneOptions } from "./loader-DILt9PGC.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
-import { r as SpatialPose } from "./audio-player-Dyjg5k92.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 { VRM } from "@pixiv/three-vrm";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
@@ -474,6 +474,14 @@ interface BloomEnvironment {
   /** How strongly the blurred glow is added back (0 = off, ~1.2 = neon). */
   strength: number;
 }
+interface PostEnvironment {
+  /** Corner darkening, 0 (off) … 1 (heavy). Default 0. */
+  vignette: number;
+  /** Color saturation multiplier: 0 = grayscale, 1 = neutral. Default 1. */
+  saturation: number;
+  /** Contrast around mid-gray: 1 = neutral. Default 1. */
+  contrast: number;
+}
 interface Environment3DConfig {
   /** Tone-mapping exposure (ACES), default 1. */
   exposure: number;
@@ -485,6 +493,8 @@ interface Environment3DConfig {
   clouds: CloudsEnvironment | null;
   /** Bloom post pass (bright-pass → blur → additive composite), or null. */
   bloom: BloomEnvironment | null;
+  /** Color grade + vignette (tone-mapped composite tail), or null. */
+  post: PostEnvironment | null;
   /**
   * `null` = not declared (shadow maps stay available, free until a light
   * casts), `false` = force-disabled, object = declared ON with quality knobs
@@ -567,6 +577,8 @@ declare class Environment3D {
   get clouds(): CloudsEnvironment | null;
   /** Parsed bloom config, or null when no bloom pass is declared. */
   get bloom(): BloomEnvironment | null;
+  /** Parsed color-grade/vignette config, or null when not declared. */
+  get post(): PostEnvironment | null;
   /** The live scene fog (color/near/far) the cloud composite fades into, or null. */
   get sceneFog(): {
     color: Color;
@@ -606,6 +618,21 @@ declare class Environment3D {
   dispose(): void;
 }
 //#endregion
+//#region src/3d/environment-runtime.d.ts
+/**
+* Live environment editing — the renderer re-applies `scene.environment`
+* every frame (cheap when unchanged), so changing the LOOK at runtime is
+* just writing that object. This helper does it safely:
+*
+*   setEnvironment3D(engine, { sky: { elevationDeg: 4 }, exposure: 0.8 });
+*   setEnvironment3D(engine, { fog: null });          // null DELETES a key
+*
+* - one-level deep merge (patching `sky.elevationDeg` keeps the other sky keys)
+* - hard-validates the merged result NOW (in your call stack), so a bad patch
+*   throws where you wrote it — never inside the render loop
+*/
+declare function setEnvironment3D(engine: Engine, patch: JsonObject): void;
+//#endregion
 //#region src/3d/nodes/billboard-3d.d.ts
 /** Valid `Billboard3D.mode` values — drives the prop options AND validateJson. */
 declare const BILLBOARD_GROUP_MODES: readonly ["screen", "y", "none"];
@@ -680,6 +707,37 @@ declare class BoneAttachment3D extends Node3D {
   override free(): void;
 }
 //#endregion
+//#region src/3d/nodes/bone-look-at-3d.d.ts
+/**
+* Look-at IK for one bone — the character's head (or chest, or turret) turns
+* toward a target node ON TOP of whatever the animation is doing. Runs after
+* the mixer each rendered frame, blends in/out smoothly, and DISENGAGES when
+* the target leaves the comfort cone (no owl necks).
+*
+*   { "name": "HeadTrack", "type": "BoneLookAt3D",
+*     "props": { "target": "../Skin", "bone": "Head", "lookAt": "%Player" } }
+*
+* `forwardAxis` names the bone's local facing axis (mixamo heads face +z,
+* the default). Purely visual — headless it's a no-op.
+*/
+declare class BoneLookAt3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  target: string;
+  bone: string;
+  lookAt: string;
+  maxAngleDeg: number;
+  weight: number;
+  forwardAxis: string;
+  private boneObj;
+  private lookedUpFor;
+  /** 0..1 engage blend — eases in/out so tracking never snaps. */
+  private engage;
+  /** Test hook. */
+  get attachedBone(): Object3D | null;
+  _onRender3D(_ctx: RenderContext3D): void;
+}
+//#endregion
 //#region src/3d/nodes/camera-3d.d.ts
 /**
 * A perspective camera. Mark exactly one camera `current: true`; with none
@@ -1064,73 +1122,6 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   override free(): void;
 }
 //#endregion
-//#region src/3d/nodes/joint-3d.d.ts
-type JointType3D = "fixed" | "spherical" | "rope" | "spring";
-/**
-* A physics joint linking its PARENT body to `target` (a node path to the
-* other body). Godot-style placement: the joint lives as a child of body A.
-*
-*   { "name": "Hinge", "type": "Joint3D",
-*     "props": { "type": "spherical", "target": "%Anchor", "anchor": [0, -20] } }
-*
-* Types: `fixed` welds the bodies rigidly · `spherical` is a ball joint at the
-* anchors · `rope` caps the anchor distance at `length` (m; 0 = measured at
-* creation) · `spring` pulls toward `length` with `stiffness`/`damping`.
-* Anchors are LOCAL meter offsets on each body.
-*/
-declare class Joint3D extends Node3D {
-  static override readonly typeName: string;
-  static override readonly props: PropSchema;
-  type: JointType3D;
-  target: string;
-  anchor: number[];
-  targetAnchor: number[];
-  /** rope/spring rest length in m; 0 = measure body distance at creation. */
-  length: number;
-  stiffness: number;
-  damping: number;
-  override onEnterTree(): void;
-  /** @internal The two bodies, resolved (throws on a bad target at step time). */
-  _resolveBodies(): {
-    a: PhysicsBody3D;
-    b: PhysicsBody3D;
-  };
-}
-//#endregion
-//#region src/3d/nodes/lights-3d.d.ts
-/** Sun-style light. Direction comes from the node's rotation. */
-declare class DirectionalLight3D extends Node3D {
-  static override readonly typeName: string;
-  static override readonly props: PropSchema;
-  color: string;
-  intensity: number;
-  castShadow: boolean;
-  /** Half-extent of the directional shadow frustum (template default ±75). */
-  shadowArea: number;
-  shadowMapSize: number;
-  /**
-  * Re-center the shadow frustum on the camera every frame. A directional sun's
-  * shadow map covers a fixed ortho box; in a big roaming world that box must be
-  * huge (and so low-resolution that the player's own shadow nearly vanishes).
-  * With this on, a SMALL `shadowArea` tracks the camera, so contact shadows stay
-  * crisp wherever you go. The renderer supplies the camera position.
-  */
-  shadowFollowsCamera: boolean;
-  protected override _createObject3D(): Object3D;
-  override _syncObject3D(): void;
-}
-/** Point light with a range (Godot's OmniLight3D). */
-declare class OmniLight3D extends Node3D {
-  static override readonly typeName: string;
-  static override readonly props: PropSchema;
-  color: string;
-  intensity: number;
-  /** 0 = unlimited (three `distance` semantics). */
-  range: number;
-  protected override _createObject3D(): Object3D;
-  override _syncObject3D(): void;
-}
-//#endregion
 //#region src/3d/nodes/mesh-instance-3d.d.ts
 type MeshKind = "box" | "sphere" | "capsule" | "plane" | "cylinder" | "gem";
 interface MeshMaterialProps {
@@ -1208,6 +1199,109 @@ declare class MeshInstance3D extends Node3D {
   override free(): void;
 }
 //#endregion
+//#region src/3d/nodes/instanced-mesh-3d.d.ts
+/**
+* Hundreds of copies of one mesh in ONE draw call — scattered rocks, fence
+* posts, pillars, crates, gravestones. Same `mesh`/`size`/`material` surface
+* as MeshInstance3D; `transforms` places the copies:
+*
+*   { "name": "Rocks", "type": "InstancedMesh3D",
+*     "props": { "mesh": "gem", "size": [0.7, 0.5, 0.7],
+*       "material": { "color": "#8a8f98", "roughness": 0.9, "flatShading": true },
+*       "transforms": [[12, 0.2, -8, 40, 1.3], [-6, 0.1, 14, 210, 0.8]] } }
+*
+* Each row is `[x, y, z, yawDeg?, scale?]` (yaw 0 and scale 1 when omitted) —
+* dense enough to generate hundreds inline. REPLACE the array to update
+* (mutations are not watched).
+*/
+declare class InstancedMesh3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  mesh: string;
+  size: number[];
+  material: MeshMaterialProps;
+  castShadow: boolean;
+  receiveShadow: boolean;
+  private _transforms;
+  private transformsDirty;
+  get transforms(): number[][];
+  set transforms(value: number[][]);
+  private instanced;
+  private builtKey;
+  static validateJson(node: Node): void;
+  /** Test hook: the live instance count. */
+  get instanceCount(): number;
+  override _syncObject3D(alpha?: number): void;
+  override free(): void;
+}
+//#endregion
+//#region src/3d/nodes/joint-3d.d.ts
+type JointType3D = "fixed" | "spherical" | "rope" | "spring";
+/**
+* A physics joint linking its PARENT body to `target` (a node path to the
+* other body). Godot-style placement: the joint lives as a child of body A.
+*
+*   { "name": "Hinge", "type": "Joint3D",
+*     "props": { "type": "spherical", "target": "%Anchor", "anchor": [0, -20] } }
+*
+* Types: `fixed` welds the bodies rigidly · `spherical` is a ball joint at the
+* anchors · `rope` caps the anchor distance at `length` (m; 0 = measured at
+* creation) · `spring` pulls toward `length` with `stiffness`/`damping`.
+* Anchors are LOCAL meter offsets on each body.
+*/
+declare class Joint3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  type: JointType3D;
+  target: string;
+  anchor: number[];
+  targetAnchor: number[];
+  /** rope/spring rest length in m; 0 = measure body distance at creation. */
+  length: number;
+  stiffness: number;
+  damping: number;
+  override onEnterTree(): void;
+  /** @internal The two bodies, resolved (throws on a bad target at step time). */
+  _resolveBodies(): {
+    a: PhysicsBody3D;
+    b: PhysicsBody3D;
+  };
+}
+//#endregion
+//#region src/3d/nodes/lights-3d.d.ts
+/** Sun-style light. Direction comes from the node's rotation. */
+declare class DirectionalLight3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  color: string;
+  intensity: number;
+  castShadow: boolean;
+  /** Half-extent of the directional shadow frustum (template default ±75). */
+  shadowArea: number;
+  shadowMapSize: number;
+  /**
+  * Re-center the shadow frustum on the camera every frame. A directional sun's
+  * shadow map covers a fixed ortho box; in a big roaming world that box must be
+  * huge (and so low-resolution that the player's own shadow nearly vanishes).
+  * With this on, a SMALL `shadowArea` tracks the camera, so contact shadows stay
+  * crisp wherever you go. The renderer supplies the camera position.
+  */
+  shadowFollowsCamera: boolean;
+  protected override _createObject3D(): Object3D;
+  override _syncObject3D(): void;
+}
+/** Point light with a range (Godot's OmniLight3D). */
+declare class OmniLight3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  color: string;
+  intensity: number;
+  /** 0 = unlimited (three `distance` semantics). */
+  range: number;
+  protected override _createObject3D(): Object3D;
+  override _syncObject3D(): void;
+}
+//#endregion
 //#region src/3d/nodes/loft-mesh-3d.d.ts
 /**
 * One station of a loft: the hull's cross-section at local `z`.
@@ -1281,6 +1375,16 @@ declare class ModelInstance3D extends Node3D {
   castShadow: boolean;
   /** false = play the clip once, then emit `animationFinished`. */
   animationLoop: boolean;
+  /**
+  * Two-layer animation: play this clip on the UPPER BODY ONLY (the
+  * `upperBodyRoot` bone subtree) while `animation` keeps driving the rest —
+  * attack while running, wave while walking. One-shot by default
+  * (`animationUpperLoop: false`): finishes, emits `animationFinished` with
+  * this key, and auto-clears back to ''.
+  */
+  animationUpper: string;
+  animationUpperLoop: boolean;
+  upperBodyRoot: string;
   receiveShadow: boolean;
   /** Hex colour multiplied into every material — RESKIN one shared GLB into many
   *  variants (e.g. a sickly-green zombie from the base human). '' = untinted. */
@@ -1299,6 +1403,12 @@ declare class ModelInstance3D extends Node3D {
   private mixer;
   private playing;
   private currentAction;
+  private playingUpper;
+  private upperAction;
+  /** Which variant the BASE action is playing ('lower' while a layer is on). */
+  private baseMode;
+  /** Masked-clip cache: source clip uuid + layer root → {upper, lower}. */
+  private readonly maskCache;
   /** action → the `animation` key that played it, so `animationFinished` reports
   *  the clip that ACTUALLY finished (a crossfaded-away one-shot can finish a few
   *  frames after `this.animation` already moved on). */
@@ -1340,7 +1450,15 @@ declare class ModelInstance3D extends Node3D {
   private applyMaterialMods;
   /** Re-apply every queued named-node pose onto the mounted instance. */
   private applyPoses;
+  /** Resolve a clip ref: embedded name → '$asset' / URL (VRM-retargeted when
+  *  needed). 'loading' = asset still fetching, try again next frame. */
+  private resolveClip;
+  /** Masked upper/lower variants of a clip for two-layer playback (cached). */
+  private layerVariants;
+  private upperLayerActive;
   private syncAnimation;
+  /** The upper-body layer: masked clip on the `upperBodyRoot` subtree. */
+  private syncUpperAnimation;
   override update(dt: number): void;
   override onExitTree(): void;
   private unmount;
@@ -2207,4 +2325,61 @@ interface WalkState {
   ignoreStatic: boolean;
 }
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, type BillboardGroupMode, BoneAttachment3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type Game3D, type Heightmap, type HeightmapOptions, 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, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainTheme, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };
+//#region src/3d/terrain-nav.d.ts
+/**
+* Terrain navigation — the bridge from a `Terrain3D` heightfield to the grid
+* A* (`findPath`). Sample the surface into walkable cells (slope- and
+* height-limited), path on the grid, then lift waypoints back onto the
+* surface with `toWorld` (its y IS the terrain height):
+*
+*   const nav = buildTerrainNav(terrain, { cellSize: 2, maxSlopeDeg: 40 });
+*   const cells = findPath(nav.grid, nav.toCell(wolfX, wolfZ), nav.toCell(px, pz));
+*   follow.setPath(cells.map(([cx, cy]) => nav.toWorld(cx, cy)));
+*
+* Trees/rocks/buildings aren't in the heightfield — stamp them out with
+* `setSolid(...nav.toCell(x, z))` after building.
+*/
+interface TerrainNav {
+  /** Feed this straight into `findPath`. */
+  grid: PathGrid;
+  cellSize: number;
+  /** World x/z → cell coords (unclamped — check bounds via grid width/height). */
+  toCell(x: number, z: number): [number, number];
+  /** Cell → world position AT THE SURFACE ([x, terrainHeight, z], cell center). */
+  toWorld(cx: number, cy: number): [number, number, number];
+  /** Mark a cell unwalkable (props, buildings, no-go zones). */
+  setSolid(cx: number, cy: number): void;
+}
+/** What we need from the terrain — Terrain3D satisfies this. */
+interface HeightSampler extends Node {
+  size: number[];
+  heightAt(x: number, z: number): number;
+}
+interface TerrainNavOptions {
+  /** Meters per cell (default 2 — character-scale corridors). */
+  cellSize?: number;
+  /** Steepest walkable slope, degrees (default 40). */
+  maxSlopeDeg?: number;
+  /** Cells whose surface is BELOW this world y are unwalkable (sea level). */
+  minHeight?: number;
+}
+declare function buildTerrainNav(terrain: HeightSampler, opts?: TerrainNavOptions): TerrainNav;
+//#endregion
+//#region src/3d/terrain-nav-debug.d.ts
+/**
+* See what the enemies see: one node that paints every WALKABLE nav cell as a
+* translucent quad hugging the terrain surface. Add it while tuning
+* `cellSize`/`maxSlopeDeg`, drop it when the routes look right:
+*
+*   if (DEBUG_NAV) this.node.addChild(createNavDebugNode(this.nav));
+*
+* One InstancedMesh — a few thousand cells render as a single draw call.
+*/
+declare function createNavDebugNode(nav: TerrainNav, opts?: {
+  color?: string;
+  opacity?: number;
+  lift?: number;
+  name?: string;
+}): InstancedMesh3D;
+//#endregion
+export { Area3D, AssetStore3D, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, 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, 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 };