romdevtools 0.44.0 → 0.56.1

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

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

package/src/mcp/tools/platforms.js

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

package/src/mcp/tools/project.js

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

package/src/mcp/tools/rendering-context.js

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

package/src/mcp/tools/toolchain.js

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

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