# 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:
```bash
cd /home/tmerritt/Projects/disassembly/<Project>/copilot
make
```

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