incanto 0.53.0 → 0.55.0

package/bin/incanto-check.mjs

@@ -58,6 +58,61 @@ function collectScenes(entry) {
   return out;
 }
 
+/**
+ * Local art the project does not contain.
+ *
+ * A scene asset pointing at a file nobody copied loads fine, validates fine and
+ * draws NOTHING — the failure exists only in a browser, in `assetErrors()`,
+ * which needs a running game and someone to look at it. This command has the
+ * scene's path and runs after every edit, and the file is either there or it is
+ * not. A WARNING, not an error: a url can legitimately be produced at runtime,
+ * and refusing to load a scene over a guess would be worse than the bug.
+ */
+function missingArt(file, json) {
+  const assets = json && typeof json === 'object' ? json.assets : null;
+  if (!assets || typeof assets !== 'object') return [];
+  const sceneDir = dirname(file);
+  const root = projectRoot(sceneDir);
+  const out = [];
+  for (const [key, decl] of Object.entries(assets)) {
+    const url = decl && typeof decl === 'object' ? decl.url : null;
+    if (typeof url !== 'string' || url === '') continue;
+    // Remote and inline are not this command's business to guess about.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('//')) continue;
+    const rel = url.replace(/^\//, '');
+    const candidates = [
+      join(root, 'public', rel),
+      join(root, rel),
+      join(sceneDir, rel),
+      join(sceneDir, '..', rel),
+    ];
+    if (candidates.some((p) => existsSync(p))) continue;
+    out.push(
+      `$${key} → ${url} is not in the project ` +
+        `(looked in ${relativeish(root, join(root, 'public'))}, ${relativeish(root, root)}` +
+        `, and beside the scene). It will draw nothing.`,
+    );
+  }
+  return out;
+}
+
+/** Nearest ancestor with a package.json, else the scene's own directory. */
+function projectRoot(from) {
+  let dir = resolve(from);
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return resolve(from);
+}
+
+function relativeish(root, p) {
+  const r = p.slice(root.length).replace(/^[\\/]/, '');
+  return r === '' ? './' : `${r}/`;
+}
+
 const roots = args.files.length > 0 ? args.files : ['.'];
 for (const r of roots) {
   if (!existsSync(resolve(r))) {
@@ -84,7 +139,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, warnings: auditScene(json) };
+  if (res.ok) return { file, ok: true, warnings: [...auditScene(json), ...missingArt(file, json)] };
   return {
     file,
     ok: false,

package/bin/incanto-verify.mjs

@@ -122,12 +122,16 @@ const rungs = [];
   );
 }
 
+/** The playtest's JSON, shared by the `plays` and `feels` rungs. */
+let playtestReport = null;
+
 // ---- plays ---------------------------------------------------------------
 if (rungs[0].status === 'pass') {
   const args = [scene, '--json', '--runs', '8'];
   if (behaviors) args.push('--behaviors', behaviors);
   const r = run('playtest', args);
   const out = safeJson(r.stdout);
+  playtestReport = out;
   const won = out?.runs?.filter((x) => x.outcome === 'won').length ?? 0;
   const total = out?.runs?.length ?? 0;
   // A scene that declares no win is not a scene that cannot be won: a
@@ -158,6 +162,48 @@ if (rungs[0].status === 'pass') {
   rungs.push({ name: 'plays', status: 'skipped', summary: 'not run — the scene does not load' });
 }
 
+// ---- feels ---------------------------------------------------------------
+// Sound and effects, from the same playtest that just ran. A game whose
+// feedback is wired but never triggered plays perfectly and feels dead, and
+// every other rung here calls it healthy.
+{
+  const fb = playtestReport?.feedback;
+  const declared = (fb?.declaredAudio?.length ?? 0) + (fb?.declaredEffects?.length ?? 0);
+  const fired = new Set([...(fb?.heard ?? []), ...(fb?.shown ?? [])]);
+  if (!fb) {
+    rungs.push({
+      name: 'feels',
+      status: 'skipped',
+      summary: 'not run — the playtest did not report',
+    });
+  } else if (declared === 0) {
+    rungs.push({
+      name: 'feels',
+      status: 'skipped',
+      summary: 'this game declares no sound and no effects',
+    });
+  } else if (fired.size === 0) {
+    rungs.push({
+      name: 'feels',
+      status: 'fail',
+      summary: `${declared} sound/effect node(s) declared, and not one fired in any run`,
+      fix: 'connect them — a signal to `play` on an AudioPlayer, or `replay()` on a one-shot; `engine.audio.recent()` and `engine.effects.recent()` say what did fire',
+    });
+  } else {
+    const silent = [...(fb.declaredAudio ?? []), ...(fb.declaredEffects ?? [])].filter(
+      (path) => !fired.has(path),
+    );
+    rungs.push({
+      name: 'feels',
+      status: 'pass',
+      summary:
+        silent.length === 0
+          ? `every one of the ${declared} sound/effect nodes fired`
+          : `${fired.size} of ${declared} fired — silent: ${silent.slice(0, 3).join(', ')}${silent.length > 3 ? ` +${silent.length - 3}` : ''}`,
+    });
+  }
+}
+
 // ---- draws ---------------------------------------------------------------
 {
   const r = run('frame', ['--json']);

package/dist/2d.d.ts

@@ -1,9 +1,9 @@
-import { Dt 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-Do0Da56m.js";
+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-CyQoSu4n.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 { t as LoadSceneOptions } from "./loader-Cu_7kJDy.js";
+import { t as LoadSceneOptions } from "./loader-DhI1jFW_.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
-import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
+import { r as ParticleView, t as ParticleSim } from "./particle-sim-C5OfBbmU.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
 
@@ -517,6 +517,16 @@ declare class AnimatedSprite2D extends Sprite2D {
   stop(): void;
   override onReady(): void;
   override update(dt: number): void;
+  /** Sheets already reported, so a bad grid says so ONCE, not every frame. */
+  private gridChecked;
+  /**
+  * Tell the author their grid does not fit, the first time it is drawn.
+  *
+  * Both halves of this were silent: a frame size that does not divide the
+  * sheet slices every row further off centre, and an animation naming a frame
+  * past the end of the grid draws whatever is at the wrong end of the image.
+  */
+  private checkGrid;
   protected override resolveTexture(assets: AssetStore2D | null): ResolvedSpriteTexture | null;
 }
 //#endregion
@@ -699,6 +709,18 @@ declare class Particles2D extends Node2D {
   static override readonly props: PropSchema;
   preset: string;
   emitting: boolean;
+  /**
+  * Where a particle LIVES once it is born.
+  *
+  * `false` (default) — the emitter's local space: the plume moves with the
+  * node, which is what a torch on a moving platform wants.
+  *
+  * `true` — the world: a particle keeps the place it was born, so dust is left
+  * BEHIND a running player instead of glued to it, and moving a one-shot to
+  * the next explosion (the documented `p.position = …; p.replay()` recipe)
+  * stops dragging the previous one across the level.
+  */
+  worldSpace: boolean;
   rate: number;
   burst: number;
   lifetime: number[];
@@ -728,9 +750,30 @@ declare class Particles2D extends Node2D {
   private finishedEmitted;
   /** @internal Lazily applies the preset + builds the deterministic sim. */
   _ensureSim(): ParticleSim;
+  /** Particles alive this frame — an emitter that is running, told from one
+  *  that is not. `framing()` says where it IS; this says whether it is going. */
+  get aliveCount(): number;
+  /** A snapshot of the live particles — positions are in whichever space
+  *  `worldSpace` selects, relative to the emitter. */
+  particles(): ParticleView[];
+  /** The emitter's world position last frame, for world-space counter-motion. */
+  private lastWorld;
+  /** Last frame's `emitting`, so turning one ON is a reportable event. */
+  private wasEmitting;
   override update(dt: number): void;
+  /**
+  * Undo the emitter's own motion on everything already alive.
+  *
+  * Ancestor-summed like the physics helpers, so it follows a moving PARENT
+  * (dust under a player) as well as the node's own position.
+  */
+  private holdWorldSpace;
+  /** Tell the engine an effect fired — the visual half of the audio record. */
+  private report;
   /** Restart a one-shot (re-burst + allow finished to fire again). */
   replay(): void;
+  /** `replay()` asked for this burst, so `emitting: false` does not hold it. */
+  private armedByReplay;
   private mesh;
   /** Parsed `paletteColors`, reused; rebuilt only when the hex list changes. */
   private paletteCache;

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-9D87XaiX.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-DROK2l7J.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BhZZ-HAp.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-BRt6XKmP.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-en63AEZO.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CfWAggJ1.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 { D as QualityCaps, Dt 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-Do0Da56m.js";
+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-CyQoSu4n.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 { t as LoadSceneOptions } from "./loader-Cu_7kJDy.js";
-import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
+import { t as LoadSceneOptions } from "./loader-DhI1jFW_.js";
+import { r as ParticleView, t as ParticleSim } from "./particle-sim-C5OfBbmU.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-DZ70IY26.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-HNGFqGUZ.js";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-CXGCpRQe.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";
@@ -61,6 +61,15 @@ declare class TextureCache3D {
   */
   acquireOwn(url: string, spec?: TextureSpec): Texture | null;
   /**
+  * File a failure this store did not load itself.
+  *
+  * `Tree3D` keeps its own cache on purpose (it decodes off-thread and its
+  * page-session lifetime is load-bearing for the editor), which left its bark
+  * and leaf textures outside the one place `assetErrors()` reads. A 404'd leaf
+  * texture is a forest of bare branches and no message anywhere.
+  */
+  noteError(url: string, error: unknown): void;
+  /**
   * What 404'd, by URL — reported raw, never by cache key, because an agent
   * greps this against the URL it wrote.
   */
@@ -1859,6 +1868,15 @@ declare class LoftMesh3D extends Node3D {
   private geometryKey;
   protected override _createObject3D(): Object3D;
   override _syncObject3D(): void;
+  /**
+  * Hand the GPU back.
+  *
+  * Every other node that builds geometry disposes it here; these four did not,
+  * so a scene swap left their buffers and materials resident and a game with
+  * level transitions climbed until the tab died — with `stats().geometries` the
+  * only witness, and only if someone was watching it.
+  */
+  override free(): void;
 }
 //#endregion
 //#region src/3d/nodes/model-instance-3d.d.ts
@@ -2030,6 +2048,18 @@ declare class Particles3D extends Node3D {
   static override readonly props: PropSchema;
   preset: string;
   emitting: boolean;
+  /**
+  * Where a particle LIVES once it is born.
+  *
+  * `false` (default) — the emitter's local space: the plume moves with the
+  * node, which is what a torch on a moving platform wants.
+  *
+  * `true` — the world: a particle keeps the place it was born, so dust is left
+  * BEHIND a running player instead of glued to it, and moving a one-shot to
+  * the next explosion (the documented `p.position = …; p.replay()` recipe)
+  * stops dragging the previous one across the level.
+  */
+  worldSpace: boolean;
   rate: number;
   burst: number;
   lifetime: number[];
@@ -2065,9 +2095,30 @@ declare class Particles3D extends Node3D {
   private finishedEmitted;
   /** @internal */
   _ensureSim(): ParticleSim;
+  /** Particles alive this frame — an emitter that is running, told from one
+  *  that is not. `framing()` says where it IS; this says whether it is going. */
+  get aliveCount(): number;
+  /** A snapshot of the live particles — positions are in whichever space
+  *  `worldSpace` selects, relative to the emitter. */
+  particles(): ParticleView[];
+  /** The emitter's world position last frame, for world-space counter-motion. */
+  private lastWorld;
+  /** Last frame's `emitting`, so turning one ON is a reportable event. */
+  private wasEmitting;
   override update(dt: number): void;
+  /**
+  * Undo the emitter's own motion on everything already alive.
+  *
+  * Ancestor-summed like the physics helpers, so it follows a moving PARENT
+  * (dust under a player) as well as the node's own position.
+  */
+  private holdWorldSpace;
+  /** Tell the engine an effect fired — the visual half of the audio record. */
+  private report;
   /** Restart a one-shot (re-burst + allow finished to fire again). */
   replay(): void;
+  /** `replay()` asked for this burst, so `emitting: false` does not hold it. */
+  private armedByReplay;
   private points;
   private positions;
   private colors;
@@ -2080,6 +2131,15 @@ declare class Particles3D extends Node3D {
   * uses the colorStart→colorEnd ramp. */
   private refreshPalette;
   private syncParticles;
+  /**
+  * Hand the GPU back.
+  *
+  * Every other node that builds geometry disposes it here; these four did not,
+  * so a scene swap left their buffers and materials resident and a game with
+  * level transitions climbed until the tab died — with `stats().geometries` the
+  * only witness, and only if someone was watching it.
+  */
+  override free(): void;
 }
 //#endregion
 //#region src/3d/terrain/heightmap.d.ts
@@ -2756,10 +2816,30 @@ declare class Trail3D extends Node3D {
   private mesh;
   private lastColor;
   protected override _createObject3D(): Object3D;
+  /** Last frame's `emitting`, so laying ribbon is a reportable event. */
+  private wasEmitting;
   override update(dt: number): void;
   _onRender3D(ctx: RenderContext3D): void;
-  /** Test hook: recorded point count. */
+  /**
+  * How many points the ribbon is made of.
+  *
+  * ZERO with no renderer, and that is not a bug: the ribbon is laid in the
+  * render sync, because each point needs the node's real world transform (a
+  * sword arc is a ROTATING parent, which an ancestor position sum cannot see).
+  * Assert it from a browser check; read a headless 0 as "nothing rendered"
+  * rather than "my trail is broken", and use the `trail` effect record for the
+  * wiring question.
+  */
   get pointCount(): number;
+  /**
+  * Hand the GPU back.
+  *
+  * Every other node that builds geometry disposes it here; these four did not,
+  * so a scene swap left their buffers and materials resident and a game with
+  * level transitions climbed until the tab died — with `stats().geometries` the
+  * only witness, and only if someone was watching it.
+  */
+  override free(): void;
 }
 //#endregion
 //#region src/3d/vegetation/tree-blueprint.d.ts
@@ -2859,7 +2939,17 @@ declare class Tree3D extends Node3D {
   /** @internal Every grown variant (medium/high tiers; empty for 'simple'). */
   _variantMeshes(): TreeVariant[];
   override update(dt: number): void;
-  override _syncObject3D(): void;
+  /** The scene's asset store, so a 404'd bark or leaf reaches assetErrors(). */
+  private assets;
+  override _syncObject3D(alpha?: number, assets?: AssetStore3D | null): void;
+  /**
+  * File a texture failure where the ladder reads it.
+  *
+  * This node keeps its own cache on purpose, and that left its textures
+  * outside the one place `assetErrors()` looks — so a leaf URL that 404s was a
+  * forest of bare branches with no message anywhere.
+  */
+  private noteTextureError;
   /** Re-grow only when a grove-shaping prop changed (the JSON IS the grove). */
   private rebuildIfNeeded;
   /** Resolve the drape target + cache the grove's world position for `bedY`. */
@@ -2930,6 +3020,15 @@ declare class VoxelGrid3D extends Node3D {
   blocks(): VoxelBlock[];
   protected override _createObject3D(): Object3D;
   override update(): void;
+  /**
+  * Hand the GPU back.
+  *
+  * Every other node that builds geometry disposes it here; these four did not,
+  * so a scene swap left their buffers and materials resident and a game with
+  * level transitions climbed until the tab died — with `stats().geometries` the
+  * only witness, and only if someone was watching it.
+  */
+  override free(): void;
 }
 //#endregion
 //#region src/3d/water/interaction.d.ts

package/dist/3d.js

@@ -1,9 +1,9 @@
-import { F as CharacterBody3D, H as WATER_MAX_RIPPLES, I as PhysicsBody3D, L as RigidBody3D, M as WATER_CUTOUT_MAX, N as WaterCutout3D, P as Area3D, R as StaticBody3D, j as Water3D, z as Node3D } from "./gameplay-CRYw_Q-T.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-SkGanr2s.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-CDJ1lVqK.js";
+import { F as CharacterBody3D, H as WATER_MAX_RIPPLES, I as PhysicsBody3D, L as RigidBody3D, M as WATER_CUTOUT_MAX, N as WaterCutout3D, P as Area3D, R as StaticBody3D, j as Water3D, z as Node3D } from "./gameplay-CZ2yq37J.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-DAbEdEwh.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-CzK9_pzg.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-njybhZon.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DmyO2oaN.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-C_ZJ6f_d.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;
@@ -50,6 +50,10 @@ const BODY = {
 	radius: .34,
 	height: 1
 };
+/** Three decimals — enough for millimetres, and no float dust in pasted JSON. */
+function round3(n) {
+	return Math.round(n * 1e3) / 1e3;
+}
 /**
 * A found character, as a thing that walks.
 *
@@ -122,10 +126,10 @@ function characterJson(target) {
 				type: "ModelInstance3D",
 				props: {
 					model: `$${target.key}`,
-					targetHeight: BODY.height + 2 * BODY.radius,
+					targetHeight: round3(BODY.height + 2 * BODY.radius),
 					position: [
 						0,
-						-(BODY.height / 2 + BODY.radius),
+						round3(-(BODY.height / 2 + BODY.radius)),
 						0
 					],
 					castShadow: true

package/dist/{behavior-Do0Da56m.d.ts → behavior-CyQoSu4n.d.ts}

@@ -718,6 +718,57 @@ declare class SfxEngine {
   play(params: SfxParams, gain: number, opts?: SfxPlayOptions): void;
 }
 //#endregion
+//#region src/core/effects-log.d.ts
+/**
+* What SHOWED — the visual half of the audio record.
+*
+* A game's feedback is sound and vision, and only one of them could be checked.
+* `engine.audio.countOf('coin')` answers "did the coin sound fire?"; nothing
+* answered "did the explosion?". `framing()` says where an emitter IS, which is
+* a different question — a particle system that never fired and one that fired
+* a hundred times sit at the same coordinates.
+*
+* Nothing here renders, so nothing here is measured in pixels. It records that
+* the effect WAS ASKED FOR, which is the wiring question a game actually has:
+* the burst that never happened because the signal was never connected looks
+* exactly like the burst that happened off-screen, and this tells them apart.
+*
+* ```ts
+* session.engine.effects.clearLog();
+* smashTheCrystal();
+* session.step(200);
+* session.engine.effects.countOf('explosion');        // 1
+* session.engine.effects.countFrom('/Game/Crystal/Boom'); // 1
+* ```
+*/
+/** The kinds of thing a game does to say "that happened". */
+type EffectKind = "burst" | "emit" | "trail" | "shake" | "flash" | "hitstop";
+/** One effect that fired. */
+interface EffectEvent {
+  kind: EffectKind;
+  /** The preset name, the flash colour, or `''` when the effect has no name. */
+  name: string;
+  /** Node path, or `engine` for the screen-wide ones. */
+  from: string;
+  /** Particles in the burst, shake magnitude, seconds frozen — the amount. */
+  amount: number;
+  /** `engine.time` when it fired, in seconds. */
+  at: number;
+}
+declare class EffectLog {
+  private readonly events;
+  /** @internal Called by the effects themselves; games read `recent()`. */
+  record(event: EffectEvent): void;
+  /** The last `limit` effects, oldest first. */
+  recent(limit?: number): EffectEvent[];
+  /** How many times an effect with this name fired (`explosion`, `#ff0000`). */
+  countOf(name: string): number;
+  /** How many effects this node fired — the question a wiring check has. */
+  countFrom(path: string): number;
+  /** Forget what has fired so far (between scenes, or between assertions). */
+  clearLog(): void;
+}
+//#endregion
 //#region src/core/input.d.ts
 /**
 * Declarative input from scene JSON `input{}` — DOM-free logic (feed key state
@@ -1404,12 +1455,36 @@ interface QualityCaps {
   minReflectionIntervalMs: number;
 }
 //#endregion
-//#region src/core/stats.d.ts
+//#region src/core/phase-timing.d.ts
 /**
-* Performance-stats shapes — pure data, importable everywhere (core stays
-* three-free; the renderer adapters fill RendererStats from three's
-* `renderer.info`).
+* Where the frame went — the breakdown `stats()` could not give.
+*
+* fps and frameMs are a TOTAL, and a total has no next question. This engine
+* has already lost a day to that: a frame drop everyone attributed to the GPU
+* turned out to be garbage collection, and nothing on screen could have said
+* so. Three of a frame's four parts are the engine's own work, and the fourth
+* is what is left — which is exactly where GC and browser work hide.
+*
+* Means over the same rolling window as `frameMs`, so the numbers are
+* comparable to each other and to the whole.
 */
+/** One frame's own accounting, in milliseconds. */
+interface FramePhases {
+  /** Fixed steps: physics, and anything on `fixedUpdate`. */
+  fixedMs: number;
+  /** The variable update: behaviors, node logic, tweens. */
+  updateMs: number;
+  /** Whatever renders, as reported by it. 0 when nothing does (headless). */
+  renderMs: number;
+  /**
+  * The frame minus the three above. GC, browser layout, input handling,
+  * anything outside the engine's own loop — and the one to look at when the
+  * others are small and the frame is not.
+  */
+  otherMs: number;
+}
+//#endregion
+//#region src/core/stats.d.ts
 /** Loop-side counters from `engine.stats()` — queryable at any time. */
 interface EngineStats {
   /** Frames per second over the last ~60 REAL ticks (headless runs: 0). */
@@ -1427,6 +1502,11 @@ interface EngineStats {
   * this counter exists for.
   */
   errors: number;
+  /**
+  * Where the frame went: fixed (physics), update (behaviors), render, and
+  * everything else. Means over the same window as `frameMs`.
+  */
+  phases: FramePhases;
 }
 /** GPU-side counters from `renderer.stats()` — the LAST rendered frame. */
 interface RendererStats {
@@ -1491,6 +1571,12 @@ declare class Engine {
   *  routes its volume through this; games set it for global volume/mute. */
   readonly audio: AudioBuses;
   /**
+  * What SHOWED — the visual half of the audio record. Particle bursts, camera
+  * shake, screen flash and freeze frames land here, so "did the explosion
+  * fire?" is answerable in a run with no renderer.
+  */
+  readonly effects: EffectLog;
+  /**
   * Persisted player settings — volume, quality, sensitivity.
   *
   * `createSaveStore` was good and had zero callers, so every game's volume
@@ -1533,6 +1619,10 @@ declare class Engine {
   private accumulator;
   private disposeScheduler;
   private readonly frameStats;
+  /** Where each frame's time went — the breakdown `frameMs` alone cannot give. */
+  private readonly phaseTimings;
+  /** This frame's render cost, as reported by whoever renders. */
+  private renderMs;
   /**
   * Game-time multiplier: 1 = realtime, 0.5 = slow motion, 0 = frozen
   * (hit-stop / pause). Scales BOTH variable and fixed updates — physics,
@@ -1626,6 +1716,15 @@ declare class Engine {
   erroredNodes(): Node[];
   /** Un-skip every quarantined node — the "try again" after you fix the code. */
   resumeErroredNodes(): number;
+  /**
+  * How long the last render took, in ms — called by whoever renders.
+  *
+  * The engine does not render, so this is the one slice it cannot measure for
+  * itself; without it the cost lands in `otherMs` beside the GC and the two
+  * are indistinguishable, which is the confusion this whole breakdown exists
+  * to end.
+  */
+  noteRenderMs(ms: number): void;
   stop(): void;
   /**
   * Live performance counters, queryable at ANY time. fps/frameMs come from a
@@ -1651,12 +1750,17 @@ declare class Engine {
   dispose(): void;
   /**
   * Advance exactly ONE fixed step and one variable update (both dt = the
-  * fixed step), bypassing the wall-clock accumulator entirely. Drift-free
-  * by construction — the unit of time for headless harnesses (incanto/test
-  * runScript): every input edge is visible to BOTH fixedUpdate and update
-  * exactly once.
+  * fixed step scaled by `timeScale`), bypassing the wall-clock accumulator
+  * entirely. Drift-free by construction — the unit of time for headless
+  * harnesses (incanto/test runScript): every input edge is visible to BOTH
+  * fixedUpdate and update exactly once.
+  *
+  * `ignorePause: true` steps a frame at full scale even while the game is
+  * paused — the debug overlay's single-step button, and nothing else.
   */
-  step(): void;
+  step(opts?: {
+    ignorePause?: boolean;
+  }): void;
   /** Advance the loop manually. First call after (re)start only primes the clock. */
   tick(nowMs: number): void;
 }
@@ -1824,4 +1928,4 @@ declare function registeredBehaviors(): string[];
 /** Test isolation helper. */
 declare function clearBehaviors(): void;
 //#endregion
-export { T_PREFIX as $, SettingsValues as A, LogEntry as At, captureBehaviors as B, EngineStats as C, MusicTrack as Ct, QualityCaps as D, Node as Dt, DeviceHints as E, BusName as Et, BehaviorState as F, ORDER_GROUP_BASE as G, savesWithoutUid as H, RestoreReport as I, effectiveOrder as J, OrderGroup as K, SaveSlot as L, readDeviceHints as M, LogManager as Mt, suggestQuality as N, Signal as Nt, QualityTier as O, NodeLifecycle as Ot, Scene as P, SignalListener as Pt, Localization as Q, SaveSlots as R, Scheduler as S, MusicManager as St, RendererStats as T, AudioBuses as Tt, SaveStore as U, restoreBehaviors as V, createSaveStore as W, BASE_LOCALE as X, resolveOrderGroups as Y, LocaleTables as Z, mergeStaticSignals as _, SfxParams as _t, clearBehaviors as a, isAudioContextAvailable as at, Engine as b, synthSfx as bt, registeredBehaviors as c, Listener as ct, PropSchema as d, SpatialParams as dt, suggestLocale as et, clearRegistry as f, Vec3 as ft, getNodeType as g, SFX_PRESET_NAMES as gt, getNodeSignals as h, SFX_PRESETS as ht, behaviorSignals as i, SfxPlayOptions as it, qualityEnvironment as j, LogLevel as jt, Settings as k, SceneTree as kt, NodeCtor as l, ROLLOFF_MODELS as lt, getNodeSchema as m, spatialPan as mt, BehaviorCtor as n, InputMap as nt, getBehavior as o, Voice as ot, createNode as p, spatialGain as pt, OrderGroupTable as q, behaviorSchema as r, SfxEngine as rt, registerBehavior as s, VoicePreset as st, Behavior as t, translationKey as tt, PropDef as u, RolloffModel as ut, registerNode as v, SfxWave as vt, GameStats as w, PlayMusicOptions as wt, EngineOptions as x, MusicBackend as xt, registeredTypes as y, SynthOptions as yt, behaviorsWithoutSave as z };
+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 };

package/dist/{create-game-9D87XaiX.js → create-game-BRt6XKmP.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { A as registerBehavior, C as diagnose, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-BTkHYrQn.js";
-import { b as AudioPlayer, x as Engine } from "./register-BTomIiYG.js";
+import { b as AudioPlayer, x as Engine } from "./register-p48lHE2o.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BnMyy9tr.js";
-import { a as openBundledEditor, c as audioErrors, i as devServerLibrary, n as pauseWhenHidden, r as crossFade, s as claimCanvasGestures, t as teardown } from "./teardown-Bw2aeyGI.js";
-import { n as registerGameplayBehaviors } from "./gameplay-CRYw_Q-T.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-DROK2l7J.js";
+import { a as openBundledEditor, c as audioErrors, i as devServerLibrary, n as pauseWhenHidden, r as crossFade, s as claimCanvasGestures, t as teardown } from "./teardown-C7uVSJvx.js";
+import { n as registerGameplayBehaviors } from "./gameplay-CZ2yq37J.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-en63AEZO.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-BhZZ-HAp.js";
+import { n as enablePhysics2D } from "./physics-2d-CfWAggJ1.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
 /**
@@ -333,7 +333,11 @@ var Renderer2D = class {
 		this.selectionLines.renderOrder = 1e4;
 		this.selectionLines.visible = false;
 		this.worldScene.add(this.selectionLines);
-		this.disconnect = this.engine.updated.connect(() => this.render());
+		this.disconnect = this.engine.updated.connect(() => {
+			const started = performance.now();
+			this.render();
+			this.engine.noteRenderMs(performance.now() - started);
+		});
 	}
 	debugLines;
 	selectionLines;