@ludra/cli 0.3.1 → 0.5.0

package/dist/commands/check.d.ts

@@ -1,3 +1,3 @@
 export declare function check(dir: string, options: {
     json?: boolean;
-}): number;
+}): Promise<number>;

package/dist/commands/check.js

@@ -1,8 +1,9 @@
 import { formatDiagnostics, paint } from "../format.js";
-import { loadProject, readScene } from "../project.js";
-export function check(dir, options) {
+import { loadGame, loadProject } from "../project.js";
+export async function check(dir, options) {
     const project = loadProject(dir);
-    const { scene, diagnostics } = readScene(project);
+    const { game, diagnostics } = await loadGame(project);
+    const scene = game?.scene;
     const errors = diagnostics.filter((d) => d.severity === "error").length;
     const warnings = diagnostics.length - errors;
     if (options.json) {

package/dist/commands/components.js

@@ -1,4 +1,4 @@
-import { COMPONENT_NAMES, COMPONENTS, EFFECT_FIELDS, EFFECTS_DESCRIPTION, EVENT_TYPES, isComponentName, PARTICLE_FIELDS, SOUND_PRESETS, } from "@ludra/core";
+import { COMPONENT_NAMES, COMPONENTS, EFFECT_FIELDS, EFFECTS_DESCRIPTION, EVENT_TYPES, isComponentName, PARTICLE_FIELDS, SCRIPT_API_REFERENCE, SOUND_PRESETS, } from "@ludra/core";
 import { pad, paint } from "../format.js";
 import { CliError } from "../project.js";
 const EFFECTS_EXAMPLE = `"effects": {
@@ -23,6 +23,10 @@ export function components(name, options) {
         if (spec.requires?.length)
             console.log(paint("dim", `  requires: ${spec.requires.join(", ")}`));
         printFields(spec.fields);
+        if (n === "script" && name === "script")
+            console.log(`\n${SCRIPT_API_REFERENCE.replace(/^/gm, "  ")}`);
+        else if (n === "script")
+            console.log(paint("dim", "  Run `ludra components script` for the script API."));
         console.log();
     }
     if (showEffects) {

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, SCRIPT_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);
@@ -122,7 +43,8 @@ import { startGame } from "${browserModule}";
 
 const data = await (await fetch("/__ludra/scene")).json();
 if (data.ok) {
-  await startGame(document.getElementById("game"), data.scene, { assetBase: "${PROJECT_PREFIX}" });
+  const scriptPaths = await (await fetch("/__ludra/scripts")).json();
+  await startGame(document.getElementById("game"), data.scene, { assetBase: "${PROJECT_PREFIX}", scriptBase: "${SCRIPT_PREFIX}", scriptPaths });
 } else {
   document.getElementById("game").hidden = true;
   const errors = document.getElementById("errors");

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,14 +1,17 @@
-import { defaultDuration, InputScript, parseDuration, renderAscii, secondsToFrames, simulate, World, } from "@ludra/core";
+import { defaultDuration, InputScript, parseDuration, renderAscii, ScriptError, 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 { CliError, loadProject, requireScene } from "../project.js";
+import { captureScreenshots } from "../headless.js";
+import { CliError, loadProject, requireGame } 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 { scene, scripts } = await requireGame(project);
     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"))));
-    const world = new World(scene);
+    const world = scriptErrors(() => new World(scene, { scripts }));
     const watch = options.watch
         ? options.watch.split(",").map((id) => id.trim()).filter(Boolean)
         : world.entities.filter((e) => e.platformer).map((e) => e.id);
@@ -18,19 +21,20 @@ export function play(dir, options) {
         }
     }
     const rows = [];
-    simulate(world, script, frames, (w) => {
+    scriptErrors(() => simulate(world, script, frames, (w) => {
         if (w.frame % every !== 0 && w.frame !== frames)
             return;
         const snapshot = w.snapshot();
         const input = w.frame === 0 ? [] : [...script.at(w.frame - 1)];
         rows.push({ time: w.time, input, entities: Object.fromEntries(watch.map((id) => [id, snapshot.entities[id] ?? null])) });
-    });
+    }));
     const columns = Number(options.columns ?? 80);
     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`));
@@ -62,7 +96,8 @@ function printTimeline(rows, watch) {
 function printEvents(events) {
     console.log(`\n${paint("bold", "Events")}${events.length === 0 ? paint("dim", " (none)") : ""}`);
     for (const event of events.slice(0, MAX_EVENTS_SHOWN)) {
-        console.log(`  ${pad(`${fixed(event.time, 2)}s`, 7)} ${pad(event.type, 8)} ${describeEvent(event)}`);
+        const name = event.type === "custom" ? event.name : event.type;
+        console.log(`  ${pad(`${fixed(event.time, 2)}s`, 7)} ${pad(name, 9)} ${describeEvent(event)}`);
     }
     if (events.length > MAX_EVENTS_SHOWN)
         console.log(paint("dim", `  … ${events.length - MAX_EVENTS_SHOWN} more (use --json for all)`));
@@ -76,11 +111,24 @@ function describeEvent(event) {
         case "die":
             return `${event.entity} ${event.cause === "fall" ? "fell out of the world" : `hit ${event.cause}`}, respawned`;
         case "win":
-            return `${event.entity} reached ${event.goal}`;
+            return event.entity === event.goal ? `${event.entity} (script) completed the level` : `${event.entity} reached ${event.goal}`;
+        case "custom":
+            return `from ${event.entity}'s script${event.data === undefined ? "" : ` ${JSON.stringify(event.data)}`}`;
         default:
             return event.entity;
     }
 }
+/** Reports a failing script as a CLI error naming the file, entity, hook and frame. */
+function scriptErrors(fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        if (err instanceof ScriptError)
+            throw new CliError(`Script error in ${err.message}`);
+        throw err;
+    }
+}
 /** Turns engine parse errors into user-facing CLI errors. */
 function parse(fn) {
     try {

package/dist/commands/test.d.ts

@@ -1,3 +1,3 @@
 export declare function test(dir: string, options: {
     json?: boolean;
-}): number;
+}): Promise<number>;

package/dist/commands/test.js

@@ -2,10 +2,10 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { runTest } from "@ludra/core";
 import { paint } from "../format.js";
-import { loadProject, requireScene } from "../project.js";
-export function test(dir, options) {
+import { loadProject, requireGame } from "../project.js";
+export async function test(dir, options) {
     const project = loadProject(dir);
-    const scene = requireScene(project);
+    const { scene, scripts } = await requireGame(project);
     const testsDir = join(project.dir, "tests");
     const files = existsSync(testsDir) ? readdirSync(testsDir).filter((f) => f.endsWith(".test.json")).sort() : [];
     if (files.length === 0) {
@@ -27,7 +27,7 @@ export function test(dir, options) {
         catch (err) {
             return { file, error: err.message, tests: [] };
         }
-        return { file, tests: cases.map((c) => runTest(scene, c)) };
+        return { file, tests: cases.map((c) => runTest(scene, c, { scripts })) };
     });
     const all = results.flatMap((r) => r.tests);
     const failed = all.filter((t) => !t.pass).length + results.filter((r) => r.error).length;

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,204 @@
+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, SCRIPT_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)},
+        scriptBase: ${JSON.stringify(SCRIPT_PREFIX)},
+        scriptPaths: await (await fetch("/__ludra/scripts")).json(),
+        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

@@ -8,6 +8,14 @@ import { play } from "./commands/play.js";
 import { test } from "./commands/test.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
+// experimental on every use. That warning is noise for game authors, so drop just that one.
+const emitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...rest) => {
+    if (String(warning instanceof Error ? warning.message : warning).includes("stripTypeScriptTypes"))
+        return;
+    return emitWarning(warning, ...rest);
+});
 const HELP = `ludra: the game engine built for AI agents
 
 Usage
@@ -20,13 +28,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 +47,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 +78,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/project.d.ts

@@ -1,4 +1,4 @@
-import { type Diagnostic, type SceneDef } from "@ludra/core";
+import { type Diagnostic, type SceneDef, type Script } from "@ludra/core";
 /** An error whose message is meant for the user (or agent) as-is, without a stack trace. */
 export declare class CliError extends Error {
 }
@@ -24,6 +24,22 @@ export interface SceneLoad {
 }
 /** Reads and validates the entry scene. JSON syntax errors become diagnostics too. */
 export declare function readScene(project: Project): 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 {
+    scene: SceneDef;
+    scripts: Map<string, Script>;
+}
+/**
+ * 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<{
+    game?: Game;
+    diagnostics: Diagnostic[];
+}>;
+/** Like `loadGame`, but stops with the diagnostics when anything is wrong. */
+export declare function requireGame(project: Project): 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;

package/dist/project.js

@@ -1,6 +1,15 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
-import { collectAssetPaths, validateScene } from "@ludra/core";
+import { pathToFileURL } from "node:url";
+import { collectAssetPaths, findRuntimeImports, validateScene, validateScriptModule, } from "@ludra/core";
 import { formatDiagnostics } from "./format.js";
 /** An error whose message is meant for the user (or agent) as-is, without a stack trace. */
 export class CliError extends Error {
@@ -61,25 +70,98 @@ 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 available = listAssets(project.dir);
+        const folder = ref.kind === "script" ? "scripts" : "assets";
+        const available = listFiles(project.dir, folder);
         return {
             severity: "error",
             code: "E_ASSET_MISSING",
             path: ref.at,
             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. "assets/player.svg").`,
