disasm/_wip/Pac-Man (Tengen) (U)/OVERVIEW.md

# Pac-Man (Tengen) (U) — Game Flow from Power-On

This document describes the execution flow of the disassembled Pac-Man (Tengen) (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.

**Variant note:** `Pac-Man (U)` is an unrelated dump (different PRG). Both use horizontal mirroring.

---

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

**`Reset`** ($C033–$C0A0)

On power-on or reset, the 6502 jumps to **$C033** (non-$C000 entry). 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` / `sta $2001` | PPUCTRL=0, PPUMASK=0 (disable NMI, rendering) |
| 5–8 | `Label_C03D`: poll `$2002` via `bpl *-3` | Wait for VBlank |
| 9–10 | `ldx #$FF` / `txs` | Initialize stack pointer to $01FF |
| 11–12 | `lda #$00` / `tay` | A=0, Y=0 |
| 13–17 | `Label_C048`: `sta $0000,y` / `iny` / `cpy #$3E` / `bne` | Clear $0000–$003D (62 bytes) |
| 18–25 | `ldx #$08` / `ldy #$87` / `Label_C054`: `sta (Zp00),y` / `iny` / `bne` / `inc Zp01` / `cpx Zp01` / `bne` | Clear 9 pages from $8700 ($8700–$8F00) via Zp00/Zp01 |
| 26–27 | `lda #$06` / `sta $2001` | PPUMASK = $06 (show BG, hide sprites) |
| 28–31 | `lda #$00` / `sta $2005` ×2 | PPUSCROLL = 0,0 |
| 32–33 | `sta Zp41` / `sta Zp42` | Zp41=Zp42=0 (scroll shadows) |
| 34–35 | `sta $2000` / `sta $2001` | PPUCTRL=0, PPUMASK=0 |
| 36 | `tay` | Y=0 |
| 37–45 | `Label_C077`: `lda $C0EB,y` / `cmp $0052,y` / `bne Label_C086` / `iny` / `cpy #$0F` / `bne` / `beq Label_C0A0` | Compare 15-byte copyright string at $C0EB with RAM at $0052; if match, jump to $C0A0 |
| 46–49 | `Label_C086`: `lda #$00` / `tay` / `Label_C089`: `sta $0000,y` / `iny` / `bne` / `ldy #$00` | If mismatch: clear $0000–$00FF, Y=0 |
| 50+ | `Label_C0A0`... | Continue initialization (title screen, game setup) |

**Copyright check:** 15-byte string "COPYRIGHT 1984 NAMCO LTD. ALL RIGHTS RESERVED" at $C0EB compared against RAM at $0052. On cold start, RAM is garbage so check fails, clearing $0000–$00FF. On warm reset, if signature persists, skips extra clear.

---

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

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

| Vector | Address | Handler |
|--------|---------|---------|
| NMI | $C0FA | `NmiHandler` |
| RESET | $C033 | `Reset` |
| IRQ | $C16A | `IrqHandler` (single `rti` — unused placeholder) |

---

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

The NMI fires once per frame and handles PPU updates, controller input, and audio:

```
NmiHandler ($C0FA):
    pha / txa / pha / tya / pha           ; preserve A,X,Y
    lda #$1E / sta $2001                   ; PPUMASK = $1E (BG+sprites on, left 8px)
    lda #$00 / sta $2003 (OAMADDR)
    sta Zp40 ($40)                         ; clear Zp40
    lda Zp45 ($45) / sta $4014 (OAMDMA)    ; sprite DMA from Zp45 page
    jsr $DE3D                              ; sprite/OAM update
    jsr $E261                              ; game logic update
    jsr $C16B                              ; palette/PPU update
    lda Zp41 / sta $2005                   ; PPUSCROLL X
    lda Zp42 / sta $2005                   ; PPUSCROLL Y
    lda Zp47 / and Zp46 / and #$01         ; check game state flags
    asl a / ora Zp43                       ; combine flags
    sta $2000                              ; PPUCTRL update
    lda #$01 / sta $4016                   ; controller strobe on
    lda #$00 / sta $4016                   ; controller strobe off
    ldx #$08
Label_C13B:
    lda $4016 / and #$01 / cmp #$01 / ror Zp4D  ; read player 1 buttons → Zp4D
    lda $4017 / and #$01 / cmp #$01 / ror Zp4E  ; read player 2 buttons → Zp4E
    dex / bne Label_C13B                   ; 8 bits each
    ldx Zp4D
    lda Zp46 / and Zp47
    beq Label_C15A
    ldx Zp4E                               ; if Zp46&Zp47: use player 2 input
Label_C15A:
    stx Zp4F                               ; store combined input
    inc Zp4B                               ; frame counter
    lda Zp48
    bne Label_C165
    jsr $EE8F                              ; attract mode logic
Label_C165:
    pla / tay / pla / tax / pla / rti      ; restore, return (IRQ handler follows)
```

**Key ZP Flags:**
- `Zp40` ($40): Cleared each NMI
- `Zp41`/$42 ($41/$42): Scroll X/Y shadows
- `Zp43` ($43): PPUCTRL flag (bit 0)
- `Zp45` ($45): OAM DMA source page
- `Zp46`/$47 ($46/$47): Game state flags
- `Zp4D`/$4E ($4D/$4E): Player 1/2 button state (shifted in)
- `Zp4F` ($4F): Active player input
- `Zp4B` ($4B): Frame counter

---

## 4. Key Subroutines

### 4.1 `$DE3D` — Sprite/OAM Update
Builds OAM at $0200 from object state.

### 4.2 `$E261` — Main Game Logic
Pac-Man movement, ghost AI, collision, dots, power pellets.

### 4.3 `$C16B` — Palette/PPU Update
```
Label_C16B:
    lda $0299 / cmp #$0F / bne Label_C18C
    lda $2002 / lda #$3F / sta $2006 / lda #$00 / sta $2006
    ldy #$00
Label_C181:
    lda $0299,y / sta $2007 / iny / cpy #$10 / bne Label_C181
```
When $0299=$0F, uploads 16 bytes from $0299 to PPU palette ($3F00).

### 4.4 `$EE8F` — Attract Mode
Called when Zp48=0 (title screen).

### 4.5 Controller Reading
8-bit shift register read from $4016 (player 1) and $4017 (player 2), results in Zp4D/Zp4E, combined to Zp4F based on Zp46/Zp47.

---

## 5. Indirect Dispatch

Multiple `jmp ($0010)` at $C250, $D90F, $D9B6, $D3CA — target in ZP $0010/$0011 set by caller.
One `jmp ($00FE)` at $EFDA — target in ZP $00FE/$00FF.

Not followed statically; requires runtime tracing.

---

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

| Address | Name | Use |
|---------|------|-----|
| $10 | `Zp10` | General purpose |
| $40 | `Zp40` | Cleared each NMI |
| $41–$42 | `Zp41`/`Zp42` | Scroll X/Y shadows |
| $43 | `Zp43` | PPUCTRL flag |
| $45 | `Zp45` | OAM DMA source page |
| $46–$47 | `Zp46`/`Zp47` | Game state flags |
| $48 | `Zp48` | Attract mode flag |
| $4B | `Zp4B` | Frame counter |
| $4D–$4E | `Zp4D`/`Zp4E` | Player 1/2 button shift registers |
| $4F | `Zp4F` | Active input |
| $0200 | OAM buffer | Sprite DMA source |
| $0299 | Palette buffer | 16 bytes for $3F00 upload |
| $0052 | Copyright check | 15-byte RAM signature |

---

## 7. Data Tables

| Table | Address | Description |
|-------|---------|-------------|
| Copyright string | $C0EB | 15 bytes "COPYRIGHT 1984 NAMCO LTD. ALL RIGHTS RESERVED" |
| Palette upload | $0299 | 16 bytes, uploaded when $0299=$0F |
| Ghost AI / level data | $C000+ | Referenced by indirect dispatch |

---

## 8. Summary of Execution Flow

```
Power On / Reset
    │
    ▼
Reset ($C033) ────► sei/cld, PPU off, wait VBlank, stack=$FF
    │
    ├─ Clear $0000–$003D (62 bytes)
    ├─ Clear $8700–$8F00 (9 pages via Zp00/Zp01)
    ├─ PPUMASK=$06, PPUSCROLL=0,0
    ├─ Zp41=Zp42=0
    ├─ PPUCTRL=0, PPUMASK=0
    ├─ Copyright check: $C0EB vs $0052 (15 bytes)
    │     ├─ Match: jump to Label_C0A0
    │     └─ Mismatch: clear $0000–$00FF
    │
    ▼
Main Initialization (Label_C0A0+)
    │
    ▼
Main Loop (VBlank synchronized)
    │
    ▼ (NMI fires once per frame)

NMI ($C0FA)
    ├─ Preserve A,X,Y
    ├─ PPUMASK=$1E, OAMADDR=0, Zp40=0
    ├─ OAM DMA from Zp45 page
    ├─ jsr $DE3D (sprites), $E261 (game logic), $C16B (palette)
    ├─ Scroll from Zp41/Zp42
    ├─ PPUCTRL from Zp43/Zp46/Zp47
    ├─ Controller strobe + 8-bit read ($4016/$4017) → Zp4D/Zp4E
    ├─ Select active input → Zp4F
    ├─ inc Zp4B (frame counter)
    ├─ Zp48=0 → jsr $EE8F (attract)
    └─ Restore, rti
```

---

## 9. Naming and Residue

**Pass 1 complete** — 4,482 lines, 192 `Label_` definitions, canonical audit comments, 19.5% code. 16 seeded routine entries from table references.

**Pass 2 outstanding** — No semantic names applied; all 192 labels remain address-derived `Label_XXXX`.

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

**Indirect dispatch** (not followed statically):
- `jmp ($0010)` at $C250, $D90F, $D9B6, $D3CA
- `jmp ($00FE)` at $EFDA

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