@ludra/cli 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ludra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @ludra/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The game engine built for AI agents.** This package provides the `ludra` command.
+
+Games are plain JSON, every error comes with a fix, and agents play-test their own games headlessly before a human ever touches them.
+
+```bash
+npx @ludra/cli new my-game
+cd my-game
+npx @ludra/cli check                                        # validate; every problem has a fix
+npx @ludra/cli play --inputs "right:1s, jump:0.4s" --ascii  # simulate and see the frame as text
+npx @ludra/cli test                                         # run tests/*.test.json
+npx @ludra/cli dev                                          # play it in the browser
+```
+
+Or install it once and use the short command:
+
+```bash
+npm install -g @ludra/cli
+ludra new my-game
+```
+
+| Command | What it does |
+| --- | --- |
+| `ludra new <folder>` | Create a game from the platformer template (art, effects and tests included) |
+| `ludra check [folder]` | Validate the scene and its assets |
+| `ludra play [folder]` | Deterministic headless run: timeline, events, ASCII map |
+| `ludra test [folder]` | Scripted inputs plus assertions such as `won == true` or `deaths == 0` |
+| `ludra components [name]` | Reference for every component, field and effect |
+| `ludra dev [folder]` | Browser runtime with keyboard controls, sound and live reload |
+
+Every command accepts `--json`. Requires Node.js 22.18 or newer.
+
+The engine runtime is published separately as [`@ludra/core`](https://www.npmjs.com/package/@ludra/core).
+
+Documentation, the Claude Code plugin and examples: **https://github.com/ersingvn/ludra**
+
+MIT licensed.

package/dist/commands/check.d.ts

@@ -0,0 +1,3 @@
+export declare function check(dir: string, options: {
+    json?: boolean;
+}): number;

package/dist/commands/check.js

@@ -0,0 +1,21 @@
+import { formatDiagnostics, paint } from "../format.js";
+import { loadProject, readScene } from "../project.js";
+export function check(dir, options) {
+    const project = loadProject(dir);
+    const { scene, diagnostics } = readScene(project);
+    const errors = diagnostics.filter((d) => d.severity === "error").length;
+    const warnings = diagnostics.length - errors;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: errors === 0, file: project.entryLabel, errors, warnings, diagnostics }, 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;
+    }
+    const count = scene?.entities.length ?? 0;
+    console.log(paint("green", `✓ ${project.entryLabel}: ${count} entities, ${warnings === 0 ? "no problems" : `${warnings} warning(s)`}`));
+    return 0;
+}

package/dist/commands/components.d.ts

@@ -0,0 +1,3 @@
+export declare function components(name: string | undefined, options: {
+    json?: boolean;
+}): number;

package/dist/commands/components.js

