@ludra/cli 0.5.0 → 0.8.0

package/blocks/turret/block.json

@@ -0,0 +1,59 @@
+{
+  "name": "turret",
+  "description": "A turret that fires deadly bullets at a steady rhythm. Bullets fly through walls and vanish after params.range px.",
+  "tags": [
+    "platformer",
+    "enemy",
+    "script"
+  ],
+  "usage": "--at x,y sets it on the surface whose top is y. params.direction is -1 (fire left) or 1 (right); params.interval is seconds between shots. Bullets fly at the turret's height, so a normal jump clears them.",
+  "entities": [
+    {
+      "id": "{id}",
+      "components": {
+        "transform": {
+          "dx": 0,
+          "dy": -12
+        },
+        "body": {
+          "type": "static",
+          "width": 32,
+          "height": 24
+        },
+        "sprite": {
+          "color": "#8fa3d9",
+          "image": "assets/turret.svg",
+          "layer": 2
+        },
+        "script": {
+          "src": "scripts/turret.ts",
+          "params": {
+            "interval": 1.5,
+            "speed": 240,
+            "direction": -1,
+            "range": 420
+          }
+        }
+      }
+    }
+  ],
+  "files": [
+    "scripts/turret.ts",
+    "scripts/bullet.ts",
+    "assets/turret.svg",
+    "assets/bullet.svg"
+  ],
+  "effects": {
+    "turret-shot": {
+      "sound": "blip",
+      "particles": {
+        "count": 6,
+        "color": "#ffd166",
+        "speed": 90,
+        "life": 0.2,
+        "size": 2,
+        "gravity": 0
+      }
+    }
+  }
+}

package/blocks/turret/demo.json

@@ -0,0 +1,35 @@
+{
+  "at": [
+    700,
+    500
+  ],
+  "tests": [
+    {
+      "name": "fires on a steady rhythm",
+      "duration": "4s",
+      "assert": [
+        "turret.state.shots >= 2",
+        "events.turret-shot >= 2"
+      ]
+    },
+    {
+      "name": "its bullets kill a player in their path",
+      "playerAt": [
+        400,
+        482
+      ],
+      "duration": "3s",
+      "assert": [
+        "deaths >= 1"
+      ]
+    },
+    {
+      "name": "bullets vanish after their range, so a far-away player is safe",
+      "duration": "4s",
+      "assert": [
+        "deaths == 0",
+        "turret-1.exists == false"
+      ]
+    }
+  ]
+}

package/blocks/turret/scripts/bullet.ts

@@ -0,0 +1,11 @@
+import type { Script } from "@ludra/core";
+
+/** Flies until it has gone params.range px, then disappears. */
+export default {
+  start({ self }) {
+    self.state.startX = self.x;
+  },
+  update({ self, world, params }) {
+    if (Math.abs(self.x - (self.state.startX as number)) > (params.range as number)) world.destroy(self);
+  },
+} satisfies Script;

package/blocks/turret/scripts/turret.ts

@@ -0,0 +1,36 @@
+import type { Script } from "@ludra/core";
+
+interface Params {
+  /** Seconds between shots. */
+  interval: number;
+  /** Bullet speed in px/s. */
+  speed: number;
+  /** -1 fires left, 1 fires right. */
+  direction: number;
+  /** Bullets vanish after flying this many px. */
+  range: number;
+}
+
+/** Fires a deadly bullet every params.interval seconds. */
+export default {
+  start({ self, params }) {
+    self.state.shots = 0;
+    self.state.next = (params.interval as number) / 2;
+  },
+  update({ self, world, params }) {
+    const { interval, speed, direction, range } = params as unknown as Params;
+    if (world.time < (self.state.next as number)) return;
+    world.spawn({
+      components: {
+        transform: { x: self.x + direction * (self.width / 2 + 8), y: self.y - 2 },
+        body: { type: "kinematic", width: 12, height: 6, sensor: true, vx: direction * speed },
+        sprite: { color: "#ff5d73", image: "assets/bullet.svg", layer: 2 },
+        hazard: {},
+        script: { src: "scripts/bullet.ts", params: { range } },
+      },
+    });
+    self.state.shots = (self.state.shots as number) + 1;
+    self.state.next = world.time + interval;
+    world.emit("turret-shot");
+  },
+} satisfies Script;

package/dist/blocks.d.ts

