@ludra/cli 0.3.1 → 0.4.0

package/dist/commands/dev.d.ts

@@ -1,8 +1,4 @@
-/**
- * Serves the game with the engine's browser runtime and reloads the page when
- * the scene file changes. No bundler: when the engine runs from source, its
- * TypeScript files are type-stripped on the fly.
- */
+/** Serves the game for a human to play, and reloads the page when the scene or its assets change. */
 export declare function dev(dir: string, options: {
     port?: string;
 }): number;

package/dist/commands/dev.js

@@ -1,66 +1,13 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { createServer } from "node:http";
-import { stripTypeScriptTypes } from "node:module";
-import { dirname, extname, join, relative, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-import { collectAssetPaths } from "@ludra/core";
 import { paint } from "../format.js";
-import { CliError, isInside, loadProject, readScene } from "../project.js";
-/**
- * Serves the game with the engine's browser runtime and reloads the page when
- * the scene file changes. No bundler: when the engine runs from source, its
- * TypeScript files are type-stripped on the fly.
- */
+import { CliError, loadProject } from "../project.js";
+import { createGameServer, PROJECT_PREFIX } from "../server.js";
+/** Serves the game for a human to play, and reloads the page when the scene or its assets change. */
 export function dev(dir, options) {
     const project = loadProject(dir);
     const port = Number(options.port ?? 5173);
     if (!Number.isInteger(port) || port <= 0)
         throw new CliError(`Invalid --port "${options.port}".`);
-    const coreEntry = fileURLToPath(import.meta.resolve("@ludra/core/browser"));
-    const coreDir = dirname(coreEntry);
-    const browserModule = `/__ludra/core/${relative(coreDir, coreEntry).replaceAll(sep, "/")}`;
-    const server = createServer((req, res) => {
-        const url = new URL(req.url ?? "/", "http://localhost");
-        try {
-            if (url.pathname === "/") {
-                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-                res.end(page(project, browserModule));
-            }
-            else if (url.pathname === "/__ludra/scene") {
-                const { scene, diagnostics } = readScene(project);
-                res.writeHead(200, { "content-type": "application/json" });
-                res.end(JSON.stringify({ ok: !!scene, scene, diagnostics }));
-            }
-            else if (url.pathname === "/__ludra/version") {
-                res.writeHead(200, { "content-type": "text/plain" });
-                res.end(version(project));
-            }
-            else if (url.pathname.startsWith(PROJECT_PREFIX)) {
-                // Only media files inside the project are served, never source or config.
-                const file = resolve(project.dir, decodeURIComponent(url.pathname.slice(PROJECT_PREFIX.length)));
-                const type = MEDIA_TYPES[extname(file).toLowerCase()];
-                if (!type || !isInside(project.dir, file) || !existsSync(file))
-                    return notFound(res);
-                res.writeHead(200, { "content-type": type, "cache-control": "no-cache" });
-                res.end(readFileSync(file));
-            }
-            else if (url.pathname.startsWith("/__ludra/core/")) {
-                const file = join(coreDir, decodeURIComponent(url.pathname.slice("/__ludra/core/".length)));
-                if (!file.startsWith(coreDir + sep) || !existsSync(file))
-                    return notFound(res);
-                const source = readFileSync(file, "utf8");
-                res.writeHead(200, { "content-type": "text/javascript; charset=utf-8" });
-                res.end(extname(file) === ".ts" ? stripTypeScriptTypes(source) : source);
-            }
-            else {
-                notFound(res);
-            }
-        }
-        catch (err) {
-            res.writeHead(500, { "content-type": "text/plain" });
-            res.end(err.message);
-        }
-    });
+    const { server } = createGameServer(project, (browserModule) => page(project, browserModule));
     server.on("error", (err) => {
         console.error(paint("red", err.code === "EADDRINUSE" ? `Port ${port} is in use. Try --port ${port + 1}.` : err.message));
         process.exit(1);
@@ -72,32 +19,6 @@ export function dev(dir, options) {
     });
     return 0;
 }
-const PROJECT_PREFIX = "/__ludra/project/";
-const MEDIA_TYPES = {
-    ".svg": "image/svg+xml",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".gif": "image/gif",
-    ".webp": "image/webp",
-    ".wav": "audio/wav",
-    ".mp3": "audio/mpeg",
-    ".ogg": "audio/ogg",
-};
-/** Changes whenever the scene or any file it references changes, so the page knows to reload. */
-function version(project) {
-    if (!existsSync(project.entryPath))
-        return "missing";
-    const files = [project.entryPath];
-    const { scene } = readScene(project);
-    if (scene)
-        files.push(...collectAssetPaths(scene).map((ref) => resolve(project.dir, ref.path)));
-    return files.map((file) => (existsSync(file) ? statSync(file).mtimeMs : 0)).join(":");
-}
-function notFound(res) {
-    res.writeHead(404, { "content-type": "text/plain" });
-    res.end("Not found");
-}
 function page(project, browserModule) {
     const { width, height } = project.config.window;
     const title = escapeHtml(project.config.name);

package/dist/commands/new.js

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { paint } from "../format.js";
@@ -19,6 +19,10 @@ export function create(dir, options) {
     }
     const name = basename(target);
     cpSync(source, target, { recursive: true });
+    // npm never publishes files named .gitignore, so templates ship it as _gitignore.
+    const gitignore = join(target, "_gitignore");
+    if (existsSync(gitignore))
+        renameSync(gitignore, join(target, ".gitignore"));
     for (const file of listFiles(target)) {
         const text = readFileSync(file, "utf8");
         if (text.includes("{{name}}"))

package/dist/commands/play.d.ts

@@ -5,6 +5,8 @@ export interface PlayOptions {
     every?: string;
     ascii?: boolean;
     columns?: string;
+    screenshot?: string;
+    out?: string;
     json?: boolean;
 }
-export declare function play(dir: string, options: PlayOptions): number;
+export declare function play(dir: string, options: PlayOptions): Promise<number>;

package/dist/commands/play.js

@@ -1,8 +1,11 @@
 import { defaultDuration, InputScript, parseDuration, renderAscii, secondsToFrames, simulate, World, } from "@ludra/core";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
 import { fixed, pad, padStart, paint } from "../format.js";
+import { captureScreenshots } from "../headless.js";
 import { CliError, loadProject, requireScene } from "../project.js";
 const MAX_EVENTS_SHOWN = 40;
-export function play(dir, options) {
+export async function play(dir, options) {
     const project = loadProject(dir);
     const scene = requireScene(project);
     const script = parse(() => InputScript.parse(options.inputs ?? ""));
@@ -29,8 +32,9 @@ export function play(dir, options) {
     if (!Number.isInteger(columns) || columns < 10)
         throw new CliError(`--columns must be a whole number of at least 10, got "${options.columns}".`);
     const ascii = options.ascii ? renderAscii(world, { columns }) : undefined;
+    const screenshots = options.screenshot ? await takeScreenshots(project, options, frames) : undefined;
     if (options.json) {
-        console.log(JSON.stringify({ duration: frames / 60, frames, inputs: options.inputs ?? "", timeline: rows, events: world.events, final: world.snapshot(), ascii }, null, 2));
+        console.log(JSON.stringify({ duration: frames / 60, frames, inputs: options.inputs ?? "", timeline: rows, events: world.events, final: world.snapshot(), ascii, screenshots }, null, 2));
         return 0;
     }
     console.log(paint("bold", `▶ ${project.config.name}: simulated ${fixed(frames / 60, 2)}s (${frames} frames)`) +
@@ -42,8 +46,38 @@ export function play(dir, options) {
     console.log(`\n${paint("bold", "Final:")} ${outcome} · score ${world.score} · deaths ${world.deaths} · ${world.entities.length} entities`);
     if (ascii)
         console.log(`\n${ascii}`);
+    if (screenshots) {
+        console.log(`\n${paint("bold", "Screenshots")} ${paint("dim", "(open these PNGs to see the frames)")}`);
+        for (const shot of screenshots)
+            console.log(`  ${pad(`${fixed(shot.time, 2)}s`, 7)} ${shot.file}`);
+    }
     return 0;
 }
+/**
+ * Renders moments of the same run in a headless browser and writes them as
+ * PNGs. `--screenshot` is a comma list of times and/or "end".
+ */
+async function takeScreenshots(project, options, lastFrame) {
+    const requested = options.screenshot.split(",").map((part) => {
+        const token = part.trim();
+        if (token === "end")
+            return lastFrame;
+        const frame = secondsToFrames(parse(() => parseDuration(token)));
+        if (frame > lastFrame) {
+            throw new CliError(`--screenshot ${token} is after the end of the run (${fixed(lastFrame / 60, 2)}s). Use a longer --duration.`);
+        }
+        return frame;
+    });
+    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 });
+    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"));
+        return { time: shot.time, frame: shot.frame, file: relative(process.cwd(), path).replaceAll("\\", "/") };
+    });
+}
 function printTimeline(rows, watch) {
     const idWidth = Math.max(6, ...watch.map((id) => id.length));
     console.log(paint("dim", `\n  ${pad("time", 7)} ${pad("input", 14)} ${pad("entity", idWidth)} ${padStart("x", 8)} ${padStart("y", 8)} ${padStart("vx", 8)} ${padStart("vy", 8)}  grounded`));

package/dist/headless.d.ts

@@ -0,0 +1,16 @@
+import type { CapturedFrame } from "@ludra/core/browser";
+import { type Project } from "./project.ts";
+/**
+ * Finds an installed Chromium-based browser: LUDRA_BROWSER if set, otherwise
+ * Chrome, Edge or Chromium in their usual places.
+ */
+export declare function findBrowser(): string | undefined;
+export interface ScreenshotRequest {
+    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

@@ -0,0 +1,202 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { CliError } from "./project.js";
+import { BLANK_PATH, createGameServer, PROJECT_PREFIX } from "./server.js";
+const TIMEOUT_MS = 60_000;
+/**
+ * Finds an installed Chromium-based browser: LUDRA_BROWSER if set, otherwise
+ * Chrome, Edge or Chromium in their usual places.
+ */
+export function findBrowser() {
+    const fromEnv = process.env.LUDRA_BROWSER;
+    if (fromEnv)
+        return existsSync(fromEnv) ? fromEnv : undefined;
+    const candidates = [];
+    if (process.platform === "win32") {
+        for (const base of [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA]) {
+            if (!base)
+                continue;
+            candidates.push(join(base, "Google", "Chrome", "Application", "chrome.exe"), join(base, "Microsoft", "Edge", "Application", "msedge.exe"));
+        }
+    }
+    else if (process.platform === "darwin") {
+        candidates.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge");
+    }
+    else {
+        const names = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge"];
+        for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+            for (const name of names)
+                candidates.push(join(dir, name));
+        }
+    }
+    return candidates.find((path) => existsSync(path));
+}
+/**
+ * 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 async function captureScreenshots(project, request) {
+    const browserPath = findBrowser();
+    if (!browserPath) {
+        throw new CliError("Screenshots need Chrome, Edge or Chromium installed, and none was found.\n" +
+            "Install one, or set LUDRA_BROWSER to the path of a Chromium-based browser.");
+    }
+    const { server, browserModule } = createGameServer(project, () => "");
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const profile = mkdtempSync(join(tmpdir(), "ludra-browser-"));
+    let browser;
+    let cdp;
+    try {
+        const { width, height } = project.config.window;
+        browser = spawn(browserPath, [
+            "--headless=new",
+            "--remote-debugging-port=0",
+            `--user-data-dir=${profile}`,
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--mute-audio",
+            "--hide-scrollbars",
+            `--window-size=${width},${height}`,
+            "about:blank",
+        ], { stdio: ["ignore", "ignore", "pipe"] });
+        cdp = await Cdp.connect(await devToolsUrl(browser));
+        const origin = `http://127.0.0.1:${port}`;
+        const { targetId } = await cdp.send("Target.createTarget", { url: origin + BLANK_PATH });
+        const { sessionId } = await cdp.send("Target.attachToTarget", { targetId, flatten: true });
+        // The new tab starts on about:blank; wait until it has loaded the game server's page.
+        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();
+      if (!data.ok) throw new Error("The scene has errors. Run ludra check.");
+      const canvas = document.createElement("canvas");
+      canvas.width = ${width};
+      canvas.height = ${height};
+      document.body.append(canvas);
+      return captureFrames(canvas, data.scene, {
+        assetBase: ${JSON.stringify(PROJECT_PREFIX)},
+        inputs: ${JSON.stringify(request.inputs)},
+        frames: ${JSON.stringify(request.frames)},
+      });
+    })()`;
+        return await evaluate(cdp, sessionId, script);
+    }
+    finally {
+        await cdp?.send("Browser.close").catch(() => { });
+        cdp?.close();
+        if (browser && browser.exitCode === null) {
+            await new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    browser.kill();
+                    resolve(undefined);
+                }, 3000);
+                browser.once("exit", () => {
+                    clearTimeout(timer);
+                    resolve(undefined);
+                });
+            });
+        }
+        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 });
+    }
+}
+/** Chrome prints "DevTools listening on ws://..." to stderr once it is ready. */
+function devToolsUrl(browser) {
+    return new Promise((resolve, reject) => {
+        let output = "";
+        const timer = setTimeout(() => reject(new CliError(`The browser did not start in time.\n${output.trim()}`)), TIMEOUT_MS);
+        browser.stderr.on("data", (chunk) => {
+            output += chunk.toString();
+            const match = /DevTools listening on (ws:\/\/\S+)/.exec(output);
+            if (match) {
+                clearTimeout(timer);
+                resolve(match[1]);
+            }
+        });
+        browser.once("exit", (code) => {
+            clearTimeout(timer);
+            reject(new CliError(`The browser exited before it was ready (code ${code}).\n${output.trim()}`));
+        });
+        browser.once("error", (err) => {
+            clearTimeout(timer);
+            reject(new CliError(`Could not start the browser: ${err.message}`));
+        });
+    });
+}
+async function waitFor(cdp, sessionId, condition) {
+    const deadline = Date.now() + TIMEOUT_MS;
+    while (!(await evaluate(cdp, sessionId, condition))) {
+        if (Date.now() > deadline)
+            throw new CliError("The browser did not load the game page in time.");
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
+async function evaluate(cdp, sessionId, expression) {
+    const result = await cdp.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true }, sessionId);
+    if (result.exceptionDetails) {
+        const details = result.exceptionDetails;
+        throw new CliError(`Rendering failed in the browser: ${details.exception?.description ?? details.text ?? "unknown error"}`);
+    }
+    return result.result.value;
+}
+/** A minimal Chrome DevTools Protocol client over the WebSocket built into Node. */
+class Cdp {
+    nextId = 1;
+    pending = new Map();
+    socket;
+    constructor(socket) {
+        this.socket = socket;
+        socket.addEventListener("message", (event) => {
+            const message = JSON.parse(String(event.data));
+            if (message.id === undefined)
+                return;
+            const waiter = this.pending.get(message.id);
+            if (!waiter)
+                return;
+            this.pending.delete(message.id);
+            if (message.error)
+                waiter.reject(new CliError(`Browser error: ${message.error.message}`));
+            else
+                waiter.resolve(message.result);
+        });
+        socket.addEventListener("close", () => {
+            for (const waiter of this.pending.values())
+                waiter.reject(new CliError("The browser closed unexpectedly."));
+            this.pending.clear();
+        });
+    }
+    static connect(url) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(url);
+            socket.addEventListener("open", () => resolve(new Cdp(socket)), { once: true });
+            socket.addEventListener("error", () => reject(new CliError(`Could not connect to the browser at ${url}.`)), { once: true });
+        });
+    }
+    send(method, params = {}, sessionId) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new CliError(`The browser did not answer ${method} in time.`));
+            }, TIMEOUT_MS);
+            this.pending.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            });
+            this.socket.send(JSON.stringify({ id, method, params, sessionId }));
+        });
+    }
+    close() {
+        this.socket.close();
+    }
+}

