ravensight-playtest 0.5.2 → 0.7.0

package/src/run/dimension.js

@@ -0,0 +1,95 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Whether a Godot project is 2D or 3D, and what the 3D Alpha says about it.
+ *
+ * Labs beta is Godot 2D. The Alpha is a proof of concept: one template, Build a
+ * feature and Validate changes, each asked for by name with `--alpha-3d`. It adds no
+ * switch and no price: the game's Labs opt-in and the capability's own LABS_* switch
+ * still decide, and the job is priced exactly as a 2D one is.
+ */
+
+export const DIMENSION_2D = '2d';
+export const DIMENSION_3D = '3d';
+
+/**
+ * The type of the main scene's root node, which is what decides what a player sees.
+ *
+ * @param {string} projectDir
+ * @returns {Promise<string|null>} null when there is no readable main scene or root
+ */
+export async function mainSceneRoot(projectDir) {
+  const settings = await readFile(path.join(projectDir, 'project.godot'), 'utf8').catch(() => null);
+  if (settings === null) return null;
+  const main = /^run\/main_scene\s*=\s*"([^"]+)"/m.exec(settings);
+  if (!main) return null;
+  const scene = await sceneText(projectDir, main[1]);
+  const root = scene && /\[node name="[^"]*" type="([A-Za-z0-9_]+)"/.exec(scene);
+  return root ? root[1] : null;
+}
+
+async function sceneText(projectDir, reference) {
+  if (reference.startsWith('res://')) {
+    return readFile(path.join(projectDir, reference.slice('res://'.length)), 'utf8').catch(() => null);
+  }
+  if (!reference.startsWith('uid://')) return null;
+  const stack = [projectDir];
+  let seen = 0;
+  while (stack.length > 0 && seen < 2000) {
+    const directory = stack.pop();
+    const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.name.endsWith('.tscn')) {
+        seen += 1;
+        const text = await readFile(full, 'utf8').catch(() => '');
+        if (text.slice(0, 300).includes(`uid="${reference}"`)) return text;
+      }
+    }
+  }
+  return null;
+}
+
+/** Whether this root type is a 3D one: Node3D, CharacterBody3D and so on. */
+export function isThreeDRoot(root) {
+  return typeof root === 'string' && /3D$/.test(root);
+}
+
+/**
+ * Why this command may not run on this project with these flags, or null. A free
+ * answer, before any price.
+ *
+ * @param {{projectDir: string, alpha3d?: boolean, name: string}} input `name` is the capability, for the sentence
+ * @returns {Promise<{refusal: string|null, dimension: string}>}
+ */
+export async function dimensionGate({ projectDir, alpha3d = false, name }) {
+  const root = await mainSceneRoot(projectDir);
+  const threeD = isThreeDRoot(root);
+  if (threeD && !alpha3d) {
+    return { dimension: DIMENSION_3D, refusal: `The main scene's root is a ${root}. ${name} works on 2D Godot projects in the beta. 3D is an Alpha proof of concept: pass --alpha-3d to ask for it.` };
+  }
+  if (!threeD && alpha3d) {
+    return { dimension: DIMENSION_2D, refusal: `--alpha-3d is for a project whose main scene has a 3D root, and this one's is ${root ? `a ${root}` : 'not one'}. Leave the flag off for a 2D project.` };
+  }
+  return { dimension: threeD ? DIMENSION_3D : DIMENSION_2D, refusal: null };
+}
+
+/**
+ * Whether a brief for Create a game asks for 3D. A brief that says 2D as well goes on,
+ * because "2D, not 3D" is a 2D brief, and the design step can still decline it.
+ *
+ * @param {string} brief
+ * @returns {boolean}
+ */
+export function briefAsksFor3d(brief) {
+  const text = String(brief || '');
+  return /\b(?:3-?d|three[- ]dimensional)\b/i.test(text) && !/\b(?:2-?d|two[- ]dimensional)\b/i.test(text);
+}
+
+/** What create says to a 3D request. Plain, and free. */
+export const CREATE_REFUSES_3D = 'Create a game makes 2D Godot games only, and it does not make a 3D game from a brief. Nothing was charged. The 3D Alpha is a proof of concept that starts from a template you run yourself: ravensight-playtest template godot-3d --game <gameId> --dir <path>. Build a feature and Validate changes then work on it with --alpha-3d.';
+
+export default { mainSceneRoot, isThreeDRoot, dimensionGate, briefAsksFor3d, CREATE_REFUSES_3D, DIMENSION_2D, DIMENSION_3D };

