romdevtools 0.29.0 → 0.40.0

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -18,6 +18,10 @@ read that platform's `platform({op:'doc', platform, name:'mental_model'})`.
    loose name (fuzzy) before assuming it's absent. Cheats are a STARTING point,
    not the whole job — combine with disassembly below.
 3. `symbols({op:'map', platform})` / the platform MENTAL_MODEL for the layout.
+4. `symbols({op:'analyze', romPath})` — for an unknown ROM with no cheats and no
+   debug file, this carves the structure (functions + strings + entrypoints) in
+   one call. The static map you hang everything else onto (see §5f for the full
+   Rizin/Ghidra analysis loop — cfg, xrefs, decompile).
 
 The cheat DB is bundled (`romdev_game_codes`). Do **not** scan the user's disk for
 `.cht` files — if it's not in the bundled DB, treat it as absent and RE it.
@@ -65,6 +69,14 @@ thousands of bytes and you'll drown).
 
 This is the Cheat-Engine/RetroArch loop. It is THE bread-and-butter primitive.
 
+**Don't know the value? (lives/timer/ammo not on the HUD)** Use the
+unknown-initial-value hunt: `memory({op:'searchUnknown', region, size})` seeds
+the WHOLE region with no value, then narrow across events with
+`searchNext({compare:'dec'|'inc'|'unchanged'|'changed'|'gt'|'lt'})` — e.g.
+`searchUnknown` → lose a life → `searchNext({compare:'dec'})` → repeat until 1–2
+remain. `op:'search'` needs a value; `op:'searchUnknown'` is for when you can't
+see the number.
+
 **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
@@ -78,7 +90,13 @@ not for value hunting. `memory({op:'diff'})` defaults to a **clustered summary**
 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. Small clusters (≤8 bytes) carry
 `before`/`after` hex inline, and `minDelta:N` drops |after−before| < N so RNG/counter
-wiggle disappears from the report.
+wiggle disappears from the report. For the locate-value-via-diff case, predicate
+filters cut a 500-byte death-window diff to the ~3 rows you want in one call:
+`changeDir:'dec'|'inc'` (direction), `deltaEq:N` (signed exact delta — `deltaEq:-1`
+= "lost one life"), and `beforeMin/Max` + `afterMin/Max` (value-range gates, e.g.
+`beforeMax:9` = a small counter, not a coordinate). `outputPath` writes the full
+diff JSON to your path regardless of size (`echo:false` returns just the
+counts+path so a big diff never streams through context).
 
 **"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
@@ -96,7 +114,7 @@ The #1 trap: visible names/labels are often **pre-rendered tile GRAPHICS**, not
 font-rendered from an ASCII string. Patching the ASCII string then does nothing.
 
 1. `text({op:'learn'})` on the on-screen text — it infers the game's char→tile-ID map
-   (games use their own encoding: Excitebike A=$0A, Mario ASCII-offset, FF sparse). Two
+   (games use their own encoding: e.g. one NES racer maps A=$0A, another uses an ASCII offset, a third a sparse table). Two
    modes: ROM mode `knownStrings:[{text, offset}]` when you found the bytes; **LIVE mode
    `fromScreen:[{text, row, col}]`** reads the tile IDs straight off the live BG map at a
    tile position (`background({view:'map'})` shows where the text sits) — this breaks the
@@ -136,8 +154,11 @@ a string — find a terminator / font map before treating the bytes as values.
 platforms (Genesis/Mega Drive, GB/GBC, SMS/GG, PCE, Lynx) the **file offset IS
 the CPU ROM address** — `memory({op:'readCart', offset:0x21FF00})` answers "does the
 running ROM have my bytes at 0x21FF00?" in one call. (NES/SNES: bytes are
-correct but mapper-banked — `mapped:true` in the response; map a CPU PC→offset
-via `breakpoint({on:'write'})`'s prgOffset/bank.)
+correct but mapper-banked — `mapped:true` in the response.) For a BANKED CPU
+address, read it directly: `memory({op:'readCart', cpuAddress:0x8654, bank:6})`
+maps the bank→PRG offset for you (NES/SNES) — the inverse of the breakpoint
+result's bank/prgOffset, so you stop hand-computing `cpuAddr−0x8000+bank*0x4000`.
+A NES `$C000+` address resolves to the fixed top bank automatically.
 
 When a write "doesn't show up", check the ROM here before assuming the patch
 failed — it's usually live and the bug is elsewhere (wrong source, see §2/§5).
