romdevtools 0.13.0

package/src/host/lynx-mikey-state.js

@@ -0,0 +1,226 @@
+// Atari Lynx (Mikey chip) state introspection.
+//
+// Same idea as nes-apu-state.js / gb-apu-state.js: give Lynx music and
+// graphics jobs a "what is each channel playing / what palette is loaded /
+// where is the display pointed this frame?" decode straight off the hardware
+// register file, independent of whatever private driver the game uses.
+//
+// Data source: the `lynx_hw_regs` region — the 512-byte Lynx hardware window
+// at $FC00-$FDFF. Byte offset `i` in the array == Lynx address $FC00 + i, so
+// the Mikey registers ($FD00-$FDFF) live in the second half, offsets
+// 0x100-0x1FF. (Suzy is the first half, $FC00-$FCFF; we don't decode it here.)
+//
+// Mikey owns audio, the palette, and the display controller:
+//
+//   Audio ch N base = 0x120 + N*8   (ch0=$FD20, ch1=$FD28, ch2=$FD30, ch3=$FD38)
+//     +0 VOLUME    signed 8-bit               $FD20
+//     +1 FEEDBACK  shift-register feedback taps $FD21
+//     +2 OUTPUT    current output value        $FD22
+//     +3 SHIFT     low 8 bits of the 12-bit LFSR $FD23
+//     +4 BACKUP    timer reload/period (pitch) $FD24
+//     +5 CONTROL   clock select + enable bits  $FD25
+//     +6 COUNTER   current timer value         $FD26
+//     +7 OTHER     bits 4-7 = high nibble of 12-bit LFSR; bits 0-3 misc $FD27
+//   MPAN    $FD44 (offset 0x144) per-channel pan
+//   MSTEREO $FD50 (offset 0x150) per-channel L/R enable (STEREO)
+//   Palette green nibbles $FDA0-$FDAF (offset 0x1A0-0x1AF): low nibble = green4
+//   Palette blue+red      $FDB0-$FDBF (offset 0x1B0-0x1BF): hi nibble = blue4,
+//                                                            lo nibble = red4
+//   DISPCTL $FD92 (offset 0x192) display control flags
+//   DISPADR $FD94-$FD95 (offset 0x194, 16-bit LE) display DMA base address
+//
+// These are the *register* bytes (what the CPU last wrote / what Mikey holds),
+// which is exactly the pitch/volume/colour/display layer you want for music
+// transcription and visual debugging without reverse-engineering the game's
+// private driver.
+
+import { freqToNote } from "./gb-apu-state.js";
+
+// Mikey audio register block: 4 channels, 8 bytes apart, starting at $FD20.
+const AUDIO_BASE = 0x120;
+const AUDIO_STRIDE = 0x08;
+
+// CONTROL low 3 bits select the timer's clock source. Each tick is this many
+// microseconds; index 7 = "link" (clocked by the previous timer's underflow),
+// for which we can't derive an absolute frequency.
+const US_PER_TICK = [1, 2, 4, 8, 16, 32, 64];
+
+// Palette register offsets within the 512-byte `lynx_hw_regs` window.
+const PAL_GREEN = 0x1a0; // $FDA0-$FDAF: low nibble = 4-bit green
+const PAL_BLUERED = 0x1b0; // $FDB0-$FDBF: hi nibble = blue, lo nibble = red
+
+// Display controller register offsets.
+const DISPCTL = 0x192; // $FD92
+const DISPADR = 0x194; // $FD94-$FD95 (16-bit LE)
+
+// Pan / stereo register offsets.
+const MPAN = 0x144; // $FD44
+const MSTEREO = 0x150; // $FD50
+
+/** Format a byte as a "0x.." hex string (2 digits). */
+function hex(b) {
+  return "0x" + (b & 0xff).toString(16).padStart(2, "0");
+}
+
+/** Format a 16-bit value as a "0x...." hex string (4 digits). */
+function hex16(v) {
+  return "0x" + (v & 0xffff).toString(16).padStart(4, "0");
+}
+
+/** Round a frequency to 2 decimal places (null stays null). */
+function round2(hz) {
+  return hz == null ? null : Math.round(hz * 100) / 100;
+}
+
+/** Interpret a byte as a signed 8-bit value (-128..127). */
+function signed8(b) {
+  return (b & 0x80) ? (b & 0xff) - 256 : (b & 0xff);
+}
+
+/** Expand a 4-bit value (0-15) to 8-bit, replicating the nibble (0xF -> 0xFF). */
+function expand4(v) {
+  return ((v & 0x0f) << 4) | (v & 0x0f);
+}
+
+/**
+ * @typedef {{
+ *   volume: number, freqHz: number|null, note: string|null, enabled: boolean,
+ *   clockSelect: number, backup: number, integrate: boolean, feedback: number,
+ *   shiftRegister: number, output: number
+ * }} LynxAudioChannel
+ */
+
+/**
+ * Decode the Lynx Mikey audio register file into per-channel musical state.
+ *
+ * Frequency is approximate: the channel timer is clocked every `usPerTick`
+ * microseconds (selected by CONTROL bits 0-2) and the audio output toggles
+ * every (BACKUP+1) ticks, so a full waveform cycle takes two toggles:
+ *   freqHz = 1e6 / ((BACKUP + 1) * usPerTick * 2)
+ * usPerTick = [1,2,4,8,16,32,64][clockSelect] for clockSelect 0-6;
+ * clockSelect 7 = "link" (timer chained to another) -> freqHz reported null.
+ * This ignores the LFSR/integrate modes, so treat it as a pitch estimate and
+ * cross-check with recordAudio when a channel looks ambiguous.
+ *
+ * @param {Uint8Array} hw the 512-byte `lynx_hw_regs` region ($FC00-$FDFF)
+ * @returns {{
+ *   channels: LynxAudioChannel[],
+ *   stereo: string,
+ *   pan: string,
+ * }}
+ */
+export function decodeLynxMikey(hw) {
+  const channels = [];
+  for (let n = 0; n < 4; n++) {
+    const base = AUDIO_BASE + n * AUDIO_STRIDE;
+    const volume = signed8(hw[base + 0]); // +0 VOLUME (signed)
+    const feedback = hw[base + 1]; // +1 FEEDBACK
+    const output = signed8(hw[base + 2]); // +2 OUTPUT (signed sample value)
+    const shift = hw[base + 3]; // +3 SHIFT (low 8 bits of LFSR)
+    const backup = hw[base + 4]; // +4 BACKUP (timer period)
+    const control = hw[base + 5]; // +5 CONTROL
+    const other = hw[base + 7]; // +7 OTHER (hi nibble of LFSR in bits 4-7)
+
+    const clockSelect = control & 0x07; // bits 0-2: clock source select
+    const enabled = !!(control & 0x10); // bit 4: enable-count
+    const integrate = !!(control & 0x20); // bit 5: integrate mode
+
+    // Frequency only means something when the channel is actually counting
+    // (enable-count set). A disabled channel — or clockSelect 7 "link" — has no
+    // standalone tone, so report null rather than a bogus ultrasonic value (a
+    // disabled channel commonly reads backup=0 → a meaningless 500 kHz).
+    const usPerTick = clockSelect < 7 ? US_PER_TICK[clockSelect] : null;
+    const freqHz =
+      (enabled && usPerTick != null) ? 1e6 / ((backup + 1) * usPerTick * 2) : null;
+
+    // 12-bit LFSR state: low 8 bits in SHIFT, high 4 bits in OTHER bits 4-7.
+    const shiftRegister = shift | ((other & 0xf0) << 4);
+
+    channels.push({
+      volume,
+      freqHz: round2(freqHz),
+      note: freqToNote(freqHz),
+      enabled,
+      clockSelect,
+      backup,
+      integrate,
+      feedback,
+      shiftRegister,
+      output,
+    });
+  }
+
+  return {
+    channels,
+    stereo: hex(hw[MSTEREO]), // $FD50 MSTEREO: per-channel L/R enable bits
+    pan: hex(hw[MPAN]), // $FD44 MPAN: per-channel pan
+  };
+}
+
+/**
+ * @typedef {{
+ *   index: number, r: number, g: number, b: number, hex: string,
+ *   green4: number, red4: number, blue4: number
+ * }} LynxPaletteEntry
+ */
+
+/**
+ * Decode the Lynx Mikey 16-entry palette into 8-bit RGB.
+ *
+ * Each colour is 12-bit (4 bits per component), split across two register
+ * banks: green nibbles at $FDA0-$FDAF, blue+red at $FDB0-$FDBF. We expand each
+ * 4-bit component to 8-bit by nibble replication (0xF -> 0xFF) so `hex` is a
+ * directly usable "#rrggbb" web colour.
+ *
+ * @param {Uint8Array} hw the 512-byte `lynx_hw_regs` region ($FC00-$FDFF)
+ * @returns {{ entries: LynxPaletteEntry[] }}
+ */
+export function decodeLynxPalette(hw) {
+  const entries = [];
+  for (let i = 0; i < 16; i++) {
+    const green4 = hw[PAL_GREEN + i] & 0x0f; // low nibble = green
+    const blueRed = hw[PAL_BLUERED + i];
+    const blue4 = (blueRed >> 4) & 0x0f; // hi nibble = blue
+    const red4 = blueRed & 0x0f; // lo nibble = red
+    const r = expand4(red4);
+    const g = expand4(green4);
+    const b = expand4(blue4);
+    const hx =
+      "#" +
+      r.toString(16).padStart(2, "0") +
+      g.toString(16).padStart(2, "0") +
+      b.toString(16).padStart(2, "0");
+    entries.push({ index: i, r, g, b, hex: hx, green4, red4, blue4 });
+  }
+  return { entries };
+}
+
+/**
+ * Decode the Lynx Mikey display controller (DISPCTL + DISPADR).
+ *
+ * DISPCTL ($FD92) bits: bit0 = display DMA enable, bit1 = flip (left-handed
+ * mode / vertical flip), bit3 = 4-colour mode (vs the default 4 bits-per-pixel
+ * 16-colour mode). DISPADR ($FD94-$FD95, 16-bit LE) is the display DMA base
+ * address — where Mikey reads the framebuffer from.
+ *
+ * @param {Uint8Array} hw the 512-byte `lynx_hw_regs` region ($FC00-$FDFF)
+ * @returns {{
+ *   dispctl: string, displayDmaEnable: boolean, flip: boolean,
+ *   fourColour: boolean, displayAddress: string, note: string,
+ * }}
+ */
+export function decodeLynxRenderingContext(hw) {
+  const dispctl = hw[DISPCTL];
+  const displayAddress = hw[DISPADR] | (hw[DISPADR + 1] << 8);
+  return {
+    dispctl: hex(dispctl),
+    displayDmaEnable: !!(dispctl & 0x01), // bit0: display DMA enable
+    flip: !!(dispctl & 0x02), // bit1: flip
+    fourColour: !!(dispctl & 0x08), // bit3: 4-colour mode (else 16-colour 4bpp)
+    displayAddress: hex16(displayAddress),
+    note:
+      "DISPCTL ($FD92) + DISPADR ($FD94). displayDmaEnable off means Mikey " +
+      "isn't scanning out a framebuffer (blank screen). displayAddress is the " +
+      "DMA base Mikey reads pixels from each frame.",
+  };
+}

