romdev-mcp 0.1.1

package/examples/snes/templates/sports.c

@@ -0,0 +1,144 @@
+/* ── sports.c — SNES PVSnesLib two-player Pong scaffold ─────────────
+ *
+ * Two-player Pong. Both ports wired:
+ *   padsCurrent(0) — UP/DOWN moves the left paddle (player 1)
+ *   padsCurrent(1) — UP/DOWN moves the right paddle (player 2)
+ *
+ * AI fallback on port 1 when no second controller is plugged in
+ * (padsCurrent(1) returns 0). Per-side score 0-9 via consoleDrawText.
+ *
+ * tcc-65816 is C89 — all declarations at block top, no inline `for (u16 i …)`.
+ */
+
+#include <snes.h>
+#include "snes_sfx.c"
+
+extern char tilfont, palfont;
+extern char tilsprite, palsprite;
+
+#define COURT_TOP   16
+#define COURT_BOT   208
+#define PADDLE_H    24
+#define BALL_SIZE   8
+#define PADDLE_X1   16
+#define PADDLE_X2   232
+
+static s16 p1y, p2y, bx, by;
+static s8  bdx, bdy;
+static u16 score_p1, score_p2;
+static u16 serve_timer;
+
+static void serve_ball(u8 to_left) {
+    bx = 124;
+    by = 110;
+    bdx = to_left ? -2 : 2;
+    bdy = ((score_p1 + score_p2) & 1) ? -1 : 1;
+    serve_timer = 30;
+}
+
+static void reset_match(void) {
+    p1y = 96;
+    p2y = 96;
+    score_p1 = 0;
+    score_p2 = 0;
+    serve_ball(0);
+}
+
+static void render_scores(void) {
+    char buf[2];
+    buf[1] = 0;
+    buf[0] = '0' + (score_p1 % 10);
+    consoleDrawText(6, 2, buf);
+    buf[0] = '0' + (score_p2 % 10);
+    consoleDrawText(24, 2, buf);
+}
+
+int main(void) {
+    u16 p1, p2;
+    u16 i, slot;
+    s16 target;
+
+    consoleSetTextMapPtr(0x6800);
+    consoleSetTextGfxPtr(0x3000);
+    consoleSetTextOffset(0x0100);
+    consoleInitText(0, 16 * 2, &tilfont, &palfont);
+    setMode(BG_MODE1, 0);
+    bgSetDisable(1);
+    bgSetDisable(2);
+
+    oamInitGfxSet(&tilsprite, 32, &palsprite, 32, 0, 0x0000, OBJ_SIZE8_L16);
+
+    consoleDrawText(2, 1, "P1");
+    consoleDrawText(28, 1, "P2");
+    consoleDrawText(6, 26, "UP/DOWN MOVES YOUR PADDLE");
+
+    /* Hide all OAM slots initially. */
+    for (i = 0; i < 7; i++) oamSet(i, 0, 240, 3, 0, 0, 0, 0);
+
+    setScreenOn();
+    sfx_init();
+    reset_match();
+
+    while (1) {
+        slot = 0;
+        /* Left paddle = 3 stacked 8×8 sprites */
+        for (i = 0; i < PADDLE_H / 8; i++) {
+            oamSet(slot++, PADDLE_X1, (u16)(p1y + i * 8), 3, 0, 0, 0, 0);
+        }
+        for (i = 0; i < PADDLE_H / 8; i++) {
+            oamSet(slot++, PADDLE_X2, (u16)(p2y + i * 8), 3, 0, 0, 0, 0);
+        }
+        oamSet(slot++, bx, by, 3, 0, 0, 0, 0);
+        oamUpdate();
+        render_scores();
+        WaitForVBlank();
+
+        p1 = padsCurrent(0);
+        p2 = padsCurrent(1);
+
+        if ((p1 & KEY_UP)   && p1y > COURT_TOP)            p1y -= 2;
+        if ((p1 & KEY_DOWN) && p1y < COURT_BOT - PADDLE_H) p1y += 2;
+
+        if (p2 != 0) {
+            if ((p2 & KEY_UP)   && p2y > COURT_TOP)            p2y -= 2;
+            if ((p2 & KEY_DOWN) && p2y < COURT_BOT - PADDLE_H) p2y += 2;
+        } else {
+            target = by - PADDLE_H / 2;
+            if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 1;
+            else if (p2y > target && p2y > COURT_TOP)       p2y -= 1;
+        }
+
+        if (serve_timer > 0) {
+            serve_timer--;
+        } else {
+            bx = (s16)(bx + bdx);
+            by = (s16)(by + bdy);
+
+            if (by < COURT_TOP)             { by = COURT_TOP; bdy = (s8)(-bdy); }
+            if (by + BALL_SIZE > COURT_BOT) { by = COURT_BOT - BALL_SIZE; bdy = (s8)(-bdy); }
+
+            if (bdx < 0
+                && bx <= PADDLE_X1 + 8
+                && bx + BALL_SIZE >= PADDLE_X1
+                && by + BALL_SIZE > p1y
+                && by < p1y + PADDLE_H) {
+                bdx = (s8)(-bdx);
+                bx = PADDLE_X1 + 8;
+                sfx_play(1);  /* paddle hit */
+            }
+            if (bdx > 0
+                && bx + BALL_SIZE >= PADDLE_X2
+                && bx <= PADDLE_X2 + 8
+                && by + BALL_SIZE > p2y
+                && by < p2y + PADDLE_H) {
+                bdx = (s8)(-bdx);
+                bx = PADDLE_X2 - BALL_SIZE;
+                sfx_play(1);
+            }
+
+            if (bx < 4)   { if (score_p2 < 9) score_p2++; sfx_play(2); serve_ball(0); }
+            if (bx > 252) { if (score_p1 < 9) score_p1++; sfx_play(2); serve_ball(1); }
+        }
+    }
+    return 0;
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "romdev-mcp",
+  "version": "0.1.1",
+  "description": "MCP server giving coding agents full control of homebrew ROM development across retro platforms (NES, SNES, GB, Genesis, Atari, C64, ...) via WASM libretro cores.",
+  "type": "module",
+  "main": "src/mcp/server.js",
+  "bin": {
+    "romdev-mcp": "src/mcp/server.js",
+    "romdev-mcp-cli": "src/cli/smoke.js"
+  },
+  "scripts": {
+    "smoke": "node --enable-source-maps src/cli/smoke.js",
+    "mcp": "node --enable-source-maps src/mcp/server.js",
+    "test": "node --test 'src/**/*.test.js' 'test/**/*.test.js'"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "libretro",
+    "wasm",
+    "emulator",
+    "homebrew",
+    "retro",
+    "nes",
+    "snes",
+    "game-boy",
+    "genesis",
+    "atari",
+    "commodore-64",
+    "agent",
+    "claude"
+  ],
+  "author": "monteslu",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@monteslu/chafa-wasm": "^0.4.0",
+    "romdev-core-fceumm": "0.1.0",
+    "romdev-core-gambatte": "0.1.0",
+    "romdev-core-gpgx": "0.1.0",
+    "romdev-core-handy": "0.1.0",
+    "romdev-core-prosystem": "0.1.0",
+    "romdev-core-vice": "0.1.0",
+    "romdev-platform-atari2600": "0.1.0",
+    "romdev-platform-gba": "0.1.0",
+    "romdev-platform-snes": "0.1.0",
+    "romdev-toolchain-cc65": "0.1.0",
+    "romdev-toolchain-m68k-gcc": "0.1.0",
+    "romdev-toolchain-rgbds": "0.1.0",
+    "romdev-toolchain-sdcc": "0.1.0",
+    "romdev-toolchain-vasm": "0.1.0",
+    "ase-parser": "^0.0.18",
+    "omggif": "^1.0.10",
+    "pngjs": "^7.0.0",
+    "socket.io": "^4.8.3",
+    "yauzl": "^3.3.1",
+    "zod": "^4.4.3"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js",
+    "examples",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "optionalDependencies": {
+    "@kmamal/sdl": "^0.11.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monteslu/romdev.git",
+    "directory": "packages/romdev"
+  },
+  "homepage": "https://github.com/monteslu/romdev#readme",
+  "bugs": {
+    "url": "https://github.com/monteslu/romdev/issues"
+  }
+}

