romdevtools 0.70.0 → 0.71.1

package/src/platforms/n64/MENTAL_MODEL.md

@@ -0,0 +1,84 @@
+# Nintendo 64 — mental model
+
+The N64 is a **3D machine**: a 93.75 MHz MIPS R4300i CPU + the RCP (Reality
+Co-Processor = RSP vector unit + RDP rasterizer) drawing into RDRAM, scanned out
+by the VI (Video Interface). romdev runs it on **parallel_n64** (libretro) built to
+WASM, rendering through the **glide64 GL HLE plugin** on the real GPU via romdev's
+native-gles / WebGL2 bridge (`hwRender: true`).
+
+## The one thing to know about rendering
+
+The N64 core renders through **glide64** — a GL HLE plugin that interprets the game's
+**GBI display lists** and rasterizes them on the real GPU. So romdev N64 homebrew draws
+by building a **GBI (F3DEX2) display list** each frame and kicking the RSP, the way a
+real game does; glide64 HLEs it onto the GPU. A software framebuffer (poking pixels
+into RDRAM) shows **black** on glide64 and would be <1fps — so don't do that.
+
+**Use the bundled `n64.c` helper** — it does the GPU path for you: `n64_clear`/`n64_rect`
+emit GPU **fill rectangles**, `n64_tri2d`/`n64_tri3d`/`n64_quad3d` scan-convert into
+GPU fill-rect spans (still GPU-rasterized, not CPU pixels), and `n64_flip` ships the
+display list as a GFX OSTask. `#include "n64.h"` and it just works (auto-bundled). How
+it gets glide64 to accept the list without shipping Nintendo microcode: the RSP-HLE
+treats an OSTask with `type==1` as graphics, and glide64 picks its command table by
+CRC-summing the task's "ucode" region — so the helper embeds a 3072-byte blob that
+*sums* to a real F3DEX2 CRC (the bytes are never executed under HLE).
+
+If the screen is black, the usual cause is software-framebuffer drawing instead of the
+helper's display-list path — see TROUBLESHOOTING. Confirm with `frame({op:'verify'})`.
+
+## CPU / memory map (R4300i, MIPS III, 64-bit, big-endian)
+
+| Region | KSEG | Address (virtual) | Notes |
+|--------|------|-------------------|-------|
+| RDRAM (cached)   | kseg0 | `0x8000_0000`+ | main RAM, 4 MB (8 MB with Expansion Pak) |
+| RDRAM (uncached) | kseg1 | `0xA000_0000`+ | same RAM, bypasses cache — use for the framebuffer |
+| Cart / PIF / RCP MMIO | kseg1 | `0xA300_0000`+ | SP/DP/VI/AI/PI/SI registers |
+
+Addresses are **big-endian**. `memory({op:'read', region:'system_ram'})` reads RDRAM.
+
+## Booting — header + IPL3
+
+A flat code image is not a bootable ROM. parallel_n64 HLEs the PIF boot: it copies
+ROM `0x40..0xFFF` into RSP DMEM and **executes it as the IPL3**. romdev's
+`build`/`cart` wrap a valid 64-byte header (magic `0x8037_1240`) + a minimal
+clean-room IPL3 (PI-DMA the game cart→RDRAM, jump to entry) + the game image. You
+don't write the header/IPL3 — the toolchain does (`wrapN64Rom`).
+
+## Input
+
+Homebrew reads controllers from **hardware** (the PIF/JoyBus), not via injection. The
+host's `setInput`/`run` holdInputs drive the emulated pad; the game polls JoyBus and
+sees them. The helper lib exposes a `pad_read()`.
+
+## Sound
+
+The AI (Audio Interface) DMAs a sample buffer from RDRAM to the DAC. `audioDebug`
+decodes the AI register block (`romdev_ai_get`). The helper lib has a minimal audio
+push path.
+
+## MCP debug & inspection tooling
+
+N64 is at **full parity** with the tile systems wherever the hardware allows:
+
+- **`cpu({op:'read'})`** — live R4300i register file (`romdev_mips_regs_get`).
+- **`breakpoint` / `watch`** — PC breakpoints + memory watchpoints, hooked into the
+  interpreter step + memory R/W paths.
+- **`audioDebug({op:'inspect'})`** — AI registers.
+- **`memory({op:'read', region:'system_ram'})`** — RDRAM.
+- **`disasm` / `decompile`** — MIPS via rizin/Ghidra (R4300 is well-supported).
+- **`frame({op:'verify'})`** — render-health (nearlyBlank guard) for no-vision agents.
+- **`renderingContext`** is **N/A** (false) — that decodes 2D tile/sprite VDP state,
+  which a 3D framebuffer machine doesn't have. Not a missing feature.
+
+## Build pipeline
+
+`build({platform:'n64'})` cross-compiles with a from-scratch **mips-elf-gcc → WASM**
+toolchain (cc1 → as → ld → objcopy orchestrated from JS, like the m68k path), big-
+endian libs, then `wrapN64Rom` produces the bootable image. `#include` the bundled
+`n64.h` for the 3D helpers (display-list build + VI setup + pad/audio).
+
+## What's NOT bundled / hardware limits
+
+- No custom RSP microcode path (glide64 HLEs the standard F3DEX-style display lists).
+- No real-hardware Expansion Pak detection beyond the standard 4/8 MB split.
+- `renderingContext` is N/A (3D, no tile VDP).

