disasm/Donkey Kong 3 (JUE)/OVERVIEW.md

Donkey Kong 3 (JUE) — Game Flow from Power-On

This document describes the execution flow of the disassembled Donkey Kong 3 (JUE) 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 ROM (whole-ROM compare).

---

1. Reset Vector — CPU $FFFC → $C000

ResetHandler ($C000–$C08C)

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

Step	Code	Purpose
1–2	cld / sei	Clear decimal mode, disable interrupts
3–6	Poll $2002 twice (bpl *-3)	Wait for two full VBlank periods (PPU warm-up)
7–8	ldx #$00 / txs	Initialize stack pointer to $01FF
9–11	ldx FrameCounter / ldy #$07 / sty WorkPointerOrValueHi	FrameCounter ($27) → X; Y=$07 → WorkPointerOrValueHi ($02)
12	ldy #$00 / sty WorkPointerOrValueLo	Y=$00 → WorkPointerOrValueLo ($01)
13–21	Clear RAM $0000–$07FF	8 pages via (WorkPointerOrValueLo),Y; dec WorkPointerOrValueHi loops pages
22	txa / bne FinishResetInitialization	If FrameCounter was non-zero, skip full clear
23	ldx #$5F	Alternate init value for warm start
24	stx Ram_06F0	Store signature at $06F0
25	jsr ClearNametable2400WithTileFF ($C1A2)	Fill nametable $2400 with $FF
26	jsr HideAllOamSprites ($C1EA)	Hide all 64 sprites (Y=$F4)
27	sty $2005 ×2	PPUSCROLL = 0,0
28	iny / sty GameMode	Y=$01 → GameMode ($3A) = title mode
29	lda #$0F / sta $4015	Enable all APU channels
30	lda #$90 / sta $2000 / sta PPUCTRL	PPUCTRL: NMI on, sprite $0000, BG $1000, 8×8 sprites

Warm-start signature: FrameCounter ($27) and Ram_06F0 survive the RAM clear. If FrameCounter ≠ 0 on reset, the game skips the full 2 KB clear and uses X=$5F.

---

2. Main Loop Dispatcher — SelectMainLoopAudioPath ($C047)

After reset initialization, control flows to SelectMainLoopAudioPath ($C047), the main loop dispatcher:

SelectMainLoopAudioPath ($C047):
    lda GameMode           ; $3A
    beq RunAudioOnlyFrame  ; 0 = title/attract: audio only
    lda PlayerModeOrScreenPhase  ; $3C
    cmp #$01
    bne RunMainGameFrame   ; !=1: gameplay frame
RunAudioOnlyFrame ($C051):
    jsr UpdateAudioEngine  ; $F820 (banked audio)
RunMainGameFrame ($C054):
    jsr DecrementGameplayTimers      ; $C3B0
    jsr UpdateTitleAndGameplayState  ; $C0BA
    jsr RequestNmiProcessing         ; $C05F
    beq SelectMainLoopAudioPath      ; loop until NMI signals frame ready

RequestNmiProcessing ($C05F): Sets NmiFrameDelay ($32) = 1, signaling NMI to do work.

WaitForFrameReady ($C063): Called after RequestNmiProcessing returns (via beq loop):

    jsr AdvancePseudoRandomState  ; $C42F (PRNG)
    lda FrameReadyFlag            ; $30
    beq WaitForFrameReady         ; wait for NMI to set it
    inc FrameCounter              ; $27
    dec NmiFrameDelay             ; $32
    lda #$00 / sta FrameReadyFlag ; clear for next frame
    rts

---

3. Interrupt Vectors — CPU $FFFA–$FFFF

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

Vector	Address	Handler
NMI	$C08D	NmiHandler
RESET	$C000	ResetHandler
IRQ	$C000	ResetHandler (reused — unused placeholder)

---

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

The NMI fires once per frame and performs PPU updates, controller reading, and signals frame completion:

NmiHandler ($C08D):
    pha / txa / pha / tya / pha           ; preserve A,X,Y
    lda #$00 / sta $2003                   ; OAMADDR = 0
    lda #$02 / sta $4014                   ; OAM DMA from $0200
    lda NmiFrameDelay  ($32)
    beq CompleteNmiAndRestoreRegisters    ; if 0: minimal NMI (title screen)
    jsr RunQueuedPpuTransfer       ; $C1F5 — process queued PPU writes
    jsr UpdatePpuTransferQueue     ; $C370 — update queue pointers
    jsr ResetPpuScroll             ; $C424 — reset scroll registers
    jsr UpdateControllerState_C328 ; $C328 — read controllers
    ldy #$01 / sty FrameReadyFlag  ; $30 = 1 (signal main loop)
CompleteNmiAndRestoreRegisters ($C0B0):
    lda #$01 / sta NmiWorkMode     ; $33 = 1 (signal NMI work done)
    pla / tay / pla / tax / pla / rti

Two NMI modes:

• NmiFrameDelay = 0 (title/attract): Only OAM DMA, no game logic.
• NmiFrameDelay = 1 (gameplay): Full PPU queue flush, controller read, scroll reset, sets FrameReadyFlag.

---

5. Title / Gameplay State Machine — UpdateTitleAndGameplayState ($C0BA)

UpdateTitleAndGameplayState ($C0BA):
    lda GameMode ($3A)
    bne HandleStartAndPlayerSelection  ; !=0: player select
    lda ControllerButtons ($1A)
    and #$10        ; START button
    beq ClearScreenSubstate
    ldy ScreenSubstate ($36)
    bne DispatchCurrentScreenState
    iny / sty ScreenSubstate           ; first START press: advance substate
    ldy CurrentScreenState ($3B)
    cpy #$0D / beq StartGameplayCountdown
    cpy #$06 / bne DispatchCurrentScreenState
    ldx #$07
    jsr CopyPlayerStateDefaults        ; init player timers
    ; ... sets CurrentScreenState=$0D, PPUMASK=$0E, PPUCTRL=$81
    jsr ClearAudioRequestFlags
    beq SelectAlternateAudioMode       ; audio request $02
ClearScreenSubstate ($C104):
    lda #$00 / sta ScreenSubstate
DispatchCurrentScreenState ($C108):
    lda CurrentScreenState ($3B)
    jsr DispatchScreenStateHandler ($C3C6)
ScreenStateHandlerTable ($C10D): 14 entries (2 bytes each)
    .word Handler_$C663, $C6AB, $C6D4, $C6EB, $C755, $C7C2, $C7DD, $C8C6, $C8C8
    .word $C93E, $C94B, $C998, $C9AF, $C9C7, $C07C

GameMode = 0 (Title):

• Waits for START press (ControllerButtons & $10)
• ScreenSubstate tracks first press vs. subsequent
• CurrentScreenState selects which title screen handler (14 states)
• State $0D = start gameplay countdown (sets GameplayTimer=$14, CurrentScreenState=$0C)
• State $06 = player select (copies defaults, sets up audio)

GameMode ≠ 0 (Player Select / Gameplay):

• HandleStartAndPlayerSelection ($C129): reads START/SELECT, sets GameMode/CurrentScreenState
• DispatchGameModePhase ($C142): dispatches on PlayerModeOrScreenPhase ($3C)
• Screen state handlers at $C18D via second table ($C192): 15 entries for gameplay screens

---

6. Key Subsystems

6.1 PPU Transfer Queue — $C1F5 / $C370

• QueuedPpuTransferCount ($34) tracks pending transfers
• Source pages from QueuedPpuTransferSourcePageTable ($C20A)
• Destination offsets from QueuedPpuTransferDestinationOffsetTable ($C206)
• RunQueuedPpuTransfer processes one per NMI; UpdatePpuTransferQueue refills

6.2 Controller Input — UpdateControllerState_C328 ($C328)

• Reads $4016 (strobe) + shift register
• Stores buttons in ControllerButtons ($1A), pressed edges in ControllerPressedOrScriptInput ($1B)
• Second controller in SecondControllerPressed ($1D)

