incanto 0.65.0 → 0.67.0

package/bin/_behaviors-loader.mjs

@@ -0,0 +1,87 @@
+/**
+ * Load a `--behaviors` file the way the author WROTE it, from any bin.
+ *
+ * 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' }`. Same for an
+ * extensionless relative import (`from './quest'`), which is what the tsconfig
+ * this package scaffolds asks for. Vite reads both. bun reads both. The bins'
+ * shebang is node.
+ *
+ * `incanto-playtest` grew a bun re-exec for exactly this and **the other four
+ * bins that take `--behaviors` never got it**: `feel`, `play`, `verify` and
+ * `multiplay` all died on the shipped `village-quest-3d`, and the only
+ * invocation the docs give (`incanto-verifying-your-game.md`) is the failing
+ * form. Worse, `verify:templates` — the gate step added specifically to run a
+ * template under node's resolver — runs `incanto-playtest`, the one bin whose
+ * fallback hides the failure. The step built to catch this class was
+ * neutralised by the thing it was built to catch.
+ *
+ * So the fallback lives here, once, and every bin uses it. Set
+ * `INCANTO_NO_BUN_REEXEC=1` to forbid it — that is how the gate exercises the
+ * resolver a user actually gets.
+ */
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Is this node refusing the file, rather than the file being wrong?
+ *
+ * Matched against the SPECIFIER where node gives us one. Node words the
+ * extensionless failure as `Cannot find module '<resolved path>' imported from
+ * '<importer>'`, and a check that reads the importer collapses it into
+ * "(file not found)" naming the file that plainly exists — which is what the
+ * author sees and cannot act on.
+ */
+export function nodeCannotReadIt(why) {
+  return (
+    /import attribute|Unknown file extension|Cannot find module|ERR_MODULE_NOT_FOUND|ERR_UNSUPPORTED_[A-Z_]+/i.test(
+      String(why),
+    ) ||
+    // Node's type stripping ERASES types; it does not transform. Anything that
+    // needs a transform is refused by name, and the wording is nothing like the
+    // resolver's. Measured on the shipped `racing-3d` example:
+    //
+    //   x TypeScript parameter property is not supported in strip-only mode
+    //
+    // `constructor(private root: Node3D)` is ordinary TypeScript that vite and
+    // bun both compile, and the bin gave up with "Pass the file that exports
+    // your Behavior subclasses" — telling the author their correct file was
+    // wrong. Enums and namespaces are refused the same way.
+    /strip-only mode|is not supported in strip|only mode|TypeScript parameter property|Unsupported TypeScript/i.test(
+      String(why),
+    )
+  );
+}
+
+/**
+ * Re-run this bin under bun, once, if node is the reason it failed.
+ *
+ * Never returns when it re-execs. Returns false when it did not (already bun,
+ * already re-execed, forbidden, no bun on PATH, or a real error in the file).
+ */
+export function reexecUnderBun(entryUrl, why) {
+  if (!nodeCannotReadIt(why)) return false;
+  if (process.versions.bun) return false;
+  if (process.env.INCANTO_BUN_REEXEC || process.env.INCANTO_NO_BUN_REEXEC) return false;
+  if (spawnSync('bun', ['--version'], { stdio: 'ignore' }).status !== 0) return false;
+  const here = new URL(entryUrl).pathname;
+  const again = spawnSync('bun', [here, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: { ...process.env, INCANTO_BUN_REEXEC: '1' },
+  });
+  process.exit(again.status ?? 1);
+}
+
+/** The sentence to print when the re-exec was not available. */
+export function behaviorsHelp(file, why) {
+  return (
+    `could not load --behaviors '${file}' (${why}).` +
+    (nodeCannotReadIt(why)
+      ? '\n\nThis is usually node refusing your file rather than a problem with it:' +
+        "\nnode cannot import JSON from a .ts module without `with { type: 'json' }`," +
+        '\nand it will not resolve an extensionless relative import. Both are what' +
+        '\nthe scaffolded tsconfig asks you to write. Run it with bun, which reads' +
+        '\nthe file as written — prefix any incanto command with `bunx --bun`.'
+      : '\nPass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.')
+  );
+}

