romdevtools 0.44.0 → 0.70.0

package/src/host/retroConstants.js

@@ -70,3 +70,17 @@ export const RETRO_LOG_ERROR = 3;
 // Sentinels
 /** Video refresh data pointer meaning "GL framebuffer is valid". */
 export const RETRO_HW_FRAME_BUFFER_VALID = -1 >>> 0; // unsigned -1
+
+// HW render context types (retro_hw_context_type) — the GL flavors the
+// HW-render cores (n64/ps1) request via RETRO_ENVIRONMENT_SET_HW_RENDER.
+export const RETRO_HW_CONTEXT_NONE = 0;
+export const RETRO_HW_CONTEXT_OPENGL = 1;        // OpenGL 2.x (compat)
+export const RETRO_HW_CONTEXT_OPENGLES2 = 2;     // GLES 2.0
+export const RETRO_HW_CONTEXT_OPENGL_CORE = 3;   // OpenGL 3+ core
+export const RETRO_HW_CONTEXT_OPENGLES3 = 4;     // GLES 3.0
+export const RETRO_HW_CONTEXT_OPENGLES_VERSION = 5; // GLES with explicit version
+
+// romdev-internal sentinel: a HW-render readback frame is already RGBA8888 (from
+// glReadPixels GL_RGBA), NOT the BGRA byte order libretro's XRGB8888 uses. The
+// framebuffer decoder special-cases this so R/B aren't swapped.
+export const ROMDEV_PIXEL_FORMAT_RGBA8888 = 0x52474241; // 'RGBA'

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/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,122 @@ 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"],
+      },
+    };
+  })(),
+
+  // ── Sega Dreamcast (sh-elf-gcc SH-4) — bare PowerVR2 framebuffer via the bundled
+  // dc.h helper; the output ELF boots DIRECTLY on Flycast's reios HLE BIOS (no GD-ROM
+  // image, no firmware) and renders on the real GPU through native-gles. dc.h is
+  // auto-bundled by the toolchain, so the example is a single main.c. No KallistiOS
+  // and no genre scaffolds yet — `hello` is the verified renderable starting point. ──
+  dreamcast: {
+    default: { main: "hello/main.c", runtime: [], lang: "C (sh-elf-gcc)", ext: ".elf",
+      describe: "DCHELLO — the canonical Dreamcast starter: bring up the PowerVR2 640x480 RGB565 framebuffer (via the auto-bundled dc.h: FB_R_CTRL/SIZE/SOF1 + SPG) and paint a test pattern (dark-blue field, red/green/blue bars, white frame). Proves the SH-4 build → Flycast reios HLE boot → native-gles GPU render pipeline end-to-end. The base to grow your own DC graphics from. Same as 'hello'." },
+    hello: { main: "hello/main.c", runtime: [], lang: "C (sh-elf-gcc)", ext: ".elf",
+      describe: "DCHELLO — a minimal Dreamcast homebrew. dc_video_init() programs the PowerVR2 framebuffer registers for 640x480 RGB565 at VRAM 0xA5000000; then dc_clear/dc_rect paint a recognizable pattern. Boots directly on Flycast's reios HLE BIOS (no firmware) and presents through native-gles with flycast_emulate_framebuffer — no TA display list needed.",
+      players: "1 (Dreamcast has 4 controller ports; the bare path doesn't wire the Maple bus yet)",
+      sram: "none in this starter — DC saves go to the VMU via the Maple bus; not wired in the bare path.",
+      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"] },
+  },
 };
 // 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.

package/src/platforms/n64/lib/c/n64.c