@@ -0,0 +1,55 @@
+import { COMPONENT_NAMES, COMPONENTS, EFFECT_FIELDS, EFFECTS_DESCRIPTION, EVENT_TYPES, isComponentName, PARTICLE_FIELDS, SOUND_PRESETS, } from "@ludra/core";
+import { pad, paint } from "../format.js";
+import { CliError } from "../project.js";
+const EFFECTS_EXAMPLE = `"effects": {
+    "collect": { "sound": "coin", "particles": { "count": 12, "color": "#ffd166", "speed": 140 } },
+    "die": { "sound": "explosion", "shake": 8, "particles": { "count": 24, "color": "#ff5d73" } }
+  }`;
+export function components(name, options) {
+    if (name !== undefined && name !== "effects" && !isComponentName(name)) {
+        throw new CliError(`Unknown component "${name}". Components: ${COMPONENT_NAMES.join(", ")}, plus "effects" for scene effects.`);
+    }
+    const names = name === undefined ? COMPONENT_NAMES : isComponentName(name) ? [name] : [];
+    const showEffects = name === undefined || name === "effects";
+    if (options.json) {
+        const effects = { description: EFFECTS_DESCRIPTION, events: EVENT_TYPES, soundPresets: SOUND_PRESETS, fields: EFFECT_FIELDS, particles: PARTICLE_FIELDS };
+        const output = Object.fromEntries(names.map((n) => [n, COMPONENTS[n]]));
+        console.log(JSON.stringify(showEffects ? { ...output, effects } : output, null, 2));
+        return 0;
+    }
+    for (const n of names) {
+        const spec = COMPONENTS[n];
+        console.log(`${paint("bold", n)} — ${spec.description}`);
+        if (spec.requires?.length)
+            console.log(paint("dim", `  requires: ${spec.requires.join(", ")}`));
+        printFields(spec.fields);
+        console.log();
+    }
+    if (showEffects) {
+        console.log(`${paint("bold", "effects")} (scene level, not a component) — ${EFFECTS_DESCRIPTION}`);
+        console.log(paint("dim", `  events: ${EVENT_TYPES.join(", ")}`));
+        console.log(paint("dim", `  sound presets: ${SOUND_PRESETS.join(", ")}`));
+        printFields(EFFECT_FIELDS);
+        console.log(`  ${pad("particles", 13)} ${pad("object", 34)} ${pad("optional", 18)} ${paint("dim", "A burst at the event position, with these fields:")}`);
+        printFields(PARTICLE_FIELDS, "    ");
+        console.log(paint("dim", `  example:\n  ${EFFECTS_EXAMPLE}`));
+        console.log();
+    }
+    return 0;
+}
+function printFields(fields, indent = "  ") {
+    for (const [field, fieldSpec] of Object.entries(fields)) {
+        // Pad before coloring so escape codes don't break the alignment.
+        const required = fieldSpec.default === undefined ? paint("yellow", pad("required", 18)) : pad(`default ${JSON.stringify(fieldSpec.default)}`, 18);
+        console.log(`${indent}${pad(field, 15 - indent.length)} ${pad(typeLabel(fieldSpec), 34)} ${required} ${paint("dim", fieldSpec.description)}`);
+    }
+}
+function typeLabel(spec) {
+    if (spec.type === "enum")
+        return spec.values.map((v) => `"${v}"`).join(" | ");
+    if (spec.type === "number" && spec.min !== undefined)
+        return `number ≥ ${spec.min}`;
+    if (spec.type === "frames")
+        return 'frames ("0", "1-4", "0,2")';
+    return spec.type;
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Serves the game with the engine's browser runtime and reloads the page when
+ * the scene file changes. No bundler: when the engine runs from source, its
+ * TypeScript files are type-stripped on the fly.
+ */
+export declare function dev(dir: string, options: {
+    port?: string;
+}): number;

package/dist/commands/dev.js

@@ -0,0 +1,146 @@
+import { existsSync, 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 { paint } from "../format.js";
+import { CliError, isInside, loadProject, readScene } from "../project.js";
+/**
+ * Serves the game with the engine's browser runtime and reloads the page when
+ * the scene file changes. No bundler: when the engine runs from source, its
+ * TypeScript files are type-stripped on the fly.
+ */
+export function dev(dir, options) {
+    const project = loadProject(dir);
+    const port = Number(options.port ?? 5173);
+    if (!Number.isInteger(port) || port <= 0)
+        throw new CliError(`Invalid --port "${options.port}".`);
+    const coreEntry = fileURLToPath(import.meta.resolve("@ludra/core/browser"));
+    const coreDir = dirname(coreEntry);
+    const browserModule = `/__ludra/core/${relative(coreDir, coreEntry).replaceAll(sep, "/")}`;
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        try {
+            if (url.pathname === "/") {
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end(page(project, browserModule));
+            }
+            else if (url.pathname === "/__ludra/scene") {
+                const { scene, diagnostics } = readScene(project);
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ ok: !!scene, scene, diagnostics }));
+            }
+            else if (url.pathname === "/__ludra/version") {
+                res.writeHead(200, { "content-type": "text/plain" });
+                res.end(version(project));
+            }
+            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)));
+                const type = MEDIA_TYPES[extname(file).toLowerCase()];
+                if (!type || !isInside(project.dir, file) || !existsSync(file))
+                    return notFound(res);
+                res.writeHead(200, { "content-type": type, "cache-control": "no-cache" });
+                res.end(readFileSync(file));
+            }
+            else if (url.pathname.startsWith("/__ludra/core/")) {
+                const file = join(coreDir, decodeURIComponent(url.pathname.slice("/__ludra/core/".length)));
+                if (!file.startsWith(coreDir + sep) || !existsSync(file))
+                    return notFound(res);
+                const source = readFileSync(file, "utf8");
+                res.writeHead(200, { "content-type": "text/javascript; charset=utf-8" });
+                res.end(extname(file) === ".ts" ? stripTypeScriptTypes(source) : source);
+            }
+            else {
+                notFound(res);
+            }
+        }
+        catch (err) {
+            res.writeHead(500, { "content-type": "text/plain" });
+            res.end(err.message);
+        }
+    });
+    server.on("error", (err) => {
+        console.error(paint("red", err.code === "EADDRINUSE" ? `Port ${port} is in use. Try --port ${port + 1}.` : err.message));
+        process.exit(1);
+    });
+    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.`));
+    });
+    return 0;
+}
+const PROJECT_PREFIX = "/__ludra/project/";
+const MEDIA_TYPES = {
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".wav": "audio/wav",
+    ".mp3": "audio/mpeg",
+    ".ogg": "audio/ogg",
+};
+/** Changes whenever the scene or any file it references 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)
+        files.push(...collectAssetPaths(scene).map((ref) => resolve(project.dir, ref.path)));
+    return files.map((file) => (existsSync(file) ? statSync(file).mtimeMs : 0)).join(":");
+}
+function notFound(res) {
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end("Not found");
+}
+function page(project, browserModule) {
+    const { width, height } = project.config.window;
+    const title = escapeHtml(project.config.name);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title} · Ludra</title>
+<style>
+  html, body { margin: 0; height: 100%; background: #0b0e14; color: #e6e6e6; font-family: system-ui, sans-serif; }
+  body { display: grid; place-items: center; }
+  canvas { max-width: 100vw; max-height: 100vh; box-shadow: 0 0 0 1px #2a3142; }
+  #errors { max-width: 900px; padding: 24px; white-space: pre-wrap; font: 14px/1.5 ui-monospace, monospace; color: #ff9b9b; }
+</style>
+</head>
+<body>
+<canvas id="game" width="${width}" height="${height}"></canvas>
+<pre id="errors" hidden></pre>
+<script type="module">
+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}" });
+} else {
+  document.getElementById("game").hidden = true;
+  const errors = document.getElementById("errors");
+  errors.hidden = false;
+  errors.textContent = "The scene has errors (run \`ludra check\`):\\n\\n" +
+    data.diagnostics.map((d) => d.severity + " " + d.code + " at " + d.path + "\\n  " + d.message + (d.fix ? "\\n  fix: " + d.fix : "")).join("\\n\\n");
+}
+
+const version = await (await fetch("/__ludra/version")).text();
+setInterval(async () => {
+  try {
+    if ((await (await fetch("/__ludra/version")).text()) !== version) location.reload();
+  } catch {}
+}, 1000);
+</script>
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}

package/dist/commands/new.d.ts

@@ -0,0 +1,3 @@
+export declare function create(dir: string | undefined, options: {
+    template?: string;
+}): number;

package/dist/commands/new.js

@@ -0,0 +1,42 @@
+import { cpSync, existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { paint } from "../format.js";
+import { CliError } from "../project.js";
+/** Same relative location from `src/commands` and `dist/commands`. */
+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]");
+    const template = options.template ?? "platformer";
+    const source = join(TEMPLATES_DIR, template);
+    if (!existsSync(source)) {
+        throw new CliError(`Unknown template "${template}". Templates: ${readdirSync(TEMPLATES_DIR).join(", ")}.`);
+    }
+    const target = resolve(dir);
+    if (existsSync(target) && readdirSync(target).length > 0) {
+        throw new CliError(`${target} already exists and is not empty. Choose a new folder.`);
+    }
+    const name = basename(target);
+    cpSync(source, target, { recursive: true });
+    for (const file of listFiles(target)) {
+        const text = readFileSync(file, "utf8");
+        if (text.includes("{{name}}"))
+            writeFileSync(file, text.replaceAll("{{name}}", name));
+    }
+    const shown = relative(process.cwd(), target) || ".";
+    console.log(paint("green", `✓ Created ${name} from the "${template}" template in ${shown}`));
+    console.log(`
+Next steps:
+  npx @ludra/cli check ${shown}          validate the scene
+  npx @ludra/cli play ${shown} --ascii   simulate it headlessly and see the final frame
+  npx @ludra/cli test ${shown}           run tests/*.test.json
+  npx @ludra/cli dev ${shown}            play it in the browser`);
+    return 0;
+}
+function listFiles(dir) {
+    return readdirSync(dir).flatMap((entry) => {
+        const path = join(dir, entry);
+        return statSync(path).isDirectory() ? listFiles(path) : [path];
+    });
+}

package/dist/commands/play.d.ts

@@ -0,0 +1,10 @@
+export interface PlayOptions {
+    inputs?: string;
+    duration?: string;
+    watch?: string;
+    every?: string;
+    ascii?: boolean;
+    columns?: string;
+    json?: boolean;
+}
+export declare function play(dir: string, options: PlayOptions): number;

package/dist/commands/play.js

@@ -0,0 +1,92 @@
+import { defaultDuration, InputScript, parseDuration, renderAscii, secondsToFrames, simulate, World, } from "@ludra/core";
+import { fixed, pad, padStart, paint } from "../format.js";
+import { CliError, loadProject, requireScene } from "../project.js";
+const MAX_EVENTS_SHOWN = 40;
+export function play(dir, options) {
+    const project = loadProject(dir);
+    const scene = requireScene(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 watch = options.watch
+        ? options.watch.split(",").map((id) => id.trim()).filter(Boolean)
+        : world.entities.filter((e) => e.platformer).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) => {
+        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}".`);
+    const ascii = options.ascii ? renderAscii(world, { columns }) : undefined;
+    if (options.json) {
+        console.log(JSON.stringify({ duration: frames / 60, frames, inputs: options.inputs ?? "", timeline: rows, events: world.events, final: world.snapshot(), ascii }, null, 2));
+        return 0;
+    }
+    console.log(paint("bold", `▶ ${project.config.name}: simulated ${fixed(frames / 60, 2)}s (${frames} frames)`) +
+        paint("dim", `  inputs: ${options.inputs?.trim() || "none"}`));
+    if (watch.length > 0)
+        printTimeline(rows, watch);
+    printEvents(world.events);
+    const outcome = world.won ? paint("green", "level complete") : "level not complete";
+    console.log(`\n${paint("bold", "Final:")} ${outcome} · score ${world.score} · deaths ${world.deaths} · ${world.entities.length} entities`);
+    if (ascii)
+        console.log(`\n${ascii}`);
+    return 0;
+}
+function printTimeline(rows, watch) {
+    const idWidth = Math.max(6, ...watch.map((id) => id.length));
+    console.log(paint("dim", `\n  ${pad("time", 7)} ${pad("input", 14)} ${pad("entity", idWidth)} ${padStart("x", 8)} ${padStart("y", 8)} ${padStart("vx", 8)} ${padStart("vy", 8)}  grounded`));
+    for (const row of rows) {
+        watch.forEach((id, i) => {
+            const e = row.entities[id];
+            const time = i === 0 ? pad(`${fixed(row.time, 2)}s`, 7) : " ".repeat(7);
+            const input = i === 0 ? pad(row.input.join("+") || "-", 14) : " ".repeat(14);
+            const values = e
+                ? `${padStart(fixed(e.x), 8)} ${padStart(fixed(e.y), 8)} ${padStart(fixed(e.vx), 8)} ${padStart(fixed(e.vy), 8)}  ${e.grounded ? "yes" : "no"}`
+                : paint("dim", "(removed)");
+            console.log(`  ${time} ${input} ${pad(id, idWidth)} ${values}`);
+        });
+    }
+}
+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)}`);
+    }
+    if (events.length > MAX_EVENTS_SHOWN)
+        console.log(paint("dim", `  … ${events.length - MAX_EVENTS_SHOWN} more (use --json for all)`));
+}
+function describeEvent(event) {
+    switch (event.type) {
+        case "collect":
+            return `${event.entity} → ${event.item} (+${event.score})`;
+        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`;
+        case "win":
+            return `${event.entity} reached ${event.goal}`;
+        default:
+            return event.entity;
+    }
+}
+/** Turns engine parse errors into user-facing CLI errors. */
+function parse(fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        throw new CliError(err.message);
+    }
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,3 @@
+export declare function test(dir: string, options: {
+    json?: boolean;
+}): number;