@@ -0,0 +1,65 @@
+import type { EffectDef, EntityDef, SceneDef } from "@ludra/core";
+/** Same relative location from `src/` and `dist/`. */
+export declare const BLOCKS_DIR: string;
+/**
+ * A reusable piece of gameplay: entities, the scripts and art they use, and
+ * effects. Entity transforms are offsets (`dx`, `dy`) from the anchor given
+ * to `ludra add --at`. Every string may use `{id}`, replaced by the id prefix.
+ */
+export interface BlockManifest {
+    name: string;
+    description: string;
+    tags: string[];
+    /** What `--at` means for this block and how to tune it. */
+    usage: string;
+    /** False for blocks that are not placed in the world (a time limit). */
+    positioned?: boolean;
+    entities: {
+        id: string;
+        components: Record<string, Record<string, unknown>>;
+    }[];
+    /** Files copied into the project at the same relative path. */
+    files: string[];
+    effects?: Record<string, EffectDef>;
+}
+export interface Block extends BlockManifest {
+    dir: string;
+}
+export declare function listBlocks(): Block[];
+export declare function loadBlock(name: string): Block;
+export interface Placement {
+    entities: EntityDef[];
+    effects: Record<string, EffectDef>;
+    prefix: string;
+}
+/** Turns a block into concrete entities at `at`, with ids that don't clash with `scene`. */
+export declare function placeBlock(block: Block, scene: SceneDef, at: {
+    x: number;
+    y: number;
+}, idBase?: string): Placement;
+export interface AddResult {
+    block: string;
+    prefix: string;
+    entities: {
+        id: string;
+        x: number;
+        y: number;
+    }[];
+    files: {
+        path: string;
+        status: "added" | "unchanged" | "kept yours" | "replaced";
+    }[];
+    effects: string[];
+}
+/**
+ * Adds a block to a project: copies its files (never overwriting a file the
+ * user changed unless `force`), appends its entities to the scene and merges
+ * effects the scene doesn't define yet.
+ */
+export declare function addBlock(projectDir: string, scenePath: string, block: Block, at: {
+    x: number;
+    y: number;
+}, options?: {
+    id?: string;
+    force?: boolean;
+}): AddResult;

package/dist/blocks.js

@@ -0,0 +1,95 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./project.js";
+/** Same relative location from `src/` and `dist/`. */
+export const BLOCKS_DIR = fileURLToPath(new URL("../blocks/", import.meta.url));
+export function listBlocks() {
+    if (!existsSync(BLOCKS_DIR))
+        return [];
+    return readdirSync(BLOCKS_DIR, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(BLOCKS_DIR, entry.name, "block.json")))
+        .map((entry) => loadBlock(entry.name))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function loadBlock(name) {
+    const dir = join(BLOCKS_DIR, name);
+    const file = join(dir, "block.json");
+    if (!existsSync(file)) {
+        const names = existsSync(BLOCKS_DIR) ? readdirSync(BLOCKS_DIR).join(", ") : "none";
+        throw new CliError(`Unknown block "${name}". Blocks: ${names}. Run \`ludra blocks\` to see what each one does.`);
+    }
+    return { ...JSON.parse(readFileSync(file, "utf8")), dir };
+}
+/** Replaces `{id}` in every string, recursively. */
+function substitute(value, id) {
+    if (typeof value === "string")
+        return value.replaceAll("{id}", id);
+    if (Array.isArray(value))
+        return value.map((v) => substitute(v, id));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, substitute(v, id)]));
+    }
+    return value;
+}
+/** Picks `base`, or `base-2`, `base-3`… so none of the block's entity ids clash with the scene. */
+function uniquePrefix(block, base, taken) {
+    for (let n = 1;; n++) {
+        const prefix = n === 1 ? base : `${base}-${n}`;
+        const ids = block.entities.map((e) => e.id.replaceAll("{id}", prefix));
+        if (ids.every((id) => !taken.has(id)))
+            return prefix;
+    }
+}
+/** Turns a block into concrete entities at `at`, with ids that don't clash with `scene`. */
+export function placeBlock(block, scene, at, idBase) {
+    const taken = new Set(scene.entities.map((e) => e.id));
+    const prefix = uniquePrefix(block, idBase ?? block.name, taken);
+    const entities = block.entities.map((template) => {
+        const def = substitute(structuredClone(template), prefix);
+        const offset = def.components.transform ?? {};
+        def.components.transform = { x: at.x + (offset.dx ?? 0), y: at.y + (offset.dy ?? 0) };
+        return def;
+    });
+    return { entities, effects: substitute(block.effects ?? {}, prefix), prefix };
+}
+/**
+ * Adds a block to a project: copies its files (never overwriting a file the
+ * user changed unless `force`), appends its entities to the scene and merges
+ * effects the scene doesn't define yet.
+ */
+export function addBlock(projectDir, scenePath, block, at, options = {}) {
+    const scene = JSON.parse(readFileSync(scenePath, "utf8"));
+    const placement = placeBlock(block, scene, at, options.id);
+    const files = block.files.map((path) => {
+        const source = readFileSync(join(block.dir, path));
+        const target = join(projectDir, path);
+        if (existsSync(target)) {
+            if (readFileSync(target).equals(source))
+                return { path, status: "unchanged" };
+            if (!options.force)
+                return { path, status: "kept yours" };
+        }
+        const existed = existsSync(target);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, source);
+        return { path, status: existed ? "replaced" : "added" };
+    });
+    scene.entities.push(...placement.entities);
+    const effects = [];
+    for (const [event, effect] of Object.entries(placement.effects)) {
+        scene.effects ??= {};
+        if (scene.effects[event])
+            continue;
+        scene.effects[event] = effect;
+        effects.push(event);
+    }
+    writeFileSync(scenePath, `${JSON.stringify(scene, null, 2)}\n`);
+    return {
+        block: block.name,
+        prefix: placement.prefix,
+        entities: placement.entities.map((e) => ({ id: e.id, x: e.components.transform.x, y: e.components.transform.y })),
+        files,
+        effects,
+    };
+}

