disasm/_wip/Hogan's Alley (JU)/OVERVIEW.md

# Hogan's Alley (JU) — Game Flow from Power-On

This document describes the execution flow of the disassembled Hogan's Alley (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` at the PRG level.

---

## 1. Reset Vector — CPU $FFFC → $C000

**`Reset`** ($C000–$C085)

On power-on or reset, the 6502 jumps to `$C000`. The reset routine performs cold-start hardware initialization:

| Step | Code | Purpose |
|------|------|---------|
| 1–2 | `cld` / `sei` | Clear decimal mode, disable interrupts |
| 3–6 | Poll `$2002` twice (`bpl *-3`) | Wait for two full VBlank periods (PPU warm-up) |
| 7–8 | `ldx #$00` / `txs` | Initialize stack pointer to $01FF |
| 9–21 | Clear RAM $0000–$07FF | Uses Zp00/Zp01 as 16-bit pointer; clears 8 pages of 256 bytes |
| 22–23 | Warm-start signature check | Loads `$05EC` into X; if non-zero, skips full clear and sets X=$5F |
| 24 | `jsr $C221` | Initialize PPU/APU registers |
| 25 | `jsr $C231` | Additional hardware init |
| 26–27 | PPU scroll init | Write $00 to `$2005` twice (X/Y scroll) |
| 28 | `lda #$0F` / `sta $4015` | Enable all APU channels |
| 29 | `jsr $FFF7` | Call audio engine init (trampoline to $F984) |
| 30 | `lda #$90` / `sta $2000` / `sta Zp08` | PPUCTRL: NMI on, sprites at $0000, BG at $1000, + $90 shadow in Zp08 |
| 31 | `lda #$02` / `sta Zp09` | Zp09 = $02 |
| 32–36 | Copy sprite data | Copy 12 bytes from $E36A to $05F0 (OAM staging area) |
| 37 | `bmi Label_C07E` | Branch to main loop (always taken after copy) |

**Warm-start signature:** Byte at `$05EC` survives RAM clear. On soft reset, if non-zero, the game skips the full 2 KB clear and initializes X=$5F instead of X=$00.

---

## 2. Interrupt Vectors — CPU $FFFA–$FFFF

Located at the end of the bank (PRG offset $3FFA):

| Vector | Address | Handler |
|--------|---------|---------|
| NMI | $C088 | `NmiHandler` |
| RESET | $C000 | `Reset` |
| IRQ | $C000 | `Reset` (reused — unused placeholder) |

---

## 3. NMI / Frame Heartbeat — `NmiHandler` ($C088)

The NMI fires once per frame and drives the frame pacing. It implements a two-phase frame structure:

```
NmiHandler ($C088):
    php / pha / txa / pha / tya / pha          ; preserve registers
    lda #$00 / sta $2003                        ; OAMADDR = 0
    lda #$02 / sta $4014                        ; OAM DMA from $0200
    lda Zp22                                    ; NMI phase flag
    bne Label_C0AB                              ; if phase 1: skip game logic
    jsr $C2BD                                   ; update game objects
    jsr $C24E                                   ; update targets
    jsr $C3A8                                   ; update shots
    jsr $C282                                   ; update sprites
    jsr $C3D0                                   ; update HUD/score
Label_C0AB:                                     ; phase 1 entry / phase 0 exit
    ldy #$01 / sty Zp22 / sty Zp20              ; set phase=1, clear main flag
    pla / tay / pla / tax / pla / plp / rti     ; restore, return
```

**Phase 0 (Zp22=0):** Full game logic update — objects, targets, shots, sprites, HUD.
**Phase 1 (Zp22=1):** Minimal — only OAM DMA, then returns. The main loop toggles Zp22.

---

## 4. Main Game Loop — $C07E

After initialization, control reaches the per-frame loop at **$C07E**:

```
Label_C07E:
    lda Zp20           ; main loop flag (set by NMI phase 0)
    bne Label_C065     ; if set, run frame logic
    jsr $C6BD          ; attract/demo mode logic
    jmp $C07E          ; loop
```

When NMI phase 0 completes, it sets **Zp20 = $01** (at $C076 in `Label_C070`). The main loop sees this, branches to **`Label_C065`** ($C065), which dispatches based on game state:

```
Label_C065:
    lda Zp24           ; game mode/state
    beq Label_C06D     ; if 0: audio-only frame (jsr $FFF4)
    lda Zp26           ; sub-state
    beq Label_C070     ; if 0: gameplay frame
Label_C06D:
    jsr $FFF4          ; audio engine update (trampoline to $FFD4)
    rts
Label_C070:
    jsr $C337          ; controller input
    jsr $C0B8          ; state dispatcher
    inc Zp2F           ; frame counter
    lda #$00 / sta Zp20 / sta Zp22  ; clear flags for next frame
```

