romdevtools 0.22.1 → 0.24.0

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -47,6 +47,19 @@ the same wall.
    `s__DATA` for `l__DATA` bytes; bring-your-own crt0 should do the
    same.
 
+6. **Don't poke a hardcoded `$C0xx` WRAM pointer for game state — it
+   overlaps your statics.** SDCC links the C runtime's data + BSS (every
+   `static` global: your PRNG seed, your grids, your scores) at the BOTTOM
+   of WRAM starting `$C000`. A `volatile uint8_t *board = (uint8_t*)0xC000;`
+   then scribbles right over `static uint32_t rng = ...;` et al. Symptom
+   looks exactly like an SDCC *codegen* bug — e.g. a 32-bit xorshift PRNG
+   that "degenerates" so every roll is identical (its seed is being
+   clobbered, not miscompiled). **Use a `static` array and let the linker
+   place it** (`static uint8_t board[78]; board[i]=p;`), or hardcode at
+   `$C200`+ and confirm with the linker map (`build({includeSymbols:true})`
+   → check `s__DATA`/`s__BSS`). Full write-up + repro in
+   `lib/c/SDCC_GOTCHAS.md` § "sm83 codegen traps in plain game logic".
+
 - **Two VRAM banks** (switched via VBK at $FF4F) — bank 0 holds tile
   pattern data, bank 1 holds per-tile BG attributes (palette index,
   H/V flip, priority, tile bank).
@@ -61,6 +74,27 @@ the same wall.
 - **HDMA** ($FF51-$FF55) for fast block transfers during HBlank —
   used for live tile streaming.
 
+## MCP debug & inspection tooling
+
+GBC shares the patched gambatte core with DMG, so **all the live inspectors
+and `gb_*` memory regions documented in the GB MENTAL_MODEL apply unchanged
+here** — `sprites({op:'inspect'})`, `tiles({op:'png'})`, `cpu({op:'read'})`,
+`audioDebug({op:'inspect', chip:'gb'})`, and the `gb_vram` / `gb_oam` / `gb_io`
+/ `gb_hram` / `gb_cpu_regs` regions (same gotcha: it's `gb_vram`, NOT the
+generic `video_ram`). Disassembly routes through the same `-m gbz80` objdump.
+See the GB MENTAL_MODEL for the shared gambatte debug tooling.
+
+CGB-only deltas on top of that shared set:
+
+- **`palette({source:'live'})`** on a CGB ROM decodes the **64-byte BCPS/OCPS
+  palette RAM** into **8 palettes × 4 colors in BGR555** (the DMG path that
+  decodes BGP/OBP0/OBP1 bytes is what runs on a `gb` build instead). The raw
+  CGB palette RAM is also readable directly via the **`gb_bgpdata`** (BG, 64
+  bytes) and **`gb_objpdata`** (OBJ, 64 bytes) memory regions.
+- **`background({view:'renderState'})`** reports the CGB extras the DMG path
+  doesn't have: the current **VRAM bank** (VBK), **KEY1** (double-speed state),
+  and the live **BCPS/OCPS palette index**.
+
 ## CGB vs DMG mode
 
 The CGB boot ROM checks header byte **`$0143`**:

package/src/platforms/gbc/lib/c/SDCC_GOTCHAS.md