@@ -170,6 +191,18 @@ can pass `{startAddress, bank}` to `disasm({target:'rom'})`. The lighter
 and returns a frame-boundary PC — a lead, not a guarantee under interrupts; use it for the
 value timeline or when you just want the change history, and cross-check the value trace.
 
+**Stop on the MEANINGFUL write, not the churn.** `breakpoint({on:'write'})` runs
+to END OF FRAME and reports the LAST matching write that frame (with `hits` =
+the count of all matching writes) — so a frequent **restoring** write (a pointer-
+arithmetic `inc`/`dec` that touches the byte every frame, a re-arm) can mask the
+write you actually want. Filter to the real change with `condition` (all 14
+platforms): `condition:'decrease'` / `'increase'` stop only when the stored byte
+actually went down/up (a real lives−1, not a restore), and `condition:'equals',
+conditionValue:N` stops on the byte becoming N (e.g. a $00→$01 respawn re-arm).
+The hit then reports `oldValueByte`→`valueByte` so you see the exact transition.
+This is the difference between pinning a genuine decrement instantly and chasing
+net-zero restoring churn.
+
 ---
 
 ## 5b. To READ a register at an instruction — execution breakpoints (all 14)
@@ -281,6 +314,40 @@ Breakpoints are great once you KNOW the address. To FIND it:
 
 ---
 
+## 5f. Carve the program STRUCTURE before you label it — the RE engine (all 14)
+
+The watch/breakpoint tools above find routines *dynamically* (run the game, see
+what touches an address). The **Rizin/Ghidra analysis engine** carves the program
+*statically* — the map you label the dynamic findings onto. All 14 platforms.
+
+- **`symbols({op:'analyze', romPath})`** — one call, the whole shape: auto-detected
+  functions + strings + entrypoints. Start here on an unknown ROM.
+- **`disasm({target:'functions', path})`** — the function list with sizes,
+  basic-block counts, and caller/callee counts. The most-called functions are
+  usually the engine primitives (read-joypad, draw-tile, RNG).
+- **`disasm({target:'cfg', path, address})`** — the basic-block control-flow graph
+  of one function (nodes + typed branch edges). "Is this a loop? where does it
+  bail?" without reading the whole disassembly.
+- **`disasm({target:'xrefs', path, address})`** — every cross-reference TO an
+  address, following the analysis graph. DEEPER than `target:'references'` (a flat
+  operand scan): once a function pass has run, `xrefs` resolves calls the flat
+  scan misses. Use it to answer "what calls this routine / reads this table?"
+- **`disasm({target:'decompile', path, address})`** — Ghidra **C-like pseudocode**
+  for a function. Read it to UNDERSTAND a routine fast; it is NOT the edit path
+  (use `target:'project'`, §7b, to change and rebuild). Quality tracks the CPU —
+  see the `qualityNote` it returns: excellent on ARM (GBA) / 68000 (Genesis),
+  good on SM83 (GB) / Z80 (SMS/GG/MSX), medium on 65816 (SNES) / HuC6280 (PCE),
+  rough on the 6502 family (carry-flag idioms and 16-bit-math-on-8-bit decompile
+  to noise — read the disassembly there, or let an LLM fold the pseudocode).
+
+**The loop:** `symbols({op:'analyze'})` or `disasm({target:'functions'})` to carve →
+`disasm({target:'cfg'/'xrefs'/'decompile'})` to understand a candidate → then the
+dynamic tools (memory search, `breakpoint({on:'write'})`, `watch`) to CONFIRM and
+label which carved function owns the value you care about. Static narrows the
+search space; dynamic proves it.
+
+---
+
 ## 6. Driving menus (the real wall-clock sink)
 
 Use `input({op:'navigate', steps:[{button, maxWaitFrames}]})` — it advances on **screen
@@ -368,7 +435,11 @@ watch the screen react — cheaper than shipping a wrong ROM patch.
 ## 7b. Whole-ROM rebuildable disassembly — `disasm({target:'project'})`
 
 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