package/src/platforms/n64/TROUBLESHOOTING.md

@@ -0,0 +1,60 @@
+# Nintendo 64 — troubleshooting
+
+Read `platform({op:'doc', platform:'n64', name:'mental_model'})` first — the shipping
+N64 renders through the **glide64 GL HLE plugin** (it rasterizes GBI display lists on
+the real GPU), not a software framebuffer.
+
+## "ROM builds + boots but the screen is BLACK"
+
+The #1 N64 bug — almost always **software-framebuffer drawing instead of the GPU path**:
+
+1. **You poked pixels into an RDRAM framebuffer yourself.** glide64 only presents GBI
+   **display lists** — it never scans out a CPU-written framebuffer. A software
+   rasterizer renders black here (and would be <1fps anyway). **Use the bundled `n64.c`
+   helper** (`n64_clear`/`n64_rect`/`n64_tri*`/`n64_quad3d` + `n64_flip`): it emits a
+   GBI display list glide64 HLEs onto the GPU. `#include "n64.h"` (auto-bundled).
+2. **You hand-built a display list with the wrong OSTask.** The RSP-HLE only routes a
+   task to glide64 when the OSTask `type` (DMEM 0xFC0) == 1, and glide64 only accepts
+   it if the task's ucode region CRC-matches a known ucode. The helper sets both (a
+   3072-byte blob summing to an F3DEX2 CRC); if you roll your own, match that.
+3. **You forgot `n64_flip()`** — the display list isn't submitted to the RSP until
+   flip kicks the task. Confirm with `frame({op:'verify'})` (nearlyBlank).
+
+## "frame({op:'verify'}) says nearlyBlank"
+
+No GBI list reached glide64 — it's a display-list / OSTask problem (causes 1-2), not a
+toolchain problem. The build is fine; the render path is the issue. The helper handles
+all of this — diff your code against it.
+
+## "Geometry is wrong / triangles inside-out / nothing where expected"
+
+3D pipeline math (the helper transforms + projects to screen space, then scan-converts
+triangles into GPU fill-rect spans). Check: 16.16 fixed-point throughout, back-face
+winding matches your vertex order, perspective divide before the viewport map, and the
+vertices land on-screen. Diff against the helper's draw order.
+
+## "Build fails: 'relocation truncated to fit'"
+
+Statics landed in `.sdata`/`.sbss` and the 16-bit GP-relative relocs overflowed. The
+toolchain passes `-G0` to **both** cc1 and the assembler to force everything into
+`.data`/`.bss`. If you're building outside `build()` with custom flags, add `-G0`
+everywhere.
+
+## "cpu({op:'read'}) / breakpoint / watch returns nothing"
+
+These read core exports (`romdev_mips_regs_get`, `romdev_*break/watch`). On N64 they
+ARE present (full parity). If they're missing, you're on a stale core — re-resolve via
+`platform({op:'resolve', platform:'n64'})` and confirm the bundled core, don't debug
+the tool.
+
+## "disasm/decompile of a multi-function program returns junk addresses"
+
+The MIPS RE works, but for absolute-addressed `jal` targets the analysis buffer's flat
+offsets must line up with the VAs' low bits (rizin ignores `-B` on a raw buffer). N64
+usually lands fine from codeStart=0x1000 post-IPL3; if a fixed-VA image misbehaves, see
+the PS1 troubleshooting note on the rebase trick — same principle.
+
+## "renderingContext returns N/A"
+
+Correct — N64 is a 3D framebuffer machine with no 2D tile/sprite VDP for that op to
+decode. Not a bug. Use `frame`/screenshot + `memory` to inspect the framebuffer.