@@ -188,3 +188,94 @@ build({
   },
 })
 ```
+
+## sm83 codegen traps in plain game logic (WRAM integer/array code)
+
+Every footgun above is about VRAM / OAM-DMA / the cart header — the stuff
+that makes sprites vanish. This section is the opposite: **plain WRAM game
+logic** — PRNGs, collision grids, score math. Two such "miscompiles" were
+reported from a real GBC Columns build session and chased to ground here.
+**Verdict: neither was an sm83 codegen bug.** They are documented so you
+don't burn hours blaming the compiler for what is actually a memory-layout
+or static-init trap.
+
+### NOT a bug: 32-bit math / `uint32_t` shifts ≥ 16
+
+Reported: *"`static uint32_t rng=0x1357; rng ^= rng<<13; rng ^= rng>>17;
+rng ^= rng<<5;` degenerates — every `1+xorshift()%6` roll comes out the
+same (near-monochrome)."*
+
+**Reproduced on sm83: it does NOT degenerate.** A ROM that seeds the PRNG,
+calls `xorshift()` 20×, and writes `1 + (result % 6)` to WRAM reads back a
+fully-varied `5,5,5,1,5,5,4,1,3,2,1,...` — the exact sequence a reference
+implementation produces. Full 32-bit fidelity was confirmed byte-for-byte
+across several seeds (`0xDEADBEEF`, `0x00000001`, …). The `<<13` / `>>17` /
+`<<5` shifts (including the ≥16-bit right shift) and `% 6` are all correct.
+**Do not rewrite a working 32-bit xorshift into 16-bit to "dodge" this.**
+32-bit ops are bigger/slower than 16-bit on an 8-bit CPU, so prefer 16-bit
+PRNGs for *speed* — but not for correctness; both are correct.
+
+### The REAL trap behind "monochrome RNG": writing game state to a fixed
+`0xC0xx` WRAM address that overlaps your statics
+
+This is what actually produces the reported symptom. SDCC links the C
+runtime's `_DATA` / `_INITIALIZED` segment (every value-initialised
+`static`, e.g. `static uint32_t rng = 0x1357;`) **at the very bottom of
+WRAM, starting `$C000`**, with `_BSS` (zero-init statics like
+`static uint8_t grid[78];`) right after it. If your code also pokes a
+**hardcoded** `$C000`-area pointer for game state —
+
+```c
+volatile uint8_t *board = (volatile uint8_t *)0xC000;   /* DON'T */
+board[i] = piece;                 /* clobbers `rng` and friends! */
+```
+
+— you are scribbling directly over your own statics. Then `xorshift()`
+reads a trashed `rng`, the PRNG collapses, and every roll looks the same.
+It presents *exactly* like a compiler bug; it is not.
+
+**Fixes (any one):**
+- **Best — let the linker place it.** Use a `static` array and take its
+  address; never hardcode a WRAM pointer:
+  `static uint8_t board[6*13]; ... board[i] = piece;`
+- If you *must* use a fixed address, put it well clear of the runtime data:
+  `$C200`+ is safe for small projects (statics here end far below `$C100`;
+  `shadow_oam` is pinned at `$C100`). Confirm with the linker map — build
+  with `includeSymbols:true` and look at `s__DATA` / `s__BSS` (e.g.
+  `s__DATA = $C000`, `s__BSS = $C006`): your scratch RAM must start ABOVE
+  the end of `_BSS`.
+- **Diagnose it in seconds:** read `system_ram` offset 0 right after boot
+  and compare against your initialised statics' expected bytes. If a
+  `static uint32_t x = 0x1357;` doesn't read back `57 13 00 00` at its map
+  address, something is overwriting it.
+
+### NOT a bug: short `for` loop with an indexed `static` array read
+
+Reported: *"`for(i=0;i<3;i++){ if(grid[r*6+col]) return 1; }` reads the
+wrong cells (pieces lock mid-air / floating gaps); unrolling the 3
+iterations fixed it."*
+
+**Reproduced on sm83: the looped form reads the CORRECT cells.** A ROM that
+seeds `grid[]` with a sparse occupied/empty pattern and runs `collides()`
+both looped and hand-unrolled, for 8 straddling `(col,topy)` inputs, gets
+**identical, correct** results from both forms (`1,0,1,0,1,1,1,1`). The
+`grid[r*6+col]` index math and the 3-iteration loop are fine. If your real
+collision check "floats," look first at the WRAM-collision trap above (a
+clobbered `grid[]`), at off-by-one row/col limits, or at signed/unsigned
+mix-ups — not at loop codegen. **Don't pre-emptively unroll loops as a
+compiler workaround; with the stack-overflow fix in place, sm83 loops with
+indexed array reads are reliable.**
+
+### z80 (SMS/GG) ONLY — fixed: value-initialised statics booted as 0
+
+Investigating the above on the **z80** port (SMS/GG share the SDCC family)
+surfaced a real bug — but a **crt0** bug, not codegen. The bundled
+`sms_crt0.s` / `gg_crt0.s` placed `_INITIALIZER` (the ROM image of
+value-initialised statics) *after* the `_DATA` RAM block in the area list,
+so sdld put it in RAM; the gsinit `ldir` then copied uninitialised RAM onto
+itself and **every `static uint8_t x = 5;` booted as 0** (and BSS wasn't
+zeroed either). On z80 *this* is what made the xorshift PRNG monochrome
+(seed `rng` booted 0 → stayed 0). Fixed 2026-06-08 by ROM-placing
+`_INITIALIZER` + adding a `_DATA` zero loop, mirroring this sm83 crt0 (which
+was already correct — hence sm83 was never affected). If you bring your own
+z80 crt0, model gsinit on `gb_crt0.s`.

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -161,6 +161,167 @@ while (1) {
 your sprite updates never appear on screen. It's the single most
 important call in any SGDK game loop.
 
+## Scrolling, parallax & the feel trap ⭐
+
+This is the section to read before you build a side-scroller. The #1
+"my horizontal movement feels choppy/juddery" bug on Genesis is a
+software mistake, not a hardware limit:
+
+> ### ⚠️ DO NOT rewrite full tilemaps in the frame loop.
+> The Genesis scrolls in HARDWARE. Moving the world is **two register
+> writes** (`VDP_setHorizontalScroll`), which are free. If instead you
+> redraw the plane each frame (a big `VDP_setTileMapXY`/`VDP_loadTileMap`
+> burst or a per-frame DMA), you overrun vblank, drop frames, and the
+> scroll judders. **Paint the planes ONCE at setup; the loop only nudges
+> scroll registers and re-stages sprites.** Use the
+> `template:"two_plane_parallax"` scaffold as the known-good shape.
+
+### Hardware scroll, the whole loop
+
+A two-plane parallax scroller's *entire* per-frame render cost is:
+
+```c
+VDP_setHorizontalScroll(BG_A, -camX);        // foreground: 1:1 with world
+VDP_setHorizontalScroll(BG_B, -(camX >> 4)); // background: 1/16 speed = far depth
+/* ...stage sprites in SCREEN space... */
+VDP_setSprite(0, playerScreenX, playerY, SPRITE_SIZE(2,2), attr);
+VDP_updateSprites(1, DMA);                    // flush the SAT
+SYS_doVBlankProcess();                        // flush DMA queue, sync vblank
+```
+
+No `VDP_setTileMapXY` / `VDP_fillTileMapRect` / `VDP_loadTileMap` in the
+loop. Those are SETUP calls (and tiny one-off updates — a coin that
+vanishes, a door that opens). They are NOT for whole-plane runtime
+redraws. Positive `camX` scrolls the plane LEFT, so you write the
+NEGATIVE camera offset. `VDP_setVerticalScroll` is the vertical twin
+(it writes VSRAM — see `genesis_vsram`).
+
+### Logical plane size vs HARDWARE plane size
+
+A common confusion: **the Genesis has ONE shared plane-size setting for
+BOTH planes A and B** (VDP regs 16). You pick 32×32 / 64×32 / 32×64 /
+64×64 *cells* once; you do NOT get an independent size per plane. So a
+"32-cell-wide level" still lives inside a 64-cell **physical** plane if
+that's the hardware size you set — the extra cells are just offscreen
+buffer. The scroll value wraps within the physical plane
+(64 cells = 512 px), which is exactly what makes a fully-painted plane
+tile forever with no redraw. Don't fight this: pick a hardware plane
+size and treat your logical world coords separately.
+
+| Plane size (cells) | Pixels   | Use                                  |
+|--------------------|----------|--------------------------------------|
+| 32×32              | 256×256  | single-screen / small wrap           |
+| **64×32** (default)| 512×256  | horizontal scroller (one plane wide) |
+| 32×64              | 256×512  | vertical scroller                    |
+| 64×64              | 512×512  | uses the most VRAM for name tables   |
+
+### How Sonic-style large maps REALLY work (wider than one plane)
+
+You do NOT make the plane "as wide as the level," and you do NOT redraw
+the plane. The 64-cell hardware plane is a **circular buffer**: as the
+camera advances, the column scrolling OFF the left re-appears on the
+right (the scroll wraps mod 512 px). You keep the visible window full by
+updating exactly **ONE offscreen column** each time the camera crosses
+an 8-px tile boundary:
+
+```c
+// camX in pixels; world is an array wider than 512 px.
+s16 newTileCol = camX >> 3;
+if (newTileCol != lastTileCol) {
+    // the column about to enter view on the right edge:
+    s16 worldCol  = (camX + SCREEN_W) >> 3;
+    s16 planeCol  = worldCol & 63;          // wrap into the 64-cell plane
+    drawWorldColumn(planeCol, worldCol);    // ONE column, ~28 cells — tiny
+    lastTileCol = newTileCol;
+}
+```
+
+That's ~28 tile writes per 8 px of travel, not a 1792-cell plane redraw.
+The `template:"platformer"` scaffold scrolls within one plane (no
+streaming); add the column-stream above to go wider. (Real Sonic also
+splits the screen with H-blank raster effects for independent strips —
+that's an IRQ/raster topic, see the `asm` template.)
+
+## Why does horizontal movement feel choppy? — motion-trace it headlessly ⭐
+
+When movement feels off, don't trial-and-error with screenshots. Sample
+the player's world-X, the camera scroll, and the actual VDP scroll
+values over ~180 frames while holding a direction, and read the curve.
+Two signatures to look for:
+
+1. **Camera scroll changes while the sprite's screen-X barely moves**
+   (or vice-versa) → your camera-follow math is off; the world slides
+   under a frozen-looking player, or the player slides on a frozen world.
+2. **Scroll JUMPS** (non-monotone, big steps) → you're scrolling by a
+   non-constant amount per frame (variable-rate camera, or you only
+   update scroll on a tile boundary instead of every frame).
+
+The exact call — hold RIGHT, sample player-X + both planes' HSCROLL +
+VSRAM over 180 frames. Expose the player/camera vars as `volatile`
+globals so they resolve (see "Reading your C globals headlessly"); the
+HSCROLL table lives in VRAM (`video_ram`), default base **$F000**
+(`frame({op:'verify'})`'s render summary prints "H-scroll table: $Fxxx"):
+
+```js
+b   = build({output:'romWithDebug', platform:'genesis', source, inline:true,
+             resolveSymbols:['g_player_x','g_cam_x']})
+// → resolvedSymbols.g_player_x.ramOffset (system_ram offset)
+recordSession({
+  frames:180, sampleEvery:10, includeScreenshots:false,
+  holdInputs:[{right:true}],
+  memorySamples:[
+    {label:'player_x', region:'system_ram', offset: PLAYER_X_OFF, length:2},
+    {label:'cam_x',    region:'system_ram', offset: CAM_X_OFF,    length:2},
+    {label:'hscrollA', region:'video_ram',  offset:0xF000,        length:2},
+    {label:'hscrollB', region:'video_ram',  offset:0xF002,        length:2},
+    {label:'vsram',    region:'genesis_vsram', offset:0,          length:4},
+  ],
+})
+```
+
+Read the columns: `player_x` should ramp smoothly; `hscrollA` should
+move 1:1 with the camera and `hscrollB` at the parallax ratio; both
+should be **monotone** (no jumps) while RIGHT is held. ⚠ Genesis WRAM +
+VRAM read **word-byte-swapped** in gpgx (a 16-bit `0x00F0` reads as
+bytes `F0 00`) — account for the swap, or read single bytes. For a
+compact value-vs-frame curve of just the HSCROLL table use
+`watch({on:'mem', region:'video_ram', offset:0xF000, length:4,
+format:'series', pressDuring:[{frame:0, button:'right', holdFrames:180}]})`.
+
+## Is the loop doing too much VDP work? — per-frame DMA budget ⭐
+
+The render-side cause of choppy scroll is **too many VDP/DMA bytes per
+frame** (a tilemap rewrite, an asset re-upload). Measure it directly,
+no core rebuild:
+
+```js
+watch({on:'dma', perFrame:true, frames:120,
+       pressDuring:[{frame:0, button:'right', holdFrames:120}]})
+```
+
+returns a per-frame timeline `[{frame, dmas, bytes, romBytes, ramBytes}]`
+plus `avgBytesPerFrame`, `peakFrame`/`peakBytes`, and `spikes`.
+
+- A **smooth hardware-scroll loop** shows a LOW, FLAT curve — after boot
+  it's mostly the steady SAT/scroll refresh (`ramBytes`, single/low
+  double digits per frame).
+- A **`spikes` entry** (bytes ≫ average, especially `romBytes` — an
+  asset upload FROM cart ROM) is the "I rewrote a tilemap / re-uploaded
+  tiles in the frame loop" smell. Move that work to setup, or stream
+  ONE column per 8-px scroll step (above).
+
+**CEILING / what this does NOT catch:** this counts mem→VDP **DMA**
+bytes (the dominant cost). Plain CPU writes to the VDP data port —
+`VDP_setTileMapXY` without DMA, single-cell pokes — are not DMA and are
+NOT counted; catching *those* would need a core-side VDP-data-port write
+hook (a gpgx patch, not shipped). In practice the expensive per-frame
+mistakes (whole-plane fills, `VDP_loadTileMap`, big `DMA_*` transfers)
+ALL go through DMA and DO show up here, so the budget is a reliable
+choppiness diagnostic today. There is no exposed per-frame
+"vblank-cycles-used / overrun" counter either — infer overrun from the
+byte budget (DMA bandwidth in vblank is finite: ~7.6 KB to VRAM in PAL
+vblank, less in NTSC; a frame moving multiple KB to VRAM is at risk).
+
 ## Input
 
 `u16 pad = JOY_readJoypad(JOY_1)` returns a packed bitmask. The
@@ -252,6 +413,25 @@ headless per-PCM-channel "is it playing" readout for Genesis yet (it would need
 core patch to expose the XGM2 Z80 driver state), so audio verification here is
 record-and-listen, not assert.
 
+## MCP debug & inspection tooling
+
+The shipped genesis_plus_gx (gpgx) core is patched for live introspection.
+Video is deeply readable; the FM audio chip is only partially exposed:
+
+- **Sprites:** `sprites({op:'inspect'})` decodes the live SAT.
+- **Palette:** `palette({source:'live'})` reads live CRAM.
+- **CPU:** `cpu({op:'read', cpu:'main'})` reads the 68000.
+- **Audio (limited):** `getYm2612State` returns the YM2612's internal
+  struct as a raw blob — gpgx doesn't expose it in a safely per-channel
+  decodable form (good for frame-to-frame diffing, see "Debugging sound").
+  `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
+  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").
+
 ## ROM layout
 
 ```

package/src/platforms/genesis/TROUBLESHOOTING.md

@@ -230,3 +230,35 @@ pixels per byte). The shipped `hello_sprite`, `tile_engine`, `shmup`,
 `platformer`, `puzzle` templates use this approach. **But never
 hand-encode a full-screen image this way** — that's the red/choppy
 failure above.
+
+## "Horizontal movement / scrolling feels choppy or judders"
+
+Almost always: **you're rewriting the tilemap in the frame loop.** The
+Genesis scrolls in HARDWARE — moving the world is two register writes
+(`VDP_setHorizontalScroll`), which cost nothing. If you instead redraw a
+plane every frame (a `VDP_fillTileMapRect` / `VDP_loadTileMap` / big
+`DMA_*` each frame), you overrun the vblank DMA budget and drop frames →
+judder. Fix: paint the planes ONCE at setup; the loop only nudges scroll
+registers + re-stages sprites. The `template:"two_plane_parallax"`
+scaffold is the known-good shape.
+
+Diagnose it without guessing (no core rebuild):
+
+- **Per-frame VDP work:** `watch({on:'dma', perFrame:true, frames:120,
+  pressDuring:[{frame:0, button:'right', holdFrames:120}]})` → a per-frame
+  `[{frame, bytes, romBytes, ramBytes}]` timeline + `spikes`. A smooth
+  loop is a LOW, FLAT curve (just the SAT/scroll refresh). A `spikes`
+  entry (bytes ≫ avg, esp. `romBytes`) IS the per-frame asset-upload /
+  tilemap-rewrite mistake. (Counts DMA bytes only — non-DMA single-cell
+  `VDP_setTileMapXY` pokes aren't counted; the expensive whole-plane work
+  always uses DMA and does show.)
+- **Motion curve:** sample the player-X + both planes' HSCROLL ($F000 in
+  `video_ram`) over 180 frames while holding a direction — see
+  MENTAL_MODEL.md "Why does horizontal movement feel choppy?". Look for
+  scroll that jumps (non-constant per-frame delta) or a camera that moves
+  while the sprite's screen-X is frozen.
+
+For a world WIDER than one 512-px plane, don't make the plane bigger and
+don't redraw it — stream ONE offscreen column per 8-px camera step
+(circular-buffer the 64-cell plane). See MENTAL_MODEL.md "How Sonic-style
+large maps REALLY work".

package/src/platforms/gg/MENTAL_MODEL.md

@@ -160,6 +160,30 @@ void main(void) {
 }
 ```
 