+re-buildable project in one call: `disasm({target:'project', path, outputDir})`.
+(To UNDERSTAND a routine before you edit it, read its `disasm({target:'decompile'})`
+pseudocode or `disasm({target:'cfg'})` graph first — §5f. `project` is the *edit*
+path; decompile is the *understanding* path. They pair: read the C, edit the asm.)
+It splits
 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
@@ -467,7 +538,10 @@ For sprite/tile edits (not text), don't hand-roll the tile-format math:
 | Find / encode a font-rendered string | `text({op:'find'})` → `text({op:'encode'})` |
 | Assemble asm → raw patch bytes | `assembleSnippet({cpu, origin, code})` |
 | Mapper-aware diff of two ROMs | `romPatch({op:'diff'})` (CPU addrs, CHR `tile:N`) |
-| Who references this address (static) | `disasm({target:'references'})` (direct modes only) |
+| Who references this address (static) | `disasm({target:'references'})` (flat scan) / `disasm({target:'xrefs'})` (deeper, graph-following) |
+| Map an unknown ROM's structure | `symbols({op:'analyze'})` / `disasm({target:'functions'})` (functions + strings + entrypoints) |
+| Graph one function's control flow | `disasm({target:'cfg', address})` (basic blocks + branch edges) |
+| Read a routine as C pseudocode | `disasm({target:'decompile', address})` (Ghidra; all 14, quality per CPU) |
 | Split / rebuild a ROM into parts | `cart({op:'extract'})` / `cart({op:'wrap'})` |
 | Swap a sprite/tile (PNG round-trip) | `tiles({op:'png'})` → edit → `romPatch({op:'spliceCHR'})` |
 | Lift art from another game's ROM | `importArt({from:'rom'})` |

package/src/platforms/atari2600/MENTAL_MODEL.md

@@ -233,3 +233,9 @@ Memory regions for **`memory({op:'read'})`**:
 audio voices (`AUDC/AUDF/AUDV` at `$15-$1A`), not a standard PSG/FM chip,
 so there's no `audioDebug` decode — read the audio state directly out of
 the `a26_tia_regs` snapshot instead.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 6502: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/atari7800/MENTAL_MODEL.md

@@ -379,3 +379,9 @@ Memory regions for **`memory({op:'read'})`**:
 chip carried over from the 2600 (`$15-$1A`), not a decodable PSG/FM chip,
 so there's no `audioDebug` decode. (Some carts add a POKEY, but it's
 non-standard — don't assume it's present.)
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 6502: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/c64/MENTAL_MODEL.md

@@ -334,3 +334,9 @@ moving further is a software char-cell shift.
 
 Track `camX` in pixels: `fine = camX & 7` → `$D016`; `coarseCol = camX >> 3`
 indexes your world map for which columns are on screen.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 6502: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/gb/MENTAL_MODEL.md

@@ -359,3 +359,9 @@ The `platformer` example is single-screen. To make it a side-scroller:
 Pattern: keep a `world_map[col][row]` array, a `camX` in pixels, convert
 actor world-X → screen-X as `worldX - camX`, and only ever touch the one
 column entering the screen per 8-px step.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on SM83: GOOD.** A dedicated SLEIGH plugin gives clean block-level pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

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

@@ -65,7 +65,7 @@ Templates ship in `examples/{gb,gbc}/templates/`:
 |---|---|
 | `default` | Minimal palette-cycle hello-world. Use when you're not sure what to build yet. |
 | `hello_sprite` | LCD init + 16-byte tile upload + 4-color OBJ palette + sprite slot 0 + d-pad movement. ~80 lines, tested end-to-end. |
-| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the Adventure / Zelda-1 / Sokoban shape. |
+| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the top-down dungeon-crawler / room-puzzle shape. |
 
 ## SDCC 4.4.0 quirks
 

package/src/platforms/gba/MENTAL_MODEL.md

