romdevtools 0.13.0

package/src/platforms/pce/vdc.js

@@ -0,0 +1,52 @@
+// PC Engine HuC6270 VDC sprite-attribute-table (SATB) decoder.
+//
+// The SATB is a 64-sprite table (romdev region `pce_vdc_satb`, 256 u16 words =
+// 4 words per sprite), mirrored from VRAM by the VDC's SATB-DMA. Per sprite:
+//   word0 = Y position + 64        (Y on screen = (w0 & 0x3FF) - 64)
+//   word1 = X position + 32        (X on screen = (w1 & 0x3FF) - 32)
+//   word2 = pattern code           (pattern = (w2 >> 1) & 0x3FF; in 16×16 cells)
+//   word3 = flags: palette (bits 0-3), priority (bit 7), CGX width (bit 8),
+//           CGY height (bits 12-13), X-flip (bit 11), Y-flip (bit 15)
+// Sprites are 16 or 32 wide (CGX) × 16/32/64 tall (CGY). Source: geargrafx
+// huc6270.cpp:803-834 (the actual renderer) is canonical.
+
+const SPRITE_WIDTH = [16, 32];          // CGX 0/1
+const SPRITE_HEIGHT = [16, 32, 64, 64]; // CGY 0..3
+
+/**
+ * Decode the 64-entry SATB into the generic sprite shape.
+ * @param {Uint8Array} satb 512 bytes = 256 u16 words (LE)
+ * @returns {Array<{slot:number, x:number, y:number, tile:number, palette:number, priority:number, flipH:boolean, flipV:boolean, size:{w:number,h:number}, visible:boolean, raw:object}>}
+ */
+export function decodeSatb(satb) {
+  const u16 = (i) => satb[i * 2] | (satb[i * 2 + 1] << 8);
+  const sprites = [];
+  for (let i = 0; i < 64; i++) {
+    const base = i * 4;
+    const w0 = u16(base + 0);
+    const w1 = u16(base + 1);
+    const w2 = u16(base + 2);
+    const flags = u16(base + 3);
+    const y = (w0 & 0x3ff) - 64;
+    const x = (w1 & 0x3ff) - 32;
+    const cgx = (flags >> 8) & 0x01;
+    const cgy = (flags >> 12) & 0x03;
+    const w = SPRITE_WIDTH[cgx];
+    const h = SPRITE_HEIGHT[cgy];
+    // On-screen if any part overlaps the 256×... visible window (rough cull).
+    const visible = (x + w > 0) && (x < 512) && (y + h > 0) && (y < 256);
+    sprites.push({
+      slot: i,
+      x, y,
+      tile: (w2 >> 1) & 0x3ff,
+      palette: flags & 0x0f,
+      priority: (flags >> 7) & 0x01,
+      flipH: !!(flags & 0x0800),
+      flipV: !!(flags & 0x8000),
+      size: { w, h },
+      visible,
+      raw: { word0: w0, word1: w1, word2: w2, flags },
+    });
+  }
+  return sprites;
+}

package/src/platforms/sms/MENTAL_MODEL.md

