disasm/Tennis (JU)/OVERVIEW.md

# Tennis (JU) — Game Flow from Power-On

This document describes the execution flow of the disassembled Tennis (JU) 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 | Vertical |
| PRG bank start | CPU $C000 |
| Source file | `copilot/prg.s` (9,268 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 | $C07D | `NmiHandler` |
| RESET | $C000 | `Reset` |
| IRQ / BRK | $C000 | `Reset` (reused — unused) |

---

## 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 → $C000

**`Reset`** ($C000)

On power-on or reset:

1. `cld` — clear decimal mode.
2. `sei` — disable maskable interrupts.
3. **Wait for VBlank** — poll `PPUSTATUS` bit 7 (`@Flow_C002`).
4. `PPUCTRL=$00`, `PPUMASK=$00` — disable rendering and NMI.
5. Stack pointer = $FF.
6. `X = FrameCounter` ($27), then `Y=$06`, `WorkPtrHi=$02`, `WorkPtrLo=$00`, `A=$00`.
7. **Clear RAM** — `sta (WorkPtrLo),y` loop decrementing `WorkPtrHi` from $02 down, effectively clearing $0000–$02FF.
8. `X` is 0 at this point; if non-zero (it never is on entry), skip; else `X=$5F`.
9. `stx $0500` — set $0500 to $5F (or 0).
10. `jsr ClearNametables` ($C195) — clear nametable memory.
11. `jsr HideAllSprites` ($C1A5) — hide all sprites by writing $F4 to OAM.
12. `PPUSCROLL=$00` twice; `GameActiveFlag=$01`.
13. `APUSTATUS=$0F` — enable all four APU channels.
14. `PPUCTRL=$90`, `PpuCtrlShadow=$90` — enable NMI, $2000 base.
15. `PpuMaskShadow=$06`.
16. Falls into **`MainLoop`** ($C04F) — the permanent foreground loop.

---

## 4. Main Loop — `MainLoop` ($C04F)

After reset, control enters the infinite foreground loop:

```
MainLoop ($C04F):
    NmiWorkComplete ($30) = $00
    if GameActiveFlag ($38) != 0:
        if GameStateStep ($3E) == 1:
            jsr RunAudioEngine ($FFF7)
        Flow_C060:
    jsr UpdateTimers ($C375)
    jsr UpdateGameState ($C0AA)
    NmiUpdatesEnabled ($32) = $01
    Flow_C06A:
    if NmiWorkComplete ($30) != 0:
        FrameCounter ($27)++
        NmiUpdatesEnabled ($32) = $00
        jmp MainLoop
    else:
        jsr RollRng ($C456)
        jmp Flow_C06A
```

The main loop is **NMI-synchronized**: it waits for `NmiWorkComplete` ($30) to become non-zero (set by NMI each frame), then advances the frame counter, clears the update-enabled flag, and loops. If NMI work is not complete, it rolls the RNG and retries.

---

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

The NMI fires once per frame:

1. **Save registers** (A, X, Y on stack).
2. **OAM DMA**: write $00 to OAMADDR ($2003), then $02 to OAMDMA ($4014) — copy $0200–$02FF to sprite RAM.
3. If `NmiUpdatesEnabled` ($32) == 0, skip to `@Flow_C0A0`.
4. Otherwise:
   - `jsr WritePalette` ($C1B5) — conditional palette upload based on `PaletteUpdateMode` ($3C).
   - `jsr WritePpuBuffer` ($C2EC) — flush pending PPU command buffer at $0590.
   - `jsr SetScroll` ($C3FD) — write scroll from $1E/$1F to PPUSCROLL.
   - `jsr ReadControllers` ($C2A4) — read both controller ports.
5. `NmiWorkComplete ($30) = $01` — signal main loop that the frame update is done.
6. `NmiTriggerFlag ($33) = $01`.
7. Restore registers, `rti`.

The label `IrqHandler` appears at the same `rti` address — IRQ/BRK vector points here, but it's unused (same as Reset).

---

## 5. Game State Machine — `UpdateGameState` ($C0AA)

Called each main-loop iteration:

```
UpdateGameState ($C0AA):
    if GameActiveFlag ($38) == 0:
        Flow_C0B1:
        if ControllerHeld ($1A) & START ($10):
            if StartButtonLatch ($34) != 0 → skip
            else: StartButtonLatch=$01
            Y = GameState ($3D)
            if GameState == 7 → Flow_C0EA
            if GameState == 4 → Flow_C0CC
            if GameState == 6 → skip
            else → Flow_C0FC
        Flow_C0FC:
        DispatchInlineAddressTable ($C38B) with GameState index
            → GameStateHandlerTable ($C101)
    else (GameActiveFlag == 0):
        Flow_C119:
        if ControllerHeld & $30 (START|SELECT):
            if bit $10 set → Flow_C134
            else: GameActiveFlag=$00, GameState=$00, PendingStateFlag=$00
                  jsr MatchRoutine_CBCB, jsr DisableRendering
                  GameMode=$SelectedGameMode ($E0), rts
        Flow_C134: (complex state-transition logic with StateTransitionFlag, GameMode, etc.)
        Flow_C180:
        GameStateStep ($3E) → DispatchInlineAddressTable → GameStateStepHandlerTable ($C185)
```

### `MainStateHandlerTable` ($C101) — indexed by `GameState` ($3D) as a byte offset (even offsets $00–$16):

| Offset | Handler | Description |
|--------|---------|-------------|
| $00 | `GameState00_InitializeMatch` ($C70A) | Match initialization |
| $02 | `GameState01_WaitForServe` ($C797) | Wait for serve input |
| $04 | `GameState02_PrepareRally` ($C7B7) | Prepare rally |
| $06 | `GameState03_RunRally` ($C7C6) | Run rally |
| $08 | `GameState04_PointEnded` ($C907) | Point ended |
| $0A | `GameState05_UpdateScore` ($CA07) | Update score |
| $0C | `GameState06_AdvanceGame` ($C9DE) | Advance game |
| $0E | `GameState07_PauseOrTransition` ($C42B) | Pause/transition (RTS) |
| $10 | `GameState08_WaitForTimer` ($CA28) | Wait for timer |
| $12 | `GameState09_RestorePreviousState` ($CA31) | Restore state |
| $14 | `GameState0A_ResumePreviousState` ($CA3A) | Resume state |
| $16 | `GameState0B_FinishTransition` ($CA5B) | Finish transition |

### `GameStateStepHandlerTable` ($C185) — indexed by `GameStateStep` ($3E):

| Offset | Handler |
|--------|---------|
| $00 | `ModeStep00_DrawSelectionScreen` ($CA87) |
| $02 | `ModeStep01_Countdown` ($CAC9) |
| $04 | `ModeStep02_InitializeSelection` ($CADD) |
| $06 | `ModeStep03_UpdateSelection` ($CAE4) |
| $08 | `ModeStep04_ConfirmSelection` ($CAEE) |
| $0A | `ModeStep05_StartDemoOrMatch` ($CAF4) |
| $0C | `ModeStep06_CompleteSetup` ($CC04) |

### Key state handlers:

- **`GameState00_InitializeMatch`** ($C70A): First-time init — clear nametable, render routine, palette mode, set `PendingStateFlag`. Subsequent calls advance through sub-states ($87/$88 counter), render sprites, enable rendering, set `GameState=$07`, call `MatchRoutine_CBCB`.
- **`GameState01_WaitForServe`** ($C797): Disable rendering, clear nametable, render court + score, zero point winners, clear animation flags, set ball trajectory flags, advance `GameState`.
- **`GameState02_PrepareRally`** ($C7B7): Enable rendering, clear PPU mask shadow bit 4, hide sprites, render routine, advance `GameState`.
- **`GameState03_RunRally`** ($C7C6): Render routine, set `PpuBufferReady`, `MatchRoutine_C7E7` (copy initial object state), `PhysicsRoutine_D7E1`, handle serving player, `EngineRoutine_C436`, advance `GameState`.

---

## 6. NMI-Driven Per-Frame Work

The NMI handler (called every VBlank) performs:

| Step | Routine | Address | Purpose |
|------|---------|---------|---------|
| OAM DMA | — | $C084–$C089 | Copy $0200–$02FF to sprite RAM |
| Palette update | `WritePalette` | $C1B5 | Conditional palette upload ($3F00/$3F10) |
| PPU buffer flush | `WritePpuBuffer` | $C2EC | Write pending PPU commands from $0590 buffer |
| Scroll | `SetScroll` | $C3FD | Write scroll X/Y from $1E/$1F |
| Controller read | `ReadControllers` | $C2A4 | Read both ports, build held/newly-pressed |

The main loop calls `UpdateGameState` ($C0AA) which dispatches to the active game state handler, then advances timers and audio.

---

## 7. Object / Sprite System

- **OAM buffer** at $0200–$02FF, written via `WriteMetaspriteToOam` ($C440).
- **Object data pointers**: `ObjectDataPointerLo/Hi` ($A8/$A9), `ObjectDataOffset` ($AA), `ActiveObjectIndex` ($AB).
- **Animation**: `AnimationFrame` ($B0), `AnimationTimer` ($B1), `PoseFrameTimer` ($B3), `PlayerAnimationId` ($B4), `PoseSequenceOffset` ($B5), `PlayerPoseId` ($B6), `PlayerPoseFlags` ($B7).
- **Racket**: `RacketTargetX` ($B8), `RacketTargetY` ($B9), `RacketContactFlags` ($BA), `RacketAimOffset` ($BB).
- **Player physics**: `PlayerMotionControl` ($60/$65 for P1/P2), X/Y position + subpixel ($61–$69), target coordinates ($80–$83), action type/state ($84–$86), facing direction ($87), position ($88–$89).
- **Ball**: `BallMotionControl` ($6A), X/Y position + subpixel ($6B–$6E), height ($6F/$70), target offset ($71), vertical velocity ($72/$73), state flags ($7A), bounce state ($7B), contact state ($8F), trajectory flags ($8D), collision flags ($8E).

---

## 8. Audio System

**`RunAudioEngine`** ($FFF7) — jumps to `AudioEngineUpdate` ($F8E0). Called from MainLoop when `GameStateStep == 1` and `GameActiveFlag != 0`.

**`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, scan 16 eight-byte slots through ($F2).
- Slots with values $01–$04 activate a channel: copy 4-byte parameters through indirect pointer $F6.

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

Audio RAM symbols ($F0–$FF): `audioRequestPtr`, `audioChannelTablePtr`, `audioSequenceTablePtr`, `audioWorkPtr`, `audioWorkValue`, `audioChannelFlags`, `audioRequestIndex`, `audioChannelOffset`, `audioIndirectPtr`, plus channel-specific effect timers ($F5–$F6), sequence pointers/indices ($F7–$FA), stream position ($FB), event priority ($FC), request flags ($FD–$FF).

---

## 9. Zero-Page / RAM Symbols (key subset)

| Address | Symbol | Use |
|---------|--------|-----|
| $01–$02 | WorkPtrLo/Hi | General indirect pointer |
| $09 | PpuCtrlShadow | $2000 mirror |
| $0A | PpuMaskShadow | $2001 mirror |
| $1A | ControllerHeld | Controller buttons held |
| $1B | Zp1B | Previous controller state |
| $20 | Zp20 | Timer counter |
| $25 | StateTimer | State countdown timer |
| $27 | FrameCounter | Frame tick counter |
| $30 | NmiWorkComplete | NMI frame-sync flag |
| $31 | PpuBufferReady | PPU buffer ready flag |
| $32 | NmiUpdatesEnabled | NMI updates enabled flag |
| $33 | NmiTriggerFlag | NMI trigger flag |
| $34 | StartButtonLatch | Start button debounce latch |
| $35 | StateTransitionFlag | State transition flag |
| $38 | GameActiveFlag | Game active flag |
| $39 | GameMode | Current game mode |
| $3C | PaletteUpdateMode | Palette update mode |
| $3D | GameState | Main game state |
| $3E | GameStateStep | Game state step/substep |
| $3F | DemoCounter | Demo counter |
| $43 | PendingStateFlag | Pending state flag |
| $44 | StateSubstep | State substep |
| $46 | PlayerCourtOrder | Player court order |
| $48–$4B | ModeAnimTimer/Frame A&B | Mode animation timers/frames |
| $4C | ServingPlayer | Serving player |
| $4D | ModeAnimSubframe | Animation subframe |
| $4E | MessageTimer | Message timer |
| $4F | MessagePlayerIndex | Message player index |
| $50 | PointWinner | Point winner |
| $51–$53 | Player/2 Point/Game Score | Score values |
| $57–$5D | Score-related state | Score display/update state |
| $5E | PendingGameState | Pending game state |
| $60–$6E | Player/Ball motion state | Player and ball physics |
| $78–$7F | Animation/ball state | Animation flags, ball state/collision |
| $80–$8F | Target/action/collision state | Player targets, action state, collision flags |
| $A8–$AA | ObjectDataPointerLo/Hi, Offset | Object data pointers |
| $AB | ActiveObjectIndex | Active object index |
| $B0–$C9 | Animation/pose/racket state | Animation frames, pose, racket targets |
| $CA–$CC | Contact/bounce state | Racket/ball contact state |
| $CD–$CF | Movement/action state | Movement speed, computer/action state |
| $E0 | SelectedGameMode | Selected game mode |
| $E6–$FF | Audio engine state | Audio request pointers, channel flags, sequence state |

---

## 10. PPU / Rendering

- **OAM DMA**: Every NMI, DMA from $0200–$02FF via `OAMDMA` ($4014).
- **PPU buffer**: `WritePpuBuffer` ($C2EC) writes a command buffer at $0590 to PPU when `PpuBufferReady` ($31) is set.
- **Scroll**: `SetScroll` ($C3FD) writes $1E/$1F to PPUSCROLL.
- **Palette**: `WritePalette` ($C1B5) conditionally uploads from RAM buffers based on `PaletteUpdateMode` ($3C).
- **Palette shadow**: `PpuCtrlShadow` ($09), `PpuMaskShadow` ($0A).
- **Sprite hiding**: `HideAllSprites` ($C1A5) writes $F4 to OAM.
- **Metasprite rendering**: `WriteMetaspriteToOam` ($C440) writes sprite data from a pointer.

---

## 11. Data Tables

| Label | Address | Description |
|-------|---------|-------------|
| `MainStateHandlerTable` | $C101 | 12 main game state handler pointers |
| `GameStateStepHandlerTable` | $C185 | 7 mode step handler pointers |
| `GameStateHandlerTable` (game mode) | $CAD7 | 8 game-mode state handler pointers |
| `InitialMatchObjectStateData` | $C847 | Initial object state data for match start |
| `EngineTable_*` | Various | Inline data tables embedded between code |
| `AudioEventSequenceData` | $FDFA | Audio event sequence data |
| Audio tables | $FF00–$FFF5 | Period/mask tables, sequences, instruments |

---

## 12. Summary of Execution Flow

```
Power On / Reset
    │
    ▼
Reset ($C000) ───────────────────────────────────────────────────────┐
    │ cld, sei, wait VBlank, PPUCTRL/PPUMASK=$00                      │
    │ stack=$FF, clear RAM $0000–$02FF                                │
    │ $0500=$5F, clear nametables, hide sprites                       │
    │ PPUSCROLL=$00, GameActiveFlag=$01                               │
    │ APUSTATUS=$0F (all channels on)                                 │
    │ PPUCTRL=$90 (NMI on), PpuCtrlShadow=$90                         │
    │ PpuMaskShadow=$06                                               │
    │                                                                 │
    ▼                                                                 │
MainLoop ($C04F) ─────────────────────────────────────────────────────┤
    │                                                                 │
    ├─ NmiWorkComplete ($30) = $00                                    │
    ├─ if GameActiveFlag && GameStateStep==1: RunAudioEngine ($FFF7)  │
    ├─ jsr UpdateTimers ($C375)                                       │
    ├─ jsr UpdateGameState ($C0AA)  ──► state machine dispatch        │
    │     ├─ State $00: InitializeMatch                               │
    │     ├─ State $01: WaitForServe                                  │
    │     ├─ State $02: PrepareRally                                  │
    │     ├─ State $03: RunRally                                      │
    │     ├─ State $04: PointEnded                                    │
    │     ├─ State $05: UpdateScore                                   │
    │     ├─ State $06: AdvanceGame                                   │
    │     ├─ State $07: PauseOrTransition (RTS)                       │
    │     ├─ State $08–$0B: WaitForTimer / Restore / Resume / Finish  │
    │     └─ return to MainLoop                                       │
    │                                                                 │
    ├─ NmiUpdatesEnabled ($32) = $01                                  │
    ├─ wait for NmiWorkComplete ($30) != 0  ◄── NMI sets this         │
    ├─ FrameCounter++, NmiUpdatesEnabled=$00                          │
    └─ jmp MainLoop                                                   │
    │                                                                 │
    │   (if NmiWorkComplete==0: jsr RollRng ($C456), retry)           │
    │                                                                 │
NMI ($C07D) [once per frame]                                          │
    │                                                                 │
    ├─ save A, X, Y                                                   │
    ├─ OAM DMA ($0200–$02FF → $4014)                                  │
    ├─ if NmiUpdatesEnabled:                                          │
    │     jsr WritePalette ($C1B5)                                    │
    │     jsr WritePpuBuffer ($C2EC)                                  │
    │     jsr SetScroll ($C3FD)                                       │
    ├─ jsr ReadControllers ($C2A4)  → $4D/$4E/$4F                     │
    ├─ NmiWorkComplete ($30) = $01  (unblocks main loop)              │
    ├─ NmiTriggerFlag ($33) = $01                                     │
    ├─ restore registers, rti                                         │
    │                                                                 │
IrqHandler ($C17E): rti (unused)                                      │
```

---

## 13. Notes

- **Build verification:** `make` in `copilot/` produces `reconstructed.nes`, compared whole-ROM against `rom.nes`.
- Vectors confirm NMI at $C07D, and both RESET and IRQ at $C000 (the reset handler doubles as the IRQ handler, just a `rti`).
- The foreground main loop (`MainLoop` at $C04F) is strictly NMI-synchronized via `NmiWorkComplete` ($30): it loops until NMI sets it to $01, processes game state and timers, then waits again.
- `UpdateGameState` ($C0AA) dispatches to one of 12 main game states via `MainStateHandlerTable` at $C101, indexed by `GameState` ($3D).
- State $04 contains a nested secondary state machine (`GameStateStepHandlerTable` at $C185, 7 steps) for mode selection/setup.
- Many routine labels are address-based (`EngineRoutine_C1DD`, `MatchRoutine_C7E7`, etc.) reflecting the automated first-pass disassembly; semantic naming is provisional.
- `symbols.inc` provides NES hardware register names and controller masks; `locals.inc` provides extensive zero-page symbol definitions covering player/ball physics, audio, and game state.
- The disassembly includes inline data tables (`EngineTable_*`) embedded between code regions, preserved verbatim for byte-identity.