package/src/cli/smoke.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+// romdev-cli — direct CLI for the romdev host.
+//
+// End users use `play` to fire up a ROM in a window. The other subcommands
+// are smoke-test harnesses that match what the MCP tools do, useful for
+// scripting + debugging without a running MCP server.
+//
+// Usage:
+//   romdev-cli play <rom-or-zip> [--platform PLAT] [--scale N]
+//   romdev-cli identify <rom-or-zip>
+//   romdev-cli run --core <path> --rom <path> [--frames N] [--screenshot out.png]
+//
+// `play` accepts .zip files — the first ROM-shaped entry is extracted to a
+// temp file and loaded into the matching libretro core. Platform is
+// inferred from the file extension if not given.
+
+import { writeFile, mkdtemp, readdir } from "node:fs/promises";
+import { existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import yauzl from "yauzl";
+import { LibretroHost } from "../host/index.js";
+import { framebufferToPng } from "../host/framebuffer.js";
+import { resolveCore } from "../cores/registry.js";
+
+// Extension → platform mapping. Drives auto-detection when --platform isn't
+// passed. Keep this in sync with cores/registry.js platform IDs.
+const EXT_TO_PLATFORM = {
+  ".nes": "nes",
+  ".unf": "nes",
+  ".fds": "nes",
+  ".sfc": "snes",
+  ".smc": "snes",
+  ".swc": "snes",
+  ".fig": "snes",
+  ".gb":  "gb",
+  ".gbc": "gbc",
+  ".gba": "gba",
+  ".md":  "genesis",
+  ".gen": "genesis",
+  ".smd": "genesis",
+  ".bin": "genesis",  // ambiguous; could be Genesis or other — defaults to Genesis
+  ".sms": "sms",
+  ".gg":  "gg",
+  ".a26": "atari2600",
+  ".a78": "atari7800",
+  ".lnx": "lynx",
+  ".prg": "c64",
+  ".d64": "c64",
+  ".t64": "c64",
+};
+
+// Known ROM file extensions for picking which entry in a .zip is the real
+// ROM (vs. a README, save state, etc.).
+const ROM_EXTS = new Set(Object.keys(EXT_TO_PLATFORM));
+
+function platformFromExtension(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return EXT_TO_PLATFORM[ext] ?? null;
+}
+
+// Extract the first ROM-looking entry from a .zip to a temp file. Returns
+// { tempPath, originalName }.
+async function extractFirstRomFromZip(zipPath) {
+  return new Promise((resolve, reject) => {
+    yauzl.open(zipPath, { lazyEntries: true }, (err, zipfile) => {
+      if (err) return reject(err);
+      let found = false;
+      zipfile.on("entry", (entry) => {
+        if (found) return;
+        const ext = path.extname(entry.fileName).toLowerCase();
+        if (!ROM_EXTS.has(ext)) {
+          zipfile.readEntry();
+          return;
+        }
+        found = true;
+        zipfile.openReadStream(entry, async (e, stream) => {
+          if (e) return reject(e);
+          const chunks = [];
+          stream.on("data", (c) => chunks.push(c));
+          stream.on("end", async () => {
+            try {
+              const dir = await mkdtemp(path.join(tmpdir(), "romdev-"));
+              const tempPath = path.join(dir, path.basename(entry.fileName));
+              await writeFile(tempPath, Buffer.concat(chunks));
+              resolve({ tempPath, originalName: entry.fileName });
+            } catch (we) {
+              reject(we);
+            }
+          });
+          stream.on("error", reject);
+        });
+      });
+      zipfile.on("end", () => {
+        if (!found) reject(new Error(`no ROM-shaped file found in ${zipPath}`));
+      });
+      zipfile.on("error", reject);
+      zipfile.readEntry();
+    });
+  });
+}
+
+async function playCommand(romPath, opts) {
+  if (!existsSync(romPath)) {
+    throw new Error(`file not found: ${romPath}`);
+  }
+
+  // Extract zip if needed
+  let actualPath = romPath;
+  let extracted = false;
+  if (path.extname(romPath).toLowerCase() === ".zip") {
+    console.error(`unzipping ${path.basename(romPath)}...`);
+    const { tempPath, originalName } = await extractFirstRomFromZip(romPath);
+    actualPath = tempPath;
+    extracted = true;
+    console.error(`  → ${originalName} (${statSync(tempPath).size} bytes)`);
+  }
+
+  // Resolve platform
+  const platform = opts.platform ?? platformFromExtension(actualPath);
+  if (!platform) {
+    throw new Error(
+      `could not infer platform from extension ${path.extname(actualPath)}. ` +
+      `Pass --platform explicitly. Known extensions: ${Object.keys(EXT_TO_PLATFORM).join(", ")}`,
+    );
+  }
+
+  const core = resolveCore(platform);
+  if (!core) {
+    throw new Error(`no bundled core for platform '${platform}'`);
+  }
+  console.error(`platform: ${platform} (${core.displayName})`);
+
+  // Load core + media
+  const host = new LibretroHost();
+  await host.loadCore(core.jsPath, core.wasmPath);
+  await host.loadMedia({ platform, path: actualPath });
+
+  // Hand off to playtest
+  const { playtest } = await import("../playtest/playtest.js");
+  const scale = opts.scale ? parseInt(opts.scale, 10) : 3;
+  const title = opts.title ?? `romdev-cli — ${path.basename(romPath)}`;
+  const aspect = opts.aspect === "tv" ? "tv" : "fb";
+  const session = await playtest({ host, scale, title, aspect });
+  await session.closed;
+  console.error("playtest closed");
+}
+
+async function identifyCommand(romPath) {
+  if (!existsSync(romPath)) throw new Error(`file not found: ${romPath}`);
+  const { identifyRomFile } = await import("../rom-id/identifier.js");
+  const info = await identifyRomFile(romPath);
+  console.log(JSON.stringify(info, null, 2));
+}
+
+async function runCommand(values) {
+  if (!values.core) throw new Error("--core <path> is required");
+  if (!values.rom)  throw new Error("--rom <path> is required");
+
+  const host = new LibretroHost();
+  await host.loadCore(values.core);
+  await host.loadMedia({
+    platform: values.platform,
+    path: values.rom,
+    mediaKind: values["media-kind"],
+  });
+
+  const n = parseInt(values.frames, 10);
+  console.error(`stepping ${n} frames...`);
+  host.stepFrames(n);
+  const status = host.getStatus();
+  console.error(`done. frame=${status.frameCount} fb=${status.fbWidth}x${status.fbHeight}`);
+
+  if (values.screenshot) {
+    const f = host.getFramebuffer();
+    const png = framebufferToPng(f.width, f.height, f.pixels, f.pitch, f.format);
+    await writeFile(values.screenshot, png);
+    console.error(`wrote ${values.screenshot} (${png.length} bytes)`);
+  }
+}
+
+function usage(exitCode = 0) {
+  console.error(`romdev-cli — homebrew retro game tooling
+
+Usage:
+  romdev-cli play <rom-or-zip> [--platform PLAT] [--scale N] [--title T] [--aspect fb|tv]
+      Open a real SDL window for any ROM. Detects platform from extension.
+      Extracts the first ROM out of a .zip automatically.
+      --aspect fb (default): window opens at raw framebuffer * scale.
+      --aspect tv: stretch to the core's reported TV aspect ratio
+                   (Atari 2600 ~4:3, SNES ~8:7, etc.).
+      Run \`romdev-cli play --help\` for the keyboard/gamepad bindings.
+
+  romdev-cli identify <rom-or-zip>
+      Print a JSON description of the ROM (platform, mapper, hash, etc.).
+
+  romdev-cli run --core <_libretro.js> --rom <path> [--frames N] [--screenshot out.png]
+      Smoke-test: step N frames headless, optionally write a PNG. For
+      pipelines that need a fast no-window verification. Most users want
+      'play' instead.
+
+Examples:
+  romdev-cli play ~/Downloads/Donkey\\ Kong\\ Country.zip
+  romdev-cli play smb1.nes --scale 4
+  romdev-cli play Adventure.a26 --aspect tv
+  romdev-cli identify rom.smc
+`);
+  process.exit(exitCode);
+}
+
+async function playHelp() {
+  const { KEYBOARD_BINDINGS_HELP } = await import("../playtest/playtest.js");
+  console.error(`romdev-cli play — open a ROM in a native window
+
+Usage:
+  romdev-cli play <rom-or-zip> [options]
+
+Options:
+  --platform <id>   Override extension-based platform detection.
+  --scale <N>       Integer upscale factor (default: 3).
+  --title <text>    Window title.
+  --aspect <mode>   'fb' (default) = raw framebuffer * scale.
+                    'tv' = stretch to the core's reported TV aspect ratio.
+
+Controls:
+${KEYBOARD_BINDINGS_HELP}
+`);
+  process.exit(0);
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      core:       { type: "string" },
+      rom:        { type: "string" },
+      frames:     { type: "string", default: "60" },
+      screenshot: { type: "string" },
+      platform:   { type: "string" },
+      "media-kind": { type: "string" },
+      scale:      { type: "string" },
+      title:      { type: "string" },
+      aspect:     { type: "string" },
+      help:       { type: "boolean", short: "h" },
+    },
+  });
+
+  const cmd = positionals[0];
+  // Global --help with no command shows top-level usage. With a command,
+  // it falls through so the command can show its own detailed help.
+  if (values.help && !cmd) usage(0);
+  if (!cmd) usage(1);
+
+  switch (cmd) {
+    case "play":
+      if (values.help) { await playHelp(); break; }
+      if (!positionals[1]) {
+        console.error("usage: romdev-cli play <rom-or-zip>  (try --help for controls)");
+        process.exit(1);
+      }
+      await playCommand(positionals[1], values);
+      break;
+    case "identify":
+      if (!positionals[1]) {
+        console.error("usage: romdev-cli identify <rom-or-zip>");
+        process.exit(1);
+      }
+      await identifyCommand(positionals[1]);
+      break;
+    case "run":
+      await runCommand(values);
+      break;
+    default:
+      console.error(`unknown command: ${cmd}`);
+      usage(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.stack ?? err.message ?? err);
+  process.exit(1);
+});

