# Bomberman (U) — Game Flow from Power-On

This document describes the execution flow of the disassembled Bomberman (U) PRG bank (16 KB, mapped at CPU **$C000–$FFFF**), starting from power-on. It is based entirely on `copilot/prg.s` (with `header.s` and `chr.s` for the iNES header and CHR data) in the repository.

---

## 1. ROM and Memory Layout

| Property | Value |
|----------|-------|
| Format | iNES / NES 2.0 |
| PRG | 1 × 16 KB (mapped at CPU $C000–$FFFF) |
| CHR | 1 × 8 KB |
| Mirroring | Vertical |
| PRG bank start | CPU $C000 |
| Source files | `copilot/prg.s` (7,553 lines, ~493 KB), `header.s`, `chr.s` |
| Output | `reconstructed.nes` (24,592 bytes) |

### Interrupt vectors (CPU $FFFA–$FFFF)

| Vector | Address | Handler |
|--------|---------|---------|
| NMI | $C01A | `NmiHandler` |
| RESET | $C000 | `Reset` |
| IRQ / BRK | $FFF9 | `IrqHandler` (just `rti` — unused) |

---

## 2. Build Status

`make` in `copilot/` assembles and links successfully, producing `reconstructed.nes` (24,592 bytes).

**Verification result:** The reconstructed ROM is **byte-identical** to `bomberman.nes` — headers, CHR, and all 16,384 PRG bytes match exactly.

### Naming fixes applied

| Change | Location | Reason |
|--------|----------|--------|
| `RandomState0` kept at `$54`; added `RandomStateAlt = $E4` | `locals.inc` | Zero-page reuse: `$54` is the random-state byte used by most code; `$E4` is a distinct byte decremented at CPU `$E71B` |
| `dec RandomState0` → `dec RandomStateAlt` | `prg.s` (was `main.s:6972`) | The original ROM has `dec $E4` at CPU `$E71B`, not `dec $54` |
| `ControllerState` → `ControllerState1` | `prg.s` (16 refs) | Clarifies this is controller port 1; added `ControllerState2 = $13` for port 2 |
| `Main_HandleControl_C368` → `MainGameLoop` | `prg.s` (3 refs) | Main per-frame game loop entry point |
| `Gameplay_HandleControl_C79D` → `GameplayUpdate` | `prg.s` (4 refs) | Gameplay object dispatcher/update |
| `Sound_HandleControl_E65F` → `SoundUpdate` | `prg.s` (3 refs) | Sound engine update called from NMI |

### Pass 3 symbol application (2026-10-19)

| Pass | Substitutions | Detail |
|------|---------------|--------|
| locals.inc (single-name) | 354 operands | All zero-page addresses with exactly one name in `locals.inc` |
| locals.inc (multi-alias, site-resolved) | 8 operands | `$E0/$E1`: `IndirectPtrLo/Hi` in the RAM-clear loop (`InitializeSystemAndRunMainLoop` → `Main_WriteSoundDispatchIndex_C317`); `SoundDelay0` (indexed, `$E1,x`) in sound engine (`Gameplay_ReadSoundDelay0_E57B`, `InitializeApu`, `Sound_ReadSoundDelay0_E661`) |
| symbols.inc (hardware) | 0 operands | `prg.s` already contains no numeric hardware operands ($2000–$4017) |
| In-file data-table labels | 24 operands | 24 ROM-space table reads (`lda $C2E7,x` → `lda SystemPaletteData,x`, etc.) substituted via `reconstructed.lbl` |

**Residue:** 758 numeric operands remain, addressing bytes not named in either `.inc` file: 505 zero-page (133 distinct addresses), 171 RAM $0100–$07FF (46 addresses), and 82 ROM table reads (54 addresses, 34 of which are interior bytes of labelled tables).

---

## 3. Reset — CPU $FFFC → $C000

**`Reset`** ($C000)

On power-on or reset:

1. `sei` — disable maskable interrupts.
2. `lda #$00 / sta PPUMASK / sta PPUCTRL` — disable PPU rendering and NMI.
3. `cld` — clear decimal mode.
4. `ldx #$FF / txs` — initialize stack pointer to $FF.
5. **Wait for two startup VBlanks** — `WaitForFirstStartupVBlank` ($C00D) and `WaitForSecondStartupVBlank` ($C012) each poll `PPUSTATUS` ($2002) for the VBlank bit.
6. `jmp InitializeSystemAndRunMainLoop` ($C30C) — transfer control to the system initializer.

---