package/src/host/msx-ay-state.js

@@ -0,0 +1,78 @@
+// MSX AY-3-8910 (PSG) decoder.
+//
+// Data source: the `msx_psg_regs` region (id 0x1C5) exposed by our patched
+// blueMSX core — the chip's 16 registers, the standard AY-3-8910 layout:
+//   R0/R1   channel A tone period (12-bit: R0 = fine, R1 low nibble = coarse)
+//   R2/R3   channel B tone period
+//   R4/R5   channel C tone period
+//   R6      noise period (5-bit)
+//   R7      mixer/enable: bits 0-2 tone A/B/C enable (0=on), bits 3-5 noise A/B/C
+//           enable (0=on), bits 6-7 = I/O port direction
+//   R8/R9/R10  channel A/B/C amplitude (bit 4 = use-envelope, bits 0-3 = level)
+//   R11/R12 envelope period (16-bit)
+//   R13     envelope shape (CONT/ATT/ALT/HOLD)
+//   R14/R15 I/O ports A/B (joysticks/keyboard on MSX — not audio)
+//
+// MSX PSG clock is 1.7897725 MHz; tone f = clock / (16 * period).
+
+const PSG_CLOCK = 1789772.5;
+
+/**
+ * @param {Uint8Array} regs the 16-byte `msx_psg_regs` region
+ * @returns {{ chip:"ay8910", channels:Array<object>, noise:object, envelope:object, ioPorts:object }}
+ */
+export function decodeMsxAy(regs) {
+  const mixer = regs[7];
+  const channels = [];
+  for (let i = 0; i < 3; i++) {
+    const fine = regs[i * 2];
+    const coarse = regs[i * 2 + 1] & 0x0f;
+    const period = (coarse << 8) | fine;
+    const toneOn = !((mixer >> i) & 1);     // bit clear = enabled
+    const noiseOn = !((mixer >> (i + 3)) & 1);
+    const amp = regs[8 + i];
+    const useEnvelope = !!(amp & 0x10);
+    const hz = toneOn && period ? Math.round(PSG_CLOCK / (16 * period)) : 0;
+    channels.push({
+      channel: ["A", "B", "C"][i],
+      tonePeriod: period,
+      approxHz: hz,
+      toneEnabled: toneOn,
+      noiseEnabled: noiseOn,
+      amplitude: amp & 0x0f,
+      useEnvelope,
+    });
+  }
+  const noisePeriod = regs[6] & 0x1f;
+  const envPeriod = regs[11] | (regs[12] << 8);
+  const envShape = regs[13];
+  return {
+    chip: "ay8910",
+    channels,
+    noise: {
+      period: noisePeriod,
+      approxHz: noisePeriod ? Math.round(PSG_CLOCK / (16 * noisePeriod)) : 0,
+    },
+    envelope: {
+      period: envPeriod,
+      shape: envShape,
+      continue: !!(envShape & 0x08),
+      attack: !!(envShape & 0x04),
+      alternate: !!(envShape & 0x02),
+      hold: !!(envShape & 0x01),
+    },
+    mixer,
+    ioPorts: { a: regs[14], b: regs[15] },
+  };
+}
+
+/**
+ * Read + decode the PSG state from a running host.
+ * @param {import("./LibretroHost.js").LibretroHost} host
+ * @returns {ReturnType<typeof decodeMsxAy> | null}
+ */
+export function getMsxAyState(host) {
+  const size = host.regionSize("msx_psg_regs");
+  if (!size) return null;
+  return decodeMsxAy(host.readMemory("msx_psg_regs", 0, size));
+}

