romdevtools 0.13.0

package/src/mcp/tools/metasprite-tools.js

@@ -0,0 +1,256 @@
+// Meta-sprite capture tools — lift a live character (composed of multiple
+// hardware sprites / OAM entries) into a reusable homebrew asset, preserving
+// each piece's position/size/tile-order/palette/flips. Works on every
+// tile-based sprite platform: genesis, snes, nes, gb, gbc, sms, gg.
+// (C64 MOBs are 24×21 bitmaps, not tiles — not supported; the adapter
+// throws a clear explanation.)
+
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import path from "node:path";
+import { getHost } from "../state.js";
+import { imageContent, jsonContent, safeTool } from "../util.js";
+import { inspectSpritesCore } from "./platform-tools.js";
+
+const SPRITE_PLATFORMS = "genesis, snes, nes, gb, gbc, sms, gg";
+
+// ── sprites op implementations ──────────────────────────────────────────
+// Each op is the body of one former narrow tool, verbatim. The `sprites`
+// router (below) dispatches on `op` and returns the MCP-shaped result.
+
+// op:'inspect' → inspectSpritesCore lives in platform-tools.js (reads native OAM).
+
+async function spritesCapture(sessionKey, { platform, rect, slots, includePartials, name, emit, outputDir }) {
+  const host = getHost(sessionKey);
+  const p = platform ?? host.status.platform;
+  const { captureMetaSprite } = await import("../../platforms/common/metasprite.js");
+  const r = await captureMetaSprite(host, p, { rect, slots, includePartials, name });
+
+  let cSource = null;
+  if (emit === "c" || emit === "both") {
+    const { emitMetaSpriteCode } = await import("../../platforms/common/metasprite.js");
+    cSource = emitMetaSpriteCode({ layout: r.layout, tiles: r.tiles, palette: r.palette, varName: name });
+  }
+
+  if (outputDir) {
+    await mkdir(outputDir, { recursive: true });
+    const w = async (f, data) => { await writeFile(path.join(outputDir, f), data); return path.join(outputDir, f); };
+    const paths = {
+      tiles: await w("tiles.bin", r.tiles),
+      palette: await w("palette.bin", r.palette),
+      paletteJson: await w("palette.json", JSON.stringify(r.paletteJson, null, 2)),
+      layout: await w("layout.json", JSON.stringify(r.layout, null, 2)),
+      preview: await w("preview.png", r.previewPng),
+    };
+    if (cSource) paths.asset_h = await w(`${name}.h`, cSource);
+    return jsonContent({
+      platform: p, name, note: r.note,
+      tileCount: r.layout.tileCount, pieceCount: r.layout.pieces.length,
+      bounds: r.layout.bounds, origin: r.layout.origin, paths,
+      nextStep: `Inspect ${paths.preview}. Re-verify any time with sprites({op:'render'}) (no rebuild). Include ${cSource ? paths.asset_h : `${paths.tiles} + ${paths.layout}`} in your project.`,
+    });
+  }
+  return {
+    content: [
+      imageContent(r.previewPng.toString("base64")),
+      { type: "text", text: JSON.stringify({
+        platform: p, name, note: r.note, layout: r.layout,
+        tilesBase64: Buffer.from(r.tiles).toString("base64"),
+        paletteBase64: Buffer.from(r.palette).toString("base64"),
+        ...(cSource ? { c: cSource } : {}),
+        hint: "Pass outputDir next time to write files instead of inlining base64.",
+      }) },
+    ],
+  };
+}
+
+async function spritesRender({ tilesPath, layoutPath, outputPath }) {
+  const { renderSaved } = await import("../../platforms/common/metasprite.js");
+  const tiles = new Uint8Array(await readFile(tilesPath));
+  const layout = JSON.parse(await readFile(layoutPath, "utf-8"));
+  const png = renderSaved(tiles, layout);
+  if (outputPath) {
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, png);
+    return jsonContent({ path: outputPath, width: layout.bounds.w, height: layout.bounds.h, pieceCount: layout.pieces.length });
+  }
+  return { content: [imageContent(png.toString("base64")), { type: "text", text: JSON.stringify({ name: layout.name, platform: layout.platform, bounds: layout.bounds, pieceCount: layout.pieces.length }) }] };
+}
+
+async function spritesGroup(sessionKey, { platform, rect, gap }) {
+  const host = getHost(sessionKey);
+  const p = platform ?? host.status.platform;
+  const { groupVisibleSprites } = await import("../../platforms/common/metasprite.js");
+  const { groups } = await groupVisibleSprites(host, p, { rect, gap });
+  return jsonContent({
+    platform: p, groupCount: groups.length, groups,
+    hint: groups.length
+      ? `Pick a group → sprites({op:'capture', platform:"${p}", slots:[${groups[0].slots.join(",")}], outputDir:"..."}). Sorted largest-first.`
+      : "No on-screen sprites — step to a gameplay frame with the character visible, or widen `rect`.",
+  });
+}
+
+async function spritesPreview(sessionKey, { platform, gap, maxGroups, outputDir, inline }) {
+  const host = getHost(sessionKey);
+  const p = platform ?? host.status.platform;
+  const { groupVisibleSprites, captureMetaSprite } = await import("../../platforms/common/metasprite.js");
+  const { groups } = await groupVisibleSprites(host, p, { gap });
+  if (!groups.length) {
+    return jsonContent({ platform: p, groupCount: 0, note: "No on-screen sprites — step to a gameplay frame with the character visible." });
+  }
+  if (!inline && !outputDir) {
+    throw new Error("sprites({op:'preview'}): pass outputDir (write per-group thumbnail PNGs to disk, returns thumbnailPath per group) or inline:true (return the thumbnails in the response).");
+  }
+  if (!inline) await mkdir(outputDir, { recursive: true });
+  const content = [];
+  const observerImages = [];
+  const summary = [];
+  let i = 0;
+  for (const g of groups.slice(0, maxGroups)) {
+    let thumb = null;
+    try {
+      const cap = await captureMetaSprite(host, p, { slots: g.slots, name: "preview" });
+      thumb = cap.previewPng;
+    } catch { /* group may not be capturable (e.g. odd sizes) — still list it */ }
+    const entry = {
+      slots: g.slots,
+      bounds: g.bounds,
+      spriteCount: g.spriteCount,
+      capture: `sprites({op:'capture', platform:"${p}", slots:[${g.slots.join(",")}], name:"<name>", emit:"both", outputDir:"..."})`,
+    };
+    if (thumb) {
+      if (inline) {
+        content.push(imageContent(thumb.toString("base64")));
+      } else {
+        const thumbPath = path.join(outputDir, `group-${i}.png`);
+        await writeFile(thumbPath, thumb);
+        entry.thumbnailPath = thumbPath;
+        observerImages.push({ kind: "image", mimeType: "image/png", base64: thumb.toString("base64") });
+      }
+    }
+    summary.push(entry);
+    i++;
+  }
+  const note = "One thumbnail per group (largest-first). Paste a group's `capture` call to lift it.";
+  if (inline) {
+    content.push({ type: "text", text: JSON.stringify({ platform: p, groupCount: groups.length, shown: summary.length, groups: summary, note }) });
+    return { content };
+  }
+  const json = jsonContent({ platform: p, groupCount: groups.length, shown: summary.length, groups: summary, note });
+  if (observerImages.length) json._observerImages = observerImages;
+  return json;
+}
+
+async function spritesExtractScreenshot({ pngPath, crop, seed, backgroundMode, bgColor, tolerance, previewScale, outputDir }) {
+  const { extractSpriteFromScreenshot } = await import("../../platforms/common/screenshot-sprite.js");
+  const pngBytes = await readFile(pngPath);
+  const r = extractSpriteFromScreenshot({ pngBytes, crop, seed, backgroundMode, bgColor, tolerance, previewScale });
+  if (outputDir) {
+    await mkdir(outputDir, { recursive: true });
+    const sp = path.join(outputDir, "sprite.png"); const dp = path.join(outputDir, "debug.png");
+    await writeFile(sp, r.png); await writeFile(dp, r.debugPng);
+    return jsonContent({ spritePath: sp, debugPath: dp, width: r.width, height: r.height, keptPixels: r.keptPixels, totalPixels: r.totalPixels, note: "Inspect debug.png (magenta = removed). Tune `tolerance` / `backgroundMode` / `seed` if the mask is wrong." });
+  }
+  return {
+    content: [
+      imageContent(r.png.toString("base64")),
+      imageContent(r.debugPng.toString("base64")),
+      { type: "text", text: JSON.stringify({ width: r.width, height: r.height, keptPixels: r.keptPixels, totalPixels: r.totalPixels, note: "First image = transparent sprite, second = debug mask (magenta = removed)." }) },
+    ],
+  };
+}
+
+async function spritesEmitC({ tilesPath, palettePath, layoutPath, name, outputPath }) {
+  const { emitMetaSpriteCode } = await import("../../platforms/common/metasprite.js");
+  const tiles = new Uint8Array(await readFile(tilesPath));
+  const palette = new Uint8Array(await readFile(palettePath));
+  const layout = JSON.parse(await readFile(layoutPath, "utf-8"));
+  const c = emitMetaSpriteCode({ layout, tiles, palette, varName: name });
+  if (outputPath) {
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, c);
+    return jsonContent({ path: outputPath, bytes: c.length, name: name || layout.name, platform: layout.platform });
+  }
+  return jsonContent({ name: name || layout.name, platform: layout.platform, source: c });
+}
+
+export function registerMetaSpriteTools(server, z, sessionKey) {
+  // rect/crop/point shapes reused across ops.
+  const rectShape = z.object({ x: z.number().int(), y: z.number().int(), w: z.number().int().min(1), h: z.number().int().min(1) });
+
+  server.tool(
+    "sprites",
+    "Hardware-sprite (OAM/SAT) inspection + the meta-sprite asset pipeline, one tool keyed by `op`.\n" +
+    "• op:'inspect' — list the loaded ROM's active sprite table as {slot,x,y,tile,palette,priority,flipH,flipV,size,visible}[] (each platform's adapter reads its native OAM and normalizes). `maxSlots`/`slots[]` shrink the response (real slot indices kept). " +
+    "JSON always returned; sms/gg, gb/gbc, atari2600/7800 also render a sprite PNG (`outputPath` or `inline:true`); nes/snes/genesis/c64/gba/pce/msx/lynx are JSON-only. (lynx/atari7800 have no fixed OAM — inspect returns the SCB-list head / MARIA display-list pointer to walk instead.)\n" +
+    "• op:'group' — cluster the current frame's on-screen sprites into likely objects (player/enemy/projectile/HUD) by proximity, sorted largest-first, so you pick a coherent character to capture.\n" +
+    "• op:'preview' — group + a thumbnail per group + a ready-to-paste capture call for each: the fast 'what's on screen, which do I lift?' step. JSON always returned; thumbnails to `outputDir/group-<i>.png` or `inline:true`.\n" +
+    `• op:'capture' — lift a visible character as a reusable meta-sprite the RIGHT way (NOT a screenshot crop, NOT crossPlatformSpriteImport): preserves the real hardware composition (each OAM/SAT entry's pos/size/tile/palette/flips) and per-platform multi-cell tile order, so you AVOID the 'looks right cropped, garbage in-game' bug. Select pieces by \`slots\` (from op:'inspect'/'group') or pixel \`rect\`; emits tiles+palette+layout.json + a preview RE-RENDERED from the exported data (+ idiomatic C with \`emit:'c'|'both'\`). Step to a frame where the character is fully visible first.\n` +
+    "• op:'render' — re-render a captured meta-sprite to PNG from its tiles.bin + layout.json WITHOUT rebuilding a ROM. Verifies a capture (or hand-edited layout) reconstructs correctly.\n" +
+    "• op:'emitC' — generate platform-idiomatic C (Genesis SGDK VDP_setSprite chain; NES/GB/GBC shadow-OAM cell tables; SNES PVSnesLib oamSet pieces; SMS/GG SAT tables) from a layout.json. Use when you captured with emit:'json' and now want the C glue.\n" +
+    `• op:'extractScreenshot' — LOSSY fallback when op:'capture' can't be used (no clean OAM/SAT composition): crop a screenshot region + flood-fill the background away. Emits a transparent PNG + debug PNG (magenta = removed) so you can tune \`tolerance\`. Prefer op:'capture' whenever sprite groups exist.\n` +
+    `group/preview/capture work on ${SPRITE_PLATFORMS}; render/emitC are file-driven (layout.json's \`platform\` selects the emitter). C64 MOBs are 24×21 bitmaps not tiles — capture throws there; use op:'inspect' + the sprite-data pointers and author MOB bitmaps directly.`,
+    {
+      op: z.enum(["inspect", "group", "preview", "capture", "render", "emitC", "extractScreenshot"])
+        .describe("inspect=list OAM; group=cluster on-screen sprites; preview=group+thumbnails+capture calls; capture=lift a meta-sprite the right way; render=re-render a saved capture; emitC=generate C from a layout; extractScreenshot=lossy screenshot-crop fallback."),
+      platform: z.string().optional().describe(`op:inspect/group/preview/capture — defaults to the loaded host. One of: ${SPRITE_PLATFORMS} (inspect also: atari2600/7800, c64, gba, pce, msx, lynx).`),
+      // inspect
+      maxSlots: z.number().int().min(1).max(128).optional().describe("op:inspect — first N sprite slots (OAM order). Omit for all."),
+      // capture/render/emitC selection + assets
+      rect: rectShape.optional().describe("op:capture — select sprites whose on-screen bounds intersect this pixel rect (mutually exclusive with `slots`). op:group — only consider sprites intersecting this rect."),
+      slots: z.array(z.number().int().min(0).max(127)).optional().describe("op:inspect — only these slot indices (non-contiguous OK); wins over maxSlots. op:capture — OAM/SAT slot numbers to lift (mutually exclusive with `rect`)."),
+      includePartials: z.boolean().default(true).describe("op:capture with `rect` — include sprites only partially inside it."),
+      name: z.string().optional().describe("op:capture — asset name (layout.json, filenames, C identifiers; default 'metasprite'). op:emitC — C identifier base (default: layout's name)."),
+      emit: z.enum(["json", "c", "both"]).default("json").describe("op:capture — 'json' = tiles/palette/layout/preview only; 'c'|'both' also emit platform-idiomatic C (<name>.h)."),
+      gap: z.number().int().min(0).default(8).describe("op:group/preview — max pixel gap between two sprites' bounds to join one group. Larger = looser."),
+      maxGroups: z.number().int().min(1).max(20).default(8).describe("op:preview — max groups to render thumbnails for (largest-first)."),
+      tilesPath: z.string().optional().describe("op:render/emitC — absolute path to tiles.bin."),
+      palettePath: z.string().optional().describe("op:emitC — absolute path to palette.bin."),
+      layoutPath: z.string().optional().describe("op:render/emitC — absolute path to layout.json (its `platform` selects the emitter; also carries bpp, palettes, pieces)."),
+      // extractScreenshot
+      pngPath: z.string().optional().describe("op:extractScreenshot — absolute path to the source screenshot PNG."),
+      crop: rectShape.optional().describe("op:extractScreenshot — region to crop, in source-image pixels."),
+      seed: z.object({ x: z.number().int().min(0), y: z.number().int().min(0) }).optional().describe("op:extractScreenshot — a point ON the sprite, in CROP-relative coords. If given, keep only the connected non-background component containing it."),
+      backgroundMode: z.enum(["edge-flood", "color"]).default("edge-flood").describe("op:extractScreenshot — 'edge-flood' (default): flood inward from the crop border. 'color': remove everything near `bgColor` anywhere."),
+      bgColor: z.array(z.number().int().min(0).max(255)).length(3).optional().describe("op:extractScreenshot — [r,g,b] background for 'color' mode (default: top-left crop pixel)."),
+      tolerance: z.number().min(0).max(441).default(24).describe("op:extractScreenshot — color-match tolerance (0-441). Raise if background leaks into the sprite; lower if sprite pixels get removed."),
+      previewScale: z.number().int().min(1).max(8).default(1).describe("op:extractScreenshot — integer upscale for the output + debug PNGs."),
+      // shared output
+      outputPath: z.string().optional().describe("op:inspect (sprite PNG)/render/emitC — write the result here; else return inline/path per op."),
+      outputDir: z.string().optional().describe("Output directory — op:capture (tiles/palette/layout/preview + <name>.h), op:preview (group-<i>.png), op:extractScreenshot (sprite.png + debug.png). Without it those ops inline base64 (op:preview instead needs inline:true)."),
+      inline: z.boolean().default(false).describe("op:inspect/preview — return the image(s) in the response instead of writing to disk."),
+    },
+    safeTool(async (args) => {
+      switch (args.op) {
+        case "inspect":           return await inspectSpritesCore(args);
+        case "group":             return await spritesGroup(sessionKey, args);
+        case "preview":           return await spritesPreview(sessionKey, args);
+        case "capture":           return await spritesCapture(sessionKey, { ...args, name: args.name ?? "metasprite" });
+        case "render": {
+          if (!args.tilesPath || !args.layoutPath) throw new Error("sprites({op:'render'}): `tilesPath` and `layoutPath` are required.");
+          return await spritesRender(args);
+        }
+        case "emitC": {
+          if (!args.tilesPath || !args.palettePath || !args.layoutPath) throw new Error("sprites({op:'emitC'}): `tilesPath`, `palettePath`, and `layoutPath` are required.");
+          return await spritesEmitC(args);
+        }
+        case "extractScreenshot": {
+          if (!args.pngPath || !args.crop) throw new Error("sprites({op:'extractScreenshot'}): `pngPath` and `crop` are required.");
+          return await spritesExtractScreenshot(args);
+        }
+        default: throw new Error(`sprites: unknown op '${args.op}'`);
+      }
+    }),
+  );
+}
+
+/**
+ * encodeArt({stage:'validate'}) — validate Genesis 4bpp tile data/palette
+ * against the VDP's hard limits. Exported so the `encodeArt` router
+ * (sprite-pipeline.js) can call it. Returns a plain object.
+ */
+export async function validateGenesisTilesCore({ tileDataPath, paletteJson, maxPaletteIndex = 15 }) {
+  const { validateGenesisTiles } = await import("../../platforms/genesis/vdp.js");
+  let tileData;
+  if (tileDataPath) tileData = new Uint8Array(await readFile(tileDataPath));
+  return validateGenesisTiles({ tileData, palette: paletteJson, maxPaletteIndex });
+}

