romdevtools 0.44.0 → 0.70.0

package/examples/ps1/sports/main.c

@@ -0,0 +1,127 @@
+/*
+ * sports/main.c — SLAM COURT: a 3D PlayStation sports game (air-hockey / pong).
+ *
+ * A 3D playfield seen in perspective: you control the near paddle, the CPU the far
+ * one. A ball bounces down the court in 3D (X across, Z into the screen); rally it
+ * past the CPU to score, miss and the CPU scores. First to 7. Title -> match ->
+ * game-over. The whole court is drawn with the perspective pipeline; the ball's
+ * size changes with depth, selling the 3D.
+ *
+ * Build: build({ platform:"ps1", language:"c" }). Controls: LEFT/RIGHT move your
+ * paddle, START begin/restart.
+ *
+ * 3D technique: the court floor is a big no-cull quad; paddles + ball are cubes at
+ * world positions. The CPU paddle tracks the ball's X with a capped speed. 16.16 fp.
+ */
+#include "psx.h"
+
+enum { TITLE, PLAY, OVER };
+
+static fix px;               /* player paddle X (near, z = small) */
+static fix cx;               /* cpu paddle X (far, z = big) */
+static fix bx, bz, bvx, bvz; /* ball position + velocity */
+static int you, cpu, state;
+static unsigned int prev_pad;
+
+#define COURT_HW  FIX(5)     /* court half-width */
+#define NEAR_Z    FIX(3)
+#define FAR_Z     FIX(22)
+
+static void draw_cube_at(fix x, fix y, fix z, fix s, unsigned int col)
+{
+    Vec3 v[8]; int i;
+    static const int sx[8]={-1,1,1,-1,-1,1,1,-1},sy[8]={-1,-1,1,1,-1,-1,1,1},sz[8]={-1,-1,-1,-1,1,1,1,1};
+    psx_model(x,y,z,0);
+    for(i=0;i<8;i++){v[i].x=sx[i]*s;v[i].y=sy[i]*s;v[i].z=sz[i]*s;}
+    psx_quad3d(v[0],v[1],v[2],v[3],col); psx_quad3d(v[5],v[4],v[7],v[6],col);
+    psx_quad3d(v[4],v[0],v[3],v[7],col); psx_quad3d(v[1],v[5],v[6],v[2],col);
+    psx_quad3d(v[4],v[5],v[1],v[0],col); psx_quad3d(v[3],v[2],v[6],v[7],col);
+}
+
+static void serve(int toward_cpu)
+{
+    bx = 0; bz = (NEAR_Z + FAR_Z) >> 1;
+    bvx = (psx_rand() & 1) ? FIXF(0.12f) : FIXF(-0.12f);
+    bvz = toward_cpu ? FIXF(0.45f) : FIXF(-0.45f);
+}
+
+static void reset_game(void) { px = 0; cx = 0; you = 0; cpu = 0; serve(1); }
+
+static void update(void)
+{
+    unsigned int pad = psx_pad();
+    if (pad & PAD_LEFT)  px -= FIXF(0.22f);
+    if (pad & PAD_RIGHT) px += FIXF(0.22f);
+    if (px < -COURT_HW) px = -COURT_HW; if (px > COURT_HW) px = COURT_HW;
+
+    /* cpu tracks the ball, capped */
+    { fix d = bx - cx; if (d > FIXF(0.16f)) d = FIXF(0.16f); if (d < -FIXF(0.16f)) d = -FIXF(0.16f); cx += d; }
+
+    bx += bvx; bz += bvz;
+    if (bx < -COURT_HW || bx > COURT_HW) bvx = -bvx;  /* side walls */
+
+    /* near paddle (player) */
+    if (bz <= NEAR_Z) {
+        fix d = bx - px; if (d < 0) d = -d;
+        if (d < FIX(2)) { bvz = -bvz; bz = NEAR_Z; bvx += (bx - px) >> 4; }
+        else { cpu++; if (cpu >= 7) { state = OVER; } else serve(1); }
+    }
+    /* far paddle (cpu) */
+    if (bz >= FAR_Z) {
+        fix d = bx - cx; if (d < 0) d = -d;
+        if (d < FIX(2)) { bvz = -bvz; bz = FAR_Z; }
+        else { you++; if (you >= 7) { state = OVER; } else serve(0); }
+    }
+    prev_pad = pad;
+}
+
+static void render(void)
+{
+    Vec3 a,b,c,d;
+    psx_clear(RGB(20, 40, 30));
+    psx_camera(0, FIX(4), FIX(-1), 0, FIXF(-0.30f)); /* look down the court */
+
+    /* court floor */
+    a.x=-COURT_HW; a.y=0; a.z=NEAR_Z; b.x=COURT_HW; b.y=0; b.z=NEAR_Z;
+    c.x=COURT_HW;  c.y=0; c.z=FAR_Z;  d.x=-COURT_HW; d.y=0; d.z=FAR_Z;
+    psx_quad3d_nc(a,b,c,d, RGB(40, 90, 60));
+    /* center line */
+    a.x=-COURT_HW; a.z=(NEAR_Z+FAR_Z)>>1; b.x=COURT_HW; b.z=a.z;
+    c.x=COURT_HW; c.z=a.z+FIXF(0.3f); d.x=-COURT_HW; d.z=c.z;
+    a.y=FIXF(0.02f);b.y=a.y;c.y=a.y;d.y=a.y;
+    psx_quad3d_nc(a,b,c,d, RGB(220,220,220));
+
+    draw_cube_at(px, FIXF(0.5f), NEAR_Z, FIXF(0.9f), RGB(80, 180, 255)); /* you */
+    draw_cube_at(cx, FIXF(0.5f), FAR_Z,  FIXF(0.9f), RGB(255, 100, 80)); /* cpu */
+    draw_cube_at(bx, FIXF(0.5f), bz, FIXF(0.4f), RGB(255, 240, 120));    /* ball */
+
+    psx_number(40, 8, (unsigned)you, RGB(80, 180, 255));
+    psx_number(240, 8, (unsigned)cpu, RGB(255, 100, 80));
+}
+
+int main(void)
+{
+    psx_init();
+    psx_srand(0x5A11);
+    state = TITLE; prev_pad = 0;
+    for (;;) {
+        unsigned int pad = psx_pad();
+        if (state == TITLE) {
+            static fix t; t += FIX(3);
+            psx_clear(RGB(15, 30, 25));
+            psx_camera(0, 0, FIX(-1), 0, 0);
+            draw_cube_at(0, 0, FIX(6), FIX(1), RGB(80, 180, 255));
+            if ((pad & PAD_START) && !(prev_pad & PAD_START)) { reset_game(); state = PLAY; }
+            prev_pad = pad;
+        } else if (state == PLAY) { update(); render(); }
+        else {
+            psx_clear(RGB(8, 20, 16));
+            psx_number(120, 100, (unsigned)you, RGB(80, 180, 255));
+            psx_number(160, 100, (unsigned)cpu, RGB(255, 100, 80));
+            if ((pad & PAD_START) && !(prev_pad & PAD_START)) { reset_game(); state = PLAY; }
+            prev_pad = pad;
+        }
+        psx_vsync();
+    }
+    return 0;
+}

