incanto 0.60.0 → 0.62.0

package/bin/incanto-check.mjs

@@ -167,6 +167,15 @@ const { auditScene, validateScene } = await import(pathToFileURL(join(DIST, 'tes
  * 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'));
@@ -174,6 +183,9 @@ for (const file of files) {
       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 */
   }
@@ -188,6 +200,7 @@ 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) {

package/bin/incanto-verify.mjs

@@ -147,9 +147,24 @@ const rungs = [];
   // the legal values sitting one key away in the same object.
   const broke = out?.results?.find((entry) => entry && entry.ok === false);
   const detail = broke && (broke.message || broke.code) ? `[${broke.code}] ${broke.message}` : null;
+  // What `incanto-check` SAID, beyond whether it passed. The rung read `ok` and
+  // dropped `warnings` on the floor, so a scene the child describes as "nothing
+  // lights this 3D scene … It will render black" was reported by the headline
+  // command as "✓ loads — the scene is legal and its assets resolve". The
+  // ladder's own header table names this tool as the one for "the scene will
+  // not load, OR RENDERS BLACK".
+  const notes = (out?.results ?? []).flatMap((entry) => entry?.warnings ?? []);
+  // "and its assets resolve" is a claim, and `missing art` is the check saying
+  // it does not. Do not make the claim when the child just contradicted it.
+  const missingArt = notes.some((n) => /is not in the project|missing|not found/i.test(String(n)));
   rungs.push(
     r.status === 0
-      ? { name: 'loads', status: 'pass', summary: 'the scene is legal and its assets resolve' }
+      ? {
+          name: 'loads',
+          status: 'pass',
+          summary: missingArt ? 'the scene is legal' : 'the scene is legal and its assets resolve',
+          ...(notes.length > 0 ? { notes, fix: `incanto-check ${scene}` } : {}),
+        }
       : {
           name: 'loads',
           status: 'fail',
@@ -175,62 +190,126 @@ if (rungs[0].status === 'pass') {
   // walkabout template has no end, and calling that a failure sends its author
   // hunting a bug that was never there.
   const noGoal = out && out.declaresWin === false;
-  // A quest — talk to the NPC, clear the enemies, light the wards — cannot be
-  // finished by a random walker, ever. Reporting that as a FAILED rung means
-  // the headline command permanently says NOT verified about a correct game,
-  // which teaches its author to stop reading it. If every run played to the
-  // end of its budget without erroring, falling or wedging, the rung has not
-  // failed: it has not measured, and the author's own scripted harness is what
-  // can judge this game.
-  // Three of the five outcomes are GAMEPLAY, not defects. `won`, `lost` and
+  // Three of the six outcomes are GAMEPLAY, not defects. `won`, `lost` and
   // `unfinished` all mean the game ran; a random player dying half the time in
-  // a platformer is the hazards working. The defects are `error` (a behaviour
-  // threw), `fell` (left the world) and `stuck` (went nowhere), and those are
-  // what this rung is for.
-  const PLAYED = new Set(['won', 'lost', 'unfinished']);
-  const playedOut =
-    out && (out.runs?.length ?? 0) > 0 && out.runs.every((x) => PLAYED.has(x.outcome));
+  // a platformer is the hazards working, and a quest cannot be finished by a
+  // random walker ever — reporting that as a FAILED rung means the headline
+  // command permanently says NOT verified about a correct game, which teaches
+  // its author to stop reading it.
+  //
+  // The other three are DEFECTS: `error` (a behaviour threw), `fell` (left the
+  // world) and `stuck` (went nowhere). They are counted BEFORE a branch is
+  // chosen, and they used to be counted after — only on the path where a win
+  // existed to miss. A scene that declares no win took the `noGoal` branch for
+  // ANY mix of outcomes, and that branch's summary was the hard-coded phrase
+  // "N runs played without error": an assumption wearing the clothes of a
+  // measurement. Measured on the shipped `basic-3d-sideview`, whose player
+  // walks off the edge on every seeded run:
+  //
+  // They used to be counted after, and only on the path where a win existed to
+  // miss. A scene that declares no win took the `noGoal` branch for ANY mix of
+  // outcomes, and that branch's summary was the hard-coded phrase "N runs
+  // played without error" — an assumption wearing the clothes of a
+  // measurement. Measured on the shipped `basic-3d-sideview`, whose player
+  // walks off the edge on every seeded run:
+  //
+  //   incanto-playtest → ✗ fell in 4/4 (last at y=-48.4)
+  //   incanto-verify   → ? plays — nothing declares a win — 8 runs played
+  //                      without error, and there was no end to reach
+  //   passes what was measured … VERIFY EXIT=0
+  //
+  // The child had just printed the defect; the parent reported the opposite of
+  // it and exited 0. The three outcomes this rung exists to catch were the
+  // three it could not report.
+  //
+  // `stuck` is the one that needs a fair chance before it counts. It means the
+  // player went nowhere, and the player goes nowhere for three different
+  // reasons: it is wedged (a defect), there IS no player (`2d-phaser-basic` is
+  // a ground, a sprite and a camera — the driver had nobody to move), or the
+  // game's own behaviours were never loaded, which is most of what makes a
+  // character move. Only the first is this rung's business.
   const tally = (name) => out?.runs?.filter((x) => x.outcome === name).length ?? 0;
-  rungs.push(
-    r.status === 0
-      ? { name: 'plays', status: 'pass', summary: `${won} of ${total} seeded runs finished it` }
-      : playedOut
-        ? {
-            name: 'plays',
-            status: 'unmeasured',
-            summary:
-              `${total} runs played without reaching a win` +
-              ` (${[
-                tally('lost') && `${tally('lost')} lost`,
-                tally('unfinished') && `${tally('unfinished')} ran out the clock`,
-              ]
-                .filter(Boolean)
-                .join(', ')})`,
-            fix: 'nothing here is broken — a win that takes skill or a sequence is out of reach of random play. Judge it with a scripted run: `bun run verify`, or `runScript` from `incanto/test`',
-          }
-        : noGoal
-          ? {
-              name: 'plays',
-              status: 'unmeasured',
-              summary: `nothing declares a win — ${total} runs played without error, and there was no end to reach`,
-              fix: 'if it is meant to be finishable, emit `won` (GameFlow, ScoreKeeper, or your own behaviour)',
-            }
-          : {
-              name: 'plays',
-              status: 'fail',
-              summary:
-                total > 0
-                  ? `no run finished it (${total} tried)`
-                  : // "could not run" with no reason is the tool doing to its
-                    // reader exactly what this whole ladder exists to prevent:
-                    // reporting a failure it already knows the cause of. The
-                    // child printed one; pass it on.
-                    `the playtest could not run — ${firstLine(r.stderr) || `exit ${r.status}`}`,
-              fix: behaviors
-                ? `see which runs stalled and where: \`incanto-playtest ${scene} --behaviors ${behaviors}\``
-                : `run it with your behaviours — without them the structure plays and your game logic does not: \`incanto-playtest ${scene} --behaviors src/behaviors.ts\``,
-            },
-  );
+  const stuckCounts = out?.hasPlayer !== false && Boolean(behaviors);
+  const DEFECT = new Set(stuckCounts ? ['error', 'fell', 'stuck'] : ['error', 'fell']);
+  const defects = out?.runs?.filter((x) => DEFECT.has(x.outcome)) ?? [];
+  const undrivable = total > 0 && defects.length === 0 && tally('stuck') === total;
+  const count = (n, word) => n && `${n} ${word}`;
+
+  if (total === 0) {
+    rungs.push({
+      name: 'plays',
+      status: 'fail',
+      // "could not run" with no reason is the tool doing to its reader exactly
+      // what this whole ladder exists to prevent: reporting a failure it
+      // already knows the cause of. The child printed one; pass it on.
+      summary: `the playtest could not run — ${firstLine(r.stderr) || `exit ${r.status}`}`,
+      fix: behaviors
+        ? `see it directly: \`incanto-playtest ${scene} --behaviors ${behaviors}\``
+        : `run it with your behaviours: \`incanto-playtest ${scene} --behaviors src/behaviors.ts\``,
+    });
+  } else if (defects.length > 0) {
+    rungs.push({
+      name: 'plays',
+      status: 'fail',
+      summary:
+        `${defects.length} of ${total} runs ended in a defect (` +
+        [
+          count(tally('fell'), 'fell out of the world'),
+          count(tally('error'), 'errored'),
+          count(tally('stuck'), 'went nowhere'),
+        ]
+          .filter(Boolean)
+          .join(', ') +
+        ')' +
+        (won > 0 ? ` — ${won} did finish it` : ''),
+      fix:
+        tally('error') > 0
+          ? `read the throw: \`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\`, and \`engine.stats().errors\` in your own harness`
+          : tally('fell') > 0
+            ? `the player left the world with nothing catching them — give the level a floor, walls, or a respawn (\`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\` prints where)`
+            : `nothing moved — check the input map and the controller: \`incanto-playtest ${scene}${behaviors ? ` --behaviors ${behaviors}` : ''}\``,
+    });
+  } else if (r.status === 0) {
+    rungs.push({
+      name: 'plays',
+      status: 'pass',
+      summary: `${won} of ${total} seeded runs finished it`,
+    });
+  } else if (undrivable) {
+    rungs.push({
+      name: 'plays',
+      status: 'unmeasured',
+      summary:
+        out?.hasPlayer === false
+          ? `nothing here is drivable — ${total} runs had nobody to move`
+          : `${total} runs went nowhere, and your behaviours were not loaded — that is most of what moves a character`,
+      fix:
+        out?.hasPlayer === false
+          ? 'give the player a character controller, the `player` group, or the name Player — otherwise no seeded run can play this'
+          : `name them: \`incanto-verify ${scene} --behaviors src/behaviors.ts\``,
+    });
+  } else if (noGoal) {
+    rungs.push({
+      name: 'plays',
+      status: 'unmeasured',
+      // Now this phrase IS measured: `defects.length === 0` got us here.
+      summary: `nothing declares a win — ${total} runs played without a defect, and there was no end to reach`,
+      fix: 'if it is meant to be finishable, emit `won` (GameFlow, ScoreKeeper, or your own behaviour)',
+    });
+  } else {
+    // A quest — talk to the NPC, clear the enemies, light the wards — cannot be
+    // finished by a random walker, ever. Reporting that as a FAILED rung means
+    // the headline command permanently says NOT verified about a correct game,
+    // which teaches its author to stop reading it.
+    rungs.push({
+      name: 'plays',
+      status: 'unmeasured',
+      summary:
+        `${total} runs played without reaching a win` +
+        ` (${[count(tally('lost'), 'lost'), count(tally('unfinished'), 'ran out the clock')].filter(Boolean).join(', ')})`,
+      fix: 'nothing here is broken — a win that takes skill or a sequence is out of reach of random play. Judge it with a scripted run: `bun run verify`, or `runScript` from `incanto/test`',
+    });
+  }
 } else {
   rungs.push({ name: 'plays', status: 'skipped', summary: 'not run — the scene does not load' });
 }

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";
 
@@ -90,6 +90,28 @@ declare class Node2D extends Node {
   /** @internal Override point. */
   protected _createObject2D(): Object3D;
   /** @internal Push JSON props onto the backing object. Called every frame. */
+  /**
+  * Has this node produced the thing `static: true` is about to freeze?
+  *
+  * `static` latches after the first sync, and a textured node's first sync
+  * happens BEFORE its texture has decoded — `TextureLoader.load()` returns a
+  * `Texture` with `image === undefined` and fills it asynchronously, while
+  * `Renderer2D.render()` calls `assets.load()` and `syncTree2D()` in the same
+  * frame. So the state frozen was `visible = false`, forever. Measured on two
+  * identical sprites differing only in `static`:
+  *
+  * ```
+  * frame 1            Backdrop(static) visible: false   Control visible: false
+  * 600 frames later   Backdrop(static) visible: false width 1
+  *                    Control          visible: true  width 64
+  * ```
+  *
+  * Nothing throws: the texture loaded fine, so `assetErrors()` is empty,
+  * `stats().errors` is 0, and `framing` reads props rather than pixels and
+  * still calls the node on-screen. Overridden by the nodes that wait on an
+  * image; a node with nothing to wait for is ready by definition.
+  */
+  _staticReady(_assets: AssetStore2D | null): boolean;
   _syncObject2D(_assets: AssetStore2D | null): void;
   override free(): void;
 }
@@ -498,6 +520,7 @@ declare class Sprite2D extends Node2D {
   protected override _createObject2D(): Object3D;
   /** Override point: AnimatedSprite2D substitutes its frame window here. */
   protected resolveTexture(assets: AssetStore2D | null): ResolvedSpriteTexture | null;
+  override _staticReady(assets: AssetStore2D | null): boolean;
   override _syncObject2D(assets: AssetStore2D | null): void;
 }
 //#endregion
@@ -568,6 +591,24 @@ declare class Camera2D extends Node2D {
   get effectiveZoom(): number;
   override update(dt: number): void;
   /** View center after clamping the (vw×vh)/zoom view rect inside `limits`. */
+  /**
+  * The view centre the renderer draws around, in WORLD space.
+  *
+  * It used to read `this.position` raw — the LOCAL prop — while every other
+  * 2D node gets its ancestors composed for free by the three scene graph. So a
+  * camera parented to the player, the Godot/Phaser idiom the authoring skill
+  * explicitly permits, framed the world origin:
+  *
+  * ```
+  * player world position : [1400, 900]
+  * renderer view centre  : {"x":0,"y":0}
+  * framing               : camera /Level/Player/Cam centred [1400, 900]
+  *                         1 in view, 0 outside it
+  * ```
+  *
+  * `framing` composes full world matrices, so the instrument the skills tell
+  * you to trust certified a view the renderer never drew.
+  */
   clampedCenter(vw: number, vh: number): {
     x: number;
     y: number;
@@ -701,6 +742,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;
@@ -872,6 +923,7 @@ declare class TileMap2D extends Node2D {
   private rebuildColliders;
   /** @internal The drawable mesh (lazily created under the backing object). */
   _mesh(): Mesh;
+  override _staticReady(assets: AssetStore2D | null): boolean;
   override _syncObject2D(assets: AssetStore2D | null): void;
   /** One quad per visible tile, atlas UVs — a single draw call for the level. */
   private buildGeometry;
@@ -1081,6 +1133,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-ClnIb_M5.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-BSu2dWGC.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-DqdVp1bt.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-BpunnGPX.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-CNh4FlbD.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BXmu2i7W.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-DEe272nY.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-8cjF3t6w.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-BCm38FJV.js";
+import { B as CharacterBody3D, F as Water3D, H as RigidBody3D, I as WATER_CUTOUT_MAX, L as WaterCutout3D, U as StaticBody3D, V as PhysicsBody3D, W as Node3D, q as WATER_MAX_RIPPLES, z as Area3D } from "./gameplay-CaHqDiQD.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-BAWeOeqf.js";
+import { a as Environment3D, i as syncTree, o as setEnvironment3D, r as Renderer3D, s as AssetStore3D, t as createGame3D } from "./create-game-Caut3bqN.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-BP0DZb_1.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-ClxP6Uv7.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 };