+## MCP debug & inspection tooling
+
+Game Gear runs on the same genesis_plus_gx (gpgx, patched) core as SMS, so the
+inspectors are identical. **The canonical reference lives in the SMS
+MENTAL_MODEL** (`src/platforms/sms/MENTAL_MODEL.md`, "MCP debug & inspection
+tooling" section): `sprites({op:'inspect'})`, `tiles({op:'png'})`,
+`cpu({op:'read'})` (Z80), `background({view:'renderState'})`,
+`audioDebug({op:'inspect', chip:'psg'})` (SN76489, the shared
+SMS/GG/Genesis region), and the z80 `objdump` disasm pipeline all apply
+unchanged.
+
+Game-Gear-only deltas:
+
+- **`palette({source:'live'})`** decodes **12-bit BGR (4-4-4)**, twice the
+  depth of SMS's 6-bit. CRAM is **64 bytes** (2 little-endian bytes per
+  entry) instead of 32.
+- The Game-Gear memory regions are **`gg_vram`** and **`gg_cram`** (the
+  64-byte palette); use these instead of `sms_vram` / `sms_cram`. The
+  `sms_vdp_regs` / `sms_z80_regs` register regions are shared (same VDP and
+  Z80).
+- `sprites({op:'inspect'})` X/Y fields are reported in **256×192 hardware
+  coordinates**, not the 160×144 visible window — match them with
+  hardware-coord arithmetic (see "Sprite coords are hardware-space" above).
+
 ## Differences from SMS — quick reference
 
 - Visible 160×144 vs 256×192 — center content

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