package/src/host/nes-apu-state.js

@@ -0,0 +1,194 @@
+// NES 2A03 APU state introspection.
+//
+// Per the rom-games music-analysis asks: give NES titles the same "what is
+// each channel playing this frame?" decode that getAudioState already gives
+// SNES (dsp) and Genesis (psg/ym2612). Before this, an NES music job had to
+// reverse-engineer the game's private sound-driver RAM by hand; now the
+// hardware register file is decoded directly, game-driver-independent.
+//
+// Data source: the `nes_apu_regs` region (id 0x104) exposed by our fceumm
+// patch (scripts/patches/fceumm-romdev-memory-regions.patch). It's a 24-byte
+// synthesized snapshot of the APU register file at CPU $4000-$4017:
+//
+//   [0x00..0x0F]  PSG[0..15]      — $4000-$400F (pulse1, pulse2, triangle, noise)
+//   [0x10]        DMCFormat       — $4010
+//   [0x11]        RawDALatch      — $4011 (DMC direct load, 7-bit)
+//   [0x12]        DMCAddressLatch — $4012
+//   [0x13]        DMCSizeLatch    — $4013
+//   [0x14]        0               — ($4014 is OAMDMA, not APU; zero-filled)
+//   [0x15]        EnabledChannels — $4015 (write side: per-channel enable)
+//   [0x16]        0               — ($4016 is controller, not APU)
+//   [0x17]        IRQFrameMode    — $4017 (frame counter mode)
+//
+// These are the *register* bytes (what the CPU last wrote), not the APU's
+// internal swe/envelope counters — which is exactly what you want for music
+// transcription: timer + duty + volume nibble decode straight to pitch.
+
+// 2A03 CPU clock (NTSC). Pulse freq = CPU / (16 * (timer + 1)),
+// triangle freq = CPU / (32 * (timer + 1)). PAL differs but fceumm
+// defaults to NTSC for homebrew, and the caller can recompute from `timer`.
+const CPU_HZ_NTSC = 1789773;
+
+// Duty-cycle bit pattern → human label (pulse $4000/$4004 bits 6-7).
+const DUTY_LABEL = ["12.5%", "25%", "50%", "75% (25% inverted)"];
+
+// Length-counter load table is irrelevant to pitch, so we don't decode it.
+
+/**
+ * Convert a frequency in Hz to the nearest MIDI note name (e.g. "A4"),
+ * or null for sub-audible / zero frequencies. A4 = 440 Hz = MIDI 69.
+ * @param {number} hz
+ * @returns {{ midi: number, name: string, cents: number } | null}
+ */
+export function hzToMidi(hz) {
+  if (!hz || hz < 16) return null; // below ~C0; treat as silent/inaudible
+  const NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+  const midiFloat = 69 + 12 * Math.log2(hz / 440);
+  const midi = Math.round(midiFloat);
+  const cents = Math.round((midiFloat - midi) * 100);
+  const name = NAMES[((midi % 12) + 12) % 12] + (Math.floor(midi / 12) - 1);
+  return { midi, name, cents };
+}
+
+/**
+ * Decode the NES APU register snapshot into per-channel musical state.
+ *
+ * @param {Uint8Array} regs the 24-byte `nes_apu_regs` region
+ * @returns {{
+ *   pulse1: PulseState, pulse2: PulseState, triangle: TriangleState,
+ *   noise: NoiseState, dmc: DmcState,
+ *   status: { pulse1: boolean, pulse2: boolean, triangle: boolean, noise: boolean, dmc: boolean },
+ *   frameCounter: { mode: 4 | 5, irqInhibit: boolean },
+ *   regsHex: string,
+ *   note: string,
+ * }}
+ *
+ * @typedef {{ enabled: boolean, duty: number, dutyLabel: string, volume: number,
+ *   constantVolume: boolean, lengthHalt: boolean, timer: number, freq: number|null,
+ *   midi: number|null, note: string|null, cents: number|null, playing: boolean }} PulseState
+ * @typedef {{ enabled: boolean, control: number, linearReload: number, lengthHalt: boolean,
+ *   timer: number, freq: number|null, midi: number|null, note: string|null, cents: number|null,
+ *   playing: boolean }} TriangleState
+ * @typedef {{ enabled: boolean, volume: number, constantVolume: boolean, lengthHalt: boolean,
+ *   period: number, mode: 'periodic'|'white', playing: boolean }} NoiseState
+ * @typedef {{ enabled: boolean, irqEnabled: boolean, loop: boolean, rateIndex: number,
+ *   directLoad: number, sampleAddress: number, sampleLength: number }} DmcState
+ */
+export function decodeNesApu(regs) {
+  // ── Pulse channels ($4000-$4003 and $4004-$4007) ──────────────────
+  const pulse = (base, statusBit) => {
+    const r0 = regs[base + 0];
+    const r2 = regs[base + 2];
+    const r3 = regs[base + 3];
+    const duty = (r0 >> 6) & 0x3;
+    const lengthHalt = !!(r0 & 0x20);     // also envelope-loop
+    const constantVolume = !!(r0 & 0x10);
+    const volume = r0 & 0x0F;             // volume (constant) or envelope period
+    const timer = ((r3 & 0x07) << 8) | r2; // 11-bit timer
+    // Below timer 8 the pulse is silenced by the hardware sweep unit.
+    const freq = timer >= 8 ? CPU_HZ_NTSC / (16 * (timer + 1)) : null;
+    const m = freq ? hzToMidi(freq) : null;
+    const enabled = !!(regs[0x15] & statusBit);
+    return {
+      enabled,
+      duty, dutyLabel: DUTY_LABEL[duty],
+      volume, constantVolume, lengthHalt,
+      timer,
+      freq: freq ? Math.round(freq * 100) / 100 : null,
+      midi: m?.midi ?? null,
+      note: m?.name ?? null,
+      cents: m?.cents ?? null,
+      // "playing" = channel enabled, audible timer, and non-zero output level
+      playing: enabled && freq != null && (constantVolume ? volume > 0 : true),
+    };
+  };
+
+  // ── Triangle ($4008-$400B) ────────────────────────────────────────
+  const t0 = regs[0x08], t2 = regs[0x0A], t3 = regs[0x0B];
+  const triLengthHalt = !!(t0 & 0x80);  // bit7 = length halt / linear control
+  const linearReload = t0 & 0x7F;
+  const triTimer = ((t3 & 0x07) << 8) | t2;
+  // Triangle is /32, and one octave below the same timer on a pulse.
+  const triFreq = triTimer >= 2 ? CPU_HZ_NTSC / (32 * (triTimer + 1)) : null;
+  const triM = triFreq ? hzToMidi(triFreq) : null;
+  const triEnabled = !!(regs[0x15] & 0x04);
+  const triangle = {
+    enabled: triEnabled,
+    control: t0 >> 7,
+    linearReload,
+    lengthHalt: triLengthHalt,
+    timer: triTimer,
+    freq: triFreq ? Math.round(triFreq * 100) / 100 : null,
+    midi: triM?.midi ?? null,
+    note: triM?.name ?? null,
+    cents: triM?.cents ?? null,
+    // Triangle has no volume control — it plays at full level whenever
+    // enabled with a non-zero linear+length counter and audible timer.
+    playing: triEnabled && triFreq != null && linearReload > 0,
+  };
+
+  // ── Noise ($400C-$400F) ───────────────────────────────────────────
+  const n0 = regs[0x0C], n2 = regs[0x0E];
+  const noiseEnabled = !!(regs[0x15] & 0x08);
+  const noise = {
+    enabled: noiseEnabled,
+    volume: n0 & 0x0F,
+    constantVolume: !!(n0 & 0x10),
+    lengthHalt: !!(n0 & 0x20),
+    period: n2 & 0x0F,                       // index into the period table
+    mode: (n2 & 0x80) ? 'periodic' : 'white', // bit7 = mode flag
+    playing: noiseEnabled && ((n0 & 0x10) ? (n0 & 0x0F) > 0 : true),
+  };
+
+  // ── DMC ($4010-$4013) ─────────────────────────────────────────────
+  const d0 = regs[0x10];
+  const dmc = {
+    enabled: !!(regs[0x15] & 0x10),
+    irqEnabled: !!(d0 & 0x80),
+    loop: !!(d0 & 0x40),
+    rateIndex: d0 & 0x0F,
+    directLoad: regs[0x11] & 0x7F,
+    sampleAddress: 0xC000 + regs[0x12] * 64,
+    sampleLength: regs[0x13] * 16 + 1,
+  };
+
+  const status = regs[0x15];
+  const frameMode = regs[0x17];
+
+  return {
+    pulse1: pulse(0x00, 0x01),
+    pulse2: pulse(0x04, 0x02),
+    triangle,
+    noise,
+    dmc,
+    status: {
+      pulse1: !!(status & 0x01),
+      pulse2: !!(status & 0x02),
+      triangle: !!(status & 0x04),
+      noise: !!(status & 0x08),
+      dmc: !!(status & 0x10),
+    },
+    frameCounter: {
+      mode: (frameMode & 0x80) ? 5 : 4,
+      irqInhibit: !!(frameMode & 0x40),
+    },
+    regsHex: Array.from(regs, (b) => b.toString(16).padStart(2, "0")).join(""),
+    note:
+      "Decoded from the APU register file ($4000-$4017) — i.e. the last values " +
+      "the CPU wrote, which is exactly the pitch/duty/volume layer you want for " +
+      "music transcription. freq/midi assume NTSC (CPU 1789773 Hz); recompute " +
+      "from `timer` for PAL. `playing` is a heuristic (enabled + audible timer + " +
+      "non-zero level); cross-check with recordAudio if a channel looks ambiguous.",
+  };
+}
+
+/**
+ * @param {import("./LibretroHost.js").LibretroHost} host
+ * @param {string} platform
+ * @returns {ReturnType<typeof decodeNesApu> | null}
+ */
+export function getNesApuState(host, platform) {
+  if (platform !== "nes") return null;
+  const regs = host.readMemory("nes_apu_regs", 0, 24);
+  return decodeNesApu(regs);
+}

