romdevtools 0.27.0 → 0.29.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

@@ -58,7 +58,7 @@ and DLL; you do NOT poke pixels into a framebuffer.**
   and (worse) burns enough cycles that the CPU stops getting time.
 - **Y position = which zone the object lives in.** Each zone covers
   N scanlines. To move an object up/down, you move it between
-  zones. (Or — in our scaffolds — you stamp the same sprite at
+  zones. (Or — in our example games — you stamp the same sprite at
   different row offsets within ONE zone's data block, which fakes
   Y movement.)
 - **Each DL header can pick a palette per object** (one of 8
@@ -136,7 +136,7 @@ The "loop continues" mask is `0x5F` (bits 0-4 + bit 6). Bit 5
 (indirect flag) and bit 7 (write-mode) do NOT keep the loop going
 by themselves.
 
-### 5-byte extended form (the bundled scaffolds use this)
+### 5-byte extended form (the bundled example games use this)
 
 ```
 +0  pixel-data LOW byte
@@ -195,7 +195,7 @@ scanlines for the ENTIRE display area (243 scanlines on NTSC,
 including 10 lines of top overscan before the visible area).
 
 If your DLL is shorter than 243 entries, MARIA reads past the end
-into random memory and renders garbage zones. The bundled scaffold
+into random memory and renders garbage zones. The bundled example
 allocates 243 entries × 3 bytes = 729 bytes (fits easily in 4 KB
 internal RAM) and points every zone with no objects at a shared
 `dl_empty[2] = {0, 0}` terminator.
@@ -213,11 +213,11 @@ for an 8-row sprite) unless you pack many sprites per page.
 **Easy work-around:** make every zone 1 scanline tall (offset=0)
 and use one DL entry per sprite ROW. Then `offset` is always 0, the
 address quirk goes away, and you can store sprite rows back-to-back.
-The bundled scaffold uses this pattern.
+The bundled example uses this pattern.
 
 The cost is more DLL entries (one per scanline), but at 3 bytes each
 across 243 lines = 729 bytes total — trivial RAM cost. Worth it for
-the simpler mental model on a starter scaffold.
+the simpler mental model on a starter example.
 
 ## Colour bytes (Atari NTSC palette)
 
@@ -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/atari7800/TROUBLESHOOTING.md

@@ -56,14 +56,14 @@ you have to:
 2. Place the sprite's DL entry into the zone covering its Y range.
 3. Per-frame, move the entry's bytes from old-zone DL → new-zone DL.
 
-Our scaffolds use a single-zone DLL for simplicity. Vertical
+Our example games use a single-zone DLL for simplicity. Vertical
 movement is faked by stamping the sprite at different row offsets
 within the canvas data — only works if the canvas is tall enough.
 
 ## "Memory overflow during link (RAM1 by N bytes)"
 
 The 7800 has **4 KB of RAM**. The `default.c` and `hello_sprite.c`
-scaffolds use very little; the `shmup.c` puzzle (and the older
+example games use very little; the `shmup.c` puzzle (and the older
 canvas-buffer approach) easily blow past it.
 
 Symptoms:
@@ -77,7 +77,7 @@ Fixes:
 - Use ROM constants (`const uint8_t` at file scope) instead of
   RAM globals.
 - Replace canvas-buffer rendering with per-object DLs (see
-  `shmup.c` scaffold for the canonical pattern).
+  `shmup.c` example for the canonical pattern).
 - Avoid per-frame `memset(canvas, 0, ...)` — instead, only stamp
   changed cells.
 
@@ -126,7 +126,7 @@ DL during active rendering; safe modification windows:
 Build a "next-frame" DL during the game-state update phase and
 swap pointers (DPPL/DPPH) at vblank — double-buffered.
 
-Our scaffolds rebuild the DL during vblank, which works for small
+Our example games rebuild the DL during vblank, which works for small
 DLs (< ~100 bytes). Large DLs that take ~1 ms to rebuild may
 exceed vblank time and start corrupting the active frame.
 
@@ -197,5 +197,5 @@ Fix options (in order of how much they shrink BSS):
   if you only need one sprite at a time — see `default.c` and
   `hello_sprite.c`. No per-scanline pool needed.
 
-The bundled scaffolds size their pools to fit; if you scale up
+The bundled example games size their pools to fit; if you scale up
 (more objects, taller play area), watch the build log.

package/src/platforms/c64/MENTAL_MODEL.md

@@ -115,9 +115,16 @@ which is what the KERNAL's IRQ uses to update key state every
 
 **Joystick.** One fire button. Press it with `input({op:'set', b: true})` (or
 spatial `south`) — both clear `$DC00` bit 4 (verified live). `a` is a **no-op**
-(no second button). Drive fire with `b`/`south` + the d-pad. The joystick reads
-**port 2** by default; switch with `input({op:'joyport', joyport:1})` /
-`input({op:'joyport'})` to read it.
+(no second button). Drive fire with `b`/`south` + the d-pad.
+
+**Two players.** BOTH C64 control ports are live at once, so 2P games just work:
+**host port 0 = player 1** (control port 2, `$DC00`) and **host port 1 = player
+2** (control port 1, `$DC01`) — the universal "port 0 = P1" convention. Pass two
+port entries: `input({op:'set', ports:[{up:true}, {down:true}]})` moves P1 up and
+P2 down independently. (Under the hood the host enables the VICE userport-adapter
+mapping so both ports route, and swaps them so P1 lands on control port 2 where
+the games read it.) The legacy `input({op:'joyport', joyport:1|2})` still selects
+which single port a ONE-stick setup drives, but you rarely need it now.
 
 **Keyboard (the C64-specific part — many games NEED it).** Unlike consoles, most
 C64 games (and cracktros) gate gameplay behind a KEYBOARD setup screen — **F1**
@@ -311,7 +318,7 @@ loads games, wrap the `.prg` into a `.d64`: `cart({op:'packDisk', prgPath})`
 
 ## Horizontal scrolling (for side-scrollers)
 
-The `platformer` scaffold is single-screen. C64 scrolling is the fiddliest of
+The `platformer` example is single-screen. C64 scrolling is the fiddliest of
 the platforms because the VIC-II only does a 0-7 px *fine* scroll in hardware;
 moving further is a software char-cell shift.
 

package/src/platforms/c64/TROUBLESHOOTING.md

@@ -83,6 +83,19 @@ KERNAL last selected. Result: ghost input.
 
 **Use port 2 (CIA1_PRA) by default.** All bundled C64 templates do.
 
+## "Player 2 input does nothing"
+
+Both C64 control ports ARE live over MCP, so 2P works — the mapping is just
+non-obvious: **host port 0 → control port 2 ($DC00) = player 1**, **host port 1
+→ control port 1 ($DC01) = player 2** (the universal "port 0 = P1" convention).
+So a 2P game reads P1 from $DC00 and P2 from $DC01, and you drive them with two
+port entries: `input({op:'set', ports:[{up:true},{down:true}]})` moves P1 up,
+P2 down. If P2 seems dead, check you passed a SECOND `ports` entry (not just
+port 0) and that the game actually entered 2P mode (its title pick, e.g. "PORT 1
+FIRE = 2P"). The host enables the VICE userport-adapter mapping + swaps the two
+RetroPad ports under the hood so this convention holds — you don't configure
+anything.
+
 ## "Audio is silent / SID doesn't play"
 
 Three things to check:

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;
@@ -265,9 +280,9 @@ names also resolve (east→A, west→B). So `input({op:'set', a: true})` presses
 expected — unlike the genesis_plus_gx platforms (Genesis/SMS/GG), there's no
 surprise here. (Same for **GBC** — it shares the gambatte core.)
 
-## What `scaffold({op:'project'})` copies into your project
+## What `examples({op:'fork'})` copies into your project
 
-`scaffold({op:'project', platform:"gb"|"gbc", template:...})` writes these files
+`examples({op:'fork', example:"gb/..."|"gbc/...", name, path})` writes these files
 into your project directory. **They're yours** — every byte that compiles
 is in the repo. Edit, fork, replace; nothing is auto-injected at build time.
 
@@ -325,7 +340,7 @@ Most game patterns DON'T need any of this. Try the C path first.
 
 ## Horizontal scrolling (for side-scrollers)
 
-The `platformer` scaffold is single-screen. To make it a side-scroller:
+The `platformer` example is single-screen. To make it a side-scroller:
 
 - **Hardware scroll:** write `SCX` (`$FF43`) each frame = camera X mod 256.
   The BG is a 32×32 tile map (256×256 px) that wraps, so `SCX` alone scrolls

package/src/platforms/gb/TROUBLESHOOTING.md

@@ -166,6 +166,102 @@ 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 example games):
+
+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 example games):
+
+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).
+
+## "My HUD scrolls with the background" / "the window ate the bottom of my screen"
+
+The window layer (WX/WY + LCDC bit 5) is the GB's fixed-HUD mechanism: it has
+no scroll registers, always draws its own map from (0,0) pinned to the screen,
+on top of the BG. Three rules, all demonstrated in the shmup example
+(`examples/gb/templates/shmup.c`, "HARDWARE IDIOM: window-layer HUD"):
+
+- **WX is screen X plus 7.** `WX=7` is the left edge. WX 0-6 produces real
+  DMG pixel-pipeline glitches; WX ≥ 167 pushes the window off-screen.
+- **The window has no height register.** From the first line it covers (WY)
+  it owns EVERY line to the bottom of the frame, full width from WX. That's
+  why GB HUDs live at the BOTTOM of the screen (`WY = 128` → lines 128-143 =
+  HUD, lines 0-127 = scrolling playfield). A top HUD needs a mid-frame
+  STAT/LYC interrupt to turn LCDC bit 5 back off — a different, fragile
+  idiom; don't fall into it by accident by setting WY=0.
+- **Sprites are NOT clipped by the window** — they draw on top of it. Despawn
+  (or Y-clamp) everything before the HUD line, or your enemies fly across
+  the score bar.
+
+Use a separate map for the window (LCDC bit 6 → $9C00) so it doesn't fight
+the BG's $9800 map.
+
+## "Hi-score doesn't persist" / save_ram is empty or all $FF
+
+Battery saves need BOTH halves:
+
+1. **The header must declare a battery cart.** The bundled `gb_crt0.s` emits
+   `$0147 = $03` (MBC1+RAM+BATTERY) and `$0149 = $02` (8 KB) as real bytes,
+   and the build's post-link header fix passes them through. The emulator
+   sizes its SAVE_RAM region from those two bytes — type $00 (ROM-only)
+   means no save_ram region at all, and writes to $A000 go nowhere.
+2. **Cart RAM is gated.** It boots DISABLED; writes are silently discarded
+   until you write `$0A` to $0000-$1FFF (any address there — it's a mapper
+   register, not memory). Write `$00` to the same range after saving
+   (battery hygiene: an enabled RAM bank can corrupt at power-off on real
+   hardware).
+
+Working pattern with magic + checksum (a fresh cart is $FF garbage — never
+trust raw bytes): shmup example, "HARDWARE IDIOM: battery SRAM". Verify
+headlessly: play to a score, force game over, `memory({op:'read',
+region:"save_ram"})` shows the record, and the hi-score still shows on the
+title after a hard reset (power cycle).
+
+## "Boot takes seconds" / a screen repaint visibly stalls the game
+
+The sm83 has no divide instruction. SDCC's software `%` / `/` costs ~700
+cycles per call — one `(r*7+c*5) % 11` in a 32×32 map fill is 2048 calls
+≈ 1.5 MILLION cycles ≈ a 1.5-second frozen boot (measured, not theoretical;
+the shmup example shipped exactly that for an hour). In any per-cell or
+per-frame loop, replace modulo patterns with running counters +
+subtract-on-overflow (see `paint_starfield` in the shmup example) and
+decimal score display with power-of-ten subtraction (`u16_to_tiles` there).
+A single `%` per event — e.g. per enemy spawn — is fine.
+
 ## Debug recipes
 
 A few high-leverage tools you might not know exist:
@@ -205,14 +301,13 @@ Boot order that always works for GBC:
    }
 ```
 
-Cribbed from `examples/gbc/templates/tile_engine.c` — start a fresh
-game from that template with:
+Cribbed from `examples/gbc/templates/tile_engine.c` — fork that
+example into a fresh game with:
 
 ```js
-scaffold({
-  op: 'project',
-  platform: "gbc",
-  template: "tile_engine",
+examples({
+  op: 'fork',
+  example: "gbc/tile_engine",
   name: "mygame",
   path: "/abs/path/to/dir",
 });

package/src/platforms/gb/lib/c/README.md

@@ -1,8 +1,8 @@
 # GB / GBC C runtime + headers
 
 These are the source files that back the GB/GBC C templates. They're
-**not** auto-injected at build time — `scaffold({op:'project', platform:"gb"|"gbc",
-template:"..."})` copies them into your project directory so the
+**not** auto-injected at build time — `examples({op:'fork', example:"gb/<name>" or
+"gbc/<name>", name, path})` copies them into your project directory so the
 project is self-describing. Build calls then point at your project's
 copy of these files via `sourcesPaths` / `includePaths` / `crt0Path`.
 
@@ -32,7 +32,7 @@ didn't produce, or to override a field:
   Fixes up / overrides the header of an existing ROM on disk (title, cart
   type, ROM/RAM size, CGB flag, etc.).
 - `node patch-header.js out.gb` — standalone Node script, copied into
-  every GB project by `scaffold({op:'project'})`. Same logic, no MCP needed.
+  every GB project by `examples({op:'fork'})`. Same logic, no MCP needed.
 - `rgbfix -v -p 0 out.gb` — what the build pipeline runs under the hood;
   RGBDS asm projects can invoke it directly.
 
@@ -46,17 +46,16 @@ didn't produce, or to override a field:
   hardware, OAM DMA timing, joypad layout. Read this before your first
   GB/GBC project.
 
-## Project templates
+## Forking an example
 
-Bootstrap a working game-loop skeleton with `scaffold({op:'project'})`:
+Bootstrap a working game-loop skeleton by forking an example with `examples({op:'fork'})`:
 
 ```js
-scaffold({
-  op:       'project',
-  platform: "gbc",
-  template: "tile_engine",   // or "hello_sprite", or "default"
-  name:     "mygame",
-  path:     "/abs/path",
+examples({
+  op:      'fork',
+  example: "gbc/tile_engine",   // or "gbc/hello_sprite", or "gbc/default"
+  name:    "mygame",
+  path:    "/abs/path",
 })
 ```