package/src/run/drivers/godot-observation.js

@@ -11,6 +11,9 @@ import { createHash } from 'node:crypto';
 
 export const MAX_TEXT_CHARS = 12000;
 
+/** Shown only when a node has three coordinates, so a 2D observation never changes. */
+export const NOTE_3D = 'note: this scene is 3D. @(x,y,z) is a world position, not a place on the screen: to click one of those nodes, name its path, and never pass its numbers as x and y. Keys and input actions move the player.';
+
 const PRESSABLE = /Button|LineEdit|TextEdit|Slider|CheckBox|CheckButton|OptionButton|ItemList|Tree/;
 
 /**
@@ -38,6 +41,7 @@ export function buildObservation({
   if (state?.current_scene) lines.push(`scene node: ${state.current_scene}`);
   if (collected.scripts.length > 0) lines.push(`scripts: ${collected.scripts.join(', ')}`);
   if (state?.truncated) lines.push('note: the scene tree was truncated');
+  if (kept && hasPosition3d(kept)) lines.push(NOTE_3D);
   if (lines.length > 0) lines.push('');
 
   if (kept) {
@@ -46,16 +50,12 @@ export function buildObservation({
     lines.push('(no visible nodes)');
   }
 
-  const states = gameState?.states ?? {};
-  const stateKeys = Object.keys(states);
-  if (stateKeys.length > 0) {
-    lines.push('', 'game state:');
-    for (const key of stateKeys) {
-      lines.push(`  ${key}: ${JSON.stringify(states[key])}`);
-    }
-  }
-
-  const text = truncate(lines.join('\n'), maxChars);
+  // The game state is what a persona plays from (ember, room, position) and
+  // the first thing a long scene tree used to push past the cap, so it is
+  // bounded on its own and the tree is cut to make room for it.
+  const gameStateText = gameStateSummary(gameState);
+  const stateSection = gameStateText ? `\n\ngame state:\n${gameStateText}` : '';
+  const text = truncate(lines.join('\n'), Math.max(0, maxChars - stateSection.length)) + stateSection;
   const observation = {
     step,
     text,
@@ -65,12 +65,50 @@ export function buildObservation({
     scene: scenePath,
     scenes: collected.scenes,
     scripts: collected.scripts,
+    gameStateText,
     hash: createHash('sha1').update(text).digest('hex'),
   };
   if (screenshotBase64) observation.screenshot_b64 = screenshotBase64;
   return observation;
 }
 
+/** The most characters of one `_ravensight_state()` dictionary shown. */
+export const MAX_STATE_CHARS = 2000;
+
+/** The most characters of the whole game state section. */
+export const MAX_STATE_SECTION_CHARS = 4000;
+
+/**
+ * Every `_ravensight_state()` result as `  <node path>: <json>` lines, each
+ * and all bounded, or '' when the game has no hook.
+ *
+ * @param {object|null} gameState the driver's get_game_state answer
+ * @returns {string}
+ */
+export function gameStateSummary(gameState) {
+  const states = gameState?.states ?? {};
+  const lines = [];
+  let used = 0;
+  for (const key of Object.keys(states)) {
+    let json;
+    try {
+      json = JSON.stringify(states[key]);
+    } catch {
+      json = '"(unserialisable)"';
+    }
+    if (json === undefined) continue;
+    if (json.length > MAX_STATE_CHARS) json = `${json.slice(0, MAX_STATE_CHARS)}... [cut]`;
+    const line = `  ${key}: ${json}`;
+    if (used + line.length > MAX_STATE_SECTION_CHARS) {
+      lines.push(`  (${Object.keys(states).length - lines.length} more state node(s) left out)`);
+      break;
+    }
+    lines.push(line);
+    used += line.length + 1;
+  }
+  return lines.join('\n');
+}
+
 /** True when the outline is too thin to play from, so vision is worth the cost. */
 export function needsVision(observation, { minChars = 200 } = {}) {
   const body = String(observation?.text ?? '')
@@ -110,7 +148,9 @@ function describe(node) {
   const parts = [node.type ?? 'Node', node.name ?? ''];
   if (node.text) parts.push(JSON.stringify(collapse(node.text)));
   if (Array.isArray(node.position)) {
-    parts.push(`@(${node.position.map((value) => round(value)).join(',')})`);
+    // A 3D unit is a metre, where a 2D one is a pixel, so whole numbers would hide a walk.
+    const place = node.position.length === 3 ? round3d : round;
+    parts.push(`@(${node.position.map((value) => place(value)).join(',')})`);
   }
   const flags = [];
   if (node.focus) flags.push('focus');
@@ -124,6 +164,14 @@ function describe(node) {
   return parts.filter(Boolean).join(' ');
 }
 
+function hasPosition3d(node) {
+  return (Array.isArray(node.position) && node.position.length === 3) || (node.children ?? []).some(hasPosition3d);
+}
+
+function round3d(value) {
+  return typeof value === 'number' ? Math.round(value * 100) / 100 : value;
+}
+
 function collapse(text) {
   return String(text).replace(/\s+/g, ' ').trim().slice(0, 200);
 }

package/src/run/drivers/godot-project.js

@@ -11,7 +11,7 @@
 // across every project layout). Both name the same script, so registering both
 // is idempotent, and one of them is guaranteed to be the mechanism Godot
 // honors.
-import { execFile } from 'node:child_process';
+import { execFile, spawn as spawnProcess } from 'node:child_process';
 import net from 'node:net';
 import fs from 'node:fs/promises';
 import os from 'node:os';
@@ -161,6 +161,43 @@ async function materializePath(root, relativePath) {
   }
 }
 
+/**
+ * A real copy of a project, with no link left that points at the developer's files.
+ *
+ * @param {string} projectDir
+ * @param {string} destination
+ * @param {{excludes?: Array<string>, skip?: (source: string) => boolean}} [options]
+ */
+export async function copyProjectTree(projectDir, destination, { excludes = DEFAULT_EXCLUDES, skip = () => false } = {}) {
+  // One dereference of any given directory. measureProject counts a symlinked
+  // tree once, so the copy has to copy it once, or the two disagree and the
+  // cap stops meaning anything.
+  const visited = new Set();
+  const realProjectDir = await realRootOf(projectDir);
+  // dereference: a symlink copied as a symlink still points at the developer's
+  // real file, and every write below would go straight through it.
+  await fs.cp(projectDir, destination, {
+    recursive: true,
+    force: true,
+    dereference: true,
+    filter: async (source) => {
+      if (excludes.includes(path.basename(source)) || skip(source)) return false;
+      const link = await fs.lstat(source).catch(() => null);
+      // fs.cp refuses a named pipe or a socket outright, and neither is part of a game.
+      if (link && (link.isFIFO() || link.isSocket())) return false;
+      if (!link?.isSymbolicLink()) return true;
+      // fs.cp throws ENOENT on a symlink it cannot dereference, and a project
+      // with one broken link in it is not a project that should fail to launch.
+      const real = await fs.realpath(source).catch(() => null);
+      if (!real) return false;
+      if (resolvesIntoOwnAncestry(real, realProjectDir)) return false;
+      if (visited.has(real)) return false;
+      visited.add(real);
+      return true;
+    },
+  });
+}
+
 /**
  * Copies the project and injects the driver addon.
  * Returns the copy's path plus the temp root to delete when the run ends.
@@ -185,31 +222,7 @@ export async function prepareProjectCopy({
     await fs.mkdir(root, { recursive: true, mode: 0o700 });
     await fs.chmod(root, 0o700);
 
-    // One dereference of any given directory. measureProject counts a symlinked
-    // tree once, so the copy has to copy it once, or the two disagree and the
-    // cap stops meaning anything.
-    const visited = new Set();
-    const realProjectDir = await realRootOf(projectDir);
-    // dereference: a symlink copied as a symlink still points at the developer's
-    // real file, and every write below would go straight through it.
-    await fs.cp(projectDir, projectCopy, {
-      recursive: true,
-      force: true,
-      dereference: true,
-      filter: async (source) => {
-        if (excludes.includes(path.basename(source))) return false;
-        const link = await fs.lstat(source).catch(() => null);
-        if (!link?.isSymbolicLink()) return true;
-        // fs.cp throws ENOENT on a symlink it cannot dereference, and a project
-        // with one broken link in it is not a project that should fail to launch.
-        const real = await fs.realpath(source).catch(() => null);
-        if (!real) return false;
-        if (resolvesIntoOwnAncestry(real, realProjectDir)) return false;
-        if (visited.has(real)) return false;
-        visited.add(real);
-        return true;
-      },
-    });
+    await copyProjectTree(projectDir, projectCopy, { excludes });
 
     // Belt and braces: dereference covers the copy, materialize covers anything
     // it left behind, so the three paths written below cannot be links.
@@ -304,6 +317,40 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/** Godot's physical key codes for the keys a game commonly binds, by the name a player would use. */
+const NAMED_KEYS = new Map([
+  [32, 'Space'], [4194305, 'Escape'], [4194306, 'Tab'], [4194309, 'Enter'], [4194325, 'Shift'], [4194326, 'Control'],
+  [4194319, 'ArrowLeft'], [4194320, 'ArrowUp'], [4194321, 'ArrowRight'], [4194322, 'ArrowDown']
+]);
+
+/**
+ * The keys each input action in project.godot is bound to, as one line a persona
+ * can read, so it presses the key the game listens for and does not guess. Null
+ * when the file or its input section cannot be read: a persona can still explore.
+ *
+ * @param {string} projectDir
+ * @returns {Promise<string|null>}
+ */
+export async function inputControls(projectDir) {
+  let text;
+  try {
+    text = await fs.readFile(path.join(projectDir, 'project.godot'), 'utf8');
+  } catch {
+    return null;
+  }
+  const section = /^\[input\]\n([\s\S]*?)(?=^\[[a-z_]+\]\s*$|(?![\s\S]))/m.exec(text);
+  if (!section) return null;
+  const lines = [];
+  for (const [, action, body] of section[1].matchAll(/^([A-Za-z_][\w.]*)=\{([\s\S]*?)^\}/gm)) {
+    const keys = [...body.matchAll(/InputEventKey[^)]*?"(?:physical_keycode|keycode)":\s*(\d+)/g)].map(([, code]) => {
+      const number = Number(code);
+      return NAMED_KEYS.get(number) || (number > 32 && number < 127 ? String.fromCharCode(number) : null);
+    }).filter(Boolean);
+    if (keys.length > 0) lines.push(`${action}: ${[...new Set(keys)].join(' or ')}`);
+  }
+  return lines.length > 0 ? lines.join('; ') : null;
+}
+
 /** Reads the project's declared engine version, e.g. "4.5" from config/features. */
 export async function readProjectEngineVersion(projectDir) {
   const text = await readIfPresent(path.join(projectDir, 'project.godot'));
@@ -381,11 +428,14 @@ export async function detectGodotBinary({
 
   const usable = [];
   for (const candidate of candidates) {
-    if (!(await isExecutable(candidate))) continue;
-    const version = await probe(candidate);
-    if (!version) continue;
-    if (version.major < minMajor) continue;
-    if (version.major === minMajor && version.minor < minMinor) continue;
+    const version = (await isExecutable(candidate)) ? await probe(candidate) : null;
+    const fits = version && (version.major > minMajor || (version.major === minMajor && version.minor >= minMinor));
+    if (!fits) {
+      // Somebody named this one. Playing on a different Godot would answer a question
+      // they did not ask, so a path that cannot be used is refused, not stepped past.
+      if (explicitPath && candidate === explicitPath) throw new Error(`--godot-path ${explicitPath} is not a usable Godot ${minMajor}.${minMinor}+ binary`);
+      continue;
+    }
     usable.push({ path: candidate, ...version });
     if (explicitPath && candidate === explicitPath) break;
   }
@@ -456,6 +506,28 @@ async function isExecutable(file) {
 }
 
 /** Finds a loopback port the driver can bind, starting from the spec default. */
+/**
+ * Two drivers in one process asked "what is free" at once and both heard 47800:
+ * the second Godot failed to listen, its CLI dialled the first one's socket with
+ * the wrong token, and both runs died (found running two personas at once). So a
+ * port handed out here is not handed out again, and each search starts somewhere
+ * random in the range so two processes rarely meet either.
+ *
+ * @returns {Promise<number>}
+ */
+const handedOut = new Set();
+export async function reservePort({ base = 47800, span = 1024, find = findFreePort } = {}) {
+  for (let attempt = 0; attempt < 16; attempt += 1) {
+    const start = base + Math.floor(Math.random() * span);
+    const port = await find(start, 64);
+    if (!handedOut.has(port)) {
+      handedOut.add(port);
+      return port;
+    }
+  }
+  return find(base, 64);
+}
+
 export async function findFreePort(start = 47800, tries = 64) {
   for (let offset = 0; offset < tries; offset += 1) {
     const port = start + offset;
@@ -473,3 +545,101 @@ function canBind(port) {
     });
   });
 }
+
+/** Directories never walked when deciding whether a project needs an import. */
+const IMPORT_WALK_SKIP = new Set(['.godot', '.git', 'node_modules', '.import']);
+
+/** The most scripts read when deciding; past this the import simply runs. */
+const IMPORT_WALK_MAX_FILES = 20000;
+
+async function listScripts(dir, out = []) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (out.length >= IMPORT_WALK_MAX_FILES) return out;
+    if (entry.isDirectory()) {
+      if (!IMPORT_WALK_SKIP.has(entry.name)) await listScripts(path.join(dir, entry.name), out);
+    } else if (entry.name.endsWith('.gd')) {
+      out.push(path.join(dir, entry.name));
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether the project's `.godot/` import cache is missing or older than its
+ * scripts. Godot resolves `class_name` from `.godot/global_script_class_cache.cfg`,
+ * which is gitignored, so a fresh clone, a CI checkout or a git worktree has
+ * none and every script naming a global class fails to parse
+ * (`Could not find type "Game"`). Decided on the developer's own directory,
+ * which is read and never written.
+ *
+ * @param {string} projectDir
+ * @returns {Promise<{needed: boolean, reason?: string}>}
+ */
+export async function projectNeedsImport(projectDir) {
+  const cacheDir = path.join(projectDir, '.godot');
+  const dir = await fs.stat(cacheDir).catch(() => null);
+  if (!dir?.isDirectory()) return { needed: true, reason: 'no .godot import cache' };
+  const scripts = await listScripts(projectDir);
+  if (scripts.length >= IMPORT_WALK_MAX_FILES) return { needed: true, reason: 'too many scripts to compare; importing to be safe' };
+  const cache = await fs.stat(path.join(cacheDir, 'global_script_class_cache.cfg')).catch(() => null);
+  if (!cache) {
+    for (const file of scripts) {
+      const text = await fs.readFile(file, 'utf8').catch(() => '');
+      if (/^\s*class_name\s+\w/m.test(text)) return { needed: true, reason: 'class_name scripts and no class cache' };
+    }
+    return { needed: false };
+  }
+  for (const file of scripts) {
+    const stat = await fs.stat(file).catch(() => null);
+    if (stat && stat.mtimeMs > cache.mtimeMs) return { needed: true, reason: 'scripts changed since the last import' };
+  }
+  return { needed: false };
+}
+
+/**
+ * `godot --headless --path <copy> --import`, bounded by a timeout. Run on the
+ * temp copy, never on the developer's project. Output goes to the run's
+ * godot.log ahead of the game's own.
+ *
+ * @returns {Promise<{ok: boolean, exitCode?: number|null, error?: string}>}
+ */
+export function importProjectCopy({ godotPath, projectCopy, env, timeoutMs = 180000, logPath = null, spawnFn = spawnProcess }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnFn(godotPath, ['--headless', '--path', projectCopy, '--import'], {
+        cwd: projectCopy,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      resolve({ ok: false, error: error.message });
+      return;
+    }
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    if (logPath) {
+      for (const stream of [child.stdout, child.stderr]) {
+        stream?.on('data', (chunk) => { void fs.appendFile(logPath, chunk).catch(() => {}); });
+      }
+    }
+    const timer = setTimeout(() => {
+      done({ ok: false, exitCode: null, error: `the import timed out after ${Math.round(timeoutMs / 1000)} s` });
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+    }, timeoutMs);
+    timer.unref?.();
+    child.on('error', (error) => done({ ok: false, error: error.message }));
+    child.on('exit', (code) => done(code === 0 ? { ok: true, exitCode: 0 } : { ok: false, exitCode: code, error: `exit ${code}` }));
+  });
+}