@@ -0,0 +1,196 @@
+/* n64.c — N64 helpers + software 3D pipeline (see n64.h). Framebuffer backend. */
+#include "n64.h"
+
+/* Two 320x240x16bpp framebuffers in RDRAM (double-buffered), cached kseg0. */
+#define FB0 0xA0100000u  /* uncached kseg1 — writes go straight to RDRAM */
+#define FB1 0xA0120000u
+static volatile unsigned short *fb;   /* the back buffer we draw into */
+static unsigned int front;
+
+/* VI registers (0xA4400000). */
+#define VI(n) (*(volatile unsigned int*)(0xA4400000u + (n)*4))
+#define VI_STATUS 0
+#define VI_ORIGIN 1
+#define VI_WIDTH  2
+#define VI_V_CURRENT 4
+#define VI_H_START 9
+#define VI_V_START 10
+#define VI_X_SCALE 12
+#define VI_Y_SCALE 13
+
+void n64_init(void)
+{
+    /* NTSC 320x240 16bpp — register indices per the N64 VI map:
+       0=STATUS 1=ORIGIN 2=WIDTH 3=V_INTR 4=CURRENT 5=BURST 6=V_SYNC 7=H_SYNC
+       8=LEAP 9=H_START 10=V_START 11=V_BURST 12=X_SCALE 13=Y_SCALE. */
+    VI(0)  = 0x0000320E;   /* STATUS: 16bpp(type=2) + AA + dither + pixel_advance */
+    VI(2)  = 320;          /* WIDTH */
+    VI(3)  = 2;            /* V_INTR */
+    VI(4)  = 0;            /* CURRENT */
+    VI(5)  = 0x03E52239;   /* BURST (NTSC) */
+    VI(6)  = 0x0000020D;   /* V_SYNC = 525 */
+    VI(7)  = 0x00000C15;   /* H_SYNC */
+    VI(8)  = 0x0C150C15;   /* LEAP */
+    VI(9)  = 0x006C02EC;   /* H_START: 108..748 */
+    VI(10) = 0x002501FF;   /* V_START: 37..511 */
+    VI(11) = 0x000E0204;   /* V_BURST */
+    VI(12) = 0x00000200;   /* X_SCALE (320) */
+    VI(13) = 0x00000400;   /* Y_SCALE (240) */
+    front = FB0;
+    fb = (volatile unsigned short *)FB1;
+    VI(1) = FB0 & 0x1FFFFFFF;   /* ORIGIN */
+}
+
+static inline void putpx(int x, int y, unsigned short c)
+{
+    if ((unsigned)x < SCREEN_W && (unsigned)y < SCREEN_H) fb[y * SCREEN_W + x] = c;
+}
+
+void n64_clear(unsigned short col)
+{
+    int i; for (i = 0; i < SCREEN_W * SCREEN_H; i++) fb[i] = col;
+}
+
+void n64_rect(int x, int y, int w, int h, unsigned short col)
+{
+    int r, c;
+    for (r = 0; r < h; r++) for (c = 0; c < w; c++) putpx(x + c, y + r, col);
+}
+
+/* edge function for the rasterizer */
+static inline int edge(int ax, int ay, int bx, int by, int cx, int cy)
+{ return (bx - ax) * (cy - ay) - (by - ay) * (cx - ax); }
+
+void n64_tri2d(int x0,int y0,int x1,int y1,int x2,int y2,unsigned short col)
+{
+    int minx = x0, maxx = x0, miny = y0, maxy = y0, px, py, w0, w1, w2, area;
+    if (x1 < minx) minx = x1; if (x1 > maxx) maxx = x1;
+    if (x2 < minx) minx = x2; if (x2 > maxx) maxx = x2;
+    if (y1 < miny) miny = y1; if (y1 > maxy) maxy = y1;
+    if (y2 < miny) miny = y2; if (y2 > maxy) maxy = y2;
+    if (minx < 0) minx = 0; if (miny < 0) miny = 0;
+    if (maxx >= SCREEN_W) maxx = SCREEN_W - 1; if (maxy >= SCREEN_H) maxy = SCREEN_H - 1;
+    area = edge(x0, y0, x1, y1, x2, y2);
+    if (area == 0) return;
+    for (py = miny; py <= maxy; py++) {
+        for (px = minx; px <= maxx; px++) {
+            w0 = edge(x1, y1, x2, y2, px, py);
+            w1 = edge(x2, y2, x0, y0, px, py);
+            w2 = edge(x0, y0, x1, y1, px, py);
+            if (area > 0) { if (w0 >= 0 && w1 >= 0 && w2 >= 0) fb[py * SCREEN_W + px] = col; }
+            else          { if (w0 <= 0 && w1 <= 0 && w2 <= 0) fb[py * SCREEN_W + px] = col; }
+        }
+    }
+}
+
+void n64_flip(void)
+{
+    /* swap buffers + point VI at the freshly drawn one, then wait for a frame. */
+    unsigned int newfront = (unsigned int)(unsigned long)fb;
+    VI(1) = newfront & 0x1FFFFFFF;
+    fb = (volatile unsigned short *)(front);
+    front = newfront;
+    { volatile int i; for (i = 0; i < 200000; i++) { } }
+}
+
+/* ── input: read controller port 0 via the SI/PIF. The PIF command 0x01 polls
+   the pad; the 16-bit button word is at PIF RAM. We use the simple JoyBus poll. ── */
+static unsigned int read_pad(void)
+{
+    volatile unsigned int *pif = (volatile unsigned int *)0xBFC007C0; /* PIF RAM */
+    volatile unsigned int *si  = (volatile unsigned int *)0xA4800000;
+    unsigned int buttons;
+    /* command block: read controller 0 (1 byte cmd 0x01, 1 byte send, ...) */
+    pif[0] = 0xFF010401; pif[1] = 0xFFFFFFFF; pif[2] = 0xFFFFFFFF;
+    pif[3] = 0xFE000000; pif[4] = 0; pif[5] = 0; pif[6] = 0; pif[7] = 1;
+    si[1] = 0x1FC007C0;          /* SI_PIF_ADDR_RD64B: kick the PIF read */
+    { volatile int t; for (t = 0; t < 5000; t++) { } }
+    buttons = pif[1] >> 16;      /* the button half-word */
+    return (~0u) & buttons;      /* JoyBus buttons are active-high already */
+}
+unsigned int n64_pad(void) { return read_pad(); }
+int n64_pressed(unsigned int mask) { return (n64_pad() & mask) ? 1 : 0; }
+
+/* ── trig (shared with PS1 lib: 256-step binary angle) ── */
+static const short SINTAB[64] = {
+0,804,1608,2410,3212,4011,4808,5602,6393,7179,7962,8739,9512,10278,11039,11793,
+12539,13279,14010,14732,15446,16151,16846,17530,18204,18868,19519,20159,20787,21403,
+22005,22594,23170,23731,24279,24811,25329,25832,26319,26790,27245,27683,28105,28510,
+28898,29268,29621,29956,30273,30571,30852,31113,31356,31580,31785,31971,32137,32285,
+32412,32521,32609,32678,32728,32757 };
+static fix sin_lut(int idx) {
+    int q = (idx >> 6) & 3, p = idx & 63; int v;
+    if (q == 0) v = SINTAB[p]; else if (q == 1) v = SINTAB[63 - p];
+    else if (q == 2) v = -SINTAB[p]; else v = -SINTAB[63 - p];
+    return ((fix)v << 16) / 32768;
+}
+fix n64_sin(fix a) { return sin_lut((F2I(a)) & 255); }
+fix n64_cos(fix a) { return sin_lut((F2I(a) + 64) & 255); }
+
+/* ── camera + model (identical to the PS1 lib) ── */
+static fix cam_x, cam_y, cam_z, cam_cy, cam_sy, cam_cp, cam_sp;
+static fix mdl_x, mdl_y, mdl_z, mdl_cy, mdl_sy;
+void n64_camera(fix ex, fix ey, fix ez, fix yaw, fix pitch)
+{ cam_x=ex;cam_y=ey;cam_z=ez; cam_cy=n64_cos(yaw);cam_sy=n64_sin(yaw); cam_cp=n64_cos(pitch);cam_sp=n64_sin(pitch); }
+void n64_model(fix tx, fix ty, fix tz, fix yaw)
+{ mdl_x=tx;mdl_y=ty;mdl_z=tz; mdl_cy=n64_cos(yaw);mdl_sy=n64_sin(yaw); }
+
+static Vec3 to_cam(Vec3 v)
+{
+    fix mx = FMUL(v.x, mdl_cy) + FMUL(v.z, mdl_sy);
+    fix mz = -FMUL(v.x, mdl_sy) + FMUL(v.z, mdl_cy);
+    fix wx = mx + mdl_x, wy = v.y + mdl_y, wz = mz + mdl_z;
+    fix rx = wx - cam_x, ry = wy - cam_y, rz = wz - cam_z;
+    fix cx = FMUL(rx, cam_cy) - FMUL(rz, cam_sy);
+    fix cz = FMUL(rx, cam_sy) + FMUL(rz, cam_cy);
+    fix cy = FMUL(ry, cam_cp) - FMUL(cz, cam_sp);
+    fix cz2 = FMUL(ry, cam_sp) + FMUL(cz, cam_cp);
+    Vec3 o; o.x = cx; o.y = cy; o.z = cz2; return o;
+}
+#define NEAR FIXF(0.5f)
+#define FOV  FIX(220)
+static int project(Vec3 c, int *sx, int *sy)
+{
+    if (c.z <= NEAR) return 0;
+    *sx = (SCREEN_W / 2) + F2I(FDIV(FMUL(c.x, FOV), c.z));
+    *sy = (SCREEN_H / 2) - F2I(FDIV(FMUL(c.y, FOV), c.z));
+    return 1;
+}
+void n64_tri3d(Vec3 a, Vec3 b, Vec3 c, unsigned short col)
+{
+    Vec3 ca=to_cam(a), cb=to_cam(b), cc=to_cam(c);
+    int x0,y0,x1,y1,x2,y2;
+    if (!project(ca,&x0,&y0)||!project(cb,&x1,&y1)||!project(cc,&x2,&y2)) return;
+    if ((x1-x0)*(y2-y0)-(x2-x0)*(y1-y0) <= 0) return; /* back-face cull */
+    n64_tri2d(x0,y0,x1,y1,x2,y2,col);
+}
+void n64_quad3d(Vec3 a, Vec3 b, Vec3 c, Vec3 d, unsigned short col)
+{ n64_tri3d(a,b,c,col); n64_tri3d(a,c,d,col); }
+void n64_tri3d_nc(Vec3 a, Vec3 b, Vec3 c, unsigned short col)
+{
+    Vec3 ca=to_cam(a), cb=to_cam(b), cc=to_cam(c);
+    int x0,y0,x1,y1,x2,y2;
+    if (!project(ca,&x0,&y0)||!project(cb,&x1,&y1)||!project(cc,&x2,&y2)) return;
+    n64_tri2d(x0,y0,x1,y1,x2,y2,col);
+}
+void n64_quad3d_nc(Vec3 a, Vec3 b, Vec3 c, Vec3 d, unsigned short col)
+{ n64_tri3d_nc(a,b,c,col); n64_tri3d_nc(a,c,d,col); }
+
+/* ── RNG ── */
+static unsigned int rng = 0x12345678u;
+void n64_srand(unsigned int s) { rng = s ? s : 1; }
+unsigned int n64_rand(void) { unsigned int x=rng; x^=x<<13; x^=x>>17; x^=x<<5; return rng=x; }
+
+/* ── HUD number (3x5 cells scaled) ── */
+static const unsigned char DIG[10][5] = {
+ {0x7,0x5,0x5,0x5,0x7},{0x2,0x6,0x2,0x2,0x7},{0x7,0x1,0x7,0x4,0x7},{0x7,0x1,0x3,0x1,0x7},
+ {0x5,0x5,0x7,0x1,0x1},{0x7,0x4,0x7,0x1,0x7},{0x7,0x4,0x7,0x5,0x7},{0x7,0x1,0x1,0x1,0x1},
+ {0x7,0x5,0x7,0x5,0x7},{0x7,0x5,0x7,0x1,0x7} };
+static void digit(int x,int y,int d,unsigned short col)
+{ int r,c; for(r=0;r<5;r++)for(c=0;c<3;c++) if(DIG[d][r]&(1<<(2-c))) n64_rect(x+c*3,y+r*3,3,3,col); }
+void n64_number(int x, int y, unsigned int value, unsigned short col)
+{
+    char buf[10]; int n=0,i;
+    if(!value)buf[n++]=0; while(value&&n<10){buf[n++]=value%10;value/=10;}
+    for(i=0;i<n;i++) digit(x+(n-1-i)*12,y,buf[i],col);
+}