romdevtools 0.71.0 → 0.84.0

package/src/platforms/gametank/lib/gt/init.c

@@ -0,0 +1,9 @@
+#include "gametank.h"
+#include "gfx_sys.h"
+#include "audio_coprocessor.h"
+#include "music.h"
+void sdk_init(void) {
+    init_graphics();
+    init_audio_coprocessor();
+    init_music();
+}

package/src/platforms/gametank/lib/gt/input.c

@@ -0,0 +1,26 @@
+#include "input.h"
+#include "gametank.h"
+
+int player1_buttons = 0, player1_old_buttons = 0, player1_new_buttons = 0;
+int player2_buttons = 0, player2_old_buttons = 0, player2_new_buttons = 0;
+
+#pragma optimize (push, off)
+void update_inputs(){
+    char inputsA, inputsB;
+    inputsA = *gamepad_2;
+    inputsA = *gamepad_1;
+    inputsB = *gamepad_1;
+
+    player1_old_buttons = player1_buttons;
+    player1_buttons = ~((((int) inputsB) << 8) | inputsA);
+    player1_buttons &= INPUT_MASK_ALL_KEYS;
+    player1_new_buttons = player1_buttons & ~player1_old_buttons;
+
+    inputsA = *gamepad_2;
+    inputsB = *gamepad_2;
+    player2_old_buttons = player2_buttons;
+    player2_buttons = ~((((int) inputsB) << 8) | inputsA);
+    player2_buttons &= INPUT_MASK_ALL_KEYS;
+    player2_new_buttons = player2_buttons & ~player2_old_buttons;
+}
+#pragma optimize (pop)

package/src/platforms/gametank/lib/gt/input.h

@@ -0,0 +1,20 @@
+#ifndef INPUT_H
+#define INPUT_H
+
+extern int player1_buttons, player1_old_buttons, player1_new_buttons;
+extern int player2_buttons, player2_old_buttons, player2_new_buttons;
+
+#define INPUT_MASK_UP		2056
+#define INPUT_MASK_DOWN		1028
+#define INPUT_MASK_LEFT		512
+#define INPUT_MASK_RIGHT	256
+#define INPUT_MASK_A		16
+#define INPUT_MASK_B		4096
+#define INPUT_MASK_C		8192
+#define INPUT_MASK_START	32
+#define INPUT_MASK_ALL_KEYS (INPUT_MASK_UP|INPUT_MASK_DOWN|INPUT_MASK_LEFT|INPUT_MASK_RIGHT|INPUT_MASK_A|INPUT_MASK_B|INPUT_MASK_C|INPUT_MASK_START)
+#define INPUT_MASK_ANY_DIRECTION (INPUT_MASK_UP|INPUT_MASK_DOWN|INPUT_MASK_LEFT|INPUT_MASK_RIGHT)
+
+void update_inputs();
+
+#endif

package/src/platforms/gametank/lib/gt/interrupt.s

@@ -0,0 +1,67 @@
+; ---------------------------------------------------------------------------
+; interrupt.s
+; ---------------------------------------------------------------------------
+;
+; Interrupt handler.
+;
+; Checks for a BRK instruction and returns from all valid interrupts.
+
+.include "modules_enabled.inc"
+
+.import   _frameflag
+.import   _draw_busy
+.export   _irq_int, _nmi_int
+
+.ifdef ENABLE_MODULE_DRAWQUEUE
+.import _next_draw_queue, _queue_end, _queue_pending, _queue_start
+.endif
+
+.pc02
+
+DMA_Start = $4006
+
+.segment  "CODE"
+
+.PC02                             ; Force 65C02 assembly mode
+
+; ---------------------------------------------------------------------------
+; Non-maskable interrupt (NMI) service routine
+
+_nmi_int:
+        PHA
+        LDA $1FFF
+        BNE nmi_done
+        STZ _frameflag
+nmi_done:
+        PLA
+        RTI
+
+; ---------------------------------------------------------------------------
+; Maskable interrupt (IRQ) service routine
+
+.ifdef ENABLE_MODULE_DRAWQUEUE
+_irq_int:
+        PHX                    ; Save X register contents to stack
+        PHA
+        PHY
+
+        ;make sure DMA isn't running then compare head and tail of queue
+        ;to determine whether there is more to process
+        STZ DMA_Start
+        STZ _queue_pending
+        STZ _draw_busy
+        LDA _queue_start
+        CMP _queue_end
+        BEQ finish_irq
+        JSR _next_draw_queue
+finish_irq:
+        PLY
+        PLA                    ; Restore accumulator contents
+        PLX                    ; Restore X register contents
+        RTI                    ; Return from all IRQ interrupts
+.else
+_irq_int:
+        STZ DMA_Start
+        STZ _draw_busy
+        RTI
+.endif