package/src/mcp/tools/platform-docs.js

@@ -0,0 +1,113 @@
+// Platform documentation tools — exposes the MENTAL_MODEL.md and
+// TROUBLESHOOTING.md files that live under src/platforms/<platform>/
+// to the agent via MCP. Templates reference these docs in their
+// comments ("read MENTAL_MODEL.md first"); without this tool the
+// agent has no way to actually read them through the protocol.
+//
+// MENTAL_MODEL.md — one-page architecture brief (memory map, video
+//   chip, frame heartbeat, build pipeline). Read once per platform
+//   before writing code.
+// TROUBLESHOOTING.md — symptom→cause→fix table. Read when stuck.
+//
+// Currently shipped for: nes, gb, snes, genesis, sms, atari7800,
+// atari2600. Others are blank (the tool returns an empty list).
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { readFile, stat } from "node:fs/promises";
+
+import { jsonContent, safeTool, textContent } from "../util.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PLATFORMS_ROOT = path.resolve(__dirname, "..", "..", "platforms");
+
+/** Known doc-file names. Add new ones here when shipping more. */
+const DOC_FILES = ["MENTAL_MODEL.md", "TROUBLESHOOTING.md", "UPSTREAM_SOURCES.md"];
+
+// Cross-platform GUIDES (not tied to one platform). Surfaced through the same
+// getPlatformDoc tool under a pseudo-platform id so agents have one way to read
+// docs. e.g. getPlatformDoc({platform:'romhacking', name:'playbook'}).
+const GUIDES = {
+  romhacking: { playbook: "_guides/ROMHACKING_PLAYBOOK.md" },
+};
+
+/**
+ * For a single platform, list which docs exist on disk.
+ *
+ * @returns {Promise<Array<{name: string, file: string, bytes: number}>>}
+ */
+async function listDocsForPlatform(platform) {
+  const dir = path.join(PLATFORMS_ROOT, platform);
+  const out = [];
+  for (const f of DOC_FILES) {
+    const full = path.join(dir, f);
+    try {
+      const s = await stat(full);
+      if (s.isFile()) {
+        out.push({ name: f.replace(/\.md$/, "").toLowerCase(), file: f, bytes: s.size });
+      }
+    } catch {
+      /* not present — skip */
+    }
+  }
+  return out;
+}
+
+/** platform({op:'docs'}) — list the docs available for a platform. */
+export async function listPlatformDocsCore({ platform }) {
+      if (GUIDES[platform]) {
+        const docs = Object.keys(GUIDES[platform]).map((name) => ({ name, file: GUIDES[platform][name] }));
+        return {
+          platform,
+          docs,
+          note: `Cross-platform guide(s). Call platform({ op:'doc', platform: '${platform}', name: '${docs[0]?.name}' }) to read.`,
+        };
+      }
+      const docs = await listDocsForPlatform(platform);
+      return {
+        platform,
+        docs,
+        note: docs.length === 0
+          ? `No docs shipped for '${platform}' yet. Try a different platform or scaffold for boilerplate. (For RE/patching workflow, see platform({op:'doc', platform:'romhacking', name:'playbook'}).)`
+          : `Call platform({op:'doc', platform, name}) to read one. 'name' is 'mental_model' or 'troubleshooting'. For RE/patching workflow across platforms, see platform({op:'doc', platform:'romhacking', name:'playbook'}).`,
+      };
+}
+
+/** platform({op:'doc'}) — full markdown of one platform doc. Returns jsonContent. */
+export async function getPlatformDocCore({ platform, name }) {
+      const lower = name.toLowerCase();
+      // Cross-platform guide lookup.
+      if (GUIDES[platform]) {
+        const rel = GUIDES[platform][lower];
+        if (!rel) throw new Error(`unknown guide '${name}' for '${platform}'. Valid: ${Object.keys(GUIDES[platform]).join(", ")}.`);
+        const full = path.join(PLATFORMS_ROOT, rel);
+        const contents = await readFile(full, "utf-8");
+        return jsonContent({ platform, name: lower, file: rel, contents });
+      }
+      let docFile;
+      if (lower === "mental_model" || lower === "mental-model" || lower === "mentalmodel") {
+        docFile = "MENTAL_MODEL.md";
+      } else if (lower === "troubleshooting") {
+        docFile = "TROUBLESHOOTING.md";
+      } else if (lower === "upstream_sources" || lower === "upstream-sources" || lower === "upstreamsources" || lower === "upstream" || lower === "sources") {
+        docFile = "UPSTREAM_SOURCES.md";
+      } else {
+        throw new Error(`unknown doc '${name}'. Valid: 'mental_model' | 'troubleshooting' | 'upstream_sources'.`);
+      }
+      const full = path.join(PLATFORMS_ROOT, platform, docFile);
+      try {
+        const contents = await readFile(full, "utf-8");
+        return jsonContent({ platform, name: lower, file: docFile, contents });
+      } catch (e) {
+        if (e.code === "ENOENT") {
+          throw new Error(
+            `No ${docFile} for platform '${platform}'. Call platform({op:'docs', platform}) to see what's shipped.`
+          );
+        }
+        throw e;
+      }
+}
+
+// listPlatformDocs/getPlatformDoc folded into the `platform` tool (op:'docs'/'doc').
+export function registerPlatformDocsTools() { /* folded into `platform` */ }