incanto 0.69.0 → 0.71.0

package/bin/incanto-multiplay.mjs

@@ -17,10 +17,11 @@
  * reconnect that never re-joins, a throttle that discards a payload, a batch
  * dropped on a closed socket.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { behaviorFiles, behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -37,6 +38,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)
+                     comma-separate or repeat for several files
   --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
@@ -65,7 +67,7 @@ const { playMultiplayer, multiplayText, registerAllNodes } = await import(
 );
 registerAllNodes();
 
-const sceneJson = JSON.parse(readFileSync(scenePath, 'utf-8'));
+const sceneJson = readJson(scenePath);
 const sceneDir = dirname(scenePath);
 
 // Without the game's own behaviours a scene that names one throws
@@ -73,9 +75,9 @@ const sceneDir = dirname(scenePath);
 // given them, and stub what is left. A stubbed behaviour still lets the
 // SCENE's replication run, which is what this command measures.
 const behaviorsFile = flag('--behaviors', null);
-if (behaviorsFile) {
+for (const file of behaviorFiles(behaviorsFile)) {
   try {
-    const mod = await import(pathToFileURL(resolve(behaviorsFile)).href);
+    const mod = await import(pathToFileURL(resolve(file)).href);
     const { registerBehavior, Behavior } = await import(
       pathToFileURL(join(PKG, 'dist', 'index.js')).href
     );
@@ -87,7 +89,7 @@ if (behaviorsFile) {
   } catch (e) {
     const why = e?.message ?? String(e);
     reexecUnderBun(import.meta.url, why);
-    console.error(behaviorsHelp(behaviorsFile, why));
+    console.error(behaviorsHelp(file, why));
     process.exit(1);
   }
 }
@@ -105,7 +107,7 @@ const scenes = {};
 for (let i = 0; i < argv.length; i++) {
   if (argv[i] !== '--scenes') continue;
   const [key, file] = String(argv[i + 1] ?? '').split('=');
-  if (key && file) scenes[key] = JSON.parse(readFileSync(resolve(sceneDir, file), 'utf-8'));
+  if (key && file) scenes[key] = readJson(resolve(sceneDir, file));
 }
 const spawnerScenes = new Set();
 const walk = (node) => {
@@ -120,7 +122,7 @@ for (const name of spawnerScenes) {
   for (const guess of [`${name}.scene.json`, `${name}.json`]) {
     const at = resolve(sceneDir, guess);
     if (existsSync(at)) {
-      scenes[name] = JSON.parse(readFileSync(at, 'utf-8'));
+      scenes[name] = readJson(at);
       break;
     }
   }
@@ -182,7 +184,7 @@ try {
     lateJoin: !argv.includes('--no-late-join'),
     load: {
       stubMissingBehaviors: true,
-      resolveScene: (p) => JSON.parse(readFileSync(resolve(sceneDir, p), 'utf-8')),
+      resolveScene: (p) => readJson(resolve(sceneDir, p)),
     },
     // Move the owner, or every replicated key holds its authored value and two
     // motionless clients agree about nothing in particular.

package/bin/incanto-new.mjs

@@ -10,9 +10,11 @@
  * three commands that get you playing. Templates are real npm consumers —
  * no monorepo, no aliases.
  */
-import { cpSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const TEMPLATES_DIR = join(PKG, 'templates-app');
@@ -26,6 +28,7 @@ const DESCRIPTIONS = {
     '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',
+  'molehill-2d': 'played with the MOUSE: whack-a-mole — clickable nodes, no character, no keyboard',
 };
 
 /**
@@ -64,17 +67,46 @@ if (argv.includes('--list') || argv.includes('-l')) {
 
 let target;
 let template = 'beacon-isle-3d';
+/*
+ * An unknown flag is a TYPO, not a request.
+ *
+ * This loop dropped anything it did not recognise, so `--tempalte platformer-2d`
+ * — and `--template=platformer-2d`, which is the form an agent types —
+ * scaffolded the default 3D game and exited 0. The funnel command silently
+ * building the wrong game is the most expensive silence in the package.
+ */
+const usage =
+  'usage: incanto-new <dir> [--template <name>] [--local] | --list\n' +
+  '  --local   pin `file:` to the incanto this command is running from,\n' +
+  '            instead of the registry — for verifying a release candidate.\n' +
+  '            From a source checkout it PACKS first, because a `file:` pin at\n' +
+  '            a workspace package is not installable.';
+const KNOWN_FLAGS = new Set(['--template', '-t', '--local', '--list', '-l', '--help', '-h']);
 for (let i = 0; i < argv.length; i++) {
-  if (argv[i] === '--template' || argv[i] === '-t') template = argv[++i];
-  else if (!argv[i].startsWith('-') && !target) target = argv[i];
+  const a = argv[i];
+  if (a === '--template' || a === '-t') template = argv[++i];
+  else if (a.startsWith('--template=')) template = a.slice('--template='.length);
+  else if (a === '--help' || a === '-h') {
+    console.log(usage);
+    process.exit(0);
+  } else if (a.startsWith('-') && !KNOWN_FLAGS.has(a)) {
+    console.error(`unknown flag '${a}'.\n${usage}`);
+    process.exit(1);
+  } else if (!a.startsWith('-')) {
+    if (target) {
+      console.error(`unexpected argument '${a}' — the template goes after --template.\n${usage}`);
+      process.exit(1);
+    }
+    target = a;
+  }
 }
 
 if (!target) {
-  console.error(
-    'usage: incanto-new <dir> [--template <name>] [--local] | --list\n' +
-      '  --local   pin `file:` to the incanto this command is running from,\n' +
-      '            instead of the registry — for verifying a release candidate.',
-  );
+  console.error(usage);
+  process.exit(1);
+}
+if (template === undefined || template === '') {
+  console.error(`--template needs a name.\n${usage}`);
   process.exit(1);
 }
 
@@ -93,11 +125,52 @@ if (existsSync(dest)) {
 cpSync(join(TEMPLATES_DIR, template), dest, { recursive: true });
 
 const pkgPath = join(dest, 'package.json');
-const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+const pkg = readJson(pkgPath);
 pkg.name = basename(dest)
   .toLowerCase()
   .replace(/[^a-z0-9-]/g, '-');
 
+/**
+ * What `--local` should pin: the directory itself, or a tarball packed from it.
+ *
+ * Only a source checkout needs the pack — that is the one whose `package.json`
+ * still carries the monorepo's `catalog:`/`workspace:` devDependencies, which
+ * bun resolves through a `file:` dependency and cannot find outside the
+ * workspace.
+ */
+function localPin(engineRoot, into) {
+  let manifest;
+  try {
+    manifest = readJson(join(engineRoot, 'package.json'));
+  } catch {
+    return engineRoot;
+  }
+  const unresolvable = Object.values(manifest.devDependencies ?? {}).some(
+    (v) => typeof v === 'string' && (v.startsWith('catalog:') || v.startsWith('workspace:')),
+  );
+  if (!unresolvable) return engineRoot;
+  // `npm pack` runs this package's `prepack`, which strips those devDeps —
+  // exactly the artifact `verify:tarball` installs and proves.
+  const out = spawnSync('npm', ['pack', '--pack-destination', into, '--silent'], {
+    cwd: engineRoot,
+    encoding: 'utf-8',
+  });
+  const name = String(out.stdout ?? '')
+    .trim()
+    .split('\n')
+    .pop();
+  if (out.status !== 0 || !name || !existsSync(join(into, name))) {
+    console.error(
+      `--local: could not pack the engine at ${engineRoot}, and pinning it directly would ` +
+        `produce a project bun cannot install (its devDependencies use the workspace-only ` +
+        `\`catalog:\` protocol).\n${(out.stderr ?? '').trim()}`,
+    );
+    process.exit(1);
+  }
+  console.log(`  packed the engine → ${name}`);
+  return `./${name}`;
+}
+
 /*
  * WHICH incanto this scaffold will install.
  *
@@ -113,7 +186,29 @@ pkg.name = basename(dest)
  */
 const ENGINE_ROOT = PKG;
 if (argv.includes('--local')) {
-  pkg.dependencies = { ...pkg.dependencies, incanto: `file:${ENGINE_ROOT}` };
+  /*
+   * A `file:` pin at a SOURCE CHECKOUT is not installable, and the flag's whole
+   * purpose is to be installed.
+   *
+   * bun resolves a `file:` dependency's devDependencies, and this package's are
+   * monorepo declarations — four of them in bun's workspace-only `catalog:`
+   * protocol. So `bun install` on a `--local` scaffold pinned at
+   * `packages/engine` fails outright and leaves NO node_modules:
+   *
+   *     error: @types/three@catalog: failed to resolve
+   *     error: three@catalog: failed to resolve      … and three more
+   *
+   * `prepack` already strips them for the published artifact, and
+   * `verify:tarball` proves THAT installs — so the fix is to pin what that
+   * step proves rather than the directory it is packed from. Six independent
+   * agents hit this before writing a line of game code; every one of them was
+   * running the bin out of a checkout, which is what an agent testing the
+   * engine does.
+   *
+   * An INSTALLED copy has no such devDeps, so it is pinned directly and nothing
+   * is packed.
+   */
+  pkg.dependencies = { ...pkg.dependencies, incanto: `file:${localPin(ENGINE_ROOT, dest)}` };
 }
 const pin = pkg.dependencies?.incanto ?? '(none)';
 writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);

package/bin/incanto-play.mjs

@@ -15,6 +15,9 @@ import { dirname, join, resolve } from 'node:path';
  *   vector <action> <x> <y>  analog direction ((0 0) clears)
  *   key <code> down|up       raw KeyboardEvent.code    mouse <0|1|2> down|up
  *   pointer <dx> <dy>        look deltas               wheel <dy>
+ *   at <x> <y> | at <path>   put the CURSOR somewhere (a node, or a point)
+ *   click [left|middle|right]  press and release there — a mouse game's whole
+ *                              input, and there was no way to say it
  *   capture [file]           current state as scene JSON (stdout or file)
  *   describe                 one line per node, non-default props only
  *   framing                  what the camera SEES: on/off screen, lights, overlaps
@@ -26,7 +29,8 @@ 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';
+import { behaviorFiles, behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -40,13 +44,19 @@ function parseArgs(argv) {
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--behaviors') args.behaviors = argv[++i];
+    // Repeatable: behaviours legitimately live in more than one file.
+    if (a === '--behaviors') args.behaviors = [...(args.behaviors ?? []), argv[++i]];
     else if (a === '--seed') args.seed = Number(argv[++i]);
     else if (a === '--fixed-hz') args.fixedHz = Number(argv[++i]);
     else if (a === '--commands') args.commands = argv[++i];
     else if (a === '--help' || a === '-h') args.help = true;
     else if (a.startsWith('--')) {
+      // `invalid`, not `help`: printing usage and exiting 0 told an agent its
+      // typo was a request. `--runs=4`, `--behaviours`, `--no-replay` all landed
+      // here and looked like success — and with `--json` the machine path was
+      // literally silent (0 bytes on stdout).
       console.error(`unknown flag: ${a}`);
+      args.invalid = true;
       args.help = true;
     } else if (!args.scene) args.scene = a;
   }
@@ -59,7 +69,7 @@ if (args.help || !args.scene) {
 
 Headless play: stdin commands (step/press/release/vector/key/mouse/pointer/
 wheel/capture/describe/framing/logs/quit), JSON-line responses on stdout.`);
-  process.exit(args.help && args.scene !== undefined ? 0 : 1);
+  process.exit(!args.invalid && args.help && args.scene !== undefined ? 0 : 1);
 }
 
 const out = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);
@@ -69,20 +79,47 @@ const fail = (cmd, e) => {
   out({ ok: false, cmd, error: { code: e?.code ?? 'ERROR', message: e?.message ?? String(e) } });
 };
 
-const { createPlaySession } = await import(pathToFileURL(join(PKG, 'dist', 'test.js')).href);
+const { createPlaySession, geometricPicker, geometricView, pointAtNode } = await import(
+  pathToFileURL(join(PKG, 'dist', 'test.js')).href
+);
 const incanto = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
 
+/**
+ * Let a behaviour ask where the cursor IS, not just what is under it.
+ *
+ * The renderer installs `toWorld`/`toScreen` so game logic can aim; there is no
+ * renderer here, so a game driven from this REPL could be clicked and never
+ * aimed. Same terms as the picker: only if the game brought none.
+ */
+/**
+ * Has anything put the cursor somewhere yet?
+ *
+ * `click` used to fire regardless, so a plan whose `at` failed reported the aim
+ * false and the click true — and the click landed wherever the cursor had been
+ * left, which is (0, 0) at the start of a session.
+ */
+let aimed = false;
+
+const aimFrom = (session) => {
+  if (session.engine.toWorld) return;
+  const view = geometricView(() => session.scene);
+  session.engine.toWorld = view.toWorld;
+  session.engine.toScreen ??= view.toScreen;
+  session.engine.screenRay ??= view.screenRay;
+};
+
 // --behaviors: import the consumer module (TS works on node >= 23.6 / bun)
 // and register every exported Behavior subclass under its export name.
 const behaviors = {};
-if (args.behaviors) {
+const behaviorSources = behaviorFiles(args.behaviors);
+for (const file of behaviorSources) {
   let mod;
   try {
-    mod = await import(pathToFileURL(resolve(args.behaviors)).href);
+    mod = await import(pathToFileURL(resolve(file)).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))
+      e?.code === 'ERR_MODULE_NOT_FOUND' && String(e.message).includes(resolve(file))
         ? 'file not found'
         : (e?.message ?? String(e));
     out({
@@ -90,7 +127,7 @@ if (args.behaviors) {
       cmd: 'behaviors',
       error: {
         code: e?.code ?? 'BEHAVIORS_LOAD_FAILED',
-        message: behaviorsHelp(args.behaviors, reason),
+        message: behaviorsHelp(file, reason),
       },
     });
     process.exit(1);
@@ -100,21 +137,20 @@ if (args.behaviors) {
       behaviors[name] = value;
     }
   }
-  if (Object.keys(behaviors).length === 0) {
-    console.error(`warning: no Behavior subclasses exported from ${args.behaviors}`);
-  }
+}
+if (behaviorSources.length > 0 && Object.keys(behaviors).length === 0) {
+  console.error(`warning: no Behavior subclasses exported from ${behaviorSources.join(', ')}`);
 }
 
-const sceneJson = JSON.parse(readFileSync(resolve(args.scene), 'utf-8'));
+const sceneJson = readJson(resolve(args.scene));
 let session;
 try {
   session = await createPlaySession(sceneJson, {
     behaviors,
-    stubMissingBehaviors: !args.behaviors, // structure-only play without code
+    stubMissingBehaviors: behaviorSources.length === 0, // structure-only play without code
     seed: args.seed,
     fixedHz: args.fixedHz,
-    resolveScene: (p) =>
-      JSON.parse(readFileSync(resolve(dirname(resolve(args.scene)), p), 'utf-8')),
+    resolveScene: (p) => readJson(resolve(dirname(resolve(args.scene)), p)),
   });
 } catch (e) {
   fail('load', e);
@@ -127,7 +163,7 @@ out({
   scene: session.scene.name,
   dimension: session.scene.dimension ?? null,
   behaviors: Object.keys(behaviors),
-  stubbed: !args.behaviors,
+  stubbed: behaviorSources.length === 0,
 });
 
 function handle(line) {
@@ -164,6 +200,81 @@ function handle(line) {
         session.engine.input.handlePointerMove(Number(parts[0]), Number(parts[1]));
         out({ ok: true, cmd });
         break;
+      /*
+       * Where the CURSOR is, and clicking it — the whole input of a match-3, a
+       * tower defense, a card game or a point-and-click.
+       *
+       * `pointer` is a look DELTA, and `mouse` presses a button at wherever the
+       * cursor is not. Headless there is also no renderer to raycast with, so
+       * `engine.picker` is null and `Clickable` is inert: this installs the
+       * geometric one on first use, the same picker `runScript`'s `click` step
+       * uses, so the two drivers answer alike.
+       */
+      case 'at': {
+        const where =
+          parts.length === 1
+            ? pointAtNode(session.scene, parts[0])
+            : [Number(parts[0]), Number(parts[1])];
+        if (!where || !Number.isFinite(where[0]) || !Number.isFinite(where[1])) {
+          out({
+            ok: false,
+            cmd,
+            error:
+              parts.length === 1
+                ? `at '${parts[0]}' — no such node, or it is not on screen`
+                : 'at needs two numbers (scene px) or one node path',
+          });
+          break;
+        }
+        session.engine.picker ??= geometricPicker(() => session.scene);
+        aimFrom(session);
+        session.engine.input.setPointerPosition(where[0], where[1]);
+        aimed = true;
+        out({ ok: true, cmd, at: where });
+        break;
+      }
+      case 'click': {
+        const button = { left: 0, middle: 1, right: 2 }[parts[0] ?? 'left'];
+        if (button === undefined) {
+          out({ ok: false, cmd, error: 'click takes nothing, or left|middle|right' });
+          break;
+        }
+        /*
+         * A click before anything aimed reported `ok: true`.
+         *
+         * The documented plan is `at %Mole; click; step 300`, and when the
+         * `at` fails — an ambiguous `%name`, a node off screen — the click that
+         * follows it clicked wherever the cursor had been left and said so with
+         * a green line. A caller reading `ok` per command sees one false and
+         * one true and concludes the click landed.
+         */
+        if (!aimed) {
+          out({
+            ok: false,
+            cmd,
+            error:
+              'nothing has aimed the cursor yet — `at <node path>` or `at X Y` first. ' +
+              'A click with no aim would land wherever the cursor was left.',
+          });
+          break;
+        }
+        session.engine.picker ??= geometricPicker(() => session.scene);
+        aimFrom(session);
+        const at = session.engine.input.pointerPosition();
+        const under = at ? session.engine.pickAt(at.x, at.y) : null;
+        const hit = under ? under.getPath() : null;
+        // Press, a step, release, a step: `Clickable` fires on the RELEASE over
+        // the node the press started on, and the frame between is where a game
+        // gets to show that it is being pressed.
+        session.engine.input.handleMouseButton(button, true);
+        session.step(16.7);
+        session.engine.input.handleMouseButton(button, false);
+        session.step(16.7);
+        // WHAT it landed on, not merely that it happened: the whole reason to
+        // aim is to hit something, and a caller cannot pick from out here.
+        out({ ok: true, cmd, t: Math.round(session.timeMs), hit });
+        break;
+      }
       case 'wheel':
         session.engine.input.handleWheel(Number(parts[0]));
         out({ ok: true, cmd });
@@ -217,6 +328,37 @@ if (args.commands) {
   // did nothing.
   const recording = text.trimStart().startsWith('{') ? JSON.parse(text) : null;
   if (recording?.replay) {
+    /*
+     * Is this a recording of THIS game?
+     *
+     * `.incanto/playtest` is keyed by `(outcome, seed)` and never cleaned, so
+     * the second playtest in a project leaves a stale `stuck-seed3.json` from a
+     * scene that no longer exists sitting beside the current one — and this
+     * replayed it against whatever scene it was pointed at and reported
+     * success. A replay of the wrong game is worse than no replay: it is a
+     * failure you cannot reproduce and an explanation that is not true.
+     *
+     * Recordings written before this carry no stamp and still play, which is
+     * the point of stamping rather than gating: an old file is not a wrong one.
+     */
+    const stamped = recording.scene;
+    const mine = sceneJson?.name;
+    if (stamped?.name && mine && stamped.name !== mine) {
+      out({
+        ok: false,
+        cmd: 'replay',
+        error: {
+          code: 'REPLAY_SCENE_MISMATCH',
+          message:
+            `this recording is of '${stamped.name}'${stamped.path ? ` (${stamped.path})` : ''} ` +
+            `and you pointed it at '${mine}'. Replays live in .incanto/playtest keyed by ` +
+            `outcome and seed, so an old one from another scene sits right beside the ` +
+            `current ones — check the file, or delete the directory and playtest again.`,
+        },
+      });
+      session.dispose();
+      process.exit(1);
+    }
     incanto.replay(session.engine, recording);
     out({
       ok: true,