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 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

---

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

---

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).

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
• copilot/OVERVIEW.md — 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)