## 4. System Initialization — `InitializeSystemAndRunMainLoop` ($C30C)

This is the main entry point after reset:

1. **Clear RAM** — writes $00 to zero page via `Main_WriteZp00_C333` ($C333) and to $0100–$07FF via an indirect pointer `IndirectPtrLo`/`IndirectPtrHi` ($E0/$E1) in a 7-page loop (`Main_WriteSoundDispatchIndex_C317` at $C317).
2. `jsr InitializeVideoSystem` ($C1F2) — disables rendering, clears shadow OAM, uploads the system palette, enables NMI.
3. `jsr InitializeApu` ($E642) — silences all APU channels, resets sound delay/state variables (`SoundDelay0`–`SoundDelay2` at $E1–$E3).
4. Writes zero to sound state variables ($E0–$E3).
5. Sets stack pointer to $FF, enables APU ($4015 = $0F).
6. `jsr ComposeStatusScreen` ($DE83) — draws the initial status/title screen.
7. `jsr EnableNmiInPpuControl` ($C2B0) — enables NMI via PPUCTRL shadow.
8. Sets `ScreenState` ($72) = $01.
9. Enters the main loop at `MainGameLoop` ($C368).

---

## 5. NMI / Frame Heartbeat — `NmiHandler` ($C01A)

The NMI fires once per frame and is the central real-time driver:

1. **Save registers** (A, X, Y on stack).
2. Set `FrameSyncFlag` ($0B) = $00.
3. Set OAM address to $00.
4. **Sprite DMA path** — if $60 is zero, write OAM entry $0700–$0703 (sprite #0 at Y=$F8) and trigger OAMDMA ($4014 = $07).
5. **VRAM transfer path** — if `VramReadOffset` ($14) ≠ `VramWriteLimit` ($15), transfer VRAM data from a table at $0600–$0607, indexing into pointer data at $D9C6–$D9C9. Handles both write and read packet types.
6. **Screen state / NMI work pending** — based on `ScreenState` ($72) and `NmiWorkPending` ($60), transfers various VRAM data blocks (title screen, gameplay screen, etc.) using `SetPpuAddress` ($C196).
7. **PPU status / audio** — reads PPUSTATUS, commits PPU state and scroll via `CommitPpuStateAndScroll` ($C296), increments `FrameCounter` ($33), handles audio channel timing at $69/$6A.
8. `jsr Ppu_WriteZp10_C19D` ($C19D) — reads and debounces both controller ports, stores results in `ControllerState1` ($12) and `ControllerState2` ($13).
9. `jsr Gameplay_ReadZpB2_E4C7` ($E4C7) — gameplay input handling.
10. `jsr SoundUpdate` ($E65F) — sound engine update.
11. **DMC control** — if $38 and `GameMode` ($59) are zero, starts DMC playback ($4010 = $0E, DMC address $C000, length $FF, enable channels).
12. **PPU scroll wait** — if $60 is set, waits for VBlank (polls PPUSTATUS bit 6), then applies scroll from $0E/$0F.
13. Toggles `FrameParity` ($DB) with `EOR #$05` (frame parity / flip-flop flag).
14. **Restore registers, `rti`.**

### Controller reading (`Ppu_ReadControllerAndReturnA_C1BF` / $C1BF)
- Strobes `JOY1` ($4016) with $01 then $00.
- Reads 8 bits per controller, shifting into X.
- `Ppu_HandleControl_C1EB` masks to the low 2 bits ($03) and increments X if non-zero (button press detection).
- Port 1 result → `ControllerState1` ($12); port 2 result → $13 (`ControllerState2`).

---

## 6. Main Loop

The main loop starts at **`MainGameLoop`** ($C368):

```
MainGameLoop ($C368):
    wait until ControllerState1 ($12) is nonzero (button pressed)
    └─ branch on SELECT ($20) to toggle $5F
    └─ decrement sub-delay $71 / main delay $70
    └─ when delays expire, increment $59 (game mode / screen state)
```

Based on `$59` and `$5F`, the loop dispatches to:
- `RunMenuSelectionScreen` ($DA8E) — title/menu screen
- Gameplay initialization paths ($C3B6–$C5FF) — sets up object positions, stage, sound
- `Main_WriteStageCounter_C613` ($C613) — stage counter display

The core per-frame gameplay dispatch uses a **state table** at `MainStateDispatchTable` ($C75D–$C79C), which maps state indices to handler sub-indices ($00–$27). Gameplay object processing walks arrays at $03E6 (state), $0436, $0486 (X/Y position), $04D6, $0526 (timer/flags), with up to 80 ($4F) object slots.

Key main-loop subroutines:
- `Main_ReadGameMode_C60B` ($C60B) — waits for `FrameDelay` ($B5) to reach zero.
- `Main_WriteStageCounter_C613` ($C613) — updates stage counter, handles START button to begin gameplay.
- `GameplayUpdate` ($C79D) — main gameplay object dispatcher (80 slots).
- `Gameplay_Dispatch_C7A4` / `Gameplay_Dispatch_C835` — object state dispatch.
- `Stage_WriteObjectWorkX_D8FC` ($D8FC) — object work initialization.

---

## 7. Gameplay Systems

### Object management
- Up to 80 object slots ($00–$4F), tracked by state at $03E6,X.
- Position arrays: $0436,X / $0486,X (X/Y), $04D6,X (state/flags), $0526,X (timer/direction).
- `Stage_WriteObjectWorkX_D8FC` ($D8FC) initializes object work fields.
- Objects are processed in a loop with `dex`/index retreat patterns ($C756, $C8A6).

### Bomb / explosion / player mechanics
Referenced throughout the gameplay code:
- `Gameplay_HandleControl_C96A`, `Gameplay_HandleControl_CA1B`, `GameplayUpdate` — player/bomb input and state.
- `Object_WriteStageProgress_CFB0` ($CFB0) — stage progress tracking.
- `Frame_ReadObjectIndex_CE5B` ($CE5B), `Frame_ReadObjectX_CDD4` ($CDD4) — frame-based object reading.

### Stage system
- `Stage_ReadZp58_D69A` ($D69A) — stage data lookup.
- Stage counter display via `Main_WriteStageCounter_C613`.

---

## 8. Audio / Sound Engine

### `InitializeApu` ($E642)
- Clears DMC direct register ($4011), sound delays `SoundDelay0`–`SoundDelay2` ($E1–$E3).
- Silences pulse 1, pulse 2, triangle, noise channel controls ($4000, $4004, $4008, $400C).
- Enables APU channels ($4015 = $0F).

### `SoundUpdate` ($E65F)
- Loops over 3 sound channels (X = 2 down to 0).
- Decrements per-channel delay at `SoundDelay0,x` ($E1,X).
- When delay expires, reads sound command state from `SoundCommandState` ($DF):
  - If $DF < 0 → read sound RAM pointer ($E6BC table).
  - If $DF == 3 → write sound command state.
  - Otherwise → return or handle based on $E0 (indirect pointer).
- Calls into sound dispatch via `SoundDispatchAddressTable` ($E6AD–$E6C8).

### Sound dispatch table (`SoundDispatchAddressTable`, $E6AD)
A jump table of 14 sound handler addresses (e.g., $E641, $E6C8, $E6CC, $E6DE, $E727, $E766, $E792, $E7AB, etc.), each handling a specific sound effect or music channel.

### Channel-specific sound paths
- `Sound_UpdateAudioChannelPath_E6CF` ($E6CF) — noise channel ($400E–$400F).
- `Sound_UpdateAudioChannelPath_E6DF` ($E6DF) — pulse 2 channel: sets sweep ($4005 = $84), timer lo/hi ($4006/$4007), noise period/length.
- `Sound_UpdateAudioChannelPath_E70B` ($E70B) — decrements `RandomState0`, reconfigures pulse 2 when expired.

### Sound state (zero page)
| Address | Symbol | Use |
|---------|--------|-----|
| $DF | `SoundCommandState` | Sound command / state |
| $E0 | `IndirectPtrLo` / `SoundDispatchIndex` | Indirect pointer low; sound dispatch index |
| $E1–$E3 | `SoundDelay0`–`SoundDelay2` | Per-channel sound delays |

---

## 9. PPU / Rendering

### `InitializeVideoSystem` ($C1F2)
- `jsr DisableRendering` ($C257) — wait for VBlank, turn off PPUMASK.
- `jsr Ppu_HandleControl_C2B9` ($C2B9) — apply PPUCTRL shadow with NMI disabled.
- Set `PpuCtrlShadow` ($0C) = $10, clear $0E/$0F/$14/$15.
- `jsr HideAllSprites` ($C268) — fills $0700–$07FF with $F8 (offscreen) in 32-byte strides.
- `jsr UploadSystemPalette` ($C2C3) — uploads 32 bytes of palette data from `SystemPaletteData` ($C2E7) to $3F00–$3F1F.
- `jsr EnableNmiInPpuControl` ($C2B0) — enable NMI.

### `CommitPpuStateAndScroll` ($C296)
- Writes `PpuMaskShadow` ($0D) to PPUMASK ($2001).
- Sets PPU address to $0000, writes $00 to $2005 twice (scroll).
- Writes `PpuCtrlShadow` ($0C) to PPUCTRL ($2000).

### Palette data (`SystemPaletteData`, $C2E7)
32 bytes of NES palette colors starting at $3F00.

---

## 10. Zero-Page / RAM Symbols

The symbol table lives in `copilot/locals.inc` (hardware constants are in `copilot/symbols.inc`). Every address it names is used by name in `prg.s`:

| Address | Symbol | Use |
|---------|--------|-----|
| $0B | `FrameSyncFlag` | Main-thread/NMI frame handoff |
| $0C | `PpuCtrlShadow` | Software copy of PPUCTRL |
| $0D | `PpuMaskShadow` | Software copy of PPUMASK |
| $12 | `ControllerState1` | Controller port 1 sample |
| $13 | `ControllerState2` | Controller port 2 sample |
| $14 | `VramReadOffset` | NMI VRAM-transfer index into the $0600 table |
| $15 | `VramWriteLimit` | Upper limit compared against $14 |
| $16 | `NmiPathSelector` | $60=0 → sprite DMA path; $60≠0 → VRAM data path |
| $1F | `ObjectScreenX` | Object coordinate temporaries used by object processing |
| $20 | `ObjectScreenY` | |
| $28 | `ObjectSpawnParam` | Object spawn parameters |
| $29 | `ObjectSpawnY` | |
| $2A | `ObjectSpawnX` | |
| $2B | `ObjectSpawnWidth` | |
| $2C | `ObjectSpawnHeight` | |
| $33 | `FrameCounter` | Frame counter |
| $54–$57 | `RandomState0`–`RandomState3` | Four-byte PRNG state used by `AdvanceRandomState` |
| $59 | `GameMode` | Game mode / screen selector |
| $5C | `ObjectStateFlags` | Object state trio |
| $5D | `ObjectStateTimer` | |
| $5E | `ObjectStateExtra` | |
| $60 | `NmiWorkPending` | Nonzero → the NMI performs VRAM transfers |
| $70 | `MainDelay` | Main-loop delay counter |
| $71 | `SubDelay` | Secondary delay counter |
| $72 | `ScreenState` | Screen state flag |
| $73 | `ObjectXLimit` | Object X limit |
| $93 | `StageCounter` | Stage counter |
| $9C–$9F | `ObjectWork0`–`ObjectWork3` | Object work fields |
| $A4 | `BonusTimer` | Bonus timer |
| $AC–$AF | `AudioPtrLo/Hi`, `AudioArgLo/Hi` | Audio data / argument pointers |
| $B0 | `GameModeCounter` | Game-mode counter |
| $B1 | `ObjectType` | Object type |
| $B5 | `FrameDelay` | Frame delay |
| $DB | `FrameParity` | Frame-parity toggle, flipped by the NMI each frame |
| $DF | `SoundCommandState` | Sound command state |
| $E0 | `IndirectPtrLo` / `SoundDispatchIndex` | Indirect pointer for the RAM-clear loop; sound dispatch index in the sound engine |
| $E1 | `IndirectPtrHi` / `SoundDelay0` | Indirect pointer high byte; per-channel delay base (indexed by X) |
| $E2–$E3 | `SoundDelay1` / `SoundDelay2` | Remaining per-channel delays |
| $E4 | `RandomStateAlt` | Distinct byte decremented at CPU $E71B (zero-page reuse) |

**Aliases.** Two addresses carry two names each; `prg.s` uses the one that matches the calling routine. `$E0`/`$E1` are `IndirectPtrLo/Hi` in the RAM-clear loop (`InitializeSystemAndRunMainLoop` / `Main_WriteSoundDispatchIndex_C317`) and in the sound engine's pointer work, but `$E1` is `SoundDelay0` wherever the sound engine indexes the per-channel delay table (`SoundDelay0,x`, i.e. `$E1`–`$E3`).

**Unnamed residue.** Most zero-page/RAM bytes the game touches have no entry in `locals.inc` and stay numeric — 758 operands address 179 distinct addresses outside the table above (e.g. the `$34`/`$35` indirect pointer used by gameplay data writes). Naming them is Pass-3 semantic work, not a substitution.

---

## 11. Data Tables

| Label | Address | Description |
|-------|---------|-------------|
| `InesHeader` | $000000–$00000F (header segment) | iNES header (in `header.s`) |
| `SystemPaletteData` | $C2E7–$C306 | 32-byte palette for $3F00 |
| `MainStateDispatchTable` | $C75D–$C79C | 64-byte gameplay state dispatch table |
| `SoundDispatchAddressTable` | $E6AD–$E6C8 | 14-entry sound handler jump table |
| `PatternTableGraphics` | $004010+ (CHR segment) | CHR pattern table data (in `chr.s`) |

---

## 12. Summary of Execution Flow

```
Power On / Reset
    │
    ▼
Reset ($C000) ───────────────────────────────────────┐
    │ sei, disable PPU, cld, stack=$FF               │
    │ wait 2× VBlank                                 │
    ▼                                                │
jmp InitializeSystemAndRunMainLoop ($C30C)           │
    │                                                │
    ├─ clear RAM ($0000–$07FF)                       │
    ├─ InitializeVideoSystem ($C1F2)                 │
    │     ├─ DisableRendering                        │
    │     ├─ HideAllSprites                          │
    │     ├─ UploadSystemPalette ($3F00–$3F1F)       │
    │     └─ EnableNmiInPpuControl                   │
    ├─ InitializeApu ($E642) — silence all channels  │
    ├─ ComposeStatusScreen ($DE83)                   │
    ├─ EnableNmiInPpuControl                         │
    └─ MainGameLoop ($C368) ◄─────────────┘
                                                      │
MainGameLoop ($C368) ─────────────────────────────────┤
    │                                                │
    ├─ wait for controller button press              │
    ├─ handle SELECT / delay counters ($70,$71)      │
    ├─ increment game mode ($59)                     │
    ├─ RunMenuSelectionScreen ($DA8E) [title]        │
    ├─ gameplay init ($C3B6–$C5FF)                   │
    ├─ GameplayUpdate ($C79D)                        │
    │     │ 80 object slots ($03E6 state array)      │
    │     ├─ object position ($0436/$0486)           │
    │     ├─ object timer ($0526)                    │
    │     └─ object dispatch via StateDispatchTable  │
    └─ eventually → back to MainGameLoop             │
                                                      │
NMI ($C01A) [every frame]                            │
    │                                                │
    ├─ OAM setup + DMA ($4014)                       │
    ├─ VRAM transfer from $0600 table                │
    ├─ screen state transfer ($D9C6–$D9C9 pointers)  │
    ├─ controller read & debounce ($C1BF)            │
    ├─ Gameplay_ReadZpB2_E4C7 ($E4C7)                │
    ├─ SoundUpdate ($E65F)                           │
    ├─ DMC start ($4010–$4013)                       │
    ├─ PPU state & scroll commit ($C296)             │
    ├─ frame parity toggle ($DB)                     │
    └─ rti                                           │
                                                      │
Sound Engine ($E65F) [from NMI]                      │
    ├─ per-channel delay countdown ($E1–$E3)         │
    ├─ SoundDispatchAddressTable ($E6AD)             │
    ├─ pulse 2, noise, DMC channel control           │
    └─ RandomStateAlt ($E4) decrement                │
```

---

## 13. Notes

- **Build is byte-identical:** The apparent one-byte difference (`dec $E4` vs `dec $54` at CPU $E71B) was resolved by recognizing zero-page reuse — `$54` is `RandomState0` used by most code, while `$E4` is a distinct byte (`RandomStateAlt`) decremented at that one location. Both are now separately named in `locals.inc`.
- **Source annotation:** `prg.s` uses the canonical `; CPU:$C123 PRG:0123  AD 21 03` audit comment format on every instruction, enabling direct comparison with the binary.
- **Code organization:** Code is organized as reachable routines traced from the NMI/RESET/IRQ control-flow graph; unreachable bytes are classified as explicit data regions.
- **Legacy file:** `copilot/main.s` (8,070 lines) is a pre-standardization duplicate kept for reference; the build uses `prg.s` + `header.s` + `chr.s`.
- **Vectors confirm** NMI at $C01A and RESET at $C000, matching the reset handler location.
- **Known misnomer:** `Main_WriteSoundDispatchIndex_C317` ($C317) is actually the RAM-clear loop (writes $00 to $0100–$07FF via `IndirectPtrLo/Hi`), not a sound-dispatch write. The name reflects a prior pass's assumption; the operands now correctly use `IndirectPtrLo/Hi`. Renaming the label is a follow-up task.