@ludra/cli 0.7.0 → 0.8.0

package/dist/project.js

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

package/dist/server.js

@@ -1,10 +1,10 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, 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";
+import { isInside, listScenes, 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. */
@@ -48,7 +48,8 @@ export function createGameServer(project, indexHtml) {
                 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);
+                // ?path= picks another scene, for goals with "next" and world.goto.
+                const { scene, diagnostics } = readScene(project, url.searchParams.get("path") ?? undefined);
                 res.writeHead(200, { "content-type": "application/json" });
                 res.end(JSON.stringify({ ok: !!scene, scene, diagnostics }));
             }
@@ -100,17 +101,23 @@ export function createGameServer(project, indexHtml) {
     });
     return { server, browserModule };
 }
-/** Changes whenever the scene or any file it references changes, so the page knows to reload. */
+/** Changes whenever a scene, prefab or any file they reference 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) {
+    const files = [];
+    for (const path of listScenes(project)) {
+        files.push(resolve(project.dir, path));
+        const { scene } = readScene(project, path);
+        if (!scene)
+            continue;
         files.push(...collectAssetPaths(scene).map((ref) => resolve(project.dir, ref.path)));
-        files.push(...scriptPaths(project, scene).map((path) => resolve(project.dir, path)));
+        files.push(...scriptPaths(project, scene).map((p) => resolve(project.dir, p)));
     }
-    return files.map((file) => (existsSync(file) ? statSync(file).mtimeMs : 0)).join(":");
+    const prefabs = join(project.dir, "prefabs");
+    if (existsSync(prefabs))
+        files.push(prefabs, ...readdirSync(prefabs).map((name) => join(prefabs, name)));
+    return [...new Set(files)].map((file) => (existsSync(file) ? statSync(file).mtimeMs : 0)).join(":");
 }
 function notFound(res) {
     res.writeHead(404, { "content-type": "text/plain" });

package/package.json

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

package/templates/breakout/CLAUDE.md

@@ -21,9 +21,10 @@ A breakout game built with Ludra, a game engine designed for AI agents.
 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.
+5. Run `npx @ludra/cli review` and fix every issue it lists: it catches what makes a game feel unfinished (untested mechanics, silent events, the default HUD, flat looks).
+6. 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.
+Never call a change done until `ludra check`, `ludra test` and `ludra review` are all clean.
 
 ## Rules of thumb
 

package/templates/breakout/package.json

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

package/templates/breakout/scenes/main.scene.json

@@ -4,7 +4,8 @@
     "width": 960,
     "height": 540,
     "gravity": 0,
-    "background": "#05001a"
+    "background": "#05001a",
+    "lives": 3
   },
   "fonts": {
     "Orbitron": "google"
@@ -38,10 +39,14 @@
     "launch": {
       "sound": "jump"
     },
-    "ball-lost": {
+    "die": {
       "sound": "explosion",
       "shake": 10
     },
+    "gameover": {
+      "sound": "explosion",
+      "shake": 14
+    },
     "win": {
       "sound": "powerup",
       "shake": 4,

package/templates/breakout/scripts/ball.ts

@@ -12,7 +12,7 @@ interface Params {
 /**
  * Rests on the paddle, launches, and keeps a constant speed (bounce: 1 does
  * the reflecting). Falling past the bottom costs a life: the paddle "dies"
- * and the ball goes back onto it.
+ * (a die event, or game over on the last ball) and the ball goes back onto it.
  */
 export default {
   start({ self, world, params }) {
@@ -39,7 +39,6 @@ export default {
     }
 
     if (self.y > world.height + 30) {
-      world.emit("ball-lost");
       world.kill(paddle);
       self.state.stuck = true;
       self.state.launchAt = world.time + launchDelay;

package/templates/breakout/scripts/rules.ts

@@ -60,7 +60,7 @@ export default {
     const left = (self.state.bricksLeft as number) ?? total;
 
     // A red flash from the edges when the ball is lost.
-    const lost = recent("ball-lost", 0.7).at(-1);
+    const lost = recent("die", 0.7).at(-1);
     if (lost) {
       const strength = 1 - (time - lost.time) / 0.7;
       const edge = g.createRadialGradient(view.width / 2, view.height / 2, view.height * 0.3, view.width / 2, view.height / 2, view.width * 0.7);
@@ -92,11 +92,16 @@ export default {
     }
     g.shadowBlur = 0;
 
-    if (world.deaths > 0) {
-      g.font = `700 11px ${FONT}`;
-      g.fillStyle = "rgba(255, 120, 140, 0.8)";
-      g.fillText(`BALLS LOST ${world.deaths}`, view.width - 36, 84);
+    // Balls left, as glowing dots under the meter.
+    for (let i = 0; i < (world.lives ?? 0); i++) {
+      g.fillStyle = "#ffd60a";
+      g.shadowColor = "#ffd60a";
+      g.shadowBlur = 10;
+      g.beginPath();
+      g.arc(view.width - 42 - i * 18, 84, 5, 0, Math.PI * 2);
+      g.fill();
     }
+    g.shadowBlur = 0;
 
     g.textAlign = "center";
     if (time < 2.5 && !world.won) {
@@ -124,5 +129,19 @@ export default {
       g.fillText("PRESS R TO PLAY AGAIN", view.width / 2, view.height / 2 + 84);
       g.globalAlpha = 1;
     }
+
+    if (world.lost) {
+      const over = recent("gameover", 1e9).at(-1);
+      const since = over ? time - over.time : 0;
+      g.fillStyle = `rgba(20, 0, 10, ${Math.min(0.75, since * 1.5)})`;
+      g.fillRect(0, 0, view.width, view.height);
+      g.globalAlpha = Math.min(1, since * 2);
+      neonText(g, "GAME OVER", view.width / 2, view.height / 2 - 6, 64, "#ff2a6d");
+      neonText(g, `${left} BRICK${left === 1 ? "" : "S"} TO GO   ·   SCORE ${world.score}`, view.width / 2, view.height / 2 + 44, 20, "#00f0ff", 700);
+      g.font = `700 12px ${FONT}`;
+      g.fillStyle = "rgba(255, 255, 255, 0.6)";
+      g.fillText("PRESS R TO TRY AGAIN", view.width / 2, view.height / 2 + 84);
+      g.globalAlpha = 1;
+    }
   },
 } satisfies Script;

package/templates/breakout/tests/gameplay.test.json

@@ -19,7 +19,7 @@
     {
       "name": "missing the ball costs a life and puts the ball back on the paddle",
       "duration": "3s",
-      "assert": ["events.ball-lost == 1", "deaths == 1", "ball.state.stuck == true"]
+      "assert": ["events.die == 1", "lives == 2", "ball.state.stuck == true"]
     },
     {
       "name": "the wall can be cleared without losing a life",

package/templates/platformer/CLAUDE.md

@@ -1,14 +1,16 @@
 # {{name}}
 
-A game built with Ludra, a game engine designed for AI agents.
+A platformer built with Ludra, a game engine designed for AI agents: two levels, Night Meadow and Moonlit Cliffs.
 
 ## 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.
+- `scenes/main.scene.json`: level 1 (the entry scene). Its flag's `next` leads to `scenes/level-2.scene.json`. Entities are made of components; `effects` adds particles, sound and shake to game events.
+- `prefabs/`: `coin` and `slime`, reused by both levels. An entity says `"prefab": "slime"` and lists only what differs.
 - `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
+- `scripts/`: `backdrop.ts` (the night sky and parallax hills), `lantern.ts` (lights a reached checkpoint), `hud.ts` (hearts, points, title card, end screens). Run `npx @ludra/cli components script` for the API.
+- `shaders/glow.frag`: the finishing shader (bloom, grade, vignette).
+- `tests/*.test.json`: gameplay tests, run headlessly. Tests for level 2 say `"scene": "scenes/level-2.scene.json"`.
 
 ## Loop
 
@@ -16,9 +18,10 @@ A game built with Ludra, a game engine designed for AI agents.
 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. 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.
+5. Run `npx @ludra/cli review` and fix every issue it lists: it catches what makes a game feel unfinished (untested mechanics, silent events, the default HUD, flat looks).
+6. 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.
+Never call a change done until `ludra check`, `ludra test` and `ludra review` are all clean.
 
 ## Rules of thumb
 
@@ -27,7 +30,8 @@ Never call a change done until `ludra check` and `ludra test` both pass.
 - Collectibles, hazards and goals need `"sensor": true` on their body.
 - Moving platforms and enemies are kinematic bodies with a `patrol`. Players standing on a moving platform are carried.
 - 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`.
+- The game has 3 lives (`world.lives`); the lantern is a `checkpoint`, placed where the player already stands before a hard part.
+- A level is done when a test proves `won == true` with `deaths == 0`. Add a level: copy a scene, point the last flag's `next` at it, and give it its own tests.
 - For more than sprites (lighting, glow, your own HUD, fonts, shaders), scripts can have `draw` and `drawUI` hooks with the real Canvas 2D context, and the scene can set `"fonts"` and `"postfx"`. See `npx @ludra/cli components script`.
 - 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/assets/lantern.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="64" viewBox="0 0 24 64">
+  <!-- A checkpoint: a wooden post with an unlit lantern hanging from it. lantern.ts lights it. -->
+  <rect x="10" y="6" width="4" height="58" rx="1.5" fill="#6b4f3a"/>
+  <rect x="10" y="6" width="2" height="58" fill="#80624a"/>
+  <rect x="4" y="6" width="16" height="3" rx="1.5" fill="#5c4332"/>
+  <path d="M6 9 v4" stroke="#cfd8ff" stroke-width="1"/>
+  <rect x="2" y="13" width="8" height="12" rx="2" fill="#2a3150" stroke="#cfd8ff" stroke-width="1.2"/>
+  <rect x="4" y="11" width="4" height="2" rx="1" fill="#cfd8ff"/>
+</svg>

package/templates/platformer/package.json

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

package/templates/platformer/prefabs/coin.prefab.json

@@ -0,0 +1,8 @@
+{
+  "description": "A spinning gold coin worth 1 point. Place it with just a transform.",
+  "components": {
+    "body": { "type": "static", "width": 20, "height": 20, "sensor": true },
+    "sprite": { "shape": "circle", "color": "#ffd166", "image": "assets/coin.svg", "frameWidth": 20, "idle": "0-3", "layer": 1 },
+    "collectible": { "score": 1 }
+  }
+}

package/templates/platformer/prefabs/slime.prefab.json

@@ -0,0 +1,9 @@
+{
+  "description": "A purple slime that walks back and forth; stomp it for a point. Override patrol to change its range and pace.",
+  "components": {
+    "body": { "type": "kinematic", "width": 32, "height": 26, "sensor": true },
+    "sprite": { "color": "#c77dff", "image": "assets/slime.svg", "frameWidth": 32, "idle": "0", "run": "0-1", "fps": 4, "layer": 2 },
+    "patrol": { "axis": "x", "distance": 200, "speed": 70 },
+    "hazard": { "stompable": true, "score": 1 }
+  }
+}