romdevtools 0.70.0 → 0.71.0

package/CHANGELOG.md

@@ -4,6 +4,65 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.71.0 — 2026-06-28
+
+### N64 / PS1 / Dreamcast reach full parity: cpuState + audioDebug + GPU-rendering helper libs + 5 examples each
+
+The three next-gen 3D platforms are now first-class alongside the original 14.
+
+**Live debugging (cpuState + audioDebug).** PS1 (beetle_psx_hw) and Dreamcast (flycast)
+gained the romdev debug-reader exports, so `cpu({op:'read'})` and
+`audioDebug({op:'inspect'})` light up (N64 already had them):
+- **PS1** — `cpu({op:'read'})` returns the live R3000A register file; `audioDebug({chip:'spu'})`
+  decodes the SPU's 24 voices + main volume (read from the raw register mirror, not the
+  sweep-quantized `SPU_Read`).
+- **Dreamcast** — `cpu({op:'read'})` returns the SH-4 registers (r0–r15, pc, pr, gbr, vbr,
+  sr + decoded flags, mac, fpul); `audioDebug({chip:'aica'})` decodes the AICA's 64
+  PCM/ADPCM channels + master volume. Full host plumbing + decoders added.
+- The capability manifest now reports cpuState/audioDebug `true` for all three (verified by
+  probing real core exports; `breakpoint`/`watch` remain pending on PS1/DC).
+
+**GPU-rendering helper libs (no software framebuffers).** Every 3D platform's helper now
+draws through the GPU — a software rasterizer would be black on the GL cores and <1fps:
+- **N64** — the `n64.h` helper was rewritten to emit a **GBI (F3DEX2) display list** that
+  glide64 HLEs onto the GPU (clear/rect as fill-rectangles, triangles scan-converted into
+  GPU fill-rect spans), instead of poking pixels into RDRAM (which rendered black on
+  glide64). No Nintendo microcode shipped — the OSTask CRC-bait trick selects F3DEX2.
+- **PS1** — already correct (GP0 GPU primitives on beetle_psx_hw).
+- **Dreamcast** — `dc.h` now sets **480i interlace** in `dc_video_init` (240p only showed
+  the top 240 of 480 lines), and added a Maple-DMA `dc_pad()` / `dc_pressed()`.
+- `#include "n64.h"` / `#include "psx.h"` now auto-bundle (parity with `dc.h`).
+
+**5 genre examples per platform.** N64, PS1, and Dreamcast each ship
+shmup / platformer / puzzle / racing / sports examples — all verified building + rendering
+on the GPU.
+
+**Docs.** MENTAL_MODEL + TROUBLESHOOTING for N64, PS1, and Dreamcast (the render model,
+boot story, debug surface, and what's N/A and why).
+
+### asar (SNES) build-tool fixes
+
+From real commercial-disassembly feedback:
+- **`build({output:'project'|'run'})` honors `options` + a new `defines` map** (e.g. asar
+  `--define`) — they were silently dropped.
+- **New `entry` param** so a project whose top file isn't `main.*` (e.g. an existing
+  `smw.asm` disassembly) builds without injecting glue.
+- **Subdirectory assets are staged recursively** (a flat `readdir` missed nested
+  `incbin`/`incsrc` targets).
+- **A clean asar error is no longer mislabeled** `[worker] Abort in WASM` (it exits errors
+  via a C++-exception path; the misleading heap-pointer line is stripped when real
+  diagnostics are present).
+- **The LoROM-header bankcross preflight no longer false-positives** on banks $01+ (the
+  header is only in bank $00) and honors `check bankcross off`.
+- **A readfile/filesize advisory** warns when a source reads many distinct files that way
+  (the asar-WASM resource limit), pointing at the pre-convert-to-`.bin` + `incbin`
+  workaround.
+
+### Toolchain
+
+- **sh-c (Dreamcast) defaults to `-O1`** — the sh-elf `cc1.wasm` has an `-O2`-only pass
+  that aborts on common control flow; `-O1` dodges it. A user-supplied `-O<level>` wins.
+
 ## 0.70.0 — 2026-06-26
 
 ### Dreamcast is ship-ready: verified build → run → screenshot, with a renderable example

