disasm/NROM/Balloon Fight (JU)

Balloon Fight (JU) — Game Flow from Power-On

This document describes the execution flow of the disassembled Balloon Fight (JU) 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. Reset Vector — CPU $FFFC → $C000

Reset ($C000–$C07E)

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

Step	Code	Purpose
1	lda #$00 / sta PPUCTRL	Disable NMI and PPU rendering
2	lda #$00 / sta PPUMASK	Disable screen output
3–6	Poll $2002 twice	Wait for two full VBlank periods (PPU warm-up)
7	sei / cld	Disable interrupts, clear decimal mode
8	ldx #$FF / txs	Initialize stack pointer
9–13	Clear Zero Page	Zero all of RAM $00–$FF
14–21	Warm-start signature check	Compare RAM $07FA–$07FC against "HAL" ($C082–$C084). If valid, skip full memory clear
22–31	Initialize memory	Clear zero page + stack page ($0700–$07FF via SortedRecordTable, x = 0), set SpawnPixelPosition = $32, run block-init loop (jsr InitializeOrQueueObject 50 times), jsr SortOrInitializeRecords
32–44	Copy initialization data	Copy 15 bytes from $C085 to $0629 (initial game state table)
45–51	Clear local variables	Zero the five-byte CurrentRecord at $03–$07
52–56	Copy saved signature	Re-store "HAL" to $07FA–$07FC
57	jmp MainInitialization	Transfer control to $F1D4

Warm-start signature: "HAL" stored at $C082; RAM copy at $07FA. This lets the game resume state after a soft reset without re-initializing everything.

---

2. Main Initialization

MainInitialization is at $F1D4 (forward-referenced in locals.inc). It sets up the first round, initializes object pools, and enters the main loop. Its body lives in the upper bank region (not fully shown in the decoded $C000–$C07E range).

---

3. Interrupt Vectors — CPU $FFFA–$FFFF

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

Vector	Address	Handler
NMI	$C094	NmiHandler
RESET	$C000	Reset
IRQ	$C0F7	IrqHandler (self-loop jmp IrqHandler — unused)

---

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

The NMI fires once per frame and drives the frame pacing. It:

1. Preserves registers (A, X, Y on stack)
2. OAM DMA: writes $00 to OAMADDR, then $02 to OAMDMA (DMA from $0200–$02FF)
3. PPU command buffer flush: compares read/write offsets at $52/$53; if data pending, calls FlushPpuCommandPreserved ($C17C)
4. Transfer sources: jsr UpdatePpuTransferSources ($D60D)
5. Build OAM: jsr BuildFrameOam ($D798)
6. Frame counter: inc FrameCounter ($19)
7. Scroll/rendering setup: sets the PPUADDR/PPUSCROLL registers, conditionally waits for VBlank if rendering disabled (polling PPUSTATUS), writes PPUCTRL
8. Audio: jsr UpdateAudioFrame ($FFF7 bank call → Sound_F758)
9. Sets NmiCompletedFlag ($02 = $01)
10. Restores registers, rti

The main game loop runs during VBlank and waits for this flag.

---

5. Main Game Loop — $C209

After initialization, control reaches the per-frame loop at $C209:

UpdateGameplayObjects      ($E691)   ; update all 20 gameplay-object slots
UpdateSpecialObjectSystem  ($C6F9)   ; every other frame (frame counter / 2)
[round spawner / HUD / spawning logic]
[object physics & collision]
[particle system]
[OAM sorting / sprite setup]
WaitForFrame               ($F465)   ; wait for NMI-completed flag
jmp back to $C209

Key flow details:

