@ludra/cli 0.4.0 → 0.7.0

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 {
@@ -56,30 +65,104 @@ export function readScene(project) {
     const missing = missingAssets(project, scene);
     return { scene: missing.length === 0 ? scene : undefined, diagnostics: [...diagnostics, ...missing] };
 }
-/** Image and audio files the scene references that are not in the project. */
+const EXAMPLE_FILE = { image: "player.svg", audio: "jump.wav", script: "enemy.ts", font: "pixel.woff2", shader: "crt.frag" };
+/** Files the scene references that are not in the project. */
 function missingAssets(project, scene) {
     return collectAssetPaths(scene)
         .filter((ref) => !isInside(project.dir, resolve(project.dir, ref.path)) || !existsSync(resolve(project.dir, ref.path)))
         .map((ref) => {
-        const available = listAssets(project.dir);
+        const folder = ref.kind === "script" ? "scripts" : ref.kind === "shader" ? "shaders" : "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}/${EXAMPLE_FILE[ref.kind]}").`,
         };
     });
 }
-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 = {
@@ -18,6 +19,12 @@ const MEDIA_TYPES = {
     ".wav": "audio/wav",
     ".mp3": "audio/mpeg",
     ".ogg": "audio/ogg",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".ttf": "font/ttf",
+    ".otf": "font/otf",
+    ".frag": "text/plain; charset=utf-8",
+    ".glsl": "text/plain; charset=utf-8",
 };
 /**
  * Serves a project to a browser: the engine's browser runtime, the validated
@@ -49,6 +56,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 +106,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.7.0",
   "description": "The game engine built for AI agents. The ludra command: create, check, play, test and run Ludra games.",
   "license": "MIT",
   "repository": {
@@ -31,10 +31,11 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "blocks"
   ],
   "dependencies": {
-    "@ludra/core": "0.4.0"
+    "@ludra/core": "0.7.0"
   },
   "keywords": [
     "game-engine",

package/templates/breakout/CLAUDE.md

@@ -0,0 +1,42 @@
+# {{name}}
+
+A breakout game built with Ludra, a game engine designed for AI agents.
+
+## Layout
+
+- `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.
+- `shaders/neon.frag`: the post-processing shader (bloom, chromatic aberration, scanlines, CRT curve).
+- `scripts/`: the game rules in TypeScript. Run `npx @ludra/cli components script` for the API.
+  - `ball.ts` rests on the paddle, launches, keeps a constant speed and costs a life when it falls out.
+  - `paddle.ts` aims the ball by where it hits the paddle.
+  - `brick.ts` breaks on contact and adds `points` to the score.
+  - `rules.ts` wins the level when no entity whose id starts with `prefix` is left, and draws the brick-break feedback and the whole interface (`drawUI`).
+  - `backdrop.ts` and `wall.ts` only draw: the synthwave sky and the neon walls.
+- `tests/*.test.json`: gameplay tests, run headlessly
+
+## Loop
+
+1. Edit `scenes/main.scene.json` or a script. 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 --watch ball,paddle --ascii` to see what actually happens. Add `--screenshot 1s,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.
+
+Never call a change done until `ludra check` and `ludra test` both pass.
+
+## Rules of thumb
+
+- Coordinates are entity centers in pixels; +y is down. The world has no gravity (`"gravity": 0`).
+- The paddle is a `kinematic` body with `topdown` `"directions": "x"`: left/right only, and it stops at walls.
+- The ball is a `dynamic` body with `"bounce": 1` and `"gravityScale": 0`. Bounce does the reflecting; `ball.ts` keeps the speed constant and never lets it fly almost flat.
+- Bricks are `static` bodies with `brick.ts`. Give each brick an id starting with `brick-` so `rules.ts` counts it.
+- The bottom of the world is open on purpose: that is where the ball is lost.
+- A level is done when a test proves `won == true` with `deaths == 0`. Long routes are easiest to find by writing a small autopilot that steers the paddle under the ball, then pasting its input (frame counts like `"left:24f"`) into the test.
+- Art and effects never change gameplay. Make it playable first, then dress it.
+
+## Looks
+
+Everything is drawn in code, no image files: each script has a `draw` hook next to its game logic. The scene loads the Orbitron font and runs `shaders/neon.frag` over every frame (tune it with `postfx.uniforms`).
+
+There are no limits on looks. A script's `draw(ctx)` paints with the real Canvas 2D context (`ctx.g`), `drawUI(ctx)` replaces the HUD, `"fonts"` loads Google Fonts, and `"postfx"` runs a GLSL shader over every frame. Run `npx @ludra/cli components script` for the API. Draw hooks only paint: they can't change the game, so tests stay valid. After every visual change, look at real frames with `play --screenshot`.

package/templates/breakout/_gitignore

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

package/templates/breakout/ludra.json

@@ -0,0 +1,5 @@
+{
+  "name": "{{name}}",
+  "entry": "scenes/main.scene.json",
+  "window": { "width": 960, "height": 540 }
+}

package/templates/breakout/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "ludra dev",
+    "check": "ludra check",
+    "test": "ludra test"
+  },
+  "devDependencies": {
+    "@ludra/cli": "^0.7.0"
+  }
+}