disasm/Pac-Man (USA) (Namco)/OVERVIEW.md

# Pac-Man (USA) (Namco) — Game Flow from Power-On

This document describes the execution flow of the disassembled Pac-Man (USA) (Namco) PRG bank (16 KB, mapped at CPU **$C000–$FFFF**), starting from power-on. It is based entirely on `copilot/prg.s` in the repository. The rebuild is verified **byte-identical** to the original `prg.bin`.

---

## 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 | Horizontal |
| PRG bank start | CPU $C000 |
| Source file | `copilot/prg.s` (14,332 lines) |
| Output | `reconstructed.nes` (whole ROM: 16-byte header + 16,384-byte PRG + 8,192-byte CHR) |

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

| Vector | Address | Handler |
|--------|---------|---------|
| NMI | $C10E | `NmiHandler` |
| RESET | $C033 | `Reset` |
| IRQ / BRK | $C17E | `IrqHandler` (just `rti` — unused) |

Additional ROM data at $FFF6–$FFF9:
- $FFF6/$FFF7 = $ECEC (little-endian), used by `DrawMazeNametable` as a source pointer ($00/$01)
- $FFF8/$FFF9 = $C10E (little-endian)

---

## 2. Build Status

`make` in `copilot/` assembles `prg.s` with `ca65`, links with `ld65`, and verifies against `prg.bin`.

**Verification result: BYTE-IDENTICAL** — `reconstructed.nes` matches `rom.nes` exactly (header + PRG + CHR).

---

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

**`Reset`** ($C033)

On power-on or reset:

1. `ldx #$00 / stx PPUCTRL` — disable PPU rendering/NMI.
2. `sei / cld` — disable maskable interrupts, clear decimal mode.
3. `dex / txs` — initialize stack pointer to $FF.
4. `nop x3` — three NOP padding bytes.
5. **Wait for two VBlanks** — `@WaitForPpu` loop: set PPUMASK=$06, poll PPUSTATUS bit 7 twice (X counts down from 2). This is the PPU warm-up delay.
6. **Clear low RAM** — `@ClearLowRam`: zero $0000–$003D.
7. **Clear RAM pages** — `@ClearRamPages`: using indirect pointer at $00/$01, clear pages starting at $0100 upward until high byte reaches $08 (effectively clearing $0100–$07FF).
8. `PPUMASK=$06`, scroll=$00 — enable background + sprites, reset scroll.
9. **Warm-start signature check** — `@CheckRamSignature`: compare RAM at $0052 against the 15-byte string `"HIROKI AOYAGI"` plus `$AA,$55` (stored at `RamSignature`, $C354–$C366):
   - If all 15 bytes match → warm start: skip full RAM clear, go to `@SignatureAlreadyPresent`.
   - If any byte differs → cold start: `@InitializeRamSignature` clears all of zero page, then copies the signature string to $0052–$0060.
10. Set $64=$01 (some flag), set gameState=$00.
11. Set $45=$07, then check cocktail/active-player flags at $46/$47. If both nonzero, perform a 16-byte swap loop (`@SwapLoop`) swapping bytes between $67,y and $77,y for Y=0..15.
12. `APUCTRL=$1F`, `APUFRAMECNT=$C0` — enable all APU channels, set frame counter mode.
13. `jsr InitializeAudioEngine` ($E1F8 region) — clear audio request/channel state.
14. `jsr $EEB4` — audio/sound engine init.
15. Set PPUCTRL=$88, `ppuCtrlShadow`=$88 — enable NMI, $2000 nametable base.
16. Set $48=$FF (gameplay suspended flag), clear $023F and $024B (PPU update buffers).
17. Set $36=$01 (some state flag).
18. `jmp MainEntry` — transfer control to the main program.

**`RamSignature`** ($C354): `.byte "HIROKI AOYAGI", $AA, $55` — developer credit / warm-start validation signature.

---

## 4. NMI / Frame Heartbeat — `NmiHandler` ($C10E)

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

