romdevtools 0.27.0 → 0.28.0

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -59,15 +59,34 @@ thousands of bytes and you'll drown).
    on-screen value. `region` defaults to `system_ram`.
 2. Change the value in-game (take damage, score a point), then
    `memory({op:'searchNext', compare:'eq', value})` — or `compare:'gt'|'lt'|'changed'|'unchanged'|
-   'inc'|'dec'` when you don't know the new value. Repeat until a handful remain.
+   'inc'|'dec'` when you don't know the new value. The relative compares work as the
+   FIRST narrow too (baselines are recorded at seed). Repeat until a handful remain.
 3. Confirm: `memory({op:'write'})` the candidate and watch the screen react.
 
 This is the Cheat-Engine/RetroArch loop. It is THE bread-and-butter primitive.
 
+**Stored ≠ displayed.** When a correct-looking seed returns 0, the byte usually isn't the
+raw number: seed `as:'bcd'` for packed-BCD scores (2 decimal digits per byte — very common
+on NES), or `as:'digits'` for one byte per ON-SCREEN digit at any constant tile base (HUD
+tile-index buffers; the matched base is reported per candidate, and `searchNext` keeps
+comparing in the same representation). For displayed−1 lives or ÷10 scores, just seed the
+transformed number. If an INPUT drives the value (position, velocity, charge), skip the
+loop entirely: `memory({op:'diffRuns', portsA:[{right:true}]})` isolates it in one call.
+
 `memory({op:'snapshot'})` + `memory({op:'diff'})` is for "which bytes did THIS one event touch?",
 not for value hunting. `memory({op:'diff'})` defaults to a **clustered summary** (ranges +
 stride) so it won't flood you — a reported stride (e.g. "islands at 0x80") is
-usually a struct/entity array, each island one record.
+usually a struct/entity array, each island one record. Small clusters (≤8 bytes) carry
+`before`/`after` hex inline, and `minDelta:N` drops |after−before| < N so RNG/counter
+wiggle disappears from the report.
+
+**"Which byte does this INPUT drive?" → `memory({op:'diffRuns'})`** — runs the same start
+state twice (savestate restore in between) under two different held inputs (`portsA` vs
+`portsB`, default released) for `frames` each, and returns only the bytes that DIVERGE
+between the runs, with run-A/run-B values on small clusters. One call replaces the whole
+save → hold → step → dump → restore → hold-other → dump → diff loop; the frame counter and
+all input-independent churn cancel out automatically. (The emulator is left at the end of
+run B.)
 
 ---
 
@@ -140,7 +159,12 @@ the copy reads from, then `breakpoint({on:'write'})` on THAT.
 **Precision — exact vs sampled.** The default `breakpoint({on:'write'})` is a core-level write
 watchpoint: it returns the EXACT writing instruction's PC, captured inside the CPU write
 path — correct even for NMI/IRQ-driven writes (the common case where a frame-sampled PC
-is just the idle loop). On a banked mapper it reports the `bank` (NES/GB/SMS-GG) so you
+is just the idle loop). On ALL 14 platforms, every hit (write/read/pc) also carries
+**`registersAtHit`** — the full register file frozen AT the hit instant — and the CPU
+stays FROZEN until the hit is cleared. Use registersAtHit instead of a follow-up
+`cpu({op:'read'})`: pre-0.28.0 the live registers kept running after a hit (on gpgx they
+drifted hundreds of instructions — address registers read that way were someone else's
+values). On a banked mapper it reports the `bank` (NES/GB/SMS-GG) so you
 can pass `{startAddress, bank}` to `disasm({target:'rom'})`. The lighter
 `breakpoint({on:'write', precision:'sampled'})` (a.k.a. `watch({on:'mem'})`) steps until the byte changes
 and returns a frame-boundary PC — a lead, not a guarantee under interrupts; use it for the
@@ -197,6 +221,16 @@ pushes a sentinel return, and runs until it returns. Most of these formats have
 you can usually craft a replacement by hand. (sandbox:false leaves the dest buffer
 live for `memory({op:'read'})`; sandbox:true restores the game untouched.)
 
+**Pass `pure:true` — on every platform.** A non-pure call that spans frames runs the
+game's OWN frame logic concurrently (VBlank handlers via RAM vectors, music
+drivers) — which can overwrite the dest buffer mid-call and hand you poisoned
+"ground truth" (a real session spent hours diffing a CORRECT reimplementation
+against it). With `pure:true` the game's handlers CANNOT run: Genesis/SMS/GG step
+only the CPU (`pureMode:'cpu-only'`); everywhere else interrupt DELIVERY is
+suppressed for the duration (`'irq-blocked'` — pending lines stay pending, video
+advances harmlessly); the 2600 has no interrupts (`'no-interrupts'`). Non-pure
+results carry a ⚠ caveat whenever frame logic ran.
+
 ## 5e. Re-inject an edited asset — the round-trip (don't reimplement the compressor)
 
 Once you can SEE the decompressed bytes (5c) and you've edited them, put them BACK
@@ -315,9 +349,14 @@ Once you know WHAT to change, the write loop is a handful of calls — no custom
   confirm a patch landed where you meant.
 - **`disasm({target:'references', path, platform, address})`** — find every instruction that
   references a target address, classified `call/jump/branch/read/write/use/ref` (walks the
-  vector table too). The fast "who touches this?" for a STATIC image. Limitation: direct
-  addressing only — indirect/computed jumps aren't detected (use the runtime `watch`/
-  `breakpoint` tools in §5/§5d for those).
+  vector table too). The fast "who touches this?" for a STATIC image. EVERY banked format
+  is scanned PER BANK — NES mappers (refs carry `prgBank`), and SNES multi-bank LoROM,
+  GB/GBC MBC, SMS/GG Sega-mapper, MSX megaROM, Atari 2600 F8/F6/F4, Atari 7800 SuperGame,
+  and >32KB HuCards (refs carry `romBank`) — so a hit in bank 12 of a 128KB cart shows up,
+  not just the first bank. Zero-page direct + indexed operands match, and `#$nn` immediates
+  are excluded (values, not addresses). Limitation: direct addressing only —
+  indirect/computed jumps aren't detected (use the runtime `watch`/`breakpoint` tools in
+  §5/§5d for those).
 - **`cart({op:'extract', path, outputDir})`** — split a ROM into standard parts (NES header/
   prg/chr; SNES copier_header+rom+internal header; Genesis vectors/header/body; GB boot/
   header/body) + a `manifest.json` (mapper, mirroring…). **`cart({op:'wrap'})`** is the inverse:
