tmerritt/disasm
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b96fb1932e5d4d37f3971010dbc2f565b65c3186
disasm/OVERVIEW.md
T
tmerritt b96fb1932e Redo Pass 1 for Wild Gunman (U): 20.5% -> 49.3% code coverage 
The original tracer followed only vectors and direct jsr/jmp/branch targets and
knew just the 151 documented 6502 opcodes. Wild Gunman dispatches at runtime, so
~4.9 KB of real code was filed as .byte data.

Root cause: Label_C341 ($C341) is a computed goto that pulls the CALLER's return
address with two 'pla' instructions, so its jump table physically follows each
'jsr $C341' (opcode 20 41 C3) and is indexed by A*2. Seven call sites exist; the
table at $C114 (after 'lda $33 / jsr $C341') decodes to 14 valid targets.

Changes:
- Tracer rebuilt with all 54 undocumented opcodes + 26 unofficial NOPs (these
  ROMs use them as 2/3-byte padding; a tracer that halts on them strands code)
- Iterative expansion seeded from inline $C341 tables, in-trace control-flow
  references, and explicit pointer tables (e.g. the 5-entry table at $DEDD)
- prg.s updated SURGICALLY: all 249 existing routine headers, semantic labels
  and locals.inc aliases preserved; only data->code promotion applied
- Fixed a byte-dropping parser bug: some .byte lines use symbolic values
  (Zp01, NmiPhase, Ctrl1), which a $XX-only regex silently skipped
- Branch targets landing mid-instruction now force a split so labels land on
  real instruction boundaries
- Bytes that cannot be assembled stay .byte: ca65's 6502 has no
  SLO/RLA/SRE/RRA/ISC/DCP/LAS/TAS/ANE/AXS/LXA mnemonics

Verified: 1,597 -> 3,956 instructions, 3,352 -> 8,085 code bytes (49.3%).
Every one of the 16,384 PRG bytes emitted exactly once, every value equal to the
ROM, zero audit-comment mismatches. Byte-identical ROM verified.
2026-10-16 20:39:11 -04:00

284 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 1) | $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
- **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`)
- **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 status — unresolved bytes preserved as `.incbin` blocks pending Pass 2/3 renaming and table decoding
- **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)
```
---
## 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 | in progress |
| 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 | pending |
| 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 | pending |
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.
Reference in new issue View Git Blame Copy Permalink