package/src/platforms/n64/UPSTREAM_SOURCES.md

@@ -0,0 +1,52 @@
+# Nintendo 64 — source you can read
+
+Trust hierarchy (try in order before filing a feedback round):
+
+1. **Bundled examples** (`examples/n64/{shmup,platformer,puzzle,racing,sports}/main.c`) —
+   verified building + rendering on the GPU. Start here for "how do I draw / animate / use
+   the 3D helpers."
+2. **Bundled helper lib source** (`src/platforms/n64/lib/c/n64.c` + `n64.h`) — the GPU
+   drawing backend. Read this when a draw call doesn't render the way you expect: it shows
+   exactly how `n64_clear`/`n64_rect`/`n64_tri*`/`n64_flip` build a **GBI (F3DEX2) display
+   list** + the OSTask kick (NOT a software framebuffer — see MENTAL_MODEL).
+3. **The core source** (NOT bundled — fetch on demand):
+
+   | What | Upstream |
+   |---|---|
+   | parallel_n64 (libretro core + glide64 GL HLE) | https://github.com/libretro/parallel-n64 |
+   | Reality co-processor / RSP-HLE + glide64 internals | (in the parallel_n64 tree: `mupen64plus-rsp-hle/`, `glide2gl/src/Glide64/`) |
+
+4. **The toolchain** — a from-scratch `mips-elf-gcc` cross-compiler (big-endian) built to
+   WASM (`scripts/build-mips-toolchain.sh` + `build-mips-wasm-tools.sh`):
+
+   | Component | Upstream |
+   |---|---|
+   | binutils | https://ftp.gnu.org/gnu/binutils/ |
+   | gcc | https://ftp.gnu.org/gnu/gcc/ |
+   | newlib | https://sourceware.org/pub/newlib/ |
+
+5. **Reverse engineering** — `disasm`/`decompile` go through Rizin + Ghidra's MIPS
+   (R4300) support:
+
+   | What | Upstream |
+   |---|---|
+   | Rizin | https://github.com/rizinorg/rizin |
+   | rz-ghidra (decompiler) | https://github.com/rizinorg/rz-ghidra |
+
+## N64 hardware docs
+
+- **n64brew wiki** (the canonical modern reference): https://n64brew.dev/wiki/
+- **RCP / RDP / RSP** + the VI/AI/PI/SI register maps: n64brew + the parallel_n64
+  `vi_controller.h` / `rsp_core.c` enums in the core tree.
+- **libdragon** (a real open N64 SDK — read its GBI/display-list code for the standard
+  command encodings): https://github.com/DragonMinded/libdragon
+
+## When to use what
+
+- "Why is my homebrew BLACK on screen?" → MENTAL_MODEL + TROUBLESHOOTING (it's almost
+  always software-framebuffer drawing instead of the GBI display-list path).
+- "How does the helper build a display list / kick the RSP?" → `n64.c`
+  (`dl_begin`/`dl_end_and_run`) + the n64brew RDP/RSP pages.
+- "Which VI register sets 16bpp / scaling?" → the core's `vi_controller.h` enum.
+- "disasm returns junk addresses on a multi-function program" → TROUBLESHOOTING (the
+  absolute-`jal` base-alignment note).

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