@@ -330,8 +369,9 @@ watch the screen react — cheaper than shipping a wrong ROM patch.
 
 For a STRUCTURAL hack (new logic, not a byte poke), turn the whole ROM into a
 re-buildable project in one call: `disasm({target:'project', path, outputDir})`. It splits
-the ROM into regions (per-16KB bank for banked NES, per-32KB for SNES LoROM, slot0+slotX
-for GB, one flat region for SMS/Genesis/C64/Atari), disassembles each through the CPU's
+the ROM into regions (per-bank on EVERY banked format: 16KB banks for NES/GB/SMS-GG/MSX/
+7800-SuperGame, 32KB for SNES LoROM, 4KB for banked 2600, 8KB pages for >32KB HuCards;
+one flat region for Genesis/C64/Lynx/GBA and small carts), disassembles each through the CPU's
 native objdump, then **reassembles + verifies byte-exact** against the original; any line
 that won't reproduce faithfully heals to a `.byte`/`db` of its real bytes, so the emitted
 `.asm` ALWAYS rebuilds (`roundTrip.allByteExact`). `readablePercent` per region tells you
@@ -343,22 +383,27 @@ rebuild exists — a `rebuild.json` of the precise `build({...})` args. So the l
 
 **Two rebuild tiers** (the disasm emits each CPU's native-reassembler syntax — ca65 for
 6502/65816, GNU `as` for m68k/arm/z80/gbz80 — which only some `build()` toolchains consume):
-- **One-call `build()` rebuild, byte-identical** — **NES, C64, Atari 7800, Lynx**. Feed
-  `rebuild.json` straight to `build`. (Lynx: `build()` yields the headerless image; prepend
-  the shipped `lnx_header.bin` for the full `.lnx`.)
+- **One-call `build()` rebuild, byte-identical** — **NES (NROM *and* banked mappers), C64,
+  Atari 7800 (flat *and* SuperGame banked), Lynx, PC Engine (flat *and* banked HuCards)**.
+  Feed `rebuild.json` straight to `build`. Banked projects ship a HEADER segment with the
+  original header bytes (16 iNES / 128 .a78 / 512 copier), per-bank segment wrappers, and a
+  generated multi-bank `.cfg` referenced via `linkerConfigPath` (so the cfg never streams
+  through context). (Lynx: `build()` yields the headerless image; prepend the shipped
+  `lnx_header.bin` for the full `.lnx`.)
 - **Native-recipe rebuild (`buildCall:null`), byte-identical, steps in `BUILD.md`** — **SMS,
   GG, MSX, GB, GBC, Genesis, GBA, Atari 2600**. Their `build()` toolchains (SDCC/RGBDS/asar/
   dasm/vasm) can't reassemble ca65/GNU-as syntax, so `BUILD.md` gives the proven native
-  `as`/`ld`/`objcopy` chain.
-- **PC Engine** is the one not-yet-byte-exact case (the region trims real padding / doesn't
-  strip a copier header) — `BUILD.md` flags it.
+  `as`/`ld`/`objcopy` chain — per-bank on banked carts (Sega-mapper SMS/GG, MSX megaROMs,
+  banked 2600 get per-bank wrappers + cfg blobs and a bank-by-bank recipe).
 
 **Rebuilding a commercial NES (NROM CHR-ROM) game — `build({inesHeader})`:** the most common
 NES RE rebuild. `build({output:'rom', platform:'nes', inesHeader:{prgBanks, chrBanks, mapper,
 mirroring}, sourcesPaths:{…the PRG…}, binaryIncludePaths:{"chr.bin":…}})` auto-emits the
 16-byte iNES header + CHARS-segment wiring + flat NROM `.cfg` — no hand-derived header bytes.