package/examples/dreamcast/platformer/main.c

@@ -0,0 +1,31 @@
+/* Dreamcast PLATFORMER demo — a side-scrolling scene: a hero hops across platforms
+ * while the camera scrolls. Self-animating (no input). Renders on the PowerVR2 via
+ * the framebuffer path. */
+#include "dc.h"
+
+void main(void){
+    int frame = 0;
+    dc_video_init();
+    for (;;){
+        int scroll = (frame * 2) % (DC_W);
+        int t = frame % 90;
+        int jump = t < 45 ? t : (90 - t);              /* 0..45..0 hop */
+        int hy = DC_H - 140 - jump * 2;
+        int hx = DC_W/2 - 16;
+
+        dc_clear(dc_rgb(80, 150, 230));                /* sky */
+        /* parallax hills */
+        { int i; for (i = -1; i < 6; i++){ int x = i*140 - (scroll/2); dc_rect(x, DC_H-200, 120, 200, dc_rgb(60, 170, 90)); } }
+        /* ground */
+        dc_rect(0, DC_H-60, DC_W, 60, dc_rgb(120, 80, 40));
+        /* floating platforms (scrolling) */
+        { int i; for (i = -1; i < 6; i++){ int x = i*180 - (scroll % 180); dc_rect(x, DC_H-160, 90, 18, dc_rgb(150, 110, 60)); } }
+        /* hero (head + body) */
+        dc_rect(hx, hy, 32, 32, dc_rgb(240, 90, 70));
+        dc_rect(hx+6, hy+6, 6, 6, dc_rgb(255,255,255)); /* eye */
+        dc_rect(hx, hy+32, 32, 20, dc_rgb(40, 60, 200)); /* legs */
+        /* a coin that bobs */
+        dc_rect(DC_W/2 + 120 - (scroll%240), DC_H-220 + (jump), 18, 18, dc_rgb(255, 220, 60));
+        frame++;
+    }
+}

package/examples/dreamcast/puzzle/main.c

@@ -0,0 +1,44 @@
+/* Dreamcast PUZZLE demo — a falling-block (Tetris-like) board that fills + clears
+ * rows on a loop. Self-animating (no input). Renders on the PowerVR2 framebuffer. */
+#include "dc.h"
+
+#define COLS 10
+#define ROWS 16
+#define CELL 24
+
+static unsigned char board[ROWS][COLS];
+static unsigned int rng = 0xACE1u;
+static unsigned int rnd(void){ rng ^= rng << 7; rng ^= rng >> 9; rng ^= rng << 8; return rng; }
+
+static const u16 PAL[7] = { 0, 0xF800, 0x07E0, 0x001F, 0xFFE0, 0xF81F, 0x07FF };
+
+void main(void){
+    int frame = 0, px = COLS/2, py = 0, col = 1, i, r, c;
+    dc_video_init();
+    for (;;){
+        int ox = (DC_W - COLS*CELL)/2, oy = (DC_H - ROWS*CELL)/2;
+
+        if ((frame % 8) == 0){
+            /* drop the active block one row; lock + respawn at the bottom */
+            if (py+1 >= ROWS || board[py+1][px]){
+                board[py][px] = col;
+                /* clear full-ish rows occasionally to keep it moving */
+                for (r = 0; r < ROWS; r++){ int full=1; for (c=0;c<COLS;c++) if(!board[r][c]) full=0;
+                    if (full){ for(c=0;c<COLS;c++) board[r][c]=0; } }
+                py = 0; px = rnd()%COLS; col = 1 + rnd()%6;
+                if (board[0][px]){ for(r=0;r<ROWS;r++)for(c=0;c<COLS;c++) board[r][c]=0; } /* reset if buried */
+            } else py++;
+        }
+        dc_clear(dc_rgb(18, 18, 30));
+        /* board frame */
+        dc_rect(ox-4, oy-4, COLS*CELL+8, ROWS*CELL+8, dc_rgb(90,90,120));
+        dc_rect(ox, oy, COLS*CELL, ROWS*CELL, dc_rgb(10,10,18));
+        /* settled cells */
+        for (r = 0; r < ROWS; r++) for (c = 0; c < COLS; c++) if (board[r][c])
+            dc_rect(ox + c*CELL+1, oy + r*CELL+1, CELL-2, CELL-2, PAL[board[r][c]]);
+        /* active block */
+        dc_rect(ox + px*CELL+1, oy + py*CELL+1, CELL-2, CELL-2, PAL[col]);
+        frame++;
+        (void)i;
+    }
+}

