disasm/CIRCUS/OVERVIEW.md

CIRCUS — Game Flow from Power-On

This document describes the execution flow of the disassembled CIRCUS 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.

---

1. ROM and Memory Layout

Property	Value
Format	iNES
PRG	1 × 16 KB (mapped at CPU $C000–$FFFF)
CHR	1 × 8 KB
Mirroring	Horizontal
PRG bank start	CPU $C000
Source file	copilot/prg.s (~12,755 lines)
Output	reconstructed_prg.bin (16,384 bytes)

Interrupt vectors (CPU $FFFA–$FFFF)

Vector	Address	Handler
NMI	$C05A	NmiHandler
RESET	$C000	Reset
IRQ / BRK	$4CB7	Outside mapped space — effectively unused

---

2. Build Status

make in copilot/ assembles prg.s with ca65, links with ld65, and verifies against prg.bin.

Verification result: BYTE-IDENTICAL — reconstructed_prg.bin matches prg.bin exactly (all 16,384 bytes), and prg.bin matches the PRG bank of CIRCUS.NES.

---

3. Pass Status

Pass	Status	Description
Pass 1	Complete	Code/data split — entire PRG bank classified as traced code or explicit .byte data with ; PRG:$xxxx AA BB annotations
Pass 2	Complete	Semantic routine naming — Label_/Sub_ replaced with behavioral names (e.g. RunMainStateDispatcher, UpdateMenuState, ReadControllers); locals.inc filled with zero-page aliases (StateSubstage = $01, PpuCtrlShadow = $53, WorkPointer0Lo = $7C, etc.)
Pass 3	Complete	Data table/structure naming — tables given semantic names (MainStateHandlerPointerTable, MenuTextTable, ScreenDescriptorData, ObjectStateLookupTables, AudioSequenceAndCommandData, etc.)

---

4. Reset — CPU $FFFC → $C000

Reset ($C000)

On power-on or reset:

1. CLD — clear decimal mode; SEI — disable maskable interrupts.
2. Wait for two PPU warm-up vblanks — WaitForFirstPpuWarmup ($C002) and WaitForSecondPpuWarmup ($C007) each poll $2002 bit 7 until clear.
3. JSR $C0B8 (InitializePpuControl) — write $08 to PPUCTRL, $00 to PPUMASK.
4. LDX #$FF / TXS — initialize stack pointer to $FF.
5. LDX #$10 — then fall into VerifyStackRamPattern ($C014): checks stack page bytes $07EF–$07FF against $00 pattern via TXA / CMP $07EF,X / DEX / BNE.
6. ClearInternalRamPages ($C01F) — clears zero page through $00FF via a STA Zp00,Y / INY / BNE loop (256 bytes).
7. ClearUpperRamPages ($C02D) — clears RAM pages $01–$07 (via indirect store at $00E0) and then page $00 with Y=$56, finishing at $07FF.
8. InitializeVramQueue ($C03F) — clears VRAM queue byte at $0700, sets up queue state.
9. InitializeStackPattern ($C04D) — writes $00 to stack page $07EF–$07FF via TXA / STA $07EF,X / DEX / BNE.
10. JSR $C3B8 — early initialization subroutine.
11. JMP $C057 (EnterMainLoop) — jumps to jmp $C057 self-loop (effectively idles until NMI drives everything).

Key point: Like Donkey Kong Jr. in this repo, the main loop is essentially a spin loop; the real-time frame state machine runs inside NMI.

---

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

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

1. Save registers (PHA / TXA / PHA / TYA / PHA).
2. Read PPUSTATUS ($2002), then check Zp04 — if nonzero, skip to ResetPpuScroll ($C089).
3. Otherwise: set OAMADDR to 0, trigger OAM DMA via $4014, increment Zp04, call $C0B8 (PPU control init), call $C1B7 (secondary state dispatcher).
4. Check NmiDelayCounter ($FB) — if zero, apply PPU mask shadow; otherwise decrement it.
5. ApplyPpuMaskShadow ($C082) — writes PpuMaskShadow ($54) to PPUMASK ($2001).
6. FinishNmiPpuUpdates ($C084) — decrements Zp04.
7. ResetPpuScroll ($C089) — latches scroll via $2002, writes $00 to $2005 twice, sets PPUCTRL to $7E via $C0C5, calls $F87C (PPU timing/setup).
8. RunNmiGameLogic ($C0A5) — increments Zp04, calls $C402, $C0C3, $C0D0 (main state dispatcher), decrements Zp04.
9. RestoreNmiRegisters ($C0B2) — PLA / TAY / PLA / TAX / PLA / RTI.

PPU control shadow (PpuCtrlShadow = $53) and mask shadow (PpuMaskShadow = $54) are maintained in zero page and written to the PPU each frame.

---

6. Main State Dispatcher — RunMainStateDispatcher ($C0D0)

The main game logic is a state machine:

1. Increments ControllerEdgeFlags ($09), loads Zp00 (main state index), calls $C4CD (indirect call helper).
2. Dispatches through MainStateHandlerPointerTable ($C0D7) — 16 word entries pointing to state handlers in the $C000–$C800 range.
3. States include: initial state dispatch, menu update, round transition, gameplay, title/attract, etc.

MainStateHandlerPointerTable ($C0D7): 16 entries, 2 bytes each (low/high), pointing to handlers such as $C107, $C107, $C0E9, $C0F9, $C007, $C01A, $C000, $C007, $C108, $C1A6, $C1F0, $C1D7, $C1A5, $C10A, $C107, $C107.

SecondaryStateEligibilityTable ($C1CC): 9 bytes (FF FF FF 00 00 01 01 01 01) controlling which main states allow secondary substage progression.

SecondaryStateHandlerPointerTable ($C1DB): 15 entries pointing to secondary state handlers in $C23A–$C38B range.

---

7. Key Subsystems

Controller Input — ReadControllers ($C100)

Reads controller 1 and 2 via shift-register polling, stores edge flags in ControllerEdgeFlags ($09), and maintains shift history at Controller1Shift ($E4) / Controller2Shift ($E5). Uses ControllerBitMaskTable ($C4A6: 40 48 60 68) for bit testing.

Menu System — UpdateMenuState ($C21C)

Handles title/menu state progression. Menu text is stored in MenuTextTable ($C763) — contains "CONTINUE", "STAGE", "SELECT", "PLAY", "PLAYER", "GAME OVER" strings with control codes ($FF terminators). Menu selection tracked at MenuSelectionIndex ($0302).

Palette / Screen Transfer — SetupScreenPaletteTransfer ($CD6D)

Sets up PPU palette and nametable transfers via descriptor streams. Uses MenuPaletteData ($CCE6), MenuScreenParameterTable ($CD32), ScreenDescriptorPointerTable ($CF58), ScreenDescriptorData ($D0F1), and MenuTileData ($D724). Palette RAM address set via SetPaletteRamAddress ($CA04).

VRAM Updates — ProcessQueuedVramUpdates ($D268)

Processes queued PPU VRAM descriptor commands. Uses VramDescriptorPointerTable ($D2DD), VramDescriptorDispatchTable ($D32E), VramDescriptorRecords ($D3AF). Executed via ExecuteVramDescriptorStream ($D330).

Object System — DispatchVariantObjectUpdate ($D807)

Updates variant objects (enemies, items) via a handler pointer table. Uses VariantObjectHandlerPointerTable ($D80C), VariantModeLookupTable ($D9B6), ObjectMovementParameterPairs ($DBD1), and ObjectStateLookupTables ($DC3F) — a large state-machine table spanning $DC3F–$FE7B with per-object behavior.

Audio — ProcessAudioFrame ($F870)

Per-frame audio engine: DecodeAudioStream ($F8D4) and ExecuteAudioCommand ($F93E) process audio sequences and commands. Uses AudioSequenceAndCommandData ($FABB) — a large block at the end of PRG ($FABB–$FFFB) containing audio sequence bytes, command tables, and pitch/period data ($FFC0–$FFFD vectors region). Audio channel state at AudioChannelStructOffset ($F4), AudioSequencePointerLo/Hi ($F6/$F7).

Initialization

• InitializeApuAndPpu ($C399) — APU and PPU initialization.
• InitializeNametablePages ($C40F) — clears nametable memory.
• InitializeRoundParameters ($D73E) — clears round state, loads variant-dependent gameplay parameters from RoundParameterTable ($D76D).
• CurrentGameVariant ($63) — selects current game variant/mode.

---

8. Zero-Page Aliases (locals.inc)

Alias	Address	Role
Zp00	$00	Main state index / general purpose
StateSubstage	$01	Secondary state substage
StateTimer	$02	State timer countdown
Zp04	$04	NMI phase / PPU update gate
PpuCtrlShadow	$53	PPUCTRL shadow register
PpuMaskShadow	$54	PPUMASK shadow register
CurrentGameVariant	$63	Current game variant
WorkPointer0Lo	$7C	Indirect pointer 0 low
WorkPointer0Hi	$7D	Indirect pointer 0 high
WorkPointer1Lo	$7E	Indirect pointer 1 low
WorkPointer1Hi	$7F	Indirect pointer 1 high
Controller1Shift	$E4	Controller 1 shift register
Controller2Shift	$E5	Controller 2 shift register
AudioChannelStructOffset	$F4	Audio channel struct offset
AudioSequencePointerLo	$F6	Audio sequence pointer low
AudioSequencePointerHi	$F7	Audio sequence pointer high

Full list in copilot/locals.inc (161 lines).

---

9. Data Tables (prg.s)