package/src/platforms/gametank/lib/gt/vectors.s

@@ -0,0 +1,14 @@
+; ---------------------------------------------------------------------------
+; vectors.s
+; ---------------------------------------------------------------------------
+;
+; Defines the interrupt vector table.
+
+.import    _init
+.import    _nmi_int, _irq_int
+
+.segment  "VECTORS"
+
+.addr      _nmi_int    ; NMI vector
+.addr      _init       ; Reset vector
+.addr      _irq_int    ; IRQ/BRK vector

package/src/platforms/gametank/lib/gt/wait.s

@@ -0,0 +1,53 @@
+; ---------------------------------------------------------------------------
+; wait.s
+; ---------------------------------------------------------------------------
+;
+; Wait for interrupt and return
+
+.export  _wait, _stop, _nop5, _nop10
+
+; ---------------------------------------------------------------------------
+; Wait for interrupt:  Forces the assembler to emit a WAI opcode ($CB)
+; ---------------------------------------------------------------------------
+
+.segment  "CODE"
+
+.proc _wait: near
+
+.byte      $CB                    ; Inserts a WAI opcode
+           RTS                    ; Return to caller
+
+.endproc
+
+; ---------------------------------------------------------------------------
+; Stop:  Forces the assembler to emit a STP opcode ($DB)
+; ---------------------------------------------------------------------------
+
+.proc _stop: near
+
+.byte      $DB                    ; Inserts a STP opcode
+
+.endproc
+
+.proc _nop5
+        NOP
+        NOP
+        NOP
+        NOP
+        NOP
+        RTS
+.endproc
+
+.proc _nop10
+        NOP
+        NOP
+        NOP
+        NOP
+        NOP
+        NOP
+        NOP
+        NOP
+        NOP
+        NOP
+        RTS
+.endproc

package/src/platforms/gba/MENTAL_MODEL.md

@@ -248,6 +248,11 @@ Loadable via mGBA (`loadMedia`).
 
 ## What's NOT bundled
 
+- **`agbcc` (the legacy GBA compiler).** romdev's GBA C path is **modern
+  `arm-none-eabi-gcc` 14.2.0** only. The byte-exact decompilations + romhacks
+  (pokeruby / pokeemerald / pokefirered, etc.) build with agbcc + a custom
+  `ld_script.txt`, so romdev **cannot reproduce a matching retail ROM** for those.
+  That's a hard limit, not a missing feature — see "romdev's build model" below.
 - **libgba's `console.c`** (iprintf-style stdio output). Pulls in
   devkitPro's libsysbase header chain — not yet ported. See
   TROUBLESHOOTING.md for the trade-off rationale and workarounds.
@@ -256,7 +261,23 @@ Loadable via mGBA (`loadMedia`).
 - **devkitARM's `bin2s`** (binary → assembly converter for asset
   pipelines). Not bundled; ship binary assets as C arrays for now.
 