package/dist/commands/blocks.d.ts

@@ -0,0 +1,12 @@
+/** `ludra blocks`: the catalog. */
+export declare function blocks(options: {
+    json?: boolean;
+}): number;
+export interface AddOptions {
+    at?: string;
+    id?: string;
+    force?: boolean;
+    json?: boolean;
+}
+/** `ludra add <block> [folder] --at x,y`. */
+export declare function add(name: string | undefined, dir: string, options: AddOptions): number;

package/dist/commands/blocks.js

@@ -0,0 +1,49 @@
+import { relative } from "node:path";
+import { addBlock, listBlocks, loadBlock } from "../blocks.js";
+import { pad, paint } from "../format.js";
+import { CliError, loadProject } from "../project.js";
+/** `ludra blocks`: the catalog. */
+export function blocks(options) {
+    const all = listBlocks();
+    if (options.json) {
+        console.log(JSON.stringify(all.map(({ name, description, tags, usage, positioned }) => ({ name, description, tags, usage, positioned: positioned ?? true })), null, 2));
+        return 0;
+    }
+    const width = Math.max(...all.map((b) => b.name.length)) + 2;
+    for (const block of all) {
+        console.log(`${paint("bold", pad(block.name, width))}${block.description} ${paint("dim", `[${block.tags.join(", ")}]`)}`);
+    }
+    console.log(paint("dim", `\nAdd one with: ludra add <block> --at x,y   (y = top of the surface it sits on; 500 in the templates)`));
+    return 0;
+}
+/** `ludra add <block> [folder] --at x,y`. */
+export function add(name, dir, options) {
+    if (!name)
+        throw new CliError("Usage: ludra add <block> [folder] --at x,y [--id name]. Run `ludra blocks` for the catalog.");
+    const block = loadBlock(name);
+    const project = loadProject(dir);
+    let at = { x: 0, y: 0 };
+    if (block.positioned !== false) {
+        const match = /^\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*$/.exec(options.at ?? "");
+        if (!match)
+            throw new CliError(`ludra add ${name} needs --at x,y. ${block.usage}`);
+        at = { x: Number(match[1]), y: Number(match[2]) };
+    }
+    const result = addBlock(project.dir, project.entryPath, block, at, { id: options.id, force: options.force });
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return 0;
+    }
+    console.log(paint("green", `✓ Added "${block.name}" to ${project.entryLabel}`));
+    for (const e of result.entities)
+        console.log(`  entity  ${pad(e.id, 22)} at (${e.x}, ${e.y})`);
+    for (const f of result.files) {
+        const note = f.status === "kept yours" ? paint("yellow", "kept yours (differs from the block; use --force to replace)") : paint("dim", f.status);
+        console.log(`  file    ${pad(f.path, 22)} ${note}`);
+    }
+    if (result.effects.length > 0)
+        console.log(`  effects ${result.effects.join(", ")}`);
+    console.log(`\n${paint("dim", block.usage)}`);
+    console.log(paint("dim", `Next: ludra check ${relative(process.cwd(), project.dir) || "."}, then play and test it.`));
+    return 0;
+}

package/dist/commands/check.d.ts

@@ -1,3 +1,4 @@
+/** Validates every scene in the project (entry scene first). */
 export declare function check(dir: string, options: {
     json?: boolean;
 }): Promise<number>;

package/dist/commands/check.js

@@ -1,22 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { checkDrawHooks } from "@ludra/core";
 import { formatDiagnostics, paint } from "../format.js";