@@ -55,7 +55,7 @@ mixing ARM + Thumb in the same binary. libgba is built Thumb-interwork.
 ```
 240×160 pixels visible, 6 BG modes (0-5)
 
-Mode 0: 4 tile BGs, scrolling. The classic 2D Mario-style mode.
+Mode 0: 4 tile BGs, scrolling. The classic 2D platformer mode.
 Mode 1: 2 tile BGs + 1 affine BG (rotation/scale).
 Mode 2: 2 affine BGs only. Mode 7-style perspective.
 Mode 3: 240×160 BGR555 framebuffer at $06000000. 16-bit per pixel.
@@ -268,3 +268,9 @@ entering view into the map's screen-blocks as the camera advances. A fixed HUD
 goes on its own BG layer left unscrolled (or via an HBlank IRQ that resets the
 offset for the HUD scanlines). Track camX in pixels; actor screen-X = worldX -
 camX.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on ARM7TDMI: EXCELLENT.** Most GBA code was compiled C, so the decompiler often recovers something close to the original source — lean on it. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -222,3 +222,9 @@ on CGB, its BG attribute byte in VRAM bank 1) each time the camera crosses an
 8-px boundary. Use the Window (LCDC bit 5) for a fixed HUD. CGB adds nothing
 that changes the scroll mechanism — just remember the per-tile attribute in
 bank 1 when you stream columns. See the GB MENTAL_MODEL for the full pattern.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on SM83: GOOD.** A dedicated SLEIGH plugin gives clean block-level pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

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

@@ -65,7 +65,7 @@ Templates ship in `examples/{gb,gbc}/templates/`:
 |---|---|
 | `default` | Minimal palette-cycle hello-world. Use when you're not sure what to build yet. |
 | `hello_sprite` | LCD init + 16-byte tile upload + 4-color OBJ palette + sprite slot 0 + d-pad movement. ~80 lines, tested end-to-end. |
-| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the Adventure / Zelda-1 / Sokoban shape. |
+| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the top-down dungeon-crawler / room-puzzle shape. |
 
 ## SDCC 4.4.0 quirks
 

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -219,7 +219,7 @@ size and treat your logical world coords separately.
 | 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)
+### How large scrolling 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
@@ -242,7 +242,7 @@ if (newTileCol != lastTileCol) {
 
 That's ~28 tile writes per 8 px of travel, not a 1792-cell plane redraw.
 The `platformer` example scrolls within one plane (no
-streaming); add the column-stream above to go wider. (Real Sonic also
+streaming); add the column-stream above to go wider. (Real large-scroller engines also
 splits the screen with H-blank raster effects for independent strips —
 that's an IRQ/raster topic, see the `asm` template.)
 
@@ -518,3 +518,9 @@ When you call `build({output:'rom'})`:
    image from the ELF → `.bin` Genesis ROM.
 
 Loadable via genesis_plus_gx (`loadMedia`).
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 68000: EXCELLENT.** An orthogonal ISA with real stack frames decompiles close to readable C — lean on it. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/genesis/TROUBLESHOOTING.md

@@ -260,5 +260,5 @@ Diagnose it without guessing (no core rebuild):
 
 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".
+(circular-buffer the 64-cell plane). See MENTAL_MODEL.md "How large scrolling
+maps REALLY work".

package/src/platforms/genesis/lib/wram.s

@@ -35,7 +35,7 @@ pad1_released     equ WRAM_BASE + $0006   ; 2 bytes
 game_state        equ WRAM_BASE + $0010   ; 1 byte: 0=title, 1=play, 2=gameover
 state_timer       equ WRAM_BASE + $0012   ; 2 bytes: frames in current state
 
-; Player / score (Tetris-shaped example).
+; Player / score (falling-block puzzle example).
 score             equ WRAM_BASE + $0020   ; 4 bytes (BCD or binary)
 lines_cleared     equ WRAM_BASE + $0024   ; 2 bytes
 level             equ WRAM_BASE + $0026   ; 1 byte

package/src/platforms/gg/MENTAL_MODEL.md

@@ -197,3 +197,9 @@ Everything else (Z80, VDP control protocol, tile format, sprite SAT
 layout, joypad polling, BG name table at $3800) is identical to SMS.
 You can use sms_hw.h notes + helpers as a reference; the GG runtime
 files in lib/c/ are direct ports.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on Z80: GOOD.** Register-rich hand asm decompiles cleanly at the block level. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/lynx/MENTAL_MODEL.md

@@ -272,3 +272,9 @@ into `.lnx`. handy accepts both.
 - One controller (handheld) — no port 2 fallback patterns.
 - 64 KB total RAM, mapped ROM. C64 has 64 KB RAM but most is shadowed
   by ROM by default.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 65C02: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/msx/MENTAL_MODEL.md

@@ -150,3 +150,9 @@ 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/`**.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on Z80: GOOD.** Register-rich hand asm decompiles cleanly at the block level. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/nes/MENTAL_MODEL.md