6.3 Audio Engine — UpdateAudioEngine ($F820)

• Banked at $F800+ (called via trampoline)
• 4-channel sequencer: AudioChannelStateArray ($F0–$F3), sequence pointers ($F9/$FA)
• Note/period tables at $F970, $FAB3
• Sound effects via StartSoundEffect ($FAE6)

6.4 Screen State Handlers — DispatchScreenStateHandler ($C3C6)

• Title: 14 handlers (attract, copyright, high score, player select, etc.)
• Gameplay: 15 handlers (level intro, gameplay, bonus, intermission, game over, etc.)
• Each handler manages its own objects, timers, and transitions

6.5 Object / Actor System

• ObjectState ($0300+): 16+ slots, fields for type, position, timer, animation
• ActorFlags ($84), ActorX ($85), ActorY ($86), ActorStateArray ($70+)
• Collision detection via ScreenCollisionState ($44), CollisionMask ($BF)

6.6 PRNG — AdvancePseudoRandomState ($C42F)

• Called once per frame in WaitForFrameReady
• Used for enemy spawn patterns, bonus timing

---

7. Memory Map (Key Zero Page / RAM)

Address	Name (from locals.inc)	Use
$00	ControllerSerialBits	Controller shift register bits
$01–$02	WorkPointerOrValueLo/Hi	General 16-bit pointer (RAM clear, PPU)
$03	SourceRecordPointerLo	PPU transfer source pointer
$1A	ControllerButtons	Current button state
$1B	ControllerPressedOrScriptInput	Edge-detected presses
$20–$27	GameplayTimerArray	8 gameplay timers
$21	GameplayTimer	Main gameplay countdown
$25	ScreenSelectionPositionOrDelay	Menu cursor / delay
$27	FrameCounter	Global frame counter
$28–$2F	SavedGameplayTimerArray	Backup timers
$30	FrameReadyFlag	Set by NMI, cleared by main loop
$31	CollisionResultFlag	Collision detection result
$32	NmiFrameDelay	NMI work trigger (0=skip, 1=do work)
$33	NmiWorkMode	NMI completion signal
$34	QueuedPpuTransferCount	Pending PPU transfers
$36	ScreenSubstate	Title screen sub-state
$37	StartInputLatch	START button latch
$38	SelectedPlayerAndScreenFlags	Player/screen selection
$3A	GameMode	0=title, 1=player select, 2+=gameplay
$3B	CurrentScreenState	Active screen handler index
$3C	PlayerModeOrScreenPhase	Player mode / screen phase
$3D	ReturnScreenState	Return destination
$40–$41	SelectedPlayerIndex, SelectedScreenVariant	Menu selections
$50+	GameplayObjectState…	Object pool ($0300+) fields mirrored in ZP
$F0–$FF	Audio engine ZP	Channel state, sequences, envelopes
$0200	OamBuffer	OAM DMA source (64 sprites)
$0300+	ObjectState…	Main object/actor array
$06F0	Ram_06F0	Warm-start signature
$0700+	Extended RAM	Actor timers, collision, audio buffers

---

8. Data Tables

Table	Address	Description
ScreenStateHandlerTable	$C10D	14 title screen handlers
ScreenStateHandlerTable (gameplay)	$C192	15 gameplay screen handlers
QueuedPpuTransferSourcePageTable	$C20A	PPU transfer source banks
QueuedPpuTransferDestinationOffsetTable	$C206	PPU dest offsets (alias at $C206)
PlayerStartXTable	$8C	Player start X positions
PlayerStartYTable	$8D	Player start Y positions
AudioPitchOrPeriodTable_F970	$F970	Note→period lookup
AudioSequenceIndexTable_FAB3	$FAB3	Sequence index table
IndexedGameplayLookupTable_FFC3	$FFC3	Gameplay bitmask/offset table
GameplayConstantTable_FF4C	$FF4C	Level/gameplay constants

---

9. Summary of Execution Flow

Power On / Reset
    │
    ▼