+            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"}").`,
         };
     });
 }
-function listAssets(dir) {
-    const assetsDir = join(dir, "assets");
-    if (!existsSync(assetsDir))
+/** Files under a project folder, as project-relative paths with forward slashes. */
+function listFiles(dir, folder) {
+    const root = join(dir, folder);
+    if (!existsSync(root))
         return [];
-    return readdirSync(assetsDir, { recursive: true, withFileTypes: true })
+    return readdirSync(root, { recursive: true, withFileTypes: true })
         .filter((entry) => entry.isFile())
         .map((entry) => relative(dir, join(entry.parentPath, entry.name)).replaceAll("\\", "/"))
         .sort();
 }
+/** Script files a game can use: those the scene references, plus everything in scripts/ (for world.spawn). */
+export function scriptPaths(project, scene) {
+    const referenced = collectAssetPaths(scene).filter((ref) => ref.kind === "script").map((ref) => ref.path);
+    const inFolder = listFiles(project.dir, "scripts").filter((path) => /\.(ts|js)$/.test(path) && !path.endsWith(".d.ts"));
+    return [...new Set([...referenced, ...inFolder])];
+}
+/**
+ * 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);
+    if (!scene)
+        return { diagnostics };
+    const scripts = new Map();
+    for (const src of scriptPaths(project, scene)) {
+        const file = resolve(project.dir, src);
+        if (!isInside(project.dir, file) || !existsSync(file))
+            continue; // reported by readScene
+        const imports = findRuntimeImports(readFileSync(file, "utf8"));
+        if (imports.length > 0) {
+            diagnostics.push({
+                severity: "error",
+                code: "E_SCRIPT_IMPORT",
+                path: src,
+                message: `${src} imports ${imports.map((i) => `"${i}"`).join(", ")}. Scripts run without a bundler and cannot import runtime code.`,
+                fix: 'Use "import type" for types (e.g. import type { Script } from "@ludra/core"), and put shared helpers inside the script.',
+            });
+            continue;
+        }
+        let module;
+        try {
+            module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+        }
+        catch (err) {
+            diagnostics.push({ severity: "error", code: "E_SCRIPT_LOAD", path: src, ...describeLoadError(err, src) });
+            continue;
+        }
+        const problems = validateScriptModule(module, src);
+        diagnostics.push(...problems);
+        if (!problems.some((d) => d.severity === "error"))
+            scripts.set(src, module.default);
+    }
+    const ok = !diagnostics.some((d) => d.severity === "error");
+    return { game: ok ? { scene, scripts } : undefined, diagnostics };
+}
+/**
+ * Node's syntax errors carry the location only in the stack: "file:///...:LINE", the source
+ * line, then a caret. Pull those out so the diagnostic points at the code.
+ */
+function describeLoadError(err, src) {
+    const error = err;
+    const lines = String(error.stack ?? "").split("\n");
+    const at = lines.findIndex((line) => /^file:\/\/.*:\d+$/.test(line));
+    if (at < 0)
+        return { message: `${src} failed to load: ${error.message}` };
+    const line = lines[at].slice(lines[at].lastIndexOf(":") + 1);
+    const code = lines[at + 1] ?? "";
+    const caret = lines[at + 2] ?? "";
+    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);
+    if (!game) {
+        throw new CliError(`${formatDiagnostics(diagnostics, project.entryLabel)}\n\nFix the errors above (see \`ludra check\`) and try again.`);
+    }
+    return game;
+}
 export function isInside(dir, path) {
     const rel = relative(dir, path);
     return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { type Server } from "node:http";
+import { type Project } from "./project.ts";
+export declare const PROJECT_PREFIX = "/__ludra/project/";
+export declare const SCRIPT_PREFIX = "/__ludra/script/";
+/** 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,112 @@
+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, scriptPaths } from "./project.js";
+export const PROJECT_PREFIX = "/__ludra/project/";
+export const SCRIPT_PREFIX = "/__ludra/script/";
+/** 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 === "/__ludra/scripts") {
+                const { scene } = readScene(project);
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify(scene ? scriptPaths(project, scene) : []));
+            }
+            else if (url.pathname.startsWith(SCRIPT_PREFIX)) {
+                // Only the game's own script files, type-stripped so the browser can import them.
+                const path = decodeURIComponent(url.pathname.slice(SCRIPT_PREFIX.length));
+                const { scene } = readScene(project);
+                const file = resolve(project.dir, path);
+                if (!scene || !scriptPaths(project, scene).includes(path) || !isInside(project.dir, file) || !existsSync(file))
+                    return notFound(res);
+                const source = readFileSync(file, "utf8");
+                res.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-cache" });
+                res.end(extname(file) === ".ts" ? stripTypeScriptTypes(source) : source);
+            }
+            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)));
+        files.push(...scriptPaths(project, scene).map((path) => resolve(project.dir, 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.5.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.5.0"
   },
   "keywords": [
     "game-engine",

package/templates/platformer/CLAUDE.md

@@ -7,13 +7,14 @@ A game built with Ludra, a game engine designed for AI agents.
 - `ludra.json`: project config (name, entry scene, window size)
 - `scenes/main.scene.json`: the level. Entities are made of components; `effects` adds particles, sound and shake to game events.
 - `assets/`: SVG art. Spritesheets are frames side by side; tiles repeat.
+- `scripts/`: custom game logic in TypeScript (create it when needed). Run `npx @ludra/cli components script` for the API.
 - `tests/*.test.json`: gameplay tests, run headlessly
 
 ## Loop
 
 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.
 
@@ -28,3 +29,4 @@ Never call a change done until `ludra check` and `ludra test` both pass.
 - A jump only triggers on a new press, so put a segment without jump between two jump segments.
 - The level is done when a test proves `won == true` with `deaths == 0`.
 - Art and effects never change gameplay. Make it playable first, then dress it. Write new art as SVG in `assets/`.
+- For behavior no component provides (chasing, keys, timers, shooting), write a script and attach it with a `script` component. Use `world.random()`, never `Math.random()`, and test what it does through `self.state` and `world.emit`.

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.5.0"
   }
 }