• Scroll handling ($C227): if PpuScrollX ($17) is non-zero, toggles PpuControlBase bit 0 (screen scroll page flip), decrements scroll X.
• Carrier/rescue sequence ($C233): updates carrier position ($0488), target player, sound requests.
• Effect object pool (8 slots, $055D–$0584): updates timers, respawns offscreen.
• Gameplay object pool (20 slots, $0530–$055C): movement, position integration.
• Round spawner ($C790): on frame boundaries, counts down RoundSpawnDelay, finds free slots, spawns round objects from tables ($C88F–$C8B5), plays spawn sound.
• HUD updates ($C831): when spawn delay reaches 1, writes round HUD digits to PPU buffer.
• Sprite sorting: SortOrInitializeRecords ($C579) maintains a sorted table of up to 50 five-byte records ($0700–$07F9) for OAM priority.

---

6. Subsystems

6.1 PPU Command Buffer ($C12D–$C1C4)

A buffered PPU update system. Commands are staged at $0300 with format:

• Byte 0: PPU address high | $20
• Byte 1: PPU address low
• Byte 2: length (number of data bytes following)

Routines:

• AppendBytesToPpuBuffer ($C131) — appends raw bytes
• AppendLengthPrefixedPpuData ($C139) — appends with length prefix
• BuildPpuCommand ($C154, formerly Sub_C154) — formats address+length command
• FlushPpuCommandPreserved ($C17C, formerly Sub_C17C) — drains buffer to $2006/$2007, preserving X/Y
• Special handling for palette writes ($3Fxx range)

6.2 Round Spawning ($C77A–$C88A)

• ChooseRoundSpawnIndex ($C77A): picks a random spawn index below RoundSpawnRandomLimit, rejecting zero
• UpdateRoundSpawner ($C790): timer-driven spawning; initializes object position, velocity (from tables at $C89F–$C8B1), flip flags, aux state; increments SpawnSelector; requests spawn sound ($F0 bit $04)
• UpdateRoundHud / ConfigureRoundPresentation ($C831–$C88A): writes round number / HUD tiles to PPU buffer

Spawn tables ($C88F–$C8B5): flip X/Y, X/Y offsets, parameter, velocity Y, position hi, velocity X — six entry types.

6.3 Gameplay Objects ($C8B7–$C9DC)

UpdateRoundObjectSpritesAndPhysics ($C8B7) updates slots 1 and 0:

• Builds 3-sprite OAM per object from tile tables ($C9DD–$CA33)
• Integrates fixed-point position ($C9B6)
• Bounds testing (TestGameplayObjectAgainstBounds, $CA67) against rectangular regions
• Velocity reflection on collision (BounceGameplayObjectX/Y, $CA4F/$CA37)
• Object removal when offscreen

6.4 Bonus Objects ($CB74–$CCCA)

• UpdateBonusObjectSystem ($CB74): per-frame phase/timer advance for the single active bonus slot
• TestBonusObjectPlayerOverlap ($CBB2): rectangle overlap vs both players; applies horizontal/vertical impulses, collision sound
• TestBonusObjectCollection ($CC3A): phase-3 collection; starts bonus timer
• TriggerBonusObjectEffect ($CCBF): increments effect counter, calls ApplyBonusEffect ($E983)
• DrawBonusObjectHud ($CCCB): 3-row HUD tile display from phase tables ($CD26–$D046)

6.5 Carrier / Rescue Sequence ($C5C3–$C715)

• UpdateCarrierSequence ($C6F9): advances carrier target X while idle; finds eligible player; starts sequence
• FindEligiblePlayerForCarrier ($C614): scans player slots 7→0, finds one at lower screen boundary ($B4+) matching carrier target X
• BeginCarrierTargetSequence ($C6C4): captures player position/state, resets timer
• UpdateCarrierArrivalSequence ($C658): moves carrier down, checks contact, transitions player to hit/rescue state, sound request
• UpdateCarrierObjectDisplay ($C5C3): builds 8-sprite carrier metasprite, updates target player position relative to carrier
• Tables: NormalDisplayModeTable ($C5B7), AlternateDisplayModeTable ($C5BB), CarrierAnimationSequenceTable ($C6B8)

6.6 Particle System ($CD4A–$CEAD)