-`disasm({target:'project'})` puts exactly this call in `rebuild.json`. (For homebrew C that
-ships fixed tile art, `linkerConfig:"chr-rom"` is the segment-split equivalent.)
+`disasm({target:'project'})` puts exactly this call in `rebuild.json` for NROM; banked
+mappers get the per-bank segment + multi-bank `.cfg` form instead (see the one-call tier
+above). (For homebrew C that ships fixed tile art, `linkerConfig:"chr-rom"` is the
+segment-split equivalent.)
 
 **Readability caveats** (the bytes are ALWAYS correct; only instruction-vs-`.byte` coverage
 varies): SNES and large Genesis ROMs come back byte-exact but DATA-ONLY (flat whole-ROM
@@ -398,6 +443,7 @@ For sprite/tile edits (not text), don't hand-roll the tile-format math:
 |---|---|
 | Find a value's address | `memory({op:'search'})` → `memory({op:'searchNext'})` (NOT full-RAM diff) |
 | Which bytes did one event touch | `memory({op:'snapshot'})` → `memory({op:'diff'})` (summary) |
+| Which byte does an INPUT drive | `memory({op:'diffRuns', portsA, portsB?})` (A/B divergence, one call) |
 | Is on-screen text a string or a bitmap | `text({op:'learn'})` (reports pre-rendered graphic) |
 | Is a "table" really ASCII/code | `memory({op:'classify'})` |
 | Confirm a patch is in the running ROM | `memory({op:'readCart'})` |
@@ -406,7 +452,8 @@ For sprite/tile edits (not text), don't hand-roll the tile-format math:
 | Which instruction READ a byte | `breakpoint({on:'read', address})` (read-side `breakpoint({on:'write'})`) |
 | Single-step the CPU | `frame({op:'stepInstruction'})` (+ `cpu({op:'read'})` to watch regs) |
 | Set a CPU register | `cpu({op:'setReg', regId, value})` |
-| Decompress a compressed asset | `cpu({op:'decompress'})` / `cpu({op:'call'})` (run the ROM's own codec) |
+| Decompress a compressed asset | `cpu({op:'decompress'})` / `cpu({op:'call', pure:true})` (run the ROM's own codec, interference-free) |
+| Where does this on-screen graphic come from | `watch({on:'copy', start, end})` (all 14 — writer PC per VRAM write; Genesis DMA also via `watch({on:'dma'})`) |
 | Re-inject edited bytes the game accepts | `romPatch({op:'makeStored'})` (verbatim-expand block) → `romPatch({op:'findFree'})` → `romPatch({op:'relocate'})` |
 | Find the pointer that loads an asset | `romPatch({op:'findPointer', romOffset})` |
 | FIND the unknown routine touching X | `watch({on:'range', start,end})` (all hits) / `watch({on:'pc'})` (coverage) |

package/src/platforms/atari2600/MENTAL_MODEL.md

@@ -215,7 +215,11 @@ What you can read:
   registers.
 - **`disasm({target:'rom'})`** and **`disasm({target:'references'})`** —
   both anchor to the top of the bank (`$F000-$FFFF`) and label the vector
-  table (NMI / RESET / IRQ at `$FFFA`).
+  table (NMI / RESET / IRQ at `$FFFA`). On banked carts (F8 = 8 KB,
+  F6 = 16 KB, F4 = 32 KB) `references` scans EVERY 4 KB bank at `$F000`,
+  refs tagged `romBank`; `disasm({target:'project'})` likewise emits one
+  region per bank plus per-bank `BANKn` wrappers and a multi-area `.cfg`
+  blob for the native ca65/ld65 rebuild.
 
 Memory regions for **`memory({op:'read'})`**:
 

package/src/platforms/atari2600/TROUBLESHOOTING.md

@@ -159,3 +159,43 @@ snippet for one approach.
 ## "First build is slow but later ones are fast"
 
 Expected. dasm cold-load is ~500ms. Steady-state builds < 100ms.
+
+
+## Pressing RIGHT also "presses" LEFT (or the player can't move at all)
+
+The classic `LDA SWCHA / ASL / BCS … / ASL / BCS …` carry-chain only works if
+NOTHING between the shifts touches A. The moment a branch body does
+`LDA P_X` (a bounds check, a compare), the next `ASL` shifts your *position*
+instead of SWCHA — and since positions are < $80, carry comes back clear and
+the "other direction" fires too. Net effect: moves cancel, the sprite sticks
+to one edge. **Re-load SWCHA and AND a single bit per direction instead:**
+
+```asm
+  LDA SWCHA
+  AND #$80        ; bit7 = P0 Right (active LOW: 0 = pressed)
+  BNE .noRight
+  ...move right (clobber A freely)...
+.noRight:
+  LDA SWCHA
+  AND #$40        ; bit6 = P0 Left
+  BNE .noLeft
+  ...
+```
+
+## Jump plays its sound but the player never leaves the ground
+
+Signed-velocity clamps must check the SIGN first. An unsigned
+`CMP #$F8 / BCS keep` "terminal velocity" clamp also catches every POSITIVE
+(rising) velocity — +6 is less than $F8 unsigned — so the jump impulse is
+instantly slammed to falling and the whole arc resolves inside one frame
+(SFX plays, screen blips, no visible jump). Clamp only while falling:
+
+```asm
+  LDA P_VY
+  BPL .vyok       ; rising → terminal clamp doesn't apply
+  CMP #$F8
+  BCS .vyok       ; -8..-1 → fine
+  LDA #$F8        ; clamp to -8
+  STA P_VY
+.vyok:
+```

package/src/platforms/atari7800/MENTAL_MODEL.md

@@ -237,10 +237,23 @@ read:
 
 ```c
 uint8_t pad = ~SWCHA;
-if (pad & JOY_UP)    /* P1 up */
-if (pad & JOY_DOWN)  /* P1 down */
-if (pad & JOY_LEFT)  /* P1 left */
 if (pad & JOY_RIGHT) /* P1 right */
+if (pad & JOY_LEFT)  /* P1 left */
+if (pad & JOY_DOWN)  /* P1 down */
+if (pad & JOY_UP)    /* P1 up */
+```
+
+**The bit order is the #1 7800 input footgun.** From bit 7 down the P1 nibble
+is **Right ($80), Left ($40), Down ($20), Up ($10)** — same as the 2600. Defining
+`JOY_UP 0x80 … JOY_RIGHT 0x10` (the "reads naturally" order) is exactly
+REVERSED, and the symptom is bizarre enough to misdiagnose: up/down steer
+left/right and vice versa. Always:
+
+```c
+#define JOY_RIGHT 0x80
+#define JOY_LEFT  0x40
+#define JOY_DOWN  0x20
+#define JOY_UP    0x10
 ```
 
 Fire button on `INPT4` at `$0C`, also active low.
@@ -343,9 +356,17 @@ What you can read:
   P / SP / PC) read from prosystem's `sally` globals.
 - **`background({view:'renderState'})`** — the MARIA CTRL bits, DPP,
   CHARBASE, and the current `dlistPtr`.
-- **`disasm({target:'rom'})`** and **`disasm({target:'references'})`** —
-  both default to the top 16 KB (`$C000-$FFFF`), where the reset vector
-  lands.
+- **`disasm({target:'rom'})`** — defaults to the top 16 KB
+  (`$C000-$FFFF`), where the reset vector lands.
+- **`disasm({target:'references'})`** — scans the WHOLE cart: flat carts
+  (≤48 KB) in one pass at their top-of-space org, SuperGame banked carts
+  (>48 KB) per 16 KB bank (last bank fixed at `$C000`, others at `$8000`),
+  refs tagged `romBank`. A 128-byte `.a78` header is stripped automatically.
+- **`disasm({target:'project'})`** — flat carts rebuild with one flat cc65
+  build; SuperGame carts get per-bank regions + NES-style glue (HEADER
+  segment with the original 128 header bytes, `BANKn` wrappers, multi-bank
+  `.cfg` via `linkerConfigPath`) — a one-call byte-identical
+  `build()` rebuild either way.
 
 Memory regions for **`memory({op:'read'})`**:
 

package/src/platforms/gb/MENTAL_MODEL.md

@@ -68,7 +68,10 @@ returns nothing.
 `disasm({target:'project'})` route through the native binutils z80 `objdump` in
 its `gbz80` machine (WASM, `-m gbz80`) — full CB-prefix coverage plus the
 SM83-specific opcodes (`ld (hl+),a`, `ldh`, `reti`, `ld hl,sp+e8`). One z80-elf
-binutils serves both plain Z80 (SMS/GG/MSX) and the GB CPU.
+binutils serves both plain Z80 (SMS/GG/MSX) and the GB CPU. MBC-banked carts
+(>32 KB) are scanned per 16 KB bank by `references` (bank 0 @ `$0000`, banks
+1+ @ their `$4000` window; refs tagged `romBank`) and split per-bank by
+`disasm({target:'project'})`.
 
 ## Five silent-failure footguns to know before you start (R26 + R27)
 
@@ -103,6 +106,18 @@ check these first. All five have shipped fixes in the bundled runtime
    (volatile-safe by construction) or cast through `volatile uint8_t *`.
    See `gb_runtime/lib/c/SDCC_GOTCHAS.md` § "Writes to VRAM" for detail.
 
+3b. **OAM DMA goes FIRST after `wait_vblank()` — before any staging work.**
+   The vblank window is ~10 scanlines (~1140 cycles) and SDCC call overhead
+   is brutal: even a few dozen `oam_set()` CALLS before the flush push the
+   DMA out of vblank into active display, where it tears the sprites on one
+   FIXED scanline every frame (the "horizontal line a third of the way down"
+   glitch). The robust frame shape is: stage OAM/BG writes into RAM any time
+   during the frame, then `wait_vblank(); oam_dma_flush();` as the very first
+   thing, then a small bounded batch of BG map writes. One frame of sprite
+   latency is imperceptible. Also: statics belong at `dataLoc 0xC200` or
+   above (the project recipe sets this) so they can't collide with
+   `shadow_oam` at $C100.
+
 4. **OAM DMA must run from HRAM.** During the ~160 µs OAM DMA window
    the CPU can ONLY fetch from HRAM ($FF80-$FFFE). The bundled
    `oam_dma_copy()` now installs a 9-byte stub at $FF80 and CALLs it;

package/src/platforms/gb/TROUBLESHOOTING.md

@@ -166,6 +166,48 @@ at $0150. If you see code in that window, either:
   works; don't override it for GB/GBC unless you know what you're
   doing.
 
+## "BG map updates randomly don't stick" / a tile updates one frame late forever
+
+The core (like real hardware mid-frame) DROPS writes to VRAM ($8000-$9FFF)
+that land outside vblank while the LCD is on — silently. A game loop that
+pokes the BG map "whenever the state changes" will have SOME of those pokes
+land mid-frame and vanish: stale cells, a piece that visually lags the
+logical grid, glitches that move around as code timing shifts.
+
+The robust pattern (used by the bundled puzzle scaffolds):
+
+1. **COLLECT** — during the frame, don't touch VRAM. Append (addr, tile)
+   pairs to a small RAM queue whenever game state changes a cell.
+2. **FLUSH** — immediately after `wait_vblank()` (right after the OAM DMA),
+   drain the queue with pure writes. No scanning, no logic — vblank is only
+   ~1140 cycles, so the flush must be writes only and bounded.
+3. **Scrub** — repaint one or two rows per frame round-robin as insurance,
+   so any cell that ever got dropped self-heals within a second.
+
+If you must write outside that structure, turn the LCD off first (only
+acceptable during init/load screens — mid-game it flashes white).
+
+## "BG map updates randomly don't stick" / a tile updates one frame late forever
+
+The core (like real hardware mid-frame) DROPS writes to VRAM ($8000-$9FFF)
+that land outside vblank while the LCD is on — silently. A game loop that
+pokes the BG map "whenever the state changes" will have SOME of those pokes
+land mid-frame and vanish: stale cells, a piece that visually lags the
+logical grid, glitches that move around as code timing shifts.
+
+The robust pattern (used by the bundled puzzle scaffolds):
+
+1. **COLLECT** — during the frame, don't touch VRAM. Append (addr, tile)
+   pairs to a small RAM queue whenever game state changes a cell.
+2. **FLUSH** — immediately after `wait_vblank()` (right after the OAM DMA),
+   drain the queue with pure writes. No scanning, no logic — vblank is only
+   ~1140 cycles, so the flush must be writes only and bounded.
+3. **Scrub** — repaint one or two rows per frame round-robin as insurance,
+   so any cell that ever got dropped self-heals within a second.
+
+If you must write outside that structure, turn the LCD off first (only
+acceptable during init/load screens — mid-game it flashes white).
+
 ## Debug recipes
 
 A few high-leverage tools you might not know exist:

package/src/platforms/gb/lib/c/patch-header.js

@@ -7,10 +7,13 @@
 //
 // WHY: most libretro GB cores (gambatte) refuse to load a ROM whose
 // Nintendo logo at $0104-$0133 doesn't match the canonical bytes or
-// whose header checksum at $014D doesn't validate. RGBDS's `rgbfix`
-// does this in the asm-build path; for SDCC-built C ROMs (which our
-// pipeline does NOT auto-patch — every byte that compiles is yours),
-// this script does the same job.
+// whose header checksum at $014D doesn't validate.
+//
+// NOTE: romdev's own build pipeline DOES auto-patch the header now (it
+// runs a bundled rgbfix after every gb/gbc link — see the
+// "rgbfix (auto header fix)" line in build logs), so you only need this
+// script when rebuilding the project OUTSIDE romdev with stock SDCC and
+// no RGBDS installed. It's what keeps the scaffold self-contained.
 //
 // The bundled gb_crt0.s reserves $0100-$014F for the header window,
 // so the bytes patched in here land on actual cartridge-header

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -31,6 +31,18 @@ the same wall.
    cast through `volatile uint8_t *`. See `lib/c/SDCC_GOTCHAS.md`
    § "Writes to VRAM".
 
+3b. **OAM DMA goes FIRST after `wait_vblank()` — before any staging work.**
+   The vblank window is ~10 scanlines (~1140 cycles) and SDCC call overhead
+   is brutal: even a few dozen `oam_set()` CALLS before the flush push the
+   DMA out of vblank into active display, where it tears the sprites on one
+   FIXED scanline every frame (the "horizontal line a third of the way down"
+   glitch). The robust frame shape is: stage OAM/BG writes into RAM any time
+   during the frame, then `wait_vblank(); oam_dma_flush();` as the very first
+   thing, then a small bounded batch of BG map writes. One frame of sprite
+   latency is imperceptible. Also: statics belong at `dataLoc 0xC200` or
+   above (the project recipe sets this) so they can't collide with
+   `shadow_oam` at $C100.
+
 4. **OAM DMA must run from HRAM.** During the ~160 µs OAM DMA window
    the CPU can ONLY fetch from HRAM ($FF80-$FFFE). The bundled
    `oam_dma_copy()` installs a 9-byte stub at $FF80 and CALLs it; the

package/src/platforms/gbc/TROUBLESHOOTING.md

@@ -120,6 +120,27 @@ in DMG mode. To switch a DMG ROM to CGB:
 2. Run `romPatch({op:'gbHeader', path:"out.gbc"})` — also fixes the global
    checksum that the boot ROM checks
 
+## "BG map updates randomly don't stick" / a tile updates one frame late forever
+
+The core (like real hardware mid-frame) DROPS writes to VRAM ($8000-$9FFF)
+that land outside vblank while the LCD is on — silently. A game loop that
+pokes the BG map "whenever the state changes" will have SOME of those pokes
+land mid-frame and vanish: stale cells, a piece that visually lags the
+logical grid, glitches that move around as code timing shifts.
+
+The robust pattern (used by the bundled puzzle scaffolds):
+
+1. **COLLECT** — during the frame, don't touch VRAM. Append (addr, tile)
+   pairs to a small RAM queue whenever game state changes a cell.
+2. **FLUSH** — immediately after `wait_vblank()` (right after the OAM DMA),
+   drain the queue with pure writes. No scanning, no logic — vblank is only
+   ~1140 cycles, so the flush must be writes only and bounded.
+3. **Scrub** — repaint one or two rows per frame round-robin as insurance,
+   so any cell that ever got dropped self-heals within a second.
+
+If you must write outside that structure, turn the LCD off first (only
+acceptable during init/load screens — mid-game it flashes white).
+
 ## "Sound is the same as DMG"
 
 That's correct — CGB has the **identical** 4-channel APU as DMG. The

package/src/platforms/gbc/lib/c/font.h

@@ -0,0 +1,43 @@
+/* AUTO-GENERATED by gen_font.py — 5x7 font, GB 2bpp, ink=value 3. */
+#ifndef FONT_H
+#define FONT_H
+#define FONT_GLYPHS 36
+static const uint8_t font_data[576] = {
+    0x38, 0x38, 0x44, 0x44, 0x4C, 0x4C, 0x54, 0x54, 0x64, 0x64, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 0 */
+    0x10, 0x10, 0x30, 0x30, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x38, 0x38, 0x00, 0x00,  /* 1 */
+    0x38, 0x38, 0x44, 0x44, 0x04, 0x04, 0x08, 0x08, 0x10, 0x10, 0x20, 0x20, 0x7C, 0x7C, 0x00, 0x00,  /* 2 */
+    0x7C, 0x7C, 0x08, 0x08, 0x10, 0x10, 0x08, 0x08, 0x04, 0x04, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 3 */
+    0x08, 0x08, 0x18, 0x18, 0x28, 0x28, 0x48, 0x48, 0x7C, 0x7C, 0x08, 0x08, 0x08, 0x08, 0x00, 0x00,  /* 4 */
+    0x7C, 0x7C, 0x40, 0x40, 0x78, 0x78, 0x04, 0x04, 0x04, 0x04, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 5 */
+    0x18, 0x18, 0x20, 0x20, 0x40, 0x40, 0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 6 */
+    0x7C, 0x7C, 0x04, 0x04, 0x08, 0x08, 0x10, 0x10, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x00, 0x00,  /* 7 */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 8 */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x3C, 0x3C, 0x04, 0x04, 0x08, 0x08, 0x30, 0x30, 0x00, 0x00,  /* 9 */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x7C, 0x7C, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* A */
+    0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x78, 0x78, 0x00, 0x00,  /* B */
+    0x38, 0x38, 0x44, 0x44, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* C */
+    0x70, 0x70, 0x48, 0x48, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x48, 0x48, 0x70, 0x70, 0x00, 0x00,  /* D */
+    0x7C, 0x7C, 0x40, 0x40, 0x40, 0x40, 0x78, 0x78, 0x40, 0x40, 0x40, 0x40, 0x7C, 0x7C, 0x00, 0x00,  /* E */
+    0x7C, 0x7C, 0x40, 0x40, 0x40, 0x40, 0x78, 0x78, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x00, 0x00,  /* F */
+    0x38, 0x38, 0x44, 0x44, 0x40, 0x40, 0x5C, 0x5C, 0x44, 0x44, 0x44, 0x44, 0x3C, 0x3C, 0x00, 0x00,  /* G */
+    0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x7C, 0x7C, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* H */
+    0x38, 0x38, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x38, 0x38, 0x00, 0x00,  /* I */
+    0x1C, 0x1C, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x48, 0x48, 0x30, 0x30, 0x00, 0x00,  /* J */
+    0x44, 0x44, 0x48, 0x48, 0x50, 0x50, 0x60, 0x60, 0x50, 0x50, 0x48, 0x48, 0x44, 0x44, 0x00, 0x00,  /* K */
+    0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x7C, 0x7C, 0x00, 0x00,  /* L */
+    0x44, 0x44, 0x6C, 0x6C, 0x54, 0x54, 0x54, 0x54, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* M */
+    0x44, 0x44, 0x44, 0x44, 0x64, 0x64, 0x54, 0x54, 0x4C, 0x4C, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* N */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* O */
+    0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x78, 0x78, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x00, 0x00,  /* P */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x54, 0x54, 0x48, 0x48, 0x34, 0x34, 0x00, 0x00,  /* Q */
+    0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x78, 0x78, 0x50, 0x50, 0x48, 0x48, 0x44, 0x44, 0x00, 0x00,  /* R */
+    0x3C, 0x3C, 0x40, 0x40, 0x40, 0x40, 0x38, 0x38, 0x04, 0x04, 0x04, 0x04, 0x78, 0x78, 0x00, 0x00,  /* S */
+    0x7C, 0x7C, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x00, 0x00,  /* T */
+    0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* U */
+    0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x28, 0x28, 0x10, 0x10, 0x00, 0x00,  /* V */
+    0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x54, 0x54, 0x54, 0x54, 0x6C, 0x6C, 0x44, 0x44, 0x00, 0x00,  /* W */
+    0x44, 0x44, 0x44, 0x44, 0x28, 0x28, 0x10, 0x10, 0x28, 0x28, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* X */
+    0x44, 0x44, 0x44, 0x44, 0x28, 0x28, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x00, 0x00,  /* Y */
+    0x7C, 0x7C, 0x04, 0x04, 0x08, 0x08, 0x10, 0x10, 0x20, 0x20, 0x40, 0x40, 0x7C, 0x7C, 0x00, 0x00,  /* Z */
+};
+#endif

package/src/platforms/gbc/lib/c/patch-header.js

@@ -7,10 +7,13 @@
 //
 // WHY: most libretro GB cores (gambatte) refuse to load a ROM whose
 // Nintendo logo at $0104-$0133 doesn't match the canonical bytes or
-// whose header checksum at $014D doesn't validate. RGBDS's `rgbfix`
-// does this in the asm-build path; for SDCC-built C ROMs (which our
-// pipeline does NOT auto-patch — every byte that compiles is yours),
-// this script does the same job.
+// whose header checksum at $014D doesn't validate.
+//
+// NOTE: romdev's own build pipeline DOES auto-patch the header now (it
+// runs a bundled rgbfix after every gb/gbc link — see the
+// "rgbfix (auto header fix)" line in build logs), so you only need this
+// script when rebuilding the project OUTSIDE romdev with stock SDCC and
+// no RGBDS installed. It's what keeps the scaffold self-contained.
 //
 // The bundled gb_crt0.s reserves $0100-$014F for the header window,
 // so the bytes patched in here land on actual cartridge-header

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -50,9 +50,13 @@ memory({op:'read', region:'system_ram', offset: sym.ramOffset, length:2})
 - **`static` file-local globals resolve too** (SGDK emits per-symbol sections).
   A non-`static` global that's never *read* can be optimised away at -O2 — mark
   game-state vars you inspect `volatile` (you want that anyway).
-- **Genesis WRAM is host-LE word-byte-swapped** in gpgx, so a 16-bit value reads
-  with its two bytes swapped at the offset (0x1234 → bytes `34 12`). Read the
-  word and account for it, or read single bytes.
+- **WRAM (`system_ram`) is normalized to CPU byte order** — offset X is the
+  byte the 68k sees at $FF0000+X, words read big-endian as expected, and
+  offsets line up with disassembly addresses and cheat-DB maps. (gpgx stores
+  work RAM host-LE word-swapped internally; the host un-swaps it. Before
+  0.28.0 the raw swapped layout leaked through — value-search/diff loops were
+  self-consistent, but any offset cross-referenced against a `move.b $FFxxxx`
+  in a disassembly was off-by-XOR-1.)
 - **PC → which function?** `symbols({op:'addr', pc, symbolsText: b.mapText})` maps
   a live `cpu({op:'read'}).pc` to the enclosing C function.
 
@@ -427,10 +431,40 @@ Video is deeply readable; the FM audio chip is only partially exposed:
   `getPsgState` decodes the SN76489 (3 tone + 1 noise channels).
 - **Memory regions:** `memory({op:'read'})` exposes CRAM, VSRAM, VDP_REGS,
   Z80_RAM (the sound CPU's RAM), M68K work RAM, YM2612, PSG, and VRAM.
-  Remember the gpgx byte-swap quirk: VRAM and WRAM read host-LE
+  Remember the gpgx byte-swap quirk for VRAM: it reads host-LE
   word-byte-swapped (a 16-bit value's two bytes are swapped at the offset)
-  — account for it or read single bytes (see "Reading your C globals
-  headlessly").
+  — use tiles({op:'pixels'}) to decode in render order. M68K work RAM
+  (`system_ram`) is NOT affected: it's normalized to CPU byte order (see
+  "Reading your C globals headlessly").
+
+## Break-instant truth: registersAtHit + pure calls (0.28.0)
+
+gpgx schedules its CPUs per scanline, so a `breakpoint` hit mid-frame used to
+leave the LIVE register file hundreds of instructions past the hit by the time
+you could read it — chasing pointer registers read that way burned a real
+session for ~2h. Fixed two ways:
+
+- **`registersAtHit`** — `breakpoint({on:'pc'|'write'|'read'})` hits now carry
+  the FULL register file (d0-d7/a0-a7/pc/sr/sp) frozen by the core at the hit
+  instant. Use it, never a follow-up `cpu({op:'read'})`. The reported `pc` for
+  write/read hits is the EXECUTING instruction's first byte (pre-0.28.0 it was
+  the post-prefetch PC — one instruction late). On a pc-break the 68k also
+  stays FROZEN for the rest of the frame, so even live reads agree.
+- **`cpu({op:'call', pure:true})`** — steps ONLY the 68k: no VDP lines, no
+  Z80, no interrupts raised. Without it, a driven routine that spans frames
+  runs the game's own VBlank logic concurrently — which can stomp the output
+  buffer you're capturing (a real session diffed a CORRECT codec
+  reimplementation against that poisoned "ground truth" for hours). Prefer
+  `pure:true` for every decompressor/codec call; non-pure results carry a ⚠
+  caveat when frame logic ran. (SMS/GG get the same via the shared core; the
+  OTHER platforms get the same guarantee via interrupt blocking —
+  `pureMode:'irq-blocked'` — so the technique transfers everywhere.)
+- **`watch({on:'copy'})`** — the CPU-port complement of `watch({on:'dma'})`:
+  logs every data-port write landing in a VRAM window with the executing
+  instruction's PC. Use `dma` when the upload is DMA'd (most Genesis
+  graphics), `copy` when the game pokes the data port directly (the
+  "video_ram writes don't reach the renderer" class of confusion — `copy`
+  shows you who's writing and where).
 
 ## ROM layout
 

package/src/platforms/genesis/lib/c/genesis_sfx.c

@@ -32,6 +32,42 @@ void sfx_noise(u8 length_frames) {
     sfx_remaining[3] = length_frames;
 }
 
+/* ── background music: a 16-step melody loop on PSG channel 2 ───────
+ * Ticked from sfx_update(), so every scaffold that already calls
+ * sfx_init() + sfx_update() gets continuous music for free ("no sound"
+ * was the #1 playtest complaint — a lone 6-frame blip on a rare event
+ * reads as silence). sfx_music(0) turns it off. SFX own channels 0-1 +
+ * noise, so effects always cut through. */
+static const u16 music_hz[16] = {
+    262, 330, 392, 523, 392, 330, 262, 0,     /* C4 E4 G4 C5 G4 E4 C4 -  */
+    220, 262, 330, 440, 330, 262, 220, 0,     /* A3 C4 E4 A4 E4 C4 A3 -  */
+};
+static u8 music_enabled = 1;
+static u8 music_step, music_timer;
+
+void sfx_music(u8 on) {
+    music_enabled = on;
+    music_step = 0;
+    music_timer = 0;
+    if (!on) PSG_setEnvelope(2, PSG_ENVELOPE_MIN);
+}
+
+static void music_tick(void) {
+    if (!music_enabled) return;
+    if (music_timer == 0) {
+        u16 hz = music_hz[music_step & 15];
+        if (hz) {
+            PSG_setFrequency(2, hz);
+            PSG_setEnvelope(2, 5);            /* moderate, under the SFX */
+        } else {
+            PSG_setEnvelope(2, PSG_ENVELOPE_MIN);
+        }
+        music_step++;
+    }
+    music_timer++;
+    if (music_timer >= 9) music_timer = 0;    /* ~6.6 notes/sec */
+}
+
 void sfx_update(void) {
     for (u8 i = 0; i < 4; i++) {
         if (sfx_remaining[i] > 0) {
@@ -41,6 +77,7 @@ void sfx_update(void) {
             }
         }
     }
+    music_tick();
 }
 
 void sfx_off(void) {

package/src/platforms/genesis/lib/c/genesis_sfx.h

@@ -42,6 +42,7 @@ void sfx_noise(u8 length_frames);
  * decrement the auto-silence countdown. Without this, notes never
  * stop ringing. */
 void sfx_update(void);
+void sfx_music(u8 on);   /* background melody loop on PSG ch2 — ON by default; 0 = off */
 
 /* Power down all PSG channels immediately. */
 void sfx_off(void);

package/src/platforms/gg/TROUBLESHOOTING.md

@@ -92,20 +92,16 @@ 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.
+## "TMR SEGA" header / ROM boots in the wrong video mode
+
+The build pipeline now stamps the 16-byte header at `$7FF0` automatically
+("TMR SEGA" + checksum + the region/size byte at `$7FFF`) and pads every
+image to 32 KB — you never hand-write it for romdev builds.
+
+The byte that matters is `$7FFF`: **high nibble = region, low nibble = ROM
+size**. romdev writes `$7C` (GG international, 32 KB) on `.gg` builds.
+If you patch a ROM by hand and leave an SMS region nibble there (`$4C` =
+SMS export), gpgx boots the `.gg` file in **SMS compatibility mode** —
+256×192 timing, SMS palette depth — and everything renders dark and
+mis-cropped even though your code is fine. Check `$7FFF` first when a GG
+ROM suddenly looks like an SMS ROM.