package/examples/dreamcast/racing/main.c

@@ -0,0 +1,39 @@
+/* Dreamcast RACING demo — a pseudo-3D road that curves + scrolls toward a horizon,
+ * with a car at the bottom that drifts side to side. Self-animating (no input).
+ * Renders on the PowerVR2 framebuffer. */
+#include "dc.h"
+
+/* tiny fixed sine via a 16-entry quarter table */
+static const int SIN16[17] = {0,49,97,142,181,213,236,251,256,251,236,213,181,142,97,49,0};
+static int isin(int a){ a &= 63; if(a<16) return SIN16[a]; if(a<32) return SIN16[32-a]; if(a<48) return -SIN16[a-32]; return -SIN16[64-a]; }
+
+void main(void){
+    int frame = 0, y;
+    dc_video_init();
+    for (;;){
+        int horizon = DC_H/3;
+        dc_clear(dc_rgb(60, 140, 230));               /* sky */
+        dc_rect(0, horizon, DC_W, DC_H-horizon, dc_rgb(40, 120, 50)); /* grass */
+
+        /* road: for each scanline below the horizon, a trapezoid widening to the
+           bottom, shifted by a curve that scrolls. */
+        for (y = horizon; y < DC_H; y++){
+            int depth = y - horizon;
+            int half = depth * (DC_W/2 - 20) / (DC_H - horizon) + 12;
+            int curve = isin((frame/2 + depth/4)) * depth / 256;
+            int cx = DC_W/2 + curve;
+            /* road stripe alternation for motion */
+            u16 rc = (((depth + frame) / 12) & 1) ? dc_rgb(70,70,75) : dc_rgb(90,90,95);
+            dc_rect(cx - half, y, half*2, 1, rc);
+            /* center dashes */
+            if ((((depth + frame*2)/16) & 1)) dc_rect(cx-2, y, 4, 1, dc_rgb(240,240,120));
+        }
+        /* the car (drifts L/R) */
+        { int carx = DC_W/2 + isin(frame/3) * 60 / 256 - 24;
+          dc_rect(carx, DC_H-70, 48, 40, dc_rgb(220, 40, 40));
+          dc_rect(carx+6, DC_H-64, 36, 14, dc_rgb(40,40,60));     /* windshield */
+          dc_rect(carx-4, DC_H-44, 10, 18, dc_rgb(20,20,20));     /* wheels */
+          dc_rect(carx+42, DC_H-44, 10, 18, dc_rgb(20,20,20)); }
+        frame++;
+    }
+}

package/examples/dreamcast/shmup/main.c