-import { loadGame, loadProject } from "../project.js";
+import { isInside, listScenes, loadGame, loadProject, scriptPaths } from "../project.js";
+/** Validates every scene in the project (entry scene first). */
 export async function check(dir, options) {
     const project = loadProject(dir);
-    const { game, diagnostics } = await loadGame(project);
-    const scene = game?.scene;
-    const errors = diagnostics.filter((d) => d.severity === "error").length;
-    const warnings = diagnostics.length - errors;
+    const results = [];
+    const scripts = new Set();
+    for (const scene of listScenes(project)) {
+        const { game, diagnostics, label } = await loadGame(project, scene);
+        // Draw hooks only run in the browser, so paint once here to catch their errors early.
+        if (game) {
+            diagnostics.push(...checkDrawHooks(game.scene, game.scripts));
+            for (const path of scriptPaths(project, game.scene))
+                scripts.add(path);
+        }
+        const errors = diagnostics.filter((d) => d.severity === "error").length;
+        results.push({ file: label, entities: game?.scene.entities.length ?? 0, errors, warnings: diagnostics.length - errors, diagnostics });
+    }
+    // world.goto("...") in scripts must point at real scenes.
+    const gotoProblems = missingGotoScenes(project, [...scripts]);
+    if (gotoProblems.length > 0) {
+        results.push({ file: "scripts", entities: 0, errors: gotoProblems.length, warnings: 0, diagnostics: gotoProblems });
+    }
+    const errors = results.reduce((n, r) => n + r.errors, 0);
+    const warnings = results.reduce((n, r) => n + r.warnings, 0);
     if (options.json) {
-        console.log(JSON.stringify({ ok: errors === 0, file: project.entryLabel, errors, warnings, diagnostics }, null, 2));
+        const diagnostics = results.flatMap((r) => r.diagnostics.map((d) => ({ file: r.file, ...d })));
+        console.log(JSON.stringify({ ok: errors === 0, file: project.entryLabel, errors, warnings, diagnostics, scenes: results }, null, 2));
         return errors > 0 ? 1 : 0;
     }
-    if (diagnostics.length > 0)
-        console.log(`${formatDiagnostics(diagnostics, project.entryLabel)}\n`);
-    if (errors > 0) {
-        console.log(paint("red", `✗ ${project.entryLabel}: ${errors} error(s), ${warnings} warning(s)`));
-        return 1;
+    for (const r of results) {
+        if (r.diagnostics.length > 0)
+            console.log(`${formatDiagnostics(r.diagnostics, r.file)}\n`);
+        if (r.errors > 0)
+            console.log(paint("red", `✗ ${r.file}: ${r.errors} error(s), ${r.warnings} warning(s)`));
+        else
+            console.log(paint("green", `✓ ${r.file}: ${r.entities} entities, ${r.warnings === 0 ? "no problems" : `${r.warnings} warning(s)`}`));
+    }
+    return errors > 0 ? 1 : 0;
+}
+/** Scene paths written literally in world.goto("...") calls that don't exist. */
+function missingGotoScenes(project, scripts) {
+    const problems = [];
+    for (const src of scripts) {
+        const file = resolve(project.dir, src);
+        if (!existsSync(file))
+            continue;
+        for (const match of readFileSync(file, "utf8").matchAll(/\bgoto\(\s*["'`]([^"'`$]+)["'`]\s*\)/g)) {
+            const target = resolve(project.dir, match[1]);
+            if (isInside(project.dir, target) && existsSync(target))
+                continue;
+            problems.push({
+                severity: "error",
+                code: "E_SCENE_MISSING",
+                path: `${src} → goto("${match[1]}")`,
+                message: `${src} goes to "${match[1]}", which does not exist.`,
+                fix: `Scenes: ${listScenes(project).join(", ")}. Paths are relative to the folder with ludra.json.`,
+            });
+        }
     }
-    const count = scene?.entities.length ?? 0;
-    console.log(paint("green", `✓ ${project.entryLabel}: ${count} entities, ${warnings === 0 ? "no problems" : `${warnings} warning(s)`}`));
-    return 0;
+    return problems;
 }

package/dist/commands/dev.js

@@ -15,7 +15,7 @@ export function dev(dir, options) {
     server.listen(port, "127.0.0.1", () => {
         console.log(paint("green", `▶ ${project.config.name} is running at http://localhost:${port}`));
         console.log(paint("dim", `  Arrows/WASD to move, Space/Z to jump, M to mute, R to restart.`));
-        console.log(paint("dim", `  Editing ${project.entryLabel} or its images and sounds reloads the page. Ctrl+C to stop.`));
+        console.log(paint("dim", `  Editing a scene, prefab, script or asset reloads the page. Ctrl+C to stop.`));
     });
     return 0;
 }
@@ -44,7 +44,12 @@ import { startGame } from "${browserModule}";
 const data = await (await fetch("/__ludra/scene")).json();
 if (data.ok) {
   const scriptPaths = await (await fetch("/__ludra/scripts")).json();
-  await startGame(document.getElementById("game"), data.scene, { assetBase: "${PROJECT_PREFIX}", scriptBase: "${SCRIPT_PREFIX}", scriptPaths });
+  const loadScene = async (path) => {
+    const next = await (await fetch("/__ludra/scene?path=" + encodeURIComponent(path))).json();
+    if (!next.ok) throw new Error(next.diagnostics.map((d) => d.code + " at " + d.path + ": " + d.message).join(" "));
+    return next.scene;
+  };
+  await startGame(document.getElementById("game"), data.scene, { assetBase: "${PROJECT_PREFIX}", scriptBase: "${SCRIPT_PREFIX}", scriptPaths, loadScene });
 } else {
   document.getElementById("game").hidden = true;
   const errors = document.getElementById("errors");

package/dist/commands/new.js

@@ -7,7 +7,7 @@ import { CliError } from "../project.js";
 const TEMPLATES_DIR = fileURLToPath(new URL("../../templates/", import.meta.url));
 export function create(dir, options) {
     if (!dir)
-        throw new CliError("Usage: ludra new <folder> [--template platformer]");
+        throw new CliError("Usage: ludra new <folder> [--template platformer|topdown|breakout]");
     const template = options.template ?? "platformer";
     const source = join(TEMPLATES_DIR, template);
     if (!existsSync(source)) {

package/dist/commands/play.d.ts

@@ -1,4 +1,5 @@
 export interface PlayOptions {
+    scene?: string;
     inputs?: string;
     duration?: string;
     watch?: string;

package/dist/commands/play.js

@@ -7,14 +7,14 @@ import { CliError, loadProject, requireGame } from "../project.js";
 const MAX_EVENTS_SHOWN = 40;
 export async function play(dir, options) {
     const project = loadProject(dir);
-    const { scene, scripts } = await requireGame(project);
+    const { scene, scripts } = await requireGame(project, options.scene);
     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 = 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);
+        : world.entities.filter((e) => e.platformer || e.topdown).map((e) => e.id);
     for (const id of watch) {
         if (!world.get(id)) {
             throw new CliError(`--watch: no entity "${id}". Entities: ${world.entities.map((e) => e.id).join(", ")}.`);
@@ -71,7 +71,7 @@ async function takeScreenshots(project, options, lastFrame) {
     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 });
+    const captured = await captureScreenshots(project, { scene: options.scene, 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"));
@@ -109,9 +109,17 @@ function describeEvent(event) {
         case "stomp":
             return `${event.entity} stomped ${event.enemy}${event.score ? ` (+${event.score})` : ""}`;
         case "die":
-            return `${event.entity} ${event.cause === "fall" ? "fell out of the world" : `hit ${event.cause}`}, respawned`;
+            return `${event.entity} ${event.cause === "fall" ? "fell out of the world" : `hit ${event.cause}`}`;
         case "win":
             return event.entity === event.goal ? `${event.entity} (script) completed the level` : `${event.entity} reached ${event.goal}`;
+        case "bounce":
+            return `${event.entity} bounced off ${event.other}`;
+        case "checkpoint":
+            return `${event.entity} reached ${event.checkpoint} (respawns there now)`;
+        case "gameover":
+            return event.cause === "script" ? `game over (from ${event.entity}'s script)` : `${event.entity} is out of lives: game over`;
+        case "goto":
+            return `${event.entity} → ${event.scene}`;
         case "custom":
             return `from ${event.entity}'s script${event.data === undefined ? "" : ` ${JSON.stringify(event.data)}`}`;
         default:

package/dist/commands/review.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `ludra review`: the signs of a slop game, found automatically. Where `check`
+ * asks "is it valid?" and `test` asks "does it work?", review asks "is it
+ * finished?": proven, felt, styled and named. Issues should be fixed before a
+ * game is called done; ideas are worth considering.
+ */
+type Area = "proof" | "feel" | "looks" | "identity";
+type Level = "issue" | "idea";
+export interface Finding {
+    level: Level;
+    area: Area;
+    code: string;
+    /** The scene or file it is about. */
+    where: string;
+    message: string;
+    fix: string;
+}
+export declare function review(dir: string, options: {
+    json?: boolean;
+    strict?: boolean;
+}): Promise<number>;
+export {};