@@ -31,6 +31,8 @@
         .globl  l__INITIALIZER
         .globl  s__INITIALIZER
         .globl  s__INITIALIZED
+        .globl  s__DATA
+        .globl  l__DATA
 
 ;; ─── Reset vector at $0000 ────────────────────────────────────────
         .area _HEADER (ABS)
@@ -83,7 +85,15 @@
 ;; call main. The initializer area is filled by sdcc when it sees
 ;; global initializations.
 
+        ;; AREA ORDERING IS LOad-BEARING. `_INITIALIZER` (the ROM image of
+        ;; every value-initialised `static` global) MUST be declared in the
+        ;; ROM group here — BEFORE the `_DATA` RAM block. If it isn't, sdld
+        ;; places `_INITIALIZER` in RAM right after `_INITIALIZED`, so the
+        ;; gsinit copy below copies uninitialised RAM onto itself and every
+        ;; `static uint8_t x = 5;` boots as 0. (Bug found 2026-06-08; see the
+        ;; matching note in sms_crt0.s — both z80 crt0s were missing this.)
         .area   _HOME
+        .area   _INITIALIZER
         .area   _CODE
         .area   _GSINIT
         .area   _GSFINAL
@@ -97,6 +107,26 @@
         .area   _CODE
 
 gsinit:
+        ;; ── Zero the BSS segment (`_DATA`). ──────────────────────────
+        ;; Every uninitialised `static` global lands in `_DATA` and MUST
+        ;; read back 0 at boot. Mirrors the sm83 GB crt0's gsinit_data loop.
+        ld      bc, #l__DATA
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_bss_done
+        ld      hl, #s__DATA
+        ld      (hl), #0x00
+        ld      d, h
+        ld      e, l
+        inc     de
+        dec     bc
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_bss_done
+        ldir                            ; propagate the 0 across _DATA
+gsinit_bss_done:
+
+        ;; ── Copy `_INITIALIZER` (ROM) → `_INITIALIZED` (RAM). ────────
         ld      bc, #l__INITIALIZER
         ld      a, b
         or      a, c

package/src/platforms/lynx/MENTAL_MODEL.md

@@ -35,13 +35,39 @@ Mikey handles:
 - **Joystick** — read via SWITCHES register at `$FCB0`. cc65 provides
   `joy_read(JOY_1)` + `JOY_LEFT/RIGHT/UP/DOWN/BTN_1/BTN_2` macros.
 
-**Live debug:** `audioDebug({op:'inspect', chip:"mikey"})` decodes the 4 audio voices
-(volume, period→freq→note, LFSR state); `palette({source:'live'})` reads the 16-entry
-palette; `background({view:'renderState'})` shows DISPCTL + the display base address;
-`cpu({op:'read'})` reads the 65C02; `breakpoint({on:'write'})` is the write watchpoint. **Sprites
-are the exception** — the Lynx has no fixed OAM (sprites are SCB linked lists
-walked by Suzy), so `sprites({op:'inspect'})` returns the SCB list head ($FC10/$FC11) and
-you walk the chain over `system_ram`, rather than reading a sprite table.
+**Live debug:** the MCP inspectors (`palette` / `cpu` / `audioDebug` /
+`background` / `breakpoint`, and the SCB-list-head `sprites` special case) are
+documented in "MCP debug & inspection tooling" below.
+
+## MCP debug & inspection tooling
+
+The Lynx runs on handy (patched). The inspectors read the *live* core state —
+reach for them when a sprite or palette renders wrong and the source alone
+doesn't explain it. Details and the per-tool facts:
+
+- **`palette({source:'live'})`** — the **16-entry, 12-bit RGB** Mikey palette
+  (`$FDA0-$FDBF`) converted to RGB.
+- **`cpu({op:'read'})`** — 65C02 dump: A / X / Y / P / SP / PC plus the
+  decoded flag bits.
+- **`audioDebug({op:'inspect', chip:'mikey'})`** — the 4 Mikey voices: volume,
+  the timer→period→frequency→note chain, and the **12-bit LFSR** state.
+- **`background({view:'renderState'})`** — decodes DISPCTL: the DMA-enable,
+  flip, and color-mode bits plus the display base address.
+- **`sprites({op:'inspect'})` is the special case.** The Lynx has **no fixed
+  OAM** — sprites are **SCB (Sprite Control Block) linked lists in RAM** that
+  Suzy walks at blit time. So this tool can't return a sprite table; instead
+  it returns the **SCB list head (SCBNEXT, `$FC10`/`$FC11`)** plus
+  instructions to walk the chain yourself over `system_ram`.
+
+### Memory regions (`memory({op:'read', region:…})`)
+
+| Region          | Address / size        | Contents                                              |
+|-----------------|-----------------------|-------------------------------------------------------|
+| `lynx_cpu_regs` | —                     | 65C02 register snapshot                               |
+| `lynx_hw_regs`  | $FC00-$FDFF window     | the **Suzy + Mikey** register window — sprite-engine regs, LCD control, audio, palette |
+| `system_ram`    | 64 KB                 | full address space (also where the SCB chain lives)   |
+
+Pair these with `breakpoint({on:'write'})` for the full live-debug loop.
 
 ## Frame heartbeat (cc65 + tgi)
 