• InitializeParticleSlots ($CD4A): 10 slots, offscreen Y ($F0)
• SpawnTimedParticle ($CD5A): random timer, finds free slot, assigns position/velocity from ParticleInitialVelocityTable ($CEAE)
• UpdateParticleSystem ($CDAA): integrates signed motion, applies scroll delta, retires offscreen particles
• DrawParticleSprites ($CE2F): 3-sprite OAM per particle with animation/attribute masking

6.7 Sound Driver ($FFF7 region, bank-switched)

• UpdateAudioFrame jumps to Sound_F758 in another bank
• Sound sequence pointer table at $3BCA (32 entries)
• Encoded sequence data $3BCA–$3FF1 (note/duration bytes with $02/$FF/$8x control codes)
• APU channel init at $F7xx region (InitializeApuChannelState, SilencePulseChannels)
• Sound request flags: $F0 (flags 0), $F1 (flags 1), $F2 (flags 2), $F3 (flags 3)

---

7. Memory Map (Key Zero Page / RAM)

Address	Name	Use
$00	PpuControlShadow	$2000 mirror
$01	PpuMaskShadow	$2001 mirror
$02	NmiCompletedFlag	VBlank sync flag
$12–$13	RecordIndex / ReverseRecordIndex	Sorted-record insertion (see reuse note below)
$14–$15	SpawnParameter / SpawnPixelPosition	Spawn args
$16	RenderingDisabledFlag	Rendering state
$17	PpuScrollX	Scroll X
$18	PpuControlBase	Base PPU control
$19	FrameCounter	Frame tick
$1B	RandomState	PRNG state
$1D–$1E	RecordPtrLo/Hi	Record table pointer
$23–$24	SpawnCommandPointerLo/Hi	Command stream pointer
$25–$26	DispatchPointerLo/Hi	Spawn dispatch indirect jump
$52–$53	Ppu buffer read/write offsets	Command buffer
$54–$56	Ppu command address/length	Pending PPU command
$7F	PlayerLifecycleState	Per-player lifecycle
$88	PlayerSlotState	Per-player active state
$91	PlayerPosX / Player0PosX	Player X
$99	CarrierTargetX	Carrier target
$9A	PlayerPosY / Player0PosY	Player Y
$A2	CarrierPosY	Carrier Y
$BD	PlayerCollisionDisable	Collision immunity
$F0–$F3	Sound request flags 0–3	Audio requests
$0300–$03FF	PPU command buffer	Staged PPU updates
$0489–$048D	Carrier sequence state	Active, mode, target, drop, timer
$0490–$0530	Gameplay object pool (20 slots)	State, pos, velocity
$055D–$0584	Effect object pool (8 slots)	State, pos
$0558–$05CE	Particle / sequence state	10-slot particle pool
$05D1–$060E	Bonus object state	Timer, phase, pos, HUD
$0700–$07F9	Sorted record table	50 × 5-byte OAM sort records
$07FA–$07FC	Warm-start signature	"HAL"

Alias reuse. Several zero-page addresses serve more than one subsystem, so locals.inc defines several names per address; prg.s uses whichever fits the routine reading it:

Address	Names used in prg.s
$12	RecordIndex (sort), Temp12 (generic scratch), CollisionDeltaX, MotionDeltaLo
$13	ReverseRecordIndex (sort), CollisionDeltaY, MotionDeltaHi
$23–$26	SpawnCommandPointerLo/Hi + DispatchPointerLo/Hi, BoundsLeftPtrLo/Hi + BoundsRightPtrLo/Hi (stage-collision bounds)
$27–$2A	BoundsTopPtrLo/Hi + BoundsBottomPtrLo/Hi (stage-collision bounds)
$3E	SequencePlayerIndex (bonus accumulation) / CurrentObjectIndex (object loops)
$57–$5A	PpuCommandData0/1/2 (PPU command buffer) / HudCommandTile0; RoundHudCommandAddressHi/Lo + RoundHudCommandLength + RoundHudTile in DrawRoundStatusPanel
$55D/$567/$57B	EffectObjectState / EffectObjectPosX / EffectObjectPosY (spawn effects) vs ParticleState / ParticlePosX / ParticlePosY (particles)