1. **Save registers** (A, X, Y on stack).
2. **PPUMASK=$1E** — enable background + sprites with specific emphasis settings.
3. **OAM DMA**: write $00 to OAMADDR ($2003), $00 to $40, then `lda $45 / sta OAMDMA` ($4014) — DMA from page $45 (i.e., $4500–$45FF) to sprite RAM.
4. **`jsr FlushGameplayPpuUpdates`** ($DE3B region) — flush pending PPU gameplay update blocks at $023F and $0245.
5. **`jsr ReadNearbyNametableTiles`** — read nametable tile data around Pac-Man (likely for collision/tunnel logic).
6. **`jsr UpdatePalettes`** — upload palette data from RAM buffers $0299 and $02A9 to PPU palette $3F00/$3F10 when those buffers are marked active ($0F marker).
7. **Restore scroll**: write $41 and $42 to PPUSCROLL (two writes — horizontal then vertical).
8. **Construct PPUCTRL**: `lda $47 / and $46 / and #$01 / asl / ora $43` — builds the PPUCTRL value from shadow/flag bits, writes to PPUCTRL.
9. **Controller strobe**: write $01 then $00 to JOY1 ($4016).
10. **Read both controllers** — 8 iterations each:
    - Controller 1: read JOY1, mask with #$03, compare with #$01, rotate into $4D (`currentInput`).
    - Controller 2: read `APUFRAMECNT` ($4017), mask with #$03, compare with #$01, rotate into $4E.
11. **Select active controller**: X = `currentInput` ($4D) by default; if `cocktailModeFlag` ($46) & `activePlayerFlag` ($47) both nonzero, X = `newlyPressedInput` ($4E). Store X to `previousInput` ($4F).
12. **`inc frameCounter`** ($4B) — increment per-frame counter.
13. **$48 gate**: if $48 (`gameplaySuspended`) != 0, skip to `@NmiDone`.
14. **`jsr InitializeAudioChannels`** — scan and activate audio channel slots.
15. **`@NmiDone`**: restore registers (Y, X, A), `rti`.

The label `IrqHandler` appears at the `rti` following NMI's register restore — it is the same code address, just an alternate entry label for the IRQ vector (which points to the same `rti`).

### `UpdatePalettes`
Conditionally uploads 16-byte palette blocks from RAM $0299 (to PPU $3F00) and $02A9 (to PPU $3F10) when the corresponding buffer marker byte equals $0F. After upload, resets the marker and PPU address to $3000.

---

## 5. Main Entry — `MainEntry` ($C573)

After Reset, control transfers to `MainEntry`. This is the foreground state-machine entry:

1. **`$40=$01`** — set the NMI sync flag (NMI will clear it each frame).
2. **`@WaitForInitialNmi`** — spin until NMI clears $40 to $00 (synchronize to first VBlank).
3. **PPUCTRL=$88 / ppuCtrlShadow=$88** — enable NMI.
4. **PPUMASK=$00** — disable rendering.
5. **Clear OAM page** — fill $0700–$07FF with 0.
6. `cocktailModeFlag=$00`, then call:
   - `jsr ClearGameplayNametables`
   - `jsr InitializeNametableAttributes`
   - `jsr InitializeNametableData`
   - `jsr $E419` — additional init (address-named).
7. **Initialize palette buffers** — copy 32 bytes from `TitleScreenPalette` to RAM $0299–$02B8.
8. Set `actorStatusDisplay` ($6C–$6F) = $2D, set $023F=$FF, `gameplaySuspended`=$FF.
9. Clear $47, $46, $42, $41, `stateTimer` ($4C), $87, $88.
10. **PPUCTRL selection**: if `gameState` ($3F) != 0, use $8A; else use $8A as well (both paths end up with $8A; the `bne` is effectively a no-op in current code). Write to PPUCTRL and `ppuCtrlShadow`.
11. **`MainDispatchLoop`** ($C645):
    - `$40=$01`, spin until NMI clears it (`@WaitForNmi`).
    - `Y = gameState` ($3F), load 16-bit handler address from `MainStateHandlerTable` ($C267) into $10/$11.
    - `jmp ($0010)` — indirect jump to the state handler.

**`MainStateHandlerTable`** ($C267–$C26E) — 4 entries, indexed by `gameState` as a byte offset (even values $00, $02, $04, $06):

| Offset | Handler | Description |
|--------|---------|-------------|
| $00 | `InitialStateHandler` | Title/input-wait state |
| $02 | `PlayerSelectionState` | 1P/2P selection |
| $04 | `State04Handler` | Substate dispatch machine |
| $06 | `TimedStateTransition` | Timed state transition |

