@ludra/cli 0.7.0 → 0.8.0

package/dist/commands/check.d.ts

@@ -1,3 +1,4 @@
+/** Validates every scene in the project (entry scene first). */
 export declare function check(dir: string, options: {
     json?: boolean;
 }): Promise<number>;

package/dist/commands/check.js

@@ -1,26 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { checkDrawHooks } from "@ludra/core";
 import { formatDiagnostics, paint } from "../format.js";
-import { loadGame, loadProject } from "../project.js";
+import { isInside, listScenes, loadGame, loadProject, scriptPaths } from "../project.js";
+/** Validates every scene in the project (entry scene first). */
 export async function check(dir, options) {
     const project = loadProject(dir);
-    const { game, diagnostics } = await loadGame(project);
-    const scene = game?.scene;
-    // Draw hooks only run in the browser, so paint once here to catch their errors early.
-    if (game)
-        diagnostics.push(...checkDrawHooks(game.scene, game.scripts));
-    const errors = diagnostics.filter((d) => d.severity === "error").length;
-    const warnings = diagnostics.length - errors;
+    const results = [];
+    const scripts = new Set();
+    for (const scene of listScenes(project)) {
+        const { game, diagnostics, label } = await loadGame(project, scene);
+        // Draw hooks only run in the browser, so paint once here to catch their errors early.
+        if (game) {
+            diagnostics.push(...checkDrawHooks(game.scene, game.scripts));
+            for (const path of scriptPaths(project, game.scene))
+                scripts.add(path);
+        }
+        const errors = diagnostics.filter((d) => d.severity === "error").length;
+        results.push({ file: label, entities: game?.scene.entities.length ?? 0, errors, warnings: diagnostics.length - errors, diagnostics });
+    }
+    // world.goto("...") in scripts must point at real scenes.
+    const gotoProblems = missingGotoScenes(project, [...scripts]);
+    if (gotoProblems.length > 0) {
+        results.push({ file: "scripts", entities: 0, errors: gotoProblems.length, warnings: 0, diagnostics: gotoProblems });
+    }
+    const errors = results.reduce((n, r) => n + r.errors, 0);
+    const warnings = results.reduce((n, r) => n + r.warnings, 0);
     if (options.json) {
-        console.log(JSON.stringify({ ok: errors === 0, file: project.entryLabel, errors, warnings, diagnostics }, null, 2));
+        const diagnostics = results.flatMap((r) => r.diagnostics.map((d) => ({ file: r.file, ...d })));
+        console.log(JSON.stringify({ ok: errors === 0, file: project.entryLabel, errors, warnings, diagnostics, scenes: results }, null, 2));
         return errors > 0 ? 1 : 0;
     }
-    if (diagnostics.length > 0)
-        console.log(`${formatDiagnostics(diagnostics, project.entryLabel)}\n`);
-    if (errors > 0) {
-        console.log(paint("red", `✗ ${project.entryLabel}: ${errors} error(s), ${warnings} warning(s)`));
-        return 1;
+    for (const r of results) {
+        if (r.diagnostics.length > 0)
+            console.log(`${formatDiagnostics(r.diagnostics, r.file)}\n`);
+        if (r.errors > 0)
+            console.log(paint("red", `✗ ${r.file}: ${r.errors} error(s), ${r.warnings} warning(s)`));
+        else
+            console.log(paint("green", `✓ ${r.file}: ${r.entities} entities, ${r.warnings === 0 ? "no problems" : `${r.warnings} warning(s)`}`));
+    }
+    return errors > 0 ? 1 : 0;
+}
+/** Scene paths written literally in world.goto("...") calls that don't exist. */
+function missingGotoScenes(project, scripts) {
+    const problems = [];
+    for (const src of scripts) {
+        const file = resolve(project.dir, src);
+        if (!existsSync(file))
+            continue;
+        for (const match of readFileSync(file, "utf8").matchAll(/\bgoto\(\s*["'`]([^"'`$]+)["'`]\s*\)/g)) {
+            const target = resolve(project.dir, match[1]);
+            if (isInside(project.dir, target) && existsSync(target))
+                continue;
+            problems.push({
+                severity: "error",
+                code: "E_SCENE_MISSING",
+                path: `${src} → goto("${match[1]}")`,
+                message: `${src} goes to "${match[1]}", which does not exist.`,
+                fix: `Scenes: ${listScenes(project).join(", ")}. Paths are relative to the folder with ludra.json.`,
+            });
+        }
     }
-    const count = scene?.entities.length ?? 0;
-    console.log(paint("green", `✓ ${project.entryLabel}: ${count} entities, ${warnings === 0 ? "no problems" : `${warnings} warning(s)`}`));
-    return 0;
+    return problems;
 }

package/dist/commands/dev.js

@@ -15,7 +15,7 @@ export function dev(dir, options) {
     server.listen(port, "127.0.0.1", () => {
         console.log(paint("green", `▶ ${project.config.name} is running at http://localhost:${port}`));
         console.log(paint("dim", `  Arrows/WASD to move, Space/Z to jump, M to mute, R to restart.`));
-        console.log(paint("dim", `  Editing ${project.entryLabel} or its images and sounds reloads the page. Ctrl+C to stop.`));
+        console.log(paint("dim", `  Editing a scene, prefab, script or asset reloads the page. Ctrl+C to stop.`));
     });
     return 0;
 }
@@ -44,7 +44,12 @@ import { startGame } from "${browserModule}";
 const data = await (await fetch("/__ludra/scene")).json();
 if (data.ok) {
   const scriptPaths = await (await fetch("/__ludra/scripts")).json();
-  await startGame(document.getElementById("game"), data.scene, { assetBase: "${PROJECT_PREFIX}", scriptBase: "${SCRIPT_PREFIX}", scriptPaths });
+  const loadScene = async (path) => {
+    const next = await (await fetch("/__ludra/scene?path=" + encodeURIComponent(path))).json();
+    if (!next.ok) throw new Error(next.diagnostics.map((d) => d.code + " at " + d.path + ": " + d.message).join(" "));
+    return next.scene;
+  };
+  await startGame(document.getElementById("game"), data.scene, { assetBase: "${PROJECT_PREFIX}", scriptBase: "${SCRIPT_PREFIX}", scriptPaths, loadScene });
 } else {
   document.getElementById("game").hidden = true;
   const errors = document.getElementById("errors");

package/dist/commands/play.d.ts

@@ -1,4 +1,5 @@
 export interface PlayOptions {
+    scene?: string;
     inputs?: string;
     duration?: string;
     watch?: string;

package/dist/commands/play.js

@@ -7,7 +7,7 @@ import { CliError, loadProject, requireGame } from "../project.js";
 const MAX_EVENTS_SHOWN = 40;
 export async function play(dir, options) {
     const project = loadProject(dir);
-    const { scene, scripts } = await requireGame(project);
+    const { scene, scripts } = await requireGame(project, options.scene);
     const script = parse(() => InputScript.parse(options.inputs ?? ""));
     const frames = secondsToFrames(options.duration ? parse(() => parseDuration(options.duration)) : defaultDuration(script));
     const every = Math.max(1, secondsToFrames(parse(() => parseDuration(options.every ?? "0.25s"))));
@@ -71,7 +71,7 @@ async function takeScreenshots(project, options, lastFrame) {
     const frames = [...new Set(requested)].sort((a, b) => a - b);
     const outDir = resolve(project.dir, options.out ?? "screenshots");
     mkdirSync(outDir, { recursive: true });
-    const captured = await captureScreenshots(project, { inputs: options.inputs ?? "", frames });
+    const captured = await captureScreenshots(project, { scene: options.scene, inputs: options.inputs ?? "", frames });
     return captured.map((shot) => {
         const path = join(outDir, `t-${fixed(shot.time, 2)}s.png`);
         writeFileSync(path, Buffer.from(shot.png.slice(shot.png.indexOf(",") + 1), "base64"));
@@ -109,11 +109,17 @@ function describeEvent(event) {
         case "stomp":
             return `${event.entity} stomped ${event.enemy}${event.score ? ` (+${event.score})` : ""}`;
         case "die":
-            return `${event.entity} ${event.cause === "fall" ? "fell out of the world" : `hit ${event.cause}`}, respawned`;
+            return `${event.entity} ${event.cause === "fall" ? "fell out of the world" : `hit ${event.cause}`}`;
         case "win":
             return event.entity === event.goal ? `${event.entity} (script) completed the level` : `${event.entity} reached ${event.goal}`;
         case "bounce":
             return `${event.entity} bounced off ${event.other}`;
+        case "checkpoint":
+            return `${event.entity} reached ${event.checkpoint} (respawns there now)`;
+        case "gameover":
+            return event.cause === "script" ? `game over (from ${event.entity}'s script)` : `${event.entity} is out of lives: game over`;
+        case "goto":
+            return `${event.entity} → ${event.scene}`;
         case "custom":
             return `from ${event.entity}'s script${event.data === undefined ? "" : ` ${JSON.stringify(event.data)}`}`;
         default:

package/dist/commands/review.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `ludra review`: the signs of a slop game, found automatically. Where `check`
+ * asks "is it valid?" and `test` asks "does it work?", review asks "is it
+ * finished?": proven, felt, styled and named. Issues should be fixed before a
+ * game is called done; ideas are worth considering.
+ */
+type Area = "proof" | "feel" | "looks" | "identity";
+type Level = "issue" | "idea";
+export interface Finding {
+    level: Level;
+    area: Area;
+    code: string;
+    /** The scene or file it is about. */
+    where: string;
+    message: string;
+    fix: string;
+}
+export declare function review(dir: string, options: {
+    json?: boolean;
+    strict?: boolean;
+}): Promise<number>;
+export {};

package/dist/commands/review.js

@@ -0,0 +1,183 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { runTest } from "@ludra/core";
+import { paint } from "../format.js";
+import { listScenes, loadGame, loadProject } from "../project.js";
+const AREAS = {
+    proof: "Proof: is it shown to work?",
+    feel: "Feel: does every moment answer the player?",
+    looks: "Looks: does it have a style of its own?",
+    identity: "Identity: is it a game, or a project folder?",
+};
+/** Events players cause or feel directly: silence on these reads as unfinished. */
+const IMPORTANT_EVENTS = new Set(["collect", "die", "stomp", "win", "gameover", "checkpoint", "jump"]);
+const LISTED = 5;
+export async function review(dir, options) {
+    const project = loadProject(dir);
+    const findings = [];
+    const add = (level, area, code, where, message, fix) => findings.push({ level, area, code, where, message, fix });
+    // Load every scene; review only makes sense for a game that passes check.
+    const scenes = [];
+    for (const label of listScenes(project)) {
+        const { game, diagnostics } = await loadGame(project, label);
+        if (!game) {
+            const errors = diagnostics.filter((d) => d.severity === "error").length;
+            add("issue", "proof", "R_CHECK_FAILS", label, `The scene has ${errors} error(s), so it can't be reviewed.`, "Run `ludra check` and fix them first.");
+            continue;
+        }
+        scenes.push({ label, game, results: [] });
+    }
+    const tests = readTests(project);
+    for (const problem of tests.problems)
+        add("issue", "proof", "R_TESTS_UNREADABLE", problem.file, problem.message, "Fix the JSON in that test file.");
+    for (const c of tests.cases) {
+        const scene = scenes.find((s) => s.label === (c.scene ?? project.entryLabel));
+        if (scene)
+            scene.results.push(runTest(scene.game.scene, c, { scripts: scene.game.scripts }));
+    }
+    if (tests.cases.length === 0) {
+        add("issue", "proof", "R_NO_TESTS", "tests/", "There are no tests, so nothing shows the game works.", 'Add tests/gameplay.test.json, starting with one that proves a level can be won: "won == true", "deaths == 0".');
+    }
+    const failing = scenes.flatMap((s) => s.results.filter((r) => !r.pass).map((r) => `"${r.name}"`));
+    if (failing.length > 0) {
+        add("issue", "proof", "R_FAILING_TESTS", "tests/", `${failing.length} test(s) fail: ${list(failing)}.`, "Run `ludra test` and fix the game (not the test) until they pass.");
+    }
+    for (const scene of scenes) {
+        reviewScene(project, scene, tests.cases.length > 0, add);
+    }
+    // Identity.
+    const folder = basename(project.dir);
+    if (project.config.name === "untitled" || project.config.name === folder) {
+        add("idea", "identity", "R_FOLDER_NAME", "ludra.json", `The game is called "${project.config.name}", the name of its folder.`, 'Give it a real title in ludra.json ("name"), the one players will see.');
+    }
+    const issues = findings.filter((f) => f.level === "issue").length;
+    const ideas = findings.length - issues;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: issues === 0, issues, ideas, findings }, null, 2));
+    }
+    else {
+        print(project, findings, issues, ideas);
+    }
+    return options.strict && issues > 0 ? 1 : 0;
+}
+function reviewScene(project, info, hasTests, add) {
+    const { label, game, results } = info;
+    const { scene, scripts } = game;
+    const sources = scriptSources(project, scene);
+    const hooksOf = (src) => Object.keys(scripts.get(src) ?? {});
+    const uses = (hook) => scene.entities.some((e) => e.components.script && hooksOf(String(e.components.script.src)).includes(hook));
+    // ---------------------------------------------------------------- proof
+    const canWin = scene.entities.some((e) => e.components.goal) || [...sources.values()].some((code) => /\bwin\(\s*\)/.test(code));
+    const proves = (r, ...needed) => r.pass && needed.every((re) => r.results.some((a) => re.test(a.source.replace(/\s+/g, " "))));
+    if (canWin && hasTests && !results.some((r) => proves(r, /^won == true\b/, /^deaths == 0\b/))) {
+        add("issue", "proof", "R_NO_WIN_PROOF", label, "No passing test proves this scene can be won without dying.", 'Add a test with a full route and "won == true", "deaths == 0". For long routes, write a small autopilot (see the skill).');
+    }
+    // A mechanic is tested when an assertion names one of its entities or the events it emits.
+    const asserted = results.flatMap((r) => r.results.map((a) => a.source)).join("\n");
+    for (const [src, code] of sources) {
+        const hooks = hooksOf(src);
+        if (!hooks.some((h) => h === "start" || h === "update" || h === "touch"))
+            continue; // only draws
+        const ids = scene.entities.filter((e) => e.components.script?.src === src).map((e) => e.id);
+        const emitted = [...code.matchAll(/\bemit\(\s*["'`]([^"'`]+)["'`]/g)].map((m) => m[1]);
+        const mentioned = ids.some((id) => asserted.includes(`${id}.`)) || emitted.some((name) => asserted.includes(`events.${name}`));
+        if (hasTests && !mentioned) {
+            add("issue", "proof", "R_UNTESTED_MECHANIC", label, `${src} (on ${list(ids)}) has no test that checks what it does.`, `Add a test that isolates it and asserts its effect: ${ids[0] ? `"${ids[0]}.state.<key> == ..."` : ""}${emitted[0] ? ` or "events.${emitted[0]} >= 1"` : ""}.`);
+        }
+    }
+    // ---------------------------------------------------------------- feel
+    const fired = new Set(results.flatMap((r) => r.events));
+    const drawn = [...sources.values()].flatMap((code) => [...code.matchAll(/\brecent\(\s*["'`]([^"'`]+)["'`]/g)].map((m) => m[1]));
+    const silent = [...fired].filter((name) => name !== "goto" && !scene.effects?.[name] && !drawn.includes(name));
+    const important = silent.filter((name) => IMPORTANT_EVENTS.has(name));
+    if (important.length > 0) {
+        add("issue", "feel", "R_SILENT_EVENT", label, `These events happen in play but nothing answers them: ${list(important)}.`, 'Give each an "effects" entry (particles in the source\'s color, a sound, shake for big moments) or react to it in a draw hook with ctx.recent("<name>").');
+    }
+    const minor = silent.filter((name) => !IMPORTANT_EVENTS.has(name));
+    if (minor.length > 0) {
+        add("idea", "feel", "R_QUIET_EVENT", label, `These events have no feedback yet: ${list(minor)}.`, "Small touches (a puff on land, a blip on bounce, a flash for custom events) make a game feel alive.");
+    }
+    const mute = Object.entries(scene.effects ?? {}).filter(([name, effect]) => IMPORTANT_EVENTS.has(name) && effect && !effect.sound).map(([name]) => name);
+    if (mute.length > 0) {
+        add("idea", "feel", "R_NO_SOUND", label, `These effects have no sound: ${list(mute)}.`, "Add a preset (jump, coin, hit, explosion, powerup, blip, thud) or an audio file.");
+    }
+    // ---------------------------------------------------------------- looks
+    if (!uses("drawUI")) {
+        add("issue", "looks", "R_DEFAULT_HUD", label, "It uses the engine's default HUD and end screens.", "Write a drawUI hook: show what matters in this game (lives as hearts, crystals as icons, a meter), a title card and a win screen, in a font that fits the mood.");
+    }
+    else if (!scene.fonts || Object.keys(scene.fonts).length === 0) {
+        add("idea", "looks", "R_SYSTEM_FONT", label, "The interface uses the system font.", 'Load a display font that fits the mood: "fonts": { "<Family>": "google" }.');
+    }
+    const hasBackdrop = scene.entities.some((e) => (e.components.sprite && Number(e.components.sprite.layer ?? 0) < 0) || (!e.components.body && e.components.script && hooksOf(String(e.components.script.src)).includes("draw")));
+    if (!hasBackdrop) {
+        add("issue", "looks", "R_FLAT_BACKDROP", label, "Behind the game there is only a flat background color.", "Paint a backdrop: a sprite on layer -1 (sky, hills, floor tiles) or an entity with only a draw hook (gradients, a sun, stars, parallax).");
+    }
+    const plain = scene.entities
+        .filter((e) => e.components.sprite && !e.components.sprite.image && !(e.components.script && hooksOf(String(e.components.script.src)).includes("draw")))
+        .map((e) => e.id);
+    if (plain.length > 0) {
+        add("issue", "looks", "R_PLAIN_SHAPES", label, `${plain.length} entit${plain.length === 1 ? "y is" : "ies are"} drawn as flat colored shapes: ${list(plain)}.`, "Give them SVG art (sprite.image) or a draw hook.");
+    }
+    if (!scene.postfx) {
+        add("idea", "looks", "R_NO_POSTFX", label, "No post-processing.", 'A finishing shader ("postfx") ties a look together: bloom for anything that glows, a grade for mood, scanlines for arcade.');
+    }
+    if (!scene.name) {
+        add("idea", "identity", "R_UNNAMED_SCENE", label, "The scene has no name.", 'Add "name" (e.g. "Crystal Grove") to the scene.');
+    }
+}
+/** Source code of the scripts a scene uses, by path. */
+function scriptSources(project, scene) {
+    const sources = new Map();
+    for (const e of scene.entities) {
+        const src = e.components.script?.src;
+        if (typeof src !== "string" || sources.has(src))
+            continue;
+        const file = resolve(project.dir, src);
+        if (existsSync(file))
+            sources.set(src, readFileSync(file, "utf8"));
+    }
+    return sources;
+}
+function readTests(project) {
+    const dir = join(project.dir, "tests");
+    const cases = [];
+    const problems = [];
+    if (!existsSync(dir))
+        return { cases, problems };
+    for (const file of readdirSync(dir).filter((f) => f.endsWith(".test.json")).sort()) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, file), "utf8"));
+            if (!Array.isArray(parsed.tests))
+                throw new Error('expected { "tests": [...] }');
+            cases.push(...parsed.tests);
+        }
+        catch (err) {
+            problems.push({ file: `tests/${file}`, message: `Could not read it: ${err.message}` });
+        }
+    }
+    return { cases, problems };
+}
+function list(items) {
+    return items.length <= LISTED ? items.join(", ") : `${items.slice(0, LISTED).join(", ")} and ${items.length - LISTED} more`;
+}
+function print(project, findings, issues, ideas) {
+    console.log(paint("bold", `Review of ${project.config.name}`));
+    for (const area of Object.keys(AREAS)) {
+        const inArea = findings.filter((f) => f.area === area).sort((a, b) => (a.level === b.level ? 0 : a.level === "issue" ? -1 : 1));
+        console.log(`\n${paint("bold", AREAS[area])}`);
+        if (inArea.length === 0) {
+            console.log(paint("green", "  ✓ nothing to flag"));
+            continue;
+        }
+        for (const f of inArea) {
+            const mark = f.level === "issue" ? paint("red", "✗") : paint("yellow", "○");
+            console.log(`  ${mark} ${paint("dim", `[${f.where}]`)} ${f.message}`);
+            console.log(`    ${paint("dim", "→")} ${f.fix}`);
+        }
+    }
+    const summary = `\n${issues} issue(s), ${ideas} idea(s).`;
+    if (issues === 0)
+        console.log(paint("green", `${summary} Nothing marks this as unfinished.${ideas > 0 ? " The ideas are worth a look." : ""}`));
+    else
+        console.log(paint("red", `${summary} Fix the issues before calling the game done.`));
+}

package/dist/commands/test.d.ts

@@ -1,3 +1,4 @@
+/** Runs every tests/*.test.json case against its scene (the entry scene unless the case names one). */
 export declare function test(dir: string, options: {
     json?: boolean;
 }): Promise<number>;

package/dist/commands/test.js

@@ -3,9 +3,17 @@ import { join } from "node:path";
 import { runTest } from "@ludra/core";
 import { paint } from "../format.js";
 import { loadProject, requireGame } from "../project.js";
+/** Runs every tests/*.test.json case against its scene (the entry scene unless the case names one). */
 export async function test(dir, options) {
     const project = loadProject(dir);
-    const { scene, scripts } = await requireGame(project);
+    // Each test runs its own scene ("scene" in the test case), loaded once.
+    const games = new Map([[project.entryLabel, await requireGame(project)]]);
+    const gameFor = async (scene) => {
+        const key = scene ?? project.entryLabel;
+        if (!games.has(key))
+            games.set(key, await requireGame(project, key));
+        return games.get(key);
+    };
     const testsDir = join(project.dir, "tests");
     const files = existsSync(testsDir) ? readdirSync(testsDir).filter((f) => f.endsWith(".test.json")).sort() : [];
     if (files.length === 0) {
@@ -16,7 +24,8 @@ export async function test(dir, options) {
             console.log(paint("yellow", message));
         return 1;
     }
-    const results = files.map((file) => {
+    const results = [];
+    for (const file of files) {
         let cases;
         try {
             const parsed = JSON.parse(readFileSync(join(testsDir, file), "utf8"));
@@ -25,10 +34,16 @@ export async function test(dir, options) {
                 throw new Error('expected { "tests": [...] }');
         }
         catch (err) {
-            return { file, error: err.message, tests: [] };
+            results.push({ file, error: err.message, tests: [] });
+            continue;
         }
-        return { file, tests: cases.map((c) => runTest(scene, c, { scripts })) };
-    });
+        const tests = [];
+        for (const c of cases) {
+            const { scene, scripts } = await gameFor(c.scene);
+            tests.push(runTest(scene, c, { scripts }));
+        }
+        results.push({ file, tests });
+    }
     const all = results.flatMap((r) => r.tests);
     const failed = all.filter((t) => !t.pass).length + results.filter((r) => r.error).length;
     if (options.json) {

package/dist/headless.d.ts

@@ -6,11 +6,9 @@ import { type Project } from "./project.ts";
  */
 export declare function findBrowser(): string | undefined;
 export interface ScreenshotRequest {
+    /** Scene to render, relative to the project. Defaults to the entry scene. */
+    scene?: string;
     inputs: string;
     frames: number[];
 }
-/**
- * Renders frames of a project in a headless browser, using the same renderer
- * players see. Starts a private game server and browser, and stops both.
- */
 export declare function captureScreenshots(project: Project, request: ScreenshotRequest): Promise<CapturedFrame[]>;

package/dist/headless.js

@@ -37,6 +37,9 @@ export function findBrowser() {
  * Renders frames of a project in a headless browser, using the same renderer
  * players see. Starts a private game server and browser, and stops both.
  */
+function sceneUrl(scene) {
+    return scene ? `/__ludra/scene?path=${encodeURIComponent(scene)}` : "/__ludra/scene";
+}
 export async function captureScreenshots(project, request) {
     const browserPath = findBrowser();
     if (!browserPath) {
@@ -73,7 +76,7 @@ export async function captureScreenshots(project, request) {
         await waitFor(cdp, sessionId, `location.origin === ${JSON.stringify(origin)} && document.readyState === "complete"`);
         const script = `(async () => {
       const { captureFrames } = await import(${JSON.stringify(browserModule)});
-      const data = await (await fetch("/__ludra/scene")).json();
+      const data = await (await fetch(${JSON.stringify(sceneUrl(request.scene))})).json();
       if (!data.ok) throw new Error("The scene has errors. Run ludra check.");
       const canvas = document.createElement("canvas");
       canvas.width = ${width};
@@ -105,8 +108,20 @@ export async function captureScreenshots(project, request) {
             });
         }
         server.close();
-        // The browser can hold its profile for a moment after exiting on Windows.
-        rmSync(profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+        removeProfile(profile);
+    }
+}
+/**
+ * The browser can keep its profile busy for a moment after exiting: files held open
+ * on Windows, helper processes still writing on macOS (ENOTEMPTY). Retry, and if it
+ * still won't go, leave it to the OS's temp cleanup rather than fail a capture that worked.
+ */
+function removeProfile(profile) {
+    try {
+        rmSync(profile, { recursive: true, force: true, maxRetries: 10, retryDelay: 300 });
+    }
+    catch (err) {
+        console.warn(`Could not remove the temporary browser profile ${profile}: ${err.message}`);
     }
 }
 /** Chrome prints "DevTools listening on ws://..." to stderr once it is ready. */

package/dist/index.js

@@ -7,6 +7,7 @@ import { dev } from "./commands/dev.js";
 import { create } from "./commands/new.js";
 import { play } from "./commands/play.js";
 import { test } from "./commands/test.js";
+import { review } from "./commands/review.js";
 import { paint } from "./format.js";
 import { CliError } from "./project.js";
 // Ludra strips types from game scripts with Node's built-in stripTypeScriptTypes, which warns that it is
@@ -21,8 +22,9 @@ const HELP = `ludra: the game engine built for AI agents
 
 Usage
   ludra new <folder> [--template <name>]       Create a game project (templates: platformer, topdown, breakout)
-  ludra check [folder] [--json]                Validate the scene; every problem comes with a fix
+  ludra check [folder] [--json]                Validate every scene; every problem comes with a fix
   ludra play [folder] [options]                Simulate the game headlessly
+      --scene scenes/level-2.scene.json        Scene to play (default: the entry scene in ludra.json)
       --inputs "right:1s, jump:0.4s"           Scripted input. Actions: left right up down jump action wait
       --duration 3s                            Run length (default: inputs + 1s)
       --watch player,enemy                     Entities in the timeline (default: the players)
@@ -32,7 +34,9 @@ Usage
       --screenshot 1s,2.5s,end                 Save real rendered frames as PNGs (needs Chrome, Edge or Chromium)
       --out screenshots                        Folder for screenshots, relative to the project (default: screenshots)
       --json                                   Machine-readable output
-  ludra test [folder] [--json]                 Run tests/*.test.json
+  ludra test [folder] [--json]                 Run tests/*.test.json (a test can pick its "scene")
+  ludra review [folder] [--json] [--strict]    Find what makes a game feel unfinished: untested mechanics,
+                                               silent events, default HUD, flat looks (--strict: exit 1 on issues)
   ludra components [name] [--json]             Reference for every component and field
   ludra blocks [--json]                        Catalog of ready-made gameplay blocks
   ludra add <block> [folder] --at x,y          Add a block: entities, scripts, art and effects
@@ -46,6 +50,7 @@ async function main(argv) {
         args: argv,
         allowPositionals: true,
         options: {
+            scene: { type: "string" },
             inputs: { type: "string" },
             duration: { type: "string" },
             watch: { type: "string" },
@@ -60,6 +65,7 @@ async function main(argv) {
             at: { type: "string" },
             id: { type: "string" },
             force: { type: "boolean" },
+            strict: { type: "boolean" },
             help: { type: "boolean", short: "h" },
         },
     });
@@ -77,6 +83,8 @@ async function main(argv) {
             return play(target ?? ".", values);
         case "test":
             return test(target ?? ".", values);
+        case "review":
+            return review(target ?? ".", values);
         case "components":
             return components(target, values);
         case "dev":

package/dist/project.d.ts

@@ -21,9 +21,21 @@ export declare function loadProject(dir: string): Project;
 export interface SceneLoad {
     scene?: SceneDef;
     diagnostics: Diagnostic[];
+    /** The scene's path relative to the project, for messages. */
+    label: string;
 }
-/** Reads and validates the entry scene. JSON syntax errors become diagnostics too. */
-export declare function readScene(project: Project): SceneLoad;
+/** Every scene in the project: the entry scene, then every .scene.json file under scenes/. */
+export declare function listScenes(project: Project): string[];
+/** Prefab files (prefabs/<name>.prefab.json) by name, plus problems reading them. */
+export declare function readPrefabs(project: Project): {
+    prefabs: Record<string, unknown>;
+    diagnostics: Diagnostic[];
+};
+/**
+ * Reads and validates a scene (the entry scene by default), with the project's
+ * prefab files merged in. JSON syntax errors become diagnostics too.
+ */
+export declare function readScene(project: Project, scenePath?: string): SceneLoad;
 /** Script files a game can use: those the scene references, plus everything in scripts/ (for world.spawn). */
 export declare function scriptPaths(project: Project, scene: SceneDef): string[];
 export interface Game {
@@ -34,12 +46,13 @@ export interface Game {
  * Reads the scene and imports its scripts. Node runs TypeScript scripts
  * directly (type stripping), so no build step is needed.
  */
-export declare function loadGame(project: Project): Promise<{
+export declare function loadGame(project: Project, scenePath?: string): Promise<{
     game?: Game;
     diagnostics: Diagnostic[];
+    label: string;
 }>;
 /** Like `loadGame`, but stops with the diagnostics when anything is wrong. */
-export declare function requireGame(project: Project): Promise<Game>;
+export declare function requireGame(project: Project, scenePath?: string): Promise<Game>;
 export declare function isInside(dir: string, path: string): boolean;
 /** Like `readScene`, but stops with the diagnostics when the scene has errors. */
-export declare function requireScene(project: Project): SceneDef;
+export declare function requireScene(project: Project, scenePath?: string): SceneDef;