romdevtools 0.43.0 → 0.56.1

package/src/mcp/tools/watch-memory.js

@@ -206,6 +206,26 @@ export function makePressDriver(host, presses) {
   };
 }
 
+/**
+ * Flush any held-input shadow before a driven run. Back-to-back `pressDuring`
+ * runs on the SAME live host can leak the PRIOR run's held button into the next
+ * run's frame 0 — the game latches the pad into its own RAM each frame, and the
+ * new run's frame-0 logic reads that stale chord before the new input propagates.
+ * That makes a negative control (hold A to prove A does NOT reach a B-only branch)
+ * FALSE-POSITIVE on frame 1. (v0.41.0 feedback 213831 #1.) Calling this first sets
+ * the pad neutral and steps `n` frames so the game's input shadow settles to
+ * neutral; then the schedule drives a clean run. Only steps when a press schedule
+ * is actually given (no-op otherwise, so it never disturbs an inherited pad).
+ * @param {import("../../host/index.js").LibretroHost} host
+ * @param {number} n   neutral frames to settle (0 = skip)
+ * @param {boolean} driven  whether this run has a pressDuring schedule
+ */
+function settleHeldInput(host, n, driven) {
+  if (!driven || !n || n <= 0) return;
+  host.setInput({ ports: [{}, {}] });
+  host.stepFrames(n | 0);
+}
+
 // Single source of truth: the same canonical region vocabulary readMemory uses
 // (host/types.js). Derived from the host map so new regions flow through
 // automatically and the two tools never disagree. Used by the ONE primary
@@ -598,7 +618,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
 
   // breakpoint({on:write|read|pc}) STOP-on-first. on:write precision:exact=bpFindWriter
   // (core watchpoint, true PC under IRQ), precision:sampled=bpRunUntilWrite (frame PC).