package/src/host/pce-psg-state.js

@@ -0,0 +1,82 @@
+// PC Engine HuC6280 PSG decoder.
+//
+// Data source: the `pce_psg_regs` region (id 0x1A5) exposed by our patched
+// geargrafx core. Layout (packed little-endian, see the geargrafx region patch):
+//   [0]   channel_select   [1] main_amplitude
+//   [2-3] lfo_frequency     [4] lfo_control
+//   then 6 channels × 14 bytes:
+//     enabled(1) frequency(2) control(1) amplitude(1) vol_left(1) vol_right(1)
+//     wave_index(1) noise_control(1) noise_enabled(1) noise_freq(4)
+//
+// The HuC6280 PSG ("wonder-PSG") has 6 wavetable channels; channels 4 and 5 can
+// also produce noise (noise_enabled). Channel control bit 7 = channel on; the
+// low nibble is the 4-bit master volume; vol_left/vol_right are the panned
+// per-side volumes (4-bit each). Frequency is a 12-bit period.
+
+const GLOBAL_BYTES = 5;
+const CHAN_BYTES = 14;
+const NUM_CH = 6;
+
+/** PC Engine PSG base clock for the wavetable channels (~3.58 MHz / 32). */
+const PSG_CLOCK = 3579545;
+
+/**
+ * @param {Uint8Array} regs the `pce_psg_regs` region (89 bytes)
+ * @returns {{ chip:"pce", channelSelect:number, mainAmplitude:number,
+ *   lfoFrequency:number, lfoControl:number, channels:Array<object> }}
+ */
+export function decodePcePsg(regs) {
+  const u16 = (o) => regs[o] | (regs[o + 1] << 8);
+  const u32 = (o) => (regs[o] | (regs[o + 1] << 8) | (regs[o + 2] << 16) | (regs[o + 3] << 24)) >>> 0;
+
+  const channels = [];
+  for (let i = 0; i < NUM_CH; i++) {
+    const b = GLOBAL_BYTES + i * CHAN_BYTES;
+    const frequency = u16(b + 1);
+    const control = regs[b + 3];
+    const on = !!(control & 0x80);
+    // Wavetable channel frequency: f = clock / (32 * period). period 0 → silent.
+    const period = frequency & 0x0fff;
+    const hz = on && period ? Math.round(PSG_CLOCK / (32 * period)) : 0;
+    channels.push({
+      channel: i,
+      enabled: !!regs[b + 0],
+      on,
+      frequency: period,
+      approxHz: hz,
+      masterVolume: control & 0x1f,        // low 5 bits = channel master volume
+      amplitude: regs[b + 4],
+      volLeft: regs[b + 5] & 0x0f,
+      volRight: regs[b + 6] & 0x0f,
+      waveIndex: regs[b + 7],
+      noiseControl: regs[b + 8],
+      noiseEnabled: !!regs[b + 9],
+      noiseFreq: u32(b + 10),
+      // Channels 4 and 5 are the only ones with a noise generator on the HuC6280.
+      canNoise: i >= 4,
+    });
+  }
+
+  return {
+    chip: "pce",
+    channelSelect: regs[0],
+    mainAmplitude: regs[1],
+    mainVolumeLeft: (regs[1] >> 4) & 0x0f,
+    mainVolumeRight: regs[1] & 0x0f,
+    lfoFrequency: u16(2),
+    lfoControl: regs[4],
+    lfoEnabled: !!(regs[4] & 0x80),
+    channels,
+  };
+}
+
+/**
+ * Read + decode the PSG state from a running host.
+ * @param {import("./LibretroHost.js").LibretroHost} host
+ * @returns {ReturnType<typeof decodePcePsg> | null}
+ */
+export function getPcePsgState(host) {
+  const size = host.regionSize("pce_psg_regs");
+  if (!size) return null;
+  return decodePcePsg(host.readMemory("pce_psg_regs", 0, size));
+}