@@ -0,0 +1,50 @@
+/* Dreamcast SHMUP demo — a vertical shooter scene rendered on the PowerVR2 via the
+ * framebuffer path. The ship weaves, bullets stream up, enemies descend + recycle.
+ * Self-animating (no input) — proves program-controlled graphics render on the GPU.
+ * (DC input via dc_pad() reads the resting controller state; full press wiring is a
+ * follow-up — see dc.h.) */
+#include "dc.h"
+
+#define NB 12
+#define NE 6
+
+static int frame;
+static unsigned int rng = 0x1234567u;
+static unsigned int rnd(void){ rng ^= rng << 13; rng ^= rng >> 17; rng ^= rng << 5; return rng; }
+
+static int bx[NB], by[NB], ba[NB];
+static int ex[NE], ey[NE];
+
+void main(void){
+    int i;
+    dc_video_init();
+    for (i = 0; i < NE; i++){ ex[i] = 60 + i*90; ey[i] = -(int)(rnd()%300); }
+    for (;;){
+        int shipx = DC_W/2 + (int)(80.0 * ((frame % 120) < 60 ? (frame%60) : (60-(frame%60))) / 60.0 - 40);
+        int shipy = DC_H - 80;
+
+        /* spawn a bullet every 8 frames */
+        if ((frame & 7) == 0){
+            for (i = 0; i < NB; i++) if (!ba[i]){ ba[i]=1; bx[i]=shipx; by[i]=shipy; break; }
+        }
+        dc_clear(dc_rgb(8, 10, 28));
+        /* starfield */
+        for (i = 0; i < 24; i++){
+            int sx = (int)((rnd()%DC_W));
+            int sy = (int)((frame*2 + i*53) % DC_H);
+            dc_rect(sx, sy, 2, 2, dc_rgb(120,120,160));
+        }
+        /* enemies */
+        for (i = 0; i < NE; i++){
+            ey[i] += 2;
+            if (ey[i] > DC_H){ ey[i] = -(int)(rnd()%200); ex[i] = (int)(rnd()%(DC_W-40)); }
+            if (ey[i] >= 0) dc_rect(ex[i], ey[i], 36, 28, dc_rgb(220, 60, 60));
+        }
+        /* bullets */
+        for (i = 0; i < NB; i++) if (ba[i]){ by[i] -= 8; if (by[i] < 0) ba[i]=0; else dc_rect(bx[i]-2, by[i], 4, 12, dc_rgb(255,240,80)); }
+        /* player ship (a little arrow of rects) */
+        dc_rect(shipx-4, shipy, 8, 24, dc_rgb(80, 200, 255));
+        dc_rect(shipx-16, shipy+14, 32, 8, dc_rgb(60, 160, 230));
+        frame++;
+    }
+}

package/examples/dreamcast/sports/main.c