@@ -1,117 +1,218 @@
-/* n64.c — N64 helpers + software 3D pipeline (see n64.h). Framebuffer backend. */
+/* n64.c — N64 helpers with a GPU (RDP/GBI) drawing backend.
+ *
+ * WHY THIS IS NOT A SOFTWARE RASTERIZER: the shipping N64 core renders through
+ * glide64 (a GL HLE plugin) — it presents the game's RDP/GBI **display lists** on
+ * the real GPU, NOT a raw CPU-written framebuffer. A software rasterizer that pokes
+ * pixels into RDRAM shows BLACK on glide64 (and would be <1fps even if it didn't).
+ * So this lib builds a GBI display list each frame and kicks the RSP/RDP; glide64
+ * HLEs it onto the GPU.
+ *
+ * HOW glide64 ACCEPTS OUR LIST (no Nintendo microcode shipped):
+ *  - The RSP-HLE treats an OSTask with type==1 (M_GFXTASK) as a graphics task and
+ *    hands the display list to glide64.
+ *  - glide64 picks its command table by CRC-summing 3072 bytes of the task's
+ *    "ucode" region and matching a known-ucode CRC. The bytes are NEVER executed
+ *    (HLE), only summed — so we embed a 3072-byte blob that SUMS to a real F3DEX2
+ *    CRC (0x5d3099f1). glide64 then interprets our list as standard F3DEX2.
+ *  - We emit standard F3DEX2 GBI: set color image / scissor / fill rectangles for
+ *    clear+rects, and shaded vertex triangles for tri2d/tri3d. Solid colors only.
+ */
 #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
+/* ── RCP register blocks ── */
+#define SP(n)  (*(volatile unsigned int*)(0xA4040000u + (n)*4))  /* RSP */
+#define DP(n)  (*(volatile unsigned int*)(0xA4100000u + (n)*4))  /* RDP cmd */
+#define VI(n)  (*(volatile unsigned int*)(0xA4400000u + (n)*4))  /* video */
+
+#define SP_MEM_ADDR  0   /* SP DMEM/IMEM address */
+#define SP_DRAM_ADDR 1
+#define SP_RD_LEN    2
+#define SP_WR_LEN    3
+#define SP_STATUS    4
+
+#define FB_ADDR 0x00200000u     /* 320x240x16bpp color image in RDRAM */
+#define DL_ADDR 0x00280000u     /* the GBI display list buffer (room for many spans) */
+#define UC_ADDR 0x00290000u     /* the fake "ucode" blob (CRC bait) */
+
+/* uncached pointers (kseg1) into those RDRAM regions */
+#define U16P(a) ((volatile unsigned short*)(0xA0000000u | (a)))
+#define U32P(a) ((volatile unsigned int*)  (0xA0000000u | (a)))
+
+static volatile unsigned int *dl;   /* write cursor into the display list */
+static unsigned int dl_count;       /* words written */
+
+/* ── GBI / F3DEX2 command opcodes (the ones the fill-rect path uses) ── */
+#define G_ENDDL          0xDF
+#define G_SETOTHERMODE_H 0xE3
+#define G_RDPPIPESYNC    0xE7
+#define G_RDPFULLSYNC    0xE9
+#define G_SETSCISSOR     0xED
+#define G_FILLRECT       0xF6
+#define G_SETFILLCOLOR   0xF7
+#define G_SETCIMG        0xFF
+
+static inline void dl_w(unsigned int w0, unsigned int w1)
+{ dl[dl_count++] = w0; dl[dl_count++] = w1; }
 
 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 */
