romdevtools 0.85.0 → 0.87.1

package/src/mcp/tools/disasm.js

@@ -1190,6 +1190,59 @@ function renderBuildMd({ platform, romPath, regions, blobs, build, verifiable, n
  * The default endian follows the CPU (Genesis/m68k → BE; everything else → LE),
  * overridable via `endian`.
  */
+/**
+ * target='source' — return a cart's high-level SOURCE instead of a disassembly, for
+ * platforms where the "cart" IS source (not machine code). Today: PICO-8 (.p8 = Lua +
+ * data sections; .p8.png = the same cart embedded in a label PNG). This is the honest
+ * "understand this cart" path for a Lua VM — there's no machine code to disassemble, so
+ * we hand back the actual Lua the game runs, plus a map of the other sections.
+ */
+async function readCartSourceCore(args) {
+  const romPath = requireRomPath(args);
+  const fs = await import("node:fs/promises");
+  const lower = romPath.toLowerCase();
+  const isPng = lower.endsWith(".p8.png");
+  const isP8 = lower.endsWith(".p8");
+  if (!isP8 && !isPng && args.platform !== "pico8") {
+    throw new Error(
+      `disasm({target:'source'}) is for source-form carts (PICO-8 .p8/.p8.png). '${romPath}' isn't one. ` +
+      `For machine-code ROMs use target:'rom'/'project'/'decompile'.`,
+    );
+  }
+  if (isPng) {
+    // A .p8.png embeds the cart in the PNG's low bits — decoding needs the FAKE-08 core.
+    throw new Error(
+      "disasm({target:'source'}): .p8.png carts store the source steganographically in the PNG — " +
+      "load it (loadMedia({platform:'pico8'})) to run it; export the .p8 text form to read the Lua. " +
+      "Pass a plain-text .p8 here to read its source directly.",
+    );
+  }
+  const text = await fs.readFile(romPath, "utf8");
+  // Split on __section__ markers, preserving order.
+  const parts = text.split(/(^__[a-z]+__$)/m);
+  const sections = {};
+  let current = "(header)";
+  let buf = [];
+  const flush = () => { if (buf.length) sections[current] = buf.join("\n").replace(/^\n+|\n+$/g, ""); buf = []; };
+  for (const chunk of parts) {
+    const m = chunk.match(/^__([a-z]+)__$/);
+    if (m) { flush(); current = m[1]; } else { buf.push(chunk); }
+  }
+  flush();
+  return {
+    platform: "pico8",
+    kind: "source",
+    format: ".p8",
+    note: "PICO-8 carts are SOURCE, not machine code — this is the Lua the game runs (+ its data sections). There is no disassembly to do.",
+    lua: sections.lua ?? "",
+    sections: Object.keys(sections),
+    // Include non-lua data sections so callers can see the full cart shape (gfx/map/sfx/music/gff/label).
+    dataSections: Object.fromEntries(
+      Object.entries(sections).filter(([k]) => k !== "lua" && k !== "(header)"),
+    ),
+  };
+}
+
 async function pointerTableCore(args) {
   const { platform, loBase, hiBase, count, convention = "direct", reverseHandler, bank } = args;
   if (loBase == null) throw new Error("disasm({target:'pointerTable'}): loBase (the table / low-byte base) is required.");
@@ -1485,11 +1538,11 @@ export function registerDisasmTools(server, z) {
     "LLM folds it. `address` for all four comes from target:'functions' (a CPU/virtual address; the file-offset " +
     "mapping is handled for you).",
     {
-      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile", "resolveJumptable", "pointerTable", "recompile"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode; resolveJumptable = recover a computed-jump dispatcher's targets (LIVE — redirects to breakpoint({on:'jumptable'}), which runs the emulator and records the real switch arms a static decompiler can't follow); recompile = EMIT backend — statically recompile a NES ROM's reset routine to SNES 65816 asar source that builds + boots (phase 1: NROM, 6502→65816 emulation mode, PPU/APU seam STUBBED). See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
+      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile", "source", "resolveJumptable", "pointerTable", "recompile"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode; resolveJumptable = recover a computed-jump dispatcher's targets (LIVE — redirects to breakpoint({on:'jumptable'}), which runs the emulator and records the real switch arms a static decompiler can't follow); recompile = EMIT backend — statically recompile a NES ROM's reset routine to SNES 65816 asar source that builds + boots (phase 1: NROM, 6502→65816 emulation mode, PPU/APU seam STUBBED). See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
       // shared
       path: z.string().optional().describe("target=bytes: raw binary path. target=rom/project/references: ROM file path."),
       base64: z.string().optional().describe("target=bytes: base64 of the bytes (OR `path`)."),
-      platform: z.enum(["nes", "snes", "sms", "gg", "gb", "gbc", "atari2600", "atari7800", "c64", "genesis", "gba", "pce", "msx", "lynx"]).optional().describe("target=rom/project/references: override platform (else sniffed from extension)."),
+      platform: z.enum(["nes", "snes", "sms", "gg", "gb", "gbc", "atari2600", "atari7800", "c64", "genesis", "gba", "pce", "msx", "lynx", "pico8"]).optional().describe("target=rom/project/references: override platform (else sniffed from extension). target=source: pico8 (.p8 carts are Lua source)."),
       startAddress: z.number().int().min(0).max(0xffffffff).default(0x8000).describe("target=bytes/rom: address of the first byte (GBA auto-bumped to 0x08000000)."),
       length: z.number().int().min(1).max(65536).optional().describe("target=rom: bytes to disassemble (default 256; mutually exclusive with endAddress)."),
       addOrigin: z.boolean().default(true).describe("target=bytes/rom: prepend `.org` so the asm re-assembles through ca65."),
@@ -1540,6 +1593,7 @@ export function registerDisasmTools(server, z) {
         case "xrefs":      return jsonContent(await analyzeXrefs(requireRomPath(args), args.address, args.platform));
         case "functions":  return jsonContent(await analyzeFunctions(requireRomPath(args), args.platform));
         case "decompile":  return jsonContent(await analyzeDecompile(requireRomPath(args), args.address, args.platform));
+        case "source":     return jsonContent(await readCartSourceCore(args));
         case "recompile":  return await recompileCore(args);
         case "pointerTable": return jsonContent(await pointerTableCore(args));
         case "resolveJumptable":

package/src/mcp/tools/project.js

@@ -662,6 +662,33 @@ const TEMPLATES = {
       mechanics: ["direct framebuffer paint (clear + solid rects)", "recognizable test pattern"],
       techniques: ["PowerVR2 framebuffer bring-up (FB_R_CTRL/FB_R_SIZE/FB_R_SOF1 + SPG)", "640x480 RGB565 at VRAM 0xA5000000", "SH-4 bare crt0 (stack + .bss + main)", "boots on Flycast reios HLE — no firmware"] },
   },
+  // PICO-8 (FAKE-08): the "source" IS a complete .p8 cart (Lua + __gfx__/__sfx__/__music__
+  // sections), so there's no crt0/runtime/linker — fork copies the .p8 and
+  // build({platform:'pico8', source:<the .p8 text>}) packages it. Each is a real playable
+  // game: hand-authored pixel-art sprites, looping music + SFX, title/play/over states,
+  // full genre mechanics. Fork one and reshape a single thing at a time.
+  pico8: {
+    shmup: { main: "templates/shmup.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "STAR SWEEPER — a vertical shooter. Ship sprite w/ thruster animation + i-frame blink, two enemy sprite types, projectile pool, ramping wave spawner, AABB collision, explosion sprites, score + persistent hi-score, looping title/play music that switches on start. The full shmup contract in ~130 lines of Lua.",
+      players: "1", mechanics: ["projectile pool", "wave spawner", "AABB collision", "i-frames", "title/play/over state machine"],
+      techniques: ["hand-authored __gfx__ sprites drawn with spr()", "__music__ + __sfx__ banks (music switches per state)", "sprite animation via frame flip", "scrolling starfield"] },
+    platformer: { main: "templates/platformer.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "HOP QUEST — a platformer. Hero sprite with idle/walk/jump frames (h-flipped by facing), gravity + solid-box collision, variable-height jump, animated spinning-coin sprites to collect, a goal flag, parallax hills, best-time tracking. Fork the movement/level and go.",
+      players: "1", mechanics: ["gravity + solid-box collision", "variable jump", "coin pickups", "goal + win state", "respawn on fall"],
+      techniques: ["hand-authored hero + coin sprites", "spr() h-flip by facing", "walk-cycle animation", "__music__ loop + jump/coin SFX", "parallax backdrop"] },
+    puzzle: { main: "templates/puzzle.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "COLOR DROP — a falling-gem match puzzle. Five faceted gem sprites, an 8×12 well, slide + soft/hard drop, horizontal match-3 line clears with a flash then gravity-settle + combo scoring, next-gem preview, game-over on stack-out. Looping music + drop/slide/match SFX.",
+      players: "1", mechanics: ["grid + falling piece", "match-3 clears", "gravity settle", "combo scoring", "next preview", "stack-out game over"],
+      techniques: ["hand-authored gem sprites", "flash-then-clear timing (state machine on a flash queue)", "column gravity compaction", "__music__ loop + SFX"] },
+    sports: { main: "templates/sports.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "RALLY VOLLEY — a 2-player paddle sports game. Paddle + ball sprites, angle-off-paddle physics, ball speed-up per rally, 1P-vs-CPU (tracking AI) or 2P couch mode toggled on the title, first-to-5 scoring. Looping music + wall/paddle/point SFX. The classic 2P scaffold.",
+      players: "1-2 (vs CPU or couch 2P)", mechanics: ["paddle + ball physics", "angle off paddle", "rally speed-up", "AI opponent", "first-to-5 match"],
+      techniques: ["hand-authored paddle/ball sprites", "mode toggle on title screen", "simple tracking AI", "__music__ loop + bounce/point SFX"] },
+    racing: { main: "templates/racing.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "LANE RUNNER — a top-down endless racer. Player + rival car sprites, 3-lane snap-steer dodging, scrolling road with animated lane dashes + shoulders, speed that ramps with distance, screen-shake on crash, distance score + best. Looping engine music + swerve/crash SFX.",
+      players: "1", mechanics: ["lane-snap steering", "rival spawner", "speed ramp", "crash + game over", "distance score"],
+      techniques: ["hand-authored car sprites", "scrolling-road illusion (moving dashes)", "camera() screen-shake", "__music__ loop + SFX"] },
+  },
 };
 // R37: GBC has its own scaffold tree at examples/gbc/templates/ +
 // src/platforms/gbc/lib/c/. Same runtime files as GB (the APU + Z80 +

package/src/toolchains/index.js

@@ -1042,8 +1042,46 @@ export async function buildForPlatform(args) {
     };
   }
 
+  if (args.platform === "pico8") {
+    // PICO-8 "build" = PACKAGE a .p8 cart (plain-text sections), NOT compile to machine
+    // code — the Lua is source. Accept bare Lua (`source`/`lua`) wrapped into a valid .p8,
+    // or a complete .p8 passed through. Optional data sections (gfx/map/sfx/music) via
+    // `sections`. The "binary" IS the .p8 text bytes, which FAKE-08 loads + runs directly.
+    const { packP8 } = await import("./pico8/pack.js");
+    try {
+      const lua = args.lua ?? args.source ?? args.code;
+      const { text, bytes, warnings } = packP8({
+        lua,
+        p8: args.p8,
+        version: args.p8Version,
+        sections: args.sections ?? {},
+      });
+      return {
+        ok: true,
+        binary: bytes,
+        listing: text,      // the readable .p8 IS the listing
+        symbols: "",
+        log: warnings.length ? warnings.map((w) => `[pico8] ${w}`).join("\n") : "[pico8] packaged .p8 cart",
+        issues: [],
+        exitCode: 0,
+        toolchain: "pico8-pack",
+      };
+    } catch (e) {
+      return {
+        ok: false,
+        binary: null,
+        listing: "",
+        symbols: "",
+        log: String(e.message ?? e),
+        issues: [],
+        exitCode: 1,
+        toolchain: "pico8-pack",
+      };
+    }
+  }
+
   throw new Error(
-    `no bundled toolchain for platform '${args.platform}'. Supported: atari2600 (dasm), nes/c64/atari7800/lynx (cc65), snes (C via tcc-65816+wla+PVSnesLib, or asm via asar), genesis (C via m68k-gcc+SGDK, or asm via vasm68k), gba (C via arm-gcc+libtonc/libgba), gb/gbc (sdcc sm83 / rgbds), sms/gg (sdcc). Call listPlatforms for the live matrix.`,
+    `no bundled toolchain for platform '${args.platform}'. Supported: atari2600 (dasm), nes/c64/atari7800/lynx (cc65), snes (C via tcc-65816+wla+PVSnesLib, or asm via asar), genesis (C via m68k-gcc+SGDK, or asm via vasm68k), gba (C via arm-gcc+libtonc/libgba), gb/gbc (sdcc sm83 / rgbds), sms/gg (sdcc), pico8 (.p8 cart packager). Call listPlatforms for the live matrix.`,
   );
 }
 

package/src/toolchains/pico8/pack.js

@@ -0,0 +1,67 @@
+// PICO-8 .p8 cart "builder" — a PACKAGER, not a compiler. PICO-8 carts are plain-text
+// files with labeled sections (__lua__, __gfx__, __gff__, __label__, __map__, __sfx__,
+// __music__); the Lua is source, not machine code. So "build" here = assemble a valid
+// .p8 from the given Lua (+ optional data sections) that FAKE-08 can load and run.
+//
+// Accepts either a full .p8 already (passed through / validated) or bare Lua source
+// (wrapped into a minimal but valid .p8). Data sections can be supplied verbatim.
+
+const P8_HEADER = "pico-8 cartridge // http://www.pico-8.com";
+const KNOWN_SECTIONS = ["lua", "gfx", "gff", "label", "map", "sfx", "music"];
+
+/** Is this text already a full .p8 cart (has the header + a __lua__ section)? */
+export function isP8Cart(text) {
+  return /^pico-8 cartridge/i.test(text.trimStart()) && /(^|\n)__lua__/.test(text);
+}
+
+/**
+ * Assemble a .p8 cart.
+ * @param {object} opts
+ * @param {string} opts.lua         Lua source for the __lua__ section (required unless `p8` given).
+ * @param {string} [opts.p8]        A complete .p8 already — validated + passed through.
+ * @param {number} [opts.version]   PICO-8 format version line (default 18).
+ * @param {Object<string,string>} [opts.sections]  Extra sections by name → body text
+ *        (e.g. { gfx: "...", map: "...", sfx: "...", music: "..." }). Bodies are the raw
+ *        hex/number rows PICO-8 uses; passed through verbatim.
+ * @returns {{ text: string, bytes: Uint8Array, warnings: string[] }}
+ */
+export function packP8({ lua, p8, version = 18, sections = {} } = {}) {
+  const warnings = [];
+
+  if (p8 != null) {
+    if (!isP8Cart(p8)) {
+      throw new Error("pico8 build: `p8` was given but doesn't look like a .p8 cart (missing 'pico-8 cartridge' header or __lua__ section).");
+    }
+    const text = p8.endsWith("\n") ? p8 : p8 + "\n";
+    return { text, bytes: new TextEncoder().encode(text), warnings };
+  }
+
+  if (typeof lua !== "string" || lua.trim() === "") {
+    throw new Error("pico8 build: provide `lua` (the cart's Lua source) or a full `p8`.");
+  }
+
+  // Validate any extra section names.
+  for (const name of Object.keys(sections)) {
+    if (!KNOWN_SECTIONS.includes(name)) {
+      warnings.push(`unknown .p8 section '__${name}__' — passing through, but PICO-8/FAKE-08 may ignore it.`);
+    }
+  }
+
+  const parts = [P8_HEADER, `version ${version}`, "__lua__", lua.replace(/\n$/, "")];
+  // Emit data sections in canonical order (skip __lua__, handled above).
+  for (const name of KNOWN_SECTIONS) {
+    if (name === "lua") continue;
+    if (sections[name] != null) {
+      parts.push(`__${name}__`, String(sections[name]).replace(/\n$/, ""));
+    }
+  }
+  // Pass through any unknown sections last (so nothing the caller sent is dropped).
+  for (const [name, body] of Object.entries(sections)) {
+    if (!KNOWN_SECTIONS.includes(name)) {
+      parts.push(`__${name}__`, String(body).replace(/\n$/, ""));
+    }
+  }
+
+  const text = parts.join("\n") + "\n";
+  return { text, bytes: new TextEncoder().encode(text), warnings };
+}