@@ -0,0 +1,39 @@
+/* Dreamcast SPORTS demo — a top-down pong/air-hockey rally: two paddles track a
+ * bouncing ball with a scoreboard. Self-animating (the CPU "AI" plays both sides).
+ * Renders on the PowerVR2 framebuffer. */
+#include "dc.h"
+
+void main(void){
+    int frame = 0;
+    int bx = DC_W/2, by = DC_H/2, vx = 5, vy = 3;
+    int p0 = DC_H/2, p1 = DC_H/2;          /* paddle centers (y) */
+    int s0 = 0, s1 = 0, i;
+    dc_video_init();
+    for (;;){
+        /* ball physics */
+        bx += vx; by += vy;
+        if (by < 12 || by > DC_H-12) vy = -vy;
+        /* paddles track the ball (simple AI) */
+        if (p0 < by) p0 += 4; else p0 -= 4;
+        if (p1 < by) p1 += 4; else p1 -= 4;
+        /* bounce off paddles / score */
+        if (bx < 40){ if (by > p0-50 && by < p0+50) vx = -vx; else { s1++; bx=DC_W/2; by=DC_H/2; vx=5; } }
+        if (bx > DC_W-40){ if (by > p1-50 && by < p1+50) vx = -vx; else { s0++; bx=DC_W/2; by=DC_H/2; vx=-5; } }
+
+        dc_clear(dc_rgb(15, 60, 30));                  /* court green */
+        /* center line (dashed) */
+        for (i = 0; i < DC_H; i += 32) dc_rect(DC_W/2-2, i+8, 4, 16, dc_rgb(200,200,200));
+        /* top/bottom rails */
+        dc_rect(0, 0, DC_W, 8, dc_rgb(220,220,220));
+        dc_rect(0, DC_H-8, DC_W, 8, dc_rgb(220,220,220));
+        /* paddles */
+        dc_rect(24, p0-50, 14, 100, dc_rgb(80, 160, 255));
+        dc_rect(DC_W-38, p1-50, 14, 100, dc_rgb(255, 160, 80));
+        /* ball */
+        dc_rect(bx-8, by-8, 16, 16, dc_rgb(255, 240, 80));
+        /* scoreboard (score as stacked pips) */
+        for (i = 0; i < s0 && i < 9; i++) dc_rect(DC_W/2 - 60 - i*10, 16, 8, 8, dc_rgb(80,160,255));
+        for (i = 0; i < s1 && i < 9; i++) dc_rect(DC_W/2 + 56 + i*10, 16, 8, 8, dc_rgb(255,160,80));
+        frame++; (void)frame;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 17 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, PlayStation, N64, Dreamcast, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",
@@ -58,9 +58,9 @@
     "romdev-core-geargrafx": "0.7.0",
     "romdev-core-gpgx": "0.12.0",
     "romdev-core-handy": "0.7.0",
-    "romdev-core-flycast": "0.1.0",
+    "romdev-core-flycast": "0.1.1",
     "romdev-core-parallel-n64": "0.1.0",
-    "romdev-core-beetle-psx-hw": "0.1.0",
+    "romdev-core-beetle-psx-hw": "0.1.1",
     "romdev-core-prosystem": "0.8.0",
     "romdev-core-vice": "0.9.0",
     "romdev-famitone": "0.1.0",

package/src/cores/capabilities.js

@@ -224,14 +224,15 @@ export const CAPABILITIES = {
       // beetle_psx_hw: the GPU renders on the REAL GPU via the GLES3/WebGL2 hardware
       // renderer through native-gles (like glide64-N64 + Flycast-DC), with OpenBIOS
       // EMBEDDED (PCSX-Redux, MIT, region-free) — no Sony firmware to ship, no BIOS file.
-      // run/screenshot + cheats live; disasm + decompile work (MIPS Capstone + the
-      // MIPS:LE:32 SLEIGH spec). cpuState/audioDebug are OFF: those need beetle-side
-      // romdev_mips_regs_get/romdev_spu_get exports (a future core patch — the old
-      // pcsx_rearmed-software build had them, but it has no WebGL2 GPU path). build needs
-      // a PS1 toolchain (PSn00bSDK, not yet).
+      // run/screenshot + cheats + cpuState + audioDebug live; disasm + decompile work
+      // (MIPS Capstone + the MIPS:LE:32 SLEIGH spec). cpuState (R3000A GPR_full/BACKED_PC)
+      // + audioDebug (SPU $1F801C00 register block) come from beetle-side
+      // romdev_mips_regs_get/romdev_spu_get exports patched into cpu.c (see
+      // scripts/patches/romdev-snippets/beetle-psx-regsnap.c). build needs a PS1
+      // toolchain (PSn00bSDK, not yet).
       build: true, run: true, screenshot: true,
       inspectSprites: false, inspectPalette: false, inspectBackground: false,
-      renderingContext: false, cpuState: false, audioDebug: false,
+      renderingContext: false, cpuState: true, audioDebug: true,
       cart: false, disasm: true, decompile: true,
     },
   },
@@ -264,11 +265,14 @@ export const CAPABILITIES = {
       // code (run + memory introspection), and the PowerVR2 present-path works — flycast
       // renders to the GL FBO and the host reads it back (verified: a framebuffer-writing
       // program shows ~727k captured pixels). `build` lands with the sh-elf-gcc WASM
-      // toolchain. The 3D renderer has no tile/sprite inspectors (N/A by hw).
-      // disasm/decompile = SH-4 analysis slice (rizin `sh` + Ghidra SuperH4 SLEIGH).
+      // toolchain. cpuState (SH-4 Sh4cntx regs) + audioDebug (AICA 64-channel register
+      // window) come from romdev_sh4_regs_get/romdev_aica_get patched into the flycast
+      // libretro entry (see scripts/patches/romdev-snippets/flycast-debug.c). The 3D
+      // renderer has no tile/sprite inspectors (N/A by hw). disasm/decompile = SH-4
+      // analysis slice (rizin `sh` + Ghidra SuperH4 SLEIGH).
       build: true, run: true, screenshot: true,
       inspectSprites: false, inspectPalette: false, inspectBackground: false,
-      renderingContext: false, cpuState: false, audioDebug: false,
+      renderingContext: false, cpuState: true, audioDebug: true,
       cart: false, disasm: true, decompile: true,
     },
   },