@ludra/cli 0.0.0-stage → 0.4.0

package/dist/headless.js

@@ -0,0 +1,202 @@
+import { spawn } from "node:child_process";
+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";
+const TIMEOUT_MS = 60_000;
+/**
+ * Finds an installed Chromium-based browser: LUDRA_BROWSER if set, otherwise
+ * Chrome, Edge or Chromium in their usual places.
+ */
+export function findBrowser() {
+    const fromEnv = process.env.LUDRA_BROWSER;
+    if (fromEnv)
+        return existsSync(fromEnv) ? fromEnv : undefined;
+    const candidates = [];
+    if (process.platform === "win32") {
+        for (const base of [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA]) {
+            if (!base)
+                continue;
+            candidates.push(join(base, "Google", "Chrome", "Application", "chrome.exe"), join(base, "Microsoft", "Edge", "Application", "msedge.exe"));
+        }
+    }
+    else if (process.platform === "darwin") {
+        candidates.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge");
+    }
+    else {
+        const names = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge"];
+        for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+            for (const name of names)
+                candidates.push(join(dir, name));
+        }
+    }
+    return candidates.find((path) => existsSync(path));
+}
+/**
+ * Renders frames of a project in a headless browser, using the same renderer
+ * players see. Starts a private game server and browser, and stops both.
+ */
+export async function captureScreenshots(project, request) {
+    const browserPath = findBrowser();
+    if (!browserPath) {
+        throw new CliError("Screenshots need Chrome, Edge or Chromium installed, and none was found.\n" +
+            "Install one, or set LUDRA_BROWSER to the path of a Chromium-based browser.");
+    }
+    const { server, browserModule } = createGameServer(project, () => "");
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const profile = mkdtempSync(join(tmpdir(), "ludra-browser-"));
+    let browser;
+    let cdp;
+    try {
+        const { width, height } = project.config.window;
+        browser = spawn(browserPath, [
+            "--headless=new",
+            "--remote-debugging-port=0",
+            `--user-data-dir=${profile}`,
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--mute-audio",
+            "--hide-scrollbars",
+            `--window-size=${width},${height}`,
+            "about:blank",
+        ], { stdio: ["ignore", "ignore", "pipe"] });
+        cdp = await Cdp.connect(await devToolsUrl(browser));
+        const origin = `http://127.0.0.1:${port}`;
+        const { targetId } = await cdp.send("Target.createTarget", { url: origin + BLANK_PATH });
+        const { sessionId } = await cdp.send("Target.attachToTarget", { targetId, flatten: true });
+        // The new tab starts on about:blank; wait until it has loaded the game server's page.
+        await waitFor(cdp, sessionId, `location.origin === ${JSON.stringify(origin)} && document.readyState === "complete"`);
+        const script = `(async () => {
+      const { captureFrames } = await import(${JSON.stringify(browserModule)});
+      const data = await (await fetch("/__ludra/scene")).json();
+      if (!data.ok) throw new Error("The scene has errors. Run ludra check.");
+      const canvas = document.createElement("canvas");
+      canvas.width = ${width};
+      canvas.height = ${height};
+      document.body.append(canvas);
+      return captureFrames(canvas, data.scene, {
+        assetBase: ${JSON.stringify(PROJECT_PREFIX)},
+        inputs: ${JSON.stringify(request.inputs)},
+        frames: ${JSON.stringify(request.frames)},
+      });
+    })()`;
+        return await evaluate(cdp, sessionId, script);
+    }
+    finally {
+        await cdp?.send("Browser.close").catch(() => { });
+        cdp?.close();
+        if (browser && browser.exitCode === null) {
+            await new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    browser.kill();
+                    resolve(undefined);
+                }, 3000);
+                browser.once("exit", () => {
+                    clearTimeout(timer);
+                    resolve(undefined);
+                });
+            });
+        }
+        server.close();
+        // The browser can hold its profile for a moment after exiting on Windows.
+        rmSync(profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+    }
+}
+/** Chrome prints "DevTools listening on ws://..." to stderr once it is ready. */
+function devToolsUrl(browser) {
+    return new Promise((resolve, reject) => {
+        let output = "";
+        const timer = setTimeout(() => reject(new CliError(`The browser did not start in time.\n${output.trim()}`)), TIMEOUT_MS);
+        browser.stderr.on("data", (chunk) => {
+            output += chunk.toString();
+            const match = /DevTools listening on (ws:\/\/\S+)/.exec(output);
+            if (match) {
+                clearTimeout(timer);
+                resolve(match[1]);
+            }
+        });
+        browser.once("exit", (code) => {
+            clearTimeout(timer);
+            reject(new CliError(`The browser exited before it was ready (code ${code}).\n${output.trim()}`));
+        });
+        browser.once("error", (err) => {
+            clearTimeout(timer);
+            reject(new CliError(`Could not start the browser: ${err.message}`));
+        });
+    });
+}
+async function waitFor(cdp, sessionId, condition) {
+    const deadline = Date.now() + TIMEOUT_MS;
+    while (!(await evaluate(cdp, sessionId, condition))) {
+        if (Date.now() > deadline)
+            throw new CliError("The browser did not load the game page in time.");
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
+async function evaluate(cdp, sessionId, expression) {
+    const result = await cdp.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true }, sessionId);
+    if (result.exceptionDetails) {
+        const details = result.exceptionDetails;
+        throw new CliError(`Rendering failed in the browser: ${details.exception?.description ?? details.text ?? "unknown error"}`);
+    }
+    return result.result.value;
+}
+/** A minimal Chrome DevTools Protocol client over the WebSocket built into Node. */
+class Cdp {
+    nextId = 1;
+    pending = new Map();
+    socket;
+    constructor(socket) {
+        this.socket = socket;
+        socket.addEventListener("message", (event) => {
+            const message = JSON.parse(String(event.data));
+            if (message.id === undefined)
+                return;
+            const waiter = this.pending.get(message.id);
+            if (!waiter)
+                return;
+            this.pending.delete(message.id);
+            if (message.error)
+                waiter.reject(new CliError(`Browser error: ${message.error.message}`));
+            else
+                waiter.resolve(message.result);
+        });
+        socket.addEventListener("close", () => {
+            for (const waiter of this.pending.values())
+                waiter.reject(new CliError("The browser closed unexpectedly."));
+            this.pending.clear();
+        });
+    }
+    static connect(url) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(url);
+            socket.addEventListener("open", () => resolve(new Cdp(socket)), { once: true });
+            socket.addEventListener("error", () => reject(new CliError(`Could not connect to the browser at ${url}.`)), { once: true });
+        });
+    }
+    send(method, params = {}, sessionId) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new CliError(`The browser did not answer ${method} in time.`));
+            }, TIMEOUT_MS);
+            this.pending.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            });
+            this.socket.send(JSON.stringify({ id, method, params, sessionId }));
+        });
+    }
+    close() {
+        this.socket.close();
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/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)
+      --screenshot 1s,2.5s,end                 Save real rendered frames as PNGs (needs Chrome, Edge or Chromium)
+      --out screenshots                        Folder for screenshots, relative to the project (default: screenshots)
+      --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.`;
+async 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" },
+            screenshot: { type: "string" },
+            out: { 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 = await 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/dist/server.d.ts

@@ -0,0 +1,17 @@
+import { type Server } from "node:http";
+import { type Project } from "./project.ts";
+export declare const PROJECT_PREFIX = "/__ludra/project/";
+/** An empty same-origin page that headless capture loads before importing the engine. */
+export declare const BLANK_PATH = "/__ludra/blank";
+export interface GameServer {
+    server: Server;
+    /** URL path of the engine's browser module, for `import()` in the page. */
+    browserModule: string;
+}
+/**
+ * Serves a project to a browser: the engine's browser runtime, the validated
+ * scene and the project's media. No bundler: when the engine runs from
+ * source, its TypeScript files are type-stripped on the fly.
+ * `indexHtml` builds the page served at "/".
+ */
+export declare function createGameServer(project: Project, indexHtml: (browserModule: string) => string): GameServer;

package/dist/server.js

@@ -0,0 +1,93 @@
+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 { isInside, readScene } from "./project.js";
+export const PROJECT_PREFIX = "/__ludra/project/";
+/** An empty same-origin page that headless capture loads before importing the engine. */
+export const BLANK_PATH = "/__ludra/blank";
+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",
+};
+/**
+ * Serves a project to a browser: the engine's browser runtime, the validated
+ * scene and the project's media. No bundler: when the engine runs from
+ * source, its TypeScript files are type-stripped on the fly.
+ * `indexHtml` builds the page served at "/".
+ */
+export function createGameServer(project, indexHtml) {
+    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(indexHtml(browserModule));
+            }
+            else if (url.pathname === BLANK_PATH) {
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end('<!doctype html><html><head><meta charset="utf-8"><title>Ludra</title></head><body style="margin:0"></body></html>');
+            }
+            else if (url.pathname === "/__ludra/scene") {
+                const { scene, diagnostics } = readScene(project);
+                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);
+        }
+    });
+    return { server, browserModule };
+}
+/** 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");
+}

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.4.0",
+  "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.4.0"
+  },
+  "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. Add `--screenshot 0.5s,end` to save real rendered frames to `screenshots/` and look at them.
+4. Write the behavior you want into `tests/*.test.json` and run `npx @ludra/cli test`.
+5. Run `npx @ludra/cli dev` so a human can play it in the browser.
+
+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/_gitignore

@@ -0,0 +1,2 @@
+node_modules/
+screenshots/

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>