package/bin/incanto-editor.mjs

@@ -200,6 +200,29 @@ async function proxyLibrary(req, res, url) {
   }
 }
 
+/**
+ * What kind of project is this — read from the scenes already in it.
+ *
+ * A 3D game's new scene must not be born 2D, and the only thing that knows
+ * which is which is what is already on disk. Returns null for an empty project,
+ * where there is genuinely nothing to go on.
+ */
+function projectDimension() {
+  let d2 = 0;
+  let d3 = 0;
+  for (const entry of discoverScenes()) {
+    try {
+      const json = JSON.parse(readFileSync(join(ROOT, entry.rel ?? entry), 'utf8'));
+      if (json?.dimension === '3d') d3 += 1;
+      else if (json?.dimension === '2d') d2 += 1;
+    } catch {
+      // not a scene, or unreadable — the scene browser already says so
+    }
+  }
+  if (d3 === 0 && d2 === 0) return null;
+  return d3 > d2 ? '3d' : '2d';
+}
+
 function discoverScenes() {
   const found = [];
   const walk = (dir, depth) => {
@@ -418,12 +441,26 @@ const server = createServer((req, res) => {
           return send(res, 409, JSON.stringify({ error: `already exists: ${wanted}` }));
         }
         const name = basename(abs).replace(/\.scene\.json$|\.json$/, '') || 'Scene';
+        /*
+         * A 3D project's new scene must not be born 2D.
+         *
+         * This hardcoded `dimension: '2d'` / `Node2D` and ignored `body`
+         * entirely, so every scene the editor created in a 3D game was the
+         * wrong kind — and node types are IMMUTABLE by design, so the halfway
+         * state (a 3D header over a Node2D root) is easy to reach through the
+         * header's dimension select and is written back with a 200.
+         *
+         * Asked for explicitly, or guessed from the project: whatever the
+         * sibling scenes are is overwhelmingly what the next one should be.
+         */
+        const asked = body?.dimension === '3d' || body?.dimension === '2d' ? body.dimension : null;
+        const dimension = asked ?? projectDimension() ?? '2d';
         const scene = {
           format: 1,
           type: 'scene',
-          dimension: '2d',
+          dimension,
           name,
-          root: { name, type: 'Node2D' },
+          root: { name, type: dimension === '3d' ? 'Node3D' : 'Node2D' },
         };
         try {
           mkdirSync(dirname(abs), { recursive: true });

package/bin/incanto-feel.mjs

@@ -21,6 +21,7 @@ import { dirname, join, resolve } from 'node:path';
  * wrong for most games.
  */
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -63,7 +64,9 @@ if (args.behaviors) {
   try {
     mod = await import(pathToFileURL(resolve(args.behaviors)).href);
   } catch (e) {
-    console.error(`could not load --behaviors '${args.behaviors}' (${e?.message ?? e}).`);
+    const why = e?.message ?? String(e);
+    reexecUnderBun(import.meta.url, why);
+    console.error(behaviorsHelp(args.behaviors, why));
     process.exit(1);
   }
   for (const [name, value] of Object.entries(mod)) {

package/bin/incanto-frame.mjs

@@ -150,11 +150,33 @@ const discovered = explicit ? [explicit] : await listeningPorts({ read });
 const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
 
 let found = null;
+/**
+ * WHOSE dev server answered.
+ *
+ * This scans a port range, so before the ping carried identity, whoever
+ * answered first won — and a passing number from ANOTHER project silently
+ * overrode this one's failing one. Measured: project A on :5188 with a real
+ * page reported "the subject fills almost nothing (0.3%)", while `incanto
+ * verify` scanning from the same directory reported `✓ draws — 37.5%`,
+ * measured on project B. Corroboration from the other direction: four scenes
+ * across two unrelated projects all reported 22.6%.
+ *
+ * So: prefer the server rooted at THIS directory. If several answer and none is
+ * ours, refuse and list them — the same refusal `verify` already makes when a
+ * project has several scenes and guessing would verify the wrong one.
+ */
+const answered = [];
 // BOTH hosts, deliberately: vite binds to ::1 on some machines and 127.0.0.1 on
 // others, and a probe of the wrong one reports "no dev server" while the page
 // is plainly on screen.
 const HOSTS = ['localhost', '127.0.0.1'];
-outer: for (const port of ports) {
+const CWD = process.cwd();
+const sameProject = (b) => {
+  if (!b?.root) return false;
+  const r = String(b.root);
+  return r === CWD || CWD.startsWith(`${r}/`) || r.startsWith(`${CWD}/`);
+};
+for (const port of ports) {
   for (const host of HOSTS) {
     try {
       const res = await fetch(`http://${host}:${port}/__incanto/ping`, {
@@ -163,8 +185,8 @@ outer: for (const port of ports) {
       if (!res.ok) continue;
       const body = await res.json();
       if (body?.incanto) {
-        found = { host, port, ...body };
-        break outer;
+        answered.push({ host, port, ...body });
+        break; // one host per port is enough
       }
     } catch {
       // not listening, not ours, or not answering — either way, next
@@ -172,6 +194,33 @@ outer: for (const port of ports) {
   }
 }
 
+if (explicit) {
+  found = answered[0] ?? null;
+} else {
+  const mine = answered.filter(sameProject);
+  if (mine.length > 0) {
+    found = mine[0];
+  } else if (answered.length === 1 && answered[0].root === undefined) {
+    // An older dev server that predates the identity field. Take it, but say so.
+    found = answered[0];
+    console.error(
+      `· the dev server on :${found.port} does not report which project it is ` +
+        '(older incanto) — if this reads the wrong game, pass --port.',
+    );
+  } else if (answered.length > 0) {
+    console.error(
+      `${answered.length} incanto dev server(s) are running and NONE of them is this ` +
+        `directory (${CWD}):\n` +
+        answered
+          .map((a) => `  :${a.port}  ${a.project || '(unnamed)'}  ${a.root ?? '?'}`)
+          .join('\n') +
+        "\n\nMeasuring one project on another project's page reports a number that has\n" +
+        "nothing to do with this game. Start this project's dev server, or pass --port.",
+    );
+    process.exit(1);
+  }
+}
+
 if (!found) {
   console.error(
     'no incanto dev server found.\n' +

package/bin/incanto-logs.mjs

@@ -75,7 +75,17 @@ const discovered = explicit ? [explicit] : await listeningPorts({ read });
 const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
 
 let found = null;
-outer: for (const port of ports) {
+// Whose dev server answered — see incanto-frame.mjs for the measurement that
+// made this necessary: a scan takes whoever replies first, and a foreign
+// project's page answered both the frame and the logs request.
+const answered = [];
+const CWD = process.cwd();
+const sameProject = (b) => {
+  if (!b?.root) return false;
+  const r = String(b.root);
+  return r === CWD || CWD.startsWith(`${r}/`) || r.startsWith(`${CWD}/`);
+};
+for (const port of ports) {
   for (const host of ['localhost', '127.0.0.1']) {
     try {
       const res = await fetch(`http://${host}:${port}/__incanto/ping`, {
@@ -84,14 +94,34 @@ outer: for (const port of ports) {
       if (!res.ok) continue;
       const body = await res.json();
       if (body?.incanto) {
-        found = { host, port };
-        break outer;
+        answered.push({ host, port, ...body });
+        break;
       }
     } catch {
       // not listening, not ours, or not answering — next
     }
   }
 }
+if (explicit) {
+  found = answered[0] ? { host: answered[0].host, port: answered[0].port } : null;
+} else {
+  const mine = answered.filter(sameProject);
+  const pick =
+    mine[0] ?? (answered.length === 1 && answered[0].root === undefined ? answered[0] : null);
+  if (pick) found = { host: pick.host, port: pick.port };
+  else if (answered.length > 0) {
+    console.error(
+      `${answered.length} incanto dev server(s) are running and none is this directory ` +
+        `(${CWD}):\n` +
+        answered
+          .map((a) => `  :${a.port}  ${a.project || '(unnamed)'}  ${a.root ?? '?'}`)
+          .join('\n') +
+        "\n\nReading another project's log buffer would report its errors as yours.\n" +
+        "Start this project's dev server, or pass --port.",
+    );
+    process.exit(1);
+  }
+}
 
 if (!found) {
   console.error(

package/bin/incanto-multiplay.mjs

@@ -20,6 +20,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -36,6 +37,7 @@ if (argv.includes('--help') || argv.includes('-h')) {
   --seconds N        simulated seconds (default 5)
   --seed N           make the match reproducible (default 1)
   --behaviors FILE   your Behavior subclasses (.ts works on bun / node >= 23.6)
+  --server FILE      your Server class (default: server/src/server.ts if present)
   --scenes a=b.json  a scene a NetworkSpawner names, repeatable
   --no-late-join     skip the late-joining client
   --json             machine-readable report
@@ -83,7 +85,9 @@ if (behaviorsFile) {
       }
     }
   } catch (e) {
-    console.error(`could not load --behaviors '${behaviorsFile}' (${e?.message ?? e}).`);
+    const why = e?.message ?? String(e);
+    reexecUnderBun(import.meta.url, why);
+    console.error(behaviorsHelp(behaviorsFile, why));
     process.exit(1);
   }
 }
@@ -122,11 +126,56 @@ for (const name of spawnerScenes) {
   }
 }
 
+/**
+ * Your REAL server class, so `agrees` measures the game you ship.
+ *
+ * `playMultiplayer` has always accepted a `server`, and this bin never passed
+ * one — so the rung ran every match against a bare loopback kernel with no
+ * remote functions. Measured: with no server `roomState` came back `{}`, with
+ * one it came back `{"matchMs": 5983.3}`; a `manager.call('claimRelic')` threw
+ * `BAD_FORMAT: Loopback kernel has no remote function 'claimRelic'` and the
+ * report STILL said `ok=true errors=0 problems=[]`. Moving `server/src/server.ts`
+ * out of the tree changed nothing, which is the whole finding: a ✓ that could
+ * not have been a ✗.
+ *
+ * Found where the templates put it, or named with `--server`.
+ */
+let server;
+const serverFlag = flag('--server', null);
+const serverGuesses = serverFlag
+  ? [resolve(serverFlag)]
+  : ['server/src/server.ts', 'server/src/server.js', 'src/server.ts'].map((g) =>
+      resolve(sceneDir, '..', '..', g),
+    );
+for (const at of serverGuesses) {
+  if (!existsSync(at)) continue;
+  try {
+    const mod = await import(pathToFileURL(at).href);
+    server = mod.Server ?? mod.default;
+    if (server) {
+      if (!argv.includes('--json')) console.log(`· server: ${at} (${server.name || 'default'})`);
+      break;
+    }
+  } catch (e) {
+    // A server that cannot be loaded must not read as a game that has none.
+    console.error(
+      `could not load the server at '${at}' (${e?.message ?? e}). ` +
+        'The agreement check would then measure a game without its own rules; refusing.',
+    );
+    process.exit(1);
+  }
+}
+if (serverFlag && !server) {
+  console.error(`--server '${serverFlag}' exports neither \`Server\` nor a default.`);
+  process.exit(1);
+}
+
 let report;
 try {
   report = await playMultiplayer({
     scene: sceneJson,
     scenes,
+    ...(server ? { server } : {}),
     players: Number(flag('--players', 2)) || 2,
     seconds: Number(flag('--seconds', 5)) || 5,
     seed: Number(flag('--seed', 1)) || 1,

package/bin/incanto-play.mjs

@@ -26,6 +26,7 @@ import { dirname, join, resolve } from 'node:path';
  */
 import { createInterface } from 'node:readline';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -79,6 +80,7 @@ if (args.behaviors) {
   try {
     mod = await import(pathToFileURL(resolve(args.behaviors)).href);
   } catch (e) {
+    reexecUnderBun(import.meta.url, e?.message ?? String(e));
     const reason =
       e?.code === 'ERR_MODULE_NOT_FOUND' && String(e.message).includes(resolve(args.behaviors))
         ? 'file not found'
@@ -88,7 +90,7 @@ if (args.behaviors) {
       cmd: 'behaviors',
       error: {
         code: e?.code ?? 'BEHAVIORS_LOAD_FAILED',
-        message: `could not load --behaviors '${args.behaviors}' (${reason}). Pass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.`,
+        message: behaviorsHelp(args.behaviors, reason),
       },
     });
     process.exit(1);

package/bin/incanto-playtest.mjs

@@ -23,6 +23,7 @@ import { dirname, join, resolve } from 'node:path';
  * Exit code 1 when no run reached a win, so CI can gate on it.
  */
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -92,31 +93,8 @@ if (args.behaviors) {
     // and vite resolve it. It broke `incanto verify` on the shipped
     // `village-quest-3d` starter, and it breaks for any author who splits their
     // behaviours across files — which is most of them, eventually.
-    const nodeCannotReadIt = /import attribute|Unknown file extension|Cannot find module/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}' (${why}).` +
-        (nodeCannotReadIt
-          ? '\n\nThis is usually node refusing your file rather than a problem with it:' +
-            "\nnode cannot import JSON from a .ts module without `with { type: 'json' }`," +
-            '\nand it will not resolve an extensionless relative import. Both are what' +
-            '\nthe scaffolded tsconfig asks you to write. Run it with bun, which reads' +
-            '\nthe file as written: `bunx incanto playtest <scene> --behaviors <file>`.'
-          : '\nPass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.'),
-    );
+    reexecUnderBun(import.meta.url, why);
+    console.error(behaviorsHelp(args.behaviors, why));
     process.exit(1);
   }
   for (const [name, value] of Object.entries(mod)) {

package/bin/incanto-verify.mjs

@@ -84,6 +84,19 @@ function findScene() {
 }
 
 const bin = (name) => join(PKG, 'bin', `incanto-${name}.mjs`);
+
+/**
+ * `--port`, passed straight through to the page-reading rungs.
+ *
+ * `draws` and `says` ask a dev server for the browser's answer, and discovery
+ * scans a port range — so with two projects running, this one measured the
+ * OTHER one's page and reported its pass. `incanto-frame`/`incanto-logs` now
+ * refuse a foreign server, and this makes the escape hatch they document
+ * reachable from the rung that actually runs them.
+ */
+const PORT = process.argv.includes('--port')
+  ? ['--port', String(process.argv[process.argv.indexOf('--port') + 1])]
+  : [];
 const run = (name, args) =>
   spawnSync(process.execPath, [bin(name), ...args], {
     encoding: 'utf-8',
@@ -424,7 +437,7 @@ if (rungs[0].status === 'pass') {
 
 // ---- draws ---------------------------------------------------------------
 {
-  const r = run('frame', ['--json']);
+  const r = run('frame', ['--json', ...PORT]);
   const out = safeJson(r.stdout);
   const report = out?.report;
   if (!report) {
@@ -466,7 +479,7 @@ if (rungs[0].status === 'pass') {
  */
 // ---- says ---------------------------------------------------------------
 {
-  const r = run('logs', ['--json']);
+  const r = run('logs', ['--json', ...PORT]);
   const report = safeJson(r.stdout);
   if (!report) {
     rungs.push({

package/dist/2d.d.ts

@@ -1,10 +1,10 @@
-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-CmMuQ6CL.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, x as EngineOptions } from "./behavior-ZnfzKDo3.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-CTB441z4.js";
+import { t as LoadSceneOptions } from "./loader-DyT30ArB.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-BrEHwbK1.js";
+import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-BNUHo0JF.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
 
@@ -157,6 +157,11 @@ declare class StaticBody2D extends PhysicsBody2D {
 */
 declare class Area2D extends PhysicsBody2D {
   static override readonly typeName: string;
+  /**
+  * Who is inside RIGHT NOW — the standing answer behind the enter/exit pair.
+  * See `Area3D.overlapping`. Empty in a scene with no physics world.
+  */
+  overlapping(group?: string): PhysicsBody2D[];
 }
 /** Dynamic simulated body. */
 declare class RigidBody2D extends PhysicsBody2D {
@@ -271,6 +276,21 @@ declare class Physics2D {
   private scopedLines;
   /** Create newly-arrived joints; tear down departed ones. */
   private syncJoints;
+  /** Who is currently inside each sensor/body, maintained from the event drain. */
+  private readonly overlaps;
+  private trackOverlap;
+  /**
+  * Forget every overlap whose node has left the tree.
+  *
+  * The lazy drop inside `overlapping()` only cleans the SETS of a key someone
+  * asks about, and only when they ask. This clears the KEYS, which is where the
+  * dead nodes were pinned.
+  */
+  /** Drop one node from the overlap map, both as a key and as a member. */
+  private forgetOverlaps;
+  private pruneOverlaps;
+  /** The bodies currently overlapping `node`. Freed nodes are dropped on read. */
+  overlapping(node: PhysicsBody2D): PhysicsBody2D[];
   /**
   * World-space raycast in PIXELS (y-down). `exclude` skips that body — a
   * shooter probing from inside its own collider needs it. Sensors (Area2D)
@@ -376,6 +396,18 @@ interface CreateGame2DOptions {
     createElement(tag: string): HTMLElement;
   };
   seed?: number;
+  /**
+  * Namespace this game's persisted settings — volume, language, quality tier.
+  *
+  * They are keyed `incanto:<namespace>:<key>` in the browser's storage and
+  * defaulted to `settings` for everyone, so two Incanto games on one domain
+  * shared one options screen. Measured: game A's player sets `renderScale
+  * 0.25, muted, quality low`; game B, whose source never mentions settings,
+  * boots at a 480x232 drawing buffer and silent.
+  *
+  * `SaveSlots(namespace)` already takes one for exactly this reason.
+  */
+  settings?: EngineOptions["settings"];
   fixedHz?: number;
   /** Renderer extras (pixelRatio, antialias, custom asset store). */
   pixelRatio?: number;
@@ -415,7 +447,22 @@ interface Game2DRenderer extends GameRenderer {
 }
 interface Game2D {
   engine: Engine;
-  scene: Scene$1;
+  /**
+  * The LIVE scene — a getter over `engine.scene`, not a snapshot.
+  *
+  * This used to be the scene captured at boot. `Engine.setScene` calls
+  * `this._scene?.root.free()`, so after any swap the old handle was not merely
+  * stale, it was EMPTIED — and a single-scene game reaches that through
+  * `flow.restart()`, which `incanto-hud.md` wires to a Start button. Measured:
+  *
+  *   before swap  game.scene.root.children = 2   engine.scene = 2
+  *   after  swap  game.scene.root.children = 0   engine.scene = 2
+  *   game.scene.root.getNode('Flow')  ->  No node at 'Flow'. Children here: [].
+  *
+  * `game.engine.scene` always worked and three skills use it, so there were
+  * two handles with one name and no note saying which was which.
+  */
+  get scene(): Scene$1;
   /**
   * What the last drawn frame actually looks like, as numbers.
   *
@@ -719,6 +766,31 @@ declare class Joint2D extends Node2D {
   length: number;
   stiffness: number;
   damping: number;
+  /**
+  * Do the two linked bodies still collide with EACH OTHER?
+  *
+  * `null` (default) decides from the joint type, because the two families want
+  * opposite answers:
+  *
+  * - **pivots** (`fixed`, `spherical`, `revolute`) → **off**. A hinge's bodies
+  *   overlap at the pivot by construction, so the contact solver fights the
+  *   joint and flings them. A puzzle builder's first hinge produced a bar that
+  *   spun chaotically forever and threw a 40 kg box thirty metres, and they
+  *   nearly filed "spherical joints inject energy":
+  *
+  *   ```
+  *   t=   0  Plank r=[0,0,0]      Box [ 0.00, 5.50,  2.40]
+  *   t=3000  Plank r=[-66,24,64]  Box [-29.70, 0.40, -4.91]
+  *   ```
+  *
+  * - **tethers** (`rope`, `spring`) → **on**. These anchor a thing to the world,
+  *   and the thing has to rest on what it is tethered to. Defaulting these off
+  *   drops a barrel roped to the floor straight through it — measured, in this
+  *   repo's own conformance room.
+  *
+  * Set `true`/`false` to say it outright.
+  */
+  collide: boolean | null;
   override onEnterTree(): void;
   /** @internal The two bodies, resolved (throws on a bad target at step time). */
   _resolveBodies(): {

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