+    int i;
+    /* NTSC 320x240 16bpp VI setup, scanning out FB_ADDR — glide64 reads our color
+       image from the SetColorImage GBI cmd, but the VI must still be programmed so
+       there is a valid display target. */
+    VI(0)  = 0x0000320E; VI(2) = 320; VI(3) = 2; VI(5) = 0x03E52239;
+    VI(6)  = 0x0000020D; VI(7) = 0x00000C15; VI(8) = 0x0C150C15;
+    VI(9)  = 0x006C02EC; VI(10)= 0x002501FF; VI(11)= 0x000E0204;
+    VI(12) = 0x00000200; VI(13)= 0x00000400;
+    VI(1)  = FB_ADDR;
+
+    /* Build the CRC-bait "ucode": 3072 bytes that SUM (as u32 words) to the F3DEX2
+       CRC glide64 expects (UCODE_ZELDA_OOT = 0x5d3099f1). All words 0 except one. */
+    { volatile unsigned int *uc = U32P(UC_ADDR);
+      for (i = 0; i < 3072/4; i++) uc[i] = 0;
+      uc[0] = 0x5d3099f1u; }
 }
 
-static inline void putpx(int x, int y, unsigned short c)
+/* Begin a fresh display list for this frame: sync + set the color image + scissor +
+   fill cycle, and a default combine that passes the fill/shade through. */
+static void dl_begin(void)
 {
-    if ((unsigned)x < SCREEN_W && (unsigned)y < SCREEN_H) fb[y * SCREEN_W + x] = c;
+    dl = U32P(DL_ADDR);
+    dl_count = 0;
+    dl_w((G_RDPPIPESYNC << 24), 0);
+    /* SetColorImage: fmt=0(RGBA) size=2(16b) width-1=319, addr=FB */
+    dl_w((G_SETCIMG << 24) | (0 << 21) | (2 << 19) | 319, FB_ADDR);
+    /* SetScissor: (0,0)-(320,240) in 10.2 fixed (<<2) */
+    dl_w((G_SETSCISSOR << 24) | (0 << 12) | 0, (320 << 14) | (240 << 2));
+    /* SetOtherMode_H: cycle type = FILL (3<<20 within the H word). F3DEX2 form:
+       shift=0x14(20) len=2 → set the 2 cycle-type bits to 3 (G_CYC_FILL). */
+    dl_w((G_SETOTHERMODE_H << 24) | ((32 - 20 - 2) << 8) | (2 - 1), 3u << 20);
+}
+
+/* End the list with sync + ENDDL, then ship it to the RSP/RDP as a GFX OSTask. */
+static void dl_end_and_run(void)
+{
+    dl_w((G_RDPFULLSYNC << 24), 0);
+    dl_w((G_ENDDL << 24), 0);
+
+    /* Write the OSTask into SP DMEM at 0xFC0 (SP DMEM is at 0xA4000000). */
+    volatile unsigned int *task = (volatile unsigned int *)0xA4000FC0u;
+    task[0] = 1;          /* 0xFC0 TASK_TYPE = M_GFXTASK (glide64 path) */
+    task[1] = 0;          /* 0xFC4 flags */
+    task[2] = 0;          /* 0xFC8 ucode_boot */
+    task[3] = 0;          /* 0xFCC ucode_boot_size */
+    task[4] = UC_ADDR;    /* 0xFD0 ucode (CRC-summed by glide64) */
+    task[5] = 0xC00;      /* 0xFD4 ucode_size (>= 3072 so the full CRC region reads) */
+    task[6] = UC_ADDR;    /* 0xFD8 ucode_data */
+    task[7] = 0x800;      /* 0xFDC ucode_data_size */
+    task[8] = 0;          /* 0xFE0 dram_stack */
+    task[9] = 0x400;      /* 0xFE4 dram_stack_size */
+    task[10] = 0;         /* 0xFE8 output_buff */
+    task[11] = 0;         /* 0xFEC output_buff_size */
+    task[12] = DL_ADDR;   /* 0xFF0 data_ptr → our GBI display list */
+    task[13] = dl_count * 4; /* 0xFF4 data_size (bytes) */
+    task[14] = 0;         /* 0xFF8 yield_data_ptr */
+    task[15] = 0;         /* 0xFFC yield_data_size */
+
+    /* Kick the RSP. The SP status-write handler runs the task only when BOTH HALT
+       and BROKE are clear after the write: bit0 (0x1) clears HALT, bit2 (0x4) clears
+       BROKE. Setting interrupt-on-break (0x100) makes the task signal completion.
+       The RSP-HLE then reads the OSTask at DMEM 0xFC0, sees type==1, and forwards
+       our display list to glide64. (SP_PC at 0xA4080000 is irrelevant under HLE —
+       the ucode never executes; only the OSTask fields + the CRC matter.) */
+    SP(SP_STATUS) = 0x00105;   /* clear HALT (0x1) + clear BROKE (0x4) + intr-on-break (0x100) */
 }
 
 void n64_clear(unsigned short col)
 {
-    int i; for (i = 0; i < SCREEN_W * SCREEN_H; i++) fb[i] = col;
+    dl_begin();
+    /* SetFillColor: 16bpp color packed twice into 32 bits. */
+    unsigned int c32 = ((unsigned int)col << 16) | col;
+    dl_w((G_SETFILLCOLOR << 24), c32);
+    /* FillRectangle covering the whole screen (coords in 10.2 fixed, inclusive). */
+    dl_w((G_FILLRECT << 24) | (((320 - 1) << 2) << 12) | ((240 - 1) << 2),
+         (0 << 12) | 0);
 }
 
 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);
