romdevtools 0.28.0 → 0.29.0

package/src/host/LibretroHost.js

@@ -43,6 +43,12 @@ const PLATFORM_CORE_OPTIONS = {
   // `… - C-BIOS` machine tree ships in romdev-core-bluemsx/bios and is mirrored
   // into the wasm FS as the system dir (see loadMedia + resolveSystemDir).
   msx: { bluemsx_msxtype: "MSX2+ - C-BIOS" },
+  // geargrafx ships with the TurboTap disabled, which makes port-1 input
+  // unreachable in-game (every pad scan slot mirrors pad 0). Enabling it
+  // costs nothing for 1P games (slot 0 still reads pad 0) and routes the
+  // host's port-1 input to pad slot 2 — PCE 2P works (probed 2026-06-10
+  // during the ZENITH BARRAGE gold round).
+  pce: { geargrafx_turbotap: "Enabled" },
   // VICE mounts a .d64/.tap/.crt but, with autostart off, just sits at the BASIC
   // `READY.` prompt — the agent would see a blue boot screen, not the game. Force
   // autostart so a disk/tape image runs the first program automatically (same as
@@ -57,6 +63,19 @@ const PLATFORM_CORE_OPTIONS = {
     // files back into the .d64 (VICE updates the in-FS image in place). Without
     // this a game's SAVE silently fails / errors — defeating disk-save support.
     vice_floppy_write_protection: "disabled",
+    // TWO live C64 control ports so 2P games see player 2. The VICE core drives
+    // ONE control port per RetroPad by default (every retro port → cur_port);
+    // the per-port split only happens with the userport adapter, where the
+    // mapper does vice_port = cur_port + retro_port. With joyport=1 + a userport
+    // adapter that gives retro0→control-port-1, retro1→control-port-2 — BOTH
+    // standard ports live. Our games read P1 on control port 2 ($DC00) and P2
+    // on port 1 ($DC01); the host swaps the two retro ports below
+    // (portInputToMask C64 path) so host port 0 = P1 (control port 2) and host
+    // port 1 = P2 (control port 1), matching the universal "port 0 = player 1"
+    // convention. Verified: drives both paddles independently in 2P, 1P-vs-CPU
+    // still reachable. (Both options ship in the wasm — no core rebuild.)
+    vice_joyport: "1",
+    vice_userport_joytype: "HIT",
   },
 };
 
@@ -415,6 +434,9 @@ export class LibretroHost {
 
     // Configure controller port 0 as joypad (some cores default to NONE).
     mod._retro_set_controller_port_device(0, RETRO_DEVICE_JOYPAD);
+    // Port 1 too — needed for 2P. The C64/VICE 2P path (two live control ports)
+    // only reads RetroPad port 1 when it's registered as a joypad device.
+    mod._retro_set_controller_port_device(1, RETRO_DEVICE_JOYPAD);
 
     // ---- Settle the framebuffer to the ROM's chosen geometry ----
     //
@@ -623,7 +645,14 @@ export class LibretroHost {
       this._applyC64ButtonKeys(input.ports[0] || {});
     }
     for (let port = 0; port < this.state.inputPorts.length; port++) {
-      const portInput = this._c64StripKeyButtons(input.ports[port], platform);
+      // C64 2P port swap: with joyport=1 + userport the VICE mapper binds
+      // RetroPad 0 → C64 control port 1 and RetroPad 1 → control port 2. But
+      // our games read player 1 on control port 2 ($DC00) and player 2 on
+      // control port 1 ($DC01). So feed host port 0's input to RetroPad slot 1
+      // (→ control port 2 = P1) and host port 1's to slot 0 (→ port 1 = P2),
+      // restoring the universal "host port 0 = player 1" convention.
+      const srcPort = platform === "c64" ? (port ^ 1) : port;
+      const portInput = this._c64StripKeyButtons(input.ports[srcPort], platform);
       this.state.inputPorts[port][0] = portInputToMask(portInput, platform);
     }
   }
@@ -1095,7 +1124,36 @@ export class LibretroHost {
       this.reset();
       return false;
     }