package/examples/ps1/sprite_move/main.c

@@ -0,0 +1,38 @@
+/*
+ * sprite_move/main.c — PS1 starter (mips-elf-gcc + the bundled psx.h helper).
+ *
+ * Boots a visible 320x240 display and animates a colored box bouncing around the
+ * screen — the canonical "GPU is alive, here's a moving primitive" PS1 starter.
+ * Exercises the whole helper lib: psx_init (GPU bring-up), psx_clear + psx_rect
+ * (flat polygons), psx_vsync (pacing).
+ *
+ * Build with: build({ platform:"ps1", language:"c" }) — language defaults to C.
+ * Output is a PS-EXE the HLE BIOS loads at 0x80010000; main() loops forever
+ * (no OS to return to).
+ *
+ * PS1 NOTE: there is no tile/sprite/nametable hardware — the GPU draws polygons
+ * into a framebuffer. A "sprite" here is a textured/flat quad you draw each frame.
+ */
+#include "psx.h"
+
+int main(void)
+{
+    int x = 40, y = 40, dx = 2, dy = 2;
+    const int W = 32, H = 32;
+
+    psx_init();
+
+    for (;;) {
+        /* move + bounce */
+        x += dx; y += dy;
+        if (x < 0 || x + W > 320) dx = -dx;
+        if (y < 0 || y + H > 240) dy = -dy;
+        if (x < 0) x = 0; if (x + W > 320) x = 320 - W;
+        if (y < 0) y = 0; if (y + H > 240) y = 240 - H;
+
+        psx_clear(RGB(20, 30, 60));            /* deep-blue background */
+        psx_rect(x, y, W, H, RGB(255, 180, 40)); /* the bouncing box */
+        psx_vsync();
+    }
+    return 0;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "romdevtools",
-  "version": "0.44.0",
-  "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
+  "version": "0.70.0",
+  "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 17 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, PlayStation, N64, Dreamcast, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",
   "bin": {
@@ -58,6 +58,9 @@
     "romdev-core-geargrafx": "0.7.0",
     "romdev-core-gpgx": "0.12.0",
     "romdev-core-handy": "0.7.0",
+    "romdev-core-flycast": "0.1.0",
+    "romdev-core-parallel-n64": "0.1.0",
+    "romdev-core-beetle-psx-hw": "0.1.0",
     "romdev-core-prosystem": "0.8.0",
     "romdev-core-vice": "0.9.0",
     "romdev-famitone": "0.1.0",
@@ -67,8 +70,10 @@
     "romdev-platform-snes": "0.8.0",
     "romdev-toolchain-cc65": "0.1.1",
     "romdev-toolchain-m68k-gcc": "0.2.0",
+    "romdev-toolchain-mips-gcc": "0.1.0",
     "romdev-toolchain-rgbds": "0.1.0",
     "romdev-toolchain-sdcc": "0.2.0",
+    "romdev-toolchain-sh-gcc": "0.1.0",
     "romdev-toolchain-vasm": "0.1.0",
     "romdev-xgm2": "0.1.0",
     "romdev_game_codes": "0.1.0",
@@ -77,6 +82,10 @@
     "yauzl": "^3.3.1",
     "zod": "^4.4.3"
   },
+  "optionalDependencies": {
+    "native-gles": "^0.5.0",
+    "webgl-node": "^1.2.0"
+  },
   "files": [
     "src",
     "!src/**/*.test.js",

package/src/analysis/analyze.js

@@ -12,7 +12,7 @@
 // resolved by the existing disasm mappers — analysis here is whole-file.
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { runRizinJson, RIZIN_ARCH } from "./rizin.js";
+import { runRizinJson, RIZIN_ARCH, RIZIN_ENDIAN } from "./rizin.js";
 import { decompileFunction, SLEIGH_LANGID } from "./decompile.js";
 import { registersForPlatform } from "../platforms/common/registers.js";
 
@@ -133,13 +133,80 @@ export function sniffPlatform(p) {
   if (/\.(lnx|lyx)$/i.test(p)) return "lynx";
   if (/\.gba$/i.test(p)) return "gba";
   if (/\.pce$/i.test(p)) return "pce";
+  if (/\.(z64|n64|v64)$/i.test(p)) return "n64";
+  if (/\.(psexe|psx)$/i.test(p)) return "ps1"; // .exe/.bin ambiguous — pass platform explicitly
+  if (/\.(cdi|gdi)$/i.test(p)) return "dreamcast"; // DC disc images; .elf is cross-platform — pass platform explicitly
   if (/\.(gen|md|bin)$/i.test(p)) return "genesis";
   return null;
 }
 
 /** rizin asm.bits per arch (analysis defaults; rizin's loader usually sets
  * these for recognized formats, but raw blobs need a hint). */
-const BITS = { arm: 32, m68k: 32, snes: 16 };
+const BITS = { arm: 32, m68k: 32, snes: 16, mips: 32, sh: 32 };
+
+/**
+ * The rizin analysis-SEED command for a context. For the 8/16-bit platforms
+ * rizin's `aaa` recognizes the bin format / vectors and seeds itself. For a RAW
+ * MIPS image (N64/PS1) there's no recognized entry, so `aaa` finds nothing —
+ * instead define a function at the code start and recursively analyze its call
+ * graph (`af` + `aac`), which surfaces the real function tree (verified: 251
+ * functions on a real libdragon N64 ROM where `aaa` found 0).
+ * @param {{arch:string, codeStart:number}} ctx
+ * @returns {string} the seed command (no trailing semicolon)
+ */
+function analysisSeed({ arch, codeStart }) {
+  // MIPS (N64/PS1) and SH-4 (Dreamcast) are raw code images with no rizin-recognized
+  // entry, so `aaa` finds nothing — seed a function at the code start + recursively
+  // analyze its call graph (`af` + `aac`). The 8/16-bit bin formats self-seed via aaa.
+  if (arch === "mips" || arch === "sh") {
+    const at = "0x" + (codeStart || 0).toString(16);
+    return `af @ ${at}; aac @ ${at}`;
+  }
+  return "aaa";
+}
+
+/** MIPS analysis runs FLAT (rizin ignores -B on a raw malloc:// buffer), so rizin
+ *  reports FILE-OFFSET addresses. For PS1 loadContext left-pads the .text so flat
+ *  offset == the VA's low 20 bits (see there); we add the VA's HIGH bits back as
+ *  `rebase` so callers get real VAs that round-trip through the decompile
+ *  VA→fileOffset math. N64 (.z64) keeps its absolute VAs baked into the code and is
+ *  analyzed flat from codeStart, so no rebase. */
+function mipsAnalysisBase({ platform, loadBase, codeStart }) {
+  // PS1 (left-padded to the VA's low 20 bits) and Dreamcast (same, loadBase
+  // 0x8c010000) need the VA's HIGH bits added back so addresses round-trip. N64 runs
+  // flat with VAs already baked in (no rebase).
+  const padded = (platform === "ps1" || platform === "dreamcast") && loadBase;
+  const rebase = padded ? (loadBase & 0xfff00000) >>> 0 : 0;
+  return { baddr: undefined, seedAt: codeStart, rebase };
+}
+
+/**
+ * Normalize an N64 ROM to BIG-ENDIAN (.z64) byte order. Dumps come in three
+ * orders, distinguished by the first 4 bytes of the header:
+ *   .z64 (big)    80 37 12 40   — native; no change
+ *   .v64 (byteswap)37 80 40 12  — swap every 2 bytes
+ *   .n64 (little) 40 12 37 80   — swap every 4 bytes
+ * MIPS analysis wants the big-endian image so addresses + instruction words line up.
+ * @param {Uint8Array} bytes
+ * @returns {{ bytes: Uint8Array, reordered: string|null }}
+ */
+function normalizeN64ByteOrder(bytes) {
+  if (bytes.length < 4) return { bytes, reordered: null };
+  const b = bytes;
+  const is = (a, c, d, e) => b[0] === a && b[1] === c && b[2] === d && b[3] === e;
+  if (is(0x80, 0x37, 0x12, 0x40)) return { bytes, reordered: null }; // .z64 big — native
+  if (is(0x37, 0x80, 0x40, 0x12)) { // .v64 byteswapped — swap pairs
+    const out = new Uint8Array(b.length & ~1);
+    for (let i = 0; i + 1 < b.length; i += 2) { out[i] = b[i + 1]; out[i + 1] = b[i]; }
+    return { bytes: out, reordered: "v64 (byteswapped) → z64" };
+  }
+  if (is(0x40, 0x12, 0x37, 0x80)) { // .n64 little — swap dwords
+    const out = new Uint8Array(b.length & ~3);
+    for (let i = 0; i + 3 < b.length; i += 4) { out[i] = b[i + 3]; out[i + 1] = b[i + 2]; out[i + 2] = b[i + 1]; out[i + 3] = b[i]; }
+    return { bytes: out, reordered: "n64 (little-endian dwords) → z64" };
+  }
+  return { bytes, reordered: null }; // unknown header — leave as-is
+}
 
 /** Build the common rizin invocation context for a ROM + platform. Returns
  * { romBytes, arch, bits, note } — arch null means let rizin sniff. */
@@ -175,11 +242,86 @@ async function loadContext(romPath, platformOverride) {
     loadBase = romBytes[0] | (romBytes[1] << 8);
     romBytes = romBytes.subarray(2);
   }
+  const warningsEarly = [];
+  // N64: normalize to big-endian (.z64) byte order, then the ROM header's entry
+  // point (big-endian word at 0x08) is the CPU load base. The 0x1000-byte header
+  // (IPL3 bootcode) precedes the game; rizin analyzes the whole image but the
+  // entry tells functions where code starts.
+  let codeStart = 0; // file offset where executable code begins (post-header)
+  if (platform === "n64") {
+    const norm = normalizeN64ByteOrder(romBytes);
+    romBytes = norm.bytes;
+    if (norm.reordered) warningsEarly.push(`N64 ROM was ${norm.reordered} byte order — normalized to z64 (big-endian) for analysis.`);
+    if (romBytes.length >= 0x0c) {
+      // entry point: big-endian 32-bit at offset 0x08.
+      loadBase = (romBytes[0x08] << 24) | (romBytes[0x09] << 16) | (romBytes[0x0a] << 8) | romBytes[0x0b];
+    }
+    // The IPL3 bootcode occupies the first 0x1000 bytes; game code starts after it.
+    // rizin's `aaa` doesn't recognize a raw N64 ROM's entry, so analysis is seeded
+    // here (see ANALYSIS_SEED).
+    codeStart = 0x1000;
+  }
+  // PS1 PS-EXE: a 2048-byte header; the load (t_addr) is a little-endian word at
+  // 0x18, and the code follows the header. Strip the header so rizin sees code at
+  // the load address. A raw .bin (no PS-EXE magic) is left flat.
+  if (platform === "ps1" && romBytes.length >= 0x800 &&
+      romBytes[0] === 0x50 && romBytes[1] === 0x53 && romBytes[2] === 0x2d && romBytes[3] === 0x58) { // "PS-X"
+    loadBase = (romBytes[0x18] | (romBytes[0x19] << 8) | (romBytes[0x1a] << 16) | (romBytes[0x1b] << 24)) >>> 0;
+    const text = romBytes.subarray(0x800);
+    // rizin ignores -B on a raw malloc:// buffer, so it addresses flat from 0. PS1
+    // jal targets are ABSOLUTE VAs (e.g. jal 0x80010518) — to let rizin follow them,
+    // left-pad the .text by the load address's low 20 bits so flat offset N == the
+    // VA's low bits (jal masks to a 28-bit region). The high bits (0x80000000) are
+    // added back as `rebase`. Without this, every cross-function call dangles and
+    // only the entry blob is discovered. (Cap the pad so a weird t_addr can't OOM.)
+    const lowPad = loadBase & 0x000fffff;
+    if (lowPad > 0 && lowPad <= 0x200000) {
+      const padded = new Uint8Array(lowPad + text.length);
+      padded.set(text, lowPad);
+      romBytes = padded;
+      codeStart = lowPad;
+    } else {
+      romBytes = text;
+    }
+  }
+  // Dreamcast SH-4: KOS produces an ELF (load base 0x8c010000) or a stripped flat
+  // binary. For an ELF, strip to the first PT_LOAD segment's bytes + take its vaddr
+  // as loadBase. Like PS1, SH-4 uses PC-relative + absolute addressing, so left-pad
+  // so flat offset == the VA's low bits and add the high bits back as rebase.
+  if (platform === "dreamcast") {
+    let text = romBytes, loadVa = 0x8c010000;
+    if (romBytes.length >= 0x34 && romBytes[0] === 0x7f && romBytes[1] === 0x45 &&
+        romBytes[2] === 0x4c && romBytes[3] === 0x46) { // "\x7fELF"
+      // ELF32 LE: e_phoff @0x1c, e_phentsize @0x2a, e_phnum @0x2c. Find first PT_LOAD.
+      const u32 = (o) => (romBytes[o] | (romBytes[o + 1] << 8) | (romBytes[o + 2] << 16) | (romBytes[o + 3] << 24)) >>> 0;
+      const u16 = (o) => romBytes[o] | (romBytes[o + 1] << 8);
+      const phoff = u32(0x1c), phentsize = u16(0x2a), phnum = u16(0x2c);
+      for (let i = 0; i < phnum; i++) {
+        const ph = phoff + i * phentsize;
+        if (u32(ph) === 1) { // PT_LOAD
+          const p_offset = u32(ph + 4), p_vaddr = u32(ph + 8), p_filesz = u32(ph + 16);
+          loadVa = p_vaddr >>> 0;
+          text = romBytes.subarray(p_offset, p_offset + p_filesz);
+          break;
+        }
+      }
+    }
+    loadBase = loadVa >>> 0;
+    const lowPad = loadBase & 0x000fffff;
+    if (lowPad > 0 && lowPad <= 0x200000) {
+      const padded = new Uint8Array(lowPad + text.length);
+      padded.set(text, lowPad);
+      romBytes = padded;
+      codeStart = lowPad;
+    } else {
+      romBytes = text;
+    }
+  }
 
   // A6: container/format sniff. Some dumps are interleaved/headered such that a
   // FLAT read scrambles every byte → fake "bad instruction" noise everywhere.
   // Detect + auto-correct, and warn so a flat disasm isn't silently wrong.
-  const warnings = [];
+  const warnings = [...warningsEarly];
   if (platform === "genesis") {
     const smd = deinterleaveSmd(romBytes);
     if (smd) {
@@ -188,7 +330,7 @@ async function loadContext(romPath, platformOverride) {
         "auto-deinterleaved before analysis. A flat read of the original would scramble every instruction.");
     }
   }
-  return { platform, romBytes, arch, bits: BITS[arch], approx, loadBase, warnings };
+  return { platform, romBytes, arch, bits: BITS[arch], endian: RIZIN_ENDIAN[platform], approx, loadBase, codeStart, warnings };
 }
 
 /** Detect + reverse Sega Mega Drive SMD interleaving. An .smd dump is a 512-byte
@@ -227,11 +369,12 @@ function hx(n) { return "0x" + (n >>> 0).toString(16); }
  * @returns {{platform, count, functions: Array<{address, name, size, nbbs, cc, callers, callees}>}}
  */
 export async function analyzeFunctions(romPath, platformOverride) {
-  const { platform, romBytes, arch, bits, loadBase, warnings } = await loadContext(romPath, platformOverride);
-  const fns = await runRizinJson({ romBytes, arch, bits, baddr: loadBase || undefined, commands: "aaa; aflj" });
+  const { platform, romBytes, arch, bits, endian, loadBase, codeStart, warnings } = await loadContext(romPath, platformOverride);
+  const { baddr, seedAt, rebase } = mipsAnalysisBase({ arch, platform, loadBase, codeStart });
+  const fns = await runRizinJson({ romBytes, arch, bits, endian, baddr, commands: `${analysisSeed({ arch, codeStart: seedAt })}; aflj` });
   const functions = fns.map((f) => ({
-    address: f.offset,
-    addressHex: hx(f.offset),
+    address: (f.offset + rebase) >>> 0,
+    addressHex: hx((f.offset + rebase) >>> 0),
     name: f.name,
     size: f.size,
     nbbs: f.nbbs,           // basic-block count
@@ -269,30 +412,35 @@ export async function analyzeFunctions(romPath, platformOverride) {
  */
 export async function analyzeCfg(romPath, address, platformOverride) {
   if (address == null) throw new Error("analyze cfg: address required");
-  const { platform, romBytes, arch, bits, loadBase } = await loadContext(romPath, platformOverride);
+  const { platform, romBytes, arch, bits, endian, loadBase, codeStart } = await loadContext(romPath, platformOverride);
   // afbj = basic blocks of the function as JSON: each block has addr/size/jump/
   // fail/ninstr. `jump` is the taken edge; `fail` (present only on conditional
   // blocks) is the fall-through. This is the structured CFG source — `agf json`
   // only gives a text body blob with untyped out_nodes.
+  // MIPS: seed the call graph first (the address is a vaddr from `functions`,
+  // which rizin recovers during `aac`). PS1 rebases to loadBase so the vaddr lines up.
+  const { baddr, seedAt, rebase } = mipsAnalysisBase({ arch, platform, loadBase, codeStart });
+  const flat = ((address >>> 0) - rebase) >>> 0; // VA → flat offset rizin uses
+  const rb = (a) => (a == null ? a : (a + rebase) >>> 0);
   const blocks = await runRizinJson({
-    romBytes, arch, bits, baddr: loadBase || undefined,
-    commands: `aaa; af @ ${hx(address)}; afbj @ ${hx(address)}`,
+    romBytes, arch, bits, endian, baddr,
+    commands: `${analysisSeed({ arch, codeStart: seedAt })}; af @ ${hx(flat)}; afbj @ ${hx(flat)}`,
   });
   if (!Array.isArray(blocks) || blocks.length === 0) {
     return { platform, arch, address, addressHex: hx(address), nodes: [], edges: [], note: "no function/blocks at address" };
   }
   const nodes = blocks.map((b) => ({
-    id: b.addr,
-    address: b.addr,
-    addressHex: hx(b.addr),
+    id: rb(b.addr),
+    address: rb(b.addr),
+    addressHex: hx(rb(b.addr)),
     size: b.size,
     ninstr: b.ninstr,
   }));
   const edges = [];
   for (const b of blocks) {
     const conditional = b.fail != null;
-    if (b.jump != null) edges.push({ from: b.addr, to: b.jump, type: conditional ? "branch_true" : "jump_or_fall" });
-    if (b.fail != null) edges.push({ from: b.addr, to: b.fail, type: "branch_false" });
+    if (b.jump != null) edges.push({ from: rb(b.addr), to: rb(b.jump), type: conditional ? "branch_true" : "jump_or_fall" });
+    if (b.fail != null) edges.push({ from: rb(b.addr), to: rb(b.fail), type: "branch_false" });
   }
   return {
     platform, arch,
@@ -308,10 +456,13 @@ export async function analyzeCfg(romPath, address, platformOverride) {
  */
 export async function analyzeXrefs(romPath, address, platformOverride) {
   if (address == null) throw new Error("analyze xrefs: address required");
-  const { platform, romBytes, arch, bits, loadBase } = await loadContext(romPath, platformOverride);
+  const { platform, romBytes, arch, bits, endian, loadBase, codeStart } = await loadContext(romPath, platformOverride);
+  const { baddr, seedAt, rebase } = mipsAnalysisBase({ arch, platform, loadBase, codeStart });
+  const flat = ((address >>> 0) - rebase) >>> 0;
+  const rb = (a) => (a == null ? a : (a + rebase) >>> 0);
   let refs;
   try {
-    refs = await runRizinJson({ romBytes, arch, bits, baddr: loadBase || undefined, commands: `aaa; axtj @ ${hx(address)}` });
+    refs = await runRizinJson({ romBytes, arch, bits, endian, baddr, commands: `${analysisSeed({ arch, codeStart: seedAt })}; axtj @ ${hx(flat)}` });
   } catch (e) {
     // axtj prints nothing (not even `[]`) when there are zero refs → our JSON
     // guard throws. Treat "no JSON" as "no refs".
@@ -319,9 +470,9 @@ export async function analyzeXrefs(romPath, address, platformOverride) {
     else throw e;
   }
   const out = (refs ?? []).map((r) => ({
-    from: r.from,
-    fromHex: hx(r.from),
-    to: r.to,
+    from: rb(r.from),
+    fromHex: hx(rb(r.from)),
+    to: rb(r.to),
     type: (r.type || "").toLowerCase(), // CALL / CODE / DATA / STRING
     opcode: r.opcode,
   }));
@@ -333,23 +484,25 @@ export async function analyzeXrefs(romPath, address, platformOverride) {
  * analysis pass. The "give me the shape of this ROM" call.
  */
 export async function analyzeStructure(romPath, platformOverride) {
-  const { platform, romBytes, arch, bits, loadBase } = await loadContext(romPath, platformOverride);
-  const baddr = loadBase || undefined;
+  const { platform, romBytes, arch, bits, endian, loadBase, codeStart } = await loadContext(romPath, platformOverride);
+  const { baddr, seedAt, rebase } = mipsAnalysisBase({ arch, platform, loadBase, codeStart });
+  const seed = analysisSeed({ arch, codeStart: seedAt });
   const [fns, strings, entries] = await Promise.all([
-    runRizinJson({ romBytes, arch, bits, baddr, commands: "aaa; aflj" }).catch(() => []),
-    runRizinJson({ romBytes, arch, bits, baddr, commands: "aaa; izj" }).catch(() => []),
-    runRizinJson({ romBytes, arch, bits, baddr, commands: "aaa; iej" }).catch(() => []),
+    runRizinJson({ romBytes, arch, bits, endian, baddr, commands: `${seed}; aflj` }).catch(() => []),
+    runRizinJson({ romBytes, arch, bits, endian, baddr, commands: `${seed}; izj` }).catch(() => []),
+    runRizinJson({ romBytes, arch, bits, baddr, commands: `${seed}; iej` }).catch(() => []),
   ]);
+  const rb = (a) => (a == null ? a : (a + rebase) >>> 0);
   return {
     platform, arch,
     functionCount: Array.isArray(fns) ? fns.length : 0,
     stringCount: Array.isArray(strings) ? strings.length : 0,
-    entrypoints: (Array.isArray(entries) ? entries : []).map((e) => ({ address: e.vaddr, addressHex: hx(e.vaddr) })),
+    entrypoints: (Array.isArray(entries) ? entries : []).map((e) => ({ address: rb(e.vaddr), addressHex: hx(rb(e.vaddr)) })),
     functions: (Array.isArray(fns) ? fns : []).slice(0, 512).map((f) => ({
-      address: f.offset, addressHex: hx(f.offset), name: f.name, size: f.size, callers: f.indegree ?? 0,
+      address: rb(f.offset), addressHex: hx(rb(f.offset)), name: f.name, size: f.size, callers: f.indegree ?? 0,
     })),
     strings: (Array.isArray(strings) ? strings : []).slice(0, 256).map((s) => ({
-      address: s.vaddr, addressHex: hx(s.vaddr), value: s.string,
+      address: rb(s.vaddr), addressHex: hx(rb(s.vaddr)), value: s.string,
     })),
   };
 }
@@ -507,6 +660,48 @@ export async function analyzeDecompile(romPath, address, platformOverride) {
   // to pure garbage.
   if (platform === "genesis") romBytes = deinterleaveSmd(romBytes) ?? romBytes;
 
+  // MIPS (N64/PS1): `address` is a vaddr from target='functions'. Map it to a file
+  // offset and decompile via the MIPS SLEIGH spec (MIPS:BE:32 for N64, MIPS:LE:32
+  // for PS1). N64: normalize byte order, fileOff = vaddr - entryVaddr + 0x1000 (post
+  // IPL3). PS1: strip PS-EXE, fileOff = vaddr - loadAddr.
+  if (platform === "n64" || platform === "ps1" || platform === "dreamcast") {
+    let fileOff;
+    if (platform === "n64") {
+      romBytes = normalizeN64ByteOrder(romBytes).bytes;
+      const entry = ((romBytes[0x08] << 24) | (romBytes[0x09] << 16) | (romBytes[0x0a] << 8) | romBytes[0x0b]) >>> 0;
+      fileOff = ((address >>> 0) - entry + 0x1000) >>> 0;
+    } else if (platform === "dreamcast") {
+      // SH-4: strip the ELF to its first PT_LOAD segment (vaddr = loadBase), or treat
+      // a raw image as flat at 0x8c010000. fileOff = address - segment vaddr.
+      let loadVa = 0x8c010000;
+      if (romBytes.length >= 0x34 && romBytes[0] === 0x7f && romBytes[1] === 0x45 && romBytes[2] === 0x4c && romBytes[3] === 0x46) {
+        const u32 = (o) => (romBytes[o] | (romBytes[o + 1] << 8) | (romBytes[o + 2] << 16) | (romBytes[o + 3] << 24)) >>> 0;
+        const u16 = (o) => romBytes[o] | (romBytes[o + 1] << 8);
+        const phoff = u32(0x1c), phentsize = u16(0x2a), phnum = u16(0x2c);
+        for (let i = 0; i < phnum; i++) {
+          const ph = phoff + i * phentsize;
+          if (u32(ph) === 1) { loadVa = u32(ph + 8) >>> 0; romBytes = romBytes.subarray(u32(ph + 4), u32(ph + 4) + u32(ph + 16)); break; }
+        }
+      }
+      fileOff = ((address >>> 0) - loadVa) >>> 0;
+    } else {
+      let loadAddr = 0;
+      if (romBytes.length >= 0x800 && romBytes[0] === 0x50 && romBytes[1] === 0x53 && romBytes[2] === 0x2d && romBytes[3] === 0x58) {
+        loadAddr = (romBytes[0x18] | (romBytes[0x19] << 8) | (romBytes[0x1a] << 16) | (romBytes[0x1b] << 24)) >>> 0;
+        romBytes = romBytes.subarray(0x800);
+      }
+      fileOff = ((address >>> 0) - loadAddr) >>> 0;
+    }
+    if (fileOff >= romBytes.length) {
+      throw new Error(`decompile: ${platform} address ${hx(address)} maps to file offset ${hx(fileOff)}, outside the ${romBytes.length}-byte image. Use an address from target='functions'.`);
+    }
+    const rm = await decompileFunction({ platform, romBytes, fileOffset: fileOff });
+    return {
+      platform, langid: rm.langid, address, addressHex: hx(address),
+      code: prettyDecompile(rm.code, platform), warnings: rm.warnings,
+    };
+  }
+
   // SNES: banked 24-bit space. `address` is a LoROM/HiROM CPU address (what
   // target='functions'/'cfg' report). Lay the cart out by CPU address so BOTH
   // the function address AND its in-bank/JSL operands resolve, then decompile at

package/src/analysis/decompile.js

@@ -47,6 +47,13 @@ export const SLEIGH_LANGID = {
   genesis: "68000:BE:32:default",
   snes: "65816:LE:24:snes",
   pce: "HuC6280:LE:16:default",
+  // 32-bit MIPS tier. PS1 R3000 = little-endian; N64 R4300 = big-endian (games run
+  // 32-bit MIPS III code). Ghidra ships both MIPS variants in its stock SLEIGH.
+  ps1: "MIPS:LE:32:default",
+  n64: "MIPS:BE:32:default",
+  // Dreamcast = SH-4 (SuperH), little-endian. Ghidra ships SuperH4 in its stock
+  // SLEIGH; we compile SuperH4_le.sla (see scripts/build-decompiler.sh).
+  dreamcast: "SuperH4:LE:32:default",
 };
 
 /**

package/src/analysis/decompiler/sleigh/mips.ldefs

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<language_definitions>
+  <language processor="MIPS"
+            endian="big"
+            size="32"
+            variant="default"
+            version="1.7"
+            slafile="mips32be.sla"
+            processorspec="mips32.pspec"
+            id="MIPS:BE:32:default">
+    <description>MIPS32 big endian (N64 R4300, 32-bit code)</description>
+    <compiler name="default" spec="mips32be.cspec" id="default"/>
+  </language>
+  <language processor="MIPS"
+            endian="little"
+            size="32"
+            variant="default"
+            version="1.7"
+            slafile="mips32le.sla"
+            processorspec="mips32.pspec"
+            id="MIPS:LE:32:default">
+    <description>MIPS32 little endian (PS1 R3000)</description>
+    <compiler name="default" spec="mips32le.cspec" id="default"/>
+  </language>
+</language_definitions>