romdevtools 0.43.0 → 0.56.1

package/src/mcp/tools/cheats.js

@@ -204,18 +204,38 @@ export async function cheatsApplyCore({ code, desc, path: romPath, index, enable
       const { code: codeToApply, appliedAs, reencodedFrom } = resolveCheatCodeForApply(rawCode, plat);
 
       const unencodable = appliedAs === "rom-unencodable";
-      const slot = index != null ? index : host.listActiveCheats().length;
+      // Slot selection: an explicit `index` wins. Otherwise, if an active cheat
+      // already targets the SAME address, REUSE its slot — applying `005C:03` over
+      // an active `005C:02` should REPLACE the freeze, not stack a second one that
+      // fights for the same byte (v0.41.0 feedback 213831 #3). Only append a new
+      // slot when nothing targets this address yet.
+      const newAddr = cheatAddress(codeToApply);
+      let replacedSlot = null;
+      let slot;
+      if (index != null) {
+        slot = index;
+      } else if (newAddr != null) {
+        const existing = host.listActiveCheats().find((c) => cheatAddress(c.code) === newAddr);
+        if (existing) { slot = existing.index; replacedSlot = existing.index; }
+        else slot = host.listActiveCheats().length;
+      } else {
+        slot = host.listActiveCheats().length;
+      }
       // Still install it (the raw poke may be what the user wants), but warn.
       host.setCheat(slot, codeToApply, enabled);
       return {
         applied: enabled,
         slot,
+        ...(replacedSlot != null ? { replacedSameAddress: true } : {}),
         code: codeToApply,
         appliedAs,
         ...(reencodedFrom ? { reencodedFrom } : {}),
         ...(resolvedDesc ? { desc: resolvedDesc } : {}),
         active: host.listActiveCheats(),
-        note: (reencodedFrom
+        note: (replacedSlot != null
+          ? `REPLACED the active cheat on the same address (slot ${replacedSlot}) — applying a new freeze on an address that already had one swaps it rather than stacking two that fight over the byte. To remove a single freeze without clearing the rest, use cheats({op:'remove', code|slot}). `
+          : "") +
+          (reencodedFrom
           ? `Raw code ${reencodedFrom} names a ROM address — re-encoded to the native ROM-patch device (${codeToApply}) so the core installs a read-intercept (a raw ADDR:VAL on a ROM address is treated as a RAM poke and would silently no-op). `
           : unencodable
           ? `WARNING: this raw code names a ROM address but couldn't be re-encoded to a ROM-patch code (a ROM patch needs a COMPARE byte — pass ADDR:VAL:COMPARE). As applied it's a RAM poke and will likely NO-OP on this read-only ROM address. Read the current byte and supply it as the compare, or use makeCheat. `
@@ -226,6 +246,53 @@ export async function cheatsApplyCore({ code, desc, path: romPath, index, enable
       };
 }
 
+/** The CPU/RAM address a cheat code targets, or null if undecodable. Used to
+ *  detect same-address freezes (replace, not stack) + for op:'remove' by code. */
+function cheatAddress(code) {
+  if (typeof code !== "string") return null;
+  // raw ADDR:VAL[:COMPARE] — the address is the first field.
+  if (code.includes(":")) {
+    const a = parseInt(code.split(":")[0], 16);
+    return Number.isNaN(a) ? null : (a & 0xffff);
+  }
+  // a device code (Game Genie / PAR / GameShark) — decode it platform-agnostically.
+  try {
+    const d = decodeCode(code, null);
+    return d && d.address != null ? (d.address & 0xffff) : null;
+  } catch { return null; }
+}
+
+/** op:'remove' — disable ONE active cheat (by slot index or by code/address),
+ *  leaving the rest in place. The single-slot complement to op:'clear' (nuke-all).
+ *  v0.41.0 feedback 213831 #3. */
+export async function cheatsRemoveCore({ slot, code }, sessionKey) {
+      const host = getHost(sessionKey);
+      if (!host.listActiveCheats) return { removed: false, reason: "no cheat interface on this core", active: [] };
+      const active = host.listActiveCheats();
+      let target = null;
+      if (slot != null) {
+        target = active.find((c) => c.index === slot);
+      } else if (code != null) {
+        // match by exact code OR by the address the code targets (so a user can
+        // remove '005C:02' by passing '005C:03', '$5C', or the device code).
+        const addr = cheatAddress(code);
+        target = active.find((c) => c.code === code) || (addr != null ? active.find((c) => cheatAddress(c.code) === addr) : null);
+      } else {
+        throw new Error("cheats({op:'remove'}): provide `slot` (index) or `code` (the cheat to remove).");
+      }
+      if (!target) {
+        return { removed: false, reason: `no active cheat matching ${slot != null ? `slot ${slot}` : `code '${code}'`}`, active };
+      }
+      host.setCheat(target.index, target.code, false); // disable that slot only
+      return {
+        removed: true,
+        slot: target.index,
+        code: target.code,
+        active: host.listActiveCheats(),
+        note: "Disabled that one cheat (volatile); the rest stay active. Use op:'clear' to remove ALL, op:'apply' to add/swap.",
+      };
+}
+
 /** op:'clear' — remove ALL active cheats (volatile core-side reset). */
 export async function cheatsClearCore(_args, sessionKey) {
       const host = getHost(sessionKey);
@@ -319,7 +386,7 @@ export function registerCheatTools(server, z, sessionKey) {
     "round-trip `verified`. RAM cheat = address+value; ROM/code cheat = also `compare` (the byte currently there — " +
     "read it first).",
     {
-      op: z.enum(["lookup", "search", "apply", "clear", "make"]).describe("lookup THIS game's DB cheats; search the DB by game name; apply a cheat live; clear all cheats; make a new code."),
+      op: z.enum(["lookup", "search", "apply", "remove", "clear", "make"]).describe("lookup THIS game's DB cheats; search the DB by game name; apply a cheat live (replaces an active cheat on the SAME address); remove ONE active cheat (by slot/code); clear ALL cheats; make a new code."),
       // lookup
       path: z.string().optional().describe("op=lookup/apply(+desc): absolute ROM path. lookup sniffs platform+name from it."),
       filter: z.string().optional().describe("op=lookup: case-insensitive substring filter on cheat descriptions."),
@@ -330,8 +397,9 @@ export function registerCheatTools(server, z, sessionKey) {
       // apply
       code: z.string().optional().describe("op=apply: raw cheat code (ADDR:VAL or a Game Genie code). Provide code OR desc."),
       desc: z.string().optional().describe("op=apply: description of a matched cheat (requires `path`). First substring match is applied."),
-      index: z.number().int().min(0).optional().describe("op=apply: cheat slot (default: next free slot). Reuse a slot to replace it."),
+      index: z.number().int().min(0).optional().describe("op=apply: cheat slot (default: reuse the slot of an active cheat on the same address, else next free). Reuse a slot to replace it."),
       enabled: z.boolean().default(true).describe("op=apply: false disables the slot instead of enabling."),
+      slot: z.number().int().min(0).optional().describe("op=remove: the active-cheat slot to disable (from apply's `slot` / active[].index). Provide slot OR code."),
       // make / search / lookup share `platform`
       platform: z.enum([...MAKE_CHEAT_PLATFORMS]).optional().describe("op=lookup: override platform detection. op=search: OPTIONAL — omit to search ALL platforms (each match returns its own `platform`); pass one only to scope the search. op=make: REQUIRED — the target platform (all 14 tier-1)."),
       address: z.number().int().min(0).optional().describe("op=make: address to cheat (RAM addr, or the ROM addr to patch)."),
@@ -345,6 +413,7 @@ export function registerCheatTools(server, z, sessionKey) {
         case "lookup": return jsonContent(await cheatsLookupCore(args));
         case "search": return jsonContent(await cheatsSearchCore(args));
         case "apply":  return attachObserverFrame(jsonContent(await cheatsApplyCore(args, sessionKey)), getHost(sessionKey), "cheat applied");
+        case "remove": return jsonContent(await cheatsRemoveCore(args, sessionKey));
         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/disasm.js

@@ -1609,6 +1609,8 @@ function sniffPlatformFromPath(p) {
   if (/\.prg$/i.test(p)) return "c64";
   if (/\.(lnx|lyx)$/i.test(p)) return "lynx";
   if (/\.gba$/i.test(p)) return "gba";
+  if (/\.(z64|n64|v64)$/i.test(p)) return "n64";
+  if (/\.(psexe|psx)$/i.test(p)) return "ps1"; // .exe/.bin are ambiguous — pass platform explicitly
   if (/\.(gen|md|bin)$/i.test(p)) return "genesis";
   return null;
 }

package/src/mcp/tools/frame.js

@@ -389,10 +389,14 @@ export function registerFrameTools(server, z, sessionKey) {
   async function shootAscii({ cols, rows, symbols, colors, path: outPath, inline }) {
     const host = getHost(sessionKey);
     const { width, height, rgba } = host.screenshotRgba();
-    // Default each cell to "2 game tiles" (8×8 platforms) so the grid maps
-    // to tile coords: cell (c,r) covers tiles (c*2..c*2+1, r*2..r*2+1).
-    if (cols == null) cols = Math.max(4, Math.floor(width / 16));
-    if (rows == null) rows = Math.max(4, Math.floor(height / 16));
+    // Default to ONE cell per 8×8 tile (so a 256×224 NES frame → 32×28, legible
+    // game state). The old /16 default (16×14 for NES) was too coarse to read
+    // anything — feedback 0.44.0 #1. The terminal symbol's own subcell shape adds
+    // detail back, so this stays cheap.
+    if (cols == null) cols = Math.max(8, Math.floor(width / 8));
+    if (rows == null) rows = Math.max(8, Math.floor(height / 8));
+    // Warn when the caller forced a grid so coarse it can't show game state.
+    const tooCoarse = cols < Math.floor(width / 8) / 2 || rows < Math.floor(height / 8) / 2;
     const { renderRgbaToAnsi } = await import("../../host/chafa-render.js");
     const ansi = await renderRgbaToAnsi(rgba, width, height, { cols, rows, symbols, colors });
     // Livestream sidebands: the human sees BOTH the real PNG and the ANSI.
@@ -401,15 +405,20 @@ export function registerFrameTools(server, z, sessionKey) {
       _observerImages: [{ kind: "image", mimeType: "image/png", base64: shot.pngBase64 }],
       _observerAnsi: ansi,
     };
+    const coarseNote = tooCoarse
+      ? `NOTE: ${cols}x${rows} is too coarse to read game state from this ${width}x${height} frame. `
+        + `For a pass/fail check ("are we in gameplay?"), a memory({op:'read'}) byte assertion is cheaper and exact — `
+        + `ascii is for a rough visual, not state.`
+      : null;
     let result;
     if (!inline) {
       await writeFile(outPath, ansi, "utf-8");
-      result = jsonContent({ path: outPath, framebuffer: { width, height }, terminal: { cols, rows, symbols, colors }, ansiBytes: Buffer.byteLength(ansi, "utf-8") });
+      result = jsonContent({ path: outPath, framebuffer: { width, height }, terminal: { cols, rows, symbols, colors }, ansiBytes: Buffer.byteLength(ansi, "utf-8"), ...(coarseNote ? { note: coarseNote } : {}) });
     } else {
       result = {
         content: [
           { type: "text", text: ansi },
-          { type: "text", text: `framebuffer ${width}x${height} → terminal ${cols}x${rows} (${symbols}/${colors}, ${Buffer.byteLength(ansi, "utf-8")}B)` },
+          { type: "text", text: `framebuffer ${width}x${height} → terminal ${cols}x${rows} (${symbols}/${colors}, ${Buffer.byteLength(ansi, "utf-8")}B)` + (coarseNote ? `\n${coarseNote}` : "") },
         ],
       };
     }
@@ -857,10 +866,10 @@ export function registerFrameTools(server, z, sessionKey) {
       inline: z.boolean().default(false).describe("op=screenshot/stepAndShot: return the image in the response instead of writing to disk."),
       overlayBoxes: z.boolean().default(false).describe("op=screenshot png: draw a colored bounding box per visible sprite (SNES+NES only)."),
       scale: z.number().gt(0).max(16).refine((s) => s <= 1 || Number.isInteger(s), { message: "scale must be 0<scale≤1 (downscale) or an integer ≥2 (upscale)" }).optional().describe("op=screenshot png: nearest-neighbor resample factor. DEFAULT (unset/1) = NATIVE resolution — perfect pixels, the accurate representation; use this. 0<scale<1 DOWNscales (0.5 ≈ 75% fewer image tokens — useful for cheap 'did it change?' checks). integer scale≥2 UPscales by pixel-duplication (e.g. scale:4 → GB 160x144 → 640x576): it adds NO information (same pixels enlarged), costs MORE image tokens, and since VLM encoders resize to their own fixed resolution it may not change what the model sees and can slightly degrade it. Only for clients that render tiny images too small to use and can't zoom."),
-      cols: z.number().int().min(4).max(640).optional().describe("op=screenshot ascii: terminal columns (default fb_width/16)."),
-      rows: z.number().int().min(4).max(480).optional().describe("op=screenshot ascii: terminal rows (default fb_height/16)."),
+      cols: z.number().int().min(4).max(640).optional().describe("op=screenshot ascii: terminal columns (default fb_width/8 — one cell per 8×8 tile, legible game state)."),
+      rows: z.number().int().min(4).max(480).optional().describe("op=screenshot ascii: terminal rows (default fb_height/8)."),
       symbols: z.enum(["ascii", "halfblock", "block", "quad", "sextant"]).default("ascii").describe("op=screenshot ascii: chafa symbol set."),
-      colors: z.enum(["true", "256", "16", "fgbg"]).default("true").describe("op=screenshot ascii: color depth."),
+      colors: z.enum(["true", "256", "16", "fgbg"]).default("256").describe("op=screenshot ascii: color depth. Default '256' (indexed) — far fewer ANSI escape bytes than 'true' (truecolor per cell) for a near-identical read. Use 'true' only when exact color matters."),
     },
     safeTool(async (args) => {
       switch (args.op) {

package/src/mcp/tools/index.js

@@ -59,6 +59,7 @@ import { createDisclosure } from "../disclosure.js";
 import { jsonContent, safeTool, withClearToolErrors } from "../util.js";
 import { getHostOrNull, setDisclosure } from "../state.js";
 import { da65Available } from "../../toolchains/cc65/da65.js";
+import { cc65Available } from "../../toolchains/cc65/cc65.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -75,7 +76,16 @@ import { dirname, join } from "node:path";
  */
 function hostCapabilities(host) {
   const da65 = da65Available();
-  if (!host) return { da65Toolchain: da65 };
+  const cc65 = cc65Available();
+  // Toolchain caps don't need a loaded host — report them either way so an agent
+  // can check build/disasm availability before loading a ROM.
+  const toolchains = {
+    da65Disasm: da65,    // disasm({target:'rom'/'references'/'cfg'/'xrefs'/'functions'/'decompile'}) — all da65-backed
+    cc65Build: cc65,     // build({platform:'nes'/'c64'/'atari7800'/'lynx'}) — cc65/ca65
+    ld65Link: cc65,      // the ld65 linker (ships with cc65 in the same package)
+    da65Toolchain: da65, // legacy alias for da65Disasm (kept for back-compat)
+  };
+  if (!host) return toolchains;
   const has = (m) => { try { return !!host[m]?.(); } catch { return false; } };
   return {
     pcBreakpoint: has("pcBreakSupported"),       // breakpoint({on:'pc'})
@@ -87,7 +97,7 @@ function hostCapabilities(host) {
     cheats: has("cheatsSupported"),              // cheats({op:'apply'}) via retro_cheat_set
     diskImage: has("diskImageSupported"),        // C64 .d64 loadMedia
     keyboard: has("keyboardSupported"),          // keyboard input (C64/MSX)
-    da65Toolchain: da65,                         // disasm({target:'rom'/'references'/...})
+    ...toolchains,
   };
 }
 

package/src/mcp/tools/lifecycle.js

@@ -21,7 +21,7 @@ export function registerLifecycleTools(server, z, sessionKey) {
     if (path && base64) throw new Error("loadMedia: provide `path` OR `base64`, not both.");
     const slotB = slot === "b";
     const host = slotB ? resetHostB(sessionKey) : resetHost(sessionKey);
-    await host.loadCore(resolved.jsPath, resolved.wasmPath);
+    await host.loadCore(resolved.jsPath, resolved.wasmPath, { hwRender: resolved.hwRender });
     const bytes = base64 ? new Uint8Array(Buffer.from(base64, "base64")) : undefined;
     await host.loadMedia({
       platform,

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

@@ -6,6 +6,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { PNG } from "pngjs";
 import { getHost } from "../state.js";
+import { naReason } from "../../cores/capabilities.js";
 import { imageContent, jsonContent, unsupported } from "../util.js";
 
 // Consolidation: several handlers in this big shared file are extracted as
@@ -39,6 +40,8 @@ import { decodeGbApu, decodeGbaApu } from "../../host/gb-apu-state.js";
 import { decodeC64Sid } from "../../host/c64-sid-state.js";
 import { decodeLynxMikey, decodeLynxPalette } from "../../host/lynx-mikey-state.js";
 import { getPcePsgState } from "../../host/pce-psg-state.js";
+import { decodePs1Spu } from "../../host/ps1-spu-state.js";
+import { decodeN64Ai } from "../../host/n64-ai-state.js";
 import { getMsxAyState } from "../../host/msx-ay-state.js";
 import { decodeGbaSprites, decodeGbaPalette } from "../../host/gba-video-state.js";
 
@@ -339,7 +342,7 @@ export function registerPlatformTools(server, z, sessionKey) {
       }
 
       unsupported(p, "inspectPalette", {
-        reason: "no palette decoder for this platform",
+        reason: naReason(p, "inspectPalette") ?? "no palette decoder for this platform",
         alternative: "platform({op:'capabilities'}) to see what's wired",
       });
   };
@@ -424,7 +427,20 @@ export function registerPlatformTools(server, z, sessionKey) {
       if (!ay) throw new Error("getAudioState chip:'ay8910' — no PSG region (load an MSX ROM into the patched blueMSX core).");
       return { platform: "msx", ...ay };
     }
-    throw new Error(`getAudioState: unknown chip '${chip}'. Use 'nes' (NES 2A03), 'gb' (Game Boy/GBC), 'gba' (GBA), 'dsp' (SNES), 'psg' (Genesis/SMS/GG SN76489), 'ym2612' (Genesis FM), 'sid' (C64), or 'mikey' (Lynx).`);
+    if (chip === "spu") {
+      // PS1 SPU — 24 ADPCM voices (volume/pitch/ADSR + key-on/off).
+      const regs = host.getSpuRegs?.();
+      if (!regs) throw new Error("getAudioState chip:'spu' — no SPU region (load a PS1 program into the rebuilt pcsx_rearmed core).");
+      return { platform: "ps1", ...decodePs1Spu(regs) };
+    }
+    if (chip === "ai") {
+      // N64 AI — the audio OUTPUT state (sample rate + playing + DMA source). N64
+      // audio is RSP-mixed, so there are no per-voice registers to decode.
+      const regs = host.getAiRegs?.();
+      if (!regs) throw new Error("getAudioState chip:'ai' — no AI region (load an N64 ROM into the rebuilt parallel_n64 core).");
+      return { platform: "n64", ...decodeN64Ai(regs) };
+    }
+    throw new Error(`getAudioState: unknown chip '${chip}'. Use 'nes' (NES 2A03), 'gb' (Game Boy/GBC), 'gba' (GBA), 'dsp' (SNES), 'psg' (Genesis/SMS/GG SN76489), 'ym2612' (Genesis FM), 'sid' (C64), 'mikey' (Lynx), 'pce', 'ay8910' (MSX), or 'spu' (PS1).`);
   }
 
   getAudioStateCore = async ({ chip }, callerSessionKey) => jsonContent(readAudioChip(chip, callerSessionKey));
@@ -701,7 +717,7 @@ export function registerPlatformTools(server, z, sessionKey) {
       }
 
       unsupported(p, "inspectSprites", {
-        reason: "no sprite decoder for this platform",
+        reason: naReason(p, "inspectSprites") ?? "no sprite decoder for this platform",
         alternative: "memory({op:'read'}) the raw OAM/sprite-attribute region, or platform({op:'capabilities'}) to see what's wired",
       });
   };
@@ -813,7 +829,7 @@ export function registerPlatformTools(server, z, sessionKey) {
         return emitImage(r.png, `SNES BG map composite (${r.width}×${r.height}, ${r.mapWidth}×${r.mapHeight} tiles, ${r.bpp}bpp, tilemap@0x${tilemapBaseByte.toString(16)}, tiles@0x${tileBaseByte.toString(16)}). ${r.note}`);
       }
       unsupported(p, "inspectBackground", {
-        reason: "no background-map snapshotter for this platform",
+        reason: naReason(p, "inspectBackground") ?? "no background-map snapshotter for this platform",
         alternative: "background({view:'renderState'}) for the register-level context, or memory({op:'read'}) the raw VRAM/nametable region",
       });
   };

package/src/mcp/tools/platforms.js

@@ -2,7 +2,7 @@ import { CORES, listAvailableCores, resolveCore } from "../../cores/registry.js"
 import { TOOLCHAINS } from "../../toolchains/registry.js";
 import { getLanguageOptions } from "../../toolchains/index.js";
 import { jsonContent, safeTool } from "../util.js";
-import { CAPABILITIES, CONTRACT_PLATFORMS, capabilitiesFor } from "../../cores/capabilities.js";
+import { CAPABILITIES, capabilitiesFor, OP_KEYS, naReason } from "../../cores/capabilities.js";
 import { listToolchainsCore, installToolchainCore } from "./toolchain.js";
 import { listPlatformDocsCore, getPlatformDocCore } from "./platform-docs.js";
 
@@ -66,6 +66,30 @@ const PLATFORM_QUIRKS = {
     ],
     starterSnippets: ["hello_msx.c", "msx_crt0.s"],
   },
+  ps1: {
+    multiBank: false,
+    maxRomBytesPerBank: 0, // disc/EXE based, not a fixed cart
+    headerLocation: "PS-EXE: 'PS-X EXE' magic at 0, entry (pc0) at +0x10, load addr (t_addr) at +0x18; 2048-byte header then code",
+    notes: [
+      "32-bit MIPS R3000 (little-endian), framebuffer GPU. Runs via PCSX-ReARMed with its BUILT-IN HLE BIOS — no firmware file needed, software-rendered. Load a .exe (PS-EXE), or a disc image if you have one.",
+      "WORKS NOW: build (buildSource language:'c' → mips-elf-gcc → a PS-EXE the HLE BIOS runs; write GPU/SPU registers directly, no SDK yet), run, frame({op:'screenshot'}), cpu({op:'read'}) (live R3000 registers), cheats, readMemory/writeMemory (system_ram = 2MB main RAM), disasm + decompile (Ghidra MIPS C), the live-debug tools breakpoint({on:'pc'/'write'/'read'}) + watch({on:'range'}), AND getAudioState({chip:'spu'}) (24-voice SPU). MIPS is little-endian here.",
+      "The bare build path: a minimal crt0 sets the stack + clears .bss + calls main(); code loads at 0x80010000. No PSn00bSDK runtime yet — drive the GPU at ports 0x1F801810/0x1F801814. The framebuffer renderer has no tile/sprite inspectors — use screenshot + memory.",
+      "For higher fidelity (GL hardware renderer) a real PS1 BIOS + the beetle_psx_hw core is the alternative, but the HLE pcsx_rearmed path ships clean with zero firmware.",
+    ],
+    starterSnippets: [],
+  },
+  n64: {
+    multiBank: false,
+    maxRomBytesPerBank: 0,
+    headerLocation: ".z64 (big-endian) magic 80 37 12 40 at 0; entry point (big-endian word) at +0x08; 0x1000-byte IPL3 bootcode then game code. .v64/.n64 byte orders are auto-normalized.",
+    notes: [
+      "32-bit MIPS R4300 (big-endian), 3D RDP/RSP. Runs via ParaLLEl-N64 with the glide64 GL renderer — HW-rendered through the OPTIONAL native GL stack (native-gles + webgl-node). Those are optionalDependencies: install them for N64; the other platforms don't need them.",
+      "WORKS NOW: build (buildSource language:'c' → mips-elf-gcc → a big-endian MIPS image; bare crt0, no libdragon yet so it's logic-only for now), run, frame({op:'screenshot'}) (real 3D frames, headless via FBO readback), cpu({op:'read'}) (live R4300 registers), cheats, readMemory/writeMemory (system_ram = 8MB RDRAM, 0x80xxxxxx maps to offset 0), disasm + decompile (Ghidra MIPS C), breakpoint + watch (live-debug instrumentation), AND getAudioState({chip:'ai'}) (audio output: sample rate + playing). MIPS is big-endian here.",
+      "build caveat: a fully BOOTABLE N64 ROM needs the IPL3 bootcode + a libdragon-style header (libdragon SDK forthcoming). The bare build compiles+links your C to a flat image — great for logic/RE, not yet a self-booting cart. 3D renderer has no tile/sprite inspectors — use screenshot + memory.",
+      "If frame() errors with an install hint, the optional GL module isn't installed: `npm install native-gles webgl-node`.",
+    ],
+    starterSnippets: [],
+  },
 };
 
 /** op:'list' — every platform with core/toolchains/languages/quirks. */
@@ -129,10 +153,20 @@ export function registerPlatformTools(server, z) {
         case "capabilities": {
           if (args.platform) {
             const cap = capabilitiesFor(args.platform);
-            if (!cap) throw new Error(`platform({op:'capabilities'}): unknown platform '${args.platform}'. Known: ${CONTRACT_PLATFORMS.join(", ")}.`);
-            return jsonContent({ platform: args.platform, ...cap });
+            if (!cap) throw new Error(`platform({op:'capabilities'}): unknown platform '${args.platform}'. Known: ${Object.keys(CAPABILITIES).join(", ")}.`);
+            // Call out WHY each unsupported op is N/A by hardware (a framebuffer/3D
+            // renderer has no tile/sprite tables; a disc system has no cart) so an
+            // agent reading the manifest sees "can't, because hardware" — not a
+            // bare `false` it might mistake for "not built yet".
+            const naReasons = {};
+            for (const op of OP_KEYS) {
+              if (!cap.ops[op]) { const r = naReason(args.platform, op); if (r) naReasons[op] = r; }
+            }
+            return jsonContent({ platform: args.platform, ...cap, ...(Object.keys(naReasons).length ? { naReasons } : {}) });
           }
-          return jsonContent({ platforms: CONTRACT_PLATFORMS, capabilities: CAPABILITIES });
+          // All platforms incl. the partial MIPS tier (ps1/n64) — so an agent can
+          // discover their capability map and see which ops are live vs not-yet.
+          return jsonContent({ platforms: Object.keys(CAPABILITIES), capabilities: CAPABILITIES });
         }
         case "resolve": {
           if (!args.platform) throw new Error("platform({op:'resolve'}): `platform` is required.");

package/src/mcp/tools/project.js

@@ -546,6 +546,106 @@ const TEMPLATES = {
       },
     };
   })(),
+
+  // ── PlayStation (mips-elf-gcc R3000) — software 3D engine helper lib + examples ──
+  // The PS1 is a 3D machine: the helper lib (psx.{h,c}) is a real software 3D
+  // pipeline (fixed-point transform + perspective + cull). 4 examples are 3D; the
+  // puzzle is 2D (a flat grid is the right idiom even on 3D hardware).
+  ps1: (() => {
+    const PS1_RUNTIME = [
+      { src: "lib/c/psx.h", dst: "psx.h" },
+      { src: "lib/c/psx.c", dst: "psx.c" },
+    ];
+    const mk = (name, describe) => ({ main: `${name}/main.c`, runtime: PS1_RUNTIME, lang: "C (mips-elf-gcc)", ext: ".exe", describe });
+    return {
+      default: mk("shmup", "STARFALL — the canonical PS1 3D starter: a vertical shooter where enemies fly in from depth and grow under perspective projection. Exercises the whole 3D helper lib (camera, model transform, culled cubes) + SIO pad + HUD. Same as 'shmup'."),
+      shmup: {
+        ...mk("shmup", "STARFALL — a 3D PlayStation vertical shooter. The playfield recedes into the screen; enemy cubes fly in from the far distance and scale up under perspective as they approach. Stream bullets into Z, AABB collision, xorshift wave spawner, parallax starfield, title/play/game-over with score + lives. Built on the software 3D pipeline (psx_camera/psx_model/psx_quad3d, 16.16 fixed point)."),
+        players: "1 (PS1 has two pad ports; a 2P round can hook port 2 later)",
+        sram: "none in this starter — PS1 saves go to a Memory Card via the BIOS; the helper lib keeps hi-score in-session (stated in-file).",
+        mechanics: ["3D perspective playfield", "depth-scaled enemies", "projectile pools", "wave spawner", "AABB collision", "lives + score", "title/play/game-over state machine"],
+        techniques: ["software 3D: fixed-point camera + model transform", "perspective projection + back-face cull", "GPU flat-shaded quads (GP0 0x20/0x60)", "SIO controller polling", "blocky HUD number font"],
+      },
+      racing: {
+        ...mk("racing", "POLE BENDER — a 3D PlayStation racer. The road is a ribbon of perspective quads receding to the horizon and bending with a sine curve; you steer a car between the verges as the world scrolls toward you, rival cubes growing as you close on them. The PS1 signature: a real 3D track, not pseudo-3D scaling. Distance score, collision spin-out, title/race/results."),
+        players: "1",
+        sram: "none (in-session best time/score; Memory Card path is the real-hardware save).",
+        mechanics: ["3D curved road (perspective quads)", "throttle/brake/steer physics", "rival traffic + collision", "distance scoring", "title/race/results state machine"],
+        techniques: ["receding road segments with depth-driven centerline curve", "no-cull ground-plane quads (psx_quad3d_nc)", "chase camera with downward tilt", "16.16 fixed-point world scroll"],
+      },
+      platformer: {
+        ...mk("platformer", "BLOCK HOP — a 3D PlayStation platformer. A cube hero runs and jumps across floating platforms drawn in perspective; gravity + jump physics in 16.16 fixed point, AABB landing on platform tops, coins to collect, a lethal pit, a chase camera that follows the hero. Title/play/game-over, score + lives."),
+        players: "1",
+        sram: "none (in-session hi-score; Memory Card is the real save path).",
+        mechanics: ["gravity + jump physics", "platform-top AABB landing", "coin pickups", "lethal pit + lives", "follow camera", "title/play/game-over"],
+        techniques: ["3D platforms as no-cull flat-topped boxes", "culled hero/coin cubes", "smooth-follow camera (psx_camera per frame)", "fixed-point physics"],
+      },
+      sports: {
+        ...mk("sports", "SLAM COURT — a 3D PlayStation sports game (air-hockey / pong). A perspective court seen down its length; you control the near paddle, the CPU the far one, and the ball bounces in 3D (X across, Z into the screen), its size changing with depth. First to 7. Title/match/game-over."),
+        players: "1 (vs CPU; a 2P split-paddle round can hook port 2 later)",
+        sram: "none (match score is in-session).",
+        mechanics: ["3D ball physics (X/Z)", "player + CPU paddles", "wall bounces + scoring", "tracking CPU AI", "first-to-7 match", "title/match/game-over"],
+        techniques: ["perspective court floor (no-cull quad)", "depth-scaled ball", "paddle/ball cubes at world positions", "capped CPU tracking"],
+      },
+      puzzle: {
+        ...mk("puzzle", "DROP GRID — the one 2D game in the PS1 set (a flat grid is the right idiom even on 3D hardware). A falling-block puzzle: colored blocks drop down a well, full rows clear and score, speed ramps up, stack the top = game over. Drawn with the GPU's 2D rectangle primitive. Title/play/game-over."),
+        players: "1",
+        sram: "none (in-session hi-score).",
+        mechanics: ["integer grid model", "falling block move/drop", "full-row clear + scoring", "ramping fall speed", "stack-out game over", "title/play/game-over"],
+        techniques: ["2D GPU rectangles (GP0 0x60 variable-size rect)", "integer board logic (no 3D needed)", "SIO pad edge detection", "row-shift clear"],
+      },
+    };
+  })(),
+
+  // ── Nintendo 64 (mips-elf-gcc R4300) — software 3D engine helper lib + examples ──
+  // The N64 was a 3D-first machine, so ALL 5 examples are 3D (even the puzzle —
+  // rendered as a 3D well of cubes). Same software-3D lib as PS1 (n64.{h,c}), a
+  // framebuffer backend the headless-angrylion core scans out.
+  n64: (() => {
+    const N64_RUNTIME = [
+      { src: "lib/c/n64.h", dst: "n64.h" },
+      { src: "lib/c/n64.c", dst: "n64.c" },
+    ];
+    const mk = (name, describe) => ({ main: `${name}/main.c`, runtime: N64_RUNTIME, lang: "C (mips-elf-gcc)", ext: ".z64", describe });
+    return {
+      default: mk("shmup", "STARFALL 64 — the canonical N64 3D starter: a vertical shooter where enemies fly in from depth and scale up under perspective. Exercises the whole software-3D lib (camera, transform, culled cubes) + SI/PIF pad + HUD, presented through angrylion's VI scanout. Same as 'shmup'."),
+      shmup: {
+        ...mk("shmup", "STARFALL 64 — a 3D Nintendo 64 vertical shooter (the N64 twin of the PS1 STARFALL). Enemy cubes fly in from the far distance and grow under perspective; stream bullets into Z, AABB collision, xorshift wave spawner, starfield, title/play/game-over with score + lives. Software 3D pipeline (n64_camera/n64_model/n64_quad3d) rendered to an RDRAM framebuffer the headless-angrylion core scans out."),
+        players: "1 (N64 has 4 controller ports; 2-4P can hook the other ports later)",
+        sram: "none in this starter — N64 saves go to Controller Pak / EEPROM / SRAM via the PI; the lib keeps hi-score in-session (stated in-file).",
+        mechanics: ["3D perspective playfield", "depth-scaled enemies", "projectile pools", "wave spawner", "AABB collision", "lives + score", "title/play/game-over state machine"],
+        techniques: ["software 3D: fixed-point camera + model transform", "perspective projection + back-face cull", "software triangle rasterizer → RDRAM framebuffer", "VI scanout (correct VI register setup)", "SI/PIF controller poll"],
+      },
+      racing: {
+        ...mk("racing", "POLE BENDER 64 — a 3D Nintendo 64 racer. A perspective road ribbon recedes to the horizon and bends with a sine curve; steer between the verges as the world scrolls toward you, rival cubes growing as you close. Distance score, collision spin-out, title/race/results. The N64's 3D heritage on display."),
+        players: "1",
+        sram: "none (in-session best; Controller Pak/EEPROM is the real-hardware save).",
+        mechanics: ["3D curved road (perspective quads)", "throttle/brake/steer", "rival traffic + collision", "distance scoring", "title/race/results"],
+        techniques: ["receding road segments with depth-driven curve", "no-cull ground-plane quads", "chase camera", "16.16 fixed-point world scroll"],
+      },
+      platformer: {
+        ...mk("platformer", "BLOCK HOP 64 — a 3D Nintendo 64 platformer. A cube hero runs and jumps across floating platforms in perspective; gravity + jump physics (16.16 fixed point), AABB landing on platform tops, coins, a lethal pit, a follow camera. Title/play/game-over, score + lives."),
+        players: "1",
+        sram: "none (in-session hi-score).",
+        mechanics: ["gravity + jump physics", "platform-top AABB landing", "coin pickups", "lethal pit + lives", "follow camera", "title/play/game-over"],
+        techniques: ["3D platforms as flat-topped boxes", "culled hero/coin cubes", "smooth-follow camera", "fixed-point physics"],
+      },
+      sports: {
+        ...mk("sports", "SLAM COURT 64 — a 3D Nintendo 64 sports game (air-hockey / pong). A perspective court down its length; you control the near paddle, the CPU the far, the ball bounces in 3D (X across, Z into the screen) and scales with depth. First to 7. Title/match/game-over."),
+        players: "1 (vs CPU; the N64's extra ports can host 2-4P later)",
+        sram: "none (match score is in-session).",
+        mechanics: ["3D ball physics (X/Z)", "player + CPU paddles", "wall bounces + scoring", "tracking CPU AI", "first-to-7", "title/match/game-over"],
+        techniques: ["perspective court floor (no-cull quad)", "depth-scaled ball", "paddle/ball cubes", "capped CPU tracking"],
+      },
+      puzzle: {
+        ...mk("puzzle", "DROP GRID 64 — a 3D Nintendo 64 falling-block puzzle. Unlike the flat-2D PS1 puzzle, this is rendered in 3D (the N64 was a 3D-first machine): the well is a perspective box of cube walls and the blocks are shaded cubes you watch fall in depth. Move/drop, full-row clear + scoring, ramping speed, stack-out = game over. Title/play/game-over."),
+        players: "1",
+        sram: "none (in-session hi-score).",
+        mechanics: ["integer grid model", "falling block move/drop", "full-row clear + scoring", "ramping fall speed", "stack-out game over", "title/play/game-over"],
+        techniques: ["3D-rendered well (cube walls + floor)", "blocks as shaded 3D cubes", "tilted camera into the well", "integer board logic", "SI/PIF pad edge detection"],
+      },
+    };
+  })(),
 };
 // 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/mcp/tools/rendering-context.js

@@ -10,6 +10,7 @@
 import { readFileSync } from "node:fs";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool, unsupported } from "../util.js";
+import { naReason } from "../../cores/capabilities.js";
 import { inspectBackgroundMapCore } from "./platform-tools.js";
 import { whichTilesAreRenderedCore } from "./which-tiles.js";
 
@@ -533,7 +534,7 @@ export async function getRenderingContextCore({ platform, area = "all", sessionK
     case "msx":   return msxContext(host, area);
     default:
       unsupported(p, "renderingContext", {
-        reason: "no rendering-context decoder for this platform",
+        reason: naReason(p, "renderingContext") ?? "no rendering-context decoder for this platform",
         alternative: "platform({op:'capabilities'}) to see what's wired",
       });
   }

package/src/mcp/tools/toolchain.js

@@ -603,7 +603,7 @@ export function registerToolchainTools(server, z, sessionKey) {
       }
 
       const host = resetHost(sessionKey);
-      await host.loadCore(resolved.jsPath, resolved.wasmPath);
+      await host.loadCore(resolved.jsPath, resolved.wasmPath, { hwRender: resolved.hwRender });
       // Pass projectName as a virtualName so the playtest window titles itself
       // with the game name (the SDL window reads host.status.mediaPath). Keep
       // a platform-correct extension so shared cores still resolve the system.