package/src/host/retroConstants.js

@@ -0,0 +1,72 @@
+// libretro.h constants we use. Subset — extended as we need more.
+
+export const RETRO_API_VERSION = 1;
+
+// Devices
+export const RETRO_DEVICE_NONE = 0;
+export const RETRO_DEVICE_JOYPAD = 1;
+export const RETRO_DEVICE_MOUSE = 2;
+export const RETRO_DEVICE_KEYBOARD = 3;
+
+// Joypad button IDs
+export const RETRO_DEVICE_ID_JOYPAD_B = 0;
+export const RETRO_DEVICE_ID_JOYPAD_Y = 1;
+export const RETRO_DEVICE_ID_JOYPAD_SELECT = 2;
+export const RETRO_DEVICE_ID_JOYPAD_START = 3;
+export const RETRO_DEVICE_ID_JOYPAD_UP = 4;
+export const RETRO_DEVICE_ID_JOYPAD_DOWN = 5;
+export const RETRO_DEVICE_ID_JOYPAD_LEFT = 6;
+export const RETRO_DEVICE_ID_JOYPAD_RIGHT = 7;
+export const RETRO_DEVICE_ID_JOYPAD_A = 8;
+export const RETRO_DEVICE_ID_JOYPAD_X = 9;
+export const RETRO_DEVICE_ID_JOYPAD_L = 10;
+export const RETRO_DEVICE_ID_JOYPAD_R = 11;
+export const RETRO_DEVICE_ID_JOYPAD_L2 = 12;
+export const RETRO_DEVICE_ID_JOYPAD_R2 = 13;
+export const RETRO_DEVICE_ID_JOYPAD_L3 = 14;
+export const RETRO_DEVICE_ID_JOYPAD_R3 = 15;
+export const RETRO_DEVICE_ID_JOYPAD_MASK = 256;
+
+// Memory regions
+export const RETRO_MEMORY_SAVE_RAM = 0;
+export const RETRO_MEMORY_RTC = 1;
+export const RETRO_MEMORY_SYSTEM_RAM = 2;
+export const RETRO_MEMORY_VIDEO_RAM = 3;
+
+// Pixel formats
+export const RETRO_PIXEL_FORMAT_0RGB1555 = 0;
+export const RETRO_PIXEL_FORMAT_XRGB8888 = 1;
+export const RETRO_PIXEL_FORMAT_RGB565 = 2;
+
+// Environment commands (subset; pass-through otherwise)
+export const RETRO_ENVIRONMENT_GET_OVERSCAN = 2;
+export const RETRO_ENVIRONMENT_GET_CAN_DUPE = 3;
+export const RETRO_ENVIRONMENT_SET_MESSAGE = 6;
+export const RETRO_ENVIRONMENT_SHUTDOWN = 7;
+export const RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL = 8;
+export const RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY = 9;
+export const RETRO_ENVIRONMENT_SET_PIXEL_FORMAT = 10;
+export const RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS = 11;
+export const RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK = 12;
+export const RETRO_ENVIRONMENT_GET_VARIABLE = 15;
+export const RETRO_ENVIRONMENT_SET_VARIABLES = 16;
+export const RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE = 17;
+export const RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME = 18;
+export const RETRO_ENVIRONMENT_GET_LIBRETRO_PATH = 19;
+export const RETRO_ENVIRONMENT_GET_LOG_INTERFACE = 27;
+export const RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY = 31;
+export const RETRO_ENVIRONMENT_SET_GEOMETRY = 37;
+export const RETRO_ENVIRONMENT_GET_LANGUAGE = 39;
+
+export const RETRO_ENVIRONMENT_EXPERIMENTAL = 0x10000;
+export const RETRO_ENVIRONMENT_PRIVATE = 0x20000;
+
+// Log levels (for log_cb that we expose via GET_LOG_INTERFACE)
+export const RETRO_LOG_DEBUG = 0;
+export const RETRO_LOG_INFO = 1;
+export const RETRO_LOG_WARN = 2;
+export const RETRO_LOG_ERROR = 3;
+
+// Sentinels
+/** Video refresh data pointer meaning "GL framebuffer is valid". */
+export const RETRO_HW_FRAME_BUFFER_VALID = -1 >>> 0; // unsigned -1