+    int x1 = x + w - 1, y1 = y + h - 1;
+    if (x < 0) x = 0; if (y < 0) y = 0;
+    if (x1 > 319) x1 = 319; if (y1 > 239) y1 = 239;
+    if (x1 < x || y1 < y) return;
+    unsigned int c32 = ((unsigned int)col << 16) | col;
+    dl_w((G_SETFILLCOLOR << 24), c32);
+    dl_w((G_FILLRECT << 24) | ((x1 << 2) << 12) | (y1 << 2),
+         ((x << 2) << 12) | (y << 2));
 }
 
-/* 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)
+/* Triangle: a flat-shaded, screen-space triangle. The verts are already projected
+   to 2D pixels by the 3D pipeline. Rather than drive glide64's full F3DEX2 vertex/
+   matrix/combine pipeline (heavy state), we scan-convert the triangle into a span of
+   GPU FILL RECTANGLES — one per scanline. These are the SAME hardware-accelerated
+   fill-rects that clear/rect use (rasterized by glide64 on the GPU, NOT CPU pixels),
+   so it stays fast + renders correctly under the fill-cycle render state. The
+   examples draw a handful of large flat quads, so the per-scanline rect count is low. */
+static void emit_tri(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; }
+    /* sort vertices by y (y0 <= y1 <= y2) */
+    int t;
+    if (y0 > y1) { t=x0;x0=x1;x1=t; t=y0;y0=y1;y1=t; }
+    if (y1 > y2) { t=x1;x1=x2;x2=t; t=y1;y1=y2;y2=t; }
+    if (y0 > y1) { t=x0;x0=x1;x1=t; t=y0;y0=y1;y1=t; }
+    if (y2 == y0) return;                 /* degenerate */
+
+    int y;
+    for (y = y0; y <= y2; y++) {
+        if (y < 0 || y > 239) continue;
+        /* x along the long edge 0→2 */
+        int xa = x0 + (x2 - x0) * (y - y0) / (y2 - y0);
+        int xb;
+        if (y < y1) {
+            if (y1 == y0) continue;
+            xb = x0 + (x1 - x0) * (y - y0) / (y1 - y0);
+        } else {
+            if (y2 == y1) continue;
+            xb = x1 + (x2 - x1) * (y - y1) / (y2 - y1);
         }
+        if (xa > xb) { t = xa; xa = xb; xb = t; }
+        if (xa < 0) xa = 0; if (xb > 319) xb = 319;
+        if (xb < xa) continue;
+        /* one GPU fill-rect for this 1px-tall span */
+        unsigned int c32 = ((unsigned int)col << 16) | col;
+        dl_w((G_SETFILLCOLOR << 24), c32);
+        dl_w((G_FILLRECT << 24) | ((xb << 2) << 12) | (y << 2),
+             ((xa << 2) << 12) | (y << 2));
     }
 }
 