package/dist/commands/test.js

@@ -0,0 +1,55 @@
+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) {
+    const project = loadProject(dir);
+    const scene = requireScene(project);
+    const testsDir = join(project.dir, "tests");
+    const files = existsSync(testsDir) ? readdirSync(testsDir).filter((f) => f.endsWith(".test.json")).sort() : [];
+    if (files.length === 0) {
+        const message = 'No tests found. Add tests/<name>.test.json with { "tests": [{ "name": "...", "inputs": "right:1s", "assert": ["player.x > 300"] }] }.';
+        if (options.json)
+            console.log(JSON.stringify({ ok: false, error: message, files: [] }, null, 2));
+        else
+            console.log(paint("yellow", message));
+        return 1;
+    }
+    const results = files.map((file) => {
+        let cases;
+        try {
+            const parsed = JSON.parse(readFileSync(join(testsDir, file), "utf8"));
+            cases = parsed.tests;
+            if (!Array.isArray(cases))
+                throw new Error('expected { "tests": [...] }');
+        }
+        catch (err) {
+            return { file, error: err.message, tests: [] };
+        }
+        return { file, tests: cases.map((c) => runTest(scene, c)) };
+    });
+    const all = results.flatMap((r) => r.tests);
+    const failed = all.filter((t) => !t.pass).length + results.filter((r) => r.error).length;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: failed === 0, passed: all.length - failed, failed, files: results }, null, 2));
+        return failed > 0 ? 1 : 0;
+    }
+    for (const result of results) {
+        console.log(paint("bold", result.file));
+        if (result.error)
+            console.log(paint("red", `  ✗ could not read file: ${result.error}`));
+        for (const t of result.tests) {
+            console.log(t.pass ? paint("green", `  ✓ ${t.name}`) : paint("red", `  ✗ ${t.name}`));
+            if (t.error)
+                console.log(`      ${t.error}`);
+            for (const r of t.results) {
+                if (!r.pass)
+                    console.log(`      ${paint("red", "✗")} ${r.source}  ${paint("dim", "→")} ${r.message}`);
+            }
+        }
+    }
+    const summary = `\n${all.length - failed} passed, ${failed} failed`;
+    console.log(failed > 0 ? paint("red", summary) : paint("green", summary));
+    return failed > 0 ? 1 : 0;
+}

