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:

cd /home/tmerritt/Projects/disassembly/<Project>/copilot
make

To verify byte-identity:

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.