+void n64_tri2d(int x0,int y0,int x1,int y1,int x2,int y2,unsigned short col)
+{ emit_tri(x0,y0,x1,y1,x2,y2,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++) { } }
+    dl_end_and_run();
+    /* wait for the frame to scan out + the RDP to drain. */
+    { volatile int i; for (i = 0; i < 100000; 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. ── */
+/* ── input: read controller port 0 via the SI/PIF JoyBus poll. ── */
 static unsigned int read_pad(void)
 {
-    volatile unsigned int *pif = (volatile unsigned int *)0xBFC007C0; /* PIF RAM */
+    volatile unsigned int *pif = (volatile unsigned int *)0xBFC007C0;
     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 */
+    si[1] = 0x1FC007C0;
     { 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 */
+    buttons = pif[1] >> 16;
+    return (~0u) & buttons;
 }
 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) ── */
+/* ── trig (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,
@@ -127,7 +228,7 @@ static fix sin_lut(int idx) {
 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) ── */
+/* ── camera + model + projection (math unchanged; output drives emit_tri) ── */
 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)
@@ -162,7 +263,7 @@ void n64_tri3d(Vec3 a, Vec3 b, Vec3 c, unsigned short col)
     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);
+    emit_tri(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); }
@@ -171,7 +272,7 @@ 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);
+    emit_tri(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); }
@@ -181,7 +282,7 @@ 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) ── */
+/* ── HUD number (3x5 cells via filled rects) ── */
 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},

package/src/platforms/ps1/MENTAL_MODEL.md