+    // Battery semantics: SAVE_RAM survives a power-cycle on a battery cart.
+    // Carry it across the reload (the reload itself zeroes it).
+    let sram = null;
+    try {
+      const size = this.regionSize("save_ram");
+      if (size > 0) sram = Uint8Array.from(this.readMemory("save_ram", 0, size));
+    } catch { /* no save_ram region on this core/cart — nothing to carry */ }
     await this.loadMedia(this._loadArgs);
+    if (sram && sram.some((b) => b !== 0)) {
+      // Restore like a frontend restores the .srm: bytes in place BEFORE the
+      // game's boot code reads them. Some cores size SAVE_RAM lazily (gpgx
+      // scans for the last non-empty byte → size 0 on a fresh boot), so fall
+      // back to the raw region pointer when the sized path refuses.
+      let restored = false;
+      try {
+        if (this.regionSize("save_ram") >= sram.length) {
+          this.writeMemory("save_ram", 0, sram);
+          restored = true;
+        }
+      } catch { /* sized path unavailable */ }
+      if (!restored) {
+        try {
+          const ptr = this.mod._retro_get_memory_data(0); // RETRO_MEMORY_SAVE_RAM
+          if (ptr) { this.mod.HEAPU8.set(sram, ptr); restored = true; }
+        } catch { /* no save buffer on this core/cart */ }
+      }
+      // loadMedia's settle frames may already have run the game's
+      // hi-score load against empty SRAM — soft-reset so boot re-reads.
+      if (restored) { try { this.reset(); } catch { /* keep the loaded state */ } }
+    }
     return true;
   }
 

package/src/http/tool-registry.js

@@ -17,7 +17,7 @@
 import { z } from "zod";
 import { registerTools } from "../mcp/tools/index.js";
 import { withClearToolErrors } from "../mcp/util.js";
-import { observer, summarizeForLog, extractImages } from "../observer/bus.js";
+import { observer, summarizeForLog, extractImages, pushObserverFrame } from "../observer/bus.js";
 import { getHostOrNull } from "../mcp/state.js";
 
 /**
@@ -151,21 +151,21 @@ export async function runTool(tool, args, sessionKey) {
     // Strip both from the caller-visible result before it's serialized.
     let sidebandImages = [];
     let frameProvider = null;
+    let frameCaption = null;
     if (r && typeof r === "object") {
       if (Array.isArray(r._observerImages)) { sidebandImages = r._observerImages; delete r._observerImages; }
       if (typeof r._observerFrameProvider === "function") { frameProvider = r._observerFrameProvider; delete r._observerFrameProvider; }
+      if (typeof r._observerFrameCaption === "string") { frameCaption = r._observerFrameCaption; delete r._observerFrameCaption; }
     }
     if (frameProvider) {
-      setImmediate(() => {
-        try {
-          const img = frameProvider();
-          // re-resolve platform: a call like loadMedia sets it DURING the call, so
-          // the post-call value is the most accurate for the frame's system label.
-          let framePlatform = platform;
-          try { framePlatform = getHostOrNull(sessionKey)?.status?.platform ?? platform; } catch { /* keep */ }
-          if (img) observer.push({ type: "call_frame", sessionKey: sessionKey ?? "http", platform: framePlatform, ts: startedAt, tool: tool.name, images: [img] });
-        } catch { /* livestream is best-effort; never affects the caller */ }
-      });
+      // Throttled to one per 2s per (session, tool), trailing-edge — same
+      // policy as the MCP path (bus.js pushObserverFrame). Platform is
+      // re-resolved at emit time (loadMedia sets it DURING the call).
+      pushObserverFrame({
+        sessionKey, tool: tool.name, ts: startedAt, platform,
+        resolvePlatform: () => { try { return getHostOrNull(sessionKey)?.status?.platform ?? platform; } catch { return platform; } },
+        ...(frameCaption ? { caption: frameCaption } : {}),
+      }, frameProvider);
     }
     const inlineImages = extractImages(r);
     const images = inlineImages.length > 0 ? inlineImages : sidebandImages;

package/src/mcp/tools/cheats.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { readFile } from "node:fs/promises";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
+import { attachObserverFrame } from "./watch-memory.js";
 import { lookupCheats, searchCheatGames } from "../../cheats/lookup.js";
 import { encodeForDevice, nativeDevicesFor, decodeCode } from "../../cheats/gamegenie.js";
 
