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

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

This document describes the execution flow of the disassembled Pac-Man (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 (Tengen) (U) is an unrelated dump (different PRG). Both use horizontal mirroring.

Unusual RESET vector: The RESET vector points to $FF00 (inside the vector page padding), not into the PRG code at $C000+. The PRG at $FF00 is all $FF bytes (invalid opcode). The actual initialization code begins at $C042 (Label_C042), reached via an unknown mechanism — possibly the dump has a corrupted vector, or the game uses a hardware reset quirk. The disassembly traces from $C042 as the effective reset entry.

---

1. Effective Reset Entry — $C042 (Label_C042)

Label_C042 ($C042–$C0A0)

The code at $C042 performs cold-start hardware initialization:

Step	Code	Purpose
1–2	ldx #$FF / txs	Initialize stack pointer to $01FF
3–4	lda #$00 / tay	A=0, Y=0
5–9	Label_C048: sta $0000,y / iny / cpy #$3E / bne	Clear $0000–$003D (62 bytes)
10–17	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
18–19	lda #$06 / sta $2001	PPUMASK = $06 (show BG, hide sprites)
20–23	lda #$00 / sta $2005 ×2	PPUSCROLL = 0,0
24–25	sta Zp41 / sta Zp42	Zp41=Zp42=0 (scroll shadows)
26–27	sta $2000 / sta $2001	PPUCTRL=0, PPUMASK=0
28	tay	Y=0
29–37	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
38–41	Label_C086: lda #$00 / tay / Label_C089: sta $0000,y / iny / bne / ldy #$00	If mismatch: clear $0000–$00FF, Y=0

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.

Note: The code from $C042 onward is identical to Pac-Man (Tengen) (U) from its Label_C03D ($C03D) onward. The only difference is the entry point ($C033 vs $C042) and the initial sei/cld/PPU off which are missing here (possibly executed before jumping to $C042).

---

2. Interrupt Vectors — CPU $FFFA–$FFFF

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

Vector	Address	Handler
NMI	$C0FA	NmiHandler
RESET	$FF00	Points into vector padding ($FF bytes) — likely corrupted dump
IRQ	$C16A	IrqHandler (single rti — unused placeholder)

Actual reset entry: $C042 (Label_C042), traced as effective cold start.

---

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

Identical to Pac-Man (Tengen) (U) — see that document for full details. Summary:

NmiHandler ($C0FA):
    pha / txa / pha / tya / pha
    lda #$1E / sta $2001
    lda #$00 / sta $2003 / sta Zp40
    lda Zp45 / sta $4014 (OAMDMA)
    jsr $DE3D (sprites) / jsr $E261 (game logic) / jsr $C16B (palette)
    lda Zp41/Zp42 → $2005 (scroll)
    lda Zp47/Zp46/Zp43 → $2000 (PPUCTRL)
    Controller strobe + 8-bit read ($4016/$4017) → Zp4D/Zp4E
    Select active input → Zp4F
    inc Zp4B (frame counter)
    Zp48=0 → jsr $EE8F (attract)
    pla / tay / pla / tax / pla / rti

---

4. Key Subroutines

Identical to Pac-Man (Tengen) (U):

• $DE3D — Sprite/OAM update
• $E261 — Main game logic
• $C16B — Palette/PPU update (uploads 16 bytes from $0299 when $0299=$0F)
• $EE8F — Attract mode logic
• Controller reading: 8-bit shift from $4016/$4017 → Zp4D/Zp4E → Zp4F

---

5. Indirect Dispatch

Same as Tengen variant:

• jmp ($0010) at $C250, $D90F, $D9B6, $D3CA
• jmp ($00FE) at $EFDA

Not followed statically.

---

6. Memory Map (Key Zero Page / RAM)

Address	Name	Use
$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

---

8. Summary of Execution Flow

Power On / Reset
    │
    ▼ (Vector points to $FF00 — $FF padding)
    │
    ▼ (Unknown mechanism reaches $C042)
Label_C042 ($C042) ────► 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) [identical to Tengen variant]
    ├─ 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,506 lines, 194 Label_ definitions, canonical audit comments, 19.6% code. 16 seeded routine entries from table references (same as Tengen variant).

Pass 2 outstanding — No semantic names applied; all 194 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

Unusual RESET vector — Points to $FF00 (vector page padding). The disassembly traces from $C042 as the effective entry. This may indicate a bad dump or a hardware quirk.

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