package/dist/index.js

@@ -20,13 +20,15 @@ Usage
       --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 components [name] [--json]             Reference for every component and field
   ludra dev [folder] [--port 5173]             Play the game in the browser with live reload
 
 Folder defaults to the current directory.`;
-function main(argv) {
+async function main(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
@@ -37,6 +39,8 @@ function main(argv) {
             every: { type: "string" },
             ascii: { type: "boolean" },
             columns: { type: "string" },
+            screenshot: { type: "string" },
+            out: { type: "string" },
             json: { type: "boolean" },
             template: { type: "string" },
             port: { type: "string" },
@@ -66,7 +70,7 @@ function main(argv) {
     }
 }
 try {
-    process.exitCode = main(process.argv.slice(2));
+    process.exitCode = await main(process.argv.slice(2));
 }
 catch (err) {
     // parseArgs reports unknown flags with a code; show those like our own errors.

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+import { type Server } from "node:http";
+import { type Project } from "./project.ts";
+export declare const PROJECT_PREFIX = "/__ludra/project/";
+/** An empty same-origin page that headless capture loads before importing the engine. */
+export declare const BLANK_PATH = "/__ludra/blank";
+export interface GameServer {
+    server: Server;
+    /** URL path of the engine's browser module, for `import()` in the page. */
+    browserModule: string;
+}
+/**
+ * Serves a project to a browser: the engine's browser runtime, the validated
+ * scene and the project's media. No bundler: when the engine runs from
+ * source, its TypeScript files are type-stripped on the fly.
+ * `indexHtml` builds the page served at "/".
+ */
+export declare function createGameServer(project: Project, indexHtml: (browserModule: string) => string): GameServer;

package/dist/server.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { stripTypeScriptTypes } from "node:module";
+import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectAssetPaths } from "@ludra/core";
+import { isInside, readScene } from "./project.js";
+export const PROJECT_PREFIX = "/__ludra/project/";
+/** An empty same-origin page that headless capture loads before importing the engine. */
+export const BLANK_PATH = "/__ludra/blank";
+const MEDIA_TYPES = {
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".wav": "audio/wav",
+    ".mp3": "audio/mpeg",
+    ".ogg": "audio/ogg",
+};
+/**
+ * Serves a project to a browser: the engine's browser runtime, the validated
+ * scene and the project's media. No bundler: when the engine runs from
+ * source, its TypeScript files are type-stripped on the fly.
+ * `indexHtml` builds the page served at "/".
+ */
+export function createGameServer(project, indexHtml) {
+    const coreEntry = fileURLToPath(import.meta.resolve("@ludra/core/browser"));
+    const coreDir = dirname(coreEntry);
+    const browserModule = `/__ludra/core/${relative(coreDir, coreEntry).replaceAll(sep, "/")}`;
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        try {
+            if (url.pathname === "/") {
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end(indexHtml(browserModule));
+            }
+            else if (url.pathname === BLANK_PATH) {
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end('<!doctype html><html><head><meta charset="utf-8"><title>Ludra</title></head><body style="margin:0"></body></html>');
+            }
+            else if (url.pathname === "/__ludra/scene") {
+                const { scene, diagnostics } = readScene(project);
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ ok: !!scene, scene, diagnostics }));
+            }
+            else if (url.pathname === "/__ludra/version") {
+                res.writeHead(200, { "content-type": "text/plain" });
+                res.end(version(project));
+            }
+            else if (url.pathname.startsWith(PROJECT_PREFIX)) {
+                // Only media files inside the project are served, never source or config.
+                const file = resolve(project.dir, decodeURIComponent(url.pathname.slice(PROJECT_PREFIX.length)));
+                const type = MEDIA_TYPES[extname(file).toLowerCase()];
+                if (!type || !isInside(project.dir, file) || !existsSync(file))
+                    return notFound(res);
+                res.writeHead(200, { "content-type": type, "cache-control": "no-cache" });
+                res.end(readFileSync(file));
+            }
+            else if (url.pathname.startsWith("/__ludra/core/")) {
+                const file = join(coreDir, decodeURIComponent(url.pathname.slice("/__ludra/core/".length)));
+                if (!file.startsWith(coreDir + sep) || !existsSync(file))
+                    return notFound(res);
+                const source = readFileSync(file, "utf8");
+                res.writeHead(200, { "content-type": "text/javascript; charset=utf-8" });
+                res.end(extname(file) === ".ts" ? stripTypeScriptTypes(source) : source);
+            }
+            else {
+                notFound(res);
+            }
+        }
+        catch (err) {
+            res.writeHead(500, { "content-type": "text/plain" });
+            res.end(err.message);
+        }
+    });
+    return { server, browserModule };
+}
+/** Changes whenever the scene or any file it references changes, so the page knows to reload. */
+function version(project) {
+    if (!existsSync(project.entryPath))
+        return "missing";
+    const files = [project.entryPath];
+    const { scene } = readScene(project);
+    if (scene)
+        files.push(...collectAssetPaths(scene).map((ref) => resolve(project.dir, ref.path)));
+    return files.map((file) => (existsSync(file) ? statSync(file).mtimeMs : 0)).join(":");
+}
+function notFound(res) {
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end("Not found");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludra/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "The game engine built for AI agents. The ludra command: create, check, play, test and run Ludra games.",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,7 @@
     "templates"
   ],
   "dependencies": {
-    "@ludra/core": "0.3.1"
+    "@ludra/core": "0.4.0"
   },
   "keywords": [
     "game-engine",

package/templates/platformer/CLAUDE.md

@@ -13,7 +13,7 @@ A game built with Ludra, a game engine designed for AI agents.
 
 1. Edit `scenes/main.scene.json`. Run `npx @ludra/cli components` for every component and field.
 2. Run `npx @ludra/cli check` after every edit. Each problem names the JSON path and a fix.
-3. Run `npx @ludra/cli play --inputs "right:1s, jump:0.4s" --ascii` to see what actually happens.
+3. Run `npx @ludra/cli play --inputs "right:1s, jump:0.4s" --ascii` to see what actually happens. Add `--screenshot 0.5s,end` to save real rendered frames to `screenshots/` and look at them.
 4. Write the behavior you want into `tests/*.test.json` and run `npx @ludra/cli test`.
 5. Run `npx @ludra/cli dev` so a human can play it in the browser.
 

package/templates/platformer/_gitignore

@@ -0,0 +1,2 @@
+node_modules/
+screenshots/

package/templates/platformer/package.json

@@ -8,6 +8,6 @@
     "test": "ludra test"
   },
   "devDependencies": {
-    "@ludra/cli": "^0.3.1"
+    "@ludra/cli": "^0.4.0"
   }
 }