incanto 0.56.0 → 0.58.0

package/README.md

@@ -6,7 +6,8 @@ rule is JSON an AI agent can read, diff, and rewrite — rendered by three.js.
 ## Start with a whole game
 
 ```bash
-bunx incanto-new my-game        # Beacon Isle — the flagship 3D template
+bunx incanto new my-game        # Beacon Isle — the flagship 3D template
+bunx incanto new my-2d --template platformer-2d   # the 2D flagship
 cd my-game && bun install && bun run dev
 ```
 
@@ -20,8 +21,9 @@ rest declared in JSON. `bun run verify` plays the entire quest **headlessly**
 and replays recorded input bit-identically: the agent loop is author → verify →
 fix, no browser needed.
 
-`bunx incanto-new --list` shows the other starters (third-person shooter,
-quest vignette).
+`bunx incanto new --list` shows all five starters, grouped by dimension: three
+3D (island adventure, third-person shooter, quest vignette) and two 2D
+(platformer, survivors-like).
 
 ## Or wire the engine yourself
 
@@ -76,7 +78,7 @@ in a world full of them). In code: `physics.debugDraw = true` + `physics.debugSc
 
 ## The agent8 asset library
 
-`bunx incanto-editor --token <v8 access token>` (or `INCANTO_V8_TOKEN`) adds a
+`bunx incanto editor --token <v8 access token>` (or `INCANTO_V8_TOKEN`) adds a
 **📚** button to every field that takes a resource — model, texture, sprite
 sheet, sound. Shelves, search, real previews (a GLB is rendered by the engine
 itself), and one pick writes the URL, or the scene `assets{}` entry plus its

package/bin/incanto-check.mjs

@@ -14,6 +14,7 @@
  * each scene file.
  */
 import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -87,6 +88,15 @@ function missingArt(file, json) {
       join(sceneDir, '..', rel),
     ];
     if (candidates.some((p) => existsSync(p))) continue;
+    // A BARE PACKAGE SPECIFIER is a bundler import, not a path — and it is the
+    // form the assets skill teaches for built-in art
+    // (`incanto/assets/items/coin.png`). A scene had no way to say "this URL
+    // arrives from the bundler": a made-up placeholder (`$KNIGHT_URL`) got
+    // flagged here as art nobody copied, and an empty string — which the loop
+    // above still skips — is rejected outright by the loader. So the honest
+    // spelling was unwritable, and every 2D example that uses built-in art
+    // warned about art that works.
+    if (resolvesAsPackageAsset(url, sceneDir)) continue;
     out.push(
       `$${key} → ${url} is not in the project ` +
         `(looked in ${relativeish(root, join(root, 'public'))}, ${relativeish(root, root)}` +
@@ -96,6 +106,23 @@ function missingArt(file, json) {
   return out;
 }
 
+/**
+ * Can this url be resolved as a file inside an installed package?
+ *
+ * `incanto/assets/items/coin.png` is what the bundler is handed and what the
+ * skills teach; if the package resolves it, the file is really there.
+ */
+function resolvesAsPackageAsset(url, from) {
+  if (url.startsWith('.') || url.startsWith('/')) return false;
+  // A bare specifier: `pkg/path` or `@scope/pkg/path`.
+  if (!/^(@[^/]+\/)?[^@/][^/]*\//.test(url)) return false;
+  try {
+    return existsSync(createRequire(join(from, 'noop.js')).resolve(url));
+  } catch {
+    return false;
+  }
+}
+
 /** Nearest ancestor with a package.json, else the scene's own directory. */
 function projectRoot(from) {
   let dir = resolve(from);

package/bin/incanto-new.mjs

@@ -2,9 +2,9 @@
 /**
  * incanto-new — scaffold a ready-to-run incanto game from a shipped template:
  *
- *   bunx incanto-new my-game                       # Beacon Isle (3D flagship)
- *   bunx incanto-new my-game --template tps-3d     # third-person shooter
- *   bunx incanto-new --list
+ *   bunx incanto new my-game                       # Beacon Isle (3D flagship)
+ *   bunx incanto new my-game --template tps-3d     # third-person shooter
+ *   bunx incanto new --list
  *
  * Copies the template, names the package after the directory, prints the
  * three commands that get you playing. Templates are real npm consumers —
@@ -19,11 +19,25 @@ const TEMPLATES_DIR = join(PKG, 'templates-app');
 
 const DESCRIPTIONS = {
   'beacon-isle-3d':
-    '3D island action-adventure (the flagship): generated world, quest NPC, terrain-nav enemies, melee',
-  'village-quest-3d': '3D quest vignette: dialogue, scene transitions, patrol AI, sword combat',
+    'island action-adventure (the 3D flagship): generated world, quest NPC, terrain-nav enemies, melee',
+  'village-quest-3d': 'quest vignette: dialogue, scene transitions, patrol AI, sword combat',
   'tps-3d': 'third-person arena shooter: GLB soldier, hitscan rifle, enemy waves',
+  'platformer-2d':
+    'side-scrolling platformer (the 2D flagship): tilemap level, coyote-time jump, follow cam, coins',
+  'star-survivor':
+    'survivors-like: waves that never stop, auto-attack, upgrades, a clock to outlast',
 };
 
+/**
+ * Which half of the engine a starter belongs to.
+ *
+ * The list was three templates, all 3D, printed in one alphabetical column —
+ * while the engine shipped a whole 2D half with its own nodes, physics,
+ * tilemaps and skill. Someone building a 2D game read that list and concluded
+ * there was nothing for them.
+ */
+const DIMENSION = (name) => (name.endsWith('-2d') || name === 'star-survivor' ? '2d' : '3d');
+
 function listTemplates() {
   if (!existsSync(TEMPLATES_DIR)) return [];
   return readdirSync(TEMPLATES_DIR, { withFileTypes: true })
@@ -34,9 +48,17 @@ function listTemplates() {
 
 const argv = process.argv.slice(2);
 if (argv.includes('--list') || argv.includes('-l')) {
-  for (const t of listTemplates()) {
-    console.log(`  ${t.padEnd(20)} ${DESCRIPTIONS[t] ?? ''}`);
+  const all = listTemplates();
+  for (const [dim, heading] of [
+    ['3d', '3D'],
+    ['2d', '2D'],
+  ]) {
+    const group = all.filter((t) => DIMENSION(t) === dim);
+    if (group.length === 0) continue;
+    console.log(`\n  ${heading}`);
+    for (const t of group) console.log(`    ${t.padEnd(20)} ${DESCRIPTIONS[t] ?? ''}`);
   }
+  console.log('\n  bunx incanto new my-game --template <name>   (default: beacon-isle-3d)\n');
   process.exit(0);
 }
 

package/bin/incanto-playtest.mjs

@@ -78,9 +78,35 @@ if (args.behaviors) {
   try {
     mod = await import(pathToFileURL(resolve(args.behaviors)).href);
   } catch (e) {
+    const why = e?.message ?? String(e);
+    // NODE CANNOT IMPORT THE PATTERN WE TEACH. Every template's behaviors.ts
+    // does `import gameJson from './game.scene.json'` — the documented way to
+    // read your own scene — and node's type stripping refuses a JSON import
+    // without `with { type: 'json' }`. Vite is fine with it, bun is fine with
+    // it, and this bin's shebang is node, so `--behaviors` failed on the
+    // engine's own flagship template. Hand the work to bun rather than telling
+    // the author their file is wrong: it is not.
+    const nodeCannotReadIt = /import attribute|Unknown file extension/i.test(why);
+    if (nodeCannotReadIt && !process.versions.bun && !process.env.INCANTO_BUN_REEXEC) {
+      const { spawnSync } = await import('node:child_process');
+      const hasBun = spawnSync('bun', ['--version'], { stdio: 'ignore' }).status === 0;
+      if (hasBun) {
+        const here = fileURLToPath(import.meta.url);
+        const again = spawnSync('bun', [here, ...process.argv.slice(2)], {
+          stdio: 'inherit',
+          env: { ...process.env, INCANTO_BUN_REEXEC: '1' },
+        });
+        process.exit(again.status ?? 1);
+      }
+    }
     console.error(
-      `could not load --behaviors '${args.behaviors}' (${e?.message ?? e}). ` +
-        'Pass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.',
+      `could not load --behaviors '${args.behaviors}' (${why}).` +
+        (nodeCannotReadIt
+          ? '\n\nThis is node refusing your file, not a problem with it: node cannot' +
+            "\nimport JSON from a .ts module without `with { type: 'json' }`, and every" +
+            '\nincanto template imports its scene that way. Run it with bun, which' +
+            '\nreads the file as written: `bunx incanto playtest <scene> --behaviors <file>`.'
+          : '\nPass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.'),
     );
     process.exit(1);
   }

package/bin/incanto-verify.mjs

@@ -20,7 +20,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -102,21 +102,55 @@ if (!existsSync(scene) || !statSync(scene).isFile()) {
   process.exit(1);
 }
 
-const behaviors = flag('--behaviors');
+/**
+ * Find the file that holds the game's Behavior subclasses.
+ *
+ * The scene was auto-discovered from the start; the behaviours were not, and
+ * without them a playtest runs the STRUCTURE with every script stubbed. On the
+ * engine's own flagship template that means the quest never advances, so bare
+ * `incanto-verify` — the exact command the README prints — reported `plays` as
+ * a failure and told the reader to re-run a different tool by hand, with the
+ * path to a file sitting right next to the scene it had already found.
+ */
+function findBehaviors(sceneFile) {
+  const named = flag('--behaviors');
+  if (named) return { file: named, guessed: false };
+  const near = dirname(sceneFile);
+  for (const dir of [near, join(near, '..'), process.cwd(), join(process.cwd(), 'src')]) {
+    for (const base of ['behaviors', 'behaviours']) {
+      for (const ext of ['.ts', '.js', '.mjs']) {
+        const candidate = join(dir, base + ext);
+        if (existsSync(candidate) && statSync(candidate).isFile()) {
+          return { file: candidate, guessed: true };
+        }
+      }
+    }
+  }
+  return { file: null, guessed: false };
+}
+
+const { file: behaviors, guessed: guessedBehaviors } = findBehaviors(scene);
 const rungs = [];
 
 // ---- loads ---------------------------------------------------------------
 {
   const r = run('check', [scene, '--json']);
   const out = safeJson(r.stdout);
-  const problems = out?.files?.flatMap((f) => f.problems ?? []) ?? [];
+  // `incanto-check --json` emits { ok, results: [{ file, ok, code, message }] }.
+  // This read `out.files[].problems[].why` — three keys that have never existed —
+  // so the summary always fell through to the first line of the pretty-printed
+  // JSON, which is `{`. Every scene-validation failure, the top rung of the
+  // ladder, rendered as `✗ loads — {` with the sentence naming the node path and
+  // 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;
   rungs.push(
     r.status === 0
       ? { name: 'loads', status: 'pass', summary: 'the scene is legal and its assets resolve' }
       : {
           name: 'loads',
           status: 'fail',
-          summary: problems[0]?.why ?? firstLine(r.stdout || r.stderr) ?? 'incanto-check failed',
+          summary: detail ?? firstLine(r.stderr) ?? 'incanto-check failed',
           fix: `fix that, then run again — nothing above this rung means anything until it is green (\`incanto-check ${scene}\` for the detail)`,
         },
   );
@@ -138,25 +172,61 @@ 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
+  // `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));
+  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` }
-      : noGoal
+      : playedOut
         ? {
             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)` : 'the playtest could not run',
-            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\``,
-          },
+              `${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\``,
+            },
   );
 } else {
   rungs.push({ name: 'plays', status: 'skipped', summary: 'not run — the scene does not load' });
@@ -291,7 +361,16 @@ function firstLine(text) {
 }
 
 const verdict = ladderVerdict(rungs);
-console.log(asJson ? JSON.stringify({ scene, ...verdict }, null, 2) : ladderText(verdict));
+if (asJson) {
+  console.log(JSON.stringify({ scene, behaviors, ...verdict }, null, 2));
+} else {
+  if (guessedBehaviors) {
+    console.log(
+      `· behaviours: ${relative(process.cwd(), behaviors) || behaviors} (found, not named)`,
+    );
+  }
+  console.log(ladderText(verdict));
+}
 // `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

package/bin/incanto.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * incanto — the front door.
+ *
+ *   bunx incanto new my-game        scaffold a game (no install needed first)
+ *   bunx incanto check src          validate scene JSON
+ *   bunx incanto verify             the whole verification ladder
+ *
+ * WHY THIS EXISTS. Every doc used to open with `bunx incanto-new my-game`, and
+ * that command 404s for the one person it is written for. `bunx <name>` fetches
+ * the PACKAGE called `<name>`; it does not search the registry for a package
+ * that happens to ship a bin by that name. There is no `incanto-new` package,
+ * so a brand-new reader's very first command failed — while every existing
+ * consumer ran it happily, because with `incanto` already in `node_modules` the
+ * same words resolve to the local bin. The funnel was the one path nobody
+ * walked.
+ *
+ * `bunx incanto <subcommand>` works from nothing, because `incanto` IS the
+ * package name. The `incanto-*` bins all still exist and are unchanged — inside
+ * a project they are the shorter thing to type.
+ *
+ * Dispatch is an in-process import, not a spawn: the child bin then runs under
+ * the SAME runtime that started this one, which matters because `--behaviors`
+ * loads your TypeScript and bun and node disagree about what they can import.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Subcommand → bin file, in the order the help should list them. */
+const COMMANDS = {
+  new: ['incanto-new.mjs', 'scaffold a ready-to-run game from a template'],
+  check: ['incanto-check.mjs', 'validate scene JSON and the assets it names'],
+  verify: ['incanto-verify.mjs', 'the whole ladder: loads · plays · feels · draws · says'],
+  playtest: ['incanto-playtest.mjs', 'drive the game headlessly and report what happened'],
+  play: ['incanto-play.mjs', 'run a scene headlessly for a fixed span'],
+  feel: ['incanto-feel.mjs', 'measure jump height, run speed, facing'],
+  frame: ['incanto-frame.mjs', 'what the running page is drawing right now'],
+  logs: ['incanto-logs.mjs', 'what the running page has been saying'],
+  editor: ['incanto-editor.mjs', 'the visual scene composer'],
+  model: ['incanto-model.mjs', "a GLB's real bounds, animations and rig"],
+  assets: ['incanto-assets.mjs', 'the built-in art and audio catalog'],
+  env: ['incanto-env.mjs', 'generate a 3D environment'],
+  skills: ['incanto-skills.mjs', 'install the agent skills for this engine version'],
+};
+
+function version() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf-8'));
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function help() {
+  const width = Math.max(...Object.keys(COMMANDS).map((k) => k.length));
+  const lines = Object.entries(COMMANDS).map(
+    ([name, [, blurb]]) => `  ${name.padEnd(width)}  ${blurb}`,
+  );
+  return [
+    `incanto ${version()} — a vibe-coding-first web game engine`,
+    '',
+    'Usage: bunx incanto <command> [options]',
+    '',
+    ...lines,
+    '',
+    'Start a game:      bunx incanto new my-game',
+    'See the templates: bunx incanto new --list',
+    '',
+    'Each command also ships as its own bin (`incanto-new`, `incanto-check`, …),',
+    'which is what to type once the package is installed in your project.',
+  ].join('\n');
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (!command || command === '--help' || command === '-h' || command === 'help') {
+  console.log(help());
+  process.exit(0);
+}
+if (command === '--version' || command === '-v') {
+  console.log(version());
+  process.exit(0);
+}
+
+const entry = COMMANDS[command];
+if (!entry) {
+  const near = Object.keys(COMMANDS).filter((k) => k.startsWith(command[0] ?? ''));
+  console.error(
+    `incanto: unknown command '${command}'.` +
+      (near.length ? ` Did you mean: ${near.join(', ')}?` : '') +
+      '\n\n' +
+      help(),
+  );
+  process.exit(2);
+}
+
+const target = join(HERE, entry[0]);
+// The child reads `process.argv.slice(2)`, so hand it an argv that looks like
+// it was invoked directly. Importing rather than spawning keeps one process
+// and, more importantly, one runtime.
+process.argv = [process.argv[0], target, ...rest];
+await import(pathToFileURL(target).href);

package/dist/2d.d.ts

@@ -1,7 +1,8 @@
-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 { 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-l08AEbq9.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-DhI1jFW_.js";
+import { r as FrameStats } from "./frame-report-DCnHFmto.js";
+import { t as LoadSceneOptions } from "./loader-BbEMTuWg.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
 import { r as ParticleView, t as ParticleSim } from "./particle-sim-C5OfBbmU.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
@@ -388,6 +389,16 @@ interface Game2D {
   engine: Engine;
   scene: Scene$1;
   /**
+  * What the last drawn frame actually looks like, as numbers.
+  *
+  * The 3D game has answered this since 0.47 and a 2D game could not, so
+  * `incanto-frame` and `incanto-verify`'s `draws` rung were permanently
+  * unmeasured for half the engine's games.
+  */
+  frame(opts?: {
+    grid?: [number, number];
+  }): Promise<FrameStats>;
+  /**
   * The AUTHORED scene this game booted from — the JSON, not the live tree.
   * A running tree has moved; the editor gets what was written down.
   */
@@ -691,6 +702,14 @@ declare class Label extends Node2D {
   _quad(): Mesh;
   override _syncObject2D(assets: AssetStore2D | null): void;
   private rasterize;
+  /**
+  * Hand the canvas and its texture back.
+  *
+  * LABEL_PLANE is shared by every Label in the process and stays; the material
+  * and the CanvasTexture are this node's, and a scene that spawns floating
+  * text left one of each behind per freed node.
+  */
+  override free(): void;
 }
 //#endregion
 //#region src/2d/nodes/particles-2d.d.ts
@@ -768,6 +787,15 @@ declare class Particles2D extends Node2D {
   * (dust under a player) as well as the node's own position.
   */
   private holdWorldSpace;
+  /** What the current mesh was built FOR — capacity and blend, the two things
+  *  baked into it. Not the draw count, which changes every frame. */
+  private meshKey;
+  /**
+  * Hand the GPU back. UNIT_PLANE is shared by every 2D particle system in the
+  * process, so the geometry stays; the per-node material and the instance
+  * buffers inside the InstancedMesh do not.
+  */
+  override free(): void;
   /** 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). */
@@ -815,6 +843,8 @@ declare class TileMap2D extends Node2D {
   private _solid;
   /** Rebuild flags — raised when the map-shaping props are REPLACED. */
   private geometryDirty;
+  /** Reported once per atlas, so a bad grid says so on the first build only. */
+  private gridChecked;
   private collidersDirty;
   /** Replace the whole array to change the map (mutations are not watched). */
   get cells(): (string | number[])[];
@@ -909,11 +939,6 @@ interface Renderer2DOptions {
   /** MSAA on the canvas. Defaults to TRUE (Phaser parity). */
   antialias?: boolean;
 }
-/**
-* 2D presentation layer: world pass through the active Camera2D
-* (center/zoom/limits), then a screen-space UI pass for UILayer subtrees.
-* 1 unit = 1 px, (0,0) top-left, +y down.
-*/
 declare class Renderer2D {
   /**
   * When set, the world pass frames THIS view instead of the scene's active
@@ -926,6 +951,33 @@ declare class Renderer2D {
     zoom: number;
   } | null;
   private readonly webgl;
+  /**
+  * The pixels of the next drawn frame — how `incanto-frame` sees a 2D game.
+  *
+  * Mirrors Renderer3D exactly: read inside the render, so
+  * `preserveDrawingBuffer` can stay off, and nudge a frame ourselves after a
+  * moment because a browser stops handing rAF to a tab it thinks is hidden —
+  * including a window merely covered by another one. Without the nudge the
+  * promise never settles and the CLI reports "no page connected" about a page
+  * that is right there.
+  */
+  captureFrame(): Promise<{
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+  }>;
+  private pendingCaptures;
+  /** Hand the waiting captures this frame's pixels. Called at the end of render. */
+  private drainFrameCapture;
+  /** The pixel ratio the scene asked for, before any render-scale setting. */
+  private basePixelRatio;
+  /**
+  * Fewer pixels for the same world — the cheapest frames on a weak device.
+  *
+  * `settings.renderScale` persisted and was applied by the 3D boot only, so a
+  * 2D game's resolution slider saved a number and changed nothing, forever.
+  */
+  setRenderScale(scale: number): void;
   private readonly worldScene;
   private readonly syncScratch;
   /** Editors set this: keep syncing `static: true` subtrees every frame. */

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-YvaNWhe6.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";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-BZwWJIns.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-C6ZBFRjd.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-EqA-jddf.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-CyQoSu4n.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-l08AEbq9.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-DhI1jFW_.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-BbEMTuWg.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-CXGCpRQe.js";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-mEN4V1CU.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";
@@ -902,6 +902,9 @@ declare class Environment3D {
   /** Underwater fog/tint, created lazily the first time the camera submerges. */
   private underwaterFog;
   private readonly underwaterBg;
+  /** Told when the scene's HDRI/preset lighting fails to arrive. Set by the
+  *  renderer, which is the piece that knows the engine and the asset store. */
+  onHdriError: ((url: string, error: unknown) => void) | null;
   constructor(scene: Scene);
   /** The sky's unit sun direction, or null when no sky is declared. */
   get sunDirection(): [number, number, number] | null;
@@ -1141,6 +1144,21 @@ declare class BoneAttachment3D extends Node3D {
   get attachedBone(): Object3D | null;
   _onRender3D(_ctx: RenderContext3D): void;
   override free(): void;
+  /** The model this attachment last looked in. */
+  private source;
+  private reportedBone;
+  /**
+  * Say when the bone NAME is wrong, without accusing a model that is still
+  * loading.
+  *
+  * The lookup retries every frame on purpose — a GLB mounts async — so the
+  * node can never conclude on its own that the name is bad. But once the model
+  * HAS bones and this one is not among them, it is a typo, and the list that
+  * would fix it is sitting in `boneNames()` right next to `findBone`. Until
+  * now a misspelled bone left the sword at the mount node's authored position
+  * while the character animated away from it, forever, in silence.
+  */
+  private reportMissingBone;
 }
 //#endregion
 //#region src/3d/nodes/bone-look-at-3d.d.ts
@@ -1262,6 +1280,18 @@ declare class CharacterController3D extends Node3D {
   private get body();
   override onEnterTree(): void;
   override fixedUpdate(dt: number): void;
+  /** Actions already reported missing, so a per-frame read says it once. */
+  private readonly reportedActions;
+  /**
+  * Read an input action this controller is allowed to be missing.
+  *
+  * Tolerated because a game may declare no sprint key and no jump; reported
+  * because otherwise a TYPO looks exactly like a deliberate omission, and the
+  * engine has already thrown the sentence that fixes it.
+  */
+  private readAction;
+  /** Report a throw the caller already caught (the move read has its own try). */
+  private reportMissingAction;
   override update(dt: number): void;
   private pivot;
   private cameraCache;

package/dist/3d.js

@@ -1,9 +1,9 @@
-import { B as Node3D, F as Area3D, I as CharacterBody3D, L as PhysicsBody3D, M as Water3D, N as WATER_CUTOUT_MAX, P as WaterCutout3D, R as RigidBody3D, U as WATER_MAX_RIPPLES, z as StaticBody3D } from "./gameplay-C_SPzmUe.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-DLHqgNAF.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-CqJkfMzm.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 { 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-BVphcxmE.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-CvvQr_bJ.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-D10bU5_J.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-NzDwWPrF.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-Dnz4fsXX.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;