**`Label_C0B8` ($C0B8)** — State dispatcher:
```
    lda Zp24
    beq Label_C0BF     ; if game mode 0: title/gameplay
    jmp $C156          ; else: other modes (game over, etc.)
```

**`Label_C0BF` ($C0BF)** — Title/Gameplay dispatcher:
```
    lda Zp16 / and #$10 / beq Label_C11A   ; check bit 4 of Zp16
    ldy $05FC / bne Label_C11F             ; check $05FC
    iny / sty $05FC
    ldy Zp25 / cpy #$07 / beq Label_C106   ; state 7
    cpy #$03 / beq Label_C0E4              ; state 3
    cpy #$04 / beq Label_C0E4              ; state 4
    cpy #$0A / beq Label_C0E4              ; state A
    cpy #$0F / bne Label_C11F              ; state F
```

States 3, 4, A → **`Label_C0E4`** (gameplay init); State 7 → **`Label_C106`**; others → **`Label_C11F`** (continue gameplay).

---

## 5. Key Subsystems

### 5.1 Gameplay Initialization — `Label_C0E4` ($C0E4)
```
    ldx #$05
Label_C0E6:
    lda Zp2A,x / sta $0430,x   ; copy Zp2A–Zp2F to $0430–$0435
    dex / bpl Label_C0E6
    jsr $C14A                  ; copy stack page $01FF to $0217
    jsr $CDB4                  ; initialize round data
    lda #$25 / sta Zp45        ; set timer
    jsr $CE4B                  ; spawn targets
    lda Zp25 / sta Zp1C        ; save state
    lda #$07 / sta Zp25        ; set state = 7
    jmp $C10E
```

### 5.2 State 7 Handler — `Label_C106` ($C106)
```
    lda #$11 / sta Zp25        ; set state = $11
    lda #$30 / sta Zp1D        ; set timer
```

### 5.3 Main Gameplay Loop — `Label_C10E` ($C10E)
```
    jsr $C746                  ; update targets
    jsr $D291                  ; update shots
    jsr $FFF4                  ; audio engine
    jmp $D2B4                  ; update sprites/OAM
```

### 5.4 Controller Input — `$C337`
Reads controller via `$4016` (strobe + shift), stores button state in Zp16/Zp17.

### 5.5 Audio Engine — `$FFF4` / `$FFF7`
Trampolines at $FFF4 (update) and $FFF7 (init) jump to banked code at $F9D4/$F984.

### 5.6 Target System — `$C746`, `$CDB4`, `$CE4B`
Manages the 5–6 shootable targets (cans, birds, etc.) — position, state, scoring.

### 5.7 Shot System — `$D291`, `$D2B4`
Player shots: tracking, collision with targets, scoring.

---

## 6. Memory Map (Key Zero Page / RAM)

| Address | Name (from `locals.inc`) | Use |
|---------|--------------------------|-----|
| $00–$01 | `Zp00` / `Zp01` | 16-bit pointer for RAM clear (Reset) |
| $08 | `Zp08` | PPUCTRL shadow ($90) |
| $09 | `Zp09` | Init value $02 |
| $16 | `Zp16` | Controller buttons (bit 4 = start pressed) |
| $1C | `Zp1C` | Saved game state |
| $1D | `Zp1D` | Timer/counter |
| $20 | `Zp20` | Main loop flag (set by NMI phase 0) |
| $22 | `Zp22` | NMI phase flag (0=game logic, 1=OAM only) |
| $24 | `Zp24` | Game mode (0=title/play, non-zero=other) |
| $25 | `Zp25` | Sub-state (3,4,7,A,F,11, etc.) |
| $26 | `Zp26` | Sub-state flag |
| $29 | `Zp29` | Reset signature ($B6) |
| $2A–$2F | `Zp2A`–`Zp2F` | Gameplay params, copied to $0430 |
| $2F | `Zp2F` | Frame counter |
| $30 | `Zp30` | Frame ready flag (set by NMI) |
| $45 | `Zp45` | Gameplay timer ($25 init) |
| $0430–$0435 | — | Gameplay parameter shadow |
| $05EC | — | Warm-start signature byte |
| $05F0–$05FB | — | OAM staging (12 bytes from $E36A) |
| $05FC | — | Title screen state |
| $06F0 | — | Reset signature mirror |
| $4014 | OAMDMA | OAM DMA trigger |
| $4015 | APUSTATUS | APU channel enable |
| $4016 | JOY1 | Controller 1 strobe/read |

---

## 7. Object Pools / Data Structures

