@ludra/cli 0.4.0 → 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.js

@@ -1,6 +1,6 @@
 import { paint } from "../format.js";
 import { CliError, loadProject } from "../project.js";
-import { createGameServer, PROJECT_PREFIX } from "../server.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);
@@ -43,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/play.js

@@ -1,17 +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 { captureScreenshots } from "../headless.js";
-import { CliError, loadProject, requireScene } from "../project.js";
+import { CliError, loadProject, requireGame } from "../project.js";
 const MAX_EVENTS_SHOWN = 40;
 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);
@@ -21,13 +21,13 @@ export async 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}".`);
@@ -96,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)`));
@@ -110,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.js

@@ -3,7 +3,7 @@ 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";
+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
@@ -78,6 +78,8 @@ export async function captureScreenshots(project, request) {
       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)},
       });

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

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

@@ -1,6 +1,7 @@
 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 {

package/dist/server.js

@@ -4,8 +4,9 @@ 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";
+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 = {
@@ -49,6 +50,22 @@ export function createGameServer(project, indexHtml) {
                 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)));
@@ -83,8 +100,10 @@ function version(project) {
         return "missing";
     const files = [project.entryPath];
     const { scene } = readScene(project);
-    if (scene)
+    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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludra/cli",
-  "version": "0.4.0",
+  "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.4.0"
+    "@ludra/core": "0.5.0"
   },
   "keywords": [
     "game-engine",

package/templates/platformer/CLAUDE.md

@@ -7,6 +7,7 @@ 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
@@ -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/package.json

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