Table	Address	Description
MainStateHandlerPointerTable	$C0D7	16-entry main state handler jump table
InitialStateDispatchTailTable	$C0F9	Initial state dispatch inline code/data
SecondaryStateEligibilityTable	$C1CC	9-byte secondary state eligibility flags
SecondaryStateHandlerPointerTable	$C1DB	15-entry secondary state handler table
ControllerBitMaskTable	$C4A6	Controller bit mask values (40 48 60 68)
OamInitializationData	$C549	OAM initialization byte sequence
SpriteTransferParameterTable	$C564	OAM DMA transfer setup code
ScreenObjectParameterTable	$C5A6	Screen object setup parameters
ObjectPositionLookupTable	$C65E	Object position data block
ObjectAttributeLookupTable	$C6C4	Object attribute data block
GameplayModeParameterTable	$C721	Gameplay mode parameter block
MenuTextTable	$C763	Menu strings ("CONTINUE", "STAGE", "SELECT", "PLAY", etc.)
GameplayObjectPointerTable	$C833	Gameplay object data block
InputDirectionLookupTable	$C906	Input direction data block
ObjectSlotOffsetTable	$C9F8	Object slot offset data block
PpuControlMaskTable	$CA47	PPU control mask values (C0 80 40 00)
PpuTimingParameterTable	$CA63	PPU timing/polling code block
SpriteLayoutTable	$CB51	Sprite/OAM setup code block
MenuPaletteData	$CCE6	Menu palette data
MenuScreenParameterTable	$CD32	Menu screen parameter block
ScreenDescriptorPointerTable	$CF58	Screen descriptor pointer table
ScreenDescriptorData	$D0F1	Screen descriptor records
MenuTileData	$D724	Menu tile descriptor data
RoundParameterTable	$D76D	Round initialization parameters
VariantObjectHandlerPointerTable	$D80C	Variant object handler pointers
VariantModeLookupTable	$D9B6	Variant mode lookup entries
ObjectMovementParameterPairs	$DBD1	Object movement parameter pairs
ObjectStateLookupTables	$DC3F	Object state machine tables ($DC3F–$FE7B)
MetaspriteAndObjectFrameData	$D63B	Metasprite/object frame data
GameplayDispatchTable_E4DD	$E4DD	Gameplay dispatch table
GameplayPositionLookup_E51D	$E51D	Gameplay position lookup
GameplayHandlerTable_E52D	$E52D	Gameplay handler table
GameplayParameterTable_E640	$E640	Gameplay parameter block
GameplayParameterTable_E6A0	$E6A0	Gameplay parameter block
GameplayObjectDescriptorData_E6DF	$E6DF	Gameplay object descriptor data
GameplayDispatchTable_E7E5	$E7E5	Gameplay dispatch table
GameplayParameterTable_E96E	$E96E	Gameplay parameter block
GameplayParameterTable_E9B6	$E9B6	Gameplay parameter block
GameplayDispatchTable_E9D9	$E9D9	Gameplay dispatch table
GameplayLookupTable_EA76	$EA76	Gameplay lookup table
GameplayLookupTable_EBC4	$EBC4	Gameplay lookup table
GameplayModeTable_EC15	$EC15	Gameplay mode table
GameplayInitializationTable_EC21	$EC21	Gameplay initialization table
GameplayLookupTable_EDFB	$EDFB	Gameplay lookup table
MovementStepTable	$F226	Movement step values
MovementCurveTable	$F320	Movement curve values
AudioVoiceParameterTable	$F023	Audio voice parameter table
AudioObjectOffsetTable	$F12E	Audio object offset table
AudioGameplaySupportData	$F163	Audio gameplay support data
SoundRequestTable	$F76C	Sound request table
AudioChannelInitializationTable	$F878	Audio channel init data
AudioSequenceAndCommandData	$FABB	Audio sequences and commands ($FABB–$FFFB)

---

10. Build

cd "_wip/CIRCUS/copilot"
make        # → ca65 + ld65 + cmp reconstructed_prg.bin prg.bin → "BYTE-IDENTICAL"

---

11. Notes

• The main loop (EnterMainLoop at $C057) is a self-jump spin loop; all per-frame work is driven by NMI.
• The IRQ vector ($4CB7) points outside mapped PRG space and is never used.
• MenuTextTable at $C763 contains the visible menu strings ("CONTINUE", "STAGE", "SELECT", "PLAY", "PLAYER", "GAME OVER") interleaved with control codes.
• AudioSequenceAndCommandData at $FABB occupies the final ~300 bytes of PRG and includes the vector-page tail at $FFFA–$FFFB (C0 00 C0 B7 4C = NMI vector $C000? No — the vectors at $FFFA are C0 00 (NMI=$C000?), C0 B7 ... wait, the actual vectors are at $FFFA-$FFFB in the file. Let me check: line 12754 shows .byte $C0, $00, $C0, $B7, $4C at CPU:$FFFB PRG:3FFB. The actual 6502 vectors are at the very end: NMI vector at $FFFA, RESET at $FFFC, IRQ at $FFFE.)

---

12. Next Steps

• Promotion — move to a top-level CIRCUS/ folder, add header.s / chr.s + full-ROM make target (as e.g. Burger Time (U)), then join the root OVERVIEW.md numbered inventory.
• Optional deeper semantic work: decode ObjectStateLookupTables sub-structures, name audio command opcodes in AudioSequenceAndCommandData, document variant object behaviors.