disasm/_wip/Popeye (JU) (PRG 1)/OVERVIEW.md

Popeye (JU) (PRG 1) — Game Flow from Power-On

This document describes the execution flow of the disassembled Popeye (JU) (PRG 1) 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.

Companion note: Popeye (JU) (PRG 0) holds a different PRG image of the same title (different mirroring flag: Vertical vs Horizontal). Neither is currently known to be a superset of the other.

---

1. Reset Vector — CPU $FFFC → $C649

Reset ($C649–$C683)

Identical to PRG 0 — On power-on or reset, the 6502 jumps to $C649 (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 #$10 / sta $2000	PPUCTRL = $10 (NMI off, sprite $0000, BG $0000, 8×8)
5–6	ldx #$FF / txs	Initialize stack pointer to $01FF
7–11	Label_C653: poll $2002 via and #$80 / beq	Wait for VBlank (bit 7 of PPUSTATUS)
12–13	ldy #$07 / sty Zp01 / ldy #$00 / sty Zp00	Zp00/Zp01 = $0700 (RAM clear pointer)
14	tya	A = 0
15–19	Label_C663: sta (Zp00),y / dey / bne / dec Zp01 / bpl	Clear $0000–$07FF (8 pages)
20	jsr $C686	Initialize player/object state at $0500–$0504
21	lda #$01 / sta Zp60	Zp60 ($60) = 1 (game state)
22	lda #$00 / sta Zp63	Zp63 ($63) = 0
23	lda Zp10 / eor #$80 / sta $2000 / sta Zp10	PPUCTRL ^= $80 (toggle NMI enable) + shadow
24	Label_C680: jsr $EE74 / jmp $C680	Infinite loop: waits for first NMI

$C686 (Label_C686) — Player state init (identical to PRG 0):

    lda #$11 / sta $0500 / sta $0502
    lda #$03 / sta $0501
    lda #$01 / sta $0503
    ldx #$19 / lda #$24
Label_C69C:
    sta $0504,x   ; fill $0504–$051C with $24 (25 bytes)
    dex / bne Label_C69C
    ldx #$00

Then falls through to $C6A4 (main loop entry).

---

2. Main Loop — $C6A4 onward

Identical to PRG 0 — main loop runs synchronized with NMI via Zp10/Zp60/Zp63 flags.

---

3. Interrupt Vectors — CPU $FFFA–$FFFF

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

Vector	Address	Handler
NMI	$C701	NmiHandler
RESET	$C649	Reset
IRQ	$FFF0	IrqHandler (single sta (Zp16,x) — undocumented opcode $81, effectively unused)

---

4. NMI / Frame Heartbeat — NmiHandler ($C701)

Identical to PRG 0 — The NMI fires once per frame and implements a state machine dispatching on Zp30/Zp31/Zp60/Zp63:

NmiHandler ($C701):
    lda Zp10 ($10) / and #$7F / sta $2000 / sta Zp10  ; PPUCTRL &= ~$80 (NMI off during frame)
    lda Zp11 ($11) / eor #$18 / sta $2001             ; PPUMASK ^= $18 (toggle bits 3,4)
    jsr $ED34                                         ; sprite/OAM update
    jsr $ED20                                         ; PPU/scroll update
    lda $0400 / bne Label_C724                        ; check $0400
    lda $0401 / bne Label_C724                        ; check $0401
    jsr $EE5E                                         ; attract mode audio
Label_C724:
    jsr $F970                                         ; gameplay audio
    jsr $EE89                                         ; sound effects
    lda Zp43 ($43)
    bne Label_C732
    lda #$FF / sta Zp43                               ; init Zp43 = $FF
Label_C732:
    lda Zp30 ($30)
    beq Label_C73C
    jsr $CA8B / jmp $C75D                             ; state: Zp30≠0
Label_C73C:
    lda Zp31 ($31)
    beq Label_C746
    jsr $CAD4 / jmp $C75D                             ; state: Zp31≠0
Label_C746:
    lda Zp60 ($60)
    bne Label_C754
    lda Zp63 ($63)
    beq Label_C75A
    jsr $CB12 / jmp $C75D                             ; state: Zp60=0, Zp63≠0
Label_C754:
    jsr $C76A / jmp $C75D                             ; state: Zp60≠0
Label_C75A:
    jsr $C89B                                         ; state: Zp60=0, Zp63=0
Label_C75D:
    ... (common NMI exit → rti)

NMI State Machine:

Condition	Handler	Description
$0400≠0 or $0401≠0	$EE5E	Attract mode audio
Zp30≠0	$CA8B	Gameplay mode A
Zp31≠0	$CAD4	Gameplay mode B
Zp60≠0	$C76A	Gameplay mode C
Zp60=0, Zp63≠0	$CB12	Bonus/stage transition
Zp60=0, Zp63=0	$C89B	Title/attract mode

---

5. Key Subsystems

5.1 Sprite/OAM System — $ED34 / $ED20

• $ED34: Builds OAM at $0200 from object arrays
• $ED20: PPU scroll/register updates

5.2 Audio Engine

• Attract: $EE5E (called when $0400/$0401 set)
• Gameplay: $F970 (music), $EE89 (sound effects)
• APU registers at $4000–$4013

5.3 Gameplay Logic

• $CA8B / $CAD4 / $C76A / $CB12 / $C89B: State-specific gameplay updates
• Player (Popeye), enemies (Bluto, Sea Hag), projectiles, collectibles (spinach, hearts, letters)

5.4 Level Data — $C000–$C648 region

• 1609 bytes classified as .byte data but referenced by 148+ code instructions
• Contains level layouts, enemy paths, platform positions
• Referenced via lda $Cxxx,x, bit $Cxxx — this is level/map data, not code

5.5 Indirect Dispatch — $ED03 (jmp ($0002))

jmp ($0002) at $ED03 — target address in ZP $0002/$0003, set by caller. Not followed statically. (Address differs slightly from PRG 0's $ECFF.)

---

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 #$18)
$30–$31	Zp30/Zp31	Gameplay state selectors
$43	Zp43	Audio state (init $FF)
$60	Zp60	Game state (set 1 at reset)
$63	Zp63	Sub-state (cleared at reset)
$0200	OAM buffer	Sprite DMA source
$0400–$0401	Attract flags	Checked in NMI for audio path
$0500–$051C	Player state	Initialized at $C686 ($11,$03,$11,$24×25)

---

7. Data Tables

Table	Address	Description
Level/map data	$C000–$C648	1609 bytes of level layouts, enemy paths (referenced by code)
Audio sequences	$F970+	Music/SFX data

---

8. Summary of Execution Flow

Identical to PRG 0 — See Popeye (JU) (PRG 0)/OVERVIEW.md for full flow diagram. The only differences between PRG 0 and PRG 1 are:

1. Mirroring: PRG 0 = Vertical, PRG 1 = Horizontal (iNES header byte 6 bit 0)
2. PRG bytes differ slightly — Different build/revision
3. Indirect dispatch address: PRG 0 at $ECFF, PRG 1 at $ED03
4. Seeded routine entries: PRG 0 has $EF19, $EF3A, $EFBF, $EFE0, $F002, $F071; PRG 1 has $EF1D, $EF3E, $EFC3, $EFE4, $F006, $F057 (offset by a few bytes)

---

9. Naming and Residue

Pass 1 complete — 14,855 lines, canonical audit comments, 72.3% code. 6 seeded routine entries from table references.

Pass 2 complete — all 876 Label_ definitions renamed: 2 semantic entry names (Reset, NmiHandler) + 315 SubC<addr> entry points + 561 <Routine>_Block_<addr> internal branch targets. No Label_ remains. Every jsr/jmp target is a named routine.

Pass 3 complete — 4 semantic zero-page aliases (PtrLo/Hi, Ptr2Lo/Hi) added to locals.inc; 80 operands substituted via apply_symbols.py (15 single + 65 hardware); data tables named: LevelData ($C000–$C648), AudioData ($F08C–$F832), VectorPageData ($FCCE–$FFEF). Remaining zero-page slots retain neutral ZpXX names.

Indirect dispatch (not followed statically): jmp ($0002) at $ED03.

Large data region — $C000–$C648 (1609 bytes) classified as data but referenced by 148+ code instructions. This is level/enemy pattern data.

PRG 0 vs PRG 1 — Same vectors, same structure. PRG 0: Vertical mirroring. PRG 1: Horizontal mirroring. PRG bytes differ slightly (different build).

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