incanto 0.7.1 → 0.8.0

package/bin/incanto-check.mjs

@@ -71,7 +71,7 @@ if (files.length === 0) {
   process.exit(1);
 }
 
-const { validateScene } = await import(pathToFileURL(join(DIST, 'test.js')).href);
+const { auditScene, validateScene } = await import(pathToFileURL(join(DIST, 'test.js')).href);
 
 const results = files.map((file) => {
   let json;
@@ -84,7 +84,7 @@ const results = files.map((file) => {
     strictBehaviors: args.strict,
     resolveScene: (p) => JSON.parse(readFileSync(resolve(dirname(file), p), 'utf-8')),
   });
-  if (res.ok) return { file, ok: true };
+  if (res.ok) return { file, ok: true, warnings: auditScene(json) };
   return {
     file,
     ok: false,
@@ -99,8 +99,10 @@ if (args.json) {
   console.log(JSON.stringify({ ok: failed.length === 0, results }, null, 2));
 } else {
   for (const r of results) {
-    if (r.ok) console.log(`  ok  ${r.file}`);
-    else console.log(`FAIL  ${r.file}\n      [${r.code}] ${r.message}`);
+    if (r.ok) {
+      console.log(`  ok  ${r.file}`);
+      for (const w of r.warnings ?? []) console.log(`      warn: ${w}`);
+    } else console.log(`FAIL  ${r.file}\n      [${r.code}] ${r.message}`);
   }
   console.log(`\n${results.length - failed.length}/${results.length} scene(s) valid`);
 }

package/dist/2d.d.ts

@@ -1,6 +1,6 @@
 import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { C as RendererStats, S as GameStats, Z as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-q3cejJgs.js";
-import { t as LoadSceneOptions } from "./loader-DnLMMRy8.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 { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
@@ -559,6 +559,66 @@ declare class Particles2D extends Node2D {
   override _syncObject2D(assets: AssetStore2D | null): void;
 }
 //#endregion
+//#region src/2d/nodes/tile-map-2d.d.ts
+/**
+* A whole tile level as ONE node — grid render in a single draw call plus
+* greedy-merged static colliders. Author the level as rows of characters:
+*
+*   { "name": "Level", "type": "TileMap2D", "props": {
+*       "texture": "$tiles", "tileSize": 32,
+*       "cells": [
+*         "..................",
+*         "......111.........",
+*         "000000000000000000"
+*       ],
+*       "solid": [0, 1] } }
+*
+* `.` / space = empty, digits 0-9 = atlas tile index, other chars map through
+* `legend` (e.g. `{"G": 12}`). The atlas is read left-to-right, top-to-bottom
+* in `tileSize` squares. Tiles listed in `solid` become static colliders,
+* greedy-merged into a few rectangles (hundreds of cells → a handful of
+* bodies). Cell (0,0) renders with its TOP-LEFT on this node's origin.
+*/
+declare class TileMap2D extends Node2D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  texture: string;
+  tileSize: number;
+  columns: number;
+  private _cells;
+  private _legend;
+  private _solid;
+  /** Rebuild flags — raised when the map-shaping props are REPLACED. */
+  private geometryDirty;
+  private collidersDirty;
+  /** Replace the whole array to change the map (mutations are not watched). */
+  get cells(): (string | number[])[];
+  set cells(value: (string | number[])[]);
+  get legend(): Record<string, number>;
+  set legend(value: Record<string, number>);
+  get solid(): number[];
+  set solid(value: number[]);
+  opacity: number;
+  private tileMesh;
+  private builtColumns;
+  private builtRows;
+  /** Loader hook: bad cells fail at LOAD (unknown chars), not at render. */
+  static validateJson(node: Node): void;
+  /** The parsed index grid (test/tooling hook). */
+  grid(): number[][];
+  override onReady(): void;
+  override update(_dt: number): void;
+  private rebuildColliders;
+  /** @internal The drawable mesh (lazily created under the backing object). */
+  _mesh(): Mesh;
+  override _syncObject2D(assets: AssetStore2D | null): void;
+  /** One quad per visible tile, atlas UVs — a single draw call for the level. */
+  private buildGeometry;
+  /** Test hook: rendered tile count (quads in the built geometry). */
+  get renderedTileCount(): number;
+  override free(): void;
+}
+//#endregion
 //#region src/2d/nodes/ui-layer.d.ts
 declare const ANCHORS: readonly ["top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right"];
 type UIAnchor = (typeof ANCHORS)[number];
@@ -720,4 +780,32 @@ declare function syncTree2D(root: Node, world: Scene, ui: Scene, assets: AssetSt
   ignoreStatic?: boolean;
 }): Sync2DResult;
 //#endregion
-export { AnimatedSprite2D, type AnimationDef, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Joint2D, type JointType2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, type UIAnchor, UILayer, createGame2D, enablePhysics2D, registerNodes2D, spriteFromLibraryMeta, syncTree2D };
+//#region src/2d/tilemap-grid.d.ts
+/**
+* Pure tile-grid logic for TileMap2D — no three, unit-testable in node.
+* Grids are `number[][]` of atlas tile indices, `-1` = empty.
+*/
+interface TileRect {
+  /** Cell coords (col, row) of the rect's top-left. */
+  x: number;
+  y: number;
+  /** Size in cells. */
+  w: number;
+  h: number;
+}
+/**
+* Normalize the `cells` prop into an index grid. Two author formats:
+* - string rows: `"." `/`" "` = empty, digits `0-9` = tile index, anything
+*   else must be in `legend` (char → index). Unknown chars HARD-fail.
+* - number rows: passed through (`-1` = empty).
+* Ragged rows are right-padded with empty.
+*/
+declare function parseCells(cells: readonly (string | readonly number[])[], legend: Record<string, number>): number[][];
+/**
+* Greedy rectangle merge over the solid cells: maximal horizontal runs,
+* extended downward while the identical run repeats. A platform level's
+* hundreds of solid tiles collapse to a handful of colliders.
+*/
+declare function mergeSolidRects(grid: readonly (readonly number[])[], solid: Set<number>): TileRect[];
+//#endregion
+export { AnimatedSprite2D, type AnimationDef, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Joint2D, type JointType2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, TileMap2D, type TileRect, type UIAnchor, UILayer, createGame2D, enablePhysics2D, mergeSolidRects, parseCells, registerNodes2D, spriteFromLibraryMeta, syncTree2D };

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-DuDkqnjl.js";
-import { a as ColorRect2D, c as AnimatedSprite2D, d as Area2D, f as CharacterBody2D, g as Node2D, h as StaticBody2D, i as Label, l as Sprite2D, m as RigidBody2D, n as UILayer, o as CharacterController2D, p as PhysicsBody2D, r as Particles2D, s as Camera2D, t as registerNodes2D, u as Joint2D } from "./register-Cl3pAxX-.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CZM5Y90X.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-BNDSbhy-.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-Cqjxrfq0.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-q2N362ph.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset
@@ -41,4 +41,4 @@ function spriteFromLibraryMeta(meta, opts) {
 	};
 }
 //#endregion
-export { AnimatedSprite2D, Area2D, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, Joint2D, Label, Node2D, Particles2D, Physics2D, PhysicsBody2D, Renderer2D, RigidBody2D, Sprite2D, StaticBody2D, UILayer, createGame2D, enablePhysics2D, registerNodes2D, spriteFromLibraryMeta, syncTree2D };
+export { AnimatedSprite2D, Area2D, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, Joint2D, Label, Node2D, Particles2D, Physics2D, PhysicsBody2D, Renderer2D, RigidBody2D, Sprite2D, StaticBody2D, TileMap2D, UILayer, createGame2D, enablePhysics2D, mergeSolidRects, parseCells, registerNodes2D, spriteFromLibraryMeta, syncTree2D };

package/dist/3d.d.ts

@@ -1,8 +1,8 @@
 import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { C as RendererStats, S as GameStats, Z as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-q3cejJgs.js";
-import { t as LoadSceneOptions } from "./loader-DnLMMRy8.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 { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
-import { r as SpatialPose } from "./audio-player-C3bH_eZ5.js";
+import { r as SpatialPose } from "./audio-player-Dyjg5k92.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";
@@ -696,6 +696,13 @@ declare class CharacterController3D extends Node3D {
   * character facing away from the camera until it first moves).
   */
   skinYawOffset: number;
+  /**
+  * Movement-state → animation asset map, applied to the `skinPath` model
+  * directly — no CharacterAnimator behavior needed:
+  *   "animations": { "idle": "$idle", "run": "$run", "fastRun": "$sprint",
+  *                   "walk": "$walk", "airborne": "$jump" }
+  */
+  animations: Record<string, string>;
   /** Camera yaw/pitch in radians (mouse look mutates these). */
   yaw: number;
   pitch: number;
@@ -1547,6 +1554,38 @@ declare class Terrain3D extends Node3D {
   override free(): void;
 }
 //#endregion
+//#region src/3d/nodes/trail-3d.d.ts
+/**
+* A fading ribbon behind whatever this node is parented to — wingtip trails,
+* sword arcs, tyre streaks. Records the node's world position over `seconds`
+* and renders a camera-facing strip that tapers and fades to the tail.
+*
+*   { "name": "WingTrail", "type": "Trail3D",
+*     "props": { "width": 0.4, "color": "#dddddd", "seconds": 0.8 } }
+*
+* `emitting: false` stops laying new ribbon (the old tail still fades out).
+*/
+declare class Trail3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  width: number;
+  color: string;
+  opacity: number;
+  seconds: number;
+  emitting: boolean;
+  additive: boolean;
+  minDistance: number;
+  private readonly points;
+  private clock;
+  private mesh;
+  private lastColor;
+  protected override _createObject3D(): Object3D;
+  override update(dt: number): void;
+  _onRender3D(ctx: RenderContext3D): void;
+  /** Test hook: recorded point count. */
+  get pointCount(): number;
+}
+//#endregion
 //#region src/3d/vegetation/tree-blueprint.d.ts
 /**
 * Tree3D construction recipes — the pure half of the procedural trees.
@@ -2116,4 +2155,4 @@ interface WalkState {
   ignoreStatic: boolean;
 }
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, type BillboardGroupMode, 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, 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 };
+export { Area3D, AssetStore3D, Billboard3D, type BillboardGroupMode, 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 };

package/dist/3d.js

@@ -1,5 +1,5 @@
-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-rFulaS3s.js";
-import { A as StaticBody3D, C as TERRAIN_THEMES, D as CharacterBody3D, E as Area3D, F as keyboardIntensity, I as movementState, L as rigPose, N as QUARTER_PITCH, O as PhysicsBody3D, P as cameraRelative, S as DEFAULT_TERRAIN_TEXTURE_BASE, T as Joint3D, _ as FLOWER_VARIETIES, a as VoxelGrid3D, b as Billboard3D, c as ModelInstance3D, d as DirectionalLight3D, f as OmniLight3D, g as resolveFlowerDensity, h as Flowers3D, i as VOXEL_PALETTE, j as Node3D, k as RigidBody3D, l as LoftMesh3D, m as DENSITY_PRESETS, n as Water3D, o as Tree3D, p as Foliage3D, r as WATER_MAX_RIPPLES, s as Particles3D, t as registerNodes3D, u as MeshInstance3D, v as CharacterController3D, w as terrainThemeLayers, x as Terrain3D, y as Camera3D } from "./register-CpXcMiEk.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-66c4iYJE.js";
+import { A as RigidBody3D, C as DEFAULT_TERRAIN_TEXTURE_BASE, D as Area3D, E as Joint3D, F as cameraRelative, I as keyboardIntensity, L as movementState, M as Node3D, O as CharacterBody3D, P as QUARTER_PITCH, R as rigPose, S as Terrain3D, T as terrainThemeLayers, _ 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 StaticBody3D, k as PhysicsBody3D, 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 TERRAIN_THEMES, x as Billboard3D, y as CharacterController3D } from "./register-Cbs7QxoV.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CroQPEER.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DT5e8izo.js";
-export { Area3D, AssetStore3D, Billboard3D, 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, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CvHr31d4.js";
+export { Area3D, AssetStore3D, Billboard3D, 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, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };

package/dist/{audio-player-C3bH_eZ5.d.ts → audio-player-Dyjg5k92.d.ts}

@@ -1,4 +1,4 @@
-import { M as Listener, Z as Node, l as PropSchema } from "./behavior-q3cejJgs.js";
+import { $ as Node, P as Listener, l as PropSchema } from "./behavior-Bod1AyJS.js";
 
 //#region src/core/nodes/audio-player.d.ts
 /**

package/dist/audit-C6rMyict.js

@@ -0,0 +1,58 @@
+//#region src/core/audit.ts
+const ANIMATED_TYPES = new Set([
+	"Particles2D",
+	"Particles3D",
+	"Water3D",
+	"AnimatedSprite2D",
+	"AnimatedSprite3D",
+	"Camera2D",
+	"Camera3D"
+]);
+const BODY_TYPES = new Set([
+	"StaticBody2D",
+	"RigidBody2D",
+	"Area2D",
+	"CharacterBody2D",
+	"StaticBody3D",
+	"RigidBody3D",
+	"Area3D",
+	"CharacterBody3D"
+]);
+const HUD_WIDGETS = new Set([
+	"UiText",
+	"UiBar",
+	"UiBanner",
+	"UiButton",
+	"UiDialogue"
+]);
+/** Human-readable warnings (empty = clean). Pure JSON walk, no registry. */
+function auditScene(scene) {
+	const warnings = [];
+	const root = scene.root;
+	if (!root) return warnings;
+	let currentCameras = 0;
+	let cameras = 0;
+	const walk = (node, path, insideHud, staticRoot) => {
+		const type = node.type ?? "";
+		const props = node.props ?? {};
+		if (type === "Camera2D" || type === "Camera3D") {
+			cameras += 1;
+			if (props.current === true) currentCameras += 1;
+		}
+		if (BODY_TYPES.has(type)) {
+			const collider = props.collider;
+			if (!collider || collider.shape === void 0) warnings.push(`${path}: ${type} has no collider — physics will skip it (add "collider": { "shape": ... }).`);
+		}
+		if (HUD_WIDGETS.has(type) && !insideHud) warnings.push(`${path}: ${type} works only as a descendant of a HudLayer — it will not render.`);
+		if (staticRoot && ANIMATED_TYPES.has(type)) warnings.push(`${path}: ${type} is frozen inside static subtree '${staticRoot}' — it will not animate/update on screen.`);
+		const nextStatic = staticRoot ?? (props.static === true ? node.name ?? path : null);
+		const nextHud = insideHud || type === "HudLayer";
+		for (const child of node.children ?? []) walk(child, `${path}/${child.name ?? "?"}`, nextHud, nextStatic);
+	};
+	walk(root, root.name ?? "root", false, root.props?.static === true ? root.name ?? "root" : null);
+	if (cameras > 0 && currentCameras === 0) warnings.push("no camera has \"current\": true — the screen renders from a default view, probably not what you framed.");
+	if (currentCameras > 1) warnings.push(`${currentCameras} cameras claim "current": true — only the first found wins.`);
+	return warnings;
+}
+//#endregion
+export { auditScene as t };

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

@@ -437,6 +437,30 @@ declare function spatialGain(distance: number, params: SpatialParams): number;
 */
 declare function spatialPan(sourcePos: Vec3, listener: Listener): number;
 //#endregion
+//#region src/core/audio/voice.d.ts
+/**
+* Continuous parametric voices — the engine hum, wind rush and thruster
+* roar that one-shot SFX can't do (racing-3d hand-built exactly this graph).
+* A voice is a small WebAudio patch you retune every frame:
+*
+*   const voice = engine.sfx.startVoice('engine');
+*   voice.set({ pitch: rpm / 4000, volume: throttle * 0.6 });
+*   voice.stop();                       // fades out and frees the graph
+*
+* Headless (no AudioContext) the handle is inert — same call sites, no ifs.
+*/
+type VoicePreset = "engine" | "wind" | "hum" | "noise";
+interface Voice {
+  /** Retune live. pitch 1 = the preset's base; volume 0..1. */
+  set(params: {
+    pitch?: number;
+    volume?: number;
+  }): void;
+  /** Fade out over `seconds` (default 0.15) and free the nodes. */
+  stop(seconds?: number): void;
+  readonly stopped: boolean;
+}
+//#endregion
 //#region src/core/audio/webaudio-sfx.d.ts
 /** A spatial emitter: where the sound is + where the listener is. */
 interface SpatialPlay {
@@ -469,6 +493,12 @@ declare class SfxEngine {
   /** True once a backend is present (lazily created on first use). */
   get available(): boolean;
   private ensure;
+  /**
+  * Start a continuous parametric voice (engine hum, wind, thrusters) —
+  * retune it per frame with `voice.set({ pitch, volume })`, `stop()` when
+  * done. Headless returns an inert handle (same call sites, no ifs).
+  */
+  startVoice(preset: VoicePreset, gain?: number): Voice;
   /** Resume a gesture-suspended context (wired to the first user gesture). */
   unlock(): void;
   /**
@@ -920,4 +950,4 @@ declare function registeredBehaviors(): string[];
 /** Test isolation helper. */
 declare function clearBehaviors(): void;
 //#endregion
-export { Signal as $, SfxPlayOptions as A, SFX_PRESET_NAMES as B, RendererStats as C, LogManager as D, LogLevel as E, SpatialParams as F, MusicBackend as G, SfxWave as H, Vec3 as I, PlayMusicOptions as J, MusicManager as K, spatialGain as L, Listener as M, ROLLOFF_MODELS as N, InputMap as O, RolloffModel as P, NodeLifecycle as Q, spatialPan as R, GameStats as S, LogEntry as T, SynthOptions as U, SfxParams as V, synthSfx as W, BusName as X, AudioBuses as Y, Node as Z, registeredTypes as _, registerBehavior as a, Scheduler as b, PropDef as c, createNode as d, SignalListener as et, getNodeSchema as f, registerNode as g, mergeStaticSignals as h, getBehavior as i, isAudioContextAvailable as j, SfxEngine as k, PropSchema as l, getNodeType as m, BehaviorCtor as n, registeredBehaviors as o, getNodeSignals as p, MusicTrack as q, clearBehaviors as r, NodeCtor as s, Behavior as t, SceneTree as tt, clearRegistry as u, Engine as v, Scene as w, EngineStats as x, EngineOptions as y, SFX_PRESETS as z };
+export { Node as $, SfxPlayOptions as A, spatialPan as B, RendererStats as C, LogManager as D, LogLevel as E, ROLLOFF_MODELS as F, SynthOptions as G, SFX_PRESET_NAMES as H, RolloffModel as I, MusicManager as J, synthSfx as K, SpatialParams as L, Voice as M, VoicePreset as N, InputMap as O, Listener as P, BusName as Q, Vec3 as R, GameStats as S, LogEntry as T, SfxParams as U, SFX_PRESETS as V, SfxWave as W, PlayMusicOptions as X, MusicTrack as Y, AudioBuses as Z, registeredTypes as _, registerBehavior as a, Scheduler as b, PropDef as c, createNode as d, NodeLifecycle as et, getNodeSchema as f, registerNode as g, mergeStaticSignals as h, getBehavior as i, isAudioContextAvailable as j, SfxEngine as k, PropSchema as l, getNodeType as m, BehaviorCtor as n, SignalListener as nt, registeredBehaviors as o, getNodeSignals as p, MusicBackend as q, clearBehaviors as r, SceneTree as rt, NodeCtor as s, Behavior as t, Signal as tt, clearRegistry as u, Engine as v, Scene as w, EngineStats as x, EngineOptions as y, spatialGain as z };

package/dist/{create-game-rFulaS3s.js → create-game-66c4iYJE.js}

@@ -1,13 +1,12 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { _ as registerBehavior, n as loadScene } from "./loader-B4OEXDZ8.js";
-import { s as Engine } from "./particle-sim-m3CdTGSl.js";
+import { l as AudioPlayer, u as Engine } from "./register-DRPIjrKG.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { s as AudioPlayer } from "./register-Dl_ixIJe.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
-import { n as registerGameplayBehaviors } from "./gameplay-CDFgSG6z.js";
+import { n as registerGameplayBehaviors } from "./gameplay-DPMgZk9W.js";
 import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
-import { O as PhysicsBody3D, c as ModelInstance3D, d as DirectionalLight3D, j as Node3D, t as registerNodes3D, y as Camera3D } from "./register-CpXcMiEk.js";
-import { n as enablePhysics3D } from "./physics-3d-DT5e8izo.js";
+import { M as Node3D, b as Camera3D, f as DirectionalLight3D, k as PhysicsBody3D, l as ModelInstance3D, t as registerNodes3D } from "./register-Cbs7QxoV.js";
+import { n as enablePhysics3D } from "./physics-3d-CvHr31d4.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/{create-game-DuDkqnjl.js → create-game-BNDSbhy-.js}

@@ -1,13 +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 { s as Engine } from "./particle-sim-m3CdTGSl.js";
+import { l as AudioPlayer, u as Engine } from "./register-DRPIjrKG.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { s as AudioPlayer } from "./register-Dl_ixIJe.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
-import { n as registerGameplayBehaviors } from "./gameplay-CDFgSG6z.js";
-import { g as Node2D, n as UILayer, p as PhysicsBody2D, s as Camera2D, t as registerNodes2D } from "./register-Cl3pAxX-.js";
+import { n as registerGameplayBehaviors } from "./gameplay-DPMgZk9W.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-Cqjxrfq0.js";
 import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
-import { n as enablePhysics2D } from "./physics-2d-CZM5Y90X.js";
+import { n as enablePhysics2D } from "./physics-2d-q2N362ph.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
 /**

package/dist/debug.d.ts

@@ -1,4 +1,4 @@
-import { C as RendererStats, E as LogLevel, v as Engine } from "./behavior-q3cejJgs.js";
+import { C as RendererStats, E as LogLevel, v as Engine } from "./behavior-Bod1AyJS.js";
 
 //#region src/debug/panel.d.ts
 /** Minimal document surface the overlay needs (injectable for tests). */

package/dist/{errors-BMFaY68Q.d.ts → errors-1dXlIwoR.d.ts}

@@ -1,3 +1,9 @@
+import { s as JsonObject } from "./schema-CcoWb32N.js";
+
+//#region src/core/audit.d.ts
+/** Human-readable warnings (empty = clean). Pure JSON walk, no registry. */
+declare function auditScene(scene: JsonObject): string[];
+//#endregion
 //#region src/core/errors.d.ts
 /**
 * Stable error codes for every hard failure in the engine.
@@ -30,4 +36,4 @@ declare class IncantoError extends Error {
   constructor(code: IncantoErrorCode, message: string, details?: IncantoErrorDetails);
 }
 //#endregion
-export { IncantoErrorCode as n, IncantoErrorDetails as r, IncantoError as t };
+export { auditScene as i, IncantoErrorCode as n, IncantoErrorDetails as r, IncantoError as t };

package/dist/{gameplay-CDFgSG6z.js → gameplay-DPMgZk9W.js}

@@ -480,6 +480,39 @@ function restartScene(engine) {
 	engine.setScene(loadScene(jsonClone(source)));
 }
 /**
+* Swap to another scene behind a black fade (title→game→next level).
+* Headless (no DOM) the swap is immediate. Restores timeScale to 1.
+*/
+function goToScene(engine, sceneJson, opts) {
+	const fade = opts?.fadeSeconds ?? .4;
+	const swap = () => {
+		engine.timeScale = 1;
+		engine.setScene(loadScene(jsonClone(sceneJson)));
+	};
+	if (typeof document === "undefined" || fade <= 0) {
+		swap();
+		return;
+	}
+	const id = "incanto-scene-fade";
+	let el = document.getElementById(id);
+	if (!el) {
+		el = document.createElement("div");
+		el.id = id;
+		el.style.cssText = "position:fixed;inset:0;z-index:10001;background:#000;opacity:0;pointer-events:none;";
+		document.body.appendChild(el);
+	}
+	el.style.transition = `opacity ${fade / 2}s`;
+	el.style.opacity = "1";
+	setTimeout(() => {
+		swap();
+		const out = document.getElementById(id);
+		if (out) {
+			out.style.opacity = "0";
+			setTimeout(() => out.remove(), fade * 500 + 60);
+		}
+	}, fade * 500 + 30);
+}
+/**
 * The win/lose/restart state machine 6+ examples hand-rolled as `over`/`win`
 * booleans. Attach to any node (the scene root is natural):
 *
@@ -531,6 +564,11 @@ var GameFlow = class extends Behavior {
 		this.thaw();
 		restartScene(this.engine);
 	}
+	/** Fade to another scene (next level, back to title). */
+	goToScene(sceneJson, opts) {
+		this.thaw();
+		goToScene(this.engine, sceneJson, opts);
+	}
 	transition(state, text, color) {
 		if (this.state === "gameover" || this.state === "won") return;
 		this.state = state;
@@ -986,6 +1024,74 @@ var Oscillate = class extends Behavior {
 	}
 };
 //#endregion
+//#region src/gameplay/path-follow.ts
+/**
+* Walk a list of waypoints at a constant speed, then stop — the delivery
+* end of `findPath`:
+*
+*   const cells = findPath(grid, start, goal);
+*   (npc.behavior as PathFollow).setPath(cells.map(([cx, cy]) => [cx * TILE, cy * TILE]));
+*
+* Waypoints are world positions in the node's own units (2D px / 3D m; use
+* [x, y] or [x, y, z] to match the node). Emits `waypointReached(index)`
+* per point and `arrived()` at the end. `loop: true` patrols the ring.
+*/
+var PathFollow = class extends Behavior {
+	static signals = ["waypointReached", "arrived"];
+	static props = {
+		speed: { default: 120 },
+		loop: { default: false }
+	};
+	/** Units per second (px in 2D, meters in 3D). */
+	speed = 120;
+	loop = false;
+	waypoints = [];
+	index = 0;
+	/** True while there is somewhere left to go. */
+	get moving() {
+		return this.index < this.waypoints.length;
+	}
+	setPath(waypoints) {
+		this.waypoints = waypoints.map((w) => [...w]);
+		this.index = 0;
+	}
+	/** Stop in place (keeps the node where it is). */
+	stop() {
+		this.waypoints = [];
+		this.index = 0;
+	}
+	update(dt) {
+		if (!this.moving) return;
+		const node = requirePosition(this);
+		let budget = this.speed * dt;
+		while (budget > 0 && this.index < this.waypoints.length) {
+			const target = this.waypoints[this.index];
+			const step = moveToward(node.position, target, budget);
+			const travelled = distanceBetween(node.position, step.position);
+			node.position = step.position;
+			budget -= travelled;
+			if (step.reached) {
+				this.node.emit("waypointReached", this.index);
+				this.index += 1;
+				if (this.index >= this.waypoints.length) if (this.loop && this.waypoints.length > 1) this.index = 0;
+				else {
+					this.node.emit("arrived");
+					return;
+				}
+			} else return;
+		}
+	}
+};
+function distanceBetween(a, b) {
+	let sum = 0;
+	const n = Math.max(a.length, b.length);
+	for (let i = 0; i < n; i++) {
+		const d = (b[i] ?? 0) - (a[i] ?? 0);
+		sum += d * d;
+	}
+	return Math.sqrt(sum);
+}
+//#endregion
 //#region src/gameplay/patrol.ts
 /**
 * Walk the node along a fixed list of waypoints at constant speed — guards,
@@ -1739,6 +1845,7 @@ var ZombieAI = class extends Behavior {
 const GAMEPLAY_BEHAVIORS = {
 	CameraShake,
 	GameFlow,
+	PathFollow,
 	Health,
 	Lifetime,
 	ScoreKeeper,
@@ -1767,4 +1874,4 @@ function registerGameplayBehaviors(opts) {
 	for (const [name, ctor] of Object.entries(GAMEPLAY_BEHAVIORS)) registerBehavior(name, ctor, { replace });
 }
 //#endregion
-export { Health as C, DamageOnContact as S, Chase as T, screenFlash as _, Wander as a, restartScene as b, Projectile as c, Oscillate as d, MoveTo as f, hitStop as g, Cooldown as h, WaveSpawner as i, Pickup as l, CameraShake as m, registerGameplayBehaviors as n, Spawner as o, Lifetime as p, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Patrol as u, Interactable as v, Collector as w, FollowCamera as x, GameFlow as y };
+export { FollowCamera as C, Chase as D, Collector as E, restartScene as S, Health as T, hitStop as _, Wander as a, GameFlow as b, Projectile as c, PathFollow as d, Oscillate as f, Cooldown as g, CameraShake as h, WaveSpawner as i, Pickup as l, Lifetime as m, registerGameplayBehaviors as n, Spawner as o, MoveTo as p, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Patrol as u, screenFlash as v, DamageOnContact as w, goToScene as x, Interactable as y };

package/dist/gameplay.d.ts

@@ -1,5 +1,5 @@
-import { c as JsonValue } from "./schema-CcoWb32N.js";
-import { Z as Node, l as PropSchema, n as BehaviorCtor, t as Behavior, v as Engine } from "./behavior-q3cejJgs.js";
+import { c as JsonValue, s as JsonObject } from "./schema-CcoWb32N.js";
+import { $ as Node, l as PropSchema, n as BehaviorCtor, t as Behavior, v as Engine } from "./behavior-Bod1AyJS.js";
 
 //#region src/gameplay/chase.d.ts
 /**
@@ -541,6 +541,13 @@ declare class ZombieAI extends Behavior {
 declare function restartScene(engine: Engine): void;
 type GameFlowState = "playing" | "paused" | "gameover" | "won";
 /**
+* Swap to another scene behind a black fade (title→game→next level).
+* Headless (no DOM) the swap is immediate. Restores timeScale to 1.
+*/
+declare function goToScene(engine: Engine, sceneJson: JsonObject, opts?: {
+  fadeSeconds?: number;
+}): void;
+/**
 * The win/lose/restart state machine 6+ examples hand-rolled as `over`/`win`
 * booleans. Attach to any node (the scene root is natural):
 *
@@ -573,6 +580,10 @@ declare class GameFlow extends Behavior {
   pause(): void;
   resume(): void;
   restart(): void;
+  /** Fade to another scene (next level, back to title). */
+  goToScene(sceneJson: JsonObject, opts?: {
+    fadeSeconds?: number;
+  }): void;
   private transition;
   private freeze;
   private thaw;
@@ -639,6 +650,36 @@ declare function screenFlash(color?: string, opacity?: number, seconds?: number)
 */
 declare function hitStop(engine: Engine, seconds?: number): void;
 //#endregion
+//#region src/gameplay/path-follow.d.ts
+/**
+* Walk a list of waypoints at a constant speed, then stop — the delivery
+* end of `findPath`:
+*
+*   const cells = findPath(grid, start, goal);
+*   (npc.behavior as PathFollow).setPath(cells.map(([cx, cy]) => [cx * TILE, cy * TILE]));
+*
+* Waypoints are world positions in the node's own units (2D px / 3D m; use
+* [x, y] or [x, y, z] to match the node). Emits `waypointReached(index)`
+* per point and `arrived()` at the end. `loop: true` patrols the ring.
+*/
+declare class PathFollow extends Behavior {
+  static readonly signals: readonly string[];
+  static readonly props: Record<string, {
+    default: number | boolean;
+  }>;
+  /** Units per second (px in 2D, meters in 3D). */
+  speed: number;
+  loop: boolean;
+  private waypoints;
+  private index;
+  /** True while there is somewhere left to go. */
+  get moving(): boolean;
+  setPath(waypoints: readonly (readonly number[])[]): void;
+  /** Stop in place (keeps the node where it is). */
+  stop(): void;
+  override update(dt: number): void;
+}
+//#endregion
 //#region src/gameplay/index.d.ts
 /** Every built-in gameplay behavior, keyed by its registration name. */
 declare const GAMEPLAY_BEHAVIORS: Readonly<Record<string, BehaviorCtor>>;
@@ -651,4 +692,4 @@ declare function registerGameplayBehaviors(opts?: {
   replace?: boolean;
 }): void;
 //#endregion
-export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, hitStop, registerGameplayBehaviors, restartScene, screenFlash };
+export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, registerGameplayBehaviors, restartScene, screenFlash };