---

## 6. Main State Handlers

### `TimedStateTransition` ($C27A) — state offset $06
- Decrement `$0F` countdown. If nonzero, return to `MainDispatchLoop`.
- When zero: set `gameState`=$02, return to `MainDispatchLoop`.
- This is a timed transitional state: another state places a duration in `$0F` and selects state $06; this handler counts down before advancing to state $02.

### `InitialStateHandler` ($C27A region, actually at $C27A? No — at $C27A is TimedStateTransition; InitialStateHandler is at $C27A? Let me re-check)

Actually from the listing:
- `TimedStateTransition` is at $C27A
- `InitialStateHandler` is at $C27A? No. Let me re-read:

Line 730: `TimedStateTransition:` is at $C27A (based on comment "$C27A-$C2A5: Timed State Transition Handler" — wait, the comment says $C27A but the code shows `dec $0F` at line 731. Then line 740: `; $C27A-$C2A5: Initial/Input State Handler` and line 766: `InitialStateHandler:`.

So there's a discrepancy in comments. The actual code:
- `TimedStateTransition` = `dec $0F / bne MainDispatchLoop / lda #$02 / sta gameState / jmp MainDispatchLoop` — this is state $06's handler.
- `InitialStateHandler` = checks controller bits $0C; if set → gameState=$06, $0F=$5A, jump MainEntry. Else increment $42; if $42 reaches $F0 → reset $42, ppuCtrlShadow=$88, gameState=$06, $0F=$5A. Otherwise return to MainDispatchLoop.

### `PlayerSelectionState` ($C546 region) — state offset $02
- If $87|$88 != 0 → `@AdvanceTimeout` (16-bit timeout counter).
- Else (first entry): copy `PlayerCountSelectionDisplayData` ($C507–$C50E) to RAM $024B until $FF terminator. Capture controller bits $04 and $08 into `pacmanRequestedDirection` ($50) and `pacmanDirection` ($51).
- `@AdvanceTimeout`: increment 16-bit counter at $87/$88. If high byte reaches $02 → reset counter, set gameState=$04, jump MainDispatchLoop.
- `@CheckSelectionInput`: if controller bit $04 changed → store as `pacmanRequestedDirection`, reset counter, set $87=$01, toggle `activePlayerFlag` ($47) between 0/1, update display marker tiles at $024D/$0251 from `PlayerCountSelectionMarkerTiles` ($C50F–$C511).
- `@CheckConfirmInput`: if controller bit $08 changed → store as `pacmanDirection`. If bit $08 now active → clear `gameplaySuspended`, `jsr $EEB4`, jump `GameModeEntry`.

**`PlayerCountSelectionDisplayData`** ($C507): `$22,$0A,$5C,$00, $22,$4A,$20,$FF` — copied to $024B on entry.
**`PlayerCountSelectionMarkerTiles`** ($C50F): `$5C,$20,$5C` — selection marker toggle data.

### `State04Handler` ($C52E region) — state offset $04
- If controller bits $0C set → gameState=$02, jump MainEntry (restart).
- Else: `Y = $87` (substate offset), load 16-bit handler from `State04SubstateTable` ($C52E), jump indirect via $10/$11.

**`State04SubstateTable`** ($C52E) — 12 entries indexed by even offsets $00–$16:

| Offset | Handler |
|--------|---------|
| $00 | `State04Initialize` |
| $02–$12 | `State04TimedSubstate` (shared, 6 entries) |
| $14 | `State04LongDelay` |
| $16 | `State04FinalPhase` |

- `State04Initialize` ($C573): sync to NMI via $40, PPUCTRL=$08, disable rendering, clear $88, call `$C5D8`, `InitializeState04PpuData` ($C608), `LoadState04DisplayData` ($C5A6), advance $87 by 2, PPUCTRL=$88, return to loop.
- `State04TimedSubstate` ($C589): increment $88; at $30 frames → clear $88, call `$C5A6`, advance $87 by 2.
- `State04LongDelay` ($C5A6): increment $88; at $80 frames → advance $87 by 2 to substate $16.
- `State04FinalPhase` ($C5D7): sets $47=$01, tail-jumps to `GameModeEntry`.
- `SetSelectionFlagAndContinue` ($C5D7): `activePlayerFlag=$01`, `jmp GameModeEntry`.

### `LoadState04DisplayData` ($C5A6)
Uses $87 as offset into `CharacterIntroDisplayDataTable` ($C687), copies $FF-terminated stream to RAM $024B. Optional secondary copy of 16 bytes from `CharacterIntroSpriteData` based on substate offset.

**`CharacterIntroDisplayDataTable`** ($C687) — 10 pointers to display streams for characters/nicknames (SHADOW, BLINKY, SPEEDY, PINKY, etc.) plus scoring legend.

---

## 7. Game Mode Entry — `GameModeEntry` ($C328)

Reached from `SetSelectionFlagAndContinue` (state $04 final phase). This transitions from the attract/selection sequence into gameplay:

1. PPUCTRL=$88, ppuCtrlShadow=$88.
2. Wait for VBlank.
3. PPUMASK=$00, gameState=$00, cocktailModeFlag=$00, $69=$00, $4A=$00.
4. `jsr ClearGameplayNametables`, `jsr DrawGameplayHudLabels`, `jsr DrawGameplayScoreFields`.
5. If `gameplaySuspended` != 0 → roundNumber=$01 (continue existing game).
6. Else → clear 32 bytes starting at roundNumber ($67–$86), set roundNumber=$03, $77=$03, clear $0600/$0601.
7. Common init: roundDisplayValue=$FF, $78=$FF, $0245=$FF, ppuCtrlShadow=$88, PPUCTRL=$88.
8. **`GameModeFrameSync`** ($C360): `$40=$01`, wait for NMI clear ($@WaitForNmi`), then:
   - If `gameplaySuspended` != 0 AND controller bits $0C set → gameState=$02, jump MainEntry (restart).
   - If `stateTimer` ($4C) != 0 → decrement, return to `@WaitForNextFrame`.
   - Else `@DispatchState`: `Y = gameState`, load handler from `GameModeStateTable` ($CAD7) into $10/$11, indirect jump.

**`GameModeStateTable`** ($CAD7) — 8 entries indexed by even offsets $00–$0E:

| Offset | Handler |
|--------|---------|
| $00 | `GameModeState00` |
| $02 | `GameModeState02` |
| $04 | `GameModeState04` |
| $06 | `GameModeState06` |
| $08 | `GameModeState08` |
| $0A | `GameModeState0A` |
| $0C | `GameModeState0C` |
| $0E | `InitializeGameplayTransitionState` |

### `GameModeState04` ($CAE9) — pause/per-frame handler
- If $060F != 0 → return to `GameModeFrameSync`.
- Else: edge-detect controller bit $08 using $49 as previous state. On new press → increment $4A, install pause display commands at $024B, toggle pause display via bit 0 of $4A.
- When not paused and bit 0 of $4A clear → call gameplay helper chain before returning to `GameModeFrameSync`.
- Adjacent data at $CB5B contains tile values for "PAUSE" text — confirms this is the pause-state handler.

---

## 8. PPU / Rendering

### `DrawMazeNametable` ($E2E4)
Draws the maze nametable using compressed data:
- PPU destination selected based on cocktail mode ($47 & $46): $2000 or $2080.
- Source pointer from `MazeDataPointerBytes` at $FFF6–$FFF7 ($ECEC → points to ROM data).
- Each row: set PPU address, decode 2-bit-run-length-encoded bytes from the source (2 bits = repeat count-1, 6 bits = tile value), write $16 (22) bytes per row.
- Advance PPU destination by $20 per row.

### `FlushGameplayPpuUpdates` ($DE3B)
- If $48 (`gameplaySuspended`) == 0 → process update block at $023F (6 bytes + terminator to PPU).
- Else → jump to `UpdateAnimatedGameplayPpuFields`.
- Block at $0245 processed similarly if nonzero.

---

## 9. Audio System

**`InitializeAudioEngine`** ($E1F8):
- Clear audio request pointer ($F0/$F1 = $0006), channel table pointer ($F2/$F3 = $0620), sequence table pointer from ROM $F100/$F101.
- audioWorkValue=$40, APUSTATUS=$1F, APUFRAMECNT=$C0.
- Clear 16 bytes through ($F0), clear 16 entries at 8-byte stride through ($F2).

**`InitializeAudioChannels`** ($EED0):
- Clear audio channel flags and work values, scan 16 eight-byte slots through ($F2).
- Slots with values $01–$04 activate a channel: copy 4-byte parameters through indirect pointer $F6.
- Falls through to runtime command processing at $EF2D.

**`UpdateAudioChannels`** ($EF2D):
- For each active slot: decrement countdown, fetch command byte from sequence table, decode command ($F0+ = special, $C0+ = delay, else = note/frequency), update APU registers ($4000–$400F).

**`UpdateAudio`** ($F8DE):
- APUFRAMECNT=$C0, update Pulse 1, Pulse 2, Noise, Sound Effect channels.
- Clear $FF–$FB; if $07FF != 0 → APUDMALOAD, decrement $07FF.

Audio data tables at $FF00–$FFF5 (period/mask tables), $FF64–$FFEA (sequences/instruments), $F450–$F49A (runtime command data).

---

## 10. Zero-Page / RAM Symbols

| Address | Symbol | Use |
|---------|--------|-----|
| $00–$01 | workPtr0/1 | General indirect pointers |
| $02–$09 | workValue0–5 | General scratch values |
| $0A | pathCompareValue | Maze pathfinding |
| $0B | pathFallbackValue | Maze pathfinding |
| $0C | legalDirections | Maze pathfinding |
| $10 | dispatchVector | State dispatch indirect pointer |
| $12–$15 | arithmeticValue/Operand | 16-bit arithmetic |
| $1A–$2D | pacmanMotion–ghost4Motion | Actor motion records (4 bytes each) |
| $2E–$2F | pacmanTargetRow/Column | Pac-Man maze target |
| $32 | pacmanSpriteFrame | Pac-Man sprite frame |
| $33 | ghostSpriteFrames | Ghost sprite frames |
| $39 | ghostDirectionFlags | Ghost direction/control state |
| $3F | gameState | Main gameplay state |
| $40 | — | NMI sync flag ($01=pending, NMI clears to $00) |
| $41 | ppuCtrlShadow | PPUCTRL mirror |
| $42 | — | Second PPUSCROLL write |
| $46 | cocktailModeFlag | Cocktail cabinet mode |
| $47 | activePlayerFlag | Active player (0/1) |
| $48 | gameplaySuspended | Gameplay suspended flag |
| $4B | frameCounter | Per-frame counter |
| $4C | stateTimer | State countdown timer |
| $4D | currentInput | Controller 1 input |
| $4E | newlyPressedInput | Newly pressed input |
| $4F | previousInput | Previous input state |
| $50 | pacmanRequestedDirection | Requested direction |
| $51 | pacmanDirection | Current direction |
| $61 | highScoreDigits | High score digits |
| $67 | roundNumber | Round number |
| $68 | roundDisplayValue | Round display value |
| $6A | pelletsRemaining | Pellets remaining |
| $6B | extraLifeAwarded | Extra life flag |
| $6C–$6F | actorStatusDisplay | Actor status display |
| $70 | playerScoreDigits | Player score digits |
| $F0–$F7 | audioRequestPtr…audioWorkValue | Audio engine pointers/values |
| $F8 | audioChannelFlags | Audio channel flags |
| $FC | audioRequestIndex | Audio request index |
| $FD | audioChannelOffset | Audio channel offset |
| $FE–$FF | audioIndirectPtr | Audio indirect pointer |

---

## 11. Data Tables

| Label | Address | Description |
|-------|---------|-------------|
| `CopyrightText` | $C004 | "COPYRIGHT 1980 1993 NAMCO LTD. ALL RIGHTS RESERVED" |
| `RamSignature` | $C354 | `"HIROKI AOYAGI" $AA $55` — warm-start signature |
| `MainStateHandlerTable` | $C267 | 4 main state handler pointers |
| `State04SubstateTable` | $C52E | 12 state-$04 substate handler pointers |
| `GameModeStateTable` | $CAD7 | 8 game-mode state handler pointers |
| `CharacterIntroDisplayDataTable` | $C687 | 10 display data pointers for character intro |
| `TitleScreenTileBlock` | $C326 | 6 rows × $17 bytes of title tile data |
| `TitleScreenPpuRecords` | $C3B0 | 9 PPU update records for title screen |
| `TitleScreenPalette` | $C43F | 32-byte initial palette |
| `TitleScreenAttributeData` | $C45F | $18 attribute bytes |
| `PlayerCountSelectionDisplayData` | $C507 | 8 bytes for player-count display |
| `PlayerCountSelectionMarkerTiles` | $C50F | $5C,$20,$5C marker toggle |
| `CharacterIntroPalette` | $C667 | 32-byte character intro palette |
| `CharacterIntroDisplayDataTable` | $C687 | Character intro display pointers |
| `CharacterNicknameHeaderData` | $C69B | "CHARACTER ; NICKNAME" display data |
| `MazeDataPointerBytes` | $FFF6 | $EC,$EC,$0E,$C1 — maze data pointer ($C10E) |
| Audio tables | $FF00–$FFEA | Period/mask tables, sequences, instruments |

---

## 12. Summary of Execution Flow

```
Power On / Reset
    │
    ▼
Reset ($C033) ───────────────────────────────────────────────┐
    │ sei, cld, disable PPU, wait 2× VBlank                   │
    │ clear RAM $0000–$003D, clear pages $0100–$07FF          │
    │ PPUMASK=$06, scroll=$00                                 │
    │ check warm-start signature "HIROKI AOYAGI" + $AA,$55    │
    │   valid → skip full clear; invalid → clear + save sig   │
    │ set flags, optional 16-byte swap ($67↔$77)              │
    │ APUCTRL=$1F, APUFRAMECNT=$C0                            │
    │ jsr InitializeAudioEngine, jsr $EEB4                    │
    │ PPUCTRL=$88 (NMI enabled), $48=$FF (suspended)          │
    │ jmp MainEntry                                           │
    │                                                         │
MainEntry ($C573)                                             │
    │ $40=$1, wait for NMI to clear it                        │
    │ PPUCTRL=$88, PPUMASK=$00, clear OAM                     │
    │ clear cocktail/player flags, $41/$42/$4C/$87/$88        │
    │ init nametables, attributes, palette buffers            │
    │ select PPUCTRL ($8A), set ppuCtrlShadow                 │
    │                                                         │
MainDispatchLoop ($C645) ─────────────────────────────────────┤
    │ $40=$1, wait for NMI                                    │
    │ Y = gameState ($3F)                                     │
    │ load handler from MainStateHandlerTable ($C267)         │
    │ jmp ($0010) → state handler                             │
    │                                                         │
    ├─ State $00: InitialStateHandler                         │
    │   ├─ controller bits $0C → gameState=$06, $0F=$5A      │
    │   │   → jump MainEntry (restart sync)                  │
    │   └─ else inc $42; if $42==$F0 → reset, gameState=$06 │
    │                                                         │
    ├─ State $02: PlayerSelectionState                        │
    │   ├─ 1P/2P selection via controller bits $04/$08       │
    │   ├─ timeout ($87/$88 reaches $0200) → gameState=$04   │
    │   └─ confirm (bit $08) → clear suspended, jsr $EEB4,   │
    │       jmp GameModeEntry                                 │
    │                                                         │
    ├─ State $04: State04Handler                              │
    │   ├─ controller bits $0C → gameState=$02, restart      │
    │   └─ Y=$87 → dispatch via State04SubstateTable ($C52E) │
    │       ├─ $00: State04Initialize (PPU setup, $87+=2)    │
    │       ├─ $02–$12: State04TimedSubstate ($30 frames)    │
    │       ├─ $14: State04LongDelay ($80 frames)            │
    │       └─ $16: State04FinalPhase → $47=$1,              │
    │           jmp GameModeEntry                             │
    │                                                         │
    └─ State $06: TimedStateTransition                        │
        │ dec $0F; if nonzero → MainDispatchLoop              │
        │ else gameState=$02 → MainDispatchLoop               │
    │                                                         │
    └─ loop back to MainDispatchLoop                          │
    │                                                         │
GameModeEntry ($C328) [from SetSelectionFlagAndContinue]      │
    │                                                         │
    ├─ PPUCTRL=$88, wait VBlank, PPUMASK=$00                  │
    ├─ clear gameplay state, HUD labels, score fields         │
    ├─ if not suspended: clear player state, roundNumber=$3   │
    │   else: roundNumber=$1                                  │
    ├─ common init: roundDisplayValue=$FF, PPUCTRL=$88       │
    │                                                         │
GameModeFrameSync ($C360) ────────────────────────────────────┤
    │ $40=$1, wait for NMI                                    │
    │                                                         │
    ├─ if suspended && controller bits $0C → gameState=$02,  │
    │   jmp MainEntry (restart)                               │
    │                                                         │
    ├─ if stateTimer != 0 → dec, return to @WaitForNextFrame │
    │                                                         │
    └─ Y = gameState → dispatch via GameModeStateTable ($CAD7)│
        │                                                     │
        ├─ $00: GameModeState00                               │
        ├─ $02: GameModeState02                               │
        ├─ $04: GameModeState04 (pause/input handler)         │
        │     ├─ $060F != 0 → return to frame sync            │
        │     ├─ edge-detect controller bit $08 ($49)         │
        │     │   → new press: inc $4A, install pause cmds   │
        │     │   → bit 0 of $4A toggles pause display        │
        │     └─ not paused, bit0 of $4A clear → gameplay     │
        │       helper chain → return to frame sync           │
        ├─ $06–$0C: GameModeState06/08/0A/0C                  │
        └─ $0E: InitializeGameplayTransitionState             │
        │                                                     │
        └─ loop back to GameModeFrameSync                     │
    │                                                         │
    └─ (eventually enters gameplay via $0E handler)           │
                                                              │
NMI ($C10E) [once per frame]                                  │
    │                                                         │
    ├─ save A, X, Y                                           │
    ├─ PPUMASK=$1E                                            │
    ├─ OAM DMA ($4500–$45FF → $0200–$02FF)                   │
    ├─ jsr FlushGameplayPpuUpdates ($DE3B)                   │
    ├─ jsr ReadNearbyNametableTiles                           │
    ├─ jsr UpdatePalettes ($3F00/$3F10 from $0299/$02A9)     │
    ├─ restore scroll ($41,$42 → PPUSCROLL)                   │
    ├─ construct PPUCTRL from $47,$46,$43                     │
    ├─ strobe JOY1, read both controllers (8 bits each)       │
    │   → $4D (current), $4E (newly pressed)                  │
    ├─ select active controller → $4F (previousInput)         │
    ├─ inc frameCounter ($4B)                                 │
    ├─ if $48==0: jsr InitializeAudioChannels                │
    ├─ restore registers, rti                                 │
    │                                                         │
IrqHandler ($C17E): rti (unused)                              │
                                                              │
Audio Engine (from NMI via InitializeAudioChannels/$EEB4)     │
    ├─ 16 eight-byte channel slots scanned                    │
    │   │ values $01–$04 activate a channel                   │
    │   │ 4-byte parameters copied via $F6 pointer            │
    ├─ UpdateAudioChannels ($EF2D):                           │
    │   │ decrement countdowns, fetch command bytes,          │
    │   │ decode ($F0+=special, $C0+=delay, else=note),       │
    │   │ write APU registers $4000–$400F                     │
    └─ UpdateAudio ($F8DE): 4 channels + SFX + DMA trigger    │
```

---

## 13. Notes

- **Build verification:** `make` in `copilot/` produces `reconstructed.nes`, compared whole-ROM against `rom.nes`.
- Vectors confirm NMI at $C10E, RESET at $C033, IRQ at $C17E (a bare `rti`, unused).
- The foreground main loop (`MainDispatchLoop` at $C645) is strictly NMI-synchronized via `$40`: NMI clears it each frame, and the main code spins waiting for it to clear before dispatching to the next state handler.
- `GameModeEntry` ($C328) is a second, separate state machine entered from the state-$04 final phase. It has its own frame sync (`$40`) and its own 8-state dispatch table (`GameModeStateTable` at $CAD7), leading into gameplay initialization.
- State $04 contains a nested secondary state machine (`State04SubstateTable` at $C52E) with 12 substate offsets, implementing a timed character-introduction sequence (GHOST names, nicknames, scoring legend).
- The warm-start signature `"HIROKI AOYAGI"` at $0052 allows the game to preserve RAM across a soft reset.
- Many routine labels are address-based (`State04TimedSubstate`, `LoadState04DisplayData`, etc.) reflecting the automated first-pass disassembly; semantic naming is provisional.
- `symbols.inc` (embedded at the top of `prg.s`) provides NES hardware register names, controller masks, and extensive zero-page symbol definitions.