disasm/Millipede (U)/OVERVIEW.md

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

This document describes the execution flow of the disassembled Millipede (U) 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 → $C735

**`Reset`** ($C735–$C7B3)

On power-on or reset, the 6502 jumps to **$C735** (non-$C000 entry, Donkey Kong Jr. style). The reset routine performs cold-start hardware initialization:

| Step | Code | Purpose |
|------|------|---------|
| 1–2 | `sei` / `cld` | Disable interrupts, clear decimal mode |
| 3–4 | `lda #$00` / `sta $2000` | PPUCTRL = 0 (NMI off, sprite $0000, BG $0000) |
| 5–6 | `ldx #$FF` / `txs` | Initialize stack pointer to $01FF |
| 7–11 | `Label_C73F`: poll `$2002` via `and #$80` / `beq` | Wait for VBlank (bit 7 of PPUSTATUS) |
| 12–13 | `ldy #$06` / `sty Zp01` / `ldy #$00` / `sty Zp00` | Zp00/Zp01 = $0600 (RAM clear pointer) |
| 14 | `tya` | A = 0 |
| 15–19 | `Label_C74F`: `sta (Zp00),y` / `dey` / `bne` / `dec Zp01` / `bpl` | Clear $0000–$05FF (6 pages) |
| 20 | `jsr $C76A` | Initialize object state at $03D0–$03F8 |
| 21 | `lda Zp10` / `ora #$80` / `sta $2000` / `sta Zp10` | PPUCTRL |= $80 (NMI on) + shadow in Zp10 |
| 22 | `Label_C764`: `jsr $F09B` / `jmp $C764` | Infinite loop: audio init? (waits for NMI) |

**`$C76A` (Label_C76A)** — Object initialization:
```
    ldx #$29 / lda #$24
Label_C76E:
    sta $03D0,x   ; clear $03D0–$03F9 (42 bytes)
    dex / bne Label_C76E
    ldx #$00
Label_C776:
    lda $C271,x / sta $03DF,x   ; copy 6 bytes from $C271 to $03DF
    inx / cpx #$06 / bne Label_C776
    lda #$2C / sta $03D0
    lda #$2D / sta $03E6
    lda #$24 / sta $03E9
    lda #$16 / sta $03F2
    lda #$D0 / sta $03F5–$03F8
    lda #$00 / sta $4011 (APUDMCDIRECT)
    lda #$06 / sta $2001 (PPUMASK: show BG)
    jsr $C7E6 / jsr $C7CA
    jmp $C7B6
```

**`$C7B6` (Label_C7B6)** — Clear score/timer:
```
    lda #$00 / sta $0330 / sta $0331
```

Then enters main loop at **`$C7BE`**.

---

## 2. Main Loop — `$C7BE` onward

```
Label_C7BE:
    jsr $C7E0
    lda Zp10 / and #$E7 / sta Zp10     ; clear bits 3,4,5 of PPUCTRL shadow
    ... (main game loop continues)
```

The main loop runs continuously, synchronized with NMI via Zp10/Zp11 flags.

---

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

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

| Vector | Address | Handler |
|--------|---------|---------|
| NMI | $C7F1 | `NmiHandler` |
| RESET | $C735 | `Reset` |
| IRQ | $FFF0 | Unused (lands in vector-page padding) |

---

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

The NMI fires once per frame and drives the frame pacing:

```
NmiHandler ($C7F1):
    lda #$00 / sta $4016                   ; controller strobe
    lda Zp10 ($10) / and #$7F / sta $2000 / sta Zp10  ; PPUCTRL &= ~$80 (NMI off during frame)
    lda Zp11 ($11) / eor #$1A / sta $2001           ; PPUMASK ^= $1A (toggle bits)
    jsr $EF4A                              ; sprite/OAM update
    jsr $EF36                              ; PPU/scroll update
    lda $0396 / bne Label_C819             ; check state
    lda $0397 / bne Label_C819
    jsr $F085                              ; attract mode audio
Label_C819:
    jsr $F9A0                              ; gameplay audio
    jsr $F0BC                              ; sound effects
    lda Zp43 ($43)
    bne Label_C827
    lda #$FF / sta Zp43                    ; init Zp43 = $FF
Label_C827:
    lda Zp60 ($60)                         ; game state
    beq Label_C843                         ; 0: title/attract
    cmp #$01 / beq Label_C849              ; 1: gameplay
    cmp #$02 / beq Label_C83D              ; 2: bonus/stage clear
    jsr $D3F1 / lda #$00 / sta Zp77 / jmp $C84C  ; 3+: other
Label_C83D:
    jsr $CCD7 / jmp $C84C                  ; state 2
Label_C843:
    jsr $C865 / jmp $C84C                  ; state 0
Label_C849:
    jsr $CA31                              ; state 1
Label_C84C:
    ... (common NMI exit)
```

