incanto 0.59.0 → 0.61.0

package/bin/incanto-check.mjs

@@ -8,6 +8,7 @@
  *   npx incanto-check src/game.scene.json   → specific files (or directories)
  *   npx incanto-check --json                → machine-readable report
  *   npx incanto-check --strict-behaviors    → unregistered script names fail too
+ *   npx incanto-check --strict-warnings     → a warning is a failure (CI, agents)
  *
  * Unregistered behaviors are STUBBED by default: structure-only validation
  * that needs no TypeScript. Sub-scene `instance` paths resolve relative to
@@ -25,6 +26,7 @@ function parseArgs(argv) {
   for (const a of argv) {
     if (a === '--json') args.json = true;
     else if (a === '--strict-behaviors') args.strict = true;
+    else if (a === '--strict-warnings') args.strictWarnings = true;
     else if (a === '--help' || a === '-h') args.help = true;
     else if (a.startsWith('--')) {
       console.error(`unknown flag: ${a}`);
@@ -36,7 +38,7 @@ function parseArgs(argv) {
 
 const args = parseArgs(process.argv.slice(2));
 if (args.help || args.invalid) {
-  console.log(`Usage: npx incanto-check [files|dirs...] [--json] [--strict-behaviors]
+  console.log(`Usage: npx incanto check [files|dirs...] [--json] [--strict-behaviors] [--strict-warnings]
 
 Validates *.scene.json files headlessly with the installed engine.
 With no arguments, scans the current directory recursively
@@ -155,6 +157,40 @@ if (files.length === 0) {
 
 const { auditScene, validateScene } = await import(pathToFileURL(join(DIST, 'test.js')).href);
 
+/**
+ * Every `strings` table in the corpus, unioned.
+ *
+ * Localization tables MERGE across scenes at runtime — a game's shared UI
+ * strings live in the scene it boots from — so auditing one file in isolation
+ * reported a key declared in the boot scene as "nothing declares" it, and told
+ * its author to add a string they already have. Checking a project means
+ * knowing what the project declares.
+ */
+const declaredElsewhere = {};
+/**
+ * Every asset the project declares.
+ *
+ * A scene a spawner instantiates resolves its `$ref`s against the HOST's
+ * `assets{}` — `remote-player.scene.json` names `$characters/base` and declares
+ * nothing itself, which is correct. Checked alone it cannot resolve; checked as
+ * part of its project it can.
+ */
+const declaredAssets = {};
+for (const file of files) {
+  try {
+    const doc = JSON.parse(readFileSync(file, 'utf-8'));
+    for (const [locale, entries] of Object.entries(doc?.strings ?? {})) {
+      if (typeof entries !== 'object' || entries === null) continue;
+      declaredElsewhere[locale] = { ...(declaredElsewhere[locale] ?? {}), ...entries };
+    }
+    for (const [key, entry] of Object.entries(doc?.assets ?? {})) {
+      if (typeof entry === 'object' && entry !== null) declaredAssets[key] ??= entry;
+    }
+  } catch {
+    /* a file that will not parse is reported below, on its own line */
+  }
+}
+
 const results = files.map((file) => {
   let json;
   try {
@@ -164,9 +200,16 @@ const results = files.map((file) => {
   }
   const res = validateScene(json, {
     strictBehaviors: args.strict,
+    declaredAssets,
     resolveScene: (p) => JSON.parse(readFileSync(resolve(dirname(file), p), 'utf-8')),
   });
-  if (res.ok) return { file, ok: true, warnings: [...auditScene(json), ...missingArt(file, json)] };
+  if (res.ok) {
+    return {
+      file,
+      ok: true,
+      warnings: [...auditScene(json, { declaredElsewhere }), ...missingArt(file, json)],
+    };
+  }
   return {
     file,
     ok: false,
@@ -177,6 +220,7 @@ const results = files.map((file) => {
 });
 
 const failed = results.filter((r) => !r.ok);
+const warned = results.reduce((n, r) => n + (r.warnings?.length ?? 0), 0);
 if (args.json) {
   console.log(JSON.stringify({ ok: failed.length === 0, results }, null, 2));
 } else {
@@ -186,10 +230,20 @@ if (args.json) {
       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`);
+  // Say the warning count on the summary line. A warning printed under an `ok`
+  // and a summary that never mentions it is a finding an agent scrolls past.
+  console.log(
+    `\n${results.length - failed.length}/${results.length} scene(s) valid` +
+      (warned > 0
+        ? `, ${warned} warning(s)${args.strictWarnings ? '' : ' — `--strict-warnings` to fail on them'}`
+        : ''),
+  );
 }
 // `exitCode`, never `process.exit()`: stdout to a PIPE is written
 // asynchronously, and exiting discards whatever has not flushed. A --json
 // report read by another program came back truncated — silently, and only
 // when piped, which is the only way a program reads it.
-process.exitCode = failed.length === 0 ? 0 : 1;
+// A warning is a finding, and a checker read by a CI step or an agent is read
+// through its EXIT CODE. Opt-in, because turning it on by default would fail
+// every project that has been living with one.
+process.exitCode = failed.length === 0 && !(args.strictWarnings && warned > 0) ? 0 : 1;

package/dist/2d.d.ts

@@ -1,10 +1,10 @@
-import { At as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-DWKTUzKI.js";
+import { P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-DsgayMsH.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
 import { r as FrameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-TvkRFbyL.js";
+import { t as LoadSceneOptions } from "./loader-DolLJWJn.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
-import { r as ParticleView, t as ParticleSim } from "./particle-sim-C5OfBbmU.js";
+import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-D5GJgb_x.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
 
@@ -701,6 +701,16 @@ declare class Label extends Node2D {
   font: string;
   /** 'left' | 'center' | 'right' — anchor of the text block on the node origin. */
   align: string;
+  /**
+  * 0..1, like `Sprite2D` and `ColorRect2D`.
+  *
+  * Label was the one 2D drawable without it, and the gap showed up through
+  * `FloatAway` — whose own doc names "a 2D `Label`" as a node it works on.
+  * `FloatAway` writes `opacity` when the node has one, so on a Label the
+  * number rose to full height at FULL opacity and then vanished in a single
+  * frame: the pop that behavior exists to avoid.
+  */
+  opacity: number;
   private quadMesh;
   private canvas;
   private lastKey;
@@ -1081,6 +1091,15 @@ interface UiSize {
 interface Sync2DScratch {
   visited: Set<Object3D>;
   cameras: Camera2D[];
+  emitters: Array<{
+    node: Node & SpatialConsumer;
+    parent: Object3D;
+  }>;
+}
+/** A node that accepts a per-frame spatial pose (an AudioPlayer with spatial on). */
+interface SpatialConsumer {
+  spatial: boolean;
+  _setSpatialPose(pose: SpatialPose): void;
 }
 declare function syncTree2D(root: Node, world: Scene, ui: Scene, assets: AssetStore2D | null, uiSize?: UiSize, scratch?: Sync2DScratch, opts?: {
   ignoreStatic?: boolean;

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-CHDLDQsQ.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-BpFcgdcL.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BaRSRrrZ.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-DH7JI5xx.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-DL3izw8j.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CBnor8Zf.js";
 //#region src/2d/library-sprite.ts
 /**
 * What a `CharacterController2D`/`3D` will ask a skin to play, and the clip in

package/dist/3d.d.ts

@@ -1,10 +1,10 @@
-import { At as Node, D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-DWKTUzKI.js";
+import { D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-DsgayMsH.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson$1, s as JsonObject } from "./schema-CFeioQRE.js";
 import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-TvkRFbyL.js";
-import { r as ParticleView, t as ParticleSim } from "./particle-sim-C5OfBbmU.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-BqWBb0kh.js";
+import { t as LoadSceneOptions } from "./loader-DolLJWJn.js";
+import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-D5GJgb_x.js";
+import { n as PathGrid } from "./pathfinding-_fGrCFmH.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
@@ -730,7 +730,7 @@ interface Game3D {
 */
 declare function createGame3D(opts: CreateGame3DOptions): Promise<Game3D>;
 //#endregion
-//#region src/3d/environment.d.ts
+//#region src/core/scene/environment.d.ts
 /**
 * The 3D `environment` header, parsed and validated — the renderer's
 * "rendering stage". Pure data in, plain data out (NO three imports), so the

package/dist/3d.js

@@ -1,9 +1,10 @@
+import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-D7jTvDQv.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-BSMny7oe.js";
-import { B as StaticBody3D, F as WaterCutout3D, I as Area3D, L as CharacterBody3D, N as Water3D, P as WATER_CUTOUT_MAX, R as PhysicsBody3D, V as Node3D, W as WATER_MAX_RIPPLES, z as RigidBody3D } from "./gameplay-BBEjPFsR.js";
-import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-DRAz5EV9.js";
-import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-BiW8Men_.js";
+import { B as StaticBody3D, F as WaterCutout3D, I as Area3D, L as CharacterBody3D, N as Water3D, P as WATER_CUTOUT_MAX, R as PhysicsBody3D, V as Node3D, W as WATER_MAX_RIPPLES, z as RigidBody3D } from "./gameplay-Dtzd2itW.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-CNxCuhZF.js";
+import { a as Environment3D, i as syncTree, o as setEnvironment3D, r as Renderer3D, s as AssetStore3D, t as createGame3D } from "./create-game-IX5lEH0P.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CYxjh-HW.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-BTUfUSWO.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;

package/dist/{pathfinding-BqWBb0kh.d.ts → audio-player-D5GJgb_x.d.ts}

@@ -1,5 +1,80 @@
-import { At as Node, d as PropSchema, dt as Listener } from "./behavior-DWKTUzKI.js";
+import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-DsgayMsH.js";
+import { a as Rng } from "./schema-CFeioQRE.js";
 
+//#region src/core/particle-sim.d.ts
+/**
+* Deterministic particle pool — pure math, renderer-agnostic, headless-
+* testable. 2D uses the xy plane (y-down, directionDeg 0 = +x, -90 = up);
+* 3D feeds the same sim with a z spread.
+*/
+interface ParticleSimConfig {
+  /** Particles per second (0 = burst-only). */
+  rate: number;
+  /** Seconds, [min, max]. */
+  lifetime: [number, number];
+  /** Initial speed, [min, max] (units/sec — px in 2D, meters in 3D). */
+  speed: [number, number];
+  /** Emission direction center, degrees (0 = +x, -90 = up in y-down 2D). */
+  directionDeg: number;
+  /** Cone width, degrees (360 = all directions). */
+  spreadDeg: number;
+  /** Constant acceleration (y-down in 2D). */
+  gravity: [number, number, number];
+  /** Exponential velocity damping per second (0 = none). */
+  drag: number;
+  maxParticles: number;
+  /** Spread emission into the z axis too (3D). */
+  spreadZ?: boolean;
+}
+interface ParticleView {
+  x: number;
+  y: number;
+  z: number;
+  vx: number;
+  vy: number;
+  vz: number;
+  /** Seconds alive. */
+  age: number;
+  /** Total lifetime in seconds. */
+  life: number;
+  /** age/life in [0, 1] — drives size/color/alpha ramps. */
+  t: number;
+  /** Per-particle random in [0, 1) — stable for the particle's lifetime. */
+  seed: number;
+}
+declare class ParticleSim {
+  private readonly config;
+  private readonly rng;
+  private readonly data;
+  private alive;
+  private spawnAccumulator;
+  private everSpawned;
+  constructor(config: ParticleSimConfig, rng: Rng);
+  /**
+  * Shift every live particle — how world-space emission is done.
+  *
+  * The pool is in the emitter's LOCAL space, so a moving emitter drags its
+  * whole plume with it: dust glued to a running player instead of left behind,
+  * and the documented "move the emitter and replay" recipe for a one-shot
+  * teleporting the previous explosion across the level. Counter-translating by
+  * the emitter's own motion each frame leaves the particles where they were
+  * born, exactly, and costs one pass over the live ones.
+  */
+  translateAll(dx: number, dy: number, dz: number): void;
+  /** Change the emission rate LIVE (particles/sec; 0 pauses emission) — lets an
+  * emitter toggle on/off at runtime (drift smoke, throttle flames). */
+  setRate(rate: number): void;
+  get count(): number;
+  /** True when nothing is alive and at least one particle has ever spawned. */
+  get done(): boolean;
+  /** Spawn n particles immediately (fireworks, explosions, flashes). */
+  burst(n: number): void;
+  update(dt: number): void;
+  forEach(fn: (p: ParticleView) => void): void;
+  private spawn;
+  private kill;
+}
+//#endregion
 //#region src/core/nodes/audio-player.d.ts
 /**
 * The per-frame spatial feed the 3D adapter pushes onto a spatial AudioPlayer:
@@ -23,7 +98,7 @@ interface AudioElementLike {
 }
 /**
 * One sound. `play()` (or `autoplay: true`) starts it; `finished` fires when
-* it ends. Browsers block audio before the first user gesture — a blocked
+* it ends — for a procedural preset as well as a `src` clip. Browsers block audio before the first user gesture — a blocked
 * play marks `pendingGesture`; `createGame` retries pending players on the
 * first pointer/key gesture automatically.
 *
@@ -58,10 +133,12 @@ declare class AudioPlayer extends Node {
   /** Start on the first frame in the tree (subject to the gesture policy). */
   autoplay: boolean;
   /**
-  * 3D positional audio: in a 3D scene the sound pans + attenuates by the
-  * emitter's world position relative to the active Camera3D (the listener).
-  * Default false → identical non-spatial behavior (back-compat). In a 2D scene
-  * spatial is currently ignored (the adapter feeds no pose) — see incanto-audio.
+  * Positional audio: the sound pans + attenuates by the emitter's world
+  * position relative to the active camera (the listener). Default false →
+  * identical non-spatial behavior.
+  *
+  * Both dimensions. A 2D scene measures in PIXELS, so the distances below —
+  * metre-shaped defaults — need setting there; `auditScene` says so.
   */
   spatial: boolean;
   /** Distance at which spatial gain is full; closer never gets louder. */
@@ -81,6 +158,21 @@ declare class AudioPlayer extends Node {
   loadError: string | null;
   private element;
   private _playing;
+  /**
+  * `engine.unscaledTime` at which the preset currently sounding ends.
+  *
+  * A preset used to be fire-and-forget: `playing` stayed false through a sound
+  * that was audibly playing, and `finished` — a signal this node DECLARES, so
+  * a connection to it loads clean — never fired at all. Wiring "when the coin
+  * chime ends, free the pickup" to a preset player produced a wire that is
+  * dead for the life of the game and says nothing.
+  *
+  * The end is known exactly: `attack + sustain + decay` is the length
+  * `synthSfx` sizes its buffer to. Measured on the UNSCALED clock because a
+  * sound does not slow down when the game does, and a paused game still hears
+  * the tail of the hit that paused it.
+  */
+  private presetEndsAt;
   private autoplayed;
   /** Last spatial pose pushed by the 3D adapter (null until/unless spatial). */
   private _spatialPose;
@@ -108,10 +200,10 @@ declare class AudioPlayer extends Node {
   play(): void;
   /**
   * Procedural-SFX path: synthesize the preset and fire it through WebAudio
-  * (low-latency, overlap-friendly). Fire-and-forget — no `finished`/`playing`
-  * tracking (these are short one-shots, not the element-driven `src` clip).
-  * Headless (no AudioContext) → silent no-op. WebAudio also needs a gesture;
-  * a suspended context is resumed by the same unlock listener as `src` players.
+  * (low-latency, overlap-friendly). Headless (no AudioContext) plays nothing —
+  * but still reports `playing` and still emits `finished` on schedule, because
+  * the length is arithmetic, not a device. WebAudio needs a gesture; a
+  * suspended context is resumed by the same unlock listener as `src` players.
   */
   private playPreset;
   /**
@@ -130,31 +222,4 @@ declare class AudioPlayer extends Node {
   override update(_dt: number): void;
 }
 //#endregion
-//#region src/core/pathfinding.d.ts
-/**
-* Grid A* — the pathfinding every top-down/RPG/tower-defense asks for and
-* agents keep re-inventing badly. Pure and dimension-free: cells in, cells
-* out; the caller maps cells to world units (px, meters, tiles).
-*/
-interface PathGrid {
-  width: number;
-  height: number;
-  /** True = impassable. Out-of-bounds is always solid. */
-  solid(x: number, y: number): boolean;
-}
-interface FindPathOptions {
-  /** Allow diagonal steps (blocked from cutting corners). Default true. */
-  diagonal?: boolean;
-  /** Abort guard for huge/impossible searches. Default 20000 nodes. */
-  maxExpansions?: number;
-}
-/**
-* A* from `from` to `to` (inclusive cell coords). Returns the cell path
-* INCLUDING both endpoints, or null when unreachable. Straight steps cost
-* 1, diagonals √2; the heuristic is octile (admissible for both modes).
-*/
-declare function findPath(grid: PathGrid, from: [number, number], to: [number, number], opts?: FindPathOptions): [number, number][] | null;
-/** Build a PathGrid from row-strings ('#' = solid) — tests and tile games. */
-declare function gridFromRows(rows: readonly string[]): PathGrid;
-//#endregion
-export { AudioElementLike as a, gridFromRows as i, PathGrid as n, AudioPlayer as o, findPath as r, SpatialPose as s, FindPathOptions as t };
+export { ParticleSimConfig as a, ParticleSim as i, AudioPlayer as n, ParticleView as o, SpatialPose as r, AudioElementLike as t };

package/dist/{behavior-DWKTUzKI.d.ts → behavior-DsgayMsH.d.ts}

@@ -551,6 +551,14 @@ interface SynthOptions {
   seed?: number;
 }
 /**
+* How long a preset lasts, in seconds — the same `attack + sustain + decay`
+* `synthSfx` uses to size its buffer.
+*
+* `pitch` deliberately does not enter into it: it is a frequency multiplier,
+* not a playback rate, so a preset played an octave up is the same length.
+*/
+declare function sfxDuration(params: SfxParams): number;
+/**
 * Render a preset to mono PCM in [-1, 1]. PURE: identical inputs → identical
 * output (the only randomness is the seeded noise generator), so determinism is
 * unit-testable headlessly. Length = ceil((attack+sustain+decay) * sampleRate).
@@ -1780,6 +1788,44 @@ declare class Engine {
   tick(nowMs: number): void;
 }
 //#endregion
+//#region src/core/prop-range.d.ts
+/**
+* The numeric range a prop documents, checked at LOAD.
+*
+* The docs give ranges constantly — `metalness`/`roughness` "0..1 … `-1` = keep
+* authored", `targetHeight` "> 0 uniformly scales the model", `opacity` 0..1 —
+* and the schema had no way to say so, so every one was a type check and
+* nothing more. Measured on `ModelInstance3D`:
+*
+* ```
+* targetHeight: -1.8   NO ERROR (kept -1.8)
+* metalness: 5         NO ERROR (kept 5)
+* roughness: -3        NO ERROR (kept -3)
+* ```
+*
+* The two failure modes differ, which is why neither is noticed. A negative
+* `targetHeight` folds into the same branch as "not set", so the model keeps
+* its authored size and looks like the prop did nothing; `metalness: 5` reaches
+* three and the surface goes wrong. An author who mistypes a decimal point gets
+* a different wrong answer depending on which prop they mistyped it in, and no
+* message in either case.
+*/
+interface PropRange {
+  /** Lowest accepted value. */
+  min?: number;
+  /** Highest accepted value. */
+  max?: number;
+  /** `min` is a bound the value must EXCEED, not reach (`targetHeight > 0`). */
+  exclusiveMin?: boolean;
+  /**
+  * Values outside the range that mean something anyway.
+  *
+  * `metalness: -1` is "keep whatever the GLB authored" — a real value with a
+  * real meaning, and the reason a range cannot just be a clamp.
+  */
+  allow?: readonly number[];
+}
+//#endregion
 //#region src/core/registry.d.ts
 /** A node prop definition. The default both documents and types the prop. */
 interface PropDef {
@@ -1808,6 +1854,38 @@ interface PropDef {
   */
   required?: boolean;
   /**
+  * This prop names an entry in the scene's `assets{}` block.
+  *
+  * Declaring it is what makes a typo a LOAD error. The check already existed —
+  * `AssetStore2D.resolve` throws `UNKNOWN_ASSET` — and it runs inside the
+  * renderer, in a browser, when the texture is first needed. Headless the
+  * scene loaded clean, so `incanto-check` certified a sprite that will draw
+  * nothing, and the docs' promise that "the engine hard-fails on a raw URL"
+  * was not true anywhere an author could see it.
+  *
+  * The same story as `nodePath` and `required`: the rule existed, nothing
+  * routed to it at author time.
+  */
+  /**
+  * The numeric range this prop documents.
+  *
+  * Without it a documented range is prose only: `metalness: 5` and
+  * `targetHeight: -1.8` both passed the kind check and then failed in two
+  * different silent ways. See prop-range.
+  */
+  range?: PropRange;
+  asset?: {
+    /** The `assets{}` entry `type` a `$ref` here must point at. */kind: "texture" | "spritesheet" | "model" | "animation";
+    /**
+    * A value that is not a `$ref` is an error.
+    *
+    * False for props that legitimately take something else — a raw URL
+    * (`UiImage.src`, `Sprite3D.texture`) or the name of a clip baked into a
+    * GLB (`ModelInstance3D.animation`).
+    */
+    refOnly?: boolean;
+  };
+  /**
   * For an OBJECT-valued prop shaped as a tagged union — `collider`, whose
   * `shape` decides which other keys are required. One declaration gives an
   * inspector both the dropdown AND something valid to write when the tag
@@ -1943,4 +2021,4 @@ declare function registeredBehaviors(): string[];
 /** Test isolation helper. */
 declare function clearBehaviors(): void;
 //#endregion
-export { T_PREFIX as $, SettingsValues as A, Node as At, captureBehaviors as B, EngineStats as C, synthSfx as Ct, QualityCaps as D, PlayMusicOptions as Dt, DeviceHints as E, MusicTrack as Et, BehaviorState as F, LogManager as Ft, ORDER_GROUP_BASE as G, savesWithoutUid as H, RestoreReport as I, Signal as It, effectiveOrder as J, OrderGroup as K, SaveSlot as L, SignalListener as Lt, readDeviceHints as M, SceneTree as Mt, suggestQuality as N, LogEntry as Nt, QualityTier as O, AudioBuses as Ot, Scene as P, LogLevel as Pt, Localization as Q, SaveSlots as R, Scheduler as S, SynthOptions as St, RendererStats as T, MusicManager as Tt, SaveStore as U, restoreBehaviors as V, createSaveStore as W, BASE_LOCALE as X, resolveOrderGroups as Y, LocaleTables as Z, mergeStaticSignals as _, spatialPan as _t, clearBehaviors as a, EffectLog as at, Engine as b, SfxParams as bt, registeredBehaviors as c, isAudioContextAvailable as ct, PropSchema as d, Listener as dt, suggestLocale as et, clearRegistry as f, ROLLOFF_MODELS as ft, getNodeType as g, spatialGain as gt, getNodeSignals as h, Vec3 as ht, behaviorSignals as i, EffectKind as it, qualityEnvironment as j, NodeLifecycle as jt, Settings as k, BusName as kt, NodeCtor as l, Voice as lt, getNodeSchema as m, SpatialParams as mt, BehaviorCtor as n, InputMap as nt, getBehavior as o, SfxEngine as ot, createNode as p, RolloffModel as pt, OrderGroupTable as q, behaviorSchema as r, EffectEvent as rt, registerBehavior as s, SfxPlayOptions as st, Behavior as t, translationKey as tt, PropDef as u, VoicePreset as ut, registerNode as v, SFX_PRESETS as vt, GameStats as w, MusicBackend as wt, EngineOptions as x, SfxWave as xt, registeredTypes as y, SFX_PRESET_NAMES as yt, behaviorsWithoutSave as z };
+export { T_PREFIX as $, SettingsValues as A, BusName as At, captureBehaviors as B, EngineStats as C, sfxDuration as Ct, QualityCaps as D, MusicTrack as Dt, DeviceHints as E, MusicManager as Et, BehaviorState as F, LogLevel as Ft, ORDER_GROUP_BASE as G, savesWithoutUid as H, RestoreReport as I, LogManager as It, effectiveOrder as J, OrderGroup as K, SaveSlot as L, Signal as Lt, readDeviceHints as M, NodeLifecycle as Mt, suggestQuality as N, SceneTree as Nt, QualityTier as O, PlayMusicOptions as Ot, Scene as P, LogEntry as Pt, Localization as Q, SaveSlots as R, SignalListener as Rt, Scheduler as S, SynthOptions as St, RendererStats as T, MusicBackend as Tt, SaveStore as U, restoreBehaviors as V, createSaveStore as W, BASE_LOCALE as X, resolveOrderGroups as Y, LocaleTables as Z, mergeStaticSignals as _, spatialPan as _t, clearBehaviors as a, EffectLog as at, Engine as b, SfxParams as bt, registeredBehaviors as c, isAudioContextAvailable as ct, PropSchema as d, Listener as dt, suggestLocale as et, clearRegistry as f, ROLLOFF_MODELS as ft, getNodeType as g, spatialGain as gt, getNodeSignals as h, Vec3 as ht, behaviorSignals as i, EffectKind as it, qualityEnvironment as j, Node as jt, Settings as k, AudioBuses as kt, NodeCtor as l, Voice as lt, getNodeSchema as m, SpatialParams as mt, BehaviorCtor as n, InputMap as nt, getBehavior as o, SfxEngine as ot, createNode as p, RolloffModel as pt, OrderGroupTable as q, behaviorSchema as r, EffectEvent as rt, registerBehavior as s, SfxPlayOptions as st, Behavior as t, translationKey as tt, PropDef as u, VoicePreset as ut, registerNode as v, SFX_PRESETS as vt, GameStats as w, synthSfx as wt, EngineOptions as x, SfxWave as xt, registeredTypes as y, SFX_PRESET_NAMES as yt, behaviorsWithoutSave as z };

package/dist/{create-game-CHDLDQsQ.js → create-game-DH7JI5xx.js}

@@ -1,14 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { c as resolveViewport, j as registerBehavior, n as loadScene, s as computeViewport, w as diagnose } from "./loader-D8n7TU8W.js";
-import { _ as Engine, g as AudioPlayer } from "./register-CDrAQqPp.js";
+import { d as computeViewport, f as resolveViewport, k as diagnose, n as loadScene, z as registerBehavior } from "./loader-D7jTvDQv.js";
+import { _ as Engine, g as AudioPlayer } from "./register-xuSRyD6b.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-DESwnpOc.js";
-import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-RApWnM1G.js";
+import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-B6rwJOyS.js";
 import { o as frameStats } from "./frame-report-BSMny7oe.js";
-import { n as registerGameplayBehaviors } from "./gameplay-BBEjPFsR.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-BpFcgdcL.js";
+import { n as registerGameplayBehaviors } from "./gameplay-Dtzd2itW.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-DL3izw8j.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-BaRSRrrZ.js";
+import { n as enablePhysics2D } from "./physics-2d-CBnor8Zf.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
 /**
@@ -199,14 +199,19 @@ function selectionOutline2D(node) {
 function createSync2DScratch() {
 	return {
 		visited: /* @__PURE__ */ new Set(),
-		cameras: []
+		cameras: [],
+		emitters: []
 	};
 }
+function isSpatialConsumer(node) {
+	return node.spatial === true && typeof node._setSpatialPose === "function";
+}
 function syncTree2D(root, world, ui, assets, uiSize, scratch, opts) {
 	const s = scratch ?? createSync2DScratch();
 	s.visited.clear();
 	s.cameras.length = 0;
-	walk(root, world, ui, false, s.visited, s.cameras, assets, uiSize, opts?.ignoreStatic === true);
+	s.emitters.length = 0;
+	walk(root, world, ui, false, s.visited, s.cameras, s.emitters, assets, uiSize, opts?.ignoreStatic === true);
 	prune(world, s.visited);
 	prune(ui, s.visited);
 	let current = null;
@@ -218,9 +223,66 @@ function syncTree2D(root, world, ui, assets, uiSize, scratch, opts) {
 		}
 	}
 	if (!current) current = s.cameras[0] ?? null;
+	feedSpatialEmitters2D(s.emitters, current);
 	return { activeCamera: current };
 }
-function walk(node, parentObj, ui, inUi, visited, cameras, assets, uiSize, ignoreStatic) {
+const emitterScratch = new Vector3();
+const listenerScratch = new Vector3();
+const upScratch = new Vector3();
+/**
+* Give a 2D scene's spatial AudioPlayers the same per-frame pose the 3D sync
+* gives its own.
+*
+* `spatial`, `refDistance`, `maxDistance` and `rolloff` have been props of
+* `AudioPlayer` since positional audio landed, and in a 2D scene all four did
+* NOTHING: the node only attenuates when an adapter pushes it a pose, and only
+* the 3D one ever did. The scene loaded, `incanto check` said valid, and the
+* sound played at full volume from the far side of the level.
+*
+* The listener is the active `Camera2D` — its world position is the view
+* centre, its own rotation turns the stereo image with it, and the view looks
+* down −Z like every other camera. Distances are therefore in the same units
+* the rest of a 2D scene is in: PIXELS. `refDistance: 1` / `maxDistance: 50`
+* are metre-shaped defaults and read as "silent one sprite away" here, so a 2D
+* scene has to set them; `auditScene` says so when it sees the defaults.
+*/
+function feedSpatialEmitters2D(emitters, camera) {
+	if (emitters.length === 0 || !camera) return;
+	const view = camera._ensureObject2D();
+	view.updateWorldMatrix(true, false);
+	view.getWorldPosition(listenerScratch);
+	upScratch.set(0, 1, 0).applyQuaternion(view.quaternion);
+	const listener = {
+		position: [
+			listenerScratch.x,
+			listenerScratch.y,
+			0
+		],
+		forward: [
+			0,
+			0,
+			-1
+		],
+		up: [
+			upScratch.x,
+			upScratch.y,
+			upScratch.z
+		]
+	};
+	for (const { node, parent } of emitters) {
+		parent.updateWorldMatrix(true, false);
+		parent.getWorldPosition(emitterScratch);
+		node._setSpatialPose({
+			position: [
+				emitterScratch.x,
+				emitterScratch.y,
+				0
+			],
+			listener
+		});
+	}
+}
+function walk(node, parentObj, ui, inUi, visited, cameras, emitters, assets, uiSize, ignoreStatic) {
 	let nextParent = parentObj;
 	let nextInUi = inUi;
 	if (node instanceof Node2D && !(node instanceof UILayer)) {
@@ -249,8 +311,11 @@ function walk(node, parentObj, ui, inUi, visited, cameras, assets, uiSize, ignor
 		visited.add(obj);
 		if (node instanceof Camera2D && !inUi) cameras.push(node);
 		nextParent = obj;
-	}
-	for (const child of node.children) walk(child, nextParent, ui, nextInUi, visited, cameras, assets, uiSize, ignoreStatic);
+	} else if (isSpatialConsumer(node)) emitters.push({
+		node,
+		parent: nextParent
+	});
+	for (const child of node.children) walk(child, nextParent, ui, nextInUi, visited, cameras, emitters, assets, uiSize, ignoreStatic);
 	if (node instanceof Node2D && !(node instanceof UILayer)) {
 		const obj = node._ensureObject2D();
 		if (node.static && !ignoreStatic) {