---

8. Object Pools

Pool	Slots	State array	Purpose
Gameplay objects	20 ($00–$13)	$0530	Round enemies/objects, movement & physics
Effect objects	8 ($00–$07)	$055D	Short-lived spawn effects
Particles	10 ($00–$09)	$055D	Visual particles (shared state array, different offset interpretation)

Slot state convention: negative ($FF) = inactive/free, zero or positive = active.

---

9. Summary of Execution Flow

Power On / Reset
    │
    ▼
Reset ($C000) ────► hardware init, clear RAM, validate "HAL" signature
    │
    ▼
jmp MainInitialization ($F1D4)
    │
    ▼
[first-round setup, object pool init]
    │
    ▼
Main Loop ($C209) ──────────────────────────────────────────────┐
    │                                                           │
    ├─ UpdateGameplayObjects ($E691)                            │
    ├─ UpdateSpecialObjectSystem ($C6F9) [alt frames]           │
    ├─ Carrier sequence ($C6F9 family)                          │
    ├─ Round spawner ($C790) + HUD ($C831)                      │
    ├─ Object physics & collision ($C8B7, $CA67)                │
    ├─ Bonus object system ($CB74)                              │
    ├─ Particle system ($CDAA)                                  │
    ├─ OAM sort ($C579)                                         │
    ├─ WaitForFrame ($F465)  ◄──────── waits for NMI flag ──────┘
    │
    ▼ (loop back to $C209)

NMI ($C094) [once per frame]
    ├─ OAM DMA ($4014)
    ├─ Flush PPU command buffer ($C17C)
    ├─ Update transfer sources ($D60D)
    ├─ Build frame OAM ($D798)
    ├─ Frame counter++, scroll setup
    ├─ UpdateAudioFrame ($FFF7 → Sound_F758)
    └─ Set NmiCompletedFlag, rti

---

10. Naming and Residue

Pass 2 (2026-10-19) replaced every address-derived definition with a semantic name — Sub_Cxxx for the routines that had no behavioural name yet, <Routine>_Block[_n] for internal branch targets — so prg.s now contains zero Label_ definitions. The 77 Sound_Fxxx entry points keep their addresses as names in the banked audio region.

Pass 3 applies the two symbol tables to the instruction stream:

• symbols.inc — the NES hardware constants (PPUCTRL … APUFRAMECNT). All 125 numeric register operands are now symbolic.
• locals.inc — zero-page/RAM names plus forward-reference aliases for routine addresses (AbsoluteDifference = $F08E, MainInitialization = $F1D4, …). All but 16 numeric operands are now symbolic.

Placeholder names renamed during the same work:

• Sub_C154 → BuildPpuCommand
• Sub_C17C → FlushPpuCommandPreserved
• Sub_C40C → SpawnRandomObject
• SpawnCommandStreamData_C4AD → RoundSpawnCommandStream (format documented)

Residue. $13 carries three aliases (ReverseRecordIndex, CollisionDeltaY, MotionDeltaHi), none of which fits the 16 sites where it is used as an ordinary high-byte scratch beside Temp12 — in LoadStageObjectData, ReadPpuStreamByte, CreateBonusResultSprites, RenderObjectSprites_Load, ResolveObjectCollisionPair and SwapObjectIndexes. Those operands are deliberately left numeric rather than given a speculative name; a neutral $13 companion to Temp12 would close them.

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

---

11. Audit Trail (comment format)

Every instruction and data line in prg.s carries the canonical repo audit comment — ; CPU:$XXXX PRG:XXXX AA BB — giving the CPU address, the PRG offset and the exact emitted bytes. That comment is the byte-identity trail, so its contents and its column both matter.

What was wrong (fixed 2026-10-21).