| Region | Purpose |
|--------|---------|
| $0430–$0435 | Gameplay parameters (target positions, timers) |
| $05F0–$05FB | Sprite/OAM data for 4–6 objects |
| $0400–$04FF | Sprite data (positions, states) |
| $0200–$02FF | OAM buffer (DMA source) |
| $E36A–$E375 | Initial sprite data (copied to $05F0 at reset) |

---

## 8. Summary of Execution Flow

```
Power On / Reset
    │
    ▼
Reset ($C000) ────► cld/sei, wait 2 VBlanks, init stack
    │
    ├─ Clear $0000–$07FF (8 pages via Zp00/Zp01)
    │
    ├─ Check $05EC warm-start signature
    │     ├─ Zero: full clear, X=$00
    │     └─ Non-zero: X=$5F (skip clear)
    │
    ├─ jsr $C221, $C231 (PPU/APU init)
    ├─ PPU scroll = 0,0
    ├─ APU enable ($4015=$0F)
    ├─ jsr $FFF7 (audio init → $F984)
    ├─ PPUCTRL = $90 (NMI on)
    ├─ Copy $E36A→$05F0 (12 bytes sprite data)
    │
    ▼
Main Loop ($C07E) ─────────────────────────────────────────┐
    │                                                      │
    ├─ lda Zp20 (NMI phase 0 flag)                         │
    │     ├─ Zero: jsr $C6BD (attract/demo), loop          │
    │     └─ Non-zero: branch to Label_C065                │
    │                                                      │
    ▼                                                      │
Label_C065 ($C065) ───► lda Zp24 (game mode)               │
    │     ├─ 0: jsr $FFF4 (audio only), rts                │
    │     └─ Non-zero: lda Zp26                            │
    │           ├─ 0: Label_C070 (gameplay frame)          │
    │           └─ Non-zero: jsr $FFF4 (audio), rts        │
    │                                                      │
    ▼                                                      │
Label_C070 ($C070) ──► jsr $C337 (controller)              │
    │                    jsr $C0B8 (state dispatch)        │
    │                    inc Zp2F (frame counter)          │
    │                    clear Zp20, Zp22                  │
    │                                                      │
    ▼                                                      │
Label_C0B8 ($C0B8) ──► lda Zp24                            │
    │     ├─ 0: Label_C0BF (title/play dispatcher)         │
    │     └─ Non-zero: jmp $C156 (other modes)             │
    │                                                      │
    ▼                                                      │
Label_C0BF ($C0BF) ──► state machine on Zp25               │
    │     ├─ 3,4,A: Label_C0E4 (gameplay init)             │
    │     ├─ 7: Label_C106 (state 7 handler)               │
    │     └─ else: Label_C11F (continue)                   │
    │                                                      │
    ▼                                                      │
Gameplay states (3,4,A→7→11→...) ──► Label_C10E            │
    │                    jsr $C746 (targets)               │
    │                    jsr $D291 (shots)                 │
    │                    jsr $FFF4 (audio)                 │
    │                    jmp $D2B4 (sprites)               │
    │                                                      │
    ▼ (loop back to $C07E)                                 │

NMI ($C088) [once per frame]
    ├─ Preserve registers
    ├─ OAM DMA ($4014 from $0200)
    ├─ lda Zp22 (phase flag)
    │     ├─ 0: jsr $C2BD (objects), $C24E (targets), $C3A8 (shots),
    │     │     $C282 (sprites), $C3D0 (HUD)
    │     └─ 1: skip game logic
    ├─ ldy #$01 / sty Zp22 / sty Zp20  (toggle phase, signal main)
    ├─ Restore registers, rti
```

---

## 9. Naming and Residue

**Pass 1 complete** — 9,810 lines, 568 `Label_` definitions, canonical audit comments, 41.8% code.

**Pass 2 outstanding** — Root inventory: *needs CDL reclass*. The 55 seeded routine entries from table references include `$E9F1` which was a false positive (data table base, not dispatch) and was forced back to data 2026-10-19. 31 of the remaining 54 have no direct `jsr`/`jmp` reference.

**Pass 3 outstanding** — No semantic zero-page aliases; `locals.inc` holds 171 neutral `ZpXX` names.

**Indirect dispatch** (not followed statically):
- `jmp ($0014)` at $C360
- `jmp ($0610)` at $F927
- `jmp ($0612)` at $F941

**Promotion outstanding** — Add `header.s`/`chr.s` + HEADER/PRG/CHR `linker.cfg`, switch `make` to whole-ROM `cmp`, move `_tools` paths from `../../../_tools/` to `../../_tools/`.

Build verification: `make` in `copilot/` produces `reconstructed_prg.bin`, compared against `prg.bin` (PRG byte-identical).