disasm/Burger Time (U)/OVERVIEW.md

Burger Time (U) — Game Flow from Power-On

This document describes the execution flow of the disassembled Burger Time (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 burger_time.nes.

---

1. ROM and Memory Layout

Property	Value
Format	iNES / NES 2.0
PRG	1 × 16 KB (mapped at CPU $C000–$FFFF)
CHR	1 × 8 KB
Mirroring	Horizontal
PRG bank start	CPU $C000
Source files	copilot/prg.s (9,323 lines), copilot/header.s, copilot/chr.s
Output	burger_time_rebuilt.nes (24,592 bytes)

Interrupt vectors (CPU $FFFA–$FFFF)

Vector	Address	Handler
NMI	$FF7F	NmiHandler
RESET	$FD24	ResetHandler
IRQ / BRK	$FD24	ResetHandler (reused)

---

2. Build Status

make in copilot/ assembles header.s, prg.s, and chr.s, links them via ld65, and verifies the result against burger_time.nes.

Verification result: BYTE-IDENTICAL — headers, CHR, and all PRG bytes match exactly.

Note: the Makefile references burger_time.nes, while the actual ROM file is named Burger Time (U) [!].nes. A symlink burger_time.nes → "../Burger Time (U) [!].nes" is required before building.

---

3. Reset — CPU $FFFC → $FD24

ResetHandler ($FD24)

On power-on or reset:

1. sei — disable maskable interrupts.
2. cld — clear decimal mode.
3. lda #$00 / sta PPUCTRL / sta PPUMASK — disable PPU rendering and NMI.
4. Wait for two VBlanks — Flow_FD2E and Flow_FD33 each poll PPUSTATUS ($2002) for the VBlank bit.
5. jsr SetDefaultScroll ($FFEB) — set scroll to ($08, $00).
6. FrameCounter ($14) = $00; FrameCounterReload ($13) = $08.
7. JOY2 ($4017) = $80 — select controller latch mode / disable IRQ.
8. Stack pointer = $FF.
9. jsr InitializeRuntimeState ($FD63) — clear NmiCompletedFlag ($0E), GameMode ($4C), PendingFrameTask ($8F), PlayerDeathFlag ($4F), StageCompleteFlag ($4E); set PPUCTRL shadow to $90; clear nametables; load initial palette; wait for NMI; set PPUMASK shadow to $1A.
10. jsr InitializeGameSystems ($C00E) — process game state at $C76E and $CB53; set up initial OAM positions ($0700=$70, $0701=$10); clear $32; call SetMainState to enter the first state.
11. Falls into Flow_FD4F ($FD4F) — the main loop.

---

4. Main Loop — State Machine at $FD4F

Flow_FD4F ($FD4F) is the central main loop. Every iteration:

1. jsr WaitForNmi ($FD9D) — block until NmiCompletedFlag ($0E) is set, then clear it.
2. Load MainGameState ($16), multiply by 2, use as index into a pointer table:
   • Low byte from MainStateDispatchTable ($C000)
   • High byte from LookupTable_C001 ($C001)
   • The two tables are interleaved in the same $C000–$C00D region.
3. Indirect jump (jmp (DataPointerLo)) to the state handler.

State Dispatch Table (CPU $C000–$C00D)

The table is structured as alternating low/high bytes indexed by MainGameState * 2:

State	CPU Addr	Handler Routine	Purpose
0	$C3F8	RunFrameSynchronizedTask_C3F8	Initial / boot frame task
1	$C04E	HandleTitleState	Title screen
2	$C12F	HandleGameStartState	Game start / level init
3	$4DC2	(unmapped / bank-switched)	(state 3 entry)
4	$C24D	Flow_C24D	Stage transition / between-levels
5	$C14F	HandleGameplayState	Main gameplay
6	$C1AA	HandlePlayerDeathState	Player death sequence
(state 7+)	(from table)	(various)	(additional states)

SetMainState ($FF7C) stores the accumulator into MainGameState ($16) and returns — used by every state handler to transition to the next state.

---

5. NMI / Frame Heartbeat — NmiHandler ($FF7F)

The NMI fires once per frame and is the real-time driver:

1. Save registers (A, X, Y on stack).
2. OAM DMA — write $00 to OAMADDR ($2003), then $07 to OAMDMA ($4014) to DMA sprite data from $0700–$07FF.
3. Set NmiCompletedFlag ($0E) = $01 — signals the main loop that a frame has elapsed.
4. Read PPUSTATUS ($2002) to reset the address latch.
5. Stage complete handling — if StageCompleteFlag ($4E) is set, jsr ProcessGameState_CEA3 ($CEA3), then clear the flag.
6. jsr ProcessPendingFrameTask ($C029) — if a frame task is pending, advance its counter.
7. If GameMode ($4C) is nonzero, jsr ProcessGameState_F493 ($F493) — per-frame gameplay/audio update.
8. Restore registers, rti.

---

6. State Handlers

6.1 Title State — HandleTitleState ($C04E)

• Sets GameMode ($4C) = $00 and Zp_57 ($57) = $00.
• jsr ProcessGameState_C7F7 ($C7F7) — title-specific game state processing.
• StateInitializedFlag ($31) = $01.
• jsr ProcessGameState_CB53 ($CB53) and jsr ProcessGameState_C81B ($C81B).
• jsr EnableBackgroundAndSprites ($C3EE) — enables rendering.
• jmp Flow_C233 ($C233) — clears stage state, sets MainGameState = 4, returns to main loop.

6.2 Game Start State — HandleGameStartState ($C12F)

• jsr ProcessGameState_C7F7 ($C7F7).
• GameActiveFlag ($4D) = $01; StateInitializedFlag ($31) = $01.
• jsr ClearNametable2000 ($FDD0) — clear nametable at $2000.
• jsr ProcessGameState_C81B ($C81B) and jsr ProcessGameState_C977 ($C977).
• Decrement Ram_0400 ($0400).
• jsr ClearNametable2000 again.
• Set MainGameState = 6 → gameplay state.
• Return to main loop via Flow_FD4F.

6.3 Gameplay State — HandleGameplayState ($C14F)

The core gameplay state. Checks Zp_52 ($52):

• If Zp_52 is nonzero → Flow_C161 (second-player / alternate player path).
• If zero → Flow_C153 (first player path).

Checks PlayerDeathFlag ($4F):

• Bit 0 = player 1 dead; bit 1 = player 2 dead.
• If a player is dead → Flow_C19E → sets MainGameState = 5 (player death state).
• Otherwise continues gameplay.

When transitioning to death (Flow_C177):

• Disable background/sprites, set state initialized, process game state, re-enable rendering.
• Store pending sound command $03 (death sound), set GameMode = $01.
• Run a frame-synchronized task at $CA80, store sound command $04.
• Jump to Flow_C233 → MainGameState = 4 (stage transition).

6.4 Player Death State — HandlePlayerDeathState ($C1AA)

• Disable rendering, clear nametable.
• Loads player-specific data based on CurrentPlayerIndex ($50): X = $C1 (player 1) or $12 (player 2).
• jsr ProcessGameState_C715 ($C715) with player data.
• Store player sprite Y at $0701.
• Load palette, wait for NMI, set PPUCTRL/PPUMASK.
• Run frame-synchronized task, clear nametable, process game state at $CEC8.
• Set MainGameState = 5, return to main loop.

6.5 Stage Complete / Between-Stage State — HandleStageCompleteState ($C22A) / Flow_C233 ($C233)

• Disable rendering, process game state, enable rendering.
• Flow_C233: clear Ram_046E–$470, Zp_2E, Zp_2F, Ram_045A.
• Set MainGameState = 4 → stage transition state.
• Return to main loop.

Flow_C24D ($C24D) — the stage transition update (runs every 8th frame via Zp_15 counter):

• Processes a long chain of game state routines: $C9F9, $D7D3, $D980, $E11E, $E0B7, $E71A, $E6AE.
• If GameMode != 0: reads controllers for current player.
• More game state processing: $D1C1, $D6BF, $CB6F, $DB45, $DBD7, $DC82, $DD61, $EA1A, $E7DE, $E81A.
• If GameMode != 0: ProcessGameState_C5FF ($C5FF) — score/remaining-life logic.
• Handles player lives (Zp_1B for player 1, Zp_23 for player 2), wraps at 7.
• Clears nametable, sets MainGameState = 5 or 6 depending on mode.

---

7. Core Gameplay Update Loop

Every 8 frames (when Zp_15 & $07 == 0), Flow_C258 ($C258) runs the primary gameplay update:

Routine	Address	Purpose
ProcessGameState_C9F9	$C9F9	Object/enemy movement
CalculateAndClampValue_D7D3	$D7D3	Value clamping
ProcessGameState_D980	$D980	Object processing
ProcessGameState_E11E	$E11E	Collision / interaction
ProcessGameState_E0B7	$E0B7	State update
ProcessGameState_E71A	$E71A	Animation
ProcessGameState_E6AE	$E6AE	Object cleanup
(player input)	—	Controller reading when GameMode != 0
ProcessGameState_D1C1	$D1C1	Player movement
ProcessGameState_D6BF	$D6BF	Player animation
ProcessGameState_CB6F	$CB6F	Burger/part assembly
ProcessGameState_DB45	$DB45	Enemy AI
ProcessGameState_DBD7	$DBD7	Collision detection
ProcessGameState_DC82	$DC82	Score / points
ProcessGameState_DD61	$DD61	Bonus items
ProcessGameState_EA1A	$EA1A	Pepper / power-up
ProcessGameState_E7DE	$E7DE	Round timing
ProcessGameState_E81A	$E81A	Level progression
ProcessGameState_C5FF	$C5FF	Lives / continues (GameMode != 0)

---

8. Audio Engine

UpdateAudioEngine ($F478)

Called from:

• Flow_C368 ($C368) — during title/transition states
• RunFrameSynchronizedTask_C3F8 ($C3F8) — during frame-synchronized tasks
• Flow_C615 ($C615) — during gameplay state
• Flow_C7D6 ($C7D6) — tail call from another path

The audio engine:

1. Clears audio RAM at $052F (167 bytes, X from $A7 down).
2. Clears APU channel volume registers $4000–$400F (20 bytes).
3. Writes $00 to SND_CHN ($4015) — disable all channels initially.
4. Sets Ram_05A3 ($05A3) = $38.
5. Processes sound commands and music updates via subroutines at $F4B3, $F5B3, $F748, $F6E4.

StorePendingSoundCommand ($C026) — stores a sound command in PendingSoundCommand ($90), processed by the NMI or audio engine.

ProcessPendingFrameTask ($C029) — processes PendingFrameTask ($8F); if $FF, resets to $00 and advances; otherwise increments the task counter up to $F1.

---

9. PPU / Rendering

EnableBackgroundAndSprites ($C3EE)

Waits for PPU VBlank, loads PpuMaskShadow ($11), ORs with $18 (enable background + sprites), calls SetPpuMaskShadow.

DisableBackgroundAndSprites ($C3E4)

Waits for PPU VBlank, loads PpuMaskShadow, ANDs with $E7 (disable background + sprites).

SetPpuControlShadow ($C3D8) / SetPpuMaskShadow ($C3DE)

Store accumulator to the shadow register ($0C/$0D) and to the corresponding PPU register ($2000/$2001).

ClearNametables ($FDAE)

Clears both nametables ($2000 and $2800) via ClearNametable2000 and ClearNametable2800.

LoadPalette ($FDF0)

Waits for PPU VBlank, sets PPU address to $3F00 (palette), writes 16 bytes of palette data from a pointer in X/Y.

SetDefaultScroll ($FFEB)

Writes $08 then $00 to PPUSCROLL ($2005).

DecodeNametableStream ($FE74)

Decodes a run-length-encoded nametable stream from a pointer (X/Y) into PPU memory. Used extensively during screen initialization (RunFrameSynchronizedTask_C3F8 calls it multiple times for different screen regions).

---

10. Controller Input

ReadControllers ($FE2B)

Reads both controller ports ($4016/$4017) by strobing JOY1, then shifting in 8 bits per controller. Results are packed into scratch variables:

• ScratchValue0 ($01), ScratchValue1 ($02), ScratchIndex ($03) — raw button bits.
• The result is processed into directional/button flags stored in Zp_2F ($2F), checked with and #$0C (start/select) and and #$08 (specific button) throughout the code.

---

11. Key Zero-Page / RAM Symbols

Address	Symbol	Use
$0E	NmiCompletedFlag	NMI frame-sync flag
$10	PpuControlShadow	$2000 mirror
$11	PpuMaskShadow	$2001 mirror
$13	FrameCounterReload	Frame counter reload value
$14	FrameCounter	Frame tick counter
$15	Zp_15	Frame divider (gameplay runs every 8 frames)
$16	MainGameState	Current state machine state
$1B	Zp_1B	Player 1 lives counter
$1F	Zp_1F	(unnamed)
$23	Zp_23	Player 2 lives counter
$2E–$2F	Zp_2E / Zp_2F	Controller/button state
$31	StateInitializedFlag	State init flag
$32–$35	Zp_32–$35	Indirect pointers / coordinates
$3F	Zp_3F	(unnamed)
$44	Zp_44	(unnamed)
$4C	GameMode	Game mode flag (0=title/demo, nonzero=gameplay)
$4D	GameActiveFlag	Game active flag
$4E	StageCompleteFlag	Stage completed flag
$4F	PlayerDeathFlag	Player death flags (bit0=P1, bit1=P2)
$50	CurrentPlayerIndex	Current player (0 or 1)
$52	Zp_52	Gameplay sub-state
$56	Zp_56	(unnamed)
$57	Zp_57	Title state variable
$5A–$5B	Zp_5A / Zp_5B	(unnamed)
$8F	PendingFrameTask	Pending frame task counter
$90	PendingSoundCommand	Pending sound command
$95–$96	DispatchPointerLo / DispatchPointerHi	State dispatch indirect pointer
$0400	Ram_0400	(unnamed)
$040D–$040F	Ram_040D–$040F	(unnamed)
$045A–$045F	Ram_045A–$045F	(unnamed)
$0460–$0467	Ram_0460–$0467	Object/enemy state
$046E–$0470	Ram_046E–$0470	Stage state
$04E0	Ram_04E0	(unnamed)
$0500–$0535	Ram_0500–$0535	Object arrays
$052F–$05A7	Ram_052F–$05A7	Audio engine state
$0536	CurrentObjectIndex	Current object being processed
$0700–$07FF	Ram_0700–$07FF	OAM buffer + sprite data

---

12. Summary of Execution Flow

Power On / Reset
    │
    ▼
ResetHandler ($FD24) ───────────────────────────────┐
    │ sei, cld, disable PPU, wait 2× VBlank          │
    │ SetDefaultScroll, init frame counters          │
    │ InitializeRuntimeState ($FD63)                 │
    │   ├─ clear NmiCompletedFlag, GameMode, etc.    │
    │   ├─ set PPUCTRL shadow=$90, clear nametables  │
    │   ├─ load palette, wait NMI                    │
    │   └─ set PPUMASK shadow=$1A                    │
    │ InitializeGameSystems ($C00E)                  │
    │   ├─ process game state ($C76E, $CB53)         │
    │   ├─ set initial OAM ($0700=$70, $0701=$10)    │
    │   └─ SetMainState → first state                │
    ▼                                                │
Flow_FD4F ($FD4F) ───────────────────────────────────┤
    │                                                │
    ├─ WaitForNmi ($FD9D)   ◄────── waits for NMI ───┘
    │                                                │
    ├─ MainGameState ($16) → dispatch table          │
    │   ├─ State 0: $C3F8 (frame sync task)          │
    │   ├─ State 1: $C04E (HandleTitleState)         │
    │   ├─ State 2: $C12F (HandleGameStartState)     │
    │   ├─ State 4: $C24D (stage transition)         │
    │   ├─ State 5: $C1AA (HandlePlayerDeathState)   │
    │   ├─ State 6: $C14F (HandleGameplayState)      │
    │   └─ ...                                       │
    │                                                │
    └─ (state handler returns via SetMainState)      │
              │                                      │
              ▼                                      │
   back to Flow_FD4F ◄───────────────────────────────┘

NMI ($FF7F) [every frame]
    ├─ OAM DMA from $0700 ($4014)
    ├─ NmiCompletedFlag ($0E) = $01
    ├─ StageCompleteFlag ($4E) handling ($CEA3)
    ├─ ProcessPendingFrameTask ($C029)
    ├─ if GameMode != 0: ProcessGameState_F493 ($F493)
    └─ rti

Gameplay Update (every 8 frames, Flow_C258 at $C258)
    ├─ object movement & collision ($C9F9–$E6AE)
    ├─ controller input (when GameMode != 0)
    ├─ player movement & animation ($D1C1, $D6BF)
    ├─ burger assembly, enemy AI ($CB6F, $DB45)
    ├─ collision, score, bonus ($DBD7–$DD61)
    ├─ pepper, round timing ($EA1A–$E81A)
    └─ lives/continues ($C5FF)

---

13. Notes

• The disassembly is organized as a state machine driven by MainGameState ($16), with the dispatch table at CPU $C000–$C00D.
• The NMI is the sole frame-sync source; the main loop (Flow_FD4F) blocks on WaitForNmi before dispatching to the current state handler.
• Gameplay updates run on an 8-frame divider (Zp_15 at $15), not every frame.
• Audio is updated both from the NMI path (ProcessGameState_F493 when GameMode != 0) and from state-specific code paths.
• Many routines are named Flow_Cxxx or ProcessGameState_Cxxx based on their CPU address, reflecting the automated disassembly origins. Semantic names are provisional.
• Build verification: make in copilot/ produces burger_time_rebuilt.nes that is byte-identical to burger_time.nes (requires a symlink named burger_time.nes pointing to the actual ROM file due to spaces/special characters in the original filename).