@@ -334,7 +335,7 @@ export function registerCheatTools(server, z, sessionKey) {
       switch (args.op) {
         case "lookup": return jsonContent(await cheatsLookupCore(args));
         case "search": return jsonContent(await cheatsSearchCore(args));
-        case "apply":  return jsonContent(await cheatsApplyCore(args, sessionKey));
+        case "apply":  return attachObserverFrame(jsonContent(await cheatsApplyCore(args, sessionKey)), getHost(sessionKey), "cheat applied");
         case "clear":  return jsonContent(await cheatsClearCore(args, sessionKey));
         case "make":   return jsonContent(await cheatsMakeCore(args));
         default: throw new Error(`cheats: unknown op '${args.op}'`);

package/src/mcp/tools/frame.js

@@ -249,12 +249,13 @@ export function registerFrameTools(server, z, sessionKey) {
       // actively playing in the playtest window means this step raced their
       // real-time loop. Field only appears when the conflict is real.
       const coDrive = humanCoDriveWarning(sessionKey);
-      return jsonContent({
+      // Livestream: the post-step frame (throttled to 1/2s per tool by the bus).
+      return attachObserverFrame(jsonContent({
         framesRun: n,
         frameCount: host.status.frameCount,
         framebuffer: { width: host.status.fbWidth, height: host.status.fbHeight },
         ...(coDrive ? { humanCoDriveWarning: coDrive } : {}),
-      });
+      }), host, `step ×${n}`);
   }
 
   // Contract: an image goes to disk (path) OR comes back inline (inline:true).

package/src/mcp/tools/index.js

@@ -87,7 +87,7 @@ const CATEGORIES = [
   {
     name: "platforms",
     description: "Discover supported platforms, their cores, toolchains, and language matrices.",
-    useWhen: ["scaffolding a new project", "checking which platforms are available", "looking up a platform's default language"],
+    useWhen: ["before forking an example for a new game", "checking which platforms are available", "looking up a platform's default language"],
     register: (s, z, k) => registerPlatformTools(s, z, k), // listPlatforms, resolvePlatform
   },
   {
@@ -138,8 +138,8 @@ const CATEGORIES = [
   },
   {
     name: "project",
-    description: "Project scaffolding + starter snippets per platform.",
-    useWhen: ["starting a new game from scratch", "looking up canonical patterns like NMI handler, OAM DMA, joypad read"],
+    description: "The example-game library (fork/list/show) + starter snippets per platform.",
+    useWhen: ["starting a new game (ALWAYS fork the nearest example — never a blank file)", "looking up canonical patterns like NMI handler, OAM DMA, joypad read"],
     register: (s, z, k) => { registerProjectTools(s, z, k); registerSnippetTools(s, z, k); registerPlatformDocsTools(s, z); },
   },
   {

package/src/mcp/tools/input.js

@@ -2,6 +2,7 @@ import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
 import { getInputLayoutCore } from "./input-layout.js";
 import { humanCoDriveWarning } from "./playtest.js";
+import { attachObserverFrame } from "./watch-memory.js";
 
 // Spreadable co-drive conflict marker for every input-driving op: while a
 // human is actively playing in this session's playtest window, their input
@@ -257,21 +258,21 @@ export function registerInputTools(server, z, sessionKey) {
       switch (args.op) {
         case "set": {
           if (!args.ports) throw new Error("input({op:'set'}): `ports` is required.");
-          return jsonContent(inputSetCore(args, sessionKey));
+          return attachObserverFrame(jsonContent(inputSetCore(args, sessionKey)), getHost(sessionKey), "input set");
         }
         case "press": {
           if (!args.button) throw new Error("input({op:'press'}): `button` is required.");
-          return jsonContent(inputPressCore(args, sessionKey));
+          return attachObserverFrame(jsonContent(inputPressCore(args, sessionKey)), getHost(sessionKey), `press ${args.button}`);
         }
         case "sequence": {
           if (!args.steps) throw new Error("input({op:'sequence'}): `steps` is required.");
-          return jsonContent(inputSequenceCore(args, sessionKey));
+          return attachObserverFrame(jsonContent(inputSequenceCore(args, sessionKey)), getHost(sessionKey), "input sequence");
         }
         case "navigate": {
           if (!args.steps) throw new Error("input({op:'navigate'}): `steps` is required.");
           // Fill per-step defaults the old navigate schema provided.
           const steps = args.steps.map((s) => ({ holdFrames: 2, maxWaitFrames: 120, settleFrames: 2, ...s }));
-          return jsonContent(inputNavigateCore({ steps }, sessionKey));
+          return attachObserverFrame(jsonContent(inputNavigateCore({ steps }, sessionKey)), getHost(sessionKey), "navigate");
         }
         case "layout": {
           if (!args.platform) throw new Error("input({op:'layout'}): `platform` is required.");

package/src/mcp/tools/lifecycle.js

@@ -2,6 +2,7 @@ import { resolveCore } from "../../cores/registry.js";
 import { clearHost, getHost, getHostOrNull, rememberLastMedia, resetHost } from "../state.js";
 import { jsonContent, safeTool, textContent } from "../util.js";
 import { resolveCheatCodeForApply } from "./cheats.js";
+import { attachObserverFrame } from "./watch-memory.js";
 
 const MEDIA_KINDS = ["cartridge", "disk", "tape", "program"];
 
@@ -58,7 +59,8 @@ export function registerLifecycleTools(server, z, sessionKey) {
     // on dimensions, so we omit it until a frame has been stepped and point the
     // caller at stepFrames instead.
     const framebufferKnown = host.status.frameCount > 0;
-    return jsonContent({
+    // Livestream: show what just loaded (the boot frame).
+    return attachObserverFrame(jsonContent({
       loaded: true,
       platform,
       core: resolved.coreName,
@@ -68,7 +70,7 @@ export function registerLifecycleTools(server, z, sessionKey) {
         ? { framebuffer: { width: host.status.fbWidth, height: host.status.fbHeight } }
         : { framebufferNote: "Framebuffer dimensions are unknown until the core runs — call stepFrames first, then getStatus (the pre-boot default does not match the real output resolution)." }),
       ...(appliedCheats ? { cheats: appliedCheats } : {}),
-    });
+    }), host, `loaded ${host.status.mediaPath ? host.status.mediaPath.split("/").pop() : platform}`);
   }
 
   server.tool(
@@ -125,10 +127,10 @@ export function registerLifecycleTools(server, z, sessionKey) {
           const host = getHost(sessionKey);
           if (hard) {
             const reloaded = await host.hardReset();
-            return textContent(reloaded ? "reset (hard / power-cycle — RAM cleared)" : "reset (soft — no cached ROM to reload for a hard reset)");
+            return attachObserverFrame(textContent(reloaded ? "reset (hard / power-cycle — RAM cleared)" : "reset (soft — no cached ROM to reload for a hard reset)"), host, "reset (hard)");
           }
           host.reset();
-          return textContent("reset (soft — RESET button; work RAM persists, use hard:true to clear it)");
+          return attachObserverFrame(textContent("reset (soft — RESET button; work RAM persists, use hard:true to clear it)"), host, "reset");
         }
         case "pause":
           getHost(sessionKey).pause();

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

@@ -69,7 +69,7 @@ export async function listPlatformDocsCore({ platform }) {
         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'}).)`
+          ? `No docs shipped for '${platform}' yet. Try a different platform, or fork an example game (examples({op:'fork'})) 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'}).`,
       };
 }

package/src/mcp/tools/preview-tile.js

@@ -409,7 +409,10 @@ export async function previewTileArtCore(args) {
 
   if (outputPath) {
     await writeFile(outputPath, png);
-    return { ...result, outputPath, note: `${png.length} bytes of PNG written to ${outputPath}.` };
+    // Livestream sideband: the human sees the rendered sheet even though the
+    // agent only gets the path.
+    return { ...result, outputPath, note: `${png.length} bytes of PNG written to ${outputPath}.`,
+      _observerImages: [{ kind: "image", mimeType: "image/png", base64: png.toString("base64") }] };
   }
   return { ...result, pngBase64: png.toString("base64") };
 }
@@ -467,7 +470,8 @@ async function previewMsxScreen2(args, d) {
   };
   if (outputPath) {
     await writeFile(outputPath, buf);
-    return { ...result, outputPath };
+    return { ...result, outputPath,
+      _observerImages: [{ kind: "image", mimeType: "image/png", base64: buf.toString("base64") }] };
   }
   return { ...result, pngBase64: buf.toString("base64") };
 }