romdevtools 0.70.0 → 0.71.1

package/src/host/LibretroHost.js

@@ -164,6 +164,29 @@ function mirrorDirToFS(FS, hostDir, fsDir) {
   }
 }
 
+/** Mirror a host dir into a PROXIED core's APP-THREAD MEMFS (a per-thread JS heap, invisible to
+ *  the main-thread FS). Each file's bytes go through shared WASM memory; romdev_app_fs_write does
+ *  the FS.writeFile on the app thread, where the core's fopen runs. */
+function mirrorDirToAppFS(mod, hostDir, fsDir) {
+  for (const name of readdirSync(hostDir)) {
+    const hostPath = path.join(hostDir, name);
+    const fsPath = fsDir + "/" + name;
+    const st = statSync(hostPath);
+    if (st.isDirectory()) {
+      mirrorDirToAppFS(mod, hostPath, fsPath);
+    } else if (st.isFile()) {
+      const bytes = readFileSync(hostPath);
+      const dataPtr = mod._malloc(bytes.length || 1);
+      mod.HEAPU8.set(bytes, dataPtr);
+      const pb = Buffer.from(fsPath + "\0", "utf-8");
+      const pathPtr = mod._malloc(pb.length);
+      mod.HEAPU8.set(pb, pathPtr);
+      try { mod._romdev_app_fs_write(pathPtr, dataPtr, bytes.length); } catch { /* skip */ }
+      mod._free(dataPtr); mod._free(pathPtr);
+    }
+  }
+}
+
 /**
  * When loadMedia is called with `bytes:` and no `virtualName`, this is
  * the extension we tack onto "/rom" so the core knows which platform
@@ -294,8 +317,16 @@ export class LibretroHost {
   async loadCore(jsPath, wasmPath, opts = {}) {
     if (this.mod) throw new Error("core already loaded; create a new host");
 
+    // Proxied (multi-threaded) cores — e.g. PPSSPP/PSP — run on a dedicated "app thread" so the
+    // JS main thread never blocks while the core's worker threads proxy back to it (which would
+    // deadlock the synchronous frame-stepping). They own the ENTIRE GL stack on the app thread
+    // (native-gles + webgl-node loaded + context created + readback all there). The registry
+    // marks them; the single-threaded GL cores keep the main-thread GL path below.
+    this._proxied = !!opts.proxied;
+    this.state.proxied = this._proxied;
+
     let glCanvas = null;
-    if (opts.hwRender) {
+    if (opts.hwRender && !this._proxied) {
       // Set up the HW-render path: LibretroGL owns the FBO/readback; a webgl-node
       // mock canvas backs the minified core's GLctx. Both pull the OPTIONAL native
       // GL deps lazily (clear install hint if absent).
@@ -317,15 +348,58 @@ export class LibretroHost {
     const mod = await loadLibretroCore({ jsPath, wasmPath, glCanvas });
     this.mod = mod;
 
-    // Canvas HW-render cores: initialize the Emscripten GL context so `GLctx` is
+    if (this._proxied) {
+      // Spawn the app thread, then build the whole GL stack on it (native-gles + webgl-node +
+      // the Emscripten GL context). 480x272 is PSP native; the readback crops per-frame.
+      if (typeof mod._romdev_proxy_init !== "function") {
+        throw new Error("core marked proxied but missing _romdev_proxy_init export");
+      }
+      mod._romdev_proxy_init();
+      // Confirm the app thread's event loop is actually SERVICING its proxy queue before driving
+      // it — app_ready is set by a proxied ping (ping_on_app), which only runs once the queue is
+      // live. Setting it eagerly would race: a proxied call issued before the loop pumps would sit
+      // unprocessed and a proxy_sync would hang main. Pump + yield so the async ping is delivered.
+      mod._romdev_app_ping();
+      while (mod._romdev_app_ready() !== 1) {
+        mod._romdev_pump_main_queue();
+        await new Promise((r) => setTimeout(r, 0));
+      }
+      if (opts.hwRender) {
+        // Async GL setup: the app thread imports native-gles/webgl-node + creates the context,
+        // which needs the main JS event loop. So kick it async + poll while yielding (a blocking
+        // proxy_sync would freeze the event loop the import() depends on → deadlock).
+        mod._romdev_proxied_gl_setup_start(480, 272);
+        while (mod._romdev_gl_setup_phase() !== 2) {
+          await new Promise((r) => setTimeout(r, 0));
+        }
+        if (mod._romdev_gl_setup_result() !== 1) {
+          throw new Error("proxied GL setup failed on the app thread");
+        }
+      }
+    }
+
+    // Canvas HW-render cores (non-proxied): initialize the Emscripten GL context so `GLctx` is
     // set BEFORE any GL call (the core's context_reset / first getParameter). Must
     // run before _retro_init.
     if (glCanvas && mod.GL) {
-      const handle = mod.GL.createContext(glCanvas, { majorVersion: 2 });
-      if (handle > 0) mod.GL.makeContextCurrent(handle);
+      {
+        const handle = mod.GL.createContext(glCanvas, { majorVersion: 2 });
+        if (handle > 0) mod.GL.makeContextCurrent(handle);
+      }
     }
 
-    registerCallbacks({ mod, state: this.state, log: this.log });
+    if (this._proxied) {
+      // Proxied cores: install the JS callback impls on Module (the C trampolines proxy each
+      // callback from the app thread back to main to run these). Register the trampolines on
+      // MAIN — they're plain C function pointers the app thread can call, and retro_init/
+      // pthread_create must run on main (Worker allocation proxies to main; it'd deadlock if
+      // main were blocked proxying init to the app thread). Only load_game/run proxy to app.
+      const { registerProxiedCallbacks } = await import("./callbacks.js");
+      registerProxiedCallbacks({ mod, state: this.state, log: this.log });
+      mod._romdev_register_callbacks();
+    } else {
+      registerCallbacks({ mod, state: this.state, log: this.log });
+    }
 
     // Pre-seed per-platform core-option overrides BEFORE _retro_init. The core
     // registers its variables (SET_VARIABLES) during retro_init and decides its
@@ -344,7 +418,13 @@ export class LibretroHost {
       }
     }
 
-    mod._retro_init();
+    // retro_init runs on MAIN even for proxied cores (it spawns the threadManager workers via
+    // pthread_create, which needs the main thread free — not blocked proxying init to app).
+    // EXCEPT proxied cores defer it to loadMedia: PPSSPP's retro_init touches the system dir
+    // (fonts/flash0), which for proxied cores is only mirrored into the app-thread FS during
+    // loadMedia — calling retro_init before the mount makes the loader hang on missing assets.
+    if (!this._proxied) mod._retro_init();
+    else this._retroInitPending = true;
     this.status.corePath = jsPath;
   }
 
@@ -364,6 +444,10 @@ export class LibretroHost {
   async loadMedia(args) {
     const mod = this._needMod();
     const { platform } = args;
+    // Allow the systemDir to be supplied per-load (not just via the constructor) — proxied cores
+    // (PSP) need it to mirror BIOS/font assets into the app-thread FS, and callers commonly pass
+    // it to loadMedia rather than at construction.
+    if (args.systemDir && !this.systemDir) this.systemDir = args.systemDir;
     // Derive the kind from the file/virtual extension when the caller didn't say
     // — so a C64 .d64 reports mediaKind:"disk" (writable save target) vs a .prg
     // "program". For an in-memory load, the virtualName carries the ext.
@@ -397,7 +481,13 @@ export class LibretroHost {
     if (this.systemDir && !this._systemDirMounted && mod.FS) {
       try {
         const FS_SYS = "/system";
-        mirrorDirToFS(mod.FS, this.systemDir, FS_SYS);
+        // Proxied cores read the system dir on the app thread (separate per-thread MEMFS); mirror
+        // ONLY there. Non-proxied cores read main's FS. (Mirroring to both is wasted work.)
+        if (this._proxied) {
+          mirrorDirToAppFS(mod, this.systemDir, FS_SYS);
+        } else {
+          mirrorDirToFS(mod.FS, this.systemDir, FS_SYS);
+        }
         // Redirect the core's reported system dir to the in-FS copy.
         if (this.state) this.state.systemDir = FS_SYS;
         this._systemDirMounted = true;
@@ -430,7 +520,10 @@ export class LibretroHost {
       throw new Error("loadMedia requires either `path` or `bytes`");
     }
     const vfsPath = "/rom" + ext;
-    if (mod.FS) {
+    // For proxied cores the core fopen's on the app thread, so the ROM goes to the app-thread
+    // MEMFS below (romdev_app_fs_write) — writing it to the main-thread FS too is wasted work
+    // (and for a 60MB ISO, a needless copy). Non-proxied cores read main's FS directly.
+    if (mod.FS && !this._proxied) {
       try {
         mod.FS.writeFile(vfsPath, data);
       } catch (e) {
@@ -448,6 +541,14 @@ export class LibretroHost {
     const pathPtr = mod._malloc(pathBytes.length);
     mod.HEAPU8.set(pathBytes, pathPtr);
 
+    // Proxied cores run on the app thread, whose MEMFS is a SEPARATE (per-thread) JS heap — the
+    // main-thread FS.writeFile above is invisible there. PPSSPP fopen's the path on the app
+    // thread, so write the ROM into the app thread's MEMFS too (the bytes are already in shared
+    // WASM memory at dataPtr).
+    if (this._proxied) {
+      mod._romdev_app_fs_write(pathPtr, dataPtr, data.length);
+    }
+
     // retro_game_info struct (16 bytes on wasm32).
     const infoPtr = mod._malloc(16);
     mod.setValue(infoPtr + 0, pathPtr, "i32");
@@ -455,7 +556,38 @@ export class LibretroHost {
     mod.setValue(infoPtr + 8, data.length, "i32");
     mod.setValue(infoPtr + 12, 0, "i32"); // meta = null
 
-    const ok = mod._retro_load_game(infoPtr);
+    // Proxied cores: run retro_load_game on the app thread ASYNCHRONOUSLY (it creates the GL
+    // context + spawns the core's worker threads there). We kick it async then poll the done
+    // flag while YIELDING to the JS event loop — the event loop must keep turning so emscripten
+    // can service the app-thread's pooled-Worker grabs / postMessage wakeups. A blocking call
+    // would freeze the event loop → the core's threads can't be scheduled → deadlock.
+    let ok;
+    if (this._proxied) {
+      // Deferred retro_init (see loadCore): now that the system dir is mirrored into the app-thread
+      // FS, the core can init (fonts/flash0 present) without hanging.
+      if (this._retroInitPending) {
+        mod._retro_init();
+        this._retroInitPending = false;
+      }
+      mod._romdev_proxied_load_game_start(infoPtr);
+      while (mod._romdev_proxied_load_state() === 0) {
+        mod._romdev_pump_main_queue();         // run callbacks the app thread proxied to main
+        await new Promise((r) => setTimeout(r, 0)); // yield → emscripten services worker ops
+      }
+      ok = mod._romdev_proxied_load_state() === 1;
+      // NOTE: PPSSPP's ContextReset (creates DrawContext + GPU) must run for rendering — without it
+      // gpu/draw are null and EmuFrame renders nothing (the blank-frame root cause). Firing it here
+      // currently heap-corrupts inside the GL render-manager construction (under investigation), so
+      // it's disabled for now; the core loads + runs stably without it (CPU/audio work, no video).
+      // ContextReset (creates GPU/DrawContext) survives intermittently after the webgl-node
+      // MAX_UNIFORM_BLOCK_SIZE fix but still hits a non-deterministic native-heap corruption in
+      // PPSSPP's GL init — disabled until that's pinned (ASAN). Core loads + runs without it.
+      if (ok && this.state.proxiedContextResetPtr) {
+        mod._romdev_proxied_fire_context_reset(this.state.proxiedContextResetPtr);
+      }
+    } else {
+      ok = mod._retro_load_game(infoPtr);
+    }
 
     // Free the struct itself. Don't free pathPtr or dataPtr — the core may
     // retain pointers into them for the life of the loaded game.
@@ -512,7 +644,10 @@ export class LibretroHost {
     //   };
     // };
     const avInfoPtr = mod._malloc(64);
-    mod._retro_get_system_av_info(avInfoPtr);
+    // Proxied cores keep core state on the app thread; retro_get_system_av_info reads it, so it
+    // must run there (a direct main-thread call reads garbage / can wedge). Proxy it.
+    if (this._proxied) mod._romdev_proxied_av_info(avInfoPtr);
+    else mod._retro_get_system_av_info(avInfoPtr);
     this.status.fbWidth = mod.getValue(avInfoPtr + 0, "i32");
     this.status.fbHeight = mod.getValue(avInfoPtr + 4, "i32");
     // aspect_ratio (+16) is the intended DISPLAY aspect (what a CRT would
@@ -540,11 +675,17 @@ export class LibretroHost {
       this.hwRender.createContext(maxW, maxH, this._glContextCreated);
     }
 
-    // Configure controller port 0 as joypad (some cores default to NONE).
-    mod._retro_set_controller_port_device(0, RETRO_DEVICE_JOYPAD);
-    // Port 1 too — needed for 2P. The C64/VICE 2P path (two live control ports)
-    // only reads RetroPad port 1 when it's registered as a joypad device.
-    mod._retro_set_controller_port_device(1, RETRO_DEVICE_JOYPAD);
+    // Configure controller port 0 as joypad (some cores default to NONE). Proxied cores touch
+    // core state on the app thread, so proxy it there.
+    if (this._proxied) {
+      mod._romdev_proxied_set_controller(0, RETRO_DEVICE_JOYPAD);
+      mod._romdev_proxied_set_controller(1, RETRO_DEVICE_JOYPAD);
+    } else {
+      mod._retro_set_controller_port_device(0, RETRO_DEVICE_JOYPAD);
+      // Port 1 too — needed for 2P. The C64/VICE 2P path (two live control ports)
+      // only reads RetroPad port 1 when it's registered as a joypad device.
+      mod._retro_set_controller_port_device(1, RETRO_DEVICE_JOYPAD);
+    }
 
     // ---- Settle the framebuffer to the ROM's chosen geometry ----
     //
@@ -567,7 +708,10 @@ export class LibretroHost {
     // VDP in 1-3 frames; SNES in 1; NES in 1-2. The cost is ~5-30 ms
     // on loadMedia, paid once. Skip when loaded paused (caller is
     // already in control).
-    if (!this.status.paused) {
+    // Proxied cores (PSP) drive frames through the async run path (run_start + poll); the
+    // synchronous settle loop below uses the blocking sync run, so skip it. PSP geometry is the
+    // fixed 480×272 av_info already read, so there's no pre-init default to settle past.
+    if (!this.status.paused && !this._proxied) {
       // Settle frames are core warm-up, not agent-visible gameplay
       // frames — don't increment frameCount. From the agent's POV the
       // first stepFrames(N) should advance the count by exactly N.
@@ -587,7 +731,7 @@ export class LibretroHost {
       let stepped = 0;
       let firstRefreshAt = -1;
       while (stepped < MAX_SETTLE) {
-        mod._retro_run();
+        this._runCore();
         this._afterRun();
         stepped++;
         if (firstRefreshAt < 0 && this.state.lastFrame && this.state.lastFrame !== beforeRefreshSnapshot) {
@@ -624,11 +768,11 @@ export class LibretroHost {
    * @returns {number} frames actually run
    */
   stepFrames(n) {
-    const mod = this._needMod();
+    this._needMod();
     this._needMedia();
     if (this.status.paused) return 0;
     for (let i = 0; i < n; i++) {
-      mod._retro_run();
+      this._runCore();
       this._afterRun();
       this.status.frameCount++;
     }
@@ -639,10 +783,44 @@ export class LibretroHost {
     return n;
   }
 
+  /** Run one frame. Proxied cores route retro_run onto the app thread (so the JS main thread
+   *  stays free to service the core's worker-thread proxy calls); others call directly. */
+  _runCore() {
+    if (this._proxied) this.mod._romdev_proxied_run();
+    else this.mod._retro_run();
+  }
+
   /** Post-_retro_run hook: HW-render readback. The video callback set
    *  state.hwFramePending during run; now (GL state stable) read back the FBO into
    *  state.lastFrame as an RGBA frame. No-op for the 14 software cores. */
   _afterRun() {
+    if (this._proxied) {
+      // Proxied cores own GL on the app thread; read the frame back THERE into a WASM buffer,
+      // then copy it out here. The core reports its size via video_refresh (hwFrameW/H).
+      if (this.state.hwFramePending) {
+        this.state.hwFramePending = false;
+        const w = this.state.hwFrameW || 480, h = this.state.hwFrameH || 272;
+        const mod = this.mod;
+        const n = w * h * 4;
+        if (!this._pxBuf || this._pxBufN !== n) {
+          if (this._pxBuf) mod._free(this._pxBuf);
+          this._pxBuf = mod._malloc(n); this._pxBufN = n;
+        }
+        mod._romdev_proxied_readback(w, h, this._pxBuf);
+        // native-gles is bottom-left origin → flip vertically into lastFrame.
+        const src = mod.HEAPU8.subarray(this._pxBuf, this._pxBuf + n);
+        const pixels = new Uint8Array(n);
+        const rowBytes = w * 4;
+        for (let y = 0; y < h; y++) {
+          pixels.set(src.subarray((h - 1 - y) * rowBytes, (h - y) * rowBytes), y * rowBytes);
+        }
+        this.state.lastFrame = {
+          width: w, height: h, pitch: rowBytes,
+          format: ROMDEV_PIXEL_FORMAT_RGBA8888, pixels, rgba: true,
+        };
+      }
+      return;
+    }
     if (this.state.hwFramePending && this.hwRender?.active) {
       this.state.hwFramePending = false;
       // Crop the GL FBO to the core's reported active resolution (e.g. DC 640x480 in an
@@ -663,9 +841,9 @@ export class LibretroHost {
    *  playtest loop can't race). Advances the (monotonic) frame counter by 1.
    *  Returns the frame count after. */
   renderOneFrame() {
-    const mod = this._needMod();
+    this._needMod();
     this._needMedia();
-    mod._retro_run();
+    this._runCore();
     this._afterRun();
     this.status.frameCount++;
     if (this.state.lastFrame) {
@@ -1543,6 +1721,47 @@ export class LibretroHost {
     }
   }
 
+  /** True when the Dreamcast core (flycast) exposes the live SH-4 register block. */
+  sh4RegsSupported() {
+    return !!(this.mod && typeof this.mod._romdev_sh4_regs_get === "function");
+  }
+
+  /** Read the live SH-4 register block as a Uint32Array(24):
+   *  [0..15]=r0..r15, 16=pc, 17=pr, 18=gbr, 19=vbr, 20=sr, 21=mac.l, 22=mac.h, 23=fpul.
+   *  null if the core doesn't expose it. */
+  getSh4Regs() {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_sh4_regs_get !== "function") return null;
+    const ptr = mod._malloc(24 * 4);
+    try {
+      mod._romdev_sh4_regs_get(ptr);
+      return new Uint32Array(mod.HEAPU8.buffer, ptr, 24).slice();
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /** True when the Dreamcast core exposes the AICA register file
+   *  (getAudioState chip:'aica'). */
+  aicaRegsSupported() {
+    return !!(this.mod && typeof this.mod._romdev_aica_get === "function");
+  }
+
+  /** Read the AICA register window (channels + CommonData) as a Uint8Array.
+   *  Default 0x3000 bytes (64 SGC channel blocks @ 0x80 each + CommonData @ 0x2800).
+   *  null if the core doesn't expose it. */
+  getAicaRegs(bytes = 0x3000) {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_aica_get !== "function") return null;
+    const ptr = mod._malloc(bytes);
+    try {
+      mod._romdev_aica_get(ptr, bytes);
+      return new Uint8Array(mod.HEAPU8.buffer, ptr, bytes).slice();
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
   /** True when the PS1 core exposes the SPU register block (getAudioState chip:'spu'). */
   spuRegsSupported() {
     return !!(this.mod && typeof this.mod._romdev_spu_get === "function");
@@ -1770,7 +1989,7 @@ export class LibretroHost {
    * @returns {number} frames actually run
    */
   _runFramesExclusive(body, maxFrames) {
-    const mod = this._needMod();
+    this._needMod();
     // Suspend ONLY the playtest window's render-tick stepping for the duration —
     // not `status.paused` (the agent's pause is a separate concept, and the core
     // run must be identical whether or not the user paused). The playtest tick
@@ -1781,7 +2000,7 @@ export class LibretroHost {
     let framesRun = 0;
     try {
       for (let i = 0; i < maxFrames; i++) {
-        mod._retro_run();
+        this._runCore();
         this.status.frameCount++;
         framesRun++;
         if (body(i)) break;

package/src/host/callbacks.js

@@ -170,7 +170,7 @@ export function registerCallbacks(args) {
     // GL state is only stable AFTER _retro_run returns. Flag it; stepFrames does the
     // glReadPixels post-run.
     const uPtr = dataPtr >>> 0;
-    if (uPtr === RETRO_HW_FRAME_BUFFER_VALID && state.hwRender?.active) {
+    if (uPtr === RETRO_HW_FRAME_BUFFER_VALID && (state.hwRender?.active || state.proxied)) {
       state.hwFramePending = true;
       // Remember the core's reported active resolution (e.g. DC 640x480) so the
       // readback can crop the (often larger, e.g. 853x853) GL FBO to just the
@@ -228,6 +228,49 @@ export function registerCallbacks(args) {
   mod._retro_set_input_state(inputStateCb);
 }
 
+/**
+ * Proxied (app-thread) cores: the C shim registers C trampolines with the core that proxy each
+ * callback back to the MAIN thread to run these JS impls. So instead of addFunction (which binds
+ * a closure to the calling thread and can't be invoked from the app thread), we install the JS
+ * impls as Module fns the trampolines call via EM_ASM. Same bodies as registerCallbacks, minus
+ * the addFunction/retro_set_* (the shim does those on the app thread).
+ */
+export function registerProxiedCallbacks(args) {
+  const { mod, state, log } = args;
+
+  mod.romdev_envCb = (cmd, dataPtr) => (handleEnv(mod, state, cmd, dataPtr, log) ? 1 : 0);
+
+  mod.romdev_videoCb = (dataPtr, w, h, pitch) => {
+    const uPtr = dataPtr >>> 0;
+    if (uPtr === RETRO_HW_FRAME_BUFFER_VALID && (state.hwRender?.active || state.proxied)) {
+      state.hwFramePending = true;
+      if (w > 0 && h > 0) { state.hwFrameW = w; state.hwFrameH = h; }
+      return;
+    }
+    if (dataPtr === 0 || uPtr === RETRO_HW_FRAME_BUFFER_VALID) return;
+    const bytes = h * pitch;
+    const view = mod.HEAPU8.subarray(dataPtr, dataPtr + bytes);
+    state.lastFrame = { width: w, height: h, pitch, format: state.pixelFormat, pixels: new Uint8Array(view) };
+  };
+
+  mod.romdev_audioBatchCb = (dataPtr, frames) => {
+    if (dataPtr === 0 || frames === 0) return frames;
+    const byteLen = frames * 2 * 2;
+    const samples = new Int16Array(mod.HEAPU8.buffer, dataPtr, byteLen / 2).slice();
+    state.audioRing.push(samples);
+    return frames;
+  };
+
+  mod.romdev_inputCb = (port, device, _idx, id) => {
+    if (device === 3) return state.keysDown.has(id) ? 1 : 0;
+    const portBits = state.inputPorts[port];
+    if (!portBits) return 0;
+    const bits = portBits[0];
+    if (id === 256) return bits;
+    return bits & (1 << id) ? 1 : 0;
+  };
+}
+
 function allocString(mod, state, str) {
   const bytes = Buffer.from(str + "\0", "utf-8");
   const ptr = mod._malloc(bytes.length);
@@ -300,6 +343,19 @@ function handleEnv(mod, state, rawCmd, dataPtr, log) {
       // already a useful diagnostic — most cores pass a fully-formed message
       // (no varargs substitution needed) or a message + N args we can't decode.
       // Read the fmt as-is so log output is actually readable.
+      // Proxied cores call the log callback from the app thread, so it must be a C function
+      // pointer (a main-thread addFunction is a bad table index there). The shim's romdev_log_cb
+      // routes to Module.romdev_logCb (installed below).
+      if (state.proxied) {
+        mod.romdev_logCb = (level, fmtPtr) => {
+          if (!log) return;
+          let msg = "<unreadable>";
+          try { msg = mod.UTF8ToString(fmtPtr); } catch { /* */ }
+          log(level, msg);
+        };
+        mod.setValue(dataPtr, mod._romdev_log_cb_ptr(), "i32");
+        return true;
+      }
       if (!state._logCbPtr) {
         state._logCbPtr = mod.addFunction((level, fmtPtr, _vaPtr) => {
           if (!log) return;
@@ -448,6 +504,17 @@ function handleEnv(mod, state, rawCmd, dataPtr, log) {
     // software cores, or no GL stack), reject so the core falls back to software.
     case E.SET_HW_RENDER:
       if (state.hwRender) return state.hwRender.setup(mod, dataPtr);
+      // Proxied cores own GL on the app thread. Fill the retro_hw_render_callback struct with
+      // C function pointers (valid on the app thread, unlike main-thread addFunction): the core
+      // reads context_reset (+4) itself; we write get_current_framebuffer (+8) + get_proc_address
+      // (+12) from the shim. bottom_left_origin (+18) is true for GL.
+      if (state.proxied) {
+        state.proxiedContextResetPtr = mod.getValue(dataPtr + 4, "i32");
+        mod.setValue(dataPtr + 8, mod._romdev_hw_get_fb_ptr(), "i32");
+        mod.setValue(dataPtr + 12, mod._romdev_hw_get_proc_ptr(), "i32");
+        state.proxiedBottomLeft = !!mod.HEAPU8[dataPtr + 18];
+        return true;
+      }
       return false;
 
     // Things we can't or don't want to support — reject so core falls back.

package/src/host/cpu-state.js

@@ -163,6 +163,35 @@ function decodeMips(regs) {
   };
 }
 
+/** Decode the SH-4 register block (Dreamcast) from getSh4Regs():
+ *  [0..15]=r0..r15, 16=pc, 17=pr, 18=gbr, 19=vbr, 20=sr, 21=mac.l, 22=mac.h, 23=fpul. */
+function decodeSh4(regs) {
+  if (!regs || regs.length < 24) return null;
+  const hx = (v) => "$" + (v >>> 0).toString(16).toUpperCase().padStart(8, "0");
+  const named = {};
+  for (let i = 0; i < 16; i++) named["r" + i] = hx(regs[i]);
+  named.pr = hx(regs[17]);
+  named.gbr = hx(regs[18]);
+  named.vbr = hx(regs[19]);
+  named.sr = hx(regs[20]);
+  named.macl = hx(regs[21]);
+  named.mach = hx(regs[22]);
+  named.fpul = hx(regs[23]);
+  // SR flags: T(0) S(1) Q(8) M(9) BL(28) RB(29) MD(30)
+  const sr = regs[20] >>> 0;
+  return {
+    pc: regs[16] >>> 0,
+    pcHex: hx(regs[16]),
+    registers: named,
+    flags: {
+      T: !!(sr & 0x1), S: !!(sr & 0x2),
+      Q: !!(sr & 0x100), M: !!(sr & 0x200),
+      BL: !!(sr & 0x10000000), RB: !!(sr & 0x20000000), MD: !!(sr & 0x40000000),
+      raw: hx(sr),
+    },
+  };
+}
+
 function decode6502(bytes) {
   if (!bytes || bytes.length < 25) return null;
   const u16le = (o) => bytes[o] | (bytes[o + 1] << 8);
@@ -327,6 +356,9 @@ export function getCPUState(host, platform, cpu = "main") {
   if (platform === "n64" || platform === "ps1") {
     return decodeMips(host.getMipsRegs?.());
   }
+  if (platform === "dreamcast") {
+    return decodeSh4(host.getSh4Regs?.());
+  }
   if (platform === "nes") {
     const bytes = host.readMemory("nes_cpu_regs", 0, 28);
     return decode6502(bytes);

package/src/host/dc-aica-state.js

@@ -0,0 +1,67 @@
+// Dreamcast AICA sound-chip decode — the "what is each of the 64 PCM channels
+// doing this frame?" view that getAudioState gives the other platforms' chips.
+// Input is the raw AICA register window (Uint8Array) from host.getAicaRegs():
+// 64 channels × 0x80 bytes starting at 0x000, plus CommonData at 0x2800.
+//
+// The AICA is a 64-channel PCM/ADPCM sampler. Canonical per-channel register map
+// (offset within the channel's 0x80 block), little-endian 16-bit registers:
+//   0x00 : KYONEX(15) KYONB(14) ... LPCTL(9) PCMS(8..7) SA-high(6..0)
+//   0x04 : SA-low (sample start address, low 16)
+//   0x08 : LSA (loop start)            0x0C : LEA (loop end)
+//   0x10 : D2R/D1R/AR (attack/decay)   0x14 : RR/DL/KRS/LS (release/sustain)
+//   0x18 : LPSLNK / OCT / FNS (pitch: OCT bits 14..11 signed, FNS bits 9..0)
+//   0x24 : DISDL (direct send level, bits 11..8) / DIPAN (pan, bits 4..0)
+// CommonData (0x2800): 0x00 MVOL (master volume, bits 3..0) + MONO/MEM8MB/etc.
+
+const CH_STRIDE = 0x80;
+const NUM_CH = 64;
+const COMMON = 0x2800;
+
+/**
+ * @param {Uint8Array|null} reg  the AICA register window from getAicaRegs()
+ * @returns {{ chip:"aica", masterVolume:number, voices:Array<object>,
+ *   activeVoices:number } | null}
+ */
+export function decodeAica(reg) {
+  if (!reg || reg.length < COMMON + 2) return null;
+  const u16 = (o) => (reg[o] | (reg[o + 1] << 8)) & 0xffff;
+
+  const voices = [];
+  let active = 0;
+  for (let c = 0; c < NUM_CH; c++) {
+    const base = c * CH_STRIDE;
+    if (base + 0x28 > reg.length) break;
+    const play = u16(base + 0x00);
+    const keyOn = !!(play & 0x4000);       // KYONB
+    const loop = !!(play & 0x0200);        // LPCTL
+    const pcms = (play >> 7) & 0x3;         // 0/1 = 16/8-bit PCM, 2 = ADPCM
+    const saHi = play & 0x7f;
+    const saLo = u16(base + 0x04);
+    const sampleAddr = ((saHi << 16) | saLo) >>> 0;
+    const lsa = u16(base + 0x08);
+    const lea = u16(base + 0x0c);
+    const pitch = u16(base + 0x18);
+    const oct = (pitch >> 11) & 0xf;        // signed 4-bit
+    const fns = pitch & 0x3ff;
+    const env = u16(base + 0x24);
+    const disdl = (env >> 8) & 0xf;         // direct send level (volume)
+    const dipan = env & 0x1f;               // pan
+    if (keyOn && disdl > 0) active++;
+    voices.push({
+      ch: c,
+      keyOn,
+      loop,
+      format: pcms === 2 ? "ADPCM" : (pcms === 1 ? "PCM8" : "PCM16"),
+      sampleAddr: "$" + sampleAddr.toString(16).toUpperCase(),
+      loopStart: lsa,
+      loopEnd: lea,
+      octave: oct >= 8 ? oct - 16 : oct,    // 4-bit signed
+      fns,
+      volume: disdl,                         // 0..15 direct send level
+      pan: dipan,
+    });
+  }
+
+  const mvol = u16(COMMON + 0x00) & 0xf;
+  return { chip: "aica", masterVolume: mvol, activeVoices: active, voices };
+}

package/src/mcp/tools/audio.js

@@ -367,7 +367,7 @@ export function registerAudioTools(server, z, sessionKey) {
     "sampled SFX fire' on Genesis is still record-and-FFT.",
     {
       op: z.enum(["inspect", "record"]).describe("inspect a sound chip's live state (single-frame, or a frames trace); or record audio to a WAV."),
-      chip: z.enum(["nes", "gb", "gba", "dsp", "psg", "ym2612", "sid", "mikey", "pce", "ay8910"]).optional().describe("op=inspect: which sound chip to decode (all 14 systems mapped)."),
+      chip: z.enum(["nes", "gb", "gba", "dsp", "psg", "ym2612", "sid", "mikey", "pce", "ay8910", "spu", "ai", "aica"]).optional().describe("op=inspect: which sound chip to decode. Tile systems: nes/gb/gba/dsp(SNES)/psg(SN76489)/ym2612(Genesis FM)/sid(C64)/mikey(Lynx)/pce/ay8910(MSX). 3D systems: spu (PS1, 24 ADPCM voices), ai (N64 AI output), aica (Dreamcast, 64 PCM/ADPCM channels)."),
       frames: z.number().int().min(1).max(60000).optional().describe("op=record: emulator frames to capture (default 180 = 3s NTSC). op=inspect: if set, TRACE the chip over N frames into a per-channel timeline; OMIT for a single-frame snapshot."),
       sampleEvery: z.number().int().min(1).default(1).describe("op=inspect trace: sample the chip only every Nth frame (thins a long trace; the last frame is always sampled). Changes on skipped frames surface at the next sampled frame, so >1 loses fine timing — keep at 1 to catch every transition."),
       path: z.string().optional().describe("op=record: absolute path to write the WAV (required for record)."),

package/src/mcp/tools/disasm.js

@@ -1461,7 +1461,7 @@ export function registerDisasmTools(server, z) {
     "read/write); also walks the vector table. Banked carts are scanned PER BANK (all of the formats above) — " +
     "refs carry `prgBank` (NES) / `romBank` (everything else). LIMITATION: direct addressing only " +
     "(indirect/computed jumps are missed).\n" +
-    "── RE ENGINE (Rizin + Ghidra, all 14 platforms) ──\n" +
+    "── RE ENGINE (Rizin + Ghidra, all platforms incl. the 3D CPUs: MIPS R3000/R4300 + SH-4) ──\n" +
     "'functions' = Rizin auto-detected function list {address,size,nbbs,cc,callers,callees,looksLikeData}; the " +
     "structural map of an unknown ROM. Sorted REAL CODE FIRST (by nbbs/cc) — don't rank by `size`, which is a lie " +
     "(rizin folds data tables into giant pseudo-functions). `looksLikeData:true` (and the top-level `dataCount`) flags " +

package/src/mcp/tools/index.js

@@ -155,7 +155,7 @@ const CATEGORIES = [
   },
   {
     name: "debug",
-    description: "Cross-platform debugging + reverse-engineering: inspectSprites, inspectPalette, getCPUState (main/spc700/z80), getAudioState (dsp/psg/ym2612), and the disasm/RE engine — disassemble (raw/ROM/rebuildable-project), plus the Rizin/Ghidra ops disasm({target:'cfg'|'xrefs'|'functions'|'decompile'}) (control-flow graphs, deep xrefs, auto-detected functions, and C pseudocode — all 14 platforms) and symbols({op:'analyze'}) (one-shot structural map).",
+    description: "Cross-platform debugging + reverse-engineering: inspectSprites, inspectPalette, getCPUState (main/spc700/z80, plus the 3D CPUs: MIPS R3000/R4300, SH-4), getAudioState (dsp/psg/ym2612/… + spu/ai/aica for PS1/N64/Dreamcast), and the disasm/RE engine — disassemble (raw/ROM/rebuildable-project), plus the Rizin/Ghidra ops disasm({target:'cfg'|'xrefs'|'functions'|'decompile'}) (control-flow graphs, deep xrefs, auto-detected functions, and C pseudocode) and symbols({op:'analyze'}) (one-shot structural map).",
     useWhen: ["sprites rendering wrong", "audio silent or distorted", "CPU stuck in unknown state", "need to read what existing ROM bytes do", "reverse-engineering an unknown ROM — carve its functions/structure before labeling them live", "want C-like pseudocode to understand a routine"],
     register: (s, z, k) => {
       registerPlatformSpecificTools(s, z, k); // inspectSprites/Palette, getCPUState, getDspState, ...

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

@@ -70,7 +70,7 @@ export async function listPlatformDocsCore({ platform }) {
         docs,
         note: docs.length === 0
           ? `No docs shipped for '${platform}' yet. Try a different platform, or fork an example game (examples({op:'fork'})) for boilerplate. (For RE/patching workflow, see platform({op:'doc', platform:'romhacking', name:'playbook'}).)`
-          : `Call platform({op:'doc', platform, name}) to read one. 'name' is 'mental_model' or 'troubleshooting'. For RE/patching workflow across platforms, see platform({op:'doc', platform:'romhacking', name:'playbook'}).`,
+          : `Call platform({op:'doc', platform, name}) to read one. 'name' is 'mental_model', 'troubleshooting', or 'upstream_sources' (whichever this platform ships — see the docs[] list above). For RE/patching workflow across platforms, see platform({op:'doc', platform:'romhacking', name:'playbook'}).`,
       };
 }