@ludra/cli 0.4.0 → 0.7.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,3 @@
 export declare function check(dir: string, options: {
     json?: boolean;
-}): number;
+}): Promise<number>;

package/dist/commands/check.js

@@ -1,8 +1,13 @@
+import { checkDrawHooks } from "@ludra/core";
 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;
+    // 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));
     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/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.js

@@ -1,33 +1,33 @@
-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);
+        : 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(", ")}.`);
         }
     }
     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,26 @@ 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 "bounce":
+            return `${event.entity} bounced off ${event.other}`;
+        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
@@ -59,6 +59,9 @@ export async function captureScreenshots(project, request) {
             "--no-default-browser-check",
             "--mute-audio",
             "--hide-scrollbars",
+            // Software WebGL, so postfx shaders render without a GPU.
+            "--use-angle=swiftshader",
+            "--enable-unsafe-swiftshader",
             `--window-size=${width},${height}`,
             "about:blank",
         ], { stdio: ["ignore", "ignore", "pipe"] });
@@ -78,6 +81,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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
+import { add, blocks } from "./commands/blocks.js";
 import { check } from "./commands/check.js";
 import { components } from "./commands/components.js";
 import { dev } from "./commands/dev.js";
@@ -8,15 +9,23 @@ 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
-  ludra new <folder> [--template platformer]   Create a game project
+  ludra new <folder> [--template <name>]       Create a game project (templates: platformer, topdown, breakout)
   ludra check [folder] [--json]                Validate the scene; every problem comes with a fix
   ludra play [folder] [options]                Simulate the game headlessly
       --inputs "right:1s, jump:0.4s"           Scripted input. Actions: left right up down jump action wait
       --duration 3s                            Run length (default: inputs + 1s)
-      --watch player,enemy                     Entities in the timeline (default: platformer entities)
+      --watch player,enemy                     Entities in the timeline (default: the players)
       --every 0.25s                            Timeline sampling interval
       --ascii                                  Print the final frame as a text map
       --columns 120                            Width of the text map (default: 80)
@@ -25,6 +34,10 @@ Usage
       --json                                   Machine-readable output
   ludra test [folder] [--json]                 Run tests/*.test.json
   ludra components [name] [--json]             Reference for every component and field
+  ludra blocks [--json]                        Catalog of ready-made gameplay blocks
+  ludra add <block> [folder] --at x,y          Add a block: entities, scripts, art and effects
+      --id name                                Id prefix for its entities (default: the block name)
+      --force                                  Replace files you changed that the block also ships
   ludra dev [folder] [--port 5173]             Play the game in the browser with live reload
 
 Folder defaults to the current directory.`;
@@ -44,10 +57,13 @@ async function main(argv) {
             json: { type: "boolean" },
             template: { type: "string" },
             port: { type: "string" },
+            at: { type: "string" },
+            id: { type: "string" },
+            force: { type: "boolean" },
             help: { type: "boolean", short: "h" },
         },
     });
-    const [command, target] = positionals;
+    const [command, target, extra] = positionals;
     if (values.help || !command || command === "help") {
         console.log(HELP);
         return 0;
@@ -65,6 +81,10 @@ async function main(argv) {
             return components(target, values);
         case "dev":
             return dev(target ?? ".", values);
+        case "blocks":
+            return blocks(values);
+        case "add":
+            return add(target, extra ?? ".", values);
         default:
             throw new CliError(`Unknown command "${command}".\n\n${HELP}`);
     }