package/dist/format.d.ts

@@ -0,0 +1,11 @@
+import { styleText } from "node:util";
+import type { Diagnostic } from "@ludra/core";
+type Style = Parameters<typeof styleText>[0];
+/** Colors only when writing to a terminal; agents reading piped output get plain text. */
+export declare function paint(style: Style, text: string): string;
+export declare function formatDiagnostic(d: Diagnostic, file: string): string;
+export declare function formatDiagnostics(diagnostics: readonly Diagnostic[], file: string): string;
+export declare function fixed(n: number, digits?: number): string;
+export declare function pad(text: string, width: number): string;
+export declare function padStart(text: string, width: number): string;
+export {};

package/dist/format.js

@@ -0,0 +1,24 @@
+import { styleText } from "node:util";
+/** Colors only when writing to a terminal; agents reading piped output get plain text. */
+export function paint(style, text) {
+    return styleText(style, text, { stream: process.stdout });
+}
+export function formatDiagnostic(d, file) {
+    const icon = d.severity === "error" ? paint("red", "✗ error") : paint("yellow", "! warning");
+    const lines = [`${icon} ${d.code} ${paint("dim", `${file} → ${d.path}`)}`, `  ${d.message}`];
+    if (d.fix)
+        lines.push(`  ${paint("cyan", "fix:")} ${d.fix}`);
+    return lines.join("\n");
+}
+export function formatDiagnostics(diagnostics, file) {
+    return diagnostics.map((d) => formatDiagnostic(d, file)).join("\n\n");
+}
+export function fixed(n, digits = 1) {
+    return n.toFixed(digits);
+}
+export function pad(text, width) {
+    return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+export function padStart(text, width) {
+    return text.length >= width ? text : " ".repeat(width - text.length) + text;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { check } from "./commands/check.js";
+import { components } from "./commands/components.js";
+import { dev } from "./commands/dev.js";
+import { create } from "./commands/new.js";
+import { play } from "./commands/play.js";
+import { test } from "./commands/test.js";
+import { paint } from "./format.js";
+import { CliError } from "./project.js";
+const HELP = `ludra: the game engine built for AI agents
+
+Usage
+  ludra new <folder> [--template platformer]   Create a game project
+  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)
+      --every 0.25s                            Timeline sampling interval
+      --ascii                                  Print the final frame as a text map
+      --columns 120                            Width of the text map (default: 80)
+      --json                                   Machine-readable output
+  ludra test [folder] [--json]                 Run tests/*.test.json
+  ludra components [name] [--json]             Reference for every component and field
+  ludra dev [folder] [--port 5173]             Play the game in the browser with live reload
+
+Folder defaults to the current directory.`;
+function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            inputs: { type: "string" },
+            duration: { type: "string" },
+            watch: { type: "string" },
+            every: { type: "string" },
+            ascii: { type: "boolean" },
+            columns: { type: "string" },
+            json: { type: "boolean" },
+            template: { type: "string" },
+            port: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    const [command, target] = positionals;
+    if (values.help || !command || command === "help") {
+        console.log(HELP);
+        return 0;
+    }
+    switch (command) {
+        case "new":
+            return create(target, values);
+        case "check":
+            return check(target ?? ".", values);
+        case "play":
+            return play(target ?? ".", values);
+        case "test":
+            return test(target ?? ".", values);
+        case "components":
+            return components(target, values);
+        case "dev":
+            return dev(target ?? ".", values);
+        default:
+            throw new CliError(`Unknown command "${command}".\n\n${HELP}`);
+    }
+}
+try {
+    process.exitCode = main(process.argv.slice(2));
+}
+catch (err) {
+    // parseArgs reports unknown flags with a code; show those like our own errors.
+    const known = err instanceof CliError || err.code?.startsWith("ERR_PARSE_ARGS");
+    console.error(known ? paint("red", err.message) : err);
+    process.exitCode = 1;
+}

package/dist/project.d.ts

@@ -0,0 +1,29 @@
+import { type Diagnostic, type SceneDef } 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 {
+}
+export interface ProjectConfig {
+    name: string;
+    entry: string;
+    window: {
+        width: number;
+        height: number;
+    };
+}
+export interface Project {
+    dir: string;
+    config: ProjectConfig;
+    entryPath: string;
+    /** Entry path relative to the project, for messages. */
+    entryLabel: string;
+}
+export declare function loadProject(dir: string): Project;
+export interface SceneLoad {
+    scene?: SceneDef;
+    diagnostics: Diagnostic[];
+}
+/** Reads and validates the entry scene. JSON syntax errors become diagnostics too. */
+export declare function readScene(project: Project): SceneLoad;
+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

@@ -0,0 +1,94 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { collectAssetPaths, validateScene } 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 {
+}
+export function loadProject(dir) {
+    const root = resolve(dir);
+    const configPath = join(root, "ludra.json");
+    if (!existsSync(configPath)) {
+        throw new CliError(`No ludra.json found in ${root}.\nRun \`ludra new <folder>\` to create a game, or pass the project folder as an argument.`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, "utf8"));
+    }
+    catch (err) {
+        throw new CliError(`ludra.json is not valid JSON: ${err.message}`);
+    }
+    const config = {
+        name: raw.name ?? "untitled",
+        entry: raw.entry ?? "scenes/main.scene.json",
+        window: { width: raw.window?.width ?? 960, height: raw.window?.height ?? 540 },
+    };
+    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)) {
+        return {
+            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.`,
+                },
+            ],
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(project.entryPath, "utf8"));
+    }
+    catch (err) {
+        return {
+            diagnostics: [{ severity: "error", code: "E_JSON_SYNTAX", path: "$", message: `Invalid JSON: ${err.message}` }],
+        };
+    }
+    const { scene, diagnostics } = validateScene(raw);
+    if (!scene)
+        return { diagnostics };
+    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. */
+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);
+        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").`,
+        };
+    });
+}
+function listAssets(dir) {
+    const assetsDir = join(dir, "assets");
+    if (!existsSync(assetsDir))
+        return [];
+    return readdirSync(assetsDir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(dir, join(entry.parentPath, entry.name)).replaceAll("\\", "/"))
+        .sort();
+}
+export function isInside(dir, path) {
+    const rel = relative(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);
+    if (!scene) {
+        throw new CliError(`${formatDiagnostics(diagnostics, project.entryLabel)}\n\nFix the errors above (see \`ludra check\`) and try again.`);
+    }
+    return scene;
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@ludra/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "The game engine built for AI agents. The ludra command: create, check, play, test and run Ludra games.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ersingvn/ludra.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/ersingvn/ludra#readme",
+  "bugs": {
+    "url": "https://github.com/ersingvn/ludra/issues"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "prepack": "tsc -b --clean && tsc -b"
+  },
+  "type": "module",
+  "bin": {
+    "ludra": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "ludra-dev": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "@ludra/core": "0.3.1"
+  },
+  "keywords": [
+    "game-engine",
+    "ai",
+    "agents",
+    "claude",
+    "llm",
+    "gamedev",
+    "headless-testing"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/platformer/CLAUDE.md

@@ -0,0 +1,30 @@
+# {{name}}
+
+A 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.
+- `assets/`: SVG art. Spritesheets are frames side by side; tiles repeat.
+- `tests/*.test.json`: gameplay tests, run headlessly
+
+## Loop
+
+1. Edit `scenes/main.scene.json`. 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 --inputs "right:1s, jump:0.4s" --ascii` to see what actually happens.
+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.
+- Jump height = jumpSpeed² / (2 · gravity). The defaults (680, 1800) give about 128px.
+- 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`.
+- Art and effects never change gameplay. Make it playable first, then dress it. Write new art as SVG in `assets/`.

package/templates/platformer/assets/coin.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="80" height="20" viewBox="0 0 80 20">
+  <!-- Spritesheet: 4 frames of 20x20, a spinning coin. -->
+  <g>
+    <circle cx="10" cy="10" r="9" fill="#e0a526"/>
+    <circle cx="10" cy="10" r="7" fill="#ffd166"/>
+    <rect x="8.5" y="5" width="3" height="10" rx="1.5" fill="#e0a526"/>
+    <circle cx="7" cy="6.5" r="1.6" fill="#fff3b0"/>
+  </g>
+  <g transform="translate(20 0)">
+    <ellipse cx="10" cy="10" rx="6.5" ry="9" fill="#e0a526"/>
+    <ellipse cx="10" cy="10" rx="4.8" ry="7" fill="#ffd166"/>
+    <rect x="9" y="5" width="2" height="10" rx="1" fill="#e0a526"/>
+  </g>
+  <g transform="translate(40 0)">
+    <ellipse cx="10" cy="10" rx="2.2" ry="9" fill="#e0a526"/>
+    <rect x="9.3" y="2" width="1.4" height="16" fill="#fff3b0"/>
+  </g>
+  <g transform="translate(60 0)">
+    <ellipse cx="10" cy="10" rx="6.5" ry="9" fill="#e0a526"/>
+    <ellipse cx="10" cy="10" rx="4.8" ry="7" fill="#f2bb3d"/>
+  </g>
+</svg>

package/templates/platformer/assets/flag.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="80" viewBox="0 0 48 80">
+  <!-- Spritesheet: 2 frames of 24x80, a waving goal flag. -->
+  <g>
+    <rect x="3" y="4" width="3" height="76" rx="1.5" fill="#cfd8ff"/>
+    <circle cx="4.5" cy="4" r="3" fill="#ffd166"/>
+    <path d="M6 8 C 12 5, 16 11, 24 8 L 24 26 C 16 29, 12 23, 6 26 Z" fill="#4cc9f0"/>
+    <path d="M6 18 C 12 15, 16 21, 24 18 L 24 26 C 16 29, 12 23, 6 26 Z" fill="#3aa6c8"/>
+  </g>
+  <g transform="translate(24 0)">
+    <rect x="3" y="4" width="3" height="76" rx="1.5" fill="#cfd8ff"/>
+    <circle cx="4.5" cy="4" r="3" fill="#ffd166"/>
+    <path d="M6 8 C 12 11, 16 5, 24 9 L 24 27 C 16 23, 12 29, 6 26 Z" fill="#4cc9f0"/>
+    <path d="M6 18 C 12 21, 16 15, 24 19 L 24 27 C 16 23, 12 29, 6 26 Z" fill="#3aa6c8"/>
+  </g>
+</svg>

package/templates/platformer/assets/ground.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40">
+  <!-- Tile: grass-topped dirt, repeats across the ground. -->
+  <rect width="40" height="40" fill="#6b4f3a"/>
+  <rect y="22" width="40" height="18" fill="#5c4332"/>
+  <circle cx="8" cy="20" r="2" fill="#80624a"/>
+  <circle cx="28" cy="30" r="2.5" fill="#80624a"/>
+  <circle cx="34" cy="16" r="1.5" fill="#4d3829"/>
+  <circle cx="16" cy="34" r="1.5" fill="#4d3829"/>
+  <rect width="40" height="9" fill="#5fbf6a"/>
+  <rect y="7" width="40" height="3" fill="#43944d"/>
+  <path d="M3 9 l 2 -6 l 2 6 M14 9 l 1.5 -5 l 1.5 5 M24 9 l 2 -7 l 2 7 M33 9 l 1.5 -4 l 1.5 4" fill="#7ed98a"/>
+</svg>

package/templates/platformer/assets/lift.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
+  <!-- Tile: riveted metal with hazard stripes for moving platforms. -->
+  <rect width="20" height="20" fill="#8fa3d9"/>
+  <rect width="20" height="3" fill="#c3d0f2"/>
+  <rect y="14" width="20" height="6" fill="#f2c14e"/>
+  <path d="M0 20 L 6 14 L 10 14 L 4 20 Z M10 20 L 16 14 L 20 14 L 14 20 Z" fill="#2b3150"/>
+  <circle cx="5" cy="8" r="1.4" fill="#5d6f9e"/>
+  <circle cx="15" cy="8" r="1.4" fill="#5d6f9e"/>
+</svg>

package/templates/platformer/assets/platform.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
+  <!-- Tile: stone brick for ledges and steps. -->
+  <rect width="20" height="20" fill="#56658f"/>
+  <rect width="20" height="3" fill="#7a8ab8"/>
+  <rect y="17" width="20" height="3" fill="#434f72"/>
+  <rect x="9" y="3" width="2" height="14" fill="#434f72"/>
+  <rect x="1" y="5" width="3" height="2" fill="#6b7aa6"/>
+  <rect x="13" y="9" width="4" height="2" fill="#6b7aa6"/>
+</svg>

package/templates/platformer/assets/player.svg

@@ -0,0 +1,65 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="140" height="36" viewBox="0 0 140 36">
+  <!-- Spritesheet: 5 frames of 28x36, facing right. 0 idle, 1-2 run, 3 jump, 4 fall. -->
+  <defs>
+    <g id="eyes">
+      <ellipse cx="15" cy="15" rx="3.2" ry="3.8" fill="#ffffff"/>
+      <ellipse cx="21.5" cy="15" rx="3.2" ry="3.8" fill="#ffffff"/>
+      <circle cx="16.3" cy="15.6" r="1.7" fill="#1d2333"/>
+      <circle cx="22.8" cy="15.6" r="1.7" fill="#1d2333"/>
+    </g>
+    <path id="leaf" d="M14 7 q 2 -6 8 -5 q -2 5 -8 5 z" fill="#4cc9a0"/>
+  </defs>
+
+  <!-- 0: idle -->
+  <g>
+    <rect x="7" y="29" width="6" height="6" rx="2" fill="#3f9e5c"/>
+    <rect x="16" y="29" width="6" height="6" rx="2" fill="#3f9e5c"/>
+    <rect x="3" y="7" width="22" height="24" rx="8" fill="#7cf29c"/>
+    <rect x="3" y="21" width="22" height="10" rx="5" fill="#62d886"/>
+    <use href="#leaf"/>
+    <use href="#eyes"/>
+  </g>
+
+  <!-- 1: run, legs apart -->
+  <g transform="translate(28 0)">
+    <rect x="3" y="28" width="6" height="6" rx="2" fill="#3f9e5c"/>
+    <rect x="19" y="29" width="6" height="6" rx="2" fill="#3f9e5c"/>
+    <rect x="3" y="6" width="22" height="24" rx="8" fill="#7cf29c"/>
+    <rect x="3" y="20" width="22" height="10" rx="5" fill="#62d886"/>
+    <use href="#leaf" transform="translate(0 -1)"/>
+    <use href="#eyes" transform="translate(0 -1)"/>
+  </g>
+
+  <!-- 2: run, legs together -->
+  <g transform="translate(56 0)">
+    <rect x="10" y="29" width="6" height="6" rx="2" fill="#3f9e5c"/>
+    <rect x="14" y="28" width="6" height="6" rx="2" fill="#3f9e5c"/>
+    <rect x="3" y="7" width="22" height="24" rx="8" fill="#7cf29c"/>
+    <rect x="3" y="21" width="22" height="10" rx="5" fill="#62d886"/>
+    <use href="#leaf"/>
+    <use href="#eyes"/>
+  </g>
+
+  <!-- 3: jump, stretched -->
+  <g transform="translate(84 0)">
+    <rect x="8" y="28" width="5" height="7" rx="2" fill="#3f9e5c"/>
+    <rect x="15" y="28" width="5" height="7" rx="2" fill="#3f9e5c"/>
+    <rect x="4" y="3" width="20" height="27" rx="8" fill="#7cf29c"/>
+    <rect x="4" y="19" width="20" height="11" rx="5" fill="#62d886"/>
+    <use href="#leaf" transform="translate(0 -4)"/>
+    <use href="#eyes" transform="translate(-0.5 -3)"/>
+  </g>
+
+  <!-- 4: fall, squashed, looking down -->
+  <g transform="translate(112 0)">
+    <rect x="4" y="29" width="7" height="6" rx="2" fill="#3f9e5c"/>
+    <rect x="17" y="29" width="7" height="6" rx="2" fill="#3f9e5c"/>
+    <rect x="1" y="10" width="26" height="21" rx="8" fill="#7cf29c"/>
+    <rect x="1" y="22" width="26" height="9" rx="4.5" fill="#62d886"/>
+    <use href="#leaf" transform="translate(0 3)"/>
+    <ellipse cx="15" cy="18" rx="3.2" ry="3.8" fill="#ffffff"/>
+    <ellipse cx="21.5" cy="18" rx="3.2" ry="3.8" fill="#ffffff"/>
+    <circle cx="16" cy="20" r="1.7" fill="#1d2333"/>
+    <circle cx="22.5" cy="20" r="1.7" fill="#1d2333"/>
+  </g>
+</svg>

package/templates/platformer/assets/slime.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="26" viewBox="0 0 64 26">
+  <!-- Spritesheet: 2 frames of 32x26, a bouncing slime facing right. -->
+  <g>
+    <path d="M2 25 C 2 10, 8 3, 16 3 C 24 3, 30 10, 30 25 Z" fill="#c77dff"/>
+    <path d="M5 25 C 5 18, 9 14, 13 14 C 9 17, 8 21, 8 25 Z" fill="#e0b0ff" opacity="0.7"/>
+    <path d="M14 11 l 6 2" stroke="#2a1440" stroke-width="2" stroke-linecap="round"/>
+    <path d="M27 11 l -4 2" stroke="#2a1440" stroke-width="2" stroke-linecap="round"/>
+    <circle cx="18" cy="15" r="2" fill="#2a1440"/>
+    <circle cx="24" cy="15" r="2" fill="#2a1440"/>
+    <path d="M17 20 q 4 2 8 0" stroke="#2a1440" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+  </g>
+  <g transform="translate(32 0)">
+    <path d="M0 25 C 0 14, 7 8, 16 8 C 25 8, 32 14, 32 25 Z" fill="#c77dff"/>
+    <path d="M3 25 C 3 20, 7 17, 11 17 C 7 19, 6 22, 6 25 Z" fill="#e0b0ff" opacity="0.7"/>
+    <path d="M14 15 l 6 2" stroke="#2a1440" stroke-width="2" stroke-linecap="round"/>
+    <path d="M28 15 l -4 2" stroke="#2a1440" stroke-width="2" stroke-linecap="round"/>
+    <circle cx="18" cy="18.5" r="2" fill="#2a1440"/>
+    <circle cx="24.5" cy="18.5" r="2" fill="#2a1440"/>
+    <path d="M17 22.5 q 4 1.5 8 0" stroke="#2a1440" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+  </g>
+</svg>

package/templates/platformer/assets/spikes.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="16" viewBox="0 0 20 16">
+  <!-- Tile: repeats horizontally across the hazard. -->
+  <path d="M0 16 L 5 1 L 10 16 Z" fill="#e4e8f2"/>
+  <path d="M5 1 L 10 16 L 6.5 16 Z" fill="#a9b1c7"/>
+  <path d="M10 16 L 15 1 L 20 16 Z" fill="#e4e8f2"/>
+  <path d="M15 1 L 20 16 L 16.5 16 Z" fill="#a9b1c7"/>
+  <rect x="0" y="13" width="20" height="3" fill="#ff5d73"/>
+</svg>

package/templates/platformer/ludra.json

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

package/templates/platformer/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.3.1"
+  }
+}

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