package/src/platforms/msx/MENTAL_MODEL.md

@@ -117,3 +117,30 @@ exactly this.
   generator + the envelope (period + shape bits).
 - `memory({op:'read'})` regions: `msx_vram`, `msx_vdp_regs`, `msx_vdp_status`,
   `msx_palette`, `msx_cpu_regs`, `msx_psg_regs`, plus `system_ram` (work RAM).
+
+## MCP debug & inspection tooling
+
+MSX is a **Tier-1** platform with deep introspection — the full set of
+inspectors and memory regions is listed under **"Debugging tools"** above
+(`cpu` / `background` / `palette` / `sprites` / `symbols` / `audioDebug` for
+the AY-3-8910 PSG, and the `msx_vram` / `msx_vdp_regs` / `msx_vdp_status` /
+`msx_palette` / `msx_cpu_regs` / `msx_psg_regs` / `system_ram` regions). The
+PSG-channel decode means `audioDebug({op:'inspect', chip:'ay8910'})` gives
+you the 3 square-wave channels plus the shared noise generator and envelope
+without poking at `msx_psg_regs` by hand.
+
+### ColecoVision shares this core family — but is bring-up only
+
+ColecoVision runs the same toolchain family and exposes only the **standard**
+introspection: `system_ram` + `save_ram` + `video_ram`. It has **no deep
+inspectors** (no `palette` / `sprites` / `background` / `audioDebug` decode)
+and **no MENTAL_MODEL of its own** — treat it as a bring-up target, not a
+finished Tier-1 platform.
+
+### Extending introspection (for whoever adds a platform)
+
+Deeper, decoded inspectors are not free — each is implemented by **patching
+the emulator core** to expose the extra register/VRAM regions, then wiring a
+decoder. To add deep introspection to ColecoVision (or any thin platform),
+follow the existing core-patch pattern used for snes9x / gpgx / fceumm / vice
+under **`scripts/patches/`**.