@@ -0,0 +1,85 @@
+# PlayStation (PS1) — mental model
+
+The PS1 is a **3D machine**: a 33.87 MHz MIPS R3000A CPU + the GPU (2D/3D
+rasterizer, drawing into 1 MB VRAM) + the GTE (Geometry Transformation Engine,
+a CPU coprocessor for 3D math) + the SPU (24-voice ADPCM sound). romdev runs it on
+**beetle_psx_hw** (Mednafen PSX) built to WASM, presenting through the
+**native-gles / WebGL2 hardware GPU**.
+
+## The one thing to know about rendering
+
+PS1 homebrew draws by issuing **GPU primitives** (GP0 command packets) — not by
+writing a raw CPU framebuffer. The core is `beetle_psx_hw`, the **hardware** renderer
+(`hwRender: true`): it rasterizes the GPU command stream on the real GPU via
+GLES3/WebGL2 (through romdev's native-gles bridge), exactly like a console. So the
+bundled `psx.c` helper lib is a small **software-3D front end** (16.16 fixed-point
+transform + project + cull + painter sort) whose **back end emits GP0 flat-poly
+primitives** to the GPU — the GPU does the actual rasterization. (This differs from
+N64, which software-rasterizes into RDRAM; PS1 hands triangles to the GPU.)
+
+GP0 gotcha that cost real time: **`GP0 0x60` is a variable-size rectangle**, encoded
+as 3 words (color, top-left corner, size) — NOT a 4-vertex polygon. Feeding it
+polygon vertices stretches rects to the screen edge. Use the right command for the
+primitive (triangles = `0x20`/`0x24`/`0x28`/`0x2C` family; rects = `0x60`). Read the
+GP0 encoding carefully.
+
+## CPU / memory map (R3000A, MIPS I, 32-bit, little-endian)
+
+| Region | Address (KUSEG/KSEG) | Notes |
+|--------|----------------------|-------|
+| Main RAM | `0x8001_0000`+ (kseg0) / `0x0001_0000`+ | 2 MB. Programs load at `0x8001_0000`. |
+| Scratchpad | `0x1F80_0000` | 1 KB fast on-chip RAM |
+| Hardware I/O | `0x1F80_1000`+ | GPU (`…1810`), SPU (`…1C00`), SIO (`…1040`), DMA, timers |
+| BIOS | `0xBFC0_0000` | HLE'd by default — you don't ship a BIOS |
+
+Addresses are **little-endian**. `memory({op:'read', region:'system_ram'})` reads
+main RAM.
+
+## Booting — PS-EXE (no BIOS, no disc)
+
+PS1 boots from a **2048-byte PS-EXE header** (magic `PS-X EXE`, with `pc0` / `t_addr`
+/ `t_size` at fixed offsets). The HLE BIOS loads `t_size` bytes to `t_addr` and jumps
+to `pc0`. romdev's `build`/`cart` wrap a valid PS-EXE around your code (`wrapPsExe`) —
+no CD image, no real BIOS needed. (We never build discs; HLE + PS-EXE is enough for
+homebrew.)
+
+## Input
+
+Homebrew reads the pad from **hardware** — the SIO handshake at `0x1F80_1040`
+(transfer `0x01`, `0x42`, read the button halfword). The host's `setInput`/`run`
+holdInputs drive the emulated pad; the game polls SIO. The helper lib has a
+`pad_read()`.
+
+## Sound
+
+The SPU (24 ADPCM voices) at `0x1F80_1C00`. Samples are SPU-ADPCM in SPU RAM, keyed on
+via the voice registers. The helper lib has a minimal tone path.
+
+## MCP debug & inspection tooling — current state
+
+- **`memory({op:'read', region:'system_ram'})`** — main RAM. ✅
+- **`disasm` / `decompile`** — MIPS via rizin/Ghidra. ✅ (R3000A `jal` targets are
+  absolute VAs — the analysis buffer is base-aligned so call-following works; see
+  TROUBLESHOOTING if a fixed-VA image misbehaves.)
+- **`frame({op:'verify'})` / screenshot** — render-health + capture. ✅
+- **`cart` extract/wrap** — PS-EXE. ✅
+- **`cpu({op:'read'})`** — live R3000A register file (`romdev_mips_regs_get`: r0..r31,
+  LO, HI, PC). ✅
+- **`audioDebug({op:'inspect', chip:'spu'})`** — the SPU register block at `0x1F80_1C00`
+  (`romdev_spu_get`, the 1 KB window). ✅
+- **`breakpoint` / `watch`** — not yet (those need interpreter-step + memory-path hooks
+  patched into beetle; cpuState/audioDebug are plain reads and ARE wired).
+- **`renderingContext`** is **N/A** (false) — 3D GPU machine, no 2D tile VDP to decode.
+
+## Build pipeline
+
+`build({platform:'ps1'})` cross-compiles with the from-scratch **mips-elf-gcc → WASM**
+toolchain (little-endian libs; a small `softint.c` supplies 64-bit divide helpers on
+the LE side), then `wrapPsExe` produces the bootable PS-EXE. `#include` the bundled
+`psx.h` for the software-3D front end + GP0 emit + SIO/SPU helpers.
+
+## What's NOT bundled / hardware limits
+
+- No CD-ROM/XA/streaming or MDEC video.
+- `breakpoint`/`watch` not yet (need interpreter-step hooks; cpuState/audioDebug ARE wired).
+- `renderingContext` is N/A (3D GPU, no tile VDP).