@ludra/cli 0.5.0 → 0.8.0

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) {
@@ -59,6 +62,9 @@ export async function captureScreenshots(project, request) {
             "--no-default-browser-check",
             "--mute-audio",
             "--hide-scrollbars",
+            // Software WebGL, so postfx shaders render without a GPU.
+            "--use-angle=swiftshader",
+            "--enable-unsafe-swiftshader",
             `--window-size=${width},${height}`,
             "about:blank",
         ], { stdio: ["ignore", "ignore", "pipe"] });
@@ -70,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};
@@ -102,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

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
+import { add, blocks } from "./commands/blocks.js";
 import { check } from "./commands/check.js";
 import { components } from "./commands/components.js";
 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
@@ -19,20 +21,27 @@ process.emitWarning = ((warning, ...rest) => {
 const HELP = `ludra: the game engine built for AI agents
 
 Usage
-  ludra new <folder> [--template platformer]   Create a game project
-  ludra check [folder] [--json]                Validate the scene; every problem comes with a fix
+  ludra new <folder> [--template <name>]       Create a game project (templates: platformer, topdown, breakout)
+  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: platformer entities)
+      --watch player,enemy                     Entities in the timeline (default: the players)
       --every 0.25s                            Timeline sampling interval
       --ascii                                  Print the final frame as a text map
       --columns 120                            Width of the text map (default: 80)
       --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
+      --id name                                Id prefix for its entities (default: the block name)
+      --force                                  Replace files you changed that the block also ships
   ludra dev [folder] [--port 5173]             Play the game in the browser with live reload
 
 Folder defaults to the current directory.`;
@@ -41,6 +50,7 @@ async function main(argv) {
         args: argv,
         allowPositionals: true,
         options: {
+            scene: { type: "string" },
             inputs: { type: "string" },
             duration: { type: "string" },
             watch: { type: "string" },
@@ -52,10 +62,14 @@ async function main(argv) {
             json: { type: "boolean" },
             template: { type: "string" },
             port: { type: "string" },
+            at: { type: "string" },
+            id: { type: "string" },
+            force: { type: "boolean" },
+            strict: { type: "boolean" },
             help: { type: "boolean", short: "h" },
         },
     });
-    const [command, target] = positionals;
+    const [command, target, extra] = positionals;
     if (values.help || !command || command === "help") {
         console.log(HELP);
         return 0;
@@ -69,10 +83,16 @@ 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":
             return dev(target ?? ".", values);
+        case "blocks":
+            return blocks(values);
+        case "add":
+            return add(target, extra ?? ".", values);
         default:
             throw new CliError(`Unknown command "${command}".\n\n${HELP}`);
     }

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;

package/dist/project.js

@@ -35,42 +35,82 @@ export function loadProject(dir) {
     const entryPath = join(root, config.entry);
     return { dir: root, config, entryPath, entryLabel: relative(root, entryPath).replaceAll("\\", "/") };
 }
-/** Reads and validates the entry scene. JSON syntax errors become diagnostics too. */
-export function readScene(project) {
-    if (!existsSync(project.entryPath)) {
+/** Every scene in the project: the entry scene, then every .scene.json file under scenes/. */
+export function listScenes(project) {
+    const inFolder = listFiles(project.dir, "scenes").filter((path) => path.endsWith(".scene.json"));
+    return [...new Set([project.entryLabel, ...inFolder])];
+}
+/** Prefab files (prefabs/<name>.prefab.json) by name, plus problems reading them. */
+export function readPrefabs(project) {
+    const prefabs = {};
+    const diagnostics = [];
+    for (const path of listFiles(project.dir, "prefabs").filter((p) => p.endsWith(".prefab.json"))) {
+        const name = path.slice(path.lastIndexOf("/") + 1, -".prefab.json".length);
+        try {
+            prefabs[name] = JSON.parse(readFileSync(join(project.dir, path), "utf8"));
+        }
+        catch (err) {
+            diagnostics.push({ severity: "error", code: "E_JSON_SYNTAX", path, message: `Invalid JSON in ${path}: ${err.message}` });
+        }
+    }
+    return { prefabs, diagnostics };
+}
+/**
+ * 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 function readScene(project, scenePath = project.entryLabel) {
+    const file = resolve(project.dir, scenePath);
+    const label = relative(project.dir, file).replaceAll("\\", "/");
+    if (!isInside(project.dir, file) || !existsSync(file)) {
+        const scenes = listScenes(project).filter((s) => existsSync(join(project.dir, s)));
         return {
+            label,
             diagnostics: [
                 {
                     severity: "error",
                     code: "E_SCENE_MISSING",
                     path: "$",
-                    message: `Entry scene ${project.entryLabel} does not exist.`,
-                    fix: `Create it, or point "entry" in ludra.json at an existing scene.`,
+                    message: `Scene ${label} does not exist.`,
+                    fix: label === project.entryLabel
+                        ? `Create it, or point "entry" in ludra.json at an existing scene.`
+                        : `Create it${scenes.length > 0 ? `, or use one of: ${scenes.join(", ")}` : ""}.`,
                 },
             ],
         };
     }
     let raw;
     try {
-        raw = JSON.parse(readFileSync(project.entryPath, "utf8"));
+        raw = JSON.parse(readFileSync(file, "utf8"));
     }
     catch (err) {
         return {
+            label,
             diagnostics: [{ severity: "error", code: "E_JSON_SYNTAX", path: "$", message: `Invalid JSON: ${err.message}` }],
         };
     }
+    // Prefab files are shared by every scene; a scene's own "prefabs" win over files of the same name.
+    const files = readPrefabs(project);
+    if (raw && typeof raw === "object" && !Array.isArray(raw) && Object.keys(files.prefabs).length > 0) {
+        const own = raw.prefabs;
+        raw = { ...raw, prefabs: { ...files.prefabs, ...(own && typeof own === "object" ? own : {}) } };
+    }
     const { scene, diagnostics } = validateScene(raw);
+    diagnostics.unshift(...files.diagnostics);
     if (!scene)
-        return { diagnostics };
+        return { label, diagnostics };
     const missing = missingAssets(project, scene);
-    return { scene: missing.length === 0 ? scene : undefined, diagnostics: [...diagnostics, ...missing] };
+    const ok = missing.length === 0 && !files.diagnostics.some((d) => d.severity === "error");
+    return { label, scene: ok ? scene : undefined, diagnostics: [...diagnostics, ...missing] };
 }
-/** Image and audio files the scene references that are not in the project. */
+const EXAMPLE_FILE = { image: "player.svg", audio: "jump.wav", script: "enemy.ts", font: "pixel.woff2", shader: "crt.frag", scene: "level-2.scene.json" };
+const FOLDER = { image: "assets", audio: "assets", script: "scripts", font: "assets", shader: "shaders", scene: "scenes" };
+/** Files the scene references that are not in the project. */
 function missingAssets(project, scene) {
     return collectAssetPaths(scene)
         .filter((ref) => !isInside(project.dir, resolve(project.dir, ref.path)) || !existsSync(resolve(project.dir, ref.path)))
         .map((ref) => {
-        const folder = ref.kind === "script" ? "scripts" : "assets";
+        const folder = FOLDER[ref.kind];
         const available = listFiles(project.dir, folder);
         return {
             severity: "error",
@@ -79,7 +119,7 @@ function missingAssets(project, scene) {
             message: `The ${ref.kind} "${ref.path}" does not exist in the project.`,
             fix: available.length > 0
                 ? `Create it, or use one of: ${available.join(", ")}.`
-                : `Create it (paths are relative to the folder with ludra.json, e.g. "${folder}/${ref.kind === "script" ? "enemy.ts" : "player.svg"}").`,
+                : `Create it (paths are relative to the folder with ludra.json, e.g. "${folder}/${EXAMPLE_FILE[ref.kind]}").`,
         };
     });
 }
@@ -103,10 +143,10 @@ export function scriptPaths(project, scene) {
  * Reads the scene and imports its scripts. Node runs TypeScript scripts
  * directly (type stripping), so no build step is needed.
  */
-export async function loadGame(project) {
-    const { scene, diagnostics } = readScene(project);
+export async function loadGame(project, scenePath) {
+    const { scene, diagnostics, label } = readScene(project, scenePath);
     if (!scene)
-        return { diagnostics };
+        return { diagnostics, label };
     const scripts = new Map();
     for (const src of scriptPaths(project, scene)) {
         const file = resolve(project.dir, src);
@@ -137,7 +177,7 @@ export async function loadGame(project) {
             scripts.set(src, module.default);
     }
     const ok = !diagnostics.some((d) => d.severity === "error");
-    return { game: ok ? { scene, scripts } : undefined, diagnostics };
+    return { game: ok ? { scene, scripts } : undefined, diagnostics, label };
 }
 /**
  * Node's syntax errors carry the location only in the stack: "file:///...:LINE", the source
@@ -155,10 +195,10 @@ function describeLoadError(err, src) {
     return { message: `${src}:${line} failed to load: ${error.message}`, fix: `Line ${line}:\n    ${code}\n    ${caret}` };
 }
 /** Like `loadGame`, but stops with the diagnostics when anything is wrong. */
-export async function requireGame(project) {
-    const { game, diagnostics } = await loadGame(project);
+export async function requireGame(project, scenePath) {
+    const { game, diagnostics, label } = await loadGame(project, scenePath);
     if (!game) {
-        throw new CliError(`${formatDiagnostics(diagnostics, project.entryLabel)}\n\nFix the errors above (see \`ludra check\`) and try again.`);
+        throw new CliError(`${formatDiagnostics(diagnostics, label)}\n\nFix the errors above (see \`ludra check\`) and try again.`);
     }
     return game;
 }
@@ -167,10 +207,10 @@ export function isInside(dir, path) {
     return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
 }
 /** Like `readScene`, but stops with the diagnostics when the scene has errors. */
-export function requireScene(project) {
-    const { scene, diagnostics } = readScene(project);
+export function requireScene(project, scenePath) {
+    const { scene, diagnostics, label } = readScene(project, scenePath);
     if (!scene) {
-        throw new CliError(`${formatDiagnostics(diagnostics, project.entryLabel)}\n\nFix the errors above (see \`ludra check\`) and try again.`);
+        throw new CliError(`${formatDiagnostics(diagnostics, label)}\n\nFix the errors above (see \`ludra check\`) and try again.`);
     }
     return scene;
 }