romdevtools 0.13.0

package/src/platforms/genesis/xgm2-pcm.js

@@ -0,0 +1,165 @@
+// Genesis XGM2 PCM encoder — turn an external WAV/PCM clip into the exact
+// sample format SGDK's XGM2 driver plays with XGM2_playPCM/XGM2_playPCMEx.
+//
+// The format rules (from SGDK include/snd/xgm2.h) are fiddly and only
+// discoverable by grepping the header — this tool bakes them in so an agent
+// doesn't botch sign/rate/alignment/padding:
+//   - 8-bit SIGNED mono PCM
+//   - 13.3 kHz native (XGM2 driver rate) — or 6.65 kHz for half-rate playback
+//   - length padded to a multiple of 256 bytes (with 0x00 = silence)
+//   - the sample buffer must be 256-byte ALIGNED in ROM (emit
+//     __attribute__((aligned(256))) on the array)
+//
+// Pure JS: a small WAV parser + linear resampler + signed-8 quantizer. No
+// ffmpeg / external codec needed.
+
+const XGM2_RATE = 13300;       // native XGM2 PCM playback rate (Hz)
+const XGM2_RATE_HALF = 6650;   // XGM2_playPCMEx halfRate=TRUE
+
+/**
+ * Parse a RIFF/WAVE buffer into float32 mono samples + its sample rate.
+ * Supports PCM 8/16/24/32-bit and IEEE float32; downmixes multi-channel to mono.
+ * @param {Uint8Array|Buffer} buf
+ * @returns {{ samples: Float32Array, sampleRate: number, channels: number, bits: number }}
+ */
+export function parseWav(buf) {
+  const u = Buffer.from(buf);
+  if (u.length < 44 || u.toString("ascii", 0, 4) !== "RIFF" || u.toString("ascii", 8, 12) !== "WAVE") {
+    throw new Error("not a RIFF/WAVE file (bad header). Pass a .wav, or use pcmBase64/pcmPath with raw s16le mono.");
+  }
+  let off = 12;
+  let fmt = null, dataOff = -1, dataLen = 0;
+  while (off + 8 <= u.length) {
+    const id = u.toString("ascii", off, off + 4);
+    const sz = u.readUInt32LE(off + 4);
+    const body = off + 8;
+    if (id === "fmt ") {
+      fmt = {
+        audioFormat: u.readUInt16LE(body),
+        channels: u.readUInt16LE(body + 2),
+        sampleRate: u.readUInt32LE(body + 4),
+        bits: u.readUInt16LE(body + 14),
+      };
+    } else if (id === "data") {
+      dataOff = body;
+      dataLen = Math.min(sz, u.length - body);
+    }
+    off = body + sz + (sz & 1); // chunks are word-aligned
+  }
+  if (!fmt) throw new Error("WAV missing 'fmt ' chunk");
+  if (dataOff < 0) throw new Error("WAV missing 'data' chunk");
+
+  const { channels, bits, sampleRate, audioFormat } = fmt;
+  const isFloat = audioFormat === 3;
+  const bytesPerSample = bits >> 3;
+  const frameBytes = bytesPerSample * channels;
+  const frames = Math.floor(dataLen / frameBytes);
+  const out = new Float32Array(frames);
+
+  for (let i = 0; i < frames; i++) {
+    let acc = 0;
+    for (let c = 0; c < channels; c++) {
+      const p = dataOff + i * frameBytes + c * bytesPerSample;
+      let v;
+      if (isFloat && bits === 32) v = u.readFloatLE(p);
+      else if (bits === 8) v = (u.readUInt8(p) - 128) / 128;        // WAV 8-bit is UNSIGNED
+      else if (bits === 16) v = u.readInt16LE(p) / 32768;
+      else if (bits === 24) { const x = u.readIntLE(p, 3); v = x / 8388608; }
+      else if (bits === 32) v = u.readInt32LE(p) / 2147483648;
+      else throw new Error(`unsupported WAV bit depth ${bits}`);
+      acc += v;
+    }
+    out[i] = acc / channels; // downmix to mono
+  }
+  return { samples: out, sampleRate, channels, bits };
+}
+
+/** Linear-resample float samples from srcRate to dstRate. */
+export function resampleLinear(samples, srcRate, dstRate) {
+  if (srcRate === dstRate) return samples;
+  const ratio = dstRate / srcRate;
+  const n = Math.max(1, Math.round(samples.length * ratio));
+  const out = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    const srcPos = i / ratio;
+    const i0 = Math.floor(srcPos);
+    const i1 = Math.min(i0 + 1, samples.length - 1);
+    const frac = srcPos - i0;
+    out[i] = samples[i0] * (1 - frac) + samples[i1] * frac;
+  }
+  return out;
+}
+
+/**
+ * Encode a WAV/PCM buffer into XGM2 PCM bytes (8-bit signed mono, target rate,
+ * length padded to a 256-byte multiple).
+ * @param {Uint8Array|Buffer} input
+ * @param {object} [opts]
+ * @param {boolean} [opts.halfRate] target 6.65 kHz instead of 13.3 kHz
+ * @param {'wav'|'pcm16'} [opts.format] input format (default 'wav'). 'pcm16' = raw s16le mono.
+ * @param {number} [opts.pcmRate] sample rate for raw pcm16 input (required for resample)
+ * @returns {{ pcm: Uint8Array, sampleCount: number, paddedBytes: number, rate: number, durationSeconds: number, sourceRate: number }}
+ */
+export function wavToXgm2Pcm(input, opts = {}) {
+  const targetRate = opts.halfRate ? XGM2_RATE_HALF : XGM2_RATE;
+  let floatSamples, sourceRate;
+  if (opts.format === "pcm16") {
+    const u = Buffer.from(input);
+    const n = u.length >> 1;
+    floatSamples = new Float32Array(n);
+    for (let i = 0; i < n; i++) floatSamples[i] = u.readInt16LE(i * 2) / 32768;
+    sourceRate = opts.pcmRate || 0;
+    if (!sourceRate) throw new Error("wavToXgm2Pcm: raw pcm16 input needs `pcmRate` (the source sample rate in Hz) to resample to the XGM2 rate.");
+  } else {
+    const parsed = parseWav(input);
+    floatSamples = parsed.samples;
+    sourceRate = parsed.sampleRate;
+  }
+
+  const resampled = resampleLinear(floatSamples, sourceRate, targetRate);
+
+  // Quantize to 8-bit SIGNED, clamped to [-128, 127].
+  const signed = new Int8Array(resampled.length);
+  for (let i = 0; i < resampled.length; i++) {
+    let v = Math.round(resampled[i] * 127);
+    if (v > 127) v = 127; else if (v < -128) v = -128;
+    signed[i] = v;
+  }
+
+  // Pad to a multiple of 256 bytes with 0x00 (silence in signed PCM).
+  const paddedLen = Math.ceil(signed.length / 256) * 256 || 256;
+  const pcm = new Uint8Array(paddedLen); // zero-filled
+  pcm.set(new Uint8Array(signed.buffer, signed.byteOffset, signed.length));
+
+  return {
+    pcm,
+    sampleCount: signed.length,
+    paddedBytes: paddedLen,
+    rate: targetRate,
+    sourceRate,
+    durationSeconds: signed.length / targetRate,
+  };
+}
+
+/**
+ * Emit a C source string declaring the sample as a 256-byte-aligned array plus
+ * a length #define, ready to #include and play with XGM2_playPCM/Ex.
+ * @param {Uint8Array} pcm
+ * @param {string} name C identifier (e.g. "sfx_jump")
+ * @param {number} rate target rate (for a comment)
+ * @returns {string}
+ */
+export function emitXgm2PcmC(pcm, name, rate) {
+  const lines = [];
+  lines.push(`// XGM2 PCM sample — 8-bit signed mono, ${rate} Hz, ${pcm.length} bytes (256-aligned).`);
+  lines.push(`// Play: XGM2_playPCM(${name}, ${name.toUpperCase()}_LEN, SOUND_PCM_CH1);`);
+  lines.push(`// (use XGM2_playPCMEx(..., TRUE, ...) if this was encoded at half-rate.)`);
+  lines.push(`#define ${name.toUpperCase()}_LEN ${pcm.length}`);
+  lines.push(`const u8 ${name}[${pcm.length}] __attribute__((aligned(256))) = {`);
+  for (let i = 0; i < pcm.length; i += 16) {
+    const row = Array.from(pcm.subarray(i, i + 16), (b) => "0x" + b.toString(16).padStart(2, "0")).join(", ");
+    lines.push("  " + row + ",");
+  }
+  lines.push("};");
+  return lines.join("\n") + "\n";
+}

