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