@@ -0,0 +1,286 @@
+# Sega Master System / Game Gear — mental model
+
+One page. Read once before you write your first SMS / GG game. The
+TROUBLESHOOTING.md alongside this file is for when something's broken;
+this is the "what's going on" version.
+
+## CPU memory map (Z80, 16-bit address space)
+
+```
+$0000-$BFFF   ROM (typical 48 KB; mapper extends to 4 MB)
+$C000-$DFFF   work RAM (8 KB, mirrored to $E000-$FFFF)
+$DFF0+        stack (grows down) — sms_crt0 sets SP here
+$FFFC-$FFFF   mapper registers (Sega mapper, page select per slot)
+```
+
+Cartridge is paged in 16 KB slots ($0000, $4000, $8000) via the Sega
+mapper at $FFFC-$FFFF. Slot 0 (`$0000-$3FFF`) holds the boot ROM /
+fixed bank with the interrupt vectors and the first chunk of code;
+slots 1 and 2 are bank-switched on demand. Our minimal templates
+fit in 32 KB so we never page.
+
+The Z80 has separate **I/O port** address space (`in`/`out`
+instructions). Game logic talks to the VDP and joypads via ports,
+NOT via memory-mapped registers.
+
+## I/O ports
+
+```
+$3E   memory control (cartridge slot + RAM enable)
+$3F   I/O control (joypad direction polarity)
+$7E   V-counter (read)        / PSG (write — sound)
+$7F   H-counter (read)
+$BE   VDP data port
+$BF   VDP control port
+$DC   P1 joypad + P2 dpad
+$DD   P2 buttons + reset / cart-detect
+```
+
+In C with SDCC's `__sfr __at` declarations:
+
+```c
+__sfr __at 0xBE PORT_VDP_DATA;
+__sfr __at 0xBF PORT_VDP_CTRL;
+__sfr __at 0xDC PORT_JOY_A;
+```
+
+Reading the variable compiles to `in a,(port)`, writing to
+`out (port),a`. See `src/platforms/sms/lib/c/sms_hw.h` for the full
+set.
+
+## VDP (Video Display Processor)
+
+The SMS VDP is a derivative of the TMS9918, with mode-4 (the SMS
+graphics mode) doing most of the lifting. It has its own VRAM
+(16 KB) and CRAM (32 bytes — palette).
+
+```
+VRAM   16 KB    tile patterns + name table + sprite attr table + sprite tile data
+CRAM   32 B     32 palette entries × 1 byte (2-2-2 BGR)
+```
+
+VRAM is reached through port $BE (data) + port $BF (control). To set
+the destination address X for a write:
+
+```c
+PORT_VDP_CTRL = X & 0xFF;             /* low byte */
+PORT_VDP_CTRL = ((X >> 8) & 0x3F) | 0x40;  /* high byte + WRITE prefix */
+```
+
+Then subsequent writes to PORT_VDP_DATA push bytes sequentially.
+
+The 11 VDP registers ($00-$0A) control the display. Idiomatic
+baseline (set by `sms_vdp_init()`):
+
+```
+R0 = 0x36   Mode 4 + line-IRQ
+R1 = 0x80   display OFF, vblank IRQ off, 192-line
+R2 = 0xFF   name table at $3800
+R4 = 0xFF   BG tile data at $0000
+R5 = 0xFF   sprite attr table at $3F00
+R6 = 0xFB   sprite tile data at $0000 (NOT $2000 — see footgun below)
+R7 = 0x00   border colour
+```
+
+Then later: `R1 = 0xE0` to enable display + vblank IRQ.
+
+## Tiles + name table
+
+Tiles are 8×8 pixels, **4 bits per pixel** in **bitplane-interleaved
+format**: 32 bytes per tile, 4 bytes per row (one byte per plane).
+512 tiles max in VRAM (256 BG + 256 sprite, by default config).
+
+The BG name table at $3800 is 32 cols × 28 rows × 2 bytes/entry.
+Each entry packs:
+
+```
+byte 0: low 8 bits of tile index
+byte 1: 0 0 0 priority palette vflip hflip tile_idx_bit9
+```
+
+Where `palette = 0` → BG palette ($00-$0F in CRAM), `palette = 1` →
+sprite palette ($10-$1F).
+
+## Sprites (sprite attribute table)
+
+SAT at VRAM $3F00. 64 sprite slots × 4 bytes:
+
+```
+$3F00-$3F3F:  64 Y bytes — Y = 0xD0 hides all subsequent sprites
+$3F80-$3FFF:  64 (X, tile) pairs interleaved
+```
+
+So Y bytes and X/tile pairs are split into TWO regions of the SAT.
+`src/platforms/sms/lib/c/sprite_table.c` keeps a 256-byte shadow
+buffer in WRAM and uploads it to the SAT each vblank.
+
+### Two footguns the bundled scaffolds keep hitting
+
+1. **8 sprites per scanline limit.** The VDP draws up to 8 sprites per
+   scanline; the 9th+ are silently dropped. If you draw a "CATCH THE
+   COIN" text using 14 sprite tiles on the same Y row, **only the
+   first 8 letters appear** and the rest vanish with no warning. Fix:
+   split text across multiple Y rows OR draw it via the BG name
+   table (which has no per-line limit).
+
+2. **SAT $D0 terminator.** The VDP treats Y=$D0 in any OAM Y byte as
+   a HARD terminator — it stops scanning further slots immediately.
+   Earlier rounds of `sms_sprite_init()` wrote $D0 to every Y byte
+   to "hide" sprites at boot, which 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. as an
+   early-out 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.
+
+`sprites({op:'inspect'})` shows the live OAM bytes + reports
+`spriteTileDataBase` — trust it over comments when sprites misbehave.
+
+### R6 sprite-tile-base default: $0000, NOT $2000
+
+`sms_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 older comments in our own
+`vdp_init.c` and `load_tiles.c`, since fixed) 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).
+
+## Palette (CRAM)
+
+32 entries × 1 byte = 32 bytes. 2-2-2 BGR encoding:
+
+```
+bit 0-1: red          0..3
+bit 2-3: green        0..3
+bit 4-5: blue         0..3
+```
+
+Brightest white = `0x3F`. Entry $00 is the BG backdrop; $10 is the
+sprite-palette colour 0 (transparent).
+
+**Game Gear** uses 4-4-4 BGR (2 bytes per entry, 64 total bytes).
+The runtime has both `sms_load_palette` (32 bytes) and
+`gg_load_palette` (64 bytes).
+
+## Frame heartbeat
+
+```c
+sms_vblank_wait();          /* poll VDP status byte bit 7 until set */
+sms_sat_upload();           /* push shadow SAT to VRAM $3F00 */
+/* update game state */
+```
+
+The vblank poll is the heartbeat. There's also a vblank IRQ if you
+need cycle-accurate timing, but for most games polling is fine.
+
+## Input
+
+`sms_joypad_read()` returns a packed byte with the buttons inverted
+(active high — pressed = 1). Bits:
+
+```
+JOY_UP    0x01
+JOY_DOWN  0x02
+JOY_LEFT  0x04
+JOY_RIGHT 0x08
+JOY_B1    0x10
+JOY_B2    0x20
+```
+
+Edge-detect by AND'ing `pad & !prev`.
+
+### Driving input over MCP — the SMS button map is INVERTED ⚠
+
+genesis_plus_gx (the SMS core) maps the two face buttons onto libretro the
+*opposite* way you'd guess (verified live against the core):
+
+| Physical button | `input({op:'set', …})`  | spatial / native |
+|-----------------|-------------------|------------------|
+| Button 1 (TL, main fire) | `{ b: true }` | `{ west: true }` · `input({op:'press', button:'1'})` |
+| Button 2 (TR)            | `{ a: true }` | `{ east: true }` · `input({op:'press', button:'2'})` |
+
+**The trap:** `input({op:'set', a: true})` presses **button 2**, not button 1. For
+the main fire (button 1 / `JOY_B1`) use `{ b: true }` or the spatial
+`{ west: true }`. The **spatial names** and `input({op:'press', button:'1'|'2'})`
+resolve correctly — prefer them over raw a/b. `input({op:'layout', platform:'sms'})`
+has the exact map. (Same genesis_plus_gx inversion as Genesis + Game Gear.)
+
+## Sound
+
+PSG (SN76489) on port $7F. 4 channels: 3 square waves + 1 noise.
+Writes are byte-wise; the high bit selects "latch register" vs
+"continue previous register".
+
+A full driver is beyond the scope of these scaffolds. For
+playable SFX, manually pulse $7F with the latch-register byte
+followed by data bytes. Real games ship a music driver in WRAM.
+
+**Debugging sound:** `audioDebug({op:'inspect', chip:"psg"})` decodes the live SN76489 —
+3 tone + 1 noise channel state (the same gpgx PSG region serves SMS/GG/Genesis).
+
+## Cartridge layout
+
+```
+$0000-$0037   reset + interrupt vectors (RST jumps)
+$0038         interrupt handler entry (IM 1 mode)
+$0066         NMI entry (pause button on SMS)
+$7FF0-$7FFF   ROM header — "TMR SEGA" trademark + checksum + region/size
+```
+
+Our minimal templates don't bother with the header (real consoles
+boot ROMs even without it; an emulator-side compatibility test
+might flag them). `sms_crt0.s` provides the RST table + the IM 1
+setup that lets vblank IRQs fire.
+
+## Build pipeline
+
+When you call `build({output:'rom', platform:"sms", language:"c"})`:
+
+1. SDCC (z80 port) compiles each `.c` → `.rel` object.
+2. `sms_crt0.s` is auto-injected as the startup file (assembled to
+   `.rel`).
+3. `sdld` links all `.rel` + the z80 standard library → `.ihx`
+   Intel HEX.
+4. The IHX is converted to a flat 32 KB `.sms` ROM.
+
+Loadable via genesis_plus_gx (`loadMedia`).
+
+## Game Gear differences
+
+- Smaller screen: 160×144 visible (vs SMS 256×192). VDP is the
+  same; cropping happens in hardware.
+- 12-bit CRAM (4 bits per channel). Use `gg_load_palette` (64 bytes
+  per palette).
+- Start button on port $00 (separate from the SMS pause-via-NMI).
+- ROM size cap is higher: GG games can go up to 1 MB.
+- Game Gear-specific buttons add port $00 read (Start) and stereo
+  PSG control on port $06.
+
+## Horizontal scrolling (for side-scrollers)
+
+The `platformer` scaffold is single-screen. To make it a side-scroller:
+
+- **Hardware scroll:** write VDP register 8 (horizontal scroll) each frame =
+  `-camX & 0xFF` (the reg scrolls the screen; the name table is 32×28 and
+  wraps). This gives smooth scrolling through one name-table's worth.
+- **Streaming:** for a world wider than 256 px, rewrite the name-table column
+  about to enter view each time `camX` crosses an 8-px boundary — write the
+  next world column's tile entries into the off-screen column. Do VDP writes
+  during vblank.
+- **Fixed HUD / status bar:** VDP register 0 bit 6 ("horizontal scroll lock")
+  freezes the top two rows of the screen regardless of the scroll register —
+  use it for a fixed HUD band while the rest scrolls.
+
+Track `camX` in pixels; actor screen-X = `worldX - camX`. (Game Gear is the
+same VDP — only the visible window differs.)

package/src/platforms/sms/TROUBLESHOOTING.md

@@ -0,0 +1,140 @@
+# Sega Master System / Game Gear — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first for the
+"what's going on" version (via `platform({op:'doc', platform:"sms", name:"mental_model"})`).
+
+## "I drive the game with setInput but the fire/action button doesn't fire"
+
+The SMS/GG button map is **inverted** vs the libretro names. genesis_plus_gx
+maps button 1 (TL, the main fire) onto libretro **b** and button 2 (TR) onto
+libretro **a** — so `input({op:'set', a:true})` presses button **2**, not button 1
+(`JOY_B1`).
+
+Fix — press the button you actually mean:
+- Button 1 (main fire, `JOY_B1`) → `input({op:'set', ports:[{b:true}]})` or `{west:true}`
+- Button 2 (`JOY_B2`) → `{a:true}` / `{east:true}`
+
+Prefer the spatial names or `input({op:'press', button:'1'|'2'})` (they resolve
+correctly per platform). `input({op:'layout', platform:'sms'})` has the full map.
+(Note: `input({op:'set'})` takes a `ports` array — `{ports:[{b:true}]}`, not a bare
+`{b:true}`. Same inversion on Game Gear.)
+
+## "ROM builds but the screen is blank / black"
+
+The VDP starts with display disabled (R1 bit 6 = 0). You have to
+explicitly turn it on AFTER you've uploaded palette + tiles +
+name table:
+
+```c
+sms_vdp_init();       /* sets display OFF as a side effect */
+sms_load_palette(...);
+sms_load_tiles(...);
+sms_set_tilemap_cell(...);
+sms_vdp_display_on(); /* ← without this, blank forever */
+```
+
+If you forget `sms_vdp_display_on()` your ROM boots and runs, but
+the display register R1 keeps bit 6 clear and you see nothing.
+
+## "Sprites are invisible / stuck at top of screen"
+
+Two common modes:
+
+1. **You forgot to call `sms_sat_upload()`.** The SAT shadow lives
+   in WRAM; `sms_sprite_set()` only updates the shadow.
+   `sms_sat_upload()` pushes the shadow to VRAM $3F00. Skip it →
+   the VDP draws whatever stale SAT it had from boot.
+2. **Y = 0xD0 anywhere in the SAT.** The SMS uses Y = 0xD0 as a
+   "stop renderer at this slot" marker. If your first sprite has
+   Y = 0xD0 (or you leave the default after `sms_sprite_init`), NO
+   sprites render. Always set Y to a real value before drawing.
+
+## "Colors look wrong / too dark"
+
+SMS CRAM is **2 bits per channel** (4 levels: 0, 1, 2, 3 → encoded
+as 0x00, 0x01, 0x02, 0x03 in the channel). So:
+
+```
+0x00 = black
+0x3F = white (red=3, green=3, blue=3 — all max)
+0x03 = pure red
+0x0C = pure green
+0x30 = pure blue
+```
+
+If your colours look "washed out greenish," you may be passing
+6-bit-per-channel values that get truncated, or you may have the
+Game Gear's 4-bit-per-channel encoding wrongly applied to SMS.
+Run on a real SMS-mode emulator to confirm.
+
+## "SDCC crashes during compile (dbuf_append_str NULL / aopGet)"
+
+R7-era SDCC sm83 had multiple register-allocator regressions
+(see `feedback_sdcc_sm83_crashes.md`). Most are fixed in the
+4.4.0 we ship with the 8 MB stack patch (R12). If you still hit
+one:
+
+- Wrap aggressive `for (;;) { switch + __sfr write }` loops in
+  `do { ... } while (1)` (matches the bundled `default` template's
+  branchless update pattern).
+- Split very-long functions into smaller ones.
+- Avoid mid-block `uint8_t var = expr;` — hoist to function top
+  (SDCC z80 is C89-strict).
+
+The full list of patterns and workarounds is in
+`src/platforms/sms/lib/README.md` (look for the SMS-14 codegen
+notes).
+
+## "Sound from PSG is silent / distorted"
+
+Three things to check:
+
+1. **PSG writes are byte-wise on port $7F.** A `uint16_t` write
+   only sends the low byte; the high byte is dropped.
+2. **The latch-register byte must come first.** Each PSG channel
+   needs `0x80 | (chan << 5) | (vol & 0x0F)` etc., then the data
+   bytes. Random write order = silent or random noise.
+3. **Audio is disabled in some emulator save-state restores.** Try
+   `host({op:'reset'})` first before debugging.
+
+## "Game Gear ROM boots black / wrong colors"
+
+GG ROMs need:
+
+- 4-bit-per-channel palette (use `gg_load_palette`, not `sms_load_palette`)
+- Lower-left 160×144 area of the 256×192 VDP framebuffer (it's
+  hardware-cropped on the GG screen — content outside that window
+  is invisible)
+- Some GG-specific I/O (port $00 for Start, port $06 for stereo
+  PSG mute control)
+
+If you ported an SMS ROM straight to `.gg` it'll boot and run, but
+the colours will be very dark (2-bit values reinterpreted as 4-bit)
+and the visible area is in the top-left corner.
+
+## "ROM > 32 KB doesn't run"
+
+The default template is single-bank (32 KB). To use the Sega
+mapper for larger ROMs, write `bank_n` to `$FFFE` (slot 1) or
+`$FFFF` (slot 2) before reading from $4000-$7FFF / $8000-$BFFF
+respectively. SDCC's default sm83/z80 link doesn't auto-page;
+you write the bank-switch yourself in code, then `jp` into the
+new bank.
+
+For most agent-driven games, stay in 32 KB and the mapper never
+matters.
+
+## "Save states don't restore VDP state"
+
+genesis_plus_gx (which we use for SMS) snapshots VDP/CRAM/VRAM
+fully. If you find a sprite missing after `state({op:'load'})`, the cause
+is usually game-side: your shadow OAM lives in WRAM, which IS
+snapshotted, but your `oam_dma_flush`/`sms_sat_upload`-equivalent
+fires *next frame* — so the very first frame after load may show
+stale SAT until your loop ticks once.
+
+## "First build is slow but later ones are fast"
+
+Expected. SDCC z80 + sdasz80 + sdld cold-load takes ~1-2s for
+the WASM mmap + class init. Steady-state builds are sub-second
+thanks to the worker pool (R12).

package/src/platforms/sms/UPSTREAM_SOURCES.md

@@ -0,0 +1,29 @@
+# Master System — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/sms/templates/*.c`).
+2. **Bundled runtime** — `src/platforms/sms/lib/c/sms_crt0.s`,
+   `vdp_init.c`, `joypad_read.c`, `sprite_table.c`, `sms_sfx.c`,
+   `sms_music.c`. All ~50-100 lines each, fully readable.
+3. **SDCC z80 port** — WASM compiler shipped, source not bundled.
+4. **Upstream GitHub**:
+
+   | What | Upstream |
+   |---|---|
+   | SDCC | http://sdcc.sourceforge.net/ |
+   | genesis_plus_gx libretro (handles SMS) | https://github.com/libretro/Genesis-Plus-GX |
+
+## SMS hardware docs
+
+- **SMS Power!** (canonical homebrew dev hub): https://www.smspower.org/Development/Documents
+- **SN76489 PSG ref**: https://www.smspower.org/Development/SN76489
+- **VDP register reference**: https://www.smspower.org/Development/VDPRegisters
+- **Z80 reference**: https://www.zilog.com/docs/z80/um0080.pdf
+
+## When to use what
+
+- "How does my sprite SAT terminator work?" → MENTAL_MODEL § SAT $D0
+- "SN76489 latch byte layout" → SMS Power PSG ref
+- "VDP mode 4 specifics" → SMS Power VDP registers
+- "genesis_plus_gx doesn't expose register X" → libretro GitHub