@ludra/cli 0.5.0 → 0.8.0

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. */
@@ -19,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
@@ -42,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 }));
             }
@@ -94,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.5.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": {
@@ -31,10 +31,11 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "blocks"
   ],
   "dependencies": {
-    "@ludra/core": "0.5.0"
+    "@ludra/core": "0.8.0"
   },
   "keywords": [
     "game-engine",

package/templates/breakout/CLAUDE.md

@@ -0,0 +1,43 @@
+# {{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 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`, `ludra test` and `ludra review` are all clean.
+
+## 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.8.0"
+  }
+}