disasm/Lode Runner (U)/OVERVIEW.md

Lode Runner (U) — Game Flow from Power-On

This document describes the execution flow of the disassembled Lode Runner (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 → $C000

Reset ($C000–$C029)

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

Step	Code	Purpose
1–2	sei / cld	Disable interrupts, clear decimal mode
3–4	ldx #$FF / bne Label_C00A	X=$FF, branch always taken (delay slot?)
5–6	txs / jmp $C012	Initialize stack pointer to $01FF
7–8	ldy #$00 / sty Zp00 / sty Zp01	Zp00/Zp01 = $0000 (RAM clear pointer)
9	tya / ldx #$08	A=0, X=8 (8 pages to clear)
10–14	Label_C01B: sta (Zp00),y / iny / bne / inc Zp01 / dex / bne	Clear $0000–$07FF (8 pages of 256 bytes)
15	lda #$23 / sta ZpE5	ZpE5 ($E5) = $23
16	jmp $C3A6	Jump to main initialization

No warm-start signature check — full 2 KB clear every reset.

---

2. Interrupt Vectors — CPU $FFFA–$FFFF

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

Vector	Address	Handler
NMI	$C02C	NmiHandler
RESET	$C000	Reset
IRQ	$FFF9	IrqHandler (single rti — unused)

---

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

The NMI fires once per frame and implements a two-path structure controlled by Zp10 ($10):

NmiHandler ($C02C):
    pha / txa / pha / tya / pha           ; preserve A,X,Y
    jsr $C27C                             ; common NMI setup
    lda Zp10 ($10)
    beq Label_C050                        ; Zp10=0: Path A
    lda #$00 / sta Zp10                   ; clear Zp10
    lda Zp11 ($11) / tax
    beq Label_C043                        ; Zp11=0: Path B
    bne Label_C050                        ; Zp11≠0: Path A
Label_C043:
    jsr $C18E                             ; Path B: PPU/game update
    lda #$20 / ldx #$00 / jsr $C178       ; PPU write ($2000 + X=0)
    jmp $C0A4                             ; → main NMI exit
Label_C050:                               ; Path A: Palette/sprite update
    lda #$3F / ldx #$08 / jsr $C178       ; PPUADDR=$3F08 (palette)
    inc Zp9E ($9E)                        ; frame sub-counter
    lda Zp9E / and #$1F / bne Label_C07B  ; every 32 frames
    inc Zp9F ($9F)                        ; secondary counter
    lda Zp9F / and #$03 / tax             ; 0-3 selector
    lda #$0F / jsr $C006                  ; PPUDATA write
    lda $C39E,x / jsr $C006               ; palette data from table
    lda #$00 / jsr $C006                  ; clear
    lda #$30 / jsr $C006                  ; $30
Label_C07B:
    lda Zp9E / and #$07 / bne Label_C0A4  ; every 8 frames
    lda #$3F / ldx #$0C / jsr $C178       ; PPUADDR=$3F0C
    inc Zp72 ($72)                        ; tertiary counter
    lda Zp72 / and #$03 / tax             ; 0-3 selector
    lda #$0F / jsr $C006
    lda #$38 / jsr $C006
    lda #$28 / jsr $C006
    lda $C3A2,x / jsr $C006               ; sprite palette data
Label_C0A4:                               ; Common NMI exit
    lda Zp03 ($03) / sta $2001 (PPUMASK)  ; apply PPUMASK
    jsr $C1E1                             ; sprite/OAM update
    lda ZpDB ($DB)
    beq Label_C0D1                        ; if 0: skip gameplay
    lda Zp06 ($06) / and #$10 / beq Label_C0D1  ; bit 4 check
    jsr $C2C6 / jsr $DE9F / jsr $C1D7     ; gameplay logic
    jmp Label_C127                        ; rti
Label_C0BF:                               ; Alternate entry (ZpDB=0?)
    jsr $C1E1
    lda Zp06 / and #$10 / beq Label_C0BF  ; wait for bit 4
    jsr $DE9F / jsr $C1D7 / jsr $C2B3
    jmp Label_C127
Label_C0D1:
    lda ZpB7 ($B7)
    beq Label_C127                        ; if 0: rti
    jsr $E271                             ; level/game init
    inc ZpB9 / lda ZpB9 / cmp ZpB8 / bcc Label_C127
    lda #$00 / sta ZpB9                   ; reset counter
    ... (level transition logic)
Label_C127:
    pla / tay / pla / tax / pla / rti     ; restore, return

Two NMI Modes:

• Path A (Zp10≠0): Palette/sprite updates, periodic palette cycling (every 8/32 frames), sprite DMA
• Path B (Zp10=0, Zp11=0): jsr $C18E → PPU register update → main exit

Key ZP Flags:

• Zp10 ($10): NMI path selector (0=Path B, non-zero=Path A)
• Zp11 ($11): Sub-path selector for Path B
• Zp9E ($9E): Frame sub-counter (palette cycling)
• Zp9F ($9F): Secondary frame counter
• Zp72 ($72): Tertiary counter (sprite palette)
• ZpDB ($DB): Gameplay active flag
• Zp06 ($06): Bit 4 = gameplay trigger
• ZpB7 ($B7): Level transition flag
• Zp03 ($03): PPUMASK shadow

---

4. Main Initialization — $C3A6 (from Reset)

After reset jumps to $C3A6, the game initializes title screen and enters main loop. The main loop is driven by NMI synchronization — the main thread waits for NMI to signal frame completion via ZP flags.

Key initialization routines (reached from $C3A6):

• $C178: PPU address/data write helper (A=addr high, X=addr low → $2006/$2006/$2007)
• $C18E: PPU control update (reads Zp03→PPUMASK, Zp10→PPUCTRL)
• $C1E1: Sprite/OAM update (builds OAM at $0200)
• $C27C: Common NMI setup (called at NMI entry)

---

5. Key Subsystems

5.1 PPU Helper — $C178 / $C006

• $C178: Set PPUADDR from A (high) / X (low), write via $2006 twice
• $C006: Write A to PPUDATA ($2007), RTS
• $C18E: Read PPUSTATUS, write Zp03→PPUMASK, Zp10→PPUCTRL

5.2 Sprite/OAM System — $C1E1 / $C1D7

• Builds OAM at $0200 from object state arrays
• $C1D7: Called from NMI paths for per-frame sprite update

5.3 Gameplay Logic — $C2C6, $DE9F, $C1D7, $C2B3

• $C2C6: Player/input handling
• $DE9F: Enemy/guard AI
• $C2B3: Level progression, scoring

5.4 Level Data & Transitions — $E271, $C0E4–$C123

• $E271: Level load/init
• $C0E4: State machine on ZpBE/ZpBA (pointer to level data)
• Level data tables at $C2F0, $C378, $C39E, $C3A2

5.5 Audio — $C12D / $C143 / $C16E

• APU register writes ($4000–$4003) for pulse channels
• Frequency data from $C2F0, $C378
• Called from level transition / gameplay

---

6. Memory Map (Key Zero Page / RAM)

Address	Name	Use
$00–$01	Zp00/Zp01	16-bit pointer (RAM clear, PPU)
$03	Zp03	PPUMASK shadow
$06	Zp06	Gameplay flags (bit 4 = trigger)
$10	Zp10	NMI path selector (0=title, ≠0=game)
$11	Zp11	NMI sub-path selector
$12–$13	Zp12/Zp13	Object/sprite pointers
$20–$21	Zp20/Zp21	Player position (X/Y)
$26	Zp26	Player state/animation
$28	Zp28	Player velocity
$32–$35	Zp32–Zp35	Enemy/guard positions
$39	Zp39	Level timer
$52–$5F	Zp52–Zp5F	Sprite attribute buffers
$72	Zp72	Sprite palette cycle counter
$85–$86	Zp85/Zp86	Level data pointers
$9E–$9F	Zp9E/Zp9F	Frame counters (palette cycling)
$B7	ZpB7	Level transition trigger
$B8–$B9	ZpB8/ZpB9	Level transition counters
$BA–$BF	ZpBA–ZpBF	Level data pointer + state
$DB	ZpDB	Gameplay active flag
$E5	ZpE5	Init constant ($23)
$0200	OAM buffer	64 sprites (DMA source)
$0300+	Game state arrays	Player, enemies, level data

---

7. Data Tables

Table	Address	Description
Palette data (BG)	$C39E	4 entries, indexed by Zp9F&3
Palette data (sprites)	$C3A2	4 entries, indexed by Zp72&3
Audio frequency low	$C2F0	Note→period low byte
Audio frequency high	$C378	Note→period high byte (×2 + index)
Level data pointer	ZpBA/ZpBC	Indirect pointer to level scripts

---

8. Summary of Execution Flow

Power On / Reset
    │
    ▼
Reset ($C000) ────► sei/cld, stack=$FF
    │
    ├─ Clear $0000–$07FF (8 pages via Zp00/Zp01)
    │
    ├─ ZpE5 = $23
    │
    ▼
jmp $C3A6 (Main Initialization)
    │
    ├─ Title screen setup
    ├─ PPU/APU init
    └─ Enter main loop (VBlank synchronized)

Main Loop (implicit, VBlank-driven)
    │
    ▼ (NMI fires once per frame)

NMI ($C02C)
    ├─ Preserve A,X,Y
    ├─ jsr $C27C (common setup)
    ├─ lda Zp10
    │     ├─ =0 (Title/Menu):
    │     │    lda Zp11
    │     │    ├─ =0: jsr $C18E (PPU update), $C178, jmp $C0A4
    │     │    └─ ≠0: Path A (palette cycling)
    │     │
    │     └─ ≠0 (Gameplay):
    │          lda #$00 / sta Zp10
    │          lda Zp11 / tax
    │          ├─ =0: jsr $C18E, $C178, jmp $C0A4
    │          └─ ≠0: Path A (palette cycling)
    │
    ├─ Path A (Label_C050):
    │     Palette writes to $3F08/$3F0C every 8/32 frames
    │     inc Zp9E, Zp9F, Zp72
    │
    ├─ Common Exit ($C0A4):
    │     lda Zp03 → PPUMASK
    │     jsr $C1E1 (sprite update)
    │     lda ZpDB
    │     ├─ =0: Label_C0BF (wait for Zp06 bit 4)
    │     └─ ≠0: Check Zp06 bit 4
    │           ├─ Clear: Label_C0D1 (level transition check)
    │           └─ Set: jsr $C2C6, $DE9F, $C1D7 (gameplay)
    │
    └─ Label_C127: Restore A,X,Y, rti

Gameplay (when ZpDB≠0, Zp06&$10)
    ├─ $C2C6: Player control
    ├─ $DE9F: Enemy AI
    ├─ $C1D7: Sprite update
    ├─ $C2B3: Level/scoring
    └─ Level transition: $E271, $C0E4 state machine

---

9. Naming and Residue

Pass 1 complete — 11,057 lines, 627 Label_ definitions, canonical audit comments, 52.6% code.

Pass 2 complete (2026-10-20) — All 627 label definitions renamed. 196 semantic routine entry points named via _tools/pass2.py derive/apply using a hand-curated routinemap; remaining 431 internal branch targets named as <Routine>_Block[_n]. Zero Label_Cxxxx definitions remain.

Pass 3 partial (2026-10-20) — _tools/apply_symbols.py substituted 85 operands (83 hardware registers + 2 single-name zero-page operands). Zero multi-alias residue. 2 semantic zero-page aliases applied; remaining 150 zero-page slots retain neutral ZpXX names in locals.inc. Data tables/structures named in Memory Map section.

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