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