package/src/platforms/nes/MENTAL_MODEL.md

@@ -25,6 +25,13 @@ The cc65 runtime claims:
 - ZP $1C+ available to your game (with our chr-ram crt0)
 - `$0500-$07FF` (3 pages): cc65 C parameter stack
 
+> **cc65 zero-page starts at $02, not $00 (applies to every cc65 platform —
+> NES, C64, Atari, Lynx, …).** cc65 reserves `$00-$01` for its runtime, so your
+> first `.res 1` in the `ZEROPAGE` segment lands at **$02**, not $00. If you
+> hand-write asm that assumes a zero-page var is at $00 you'll clobber the
+> runtime. Confirm actual addresses with `symbols({op:'map'})` after
+> `build({output:'romWithDebug'})`.
+
 ## PPU memory map (separate from CPU bus!)
 
 ```
@@ -94,6 +101,15 @@ The `nes_runtime` helper `tile_set_palette(nt, x, y, palette)` does
 the read-modify-write dance and the bit-twiddling — use it instead
 of writing attributes by hand.
 
+> **256-tile cap per pattern table (the busy-image trap).** The nametable's
+> tile index is 8-bit, so a single pattern table holds at most **256 unique
+> tiles** — and a per-frame BG can therefore use at most 256 distinct tiles.
+> Auto-converting a busy full-screen illustration almost always needs more than
+> 256 unique 8×8 tiles and **overflows**; `encodeArt({stage:'tilemap'})` warns
+> when it does. The only real workaround is mid-frame CHR bank switching
+> (an MMC3-class mapper) — the bundled NROM presets can't do it, so design BG
+> art to reuse tiles (≤256 unique per table).
+
 ## Palettes
 
 32 bytes at $3F00-$3F1F:
@@ -329,6 +345,25 @@ incorrectly aligned."
   scrolling worlds you need to manage the nametable buffer + bank
   switching yourself.
 
+## MCP debug & inspection tooling
+
+The shipped fceumm core is patched for live introspection — read state
+instead of guessing:
+
+- **Sprites:** `sprites({op:'inspect'})` decodes live OAM.
+- **Palette:** `palette({source:'live'})` reads the live 32-byte palette RAM.
+- **CPU:** `cpu({op:'read'})` reads the 6502.
+- **Background render state:** `background({view:'renderState'})` decodes
+  PPUCTRL/PPUMASK and resolves the active CHR bank (plus its file offset) —
+  this is what tells you which pattern table BG vs sprites are fetching from
+  (the bit-4 footgun above).
+- **Memory regions:** `memory({op:'read'})` exposes OAM, Palette,
+  Nametables (CIRAM — including the 2-bit-per-16x16 attribute data that
+  selects each tile group's sub-palette, decoded by `inspectBackgroundMap`),
+  CHR (live MMC1-banked CHR — don't parse the iNES file), CPU_REGS,
+  PPU_REGS, and APU_REGS (the synthesized $4000-$4017 snapshot consumed by
+  `audioDebug`).
+
 ## Rebuilding a CHR-ROM NROM image (reverse-engineering)
 
 The homebrew presets above are CHR-**RAM** (the CPU uploads tiles at runtime).