incanto 0.12.0 → 0.14.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-C_xf4gm9.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-B6D864oZ.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 { n as PathGrid, s as SpatialPose } from "./pathfinding-BSiXjd6W.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";
@@ -618,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"];
@@ -692,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
@@ -842,9 +888,13 @@ declare class Flowers3D extends Node3D {
   clustering: number;
   /** Gentle head-bob wind strength — 0 holds still. */
   sway: number;
-  /** Drape each plant onto a Terrain3D's surface so flowers root on the ground
-  * instead of a flat plane (lets ONE bed cover rolling terrain). */
-  drape: boolean;
+  /**
+  * null (the default) is AUTO: whenever the scene has a Terrain3D, instances
+  * root on it — flat ground behaves as before, rolling terrain just works.
+  * true forces it (keeps retrying until a terrain appears), false disables
+  * draping entirely.
+  */
+  drape: boolean | null;
   /** 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;
@@ -979,9 +1029,14 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   flowers: number;
   /** Placement seed — the field is identical across runs and machines. */
   seed: number;
-  /** Drape each instance onto a Terrain3D's surface so blades root on the
-  * ground instead of a flat plane (lets ONE field cover rolling terrain). */
-  drape: boolean;
+  /**
+  * Drape each instance onto a Terrain3D's surface so blades root on the
+  * ground instead of a flat plane. null (the default) is AUTO: whenever the
+  * scene has a Terrain3D, instances root on it — flat ground behaves as
+  * before, rolling terrain just works. true forces it (keeps retrying until
+  * a terrain appears), false disables draping entirely.
+  */
+  drape: boolean | null;
   /** 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;
@@ -1015,6 +1070,8 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   /** @internal Every InstancedMesh of the field: [quads] or [quads, quads90°]. */
   _fields(): InstancedMesh[];
   override update(dt: number): void;
+  /** Wind time/strength + the ≤4 character-bend slots (no-op before first build). */
+  private writeAnimationUniforms;
   override _syncObject3D(): void;
   /**
   * @internal Environment-sky sun hand-off (see {@link SunConsumer3D}): the
@@ -1076,73 +1133,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 {
@@ -1220,6 +1210,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`.
@@ -1293,6 +1386,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. */
@@ -1311,6 +1414,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). */
@@ -1352,7 +1461,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;
@@ -1715,11 +1832,14 @@ declare class Tree3D extends Node3D {
   /** Let leaves cast shadows. false keeps trunk/branch shadows but drops the
   * expensive alpha-cutout leaf shadow pass (the dappled floor) for big FPS. */
   leafShadows: boolean;
-  /** Drape the grove over a Terrain3D: each scattered instance roots at the
-  * ground height under it (not the node's single Y), so a patch on rolling or
-  * carved terrain never floats/buries. No effect on a count:1 tree placed by
-  * hand unless it sits off the ground. */
-  drape: boolean;
+  /**
+  * Drape the grove over a Terrain3D: each scattered instance roots at the
+  * ground height under it (not the node's single Y), so a patch on rolling
+  * or carved terrain never floats/buries. null (the default) is AUTO:
+  * whenever the scene has a Terrain3D the grove drapes onto it. true forces
+  * it (keeps retrying until a terrain appears), false disables draping.
+  */
+  drape: boolean | null;
   /** Node path to the Terrain3D to drape onto ('' = auto-find the first one). */
   terrain: string;
   /** Resolved drape target + the grove's world position, set per rebuild. */
@@ -2259,4 +2379,21 @@ interface TerrainNavOptions {
 }
 declare function buildTerrainNav(terrain: HeightSampler, opts?: TerrainNavOptions): TerrainNav;
 //#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 HeightSampler, 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 TerrainNav, type TerrainNavOptions, type TerrainTheme, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };
+//#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 };

package/dist/3d.js

@@ -1,7 +1,35 @@
-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-B2fewJUy.js";
-import { A as PhysicsBody3D, C as Terrain3D, D as Joint3D, E as terrainThemeLayers, F as QUARTER_PITCH, I as cameraRelative, L as keyboardIntensity, M as StaticBody3D, N as Node3D, O as Area3D, R as movementState, S as Billboard3D, T as TERRAIN_THEMES, _ as resolveFlowerDensity, a as VoxelGrid3D, b as Camera3D, c as Particles3D, d as MeshInstance3D, f as DirectionalLight3D, g as Flowers3D, h as DENSITY_PRESETS, i as VOXEL_PALETTE, j as RigidBody3D, k as CharacterBody3D, l as ModelInstance3D, m as Foliage3D, n as Water3D, o as Tree3D, p as OmniLight3D, r as WATER_MAX_RIPPLES, s as Trail3D, t as registerNodes3D, u as LoftMesh3D, v as FLOWER_VARIETIES, w as DEFAULT_TERRAIN_TEXTURE_BASE, x as BoneAttachment3D, y as CharacterController3D, z as rigPose } from "./register-ysLR3WQS.js";
+import { t as IncantoError } from "./errors-BpWbnbb_.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-OSntcIiM.js";
+import { A as Area3D, B as movementState, C as BoneAttachment3D, D as TERRAIN_THEMES, E as DEFAULT_TERRAIN_TEXTURE_BASE, F as Node3D, L as QUARTER_PITCH, M as PhysicsBody3D, N as RigidBody3D, O as terrainThemeLayers, P as StaticBody3D, R as cameraRelative, S as BoneLookAt3D, T as Terrain3D, V as rigPose, _ as Flowers3D, a as VoxelGrid3D, b as CharacterController3D, c as Particles3D, d as DirectionalLight3D, f as OmniLight3D, g as DENSITY_PRESETS, h as Foliage3D, i as VOXEL_PALETTE, j as CharacterBody3D, k as Joint3D, l as ModelInstance3D, m as MeshInstance3D, n as Water3D, o as Tree3D, p as InstancedMesh3D, r as WATER_MAX_RIPPLES, s as Trail3D, t as registerNodes3D, u as LoftMesh3D, v as resolveFlowerDensity, w as Billboard3D, x as Camera3D, y as FLOWER_VARIETIES, z as keyboardIntensity } from "./register-C9-16x_t.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CroQPEER.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-RLNaxRyw.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-D_kUdOjr.js";
+//#region src/3d/environment-runtime.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
+*/
+function setEnvironment3D(engine, patch) {
+	const scene = engine.scene;
+	if (!scene) throw new IncantoError("BAD_FORMAT", "setEnvironment3D: the engine has no scene.");
+	const merged = { ...scene.environment ?? {} };
+	for (const [key, value] of Object.entries(patch)) if (value === null) delete merged[key];
+	else if (typeof value === "object" && !Array.isArray(value) && typeof merged[key] === "object" && merged[key] !== null && !Array.isArray(merged[key])) merged[key] = {
+		...merged[key],
+		...value
+	};
+	else merged[key] = value;
+	parseEnvironment3D(merged);
+	scene.environment = merged;
+}
+//#endregion
 //#region src/3d/terrain-nav.ts
 function buildTerrainNav(terrain, opts) {
 	const cellSize = opts?.cellSize ?? 2;
@@ -71,4 +99,46 @@ const CORNERS = [
 	[-1, -1]
 ];
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, StaticBody3D, TERRAIN_THEMES, Terrain3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, buildTerrainNav, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };
+//#region src/3d/terrain-nav-debug.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.
+*/
+function createNavDebugNode(nav, opts) {
+	const node = new InstancedMesh3D(opts?.name ?? "__navDebug");
+	node.mesh = "plane";
+	node.size = [
+		nav.cellSize * .9,
+		1,
+		nav.cellSize * .9
+	];
+	node.material = {
+		color: opts?.color ?? "#37ff8b",
+		emissive: opts?.color ?? "#37ff8b",
+		emissiveIntensity: .5,
+		opacity: opts?.opacity ?? .3,
+		roughness: 1,
+		depthWrite: false
+	};
+	node.renderOrder = 50;
+	const lift = opts?.lift ?? .08;
+	const rows = [];
+	for (let cy = 0; cy < nav.grid.height; cy++) for (let cx = 0; cx < nav.grid.width; cx++) {
+		if (nav.grid.solid(cx, cy)) continue;
+		const [x, y, z] = nav.toWorld(cx, cy);
+		rows.push([
+			x,
+			y + lift,
+			z
+		]);
+	}
+	node.transforms = rows;
+	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, 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 };

package/dist/{behavior-Bod1AyJS.d.ts → behavior-CPibUfnH.d.ts}

@@ -693,8 +693,10 @@ declare class Scene {
   readonly dimension: "2d" | "3d" | undefined;
   readonly root: Node;
   readonly tree: SceneTree;
-  /** Scene-level rendering environment (read by renderer adapters). */
-  readonly environment: JsonObject | undefined;
+  /** Scene-level rendering environment (read by renderer adapters EVERY
+  *  frame, cheap when unchanged) — mutable so runtime look changes
+  *  (setEnvironment3D, DayNight) are just writes to this object. */
+  environment: JsonObject | undefined;
   /** Asset declarations (consumed by renderer/asset layers, `$key` references). */
   readonly assets: Record<string, JsonObject> | undefined;
   /** Named constant values (`{"@const": "NAME"}` prop references resolve to these). */

package/dist/{create-game-C_xf4gm9.js → create-game-Ct86zczq.js}

@@ -1,12 +1,12 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { _ as registerBehavior, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-B4OEXDZ8.js";
-import { l as AudioPlayer, u as Engine } from "./register-DJZXxwAn.js";
+import { _ as registerBehavior, n as loadScene, o as computeViewport, s as resolveViewport } 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 { n as registerGameplayBehaviors } from "./gameplay-Dn3yidJw.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-BD6zgrv_.js";
+import { n as registerGameplayBehaviors } from "./gameplay-sSqrUcnz.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-Djwckzgx.js";
 import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
-import { n as enablePhysics2D } from "./physics-2d-B6D864oZ.js";
+import { n as enablePhysics2D } from "./physics-2d-BiIdl51r.js";
 import { Box3, BufferAttribute, BufferGeometry, Color, LineBasicMaterial, LineSegments, LinearFilter, NearestFilter, OrthographicCamera, Raycaster, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
 //#region src/2d/assets.ts
 /**