**NMI State Machine (Zp60 / $60):**
- **0 (Title/Attract):** `$C865` — attract mode logic
- **1 (Gameplay):** `$CA31` — main gameplay update
- **2 (Bonus/Transition):** `$CCD7` — stage clear, bonus
- **3+ (Other):** `$D3F1` — game over, high score, etc.

**Key NMI Operations:**
1. Controller strobe (`$4016`)
2. PPUCTRL/PPUMASK update (Zp10/Zp11 shadows)
3. Sprite/OAM update (`$EF4A`)
4. PPU/Scroll update (`$EF36`)
5. Audio engine (`$F9A0` gameplay, `$F085` attract, `$F0BC` SFX)
6. Game state dispatch via Zp60

---

## 5. Key Subsystems

### 5.1 Sprite/OAM System — `$EF4A` / `$EF36`
- `$EF4A`: Builds OAM at $0200 from object arrays
- `$EF36`: PPU scroll/register updates

### 5.2 Audio Engine
- **Attract:** `$F085` (called when $0396/$0397 set)
- **Gameplay:** `$F9A0` (music), `$F0BC` (sound effects)
- APU registers at $4000–$4013

### 5.3 Gameplay Logic — `$CA31` / `$CCD7` / `$D3F1` / `$C865`
- `$CA31`: Main gameplay (player, millipede, enemies, collision)
- `$CCD7`: Stage clear / bonus round
- `$D3F1`: Game over / high score
- `$C865`: Attract mode demo

### 5.4 Object State — $03D0+ region
- `$03D0–$03F8`: Initialized at reset from $C271 table
- `$0330–$0331`: Score/timer
- `$0396–$0397`: Attract mode flags
- `$03F5–$03F8`: Player position/state

### 5.5 Indirect Dispatch — `$EF15` (`jmp ($0002)`)
`jmp ($0002)` at $EF15 — target address in ZP $0002/$0003, set by caller. Not followed statically.

---

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