@@ -415,6 +415,12 @@ multi-bank `.cfg` referenced via `linkerConfigPath`. Either way: feed
 is the RE workhorse loop: `disasm({target:'project'})` → edit the `.asm` →
 rebuild → `diffRoms` to confirm your patch landed.
 
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 6502: ROUGH.** Carry-flag idioms and 16-bit math on an 8-bit CPU decompile to noise that only reads cleanly once an LLM folds it — on this CPU the disassembly is often more honest than the pseudocode. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.
+
 ## When to drop to asm
 
 Game-loop in C is fine for ~80% of homebrew. Drop to asm when:

package/src/platforms/pce/MENTAL_MODEL.md

@@ -110,3 +110,9 @@ screen. Keep at least one (2+ byte) global. See TROUBLESHOOTING.md.
   PCE asm toolchain IS cc65/ca65 — a **one-call byte-identical `build()`
   rebuild** via `rebuild.json` (flat and banked; a 512-byte copier header is
   split out and re-emitted as a HEADER segment).
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on HuC6280: MEDIUM.** The Ghidra HuC6280 SLEIGH covers all custom opcodes + MPR banking; pseudocode is usable. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/sms/MENTAL_MODEL.md

@@ -340,3 +340,9 @@ The `platformer` example is single-screen. To make it a side-scroller:
 
 Track `camX` in pixels; actor screen-X = `worldX - camX`. (Game Gear is the
 same VDP — only the visible window differs.)
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on Z80: GOOD.** Register-rich hand asm decompiles cleanly at the block level. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/platforms/snes/MENTAL_MODEL.md

@@ -47,13 +47,13 @@ The SNES has 8 BG modes selected via PPU register $2105 (BGMODE):
 
 ```
 0  4 BGs × 4 colors      — text-mode look
-1  3 BGs (16+16+4 col)   — default for most games (Super Mario World)
-2  2 BGs × 16 col + tilemap offset-per-tile (Yoshi's Island)
-3  1 BG × 256 col + 1 BG × 16 col (Donkey Kong Country)
+1  3 BGs (16+16+4 col)   — default for most games (typical 2D platformer)
+2  2 BGs × 16 col + tilemap offset-per-tile (a pre-rendered-sprite platformer)
+3  1 BG × 256 col + 1 BG × 16 col (pre-rendered-sprite platformer)
 4  1 BG × 256 col + 1 BG × 4 col with offset-per-tile
 5  2 BGs hi-res (512 px wide, half-height)
 6  hi-res mosaic
-7  1 BG with affine transform (Mario Kart, F-Zero)
+7  1 BG with affine transform (mode-7 racers)
 ```
 
 PVSnesLib's default is `BG_MODE1` (`setMode(BG_MODE1, 0)`) — three
@@ -313,3 +313,9 @@ and parallax is nearly free.
   scanlines.
 
 Track `camX` in pixels; actor screen-X = `worldX - camX`.
+
+## Reverse-engineering & decompilation
+
+The Rizin/Ghidra analysis engine works here like everywhere: `disasm({target:'functions'})` to carve the program, `disasm({target:'cfg'|'xrefs'})` to trace it, `symbols({op:'analyze'})` for a one-shot structural map.
+
+**Decompiler quality on 65816: MEDIUM.** The M/X register-width flags make instruction meaning context-dependent, but the Ghidra 65816 SLEIGH tracks them, so pseudocode is usable. `disasm({target:'decompile', address})` returns C-like pseudocode (the `qualityNote` field restates this). Read it to UNDERSTAND a routine; use `disasm({target:'project'})` to actually edit + rebuild. See the cross-platform ROM-hacking playbook §5f for the full loop.

package/src/toolchains/_worker/wasm-worker.js

@@ -109,6 +109,11 @@ async function runJob(job) {
       return buf[idx++];
     };
   }
+  // Optional environment variables for the WASM (e.g. SLEIGHHOME for the Ghidra
+  // decompiler). Seed Module.ENV in preRun, before libc reads getenv().
+  if (job.env && typeof job.env === "object") {
+    moduleArgs.preRun = [(m) => { Object.assign((m.ENV || (m.ENV = {})), job.env); }];
+  }
 
   const mod = await factory(moduleArgs);