ResetHandler ($C000) ────► cld/sei, wait 2 VBlanks, init stack
    │
    ├─ Clear $0000–$07FF (8 pages via WorkPointerOrValueLo/Hi)
    │     └─ Warm-start: if FrameCounter≠0, skip clear, X=$5F
    │
    ├─ stx Ram_06F0 (signature)
    ├─ jsr ClearNametable2400WithTileFF ($C1A2)
    ├─ jsr HideAllOamSprites ($C1EA)
    ├─ PPUSCROLL = 0,0
    ├─ GameMode = 1 (title)
    ├─ APU enable ($4015=$0F)
    ├─ PPUCTRL = $90 (NMI on)
    │
    ▼
SelectMainLoopAudioPath ($C047) ─────────────────────────────┐
    │                                                         │
    ├─ GameMode=0: jsr UpdateAudioEngine ($F820), loop       │
    │                                                         │
    └─ GameMode≠0:                                            │
         jsr DecrementGameplayTimers ($C3B0)                  │
         jsr UpdateTitleAndGameplayState ($C0BA)              │
         jsr RequestNmiProcessing ($C05F)  → NmiFrameDelay=1  │
         jsr WaitForFrameReady ($C063)  ◄── wait for NMI ────┘
              │
              ├─ jsr AdvancePseudoRandomState ($C42F)
              ├─ wait for FrameReadyFlag ($30)
              ├─ inc FrameCounter ($27), dec NmiFrameDelay
              └─ clear FrameReadyFlag, rts
         beq SelectMainLoopAudioPath (loop)

NMI ($C08D) [once per frame]
    ├─ Preserve A,X,Y
    ├─ OAM DMA ($4014 from $0200)
    ├─ lda NmiFrameDelay ($32)
    │     ├─ 0: CompleteNmiAndRestoreRegisters (title)
    │     └─ 1: RunQueuedPpuTransfer ($C1F5)
    │           UpdatePpuTransferQueue ($C370)
    │           ResetPpuScroll ($C424)
    │           UpdateControllerState_C328 ($C328)
    │           ldy #$01 / sty FrameReadyFlag ($30)
    ├─ lda #$01 / sta NmiWorkMode ($33)
    └─ Restore A,X,Y, rti

Title Screen ($C0BA, GameMode=0)
    ├─ Wait for START (ControllerButtons & $10)
    ├─ ScreenSubstate tracks first/second press
    ├─ CurrentScreenState selects handler (14 states at $C10D)
    ├─ State $0D: StartGameplayCountdown → GameplayTimer=$14, State=$0C
    └─ State $06: CopyPlayerStateDefaults → init timers, audio

Player Select / Gameplay ($C129, GameMode≠0)
    ├─ HandleStartAndPlayerSelection: START/SELECT → GameMode, CurrentScreenState
    ├─ DispatchGameModePhase ($C142): PlayerModeOrScreenPhase ($3C) → handler
    ├─ DispatchScreenState ($C18D): 15 gameplay handlers ($C192 table)
    └─ Gameplay loop: objects, collision, scoring, level progression

---

10. Naming and Residue

Pass 1/2/3 complete — prg.s has zero Label_ definitions. All routines carry semantic names from Pass 2 (ResetHandler, NmiHandler, UpdateTitleAndGameplayState, DispatchScreenStateHandler, etc.) and internal branch targets use <Routine>_Block[_n] convention.

Pass 3 symbols applied (2026-10-19): _tools/apply_symbols.py substituted 75 operands (17 single-name + 58 hardware) from symbols.inc/locals.inc. Zero residue.

Overlapping table aliases (expressed as relocatable symbols):

• QueuedPpuTransferDestinationOffsetTable = RunQueuedPpuTransfer + $11 ($C206)
• AudioPitchOrPeriodTable_F970 = Flow_F96F + $01 ($F970)
• AudioSequenceIndexTable_FAB3 = Flow_FA85 + $2E ($FAB3)

Vectors at PRG $3FFA: .word NmiHandler, ResetHandler, ResetHandler

Build verification: make in copilot/ produces reconstructed.nes, compared whole-ROM against rom.nes (byte-identical).