| Address | Name | Use |
|---------|------|-----|
| $00–$01 | `Zp00`/`Zp01` | 16-bit pointer (RAM clear) |
| $02–$03 | `Zp02`/`Zp03` | Indirect dispatch pointer (`jmp ($0002)`) |
| $10 | `Zp10` | PPUCTRL shadow (bit 7 = NMI enable) |
| $11 | `Zp11` | PPUMASK shadow (toggled via EOR #$1A) |
| $43 | `Zp43` | Audio state (init $FF) |
| $60 | `Zp60` | Game state (0=attract, 1=play, 2=bonus, 3+=other) |
| $77 | `Zp77` | Gameplay sub-state |
| $0330–$0331 | Score/Timer | Cleared at $C7B6 |
| $0396–$0397 | Attract flags | Checked in NMI for audio path |
| $03D0–$03F8 | Object init state | Copied from $C271 at reset |
| $03DF–$03E4 | Object params | 6 bytes from $C271 |
| $03F5–$03F8 | Player state | Initialized to $D0 |
| $4011 | APUDMCDIRECT | DMC direct load (silenced at reset) |
| $4016 | JOY1 | Controller strobe (NMI) |

---

## 7. Data Tables

| Table | Address | Description |
|-------|---------|-------------|
| Object init data | $C271 (`ObjectInitData`) | 6 bytes copied to $03DF at reset |
| Level data | $C000 (`LevelData`) | 1845 bytes of level/enemy pattern data |
| Audio data | $F24F (`AudioData`) | audio sequences |
| Vector page | $FE61 (`VectorPageData`) | padding/vectors |
| Level/millipede data | $C000–$C734 | 1845 bytes of level layouts, enemy paths (classified as data, referenced by code) |
| Audio sequences | $F000+ | Music/SFX data |

**Note:** The region $C000–$C734 (1845 bytes) is classified as `.byte` data but is heavily referenced by code (93+ references from `lda $Cxxx,x`, `bit $Cxxx` instructions). This is level/map data for the millipede and enemy movement patterns.

---

## 8. Summary of Execution Flow

```
Power On / Reset
    │
    ▼
Reset ($C735) ────► sei/cld, PPUCTRL=0, stack=$FF
    │
    ├─ Wait VBlank (poll $2002 bit 7)
    │
    ├─ Clear $0000–$05FF (6 pages via Zp00/Zp01)
    │
    ├─ jsr $C76A:
    │     Clear $03D0–$03F9
    │     Copy $C271→$03DF (6 bytes)
    │     Init $03D0=$2C, $03E6=$2D, $03E9=$24, $03F2=$16
    │     $03F5–$03F8 = $D0
    │     APUDMCDIRECT=0, PPUMASK=$06
    │     jsr $C7E6, $C7CA
    │
    ├─ PPUCTRL |= $80 (NMI on) → Zp10
    │
    ▼
Label_C764: jsr $F09B / jmp $C764  (wait for first NMI)
    │
    ▼ (NMI fires)

NMI ($C7F1) [once per frame]
    ├─ Controller strobe ($4016)
    ├─ Zp10 &= $7F → PPUCTRL (NMI off during frame)
    ├─ Zp11 ^= $1A → PPUMASK (toggle bits 1,3,4)
    ├─ jsr $EF4A (sprite/OAM update)
    ├─ jsr $EF36 (PPU/scroll update)
    ├─ Check $0396/$0397 → attract audio ($F085) if set
    ├─ jsr $F9A0 (gameplay audio)
    ├─ jsr $F0BC (sound effects)
    ├─ Zp43 init ($FF) if zero
    ├─ Dispatch on Zp60 ($60):
    │     0: jsr $C865 (attract) → $C84C
    │     1: jsr $CA31 (gameplay) → $C84C
    │     2: jsr $CCD7 (bonus) → $C84C
    │     3+: jsr $D3F1 → $C84C
    └─ $C84C: common exit → rti

Main Loop ($C7BE+)
    ├─ jsr $C7E0
    ├─ Zp10 &= $E7 (clear bits 3,4,5)
    ├─ Game logic (player, millipede, enemies)
    ├─ Collision detection
    ├─ Level progression
    └─ Loop (VBlank synchronized via Zp10/Zp11)
```

---

## 9. Naming and Residue

**Pass 1 complete** — 14,744 lines, canonical audit comments, 74.6% code. All 839 address-derived `Label_` definitions have been renamed: 12 semantic routine names (Reset, NmiHandler, MainLoop, GameplayUpdate, AttractMode, AttractAudio, GameOver, StageClear, InitObjects, ClearScore, SoundEffects, GameplayAudio) + 264 `SubC<addr>` entry points + 577 `Sub_8764_*` internal branch targets. No `Label_` remains.

**Pass 2 complete** — every `jsr`/`jmp` target is a named routine (semantic or `SubC<addr>`); internal branch targets use `<Routine>_Block`/`JoinBranchPaths` style names.

**Pass 3 complete** — 8 semantic zero-page aliases (PtrLo/Hi, Ptr2Lo/Hi, PpuCtrlShadow, PpuMaskShadow, AudioState, GameState, GameplaySubState); hardware register operands substituted via `apply_symbols.py`; data tables named: `LevelData` ($C000–$C734), `ObjectInitData` ($C271), `AudioData` ($F24F–$F984), `VectorPageData` ($FE61–$FFFF). Remaining zero-page slots retain neutral `ZpXX` names where role is not unique.

**Indirect dispatch** (not followed statically): `jmp ($0002)` at $EF15.

**Large data region** — $C000–$C734 (1845 bytes) classified as data but referenced by 93+ code instructions (`lda $Cxxx,x`, `bit $Cxxx`). This is level/enemy pattern data, not code.

**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).