-  async function bpFindWriter({ address, maxFrames = 600, pressDuring, abortIf, condition, conditionValue }) {
+  async function bpFindWriter({ address, maxFrames = 600, pressDuring, settleFrames = 0, abortIf, condition, conditionValue }) {
       const host = getHost(sessionKey);
       if (!host.watchpointSupported || !host.watchpointSupported()) {
         return jsonContent({
@@ -616,10 +636,14 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       // last write of the frame. Core support is feature-detected; if the loaded
       // core build predates condition support, we fall back to a host-side
       // 'equals' filter on the reported value (inc/dec need the core's old byte).
+      const presses0 = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+      // Flush a prior run's held input BEFORE arming, so a back-to-back driven run
+      // starts from a neutral pad (see settleHeldInput / 213831 #1).
+      settleHeldInput(host, settleFrames, presses0.length > 0);
       const wantCond = condition != null;
       const coreCond = host.setWatchpoint(address, true, wantCond ? { condition, value: conditionValue } : undefined);
       const coreHandledCond = wantCond && coreCond && coreCond.conditionApplied === true;
-      const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+      const presses = presses0;
       const pressDriver = makePressDriver(host, presses);
       // Abort-guard: sample caller-named "still valid?" bytes each frame; if any
       // changes, a driven run that DERAILED (player died → title screen, scene
@@ -761,7 +785,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       });
   }
 
-  async function bpRunUntilPC({ address, maxFrames = 600, pressDuring, captureMemory }) {
+  async function bpRunUntilPC({ address, maxFrames = 600, pressDuring, settleFrames = 0, captureMemory }) {
       const host = getHost(sessionKey);
       if (!host.pcBreakSupported || !host.pcBreakSupported()) {
         return jsonContent({
@@ -771,6 +795,10 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         });
       }
       const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+      // Flush a prior run's held-button shadow BEFORE arming (so the settle frames
+      // don't trip the breakpoint) — prevents a back-to-back negative control from
+      // false-positiving on frame 0. See settleHeldInput.
+      settleHeldInput(host, settleFrames, presses.length > 0);
       const pressDriver = makePressDriver(host, presses);
       host.setPCBreak(address, true, false);
       let hit = false, framesRun = 0, last = null;
@@ -797,9 +825,13 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
           ...(pcNow != null ? { pcNow: "$" + pcNow.toString(16).toUpperCase() } : {}),
           note: (drove
-            ? "PC never reached that address within maxFrames EVEN WITH the scheduled input — so this is " +
-              "likely the WRONG ADDRESS for the path that actually ran (a different routine handles it), " +
-              "or the address isn't an instruction boundary (mid-instruction never matches REG_PC). "
+            ? "PC never reached that address within maxFrames EVEN WITH the scheduled input. Either (a) this is " +
+              "the WRONG ADDRESS for the path that actually ran (a different routine handles it), (b) the address " +
+              "isn't an instruction boundary (mid-instruction never matches REG_PC), OR (c) the condition " +
+              "LEGITIMATELY did not occur — i.e. this hit:false is the DESIRED result of a negative control " +
+              "(you're proving input X does NOT reach this branch; e.g. an A-vs-B discriminator where only the " +
+              "other button should hit). If you confirmed the address is reachable on the positive run, (c) is " +
+              "the expected outcome, not a failure. "
             : "PC never reached that address within maxFrames. Either the code path didn't execute (drive " +
               "it with pressDuring to reach the right game state), or the address isn't an instruction " +
               "boundary (mid-instruction never matches REG_PC). ") +
@@ -1091,6 +1123,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         port: z.number().int().min(0).max(3).default(0),
         holdFrames: z.number().int().min(1).default(2),
       })).optional().describe("Schedule input while waiting (drive the game to the state that triggers the condition). If OMITTED, this run inherits whatever input({op:'set'}) last held — same as frame({op:'step'}). If GIVEN, the schedule OWNS the pad for the whole run (a prior input({op:'set'}) is ignored); use it to drive the watched window itself. Entries with OVERLAPPING windows on the same port are OR'd into a chord (e.g. b+right held while a fires mid-window), not overwritten."),
+      settleFrames: z.number().int().min(0).max(120).default(0).describe("on:'pc'/'write' with pressDuring — release the pad to NEUTRAL and step this many frames BEFORE the run, so the PRIOR run's held-button shadow (the game latches the pad into its own RAM each frame) doesn't bleed into this run's frame 0. Set ~10-30 for back-to-back A/B-discriminator / negative-control runs on the same live host (hold A to prove A does NOT reach a B-only branch) — without it the stale chord can false-positive on frame 1. No-op without pressDuring."),
       abortIf: z.array(z.object({
         region: regionStr("memory region (default system_ram)").optional(),
         offset: z.number().int().min(0).describe("byte offset within the region"),
@@ -1295,7 +1328,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
 
   // ── Range watch + coverage trace (item 2, discovery) ────────────────────────
 
-  async function wRange({ start, end, kind = "both", frames = 120, pressDuring, limit = 200, fromState, fromStatePath }) {
+  async function wRange({ start, end, kind = "both", frames = 120, pressDuring, limit = 200, dedupe = false, distinctPCsOnly = false, fromState, fromStatePath }) {
       const host = getHost(sessionKey);
       if (!host.rangeWatchSupported || !host.rangeWatchSupported()) {
         return jsonContent({ notSupported: true, events: [],
@@ -1313,20 +1346,59 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       if (presses.length) pressDriver.applyForFrame(0);
       const r = host.watchRange(start, end, kind, frames);
       pressDriver.finish();
-      const events = r.events.slice(0, limit).map((e) => ({
-        pc: "$" + e.pc.toString(16).toUpperCase(),
-        address: "$" + e.address.toString(16).toUpperCase(),
-        value: "0x" + e.value.toString(16).toUpperCase().padStart(2, "0"),
-      }));
-      // distinct PCs are the actionable summary
-      const distinctPCs = [...new Set(r.events.map((e) => e.pc))].slice(0, 64)
-        .map((p) => "$" + p.toString(16).toUpperCase());
+      const hx = (n, w = 0) => "$" + n.toString(16).toUpperCase().padStart(w, "0");
+      const hxv = (n) => "0x" + n.toString(16).toUpperCase().padStart(2, "0");
+
+      // Per-PC digest — the actionable "which routines touch this range" answer.
+      // Each writer's hit count + a sample address/value, sorted by frequency. This
+      // is what a "who writes here?" query actually needs; the per-event flood (a
+      // per-frame counter inc'd at one PC → hundreds of near-identical rows) is
+      // ~95% wasted tokens for that question. (v0.41.0 feedback 133737 N1.)
+      const byPC = new Map();
+      for (const e of r.events) {
+        let g = byPC.get(e.pc);
+        if (!g) { g = { pc: e.pc, count: 0, sampleAddress: e.address, sampleValue: e.value }; byPC.set(e.pc, g); }
+        g.count++;
+      }
+      const byPCList = [...byPC.values()].sort((a, b) => b.count - a.count).slice(0, 64)
+        .map((g) => ({ pc: hx(g.pc), count: g.count, sampleAddress: hx(g.sampleAddress), sampleValue: hxv(g.sampleValue) }));
+      const distinctPCs = byPCList.map((g) => g.pc);
+
+      // distinctPCsOnly → return JUST the digest, suppress the raw event list (the
+      // common "discover the writers" use; no per-event tokens spent).
+      if (distinctPCsOnly) {
+        return attachObserverFrame(jsonContent({
+          range: hx(start) + ".." + hx(end), kind, total: r.total, truncated: r.truncated,
+          ...(stateInfo ? { restoredFrom: stateInfo } : {}),
+          distinctPCs, byPC: byPCList,
+          note: "distinctPCsOnly: per-PC digest only (raw events suppressed). Each PC is a routine that touches the range; `count` is how often it fired, `sampleAddress`/`sampleValue` a representative hit. disasm({target:'rom'}) a PC to identify it. Drop distinctPCsOnly (or set dedupe:true) for the events." +
+            (r.truncated ? " TRUNCATED: more events than the buffer held — narrow start..end/frames." : ""),
+        }), host);
+      }
+
+      // dedupe → collapse identical (pc,address,value) rows to one with an
+      // `occurrences` count, so a byte written the same way every frame is 1 row
+      // not hundreds (parity with on:'dma's dedupe).
+      let events;
+      if (dedupe) {
+        const seen = new Map();
+        for (const e of r.events) {
+          const k = `${e.pc}|${e.address}|${e.value}`;
+          const g = seen.get(k);
+          if (g) g.occurrences++;
+          else seen.set(k, { pc: hx(e.pc), address: hx(e.address), value: hxv(e.value), occurrences: 1 });
+        }
+        events = [...seen.values()].sort((a, b) => b.occurrences - a.occurrences).slice(0, limit);
+      } else {
+        events = r.events.slice(0, limit).map((e) => ({ pc: hx(e.pc), address: hx(e.address), value: hxv(e.value) }));
+      }
       return attachObserverFrame(jsonContent({
-        range: "$" + start.toString(16).toUpperCase() + "..$" + end.toString(16).toUpperCase(),
+        range: hx(start) + ".." + hx(end),
         kind, total: r.total, returned: events.length, truncated: r.truncated,
+        ...(dedupe ? { deduped: true, uniqueEvents: events.length } : {}),
         ...(stateInfo ? { restoredFrom: stateInfo } : {}),
-        distinctPCs, events,
-        note: "distinctPCs is the actionable summary — each is a routine that touches this range; disasm({target:'rom'}) one to identify the renderer/reader. " +
+        distinctPCs, byPC: byPCList, events,
+        note: "distinctPCs/byPC is the actionable summary — each PC is a routine that touches this range; disasm({target:'rom'}) one to identify the renderer/reader. For a 'who writes here?' query, distinctPCsOnly:true returns JUST the digest (no per-event flood); dedupe:true collapses per-frame churn to unique (pc,address,value) rows with `occurrences`. " +
           (r.truncated ? "TRUNCATED: more events than the buffer held — narrow `start..end` or `frames` for the full set." : ""),
       }), host);
   }
@@ -1361,7 +1433,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "• on:'mem' — the power tool: answer 'what code is touching this RAM byte?' OR extract a frame-accurate event timeline (music-driver note onsets, physics arcs). Reports every frame that changed a watched byte as {frame,offset,before,after,pc}. " +
     "Extras: `ranges:[{region,offset,length,label}]` watches MANY disjoint regions in ONE pass (identical frames); `onChange:'reset'|'increase'|'decrease'|'any'` edge filter (reset = counter-reload = the note-onset signal); `valueFilter:{min,max}`; `format:'series'` = compact columnar value-vs-frame curve (~10× smaller for a ramp); `sampleEvery`; `groupByPC` (collapse by sampled PC); `cheatLabels` (auto-name addresses from the cheat DB); `outputPath` streams all events as NDJSON; `stopOnFirst` exits on the first match. " +
     "**CAVEAT: frame-level, not instruction-level (last value per frame); the sampled `pc` is a frame-boundary sample — for ISR-driven writes use breakpoint({on:'write', precision:'exact'}) for the real writer.**\n" +
-    "• on:'range' — DISCOVERY: log EVERY instruction that reads or writes ANYWHERE in [start,end]. The fix for 'I don't know which PC touches this'. Returns {pc,address,value}[] + the actionable distinctPCs. (Ring-buffered: `truncated:true` if it overflows.) `fromState`/`fromStatePath` restores a savestate FIRST so the trace runs from a known moment (jump to the boss, then see what writes HP) — deterministic + repeatable.\n" +
+    "• on:'range' — DISCOVERY: log EVERY instruction that reads or writes ANYWHERE in [start,end]. The fix for 'I don't know which PC touches this'. Returns {pc,address,value}[] + the actionable distinctPCs + a per-PC digest (byPC). For a pure 'who writes here?' query, `distinctPCsOnly:true` returns JUST the digest (no per-event flood — a per-frame counter inc'd at one PC otherwise floods hundreds of near-identical rows); `dedupe:true` collapses identical (pc,address,value) events to one row with `occurrences`. (Ring-buffered: `truncated:true` if it overflows.) `fromState`/`fromStatePath` restores a savestate FIRST so the trace runs from a known moment (jump to the boss, then see what writes HP) — deterministic + repeatable.\n" +
     "• on:'pc' — DISCOVERY (coverage trace): record every DISTINCT PC executed within [start,end] — 'what code runs here?'. Log execution in the bank where you suspect the renderer lives during the moment it draws, then disassemble the PCs. Also takes `fromState`/`fromStatePath` to trace from a restored moment.\n" +
     "• on:'dma' — GENESIS ONLY: trace mem→VDP DMAs (the answer to 'this name/portrait/logo is a pre-rendered bitmap DMA'd into VRAM — WHERE in ROM?', which on:'write' can't catch). `precision:'exact'` (default) logs every mem→VDP DMA with its VRAM DESTINATION + ROM SOURCE + length (filter by `vramDest`±`destWindow`; `dedupe` collapses the per-frame refresh; `sourceFilter:'rom-only'` drops RAM→VRAM noise; catches a same-frame second DMA). `precision:'sampled'` is the cheap frame-sampled source-register read (may miss two DMAs in one frame, dest-agnostic). `perFrame:true` switches to FEEL/PERF MODE: a per-frame timeline of VDP-DMA WORK ({frame,dmas,bytes,romBytes,ramBytes} + peakFrame + `spikes`) — the cheap 'why does horizontal movement feel choppy?' diagnostic (a per-frame byte spike = too much VDP work in the loop, e.g. a tilemap rewrite). On non-Genesis cores returns `notSupported`.\n" +
     "• on:'copy' — ALL 14 PLATFORMS: log every write landing in a VRAM/dest address window [start,end] with the EXECUTING instruction's PC — the generic answer to 'this tile/nametable/portrait on screen: which routine uploads it?'. Port-based video memory (NES $2007, SNES $2118/19 — incl. the DMA path, PCE VWR, MSX/SMS/GG VDP data port, Genesis data port) is hooked INSIDE the core, so `start`/`end` are VRAM addresses (NES PPU $0000-$3FFF; SNES VRAM byte addr; PCE VRAM word addr; MSX/SMS/GG VRAM addr). Direct-mapped platforms (GB/GBC $8000-$9FFF, GBA 0x06000000+, C64/Lynx/7800 RAM framebuffers) route through the CPU-address range log automatically — pass CPU addresses there. Follow up with breakpoint({on:'pc', address: pc}) to get registersAtHit at the uploader.",
@@ -1385,6 +1457,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       stopOnFirst: z.boolean().default(false).describe("on:'mem' — stop on the first filter-passing change instead of running the full duration. (For a true stop-on-first breakpoint, prefer the `breakpoint` tool.)"),
       // on:'range'
       kind: z.enum(["read", "write", "both"]).default("both").describe("on:'range' — watch reads, writes, or both."),
+      distinctPCsOnly: z.boolean().default(false).describe("on:'range' — return JUST the per-PC digest (distinctPCs + byPC[{pc,count,sampleAddress,sampleValue}]) and SUPPRESS the raw event list. The token-cheap form of the common 'which routines touch this range?' query — a per-frame counter inc'd at one PC floods hundreds of near-identical events otherwise."),
       // on:'range' / on:'pc' window
       start: z.number().int().min(0).optional().describe("on:'range'/'pc' — low CPU address of the window."),
       end: z.number().int().min(0).optional().describe("on:'range'/'pc' — high CPU address (inclusive)."),
@@ -1397,7 +1470,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       precision: z.enum(["exact", "sampled"]).default("exact").describe("on:'dma' — exact=per-DMA core log with VRAM dest + ROM source (catches same-frame DMAs); sampled=frame-sampled source-register read (cheaper, may miss two DMAs in one frame, dest-agnostic). Ignored when perFrame:true."),
       vramDest: z.number().int().min(0).optional().describe("on:'dma' precision:'exact' — keep only DMAs whose VRAM destination is within ±`destWindow` of this address."),
       destWindow: z.number().int().min(0).default(0x40).describe("on:'dma' precision:'exact' — match window around vramDest (default 64 bytes ≈ 1 tile)."),
-      dedupe: z.boolean().default(true).describe("on:'dma' precision:'exact' — collapse identical DMAs (same dest+source+length+code) to one entry with an `occurrences` count (default on)."),
+      dedupe: z.boolean().optional().describe("Collapse identical events to one entry with an `occurrences` count. on:'dma' precision:'exact' — identical DMAs (same dest+source+length+code), DEFAULT ON. on:'range' — identical (pc,address,value) writes, DEFAULT OFF (turns per-frame churn from hundreds of rows into a few)."),
       sourceFilter: z.enum(["all", "rom-only", "ram-only"]).default("all").describe("on:'dma' precision:'exact' — 'rom-only' drops the RAM→VRAM per-frame refresh noise; 'ram-only' keeps only it."),
       romPreviewBytes: z.number().int().min(0).max(64).default(0).describe("on:'dma' — bytes of the ROM source to preview per DMA (exact default 0; sampled default 16)."),
       minLengthBytes: z.number().int().min(0).max(65536).default(0).describe("on:'dma' precision:'sampled' — ignore DMAs shorter than this many bytes (filters tiny scroll/sprite updates so graphic uploads stand out)."),

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);
+}

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

@@ -0,0 +1,68 @@
+/* n64.h — N64 (R4300) helper lib with a software 3D pipeline, for romdev.
+ *
+ * The N64 is a 3D machine; this is a real software 3D engine (identical fixed-point
+ * math to the PS1 lib, so games port directly) with an N64 framebuffer backend: a
+ * 320x240 16-bit (RGBA5551) framebuffer in RDRAM that the Video Interface scans out,
+ * and a software triangle rasterizer (the RDP is far more complex; direct FB writes
+ * are portable + reliable). Big-endian.
+ *
+ * Build: build({ platform:"n64", language:"c" }) → a self-booting .z64 (our clean
+ * IPL3 DMAs the game to RDRAM and jumps in). main() loops forever.
+ */
+#ifndef ROMDEV_N64_H
+#define ROMDEV_N64_H
+
+typedef int fix; /* 16.16 */
+#define FIX(n)   ((fix)((n) << 16))
+#define FIXF(f)  ((fix)((f) * 65536.0f))
+#define FMUL(a,b) ((fix)(((long long)(a) * (b)) >> 16))
+#define FDIV(a,b) ((fix)(((long long)(a) << 16) / (b)))
+#define F2I(a)   ((a) >> 16)
+
+typedef struct { fix x, y, z; } Vec3;
+
+#define SCREEN_W 320
+#define SCREEN_H 240
+
+/* RGBA5551 color (the VI framebuffer format): 5-5-5-1. */
+#define RGB(r,g,b) ((unsigned short)((((r)>>3)<<11)|(((g)>>3)<<6)|(((b)>>3)<<1)|1))
+
+/* controller digital buttons (active-high after read). */
+#define PAD_A      0x8000
+#define PAD_B      0x4000
+#define PAD_Z      0x2000
+#define PAD_START  0x1000
+#define PAD_UP     0x0800
+#define PAD_DOWN   0x0400
+#define PAD_LEFT   0x0200
+#define PAD_RIGHT  0x0100
+#define PAD_L      0x0020
+#define PAD_R      0x0010
+
+/* ── framebuffer / 2D ── */
+void n64_init(void);
+void n64_clear(unsigned short col);
+void n64_rect(int x, int y, int w, int h, unsigned short col);
+void n64_tri2d(int x0,int y0,int x1,int y1,int x2,int y2,unsigned short col);
+void n64_flip(void);          /* present the framebuffer (swap + wait vblank) */
+
+/* ── input ── */
+unsigned int n64_pad(void);
+int n64_pressed(unsigned int mask);
+
+/* ── 3D pipeline (same API as the PS1 lib) ── */
+void n64_camera(fix ex, fix ey, fix ez, fix yaw, fix pitch);
+void n64_model(fix tx, fix ty, fix tz, fix yaw);
+void n64_tri3d(Vec3 a, Vec3 b, Vec3 c, unsigned short col);
+void n64_quad3d(Vec3 a, Vec3 b, Vec3 c, Vec3 d, unsigned short col);
+void n64_tri3d_nc(Vec3 a, Vec3 b, Vec3 c, unsigned short col);
+void n64_quad3d_nc(Vec3 a, Vec3 b, Vec3 c, Vec3 d, unsigned short col);
+
+/* ── misc ── */
+fix n64_sin(fix a);
+fix n64_cos(fix a);
+unsigned int n64_rand(void);
+void n64_srand(unsigned int seed);
+void n64_number(int x, int y, unsigned int value, unsigned short col);
+
+#endif