@@ -0,0 +1,154 @@
+{
+  "name": "Level 1",
+  "world": { "width": 1920, "height": 540, "gravity": 1800, "background": "#1b2140" },
+  "effects": {
+    "jump": { "sound": "jump", "particles": { "count": 6, "color": "#cfd8ff", "speed": 60, "direction": 90, "spread": 150, "life": 0.25, "size": 3, "gravity": 0 } },
+    "land": { "sound": "thud", "particles": { "count": 5, "color": "#cfd8ff", "speed": 50, "direction": -90, "spread": 160, "life": 0.2, "size": 2, "gravity": 300 } },
+    "collect": { "sound": "coin", "particles": { "count": 14, "color": "#ffd166", "speed": 140, "life": 0.45, "size": 3, "gravity": 200 } },
+    "stomp": { "sound": "hit", "shake": 5, "particles": { "count": 18, "color": "#c77dff", "speed": 180, "life": 0.5, "size": 4 } },
+    "die": { "sound": "explosion", "shake": 10, "particles": { "count": 30, "color": "#ff5d73", "speed": 220, "life": 0.7, "size": 4 } },
+    "win": { "sound": "powerup", "shake": 3, "particles": { "count": 60, "color": "#4cc9f0", "speed": 260, "life": 1.2, "size": 4, "gravity": 150 } }
+  },
+  "entities": [
+    {
+      "id": "player",
+      "components": {
+        "transform": { "x": 80, "y": 482 },
+        "body": { "type": "dynamic", "width": 28, "height": 36 },
+        "sprite": {
+          "color": "#7cf29c",
+          "image": "assets/player.svg",
+          "frameWidth": 28,
+          "frameHeight": 36,
+          "idle": "0",
+          "run": "1-2",
+          "jump": "3",
+          "fall": "4",
+          "fps": 10,
+          "layer": 3
+        },
+        "platformer": { "speed": 240, "jumpSpeed": 680 },
+        "camera": {}
+      }
+    },
+    {
+      "id": "ground-start",
+      "components": {
+        "transform": { "x": 380, "y": 520 },
+        "body": { "type": "static", "width": 760, "height": 40 },
+        "sprite": { "color": "#3b4766", "image": "assets/ground.svg", "tile": true }
+      }
+    },
+    {
+      "id": "ground-end",
+      "components": {
+        "transform": { "x": 1450, "y": 520 },
+        "body": { "type": "static", "width": 940, "height": 40 },
+        "sprite": { "color": "#3b4766", "image": "assets/ground.svg", "tile": true }
+      }
+    },
+    {
+      "id": "wall-left",
+      "components": {
+        "transform": { "x": -10, "y": 270 },
+        "body": { "type": "static", "width": 20, "height": 540 }
+      }
+    },
+    {
+      "id": "wall-right",
+      "components": {
+        "transform": { "x": 1930, "y": 270 },
+        "body": { "type": "static", "width": 20, "height": 540 }
+      }
+    },
+    {
+      "id": "ledge",
+      "components": {
+        "transform": { "x": 300, "y": 410 },
+        "body": { "type": "static", "width": 160, "height": 20 },
+        "sprite": { "color": "#56658f", "image": "assets/platform.svg", "tile": true }
+      }
+    },
+    {
+      "id": "coin-1",
+      "components": {
+        "transform": { "x": 300, "y": 370 },
+        "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 }
+      }
+    },
+    {
+      "id": "spikes",
+      "components": {
+        "transform": { "x": 560, "y": 492 },
+        "body": { "type": "static", "width": 80, "height": 16, "sensor": true },
+        "sprite": { "color": "#ff5d73", "image": "assets/spikes.svg", "tile": true, "layer": 1 },
+        "hazard": {}
+      }
+    },
+    {
+      "id": "lift",
+      "components": {
+        "transform": { "x": 800, "y": 440 },
+        "body": { "type": "kinematic", "width": 120, "height": 20 },
+        "sprite": { "color": "#8fa3d9", "image": "assets/lift.svg", "tile": true },
+        "patrol": { "axis": "x", "distance": 140, "speed": 90 }
+      }
+    },
+    {
+      "id": "coin-2",
+      "components": {
+        "transform": { "x": 870, "y": 390 },
+        "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 }
+      }
+    },
+    {
+      "id": "slime",
+      "components": {
+        "transform": { "x": 1150, "y": 487 },
+        "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 }
+      }
+    },
+    {
+      "id": "step-1",
+      "components": {
+        "transform": { "x": 1500, "y": 410 },
+        "body": { "type": "static", "width": 140, "height": 20 },
+        "sprite": { "color": "#56658f", "image": "assets/platform.svg", "tile": true }
+      }
+    },
+    {
+      "id": "step-2",
+      "components": {
+        "transform": { "x": 1680, "y": 330 },
+        "body": { "type": "static", "width": 140, "height": 20 },
+        "sprite": { "color": "#56658f", "image": "assets/platform.svg", "tile": true }
+      }
+    },
+    {
+      "id": "coin-3",
+      "components": {
+        "transform": { "x": 1680, "y": 290 },
+        "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 }
+      }
+    },
+    {
+      "id": "flag",
+      "components": {
+        "transform": { "x": 1860, "y": 460 },
+        "body": { "type": "static", "width": 24, "height": 80, "sensor": true },
+        "sprite": { "color": "#4cc9f0", "image": "assets/flag.svg", "frameWidth": 24, "idle": "0-1", "fps": 3, "flip": false, "layer": 1 },
+        "emitter": { "rate": 6, "color": "#fff3b0", "speed": 30, "spread": 70, "life": 1.2, "size": 3, "gravity": -20 },
+        "goal": { "requireScore": 4 }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "tests": [
+    {
+      "name": "player rests on the ground",
+      "duration": "1s",
+      "assert": ["player.grounded == true", "player.y == 482", "deaths == 0"]
+    },
+    {
+      "name": "player runs right",
+      "inputs": "right:1s",
+      "assert": ["player.x > 300 at 1s", "player.grounded == true at 1s"]
+    },
+    {
+      "name": "jumping leaves the ground and lands again",
+      "inputs": "wait:0.2s, jump:0.4s",
+      "assert": ["events.jump == 1", "player.y < 400 at 0.5s", "player.grounded == true at end"]
+    },
+    {
+      "name": "spikes kill the player, who respawns at the start",
+      "inputs": "right:1.85s",
+      "duration": "2s",
+      "assert": ["deaths == 1", "events.die == 1", "player.x < 200"]
+    },
+    {
+      "name": "the lift carries the player over the pit",
+      "inputs": "right:0.3s, right+jump:0.45s, right:0.85s, right+jump:0.45s, right:0.35s, right+jump:0.45s, right:0.18s",
+      "duration": "4s",
+      "assert": ["coin-2.exists == false", "player.grounded == true", "player.x > 860", "deaths == 0"]
+    },
+    {
+      "name": "the level can be completed without dying",
+      "inputs": "right:0.3s, right+jump:0.45s, right:0.85s, right+jump:0.45s, right:0.35s, right+jump:0.45s, right:0.18s, wait:1.0s, right+jump:0.45s, right:0.3s, wait:0.6s, right+jump:0.45s, right:0.1s, wait:0.6s, right:0.7s, right+jump:0.45s, right:0.2s, right+jump:0.45s, right:1.5s",
+      "assert": ["won == true", "deaths == 0", "score == 4", "events.stomp == 1", "slime.exists == false"]
+    }
+  ]
+}