-Everything else from a stock devkitARM install works.
+Everything else from a stock devkitARM install (homebrew-style) works.
+
+## romdev's build model (read this before driving an existing project)
+
+`build` is a **single-shot "compile these sources → one ROM" tool**, NOT an arbitrary
+build-system backend. The toolchain binaries are **WASM, run only inside romdev's build
+worker (virtual FS)** — they are **not host-callable** and **cannot back an external
+project's `Makefile`** as `$(TOOLCHAIN)/bin`. (The `.mjs` wrappers under `node_modules`
+export a worker factory, not a CLI `main` — invoking one directly exits 0 and writes
+nothing.)
+
+So for an **existing decomp/romhack** (agbcc-era or any project with its own Makefile):
+build it **on the host** with its own toolchain, then point romdev at the resulting
+`.gba` for the run / inspect / debug / decompile loop. Confirmed host recipe for the
+Pokémon Gen-III decomps: `brew install arm-none-eabi-gcc arm-none-eabi-binutils`, clone
+`pret/agbcc` → `./build.sh` → `./install.sh <repo>`, then `make <target>` (yields a
+byte-matching ROM). romdev's value here is everything AFTER the build, not the build.
 
 ## Horizontal scrolling (for side-scrollers)
 

package/src/playtest/playtest.js

@@ -6,8 +6,10 @@ import {
   RETRO_PIXEL_FORMAT_0RGB1555,
   RETRO_PIXEL_FORMAT_RGB565,
   RETRO_PIXEL_FORMAT_XRGB8888,
+  ROMDEV_PIXEL_FORMAT_RGBA8888,
 } from "../host/retroConstants.js";
 import { log } from "../mcp/log.js";