package/src/platforms/gg/MENTAL_MODEL.md

@@ -0,0 +1,174 @@
+# Game Gear — mental model
+
+One page. Read once before you write your first GG game.
+
+## CPU + memory map
+
+```
+Z80A @ 3.58 MHz, 8 KB cartridge RAM (system RAM bigger via mapper).
+$0000-$3FFF  ROM bank 0 (fixed)
+$4000-$7FFF  ROM bank 1 (mapper-switchable via port $FE)
+$8000-$BFFF  ROM bank 2 (mapper-switchable via port $FF)
+$C000-$DFFF  Work RAM
+$E000-$FFFB  Work RAM mirror
+$FFFC-$FFFF  Mapper control registers
+```
+
+Most 32 KB scaffolds fit in banks 0+1 and never touch the mapper.
+
+## VDP (display)
+
+GG VDP = SMS VDP in Mode 4, smaller visible viewport.
+
+- **Framebuffer:** 256×192 (same as SMS)
+- **Visible:** 160×144 centered (48 px border each side, 24 px top/bottom)
+- **Modes:** only Mode 4 (256×192 tile + sprite) is useful — the other
+  TMS9918 modes are inherited but not used.
+- **Palette:** 32 entries × 12-bit BGR (4-4-4) — twice the depth of
+  SMS. Each CRAM entry is 2 little-endian bytes. BG entries 0-15,
+  sprite entries 16-31.
+- **Tile size:** 8×8, 4bpp planar. 448 tile slots × 32 bytes each.
+- **Sprites:** 64 SAT entries, 8×8 or 8×16 mode. **Hardware limit: at
+  most 8 sprites per scanline.** Extra sprites on the same row are
+  silently dropped by the VDP — symptom is "the first 8 letters of
+  my 14-letter title render, the rest are invisible." For text
+  overlays > 8 chars on the same row, split across multiple Y rows
+  OR draw the text via the BG name table (no per-line limit).
+
+**Always render gameplay content inside (48, 24)..(207, 167)** so it's
+visible on real hardware. The bundled scaffolds work without this
+because gpgx shows the full framebuffer.
+
+### Sprite coords are hardware-space, NOT visible-space
+
+The libretro core's screenshot returns only the 160×144 visible region,
+but the bytes you write to OAM are still in 256×192 hardware
+coordinates. An 8×8 sprite at OAM `(X=48, Y=24)` appears at the
+**top-left of the visible region** (which is the same hardware-coord
+`(48, 24)`). The visible region is OAM `x ∈ [48, 207]`, `y ∈ [24, 167]`.
+
+To center a sprite on screen: target OAM `(48 + 76, 24 + 68)` for
+roughly visible center, not `(80, 72)`.
+
+The `sprites({op:'inspect'})` tool's X/Y fields report hardware coords too —
+match them up with hardware-coord arithmetic, not visible-coord.
+
+### SAT $D0 terminator — still a hazard if you write $D0 yourself
+
+The SMS/GG renderer treats Y=$D0 in **any** OAM Y byte as a HARD
+terminator — it stops scanning further sprite slots the moment it
+hits one. Earlier rounds of the bundled `gg_sprite_init()` wrote
+$D0 to every Y byte to "hide" sprites at boot — that caused the
+classic "I populated slots 0..5 and slot 6 was still $D0 so the
+renderer halted at slot 5" footgun.
+
+**The runtime now initialises unused slots to $E0** (off-screen,
+below the 192-line area, but NOT the terminator). Slots you don't
+touch stay invisible AND don't kill the renderer. You only have
+to worry about $D0 if you write it explicitly — e.g. to stop
+sprite scanning early as an optimisation.
+
+If sprites past a certain slot are missing in `sprites({op:'inspect'})`,
+check the live OAM Y bytes for $D0 in a slot before them. That's
+still the diagnosis; the runtime just doesn't create the problem
+on its own anymore.
+
+### R6 sprite-tile-base default: $0000, NOT $2000
+
+`gg_vdp_init()` sets R6 = 0xFB. R6 bit 2 is the SA13 select for
+sprite tile data — and bit 2 is **CLEAR** in 0xFB. That means
+sprite tiles read from `$0000-$1FFF`, **sharing the bank with BG
+tiles**. Many references (including the older comments we just
+fixed in `vdp_init.c` and `load_tiles.c`) say "R6=0xFB → sprite
+tiles at $2000" — that's wrong.
+
+If you want sprite tiles in their own bank at $2000, set
+`vdp_write_reg(6, 0xFF)` AND upload tiles to VRAM $2000. Otherwise
+upload sprite tiles to $0000 alongside BG tiles (just make sure
+they don't collide).
+
+The `sprites({op:'inspect'})` tool's `spriteTileDataBase` field reports the
+address the VDP is actually reading from — trust that over any
+comment.
+
+## I/O port map
+
+```
+$06   PSG stereo control (write — L/R routing per channel)
+$3E   memory control (mostly leave alone)
+$3F   I/O control (mostly leave alone)
+$7E   read = V-counter; write = ignored
+$7F   read = H-counter; write = PSG (4-channel SN76489)
+$BE   VDP data
+$BF   VDP control (address + register write)
+$DC   joypad A — D-pad + B1 + B2 (active low)
+$DD   joypad B — extra (mostly unused on GG)
+$00   GG-specific: bit 7 = START button (active low)
+$01-$05  GG-specific: link cable, sound balance, etc.
+```
+
+### Driving input over MCP — the button map is INVERTED ⚠
+
+Game Gear runs on genesis_plus_gx, which maps the two face buttons onto libretro
+the *opposite* of the obvious way (verified live against the core — same as SMS):
+
+| Physical button | `input({op:'set', …})`  | spatial / native |
+|-----------------|-------------------|------------------|
+| Button 1 (main fire) | `{ b: true }` | `{ west: true }` · `input({op:'press', button:'1'})` |
+| Button 2             | `{ a: true }` | `{ east: true }` · `input({op:'press', button:'2'})` |
+| START               | `{ start: true }` | — |
+
+**The trap:** `input({op:'set', a: true})` presses **button 2**, not button 1. For the
+main fire use `{ b: true }` / `{ west: true }`. Prefer spatial names or
+`input({op:'press', button:'1'|'2'})` over raw a/b. `input({op:'layout', platform:'gg'})`
+has the exact map.
+
+## Audio
+
+SN76489 PSG — same chip as SMS + Genesis. 4 channels: 3 squares + 1 noise.
+
+Write-only via port `$7F`. See `gg_sfx.h`/`gg_sfx.c` for the canonical
+wrapper (sfx_init / sfx_tone / sfx_noise / sfx_update / sfx_off — same
+function shape as nes_runtime / gb_runtime / gba_sfx / genesis_sfx /
+sms_sfx).
+
+Optional: GG-only stereo register at port `$06` (bits 0-3 = which
+channels route to the right speaker, bits 4-7 = same for left).
+Defaults to mono — write `0xFF` for "all channels to both speakers"
+explicitly.
+
+**Debugging sound:** `audioDebug({op:'inspect', chip:"psg"})` decodes the live SN76489 —
+3 tone + 1 noise channel state (the same gpgx PSG region serves GG/SMS/Genesis).
+
+## Frame heartbeat
+
+```c
+#include "gg_hw.h"
+#include "gg_sfx.h"
+
+void main(void) {
+    gg_vdp_init();
+    sfx_init();
+    gg_vdp_display_on();
+
+    while (1) {
+        gg_vblank_wait();
+        sfx_update();
+        /* update game state, stage SAT, etc. */
+    }
+}
+```
+
+## Differences from SMS — quick reference
+
+- Visible 160×144 vs 256×192 — center content
+- 12-bit CRAM vs 6-bit — palettes are 64 bytes vs 32
+- One controller only (no port 2)
+- START button at port $00 bit 7 (not on PORT_JOY_A)
+- Optional PSG stereo register at port $06
+- ROM header magic is identical to SMS ("TMR SEGA" at $7FF0)
+
+Everything else (Z80, VDP control protocol, tile format, sprite SAT
+layout, joypad polling, BG name table at $3800) is identical to SMS.
+You can use sms_hw.h notes + helpers as a reference; the GG runtime
+files in lib/c/ are direct ports.

package/src/platforms/gg/TROUBLESHOOTING.md

@@ -0,0 +1,105 @@
+# Game Gear — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first
+(`platform({op:'doc', platform:"gg", name:"mental_model"})`).
+
+## "ROM runs but content is off the screen"
+
+GG's visible viewport is **160×144 centered in a 256×192 framebuffer**.
+Anything you draw outside `(48, 24)..(207, 167)` is in the border —
+visible in headless emulator screenshots (gpgx shows the whole frame)
+but invisible on real hardware.
+
+The bundled scaffolds are direct ports of the SMS scaffolds and target
+the full 256×192 area. Works fine for development under gpgx; for
+shipping to a real GG, reposition sprite + tilemap content to the
+visible center.
+
+## "START button doesn't work"
+
+GG splits the START button onto a GG-specific port (`$00` bit 7,
+active low), separate from the D-pad/A/B which are on `$DC` like
+SMS. `gg_joypad_read()` already merges them — START shows up in bit 7
+of the returned byte (`JOY_START` mask).
+
+If you copied an SMS scaffold that uses PAUSE-as-START semantics
+(SMS pause button is at port $DD bit 4 IIRC), it won't work on GG;
+swap to JOY_START.
+
+## "I drive the game with setInput but the fire/action button doesn't fire"
+
+The GG button map is **inverted** vs the libretro names (same genesis_plus_gx
+core as SMS). Button 1 (main fire) is libretro **b**, button 2 is libretro **a**
+— so `input({op:'set', a:true})` presses button **2**, not button 1 (`JOY_B1`).
+
+Fix:
+- Button 1 (`JOY_B1`) → `input({op:'set', ports:[{b:true}]})` or `{west:true}`
+- Button 2 (`JOY_B2`) → `{a:true}` / `{east:true}`
+- START → `{start:true}`
+
+Prefer spatial names or `input({op:'press', button:'1'|'2'})`.
+`input({op:'layout', platform:'gg'})` has the full map.
+
+## "Sound only comes out of one speaker"
+
+GG has a stereo control register at port `$06` that the SMS doesn't
+have. After power-on it defaults to a sensible state on real hardware
+but on some emulators / on real cartridge dev kits the L/R bits
+might be cleared. Force mono explicitly:
+
+```c
+__sfr __at 0x06 PORT_GG_PSG_STEREO;  /* already in gg_hw.h */
+PORT_GG_PSG_STEREO = 0xFF;  /* all 4 channels to both speakers */
+```
+
+(0xFF = bits 0-3 enable channels 0-3 on the right speaker, bits 4-7
+enable on the left.)
+
+## "Palette looks wrong — colors too saturated/wrong shade"
+
+GG palette is **4-4-4 BGR** (12 bits per entry) — twice as deep as
+SMS's 2-2-2. If you ported SMS palette bytes directly, you're feeding
+6-bit values into a 12-bit register and getting the wrong shade.
+
+Convert SMS palette bytes → GG palette bytes by reading the 2-2-2
+fields out of each SMS byte and shifting them to 4-4-4 nibbles:
+
+```c
+uint16_t sms_to_gg(uint8_t sms_byte) {
+    uint8_t r = (sms_byte) & 0x03;        /* 2 bits */
+    uint8_t g = (sms_byte >> 2) & 0x03;
+    uint8_t b = (sms_byte >> 4) & 0x03;
+    /* Scale 0..3 -> 0..F by *5 (close enough for 4-bit). */
+    return (uint16_t)((r * 5) | ((g * 5) << 4) | ((b * 5) << 8));
+}
+```
+
+Then store as `low = (gg & 0xFF)`, `high = (gg >> 8) & 0xFF` for the
+two-byte little-endian CRAM entry.
+
+## "Linking error: undefined reference to sms_joypad_read_p2"
+
+GG only has one controller. The SMS scaffolds use `sms_joypad_read_p2`
+for the two-controller patterns (Pong, 2P shmup). When porting, drop
+the P2 read + force `p2 = 0` so the AI fallback always engages.
+
+The bundled GG `sports.c` already does this — copy that pattern when
+porting other SMS multiplayer code.
+
+## "Build errors mention 'TMR SEGA' or ROM header"
+
+Same magic as SMS — gpgx accepts headerless ROMs fine for development.
+For real-hardware ROM-burning include a header at $7FF0:
+
+```
+db "TMR SEGA"
+dw 0                  ; reserved
+dw 0                  ; checksum (gpgx ignores)
+db 0x00, 0x00, 0x00   ; product code BCD
+db 0x00               ; product code high + version
+db 0x40               ; region (0x40 = GG)
+db 0x4C               ; ROM size (0x4C = 32 KB)
+```
+
+The bundled scaffolds build without a header — sufficient for the
+emulator-driven workflow. Add one before shipping to a cartridge.

package/src/platforms/gg/UPSTREAM_SOURCES.md

@@ -0,0 +1,36 @@
+# Game Gear — source you can read
+
+GG shares its toolchain (SDCC z80) + emulator (genesis_plus_gx) +
+most of the runtime with SMS (`sms_crt0.s` ≡ `gg_crt0.s` byte-for-
+byte; PSG protocol identical). The GG tree at `src/platforms/gg/`
+holds the GG-specific scaffolds and runtime helpers; SMS docs apply
+for everything else.
+
+GG-specific:
+- Visible viewport 160×144 inside 256×192 framebuffer — content
+  must be centered
+- CRAM is 12-bit BGR (vs SMS's 6-bit) — 64 bytes vs 32
+- START button at port $00 bit 7 (not on PORT_JOY_A)
+- Optional stereo via PSG stereo register at port $06
+- One controller only — no port 2 fallback patterns
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/gg/templates/*.c`).
+2. **Bundled runtime** — `src/platforms/gg/lib/c/*` — VDP, joypad,
+   sprite_table, sfx, music. All small + readable.
+3. **SDCC z80 port** — WASM compiler shipped, source not bundled.
+4. **Upstream**:
+
+   | What | Upstream |
+   |---|---|
+   | SDCC | http://sdcc.sourceforge.net/ |
+   | genesis_plus_gx libretro | https://github.com/libretro/Genesis-Plus-GX |
+
+## GG-specific docs
+
+- **SMS Power!** covers GG too: https://www.smspower.org/Development/Documents
+  (most pages have GG addendum or work identically)
+- **GG-specific extensions** (CRAM depth, START): SMS Power's GG section
+
+For everything else, see `../sms/UPSTREAM_SOURCES.md`.

package/src/platforms/gg/lib/c/gg_crt0.s

@@ -0,0 +1,112 @@
+;; Game Gear crt0 for SDCC. Byte-identical to sms_crt0.s — GG uses the
+;; same Z80 boot model as SMS: same vector table at $0000, same IRQ
+;; mode 1 vector at $0038, same NMI at $0066 (the GG's pause-equivalent
+;; is the START button on port $00, NOT NMI — but NMI is still vectored
+;; for safety).
+;;
+;; Why this exists separately from sms_crt0.s: every project under
+;; createProject({platform:"gg"}) should be self-contained. Cross-
+;; platform-by-construction: a `.gg` ROM rebuilds without romdev
+;; running. Don't read from sms/lib at build time.
+;;
+;; Replaces SDCC's stock z80 crt0 (which assumes a host runtime that
+;; handles I/O via rst $08 — not what a GG cartridge needs). This one
+;; boots cleanly into a real cartridge: vector table at $0000, sets
+;; SP to $DFF0, calls main().
+;;
+;; Use via:
+;;   build({output:'rom'})({
+;;     platform: "gg",
+;;     sources: {
+;;       "main.c": ...,
+;;       "gg_crt0.s": ...this file...,
+;;     },
+;;     crt0: ".module empty\n",  // <-- empty stock crt0
+;;   })
+;;
+;; OR pass the contents of this file as `crt0` to runSdld.
+
+        .module gg_crt0
+        .globl  _main
+        .globl  l__INITIALIZER
+        .globl  s__INITIALIZER
+        .globl  s__INITIALIZED
+
+;; ─── Reset vector at $0000 ────────────────────────────────────────
+        .area _HEADER (ABS)
+        .org    0x0000
+        di                          ; interrupts off until we're ready
+        im      1                   ; mode 1 — IRQs jump to $0038
+        ld      sp, #0xDFF0         ; GG/SMS stack (top of WRAM minus 16)
+        jp      gsinit              ; skip the interrupt vector table
+
+;; ─── RST handlers (default = return) ──────────────────────────────
+        .org    0x0008
+        ret
+        .ds     0x08 - 1
+        .org    0x0010
+        ret
+        .ds     0x08 - 1
+        .org    0x0018
+        ret
+        .ds     0x08 - 1
+        .org    0x0020
+        ret
+        .ds     0x08 - 1
+        .org    0x0028
+        ret
+        .ds     0x08 - 1
+        .org    0x0030
+        ret
+        .ds     0x08 - 1
+
+;; ─── IRQ vector at $0038 (IM 1) ───────────────────────────────────
+;; GG hits this on vblank IF VDP R1 bit 5 is set. Default = clear the
+;; VDP status flag and return. User code that wants a real ISR can
+;; install one by writing to (vdp_isr_ptr) and a `ld hl,(vdp_isr_ptr) /
+;; jp (hl)` shim — but for now a bare ei/reti keeps things simple.
+        .org    0x0038
+        push    af
+        in      a, (#0xBF)          ; read VDP status — clears IRQ flag
+        pop     af
+        ei
+        reti
+
+;; ─── NMI vector at $0066 ──────────────────────────────────────────
+;; GG has no Pause button — START is read from port $00 bit 7 instead.
+;; NMI is vectored for safety (some homebrew loaders trigger it).
+        .org    0x0066
+        retn
+
+;; ─── crt0 body ────────────────────────────────────────────────────
+;; Standard SDCC pattern: jump to a code area, run initializers, then
+;; call main. The initializer area is filled by sdcc when it sees
+;; global initializations.
+
+        .area   _HOME
+        .area   _CODE
+        .area   _GSINIT
+        .area   _GSFINAL
+
+        .area   _DATA
+        .area   _INITIALIZED
+        .area   _BSEG
+        .area   _BSS
+        .area   _HEAP
+
+        .area   _CODE
+
+gsinit:
+        ld      bc, #l__INITIALIZER
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_done
+        ld      de, #s__INITIALIZED
+        ld      hl, #s__INITIALIZER
+        ldir
+
+gsinit_done:
+        call    _main
+hang:
+        halt
+        jr      hang

package/src/platforms/gg/lib/c/gg_hw.h

@@ -0,0 +1,62 @@
+/* Game Gear hardware register declarations for SDCC.
+ *
+ * GG = "SMS in a handheld" — same Z80, same VDP (Mode 4), same SN76489 PSG,
+ * same I/O port layout for SMS-compatible reads. Key differences:
+ *
+ *   1. Visible viewport is 160×144 (vs SMS 256×192). The framebuffer is
+ *      still 256×192 internally; only the centered 160×144 region shows.
+ *      Borders fill the rest. Always render game content centered.
+ *
+ *   2. Input is at port $DC (same as SMS) PLUS port $00 (GG-specific
+ *      START button). When porting an SMS game, START on GG requires a
+ *      separate read.
+ *
+ *   3. PSG has a stereo control register at port $06 (write-only). Each
+ *      of the 4 PSG channels can be routed to L, R, or both. Defaults
+ *      to mono (both speakers, all channels). We don't touch it; if you
+ *      want stereo, write to PORT_GG_PSG_STEREO directly.
+ *
+ *   4. ROM header is at the same $7FF0-$7FFF region but the "TMR SEGA"
+ *      magic is identical; gpgx accepts headerless ROMs fine.
+ *
+ * SDCC __sfr declares Z80 I/O ports: reading the variable compiles to
+ * `in a, (port)`, writing to `out (port), a`. So port I/O is plain C
+ * assignment.
+ */
+#ifndef GG_HW_H
+#define GG_HW_H
+
+#include <stdint.h>
+
+/* ─── VDP (SMS-compatible) ──────────────────────────────────────── */
+__sfr __at 0xBE PORT_VDP_DATA;
+__sfr __at 0xBF PORT_VDP_CTRL;
+
+/* ─── PSG / counters (SMS-compatible) ───────────────────────────── */
+__sfr __at 0x7E PORT_V_COUNTER;
+__sfr __at 0x7F PORT_H_COUNTER;     /* write = PSG */
+
+/* ─── SMS-style controller ports (D-pad + 1/2) ──────────────────── */
+__sfr __at 0xDC PORT_JOY_A;
+__sfr __at 0xDD PORT_JOY_B;
+
+/* ─── GG-specific extras ───────────────────────────────────────── */
+__sfr __at 0x00 PORT_GG_INPUT;       /* bit 7 = START (active low) */
+__sfr __at 0x06 PORT_GG_PSG_STEREO;  /* PSG L/R routing, write-only */
+
+/* ─── Joypad bits (active low — invert after read) ─────────────── */
+#define JOY_UP    0x01
+#define JOY_DOWN  0x02
+#define JOY_LEFT  0x04
+#define JOY_RIGHT 0x08
+#define JOY_B1    0x10
+#define JOY_B2    0x20
+#define JOY_START 0x80  /* on GG_INPUT bit 7, NOT on JOY_A */
+
+/* ─── VDP address-set prefixes ──────────────────────────────────── */
+#define VDP_VRAM_WRITE 0x40
+#define VDP_VRAM_READ  0x00
+#define VDP_REG_WRITE  0x80
+#define VDP_CRAM_WRITE 0xC0
+
+#endif