1. The addresses were stale by two bytes. The comment trail had been generated when the warm-start signature was still a single byte, so from ResetInitializationData ($C085) onward every comment claimed a CPU address and PRG offset two bytes below the truth — NmiHandler read $C092 instead of $C094, AllocateEffectObject read $C469 instead of $C46B, and so on. The .byte "HAL" string at $C082–$C084 is three bytes, not one. 5,944 of the 6,007 comments were affected; the routine headers (; PRG offsets: / ; CPU range:) and the linker labels were right all along, so the two disagreed with each other.
2. The comments were not in the canonical column. They sat two spaces after the mnemonic instead of in the column-35 field that nesdis.py emits (f" {text:<31}; CPU:…"), so the file had no column discipline at all.

What was done. _tools/repair_audit_comments.py rebuilt the trail from the ca65 -l listing (the linker is ground truth for each source line's offset and byte span) and validated every rewritten comment against prg.bin; _tools/align_audit_comments.py then restored the column. Both steps are whitespace-and-comment only — the code text of all 8,544 lines is unchanged, so the rebuild stays byte-identical.

A bug in _tools/align_audit_comments.py was fixed at the same time: it tested the indented code length against 31 rather than against 35, so code texts of 28–31 characters (83 + 36 + 51 lines here) were never padded into the column.

Verification.

• make → Byte-identical ROM verified.
• All 6,007 audit comments re-checked against prg.bin: every byte list matches the ROM at the offset it names, and every CPU field equals $C000 + PRG.
• All 63 routine headers re-checked against the instruction comments they describe: every ; PRG offsets: range and ; PRG offset: entry point agrees.
• Every label in the source agrees with the linker label file (reconstructed.lbl).
• python3 _tools/verify_pass1.py "Balloon Fight (JU)" → canonical, verdict OK.

---

12. Routine Headers — the Clobbers: Section

The header template AGENTS.md describes is global + local description, parameters, returns, clobbers. The first four were already here; the fifth was missing from 61 of the 63 routine headers (only AllocateEffectObject and AllocateGameplayObject had one, and both were incomplete). All 63 now carry a ; Clobbers: block, so every header in the file is complete.

Nothing was guessed. _tools/derive_clobbers.py derives the block from the source:

• the opcode comes from the audit comment's byte list, so the addressing mode is exact (sta $0400,x is ABSX, sta Zp00 is ZP) and a data directive is never mistaken for an instruction;
• the operand is resolved through locals.inc, symbols.inc and the labels in prg.s, so a clobber can be named — and where several names share one address (Temp12 and RecordIndex are both $12) the first name in locals.inc is used;
• the control flow comes from the instructions. A unit is a named entry point in the source; the code a unit reaches — the shared tails it branches into, the block it falls through into — is its own, while a jsr/jmp to another unit is a call, so the callee's clobbers count but its code is not merged in;
• register preservation is modelled: a small abstract interpreter carries the value of A, X, Y and of each processor flag through the unit, so a routine that saves a register on the stack and puts it back is not reported as clobbering it. That is why FlushPpuCommandPreserved reports only A, and why NmiHandler — which saves and restores A, X and Y around the frame — reports no register at all;
• a call into code the project has not decoded (a forward reference in locals.inc that lands in the undecoded upper bank) can damage anything, so it is reported as a clobber of every register and every flag.

The flags are named individually — the N, Z, C and V flags — because that is what the instructions actually set.

Results worth noting.

Routine	Clobbers	Why
NmiHandler	no register, the N, Z, C and V flags	saves and restores A, X and Y around the frame
FlushPpuCommandPreserved	A, the N, Z and C flags	the name is the contract: X and Y come back unchanged
IrqHandler	nothing	a one-instruction self-loop
TriggerBonusObjectEffect	A, the N, Z, C and V flags	moves Y into X and puts the old X back into X; A is left holding the old X
AllocateEffectObject	A and X, the N and Z flags	the hand-written "A and X." was right about the registers and silent about the rest

Verification. Comment-only change: the code text of all 8,538 lines is unchanged, make still prints Byte-identical ROM verified., the 6,007 audit comments still re-check against prg.bin, and the tool is idempotent — running it twice leaves the file byte-identical.