+import { initResampler, resampleS16Stereo } from "./resampler/index.mjs";
 import path from "node:path";
 import { existsSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
 import { execFile } from "node:child_process";
@@ -203,10 +205,39 @@ const SDL_BUTTON_TO_LIBRETRO_BIT = {
   back: 2,      // SELECT
   guide: 2,
   start: 3,
-  leftShoulder: 10,
-  rightShoulder: 11,
-  leftStick: 14,
-  rightStick: 15,
+  leftShoulder: 10,   // RETRO L
+  rightShoulder: 11,  // RETRO R
+  leftStick: 14,      // RETRO L3
+  rightStick: 15,     // RETRO R3
+  // NOTE: L2/R2 (bits 12/13) are ANALOG triggers in libretro — node-sdl exposes
+  // them as axes (leftTrigger/rightTrigger), not buttons, so they're read from
+  // inst.axes below, not here.
+};
+
+// N64-specific pad map. parallel_n64's RetroPad layout (its digital_cbuttons_map)
+// is NOT the generic NES/SNES one — RETRO B="N64 A", RETRO Y="N64 B", RETRO X/A/L/R
+// are the four C-buttons, RETRO Select="N64 L", RETRO R2="N64 R", RETRO L2="N64 Z".
+// The N64's Z/L/R are DIGITAL buttons (its analog triggers don't exist), so on a
+// modern pad they go on the SHOULDER buttons, NOT the analog triggers (which idle
+// half-pressed and would stick). Layout for a standard X360-style pad:
+//   Xbox A (bottom) = N64 A   (accelerate)
+//   Xbox B (right)  = N64 B   (brake)
+//   Xbox X (left)   = N64 Z   (FIRE ITEM)  ← a free face button, easy to reach
+//   Xbox Y (top)    = N64 B   (alias, so either right/top brakes)
+//   L shoulder      = N64 L
+//   R shoulder      = N64 R   (hop / drift)
+//   right stick     = the four C-buttons (in readControllerInto)
+//   left stick/dpad = N64 analog stick (via the dpad→ANALOG synth in callbacks.js)
+const SDL_BUTTON_TO_LIBRETRO_BIT_N64 = {
+  dpadUp: 4, dpadDown: 5, dpadLeft: 6, dpadRight: 7,  // N64 d-pad (literal)
+  a: 0,               // Xbox A (bottom) → RETRO B  = N64 A   (accelerate)
+  b: 1,               // Xbox B (right)  → RETRO Y  = N64 B   (brake)
+  y: 1,               // Xbox Y (top)    → RETRO Y  = N64 B   (alias)
+  x: 12,              // Xbox X (left)   → RETRO L2 = N64 Z   (FIRE ITEM)
+  start: 3,           // Start
+  leftShoulder: 2,    // L shoulder → RETRO Select = N64 L
+  rightShoulder: 13,  // R shoulder → RETRO R2     = N64 R   (hop/drift)
+  // C-buttons (RETRO X/A/L/R) come from the RIGHT STICK in readControllerInto.
 };
 
 // Analog stick → dpad direction (for games that only read dpad)
@@ -479,12 +510,22 @@ export async function playtest(args) {
   }
 
   // Open the window.
+  //
+  // HW-render cores (n64/ps1/dreamcast) already own a GL context via native-gles
+  // (the EGL pbuffer the core renders its RDP/GPU into; we glReadPixels it to CPU
+  // pixels). If the SDL window ALSO requests an accelerated (GL) renderer, node-sdl
+  // calls glXMakeCurrent on the same X display and the two GL contexts collide →
+  // `X Error BadAccess (GLX X_GLXMakeCurrent)`, crashing the process. The window only
+  // ever presents CPU pixels (window.render(..., "rgba32", rgba)), so it does NOT need
+  // its own GL context — open a SOFTWARE-blit window for HW-render cores to avoid the
+  // context fight. Software cores keep the accelerated path (faster upscale blit).
+  const hwRenderCore = !!host.hwRender;
   const window = sdl.video.createWindow({
     title,
     width: winInitW,
     height: winInitH,
     resizable: true,
-    accelerated: true,
+    accelerated: hwRenderCore ? false : true,
     vsync: false,
   });
   log.debug(`[playtest] window opened: ${winInitW}x${winInitH}, fb=${fbWidth}x${fbHeight}, aspect=${aspectMode}`);
@@ -494,16 +535,38 @@ export async function playtest(args) {
   // Mismatched rates produce choppy/sped-up/cracking playback because the
   // SDL device consumes samples at the wrong rate, alternately starving
   // (clicks) and overflowing.
+  //
+  // EXCEPTION — very-low-rate cores (the GameTank ACP emits ~13983 Hz, 3x lower
+  // than anything else): SDL's device buffer granularity (thousands of samples)
+  // dwarfs a 60 fps core's ~233-sample-per-frame chunks at that rate, so the
+  // device starves between ticks = clicks and pops. (RetroArch avoids this with
+  // a sinc resampler + dynamic rate control to the device rate.) So for low
+  // rates we open the device at 48 kHz and LINEAR-RESAMPLE each chunk up to it,
+  // which makes the per-frame chunks big enough for clean playback.
   let audio = null;
   const coreSampleRate = Math.round(host.status.audioSampleRate ?? 48000);
+  const AUDIO_RESAMPLE_TO = 48000;
+  let needsResample = coreSampleRate > 0 && coreSampleRate < 24000;
+  // Load the WASM+SIMD resampler if this core needs upsampling. If it fails to
+  // load, fall back to opening the device at the native rate (better than no
+  // audio) — needsResample is forced off so we never call a missing resampler.
+  if (needsResample) {
+    const ready = await initResampler();
+    if (!ready) {
+      log.error("[playtest] resampler WASM failed to load — using native rate (audio may click)");
+      needsResample = false;
+    }
+  }
+  const deviceSampleRate = needsResample ? AUDIO_RESAMPLE_TO : coreSampleRate;
   try {
     audio = sdl.audio.openDevice({ type: "playback" }, {
       channels: 2,
-      frequency: coreSampleRate,
+      frequency: deviceSampleRate,
       format: "s16",
     });
     audio.play();
-    log.debug(`[playtest] audio: ${coreSampleRate} Hz, stereo, s16`);
+    log.debug(`[playtest] audio: ${deviceSampleRate} Hz, stereo, s16` +
+      (needsResample ? ` (resampled from core ${coreSampleRate} Hz)` : ""));
   } catch (e) {
     log.error("[playtest] audio init failed (continuing silent):", e.message);
   }
@@ -688,7 +751,15 @@ export async function playtest(args) {
 
   // Tick = one emulated frame + render + audio drain. Driven by setInterval
   // so the Node event loop stays free for MCP requests on the same host.
-  const frameMs = 1000 / 60;
+  // Pace to the CORE's native refresh rate (status.coreFps), not a hardcoded 60: a
+  // 30fps title (Sonic Adventure on flycast) at a 60Hz tick gets double-ticked —
+  // wasting half the budget and, on the heavy interpreter-only DC core (23ms/frame,
+  // no JIT), falling behind every tick → the black-flash/glitch. At its real 30fps
+  // each frame gets a full 33ms tick, which the core can actually hit. Clamped so a
+  // bogus report can't run the window absurdly fast or slow.
+  const coreFps = openHost?.status?.coreFps;
+  const fps = (coreFps >= 20 && coreFps <= 120) ? coreFps : 60;
+  const frameMs = 1000 / fps;
 
   function tick() {
     if (!running || window.destroyed) { stop(); return; }
@@ -704,7 +775,12 @@ export async function playtest(args) {
     // the N-second cadence; serialize off the live host so it captures the human's
     // exact progress. Skipped while paused (nothing changed) and on the very first
     // ticks (let the core settle).
-    if (checkpointPath && tickCount - lastCheckpointTick >= checkpointEverySec * 60 && !h.status.paused) {
+    // Auto-checkpoint serializes the WHOLE machine state — cheap for 8/16-bit (KB,
+    // instant) but BRUTAL for the hwRender 3D cores (DC/N64 savestate ≈16MB, ~18ms
+    // to serialize), which would freeze the window for ~18ms every cadence on an
+    // already-slow core. Skip it entirely for hwRender — same call as the rewind
+    // buffer skip. (Eviction recovery matters less than a playable window here.)
+    if (!h.hwRender && checkpointPath && tickCount - lastCheckpointTick >= checkpointEverySec * 60 && !h.status.paused) {
       lastCheckpointTick = tickCount;
       writeCheckpoint(h, "auto");
     }
@@ -726,6 +802,7 @@ export async function playtest(args) {
     // window leaves it alone. Select+Start on any controller quits.
     let quit = false;
     const isC64 = h.status?.platform === "c64";
+    const isN64 = h.status?.platform === "n64";
     function readControllerInto(port, inst) {
       if (!inst) return;
       const btn = inst.buttons || {};
@@ -733,7 +810,8 @@ export async function playtest(args) {
         quit = true;
         return;
       }
-      for (const [sdlName, bit] of Object.entries(SDL_BUTTON_TO_LIBRETRO_BIT)) {
+      const buttonMap = isN64 ? SDL_BUTTON_TO_LIBRETRO_BIT_N64 : SDL_BUTTON_TO_LIBRETRO_BIT;
+      for (const [sdlName, bit] of Object.entries(buttonMap)) {
         if (btn[sdlName]) port[bitToName(bit)] = true;
       }
       const axes = inst.axes || {};
@@ -743,6 +821,9 @@ export async function playtest(args) {
       else if (lx < -STICK_DEADZONE) port.left = true;
       if (ly > STICK_DEADZONE) port.down = true;
       else if (ly < -STICK_DEADZONE) port.up = true;
+      // NOTE: the analog triggers are NOT used for N64 — its Z/L/R are digital and
+      // map to the SHOULDER buttons (see SDL_BUTTON_TO_LIBRETRO_BIT_N64). (node-sdl's
+      // X360 trigger axes also idle at ~0.5, so reading them as buttons would stick.)
       // C64: the RIGHT stick selects the function keys (F1/F3/F5/F7) — the
       // Batocera/RetroDeck convention so a controller alone reaches the keyboard
       // keys C64 setup screens need. Emitted as virtual buttons the host's C64
@@ -755,6 +836,19 @@ export async function playtest(args) {
         if (rx < -STICK_DEADZONE) port.c64_f3 = true;        // left  → F3
         else if (rx > STICK_DEADZONE) port.c64_f5 = true;    // right → F5
       }
+      // N64: the RIGHT stick drives the four C-buttons — the standard emulation
+      // convention so a modern dual-stick pad plays N64 naturally (left stick =
+      // analog stick via the d-pad synthesis in callbacks.js; right stick = C). The
+      // C-buttons land on libretro bits A/X/L/R, which parallel_n64 reads as
+      // C-Down/C-Up/C-Left/C-Right. Z is the left trigger (mapped above).
+      if (isN64) {
+        const rx = axes.rightStickX ?? 0;
+        const ry = axes.rightStickY ?? 0;
+        if (ry < -STICK_DEADZONE) port.x = true;        // up    → C-Up    (RETRO X)
+        else if (ry > STICK_DEADZONE) port.a = true;    // down  → C-Down  (RETRO A)
+        if (rx < -STICK_DEADZONE) port.l = true;        // left  → C-Left  (RETRO L)
+        else if (rx > STICK_DEADZONE) port.r = true;    // right → C-Right (RETRO R)
+      }
     }
 
     const port0 = {};
@@ -792,8 +886,14 @@ export async function playtest(args) {
       // either port)?
       const humanPressing = anyButtonHeld(port0) || anyButtonHeld(port1);
       humanInput.note(humanPressing, tickCount);
-      // Capture snapshot before stepping so R can rewind to it later.
-      if (h.status?.loaded) {
+      // Capture snapshot before stepping so R can rewind to it later. SKIP for
+      // hwRender cores (n64/ps1/dreamcast): their savestates are HUGE (N64 ≈16MB
+      // each — 600 frames would be ~9GB of RAM) and serializeState costs ~8ms/frame
+      // there, eating half the 16.6ms budget and starving the audio feed (the choppy
+      // playback). The R-key rewind is a nicety, not worth that on the 3D engines —
+      // pause + savestate still work for those. (Rewind buffer is playtest-only; it's
+      // NOT part of the debug ABI, so dropping it on these cores changes nothing else.)
+      if (h.status?.loaded && !h.hwRender) {
         try {
           const snap = h.serializeState();
           rewindBuffer.push(snap);
@@ -810,9 +910,39 @@ export async function playtest(args) {
         h.setInput({ ports: [port0, port1] });
         humanInputDirty = humanPressing;
       }
+      // AUDIO-PACED stepping, BUDGETED BY WALL-CLOCK. We catch the buffer up by
+      // stepping extra frames per tick to keep SDL's queue topped — but a fast core
+      // (n64 2.4ms/frame) and a SUB-REALTIME core (flycast DC ~60ms/frame) need very
+      // different burst sizes. A fixed MAX_STEPS frame-count cap is the trap: 8 frames
+      // is 19ms on n64 (fine) but 480ms on DC — which BLOCKS the Node event loop for
+      // half a second per tick, so the window can't repaint and audio drains dry →
+      // "breaks down, super choppy" death spiral that never recovers. The fix is to
+      // cap by TIME: keep stepping only while we're under a wall-clock budget (~1.5
+      // ticks). A sub-realtime core then runs steady-slow (audio underruns gracefully,
+      // a constant low pitch) instead of stuttering — and the loop ALWAYS yields the
+      // event loop promptly so the window stays responsive.
       let stepped = 0;
       try {
-        stepped = h.stepFrames(1);
+        if (audio && deviceSampleRate > 0) {
+          const bps = deviceSampleRate * 4; // stereo s16
+          const TARGET_MS = 60;             // keep ~60ms queued — drain sets the speed
+          const BUDGET_MS = frameMs * 1.5;  // wall-clock ceiling for the whole burst
+          const burstStart = performance.now();
+          do {
+            stepped += h.stepFrames(1);
+            // Stop the instant we've spent our wall-clock budget — this is what keeps
+            // a slow core from freezing the loop. A single frame already over budget
+            // still steps once (progress), then we yield.
+            if (performance.now() - burstStart >= BUDGET_MS) break;
+            const qMs = ((audio.queued ?? 0) / bps) * 1000;
+            let ringMs = 0;
+            for (const b of h.state.audioRing) ringMs += (b.length / 2);
+            ringMs = (ringMs / deviceSampleRate) * 1000;
+            if (qMs + ringMs >= TARGET_MS) break;
+          } while (true);
+        } else {
+          stepped = h.stepFrames(1); // no audio device → plain 1 frame/tick
+        }
       } catch (e) {
         // A step error mid-swap (host being torn down/rebuilt) is transient —
         // skip this frame and let the next tick pick up the new host. Don't kill
@@ -879,17 +1009,16 @@ export async function playtest(args) {
     }
 
     if (running && audio && h.state.audioRing.length > 0) {
-      // SDL device tells us how many bytes are still queued (not yet played).
-      // If we get >200ms ahead, the player got a stutter and is now
-      // building latency — drop new samples until the queue drains back
-      // to ~50ms. This keeps audio synced to wall clock without underruns.
-      // Wrap the whole block in try/catch — stop() may have closed the
-      // audio device between the running check and the access below.
+      // Enqueue the real audio the core produced this tick. The AUDIO-PACED stepping
+      // above already steps however many frames are needed to keep ~60ms queued, so
+      // the buffer stays full from REAL samples — no silence padding, no rate-deficit
+      // starvation. SDL's steady drain at the device rate is what sets emulation speed.
+      // We only stop enqueuing if latency runs away (>250ms) — a safety valve, not
+      // the normal path.
       try {
-        const bytesPerSecond = coreSampleRate * 2 /* ch */ * 2 /* s16 */;
-        const queuedBytes = audio.queued ?? 0;
-        const queuedMs = (queuedBytes / bytesPerSecond) * 1000;
-        if (queuedMs < 200) {
+        const bytesPerSecond = deviceSampleRate * 2 /* ch */ * 2 /* s16 */;
+        const queuedMs = ((audio.queued ?? 0) / bytesPerSecond) * 1000;
+        if (queuedMs < 250) {
           let total = 0;
           for (const buf of h.state.audioRing) total += buf.byteLength;
           const merged = Buffer.alloc(total);
@@ -898,14 +1027,15 @@ export async function playtest(args) {
             merged.set(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength), off);
             off += buf.byteLength;
           }
-          audio.enqueue(merged);
+          audio.enqueue(needsResample
+            ? resampleS16Stereo(merged, coreSampleRate, deviceSampleRate)
+            : merged);
         }
       } catch (e) {
         if (!e.message?.includes("closed")) {
           log.error("[playtest] audio enqueue error:", e.message);
         }
       }
-      // Always clear the ring — if we skipped enqueue we drop those samples.
       h.state.audioRing.length = 0;
     }
   }
@@ -992,7 +1122,25 @@ function bitToName(bit) {
 /** Convert libretro framebuffer (any pixel format) to RGBA32. */
 function framebufferToRgba(f) {
   const out = Buffer.alloc(f.width * f.height * 4);
-  if (f.format === RETRO_PIXEL_FORMAT_XRGB8888) {
+  if (f.format === ROMDEV_PIXEL_FORMAT_RGBA8888) {
+    // HW-render readback (n64/ps1/dreamcast via native-gles): pixels are ALREADY
+    // RGBA in row order. Copy straight through but FORCE alpha=255 — the GL render
+    // target leaves alpha=0 (unused channel), which SDL would composite as fully
+    // transparent → a black window. This is the on-screen analogue of the same
+    // alpha fix framebufferToRgba() in framebuffer.js does for screenshots.
+    for (let y = 0; y < f.height; y++) {
+      const src = y * f.pitch;
+      const dst = y * f.width * 4;
+      for (let x = 0; x < f.width; x++) {
+        const s = src + x * 4;
+        const d = dst + x * 4;
+        out[d + 0] = f.pixels[s + 0];
+        out[d + 1] = f.pixels[s + 1];
+        out[d + 2] = f.pixels[s + 2];
+        out[d + 3] = 0xff;
+      }
+    }
+  } else if (f.format === RETRO_PIXEL_FORMAT_XRGB8888) {
     for (let y = 0; y < f.height; y++) {
       const src = y * f.pitch;
       const dst = y * f.width * 4;

package/src/playtest/resampler/build.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Build the WASM+SIMD audio resampler for the playtest sink.
+# Mirrors simdpipe's emcc style (-O3 -msimd128, MODULARIZE ES6). Single-thread,
+# small heap (audio chunks are a few KB). Output: resampler.mjs + resampler.wasm.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+source "$HOME/code/mine/emsdk/emsdk_env.sh" >/dev/null 2>&1 || true
+
+emcc resampler.c \
+  -O3 -msimd128 -ffast-math \
+  -s WASM=1 -s MODULARIZE=1 -s EXPORT_ES6=1 \
+  -s ENVIRONMENT=node,web,worker \
+  -s ALLOW_MEMORY_GROWTH=1 -s INITIAL_MEMORY=4194304 \
+  -s EXPORTED_RUNTIME_METHODS='["HEAP16","HEAPU8","cwrap","ccall"]' \
+  -s EXPORTED_FUNCTIONS='["_rs_alloc","_rs_free","_rs_resample","_malloc","_free"]' \
+  -o resampler.mjs
+
+echo "built resampler.mjs + resampler.wasm ($(stat -c%s resampler.wasm 2>/dev/null || echo '?') bytes)"

package/src/playtest/resampler/index.mjs

@@ -0,0 +1,75 @@
+/* ── resampler/index.mjs — JS wrapper for the WASM+SIMD audio resampler ────────
+ *
+ * Loads the WASM module once and exposes resampleS16Stereo(buf, src, dst) that
+ * resamples an interleaved S16LE stereo Node Buffer. Used by the playtest audio
+ * sink for low-rate cores (the GameTank ACP at ~13983 Hz) — see resampler.c for
+ * the why (libretro frontends resample; only GameTank is low enough to need it).
+ *
+ * The WASM scratch buffers are sized once to the largest chunk seen and reused.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+let mod = null;        // the emscripten Module
+let inPtr = 0, inCap = 0;    // input scratch (bytes)
+let outPtr = 0, outCap = 0;  // output scratch (bytes)
+
+/** Lazily instantiate the WASM module. Returns true once ready, false if it
+ * failed to load (caller falls back to passing audio through unresampled). */
+export async function initResampler() {
+  if (mod) return true;
+  try {
+    const factory = (await import(path.join(__dirname, "resampler.mjs"))).default;
+    mod = await factory();
+    return true;
+  } catch (e) {
+    mod = null;
+    return false;
+  }
+}
+
+function ensureCap(needIn, needOut) {
+  if (needIn > inCap) {
+    if (inPtr) mod._rs_free(inPtr);
+    inCap = needIn * 2; // grow with headroom
+    inPtr = mod._rs_alloc(inCap);
+  }
+  if (needOut > outCap) {
+    if (outPtr) mod._rs_free(outPtr);
+    outCap = needOut * 2;
+    outPtr = mod._rs_alloc(outCap);
+  }
+}
+
+/**
+ * Resample an interleaved S16LE stereo Buffer from srcRate to dstRate using the
+ * WASM+SIMD core. Synchronous; initResampler() must have resolved true first.
+ * Falls back to returning the input unchanged if the module isn't loaded.
+ * @param {Buffer} buf interleaved S16LE stereo at srcRate
+ * @param {number} srcRate
+ * @param {number} dstRate
+ * @returns {Buffer} interleaved S16LE stereo at dstRate
+ */
+export function resampleS16Stereo(buf, srcRate, dstRate) {
+  if (!mod || srcRate === dstRate || srcRate <= 0 || dstRate <= 0) return buf;
+  const inFrames = (buf.length / 4) | 0; // 4 bytes/stereo frame
+  if (inFrames < 2) return buf;
+  const maxOutFrames = Math.ceil(inFrames * (dstRate / srcRate)) + 2;
+
+  ensureCap(inFrames * 4, maxOutFrames * 4);
+
+  // copy input into WASM heap
+  mod.HEAPU8.set(new Uint8Array(buf.buffer, buf.byteOffset, buf.length), inPtr);
+
+  const outFrames = mod._rs_resample(
+    inPtr, inFrames, outPtr, maxOutFrames, srcRate, dstRate
+  );
+  if (outFrames <= 0) return buf;
+
+  // copy result out into a fresh Buffer (the audio device owns its own memory,
+  // and the WASM heap may move on the next call).
+  const outBytes = outFrames * 4;
+  return Buffer.from(new Uint8Array(mod.HEAPU8.buffer, outPtr, outBytes));
+}