package/src/cores/registry.js

@@ -0,0 +1,95 @@
+// Core registry. Maps platform IDs to bundled libretro WASM cores.
+//
+// All v1 cores ship inside the npm package under src/cores/wasm/. Resolution
+// is a simple path lookup — there is no fetcher because there is nothing to
+// fetch.
+
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Directory holding all bundled `.js` + `.wasm` libretro core pairs. */
+export const CORES_DIR = path.resolve(__dirname, "wasm");
+
+/**
+ * @typedef {Object} CoreInfo
+ * @property {string} platform     short platform id ("nes", "gb", ...)
+ * @property {string} coreName     filename stem (matches `<coreName>_libretro.js`)
+ * @property {string} displayName
+ * @property {string} [aka]        comma-separated synonyms accepted in resolvers
+ */
+
+/**
+ * @type {Record<string, CoreInfo>}
+ */
+export const CORES = {
+  nes: { platform: "nes", coreName: "fceumm", displayName: "Nintendo Entertainment System (fceumm)" },
+  gb: { platform: "gb", coreName: "gambatte", displayName: "Game Boy / GBC (gambatte)" },
+  gbc: { platform: "gbc", coreName: "gambatte", displayName: "Game Boy / GBC (gambatte)" },
+  atari2600: { platform: "atari2600", coreName: "stella2014", displayName: "Atari 2600 (Stella)" },
+  atari7800: { platform: "atari7800", coreName: "prosystem", displayName: "Atari 7800 (ProSystem)" },
+  lynx: { platform: "lynx", coreName: "handy", displayName: "Atari Lynx (Handy)" },
+  sms: { platform: "sms", coreName: "genesis_plus_gx", displayName: "Sega Master System (Genesis Plus GX)" },
+  gg: { platform: "gg", coreName: "genesis_plus_gx", displayName: "Sega Game Gear (Genesis Plus GX)" },
+  genesis: { platform: "genesis", coreName: "genesis_plus_gx", displayName: "Sega Genesis / Mega Drive (Genesis Plus GX)" },
+  snes: { platform: "snes", coreName: "snes9x", displayName: "SNES (snes9x)" },
+  gba: { platform: "gba", coreName: "mgba", displayName: "Game Boy Advance (mGBA)" },
+  c64: { platform: "c64", coreName: "vice_x64", displayName: "Commodore 64 (VICE x64)" },
+};
+
+/**
+ * Resolve a platform id to absolute paths for its core.
+ * Returns null if the core isn't bundled.
+ * @param {string} platform
+ * @returns {{ platform: string, coreName: string, displayName: string, jsPath: string, wasmPath: string } | null}
+ */
+// Platform → the @romdev binary package that ships its core wasm. Resolution
+// tries the package first (the shipped layout), then falls back to a local
+// src/cores/wasm copy (transition / dev). Add a row here as each platform's
+// package is carved out; platforms not listed still resolve locally.
+const CORE_PACKAGES = {
+  atari2600: "romdev-platform-atari2600",
+  nes: "romdev-core-fceumm",
+  gb: "romdev-core-gambatte",
+  gbc: "romdev-core-gambatte",
+  genesis: "romdev-core-gpgx",
+  sms: "romdev-core-gpgx",
+  gg: "romdev-core-gpgx",
+  c64: "romdev-core-vice",
+  lynx: "romdev-core-handy",
+  atari7800: "romdev-core-prosystem",
+  snes: "romdev-platform-snes",
+  gba: "romdev-platform-gba",
+};
+
+/** Try to get {jsPath,wasmPath} for a core from its @romdev package. */
+function resolveCoreFromPackage(platform, coreName) {
+  const pkg = CORE_PACKAGES[platform];
+  if (!pkg) return null;
+  try {
+    const dir = path.dirname(fileURLToPath(import.meta.resolve(pkg)));
+    const jsPath = path.join(dir, "wasm", `${coreName}_libretro.js`);
+    const wasmPath = path.join(dir, "wasm", `${coreName}_libretro.wasm`);
+    if (existsSync(jsPath) && existsSync(wasmPath)) return { jsPath, wasmPath };
+  } catch { /* package not resolvable — fall through to local */ }
+  return null;
+}
+
+export function resolveCore(platform) {
+  const info = CORES[platform];
+  if (!info) return null;
+  const fromPkg = resolveCoreFromPackage(platform, info.coreName);
+  if (fromPkg) return { ...info, ...fromPkg };
+  const jsPath = path.join(CORES_DIR, `${info.coreName}_libretro.js`);
+  const wasmPath = path.join(CORES_DIR, `${info.coreName}_libretro.wasm`);
+  if (!existsSync(jsPath) || !existsSync(wasmPath)) return null;
+  return { ...info, jsPath, wasmPath };
+}
+
+/** List all platforms whose core is actually bundled and resolvable. */
+export function listAvailableCores() {
+  return Object.keys(CORES).filter((p) => resolveCore(p) !== null);
+}