disasm/OVERVIEW.md

# Disassembly Project Index — /home/tmerritt/Projects/disassembly/

This document provides a consolidated overview of all NES disassembly projects in this directory. Each project has its own folder containing a `copilot/` subdirectory with the full source, build tooling, and an individual `OVERVIEW.md` (at the project folder root) with a detailed power-on execution flow analysis.

---

## Project Inventory

| # | Project | Region/Version | PRG Size | CHR Size | Mirroring | Build Status | Vectors (NMI / RESET / IRQ) |
|---|---------|----------------|----------|----------|-----------|--------------|------------------------------|
| 1 | Balloon Fight (JU) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL | $C094 / $C000 / $C0F7 |
| 2 | Baseball (UE) | USA/Europe | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL | $C046 / $C40B / $C43E |
| 3 | Bomberman (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL | $C01A / $C000 / $FFF9 |
| 4 | Burger Time (U) | USA | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL | $C046 / $C40B / $C43E |
| 5 | Clu Clu Land (JU) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL | $C1F1 / $C000 / $FFF9 |
| 6 | Defender 2 (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL | $CAA1 / $C983 / $CA9E |
| 7 | Excitebike (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL | $C1F1 / $FD24 / $FD24 |
| 8 | Tennis (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL | $C07D / $C000 / $C000 |
| 9 | Pac-Man (USA) (Namco) | USA | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL | $C10E / $C000 / $C17E |
| 10 | Donkey Kong 3 (JUE) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL | $C07D / $C000 / $C000 |
| 11 | Donkey Kong Jr. (JU) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 2/3) | $C6E6 / $C66E / $FFF0 |

---

## Per-Project Details

### 1. Balloon Fight (JU)
- **Folder:** `Balloon Fight (JU)/`
- **ROM:** `balloon.nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (8,538 lines)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C094 (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C0F7 (`IrqHandler`, self-loop)
- **Key subsystems:** NMI-driven frame loop with PPU command buffer, round spawner ($C790), bonus objects ($CB74), carrier/rescue sequence ($C6F9), particle system ($CDAA), sound driver ($FFF7 banked)
- **Build fix:** None needed; byte-identical out of the box. **Pass 1 verified complete 2026-10-16** — 5,303 instructions / 11,260 code bytes (68.7%), which is *more* than the complete-opcode static tracer finds (5,277 / 11,202); the 166 tracer-only bytes are genuine data (command scripts at $D437/$D45A, the $C3B5 pointer table, the arithmetic table at $FBCA), not missed code. The last two `.incbin` spans were converted to explicit classified bytes (`TrailingFillBeforeApuTables` at $F4C5, `SoundEngineTailBytes` at $F5FC), so no ROM byte is hidden
- **Details:** `Balloon Fight (JU)/OVERVIEW.md`

### 2. Baseball (UE)
- **Folder:** `Baseball (UE)/`
- **ROM:** `baseball.nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (21,624 lines — largest source)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C046 (`NMI`), RESET → $C40B (`Reset`), IRQ → $C43E (`IRQ`, `rti`)
- **Key subsystems:** Queued event system ($EB66–$EB9C) as the main frame driver, round/state machine ($C5FE), batting/pitching ($C6044–$C6414), object sorting ($C339), sound driver ($F9D0–$FE2x)
- **Build fix:** None needed; byte-identical out of the box
- **Details:** `Baseball (UE)/OVERVIEW.md`

### 3. Bomberman (U)
- **Folder:** `Bomberman (U)/`
- **ROM:** `bomberman.nes` (24,592 bytes)
- **Source:** `copilot/main.s` (8,070 lines)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C01A (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $FFF9 (`IrqHandler`, `rti`)
- **Key subsystems:** NMI-driven PPU command queue and VRAM transfers, main loop at $C368 with state dispatch table ($C75D), bomb/object object slots (80 slots at $03E6), sound driver ($E642–$FE2x) with dispatch table ($E6AD)
- **Build fix:** One-byte mismatch at CPU $E70C (`dec $E4` vs `dec $54`) — resolved by adding `RandomStateAlt = $E4` to `locals.inc` alongside `RandomState0 = $54` (zero-page reuse); also renamed `ControllerState` → `ControllerState1`, `Main_HandleControl_C368` → `MainGameLoop`, `Gameplay_HandleControl_C79D` → `GameplayUpdate`, `Sound_HandleControl_E65F` → `SoundUpdate`
- **Details:** `Bomberman (U)/OVERVIEW.md`

### 4. Burger Time (U)
- **Folder:** `Burger Time (U)/`
- **ROM:** `Burger Time (U) [!].nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (9,323 lines), `copilot/header.s`, `copilot/chr.s`
- **Linker:** HEADER, PRG at $C000 (0x3FFA), VECTORS at $FFFA, CHR
- **Vectors:** NMI → $C046 (`NmiHandler`), RESET → $C40B (`ResetHandler`), IRQ → $C43E (`IrqHandler`)
- **Key subsystems:** Event-driven main loop via `CommonEngineExit` ($EB6A) and queued events ($EB9D), title screen / round state machine ($C5FE), object arrays ($03E6 state, $0436/$0486 position), audio engine ($F9D0–$FE2x) with music sequencer ($FD34)
- **Build fix:** None needed; byte-identical. Requires symlink `burger_time.nes → "../Burger Time (U) [!].nes"` due to spaces in ROM filename
- **Details:** `Burger Time (U)/OVERVIEW.md`

### 5. Clu Clu Land (JU)
- **Folder:** `Clu Clu Land (JU)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `copilot/main.s` (9,150 lines)
- **Linker:** PRG at $C000, 16 KB; single segment (no separate HEADER/CHR segments in cfg, but CHR data is embedded inline at end of prg.s)
- **Vectors:** NMI → $C1F1 (`NMIHandler`), RESET → $C000 (`ResetEntry`), IRQ → $C196 (`IrqHandler`, reuses Reset)
- **Key subsystems:** State-machine main loop via dispatch table at $C000–$C00D, NMI-driven PPU command queue + VRAM transfers, object pools ($03E6 state, $0436/$0486 position), sound driver ($E642–$F7C0) with dispatch table ($E6AD)
- **Build fix:** One `bpl` branch to undefined label at CPU $FAB4 — replaced with `bne *-$1B` to produce original `d0 e3` bytes (disassembler mislabeled `bne` as `bpl`)
- **Details:** `Clu Clu Land (JU)/OVERVIEW.md`

### 6. Defender 2 (U)
- **Folder:** `Defender 2 (U)/`
- **ROM:** `Defender 2 (U).nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (11,905 lines)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (0x3FFA), VECTORS at $FFFA, CHR at $0000
- **Vectors:** NMI → $CAA1 (`NmiHandler`), RESET → $C983 (`ResetHandler`), IRQ → $CA9E (`IrqHandler`, reuses Reset)
- **Key subsystems:** Event-driven main loop (`UpdateSideScrollingGameplay_CA6A` at $CA6A) waiting on NMI flag, side-scrolling gameplay ($C073–$C324 family), PPU streaming ($F20B–$F7C0), audio engine ($E642–$F7C0) with dispatch table ($E6AD)
- **Build fix:** Same `bpl` → `bne *-$1B` fix at CPU $E811 as Clu Clu Land (disassembler mislabeled `bne` as `bpl`)
- **Details:** `Defender 2 (U)/OVERVIEW.md`

### 7. Excitebike (JU)
- **Folder:** `Excitebike (JU)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (14,111 lines)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C23B (`NMI`), RESET → $C184 (`Reset`), IRQ → $FFF0 (points into audio data region — likely placeholder/unused)
- **Key subsystems:** NMI-driven state machine with dispatch table at $C000–$C00D (14 states), title/menu system ($C346–$C454), gameplay update chain ($C99A), race update ($C8D6), audio engine ($F8DE) with 4 channels + SFX, serial I/O over controller port $4016
- **Build fix:** Same `bpl` → `bne *-$1B` fix at CPU $FAB4 (same pattern as Clu Clu Land/Defender 2)
- **Details:** `Excitebike (JU)/OVERVIEW.md`

### 8. Tennis (JU)
- **Folder:** `Tennis (JU)/`
- **ROM:** `Tennis (JU).nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (9,268 lines)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C07D (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (`Reset` reused)
- **Key subsystems:** NMI-synchronized main loop (`MainLoop` at $C04F), game state machine via `MainStateHandlerTable` ($C101, 12 states), game mode state machine via `GameModeStateTable` ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
- **Build fix:** None needed; byte-identical out of the box
- **Details:** `Tennis (JU)/OVERVIEW.md`

### 9. Pac-Man (USA) (Namco)
- **Folder:** `Pac-Man (USA) (Namco)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (9,268 lines)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C10E (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C17E (`IrqHandler`)
- **Key subsystems:** NMI-synchronized main loop (`MainLoop` at $C04F), game state machine via `MainStateHandlerTable` ($C101, 12 states), game mode state machine via `GameModeStateTable` ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
- **Build fix:** None needed; byte-identical out of the box
- **Details:** `Pac-Man (USA) (Namco)/OVERVIEW.md`

### 10. Donkey Kong 3 (JUE)
- **Folder:** `Donkey Kong 3 (JUE)/`
- **ROM:** `Donkey Kong 3 (JUE).nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (9,952 lines)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C07D (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (`Reset` reused)
- **Key subsystems:** Main loop with object/game state management at $C02E–$C18D, object movement and geometry calculations ($C28E–$C683), audio engine ($F8DE+) with sound channels ($F0–$FF), PPU command buffer streaming ($C3F4+)
- **Build fix:** Build split `main.s` into `header.s`, `prg.s`, `chr.s`; added `RandomStateAlt = $E4` for `dec $E4` at CPU $E71B (zero-page reuse with `RandomState0 = $54`). **2026-10-16 — one-byte branch-target bug fixed:** the project was recorded as BYTE-IDENTICAL but had never built byte-identical. The `bne` at CPU $C14C (PRG $014C) was annotated `D0 12` (target $C160) but assembled as `D0 0D`, because it was labelled `StoreSelectedPlayerAndScreenFlags` ($C15B) instead of the routine actually at $C160. Retargeted to `ClearAudioSetGameMode` — which is also the semantically correct target for a "mode != $01" test. `cmp` now passes.
- **Details:** `Donkey Kong 3 (JUE)/copilot/OVERVIEW.md`

### 11. Donkey Kong Jr. (JU)
- **Folder:** `Donkey Kong Jr. (JU)/`
- **ROM:** `Donkey Kong Jr. (JU).nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (12,807 lines; 6,135 instructions, 266 routines, 68 data labels, 0 conflicts)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C6E6 (`NmiHandler`), RESET → $C66E (`ResetHandler`), IRQ → $FFF0 (stray byte, effectively unused)
- **Key subsystems:** Reset idles in a PRNG-advance loop — the entire frame state machine (title/attract/gameplay/sound) runs inside the NMI handler; VRAM/event queue at $0300 with dispatch table at $BFFE; 8-byte PRNG at $18–$1F; sound timers at $F1AF
- **Build fix:** None needed; byte-identical out of the box (`make` in `copilot/`). **Pass 1 verified complete 2026-10-16** — a full byte-accounting audit of `prg.s` confirms all 16,384 PRG bytes are emitted exactly once (6,199 instructions + 3,889 `.byte` + 16 `.word`), every emitted value equals the ROM byte, and there are zero audit-comment mismatches or duplicate addresses. No `.incbin` remains. A complete-opcode static tracer independently reaches 6,135 instructions / 12,358 code bytes (75.4%) — every one of which is already present in the file, and the file carries 121 further code bytes the tracer does not find (reached via the `DeferredTaskHandlerTable` dispatch at $BFFE). Pass 2/3 naming is complete; Pass 3 tables are named (`DeferredTaskHandlerTable`, `HudDigitDescriptorTable`, …)
- **Details:** `Donkey Kong Jr. (JU)/OVERVIEW.md`

### 12. CIRCUS
- **Folder:** `CIRCUS/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (~12,755 lines)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C05A (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $4CB7 (outside mapped space — effectively unused)
- **Key subsystems:** NMI-driven frame state machine — main loop is a spin loop at $C057, all per-frame work runs in NMI; main state dispatcher at $C0D0 with 16-state pointer table; controller input with edge flags at $09; menu system with text table at $C763 ("CONTINUE", "STAGE", "SELECT", "PLAY"); palette/screen transfer via descriptor streams; VRAM queue processing; variant object state machine at $DC3F–$FE7B; audio engine with sequence data at $FABB–$FFFB
- **Build fix:** None needed; byte-identical out of the box (`make` in `copilot/`). Pass 1/2/3 complete — full code/data classification, semantic routine naming, and data table naming all done
- **Details:** `CIRCUS/OVERVIEW.md`

### 13. Wild Gunman (U)
- **Folder:** `Wild Gunman (U)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (~3,000 lines with routine headers)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C086 (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (reuses `Reset`)
- **Key subsystems:** NMI-driven frame loop — main loop is a spin loop waiting on NMI phase flag ($20); NMI handler does OAM DMA ($4014), PPU updates, and calls game logic subroutines ($C29F, $C233, $C3AC, $C265); main state dispatcher at $C0B3 based on `GameMode` ($30); reset copies sprite/OAM data from $C844 to $05F0; APU enabled via $4015 = $0F
- **Build fix:** None needed; byte-identical out of the box (`make` in `copilot/`). **Pass 1 redone 2026-10-16** — the original tracer followed only RESET/NMI/IRQ and jsr/jmp/branch targets and knew just the 151 documented opcodes, so it missed Wild Gunman's runtime dispatch (`Label_C341`'s `pla`-based computed goto puts the jump table inline right after each `jsr $C341`) and filed ~4.9 KB of real code as `.byte` data. Code coverage went **1,597 instr / 3,352 B (20.5%) → 3,956 instr / 8,085 B (49.3%)**. Pass 2 partial — routine headers and semantic naming for key routines (`Reset`, `NmiHandler`, `MainStateDispatch`, `MainLoopBody`, etc.); zero-page aliases in `locals.inc` (`GameMode`=$30, `NmiPhase`=$20, `NmiFlag`=$22, `Timer2F`=$2F, etc.). Pass 3 pending (no data tables named yet)
- **Details:** `Wild Gunman (U)/OVERVIEW.md`

### 14. Joypad Test Cartridge (U)
- **Folder:** `Joypad Test Cartridge (U)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `copilot/prg.s` (~1,360 lines with routine headers)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $CCF7 (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (reuses `Reset`)
- **Key subsystems:** NMI-driven frame loop — main loop spins waiting on NMI phase; NMI handler does OAM DMA ($4014), PPU scroll/control latch, and burst VRAM writes from table at $0302; `VramPtrWrite` ($CD3F) uses a return-address modification trick at `RetAddrUpdate` ($CDC8) for runtime-computed dispatch; `VramWrite` ($CDEE) sets PPU address and writes data to PPUDATA; reset clears RAM, initializes PPU ($2000=$10, $2001=$00), triggers OAM DMA, and enters main loop
- **Build fix:** None needed; byte-identical out of the box (`make` in `copilot/`). Pass 1 complete — full code/data classification (~3.5% code / ~96.5% data); Pass 2 complete — routine headers for all labels, semantic naming for key routines, zero-page aliases in `locals.inc` (`VramPtrLo`=$00, `PpuCtrlShadow`=$EF, `FrameCounterLo`=$53, etc.)
- **Details:** `Joypad Test Cartridge (U)/OVERVIEW.md`

---

## Skeleton Projects (under `_wip/`)

20 additional ROMs awaiting full disassembly. Each is set up as a Pass-0 skeleton (`default_project.tar.gz`): `copilot/` contains the split `prg.bin`/`header.bin`/`chr.bin`, a symbolic skeleton `prg.s`, and builds **BYTE-IDENTICAL** at the PRG level. Mapper 0 / 16 KB PRG / 8 KB CHR for all.

| Project | Vectors (NMI/RESET/IRQ) | Mir. | Status |
|---------|--------------------------|------|--------|
| `Donkey Kong (JU)` | $C85F / $C79E / $FFF0 | V | BYTE-IDENTICAL |
| `Donkey Kong Jr. Math (U)` | $C4A9 / $C41E / $FFF0 | H | BYTE-IDENTICAL |
| `Duck Hunt (JUE)` | $C086 / $C000 / $C000 | H | BYTE-IDENTICAL |
| `Golf (JU)` | $C0A6 / $C000 / $C0C4 | H | BYTE-IDENTICAL |
| `Hogan's Alley (JU)` | $C088 / $C000 / $C000 | H | BYTE-IDENTICAL |
| `Ice Climber (JE)` | $C076 / $C014 / $FFF0 | V | BYTE-IDENTICAL |
| `Ice Climber (U)` | $C076 / $C014 / $FFF0 | V | BYTE-IDENTICAL |
| `Lode Runner (U)` | $C02C / $C000 / $FFF9 | H | BYTE-IDENTICAL |
| `Lunar Pool (U)` | $FF65 / $E80C / $FF64 | H | BYTE-IDENTICAL |
| `MUSCLE (U)` | $86CB / $8000 / $8764 | H | **Pass 3 done** — code/data split, full semantic naming, data tables structured; see `_wip/MUSCLE (U)/OVERVIEW.md` |
| `Mario Bros (JU)` | $C07D / $C000 / $C000 | H | BYTE-IDENTICAL |
| `Millipede (U)` | $C7F1 / $C735 / $FFF0 | H | BYTE-IDENTICAL |
| `Pac-Man (Tengen) (U)` | $C0FA / $C033 / $C16A | V | BYTE-IDENTICAL |
| `Pac-Man (U)` | $C0FA / $FF00 / $C16A | V | BYTE-IDENTICAL |
| `Pinball (JU)` | $C1ED / $C000 / $C1ED | H | BYTE-IDENTICAL |
| `Popeye (JU) (PRG 0)` | $C701 / $C649 / $FFF0 | H | BYTE-IDENTICAL |
| `Popeye (JU) (PRG 1)` | $C701 / $C649 / $FFF0 | V | BYTE-IDENTICAL |
| `Pyramid (U)` | $D72E / $FF00 / $FF00 | H | **Pass 1 done** — classified code/data, byte-identical; see `_wip/Pyramid (U)/OVERVIEW.md` |
| `Raid on Bungeling Bay (U)` | $C04C / $C000 / $C2C0 | H | BYTE-IDENTICAL |
| `Raid on Bungeling Bay (U) [a2]` | $C04C / $C000 / $C2C0 | V | BYTE-IDENTICAL |
| `Urban Champion (JU)` | $CA91 / $CA00 / $CA00 | H | BYTE-IDENTICAL |

Notable vector/header observations for Pass 1 work:
- **Pac-Man (U)** RESET at `$FF00` (vector-page tail), while the Tengen variant RESETs at `$C033` — different builds confirmed (PRG bytes differ).
- **MUSCLE (U)** — resolved at Pass 1: this is the one NROM ROM in the set mapped **low**, at $8000–$BFFF, because RESET is $8000. The skeleton's `$C000` linker assumption was wrong and `linker.cfg` had to move. The vectors themselves still sit in the mirror at $FFFA. IRQ $8764 is a bare `RTI` that doubles as the NMI epilogue.
- **Lunar Pool (U)** NMI `$FF65` / IRQ `$FF64` are adjacent in the vector page; RESET `$E80C`.
- **NES PowerPad Test Card (U)** — *at Pass 2/3*: minimal code (~7.2%), data-heavy test cartridge. RESET at $E000 (non-$C000 entry). NMI handler reads controllers via shift register, processes pad transitions, draws score/lives. See `NES PowerPad Test Card (U)/OVERVIEW.md`.
- **Ice Climber (JE) vs (U)**: byte-identical PRG *and* header — only the CHR differs (~regional title graphic).
- **Popeye (JU) PRG 0 vs PRG 1**: different PRG binaries (and mirroring); same vectors.
- **Raid on Bungeling Bay (U) vs [a2]**: `[a2]` differs in mirroring only per header, but PRGs differ — separate builds.
- **Pyramid (U)** — *already at Pass 1*: interesting unlicensed Sachen boot ($4100 mapper pokes, "AV" stack-byte check, two queued-event dispatchers). See its `OVERVIEW.md`.
- **MUSCLE (U)** — *at Pass 3*: bytecode-VM game. A naive recursive trace reaches only 50.6% of the PRG because the game dispatches through three jump tables and two zero-page `jmp (zp)` calls that a static descender cannot follow: a 38-entry token-program pointer table at `$8CEF`, a 40-entry opcode handler table at `$9237`, a second 16-entry handler table at `$9F2B`, and a 3-entry per-level VRAM-writer table at `$AC35`. Resolving those took code coverage to 64.9%. Compressed-VRAM RLE decoder at `$AC82` with a 12-byte fill table at `$ACBD`; restoring division by 20 at `$82AC`; four-channel sound engine with per-channel state in zero page `$C4-$EF`. See `MUSCLE (U)/OVERVIEW.md`.
- **CIRCUS** — *at Pass 2/3*: full recursive disassembly complete. NMI-driven frame state machine (main loop is a spin loop at $C057). Menu text at $C763 ("CONTINUE", "STAGE", "SELECT", "PLAY"). Object state machine at $DC3F–$FE7B. Audio sequence data at $FABB–$FFFB. See `CIRCUS/OVERVIEW.md`.
- **Joypad Test Cartridge (U)** — *at Pass 2/3*: minimal code (~3.5%), data-heavy test cartridge. NMI handler drives per-frame PPU/OAM updates. Uses return-address modification trick at `RetAddrUpdate` ($CDC8) with `VramPtrWrite` ($CD3F) for runtime-computed dispatch. See `Joypad Test Cartridge (U)/OVERVIEW.md`.
- **Wild Gunman (U)** — *Pass 1 redone, Pass 2 partial, Pass 3 pending*: NMI-driven frame loop. Gates its code behind runtime computed-goto tables — see the `prg.s` header block and its `OVERVIEW.md`.

## Common Patterns Across All Projects

### Memory Map
Every project uses a single 16 KB PRG bank mapped at CPU **$C000–$FFFF**, with 8 KB CHR. All builds are NROM (no bank switching).

### Interrupt Structure
All projects follow the same NES interrupt pattern:
- **NMI** fires once per frame and is the real-time heartbeat — handles OAM DMA, PPU updates, controller reading, and audio.
- **RESET** performs cold-start hardware init, RAM clearing, and enters the main loop.
- **IRQ** is almost always unused (either `rti` or a self-loop).

Two exceptions worth noting from branches of this family:
- **Excitebike** uses a state-dispatch table at $C000 rather than a conventional inline main loop, and its IRQ vector points into a data region (unused).
- **Donkey Kong Jr.** is the extreme case: its reset path idles forever in a PRNG-advance loop, and the *entire* frame state machine (title, attract, gameplay, sound) executes inside the NMI handler itself. Its reset entry is also at $C66E rather than $C000.

### Build Toolchain
All projects use the same toolchain:
- **ca65** (6502 assembler)
- **ld65** (linker with `.cfg` memory map)
- All rebuilds are verified **byte-identical** to the original `prg.bin` / ROM PRG bank.

### Disassembly Style
All sources are "Pass-1" style disassemblies:
- Every instruction annotated with PRG offset, CPU address, and emitted bytes
- Inline `.byte`/`.word`/`.res` data blocks interleaved with code
- Address-based labels (`Label_Cxxxx`, `Sub_Cxxxx`, `EngineRoutine_Cxxxx`) where semantics are not yet resolved
- Zero-page symbol files (`locals.inc`) and hardware symbol files (`symbols.inc`)

---

## Navigation

Each project folder contains:
- `copilot/` — disassembly source, build config, and build artifacts
- `OVERVIEW.md` (at the project folder root) — detailed per-project power-on execution flow analysis
- `<rom>.nes` — original NES ROM image (for reference)

To rebuild any project:
```bash
cd /home/tmerritt/Projects/disassembly/<Project>/copilot
make
```

To verify byte-identity:
```bash
make verify   # (where supported by the Makefile)
```

---

## Pass 1 methodology note (2026-10-16)

The original Pass 1 disassembler had two limitations that silently understated
code coverage. Both are worth knowing before trusting a coverage percentage:

1. **Documented opcodes only.** Its table held the 151 documented 6502 opcodes.
   These ROMs also use the 54 undocumented opcodes and the 26 unofficial NOPs
   as 2/3-byte padding; a tracer that halts on them strands the real code behind.
2. **No runtime dispatch.** It followed only vectors and direct `jsr`/`jmp`/branch
   targets. Games here dispatch through computed jumps — `jmp ($0014)`, the
   `pla`-based inline-table gotos in Wild Gunman (`Label_C341`), and task tables
   like Donkey Kong Jr.'s `DeferredTaskHandlerTable` at $BFFE.

Effect measured per project (old tracer → complete-opcode dispatch-aware tracer):

| Project | Old | Complete | Action taken |
|---------|-----|----------|--------------|
| NES PowerPad Test Card (U) | 546 instr | 559 | Pass 1 already sound |
| Joypad Test Cartridge (U) | 282 instr | **1,379** | **Pass 1 redo still outstanding** |
| Wild Gunman (U) | 1,600 instr | **4,083** | Pass 1 redone (49.3% code) |
| Balloon Fight (JU) | 5,216 instr | 5,277 | hand-done file was already better |
| Donkey Kong Jr. (JU) | 6,135 instr | 6,135 | file already complete |

**Joypad Test Cartridge (U) is the one project still carrying the old, truncated
Pass 1** — its recorded "3.5% code" is really ~18%, and roughly 2.4 KB of code is
still filed as `.byte` data. It must be redone before its Pass 2/3 can be trusted.

---

## Summary

All 15 projects in this repository rebuild **byte-identical** to their original ROMs:

| # | Project | Build Status | Pass 3 |
|---|---------|--------------|--------|
| 1 | Balloon Fight (JU) | BYTE-IDENTICAL | complete (Pass 1 verified) |
| 2 | Baseball (UE) | BYTE-IDENTICAL | complete |
| 3 | Bomberman (U) | BYTE-IDENTICAL | complete |
| 4 | Burger Time (U) | BYTE-IDENTICAL | complete |
| 5 | Clu Clu Land (JU) | BYTE-IDENTICAL | complete |
| 6 | Defender 2 (U) | BYTE-IDENTICAL | complete |
| 7 | Excitebike (JU) | BYTE-IDENTICAL | complete |
| 8 | Tennis (JU) | BYTE-IDENTICAL | complete |
| 9 | Pac-Man (USA) (Namco) | BYTE-IDENTICAL | complete |
| 10 | Donkey Kong 3 (JUE) | BYTE-IDENTICAL | complete |
| 11 | Donkey Kong Jr. (JU) | BYTE-IDENTICAL | complete (Pass 1 verified) |
| 12 | CIRCUS | BYTE-IDENTICAL | complete |
| 13 | Wild Gunman (U) | BYTE-IDENTICAL | pending (Pass 1 redone) |
| 14 | Joypad Test Cartridge (U) | BYTE-IDENTICAL | pending |
| 15 | NES PowerPad Test Card (U) | BYTE-IDENTICAL | complete |

The 20 `_wip/` skeleton projects above also all rebuild byte-identical (PRG level); all Pass 1 work and promotion to this index's numbered inventory is future work.