Standardizes build process and adds OVERVIEW.md for each

2026-10-15 18:50:41 -04:00
1 parent 25423d3828
commit a29b03b00b
@@ -0,0 +1,265 @@
+# 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), set `$15 = $32`, run block-init loop (`jsr $D6DE` 50 times), `jsr $C579` |
+| 32–44 | Copy initialization data | Copy 15 bytes from $C085 to $0629 (initial game state table) |
+| 45–51 | Clear local variables | Zero $03–$06 |
+| 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 $C0F7` — 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 `$2003`, then `$02` to `$4014` (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 $2006/$2005 scroll registers, conditionally waits for VBlank if rendering disabled, writes $2000
+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 |
+| $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" |
+
+---
+
+## 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. Notes on Provisional Areas
+
+Some routines in the disassembly still carry placeholder names (`Label_Cxxxx`, `Sound_FBxx`) and some data blocks were previously marked "undecoded." These have been cleaned up in this review:
+
+- `Sub_C154` → **`BuildPpuCommand`**
+- `Sub_C17C` → **`FlushPpuCommandPreserved`**
+- `Sub_C40C` → **`SpawnRandomObject`**
+- `SpawnCommandStreamData_C4AD` → **`RoundSpawnCommandStream`** (format documented)
+
+The 497 `Label_` branch targets are local intra-routine labels; none are subroutine entry points (confirmed against all `jsr`/`jmp` targets in the source). The 77 `Sound_FBxx` labels are sound-driver entry points in the banked audio region.
+
+Build verification: `make` in `copilot/` produces `reconstructed_prg.bin` that is **byte-identical** to `prg.bin` and to the PRG bank of `balloon.nes`.
@@ -1,10 +1,25 @@
-all: reconstructed_prg.bin verify
-prg.o: prg.s symbols.inc prg.bin
-	ca65 -g -o $@ prg.s
-reconstructed_prg.bin: prg.o linker.cfg
-	ld65 -C linker.cfg -m reconstructed.map -Ln reconstructed.lbl -o $@ prg.o
-verify: reconstructed_prg.bin prg.bin
-	cmp reconstructed_prg.bin prg.bin
-	@echo BYTE-IDENTICAL
+CA65 ?= ca65
+LD65 ?= ld65
+
+all: reconstructed.nes verify
+
+prg.o: prg.s symbols.inc locals.inc
+	$(CA65) -g -o $@ $<
+
+header.o: header.s
+	$(CA65) -g -o $@ $<
+
+chr.o: chr.s
+	$(CA65) -g -o $@ $<
+
+reconstructed.nes: header.o prg.o chr.o linker.cfg
+	$(LD65) -C linker.cfg -m reconstructed.map -Ln reconstructed.lbl -o $@ header.o prg.o chr.o
+
+verify: reconstructed.nes
+	cmp reconstructed.nes rom.nes
+	@echo "Byte-identical ROM verified."
+
 clean:
-	rm -f prg.o reconstructed_prg.bin reconstructed.map reconstructed.lbl
+	rm -f *.o reconstructed.nes reconstructed.map reconstructed.lbl
+
+.PHONY: all verify clean
@@ -0,0 +1,2 @@
+.segment "CHR"
+    .incbin "chr.bin"
@@ -0,0 +1,2 @@
+.segment "HEADER"
+    .incbin "header.bin"
@@ -1,6 +1,10 @@
 MEMORY {
-  PRG: start = $C000, size = $4000, file = %O, fill = yes;
+  HEADER: start = $0000, size = $0010, fill = yes;
+  PRG:    start = $C000, size = $4000, fill = yes;
+  CHR:    start = $0000, size = $2000, fill = yes;
 }
 SEGMENTS {
-  PRG: load = PRG, type = ro;
-}
+  HEADER: load = HEADER, type = ro;
+  PRG:    load = PRG,    type = ro;
+  CHR:    load = CHR,    type = ro;
+}
@@ -1,230 +1,229 @@
-; Balloon Fight application-specific RAM and forward references.
-
-; Spawn-dispatch state
-DispatchPointerLo             = $25
-DispatchPointerHi             = $26
-SpawnCommandPointerLo         = $23
-SpawnCommandPointerHi         = $24
-SpawnParameter                = $14
-SpawnPixelPosition            = $15
-
-; Eight-entry effect-object pool ($00-$07)
-EffectObjectState             = $055D
-EffectObjectPosX              = $0567
-EffectObjectPosY              = $057B
-
-; Twenty-entry gameplay-object pool ($00-$13)
-GameplayObjectPosX            = $0490
-GameplayObjectPosY            = $04A4
-GameplayObjectVelocityY       = $04E0
-GameplayObjectVelocityX       = $04F4
-GameplayObjectParameter       = $0508
-GameplayObjectPosXHi          = $051C
-GameplayObjectState           = $0530
-
-; NMI/PPU state
 PpuControlShadow             = $00
 PpuMaskShadow                = $01
 NmiCompletedFlag             = $02
+CurrentRecord                = $0003
+
+Temp12                       = $12
+RecordIndex                  = $12
+CurrentRoundObjectTile       = $12
+CollisionDeltaX              = $12
+MotionDeltaLo                = $12
+
+ReverseRecordIndex           = $13
+CollisionDeltaY              = $13
+MotionDeltaHi                = $13
+
+SpawnParameter               = $14
+SpawnPixelPosition           = $15
+
 RenderingDisabledFlag        = $16
 PpuScrollX                   = $17
 PpuControlBase               = $18
 FrameCounter                 = $19
+
+RandomState                  = $1B
+
+RecordPtrLo                  = $1D
+RecordPtrHi                  = $1E
+DestinationPtrLo             = $1F
+DestinationPtrHi             = $20
+
 PpuSourcePtrLo               = $21
 PpuSourcePtrHi               = $22
+
+SpawnCommandPointerLo        = $23
+BoundsLeftPtrLo              = $23
+
+SpawnCommandPointerHi        = $24
+BoundsLeftPtrHi              = $24
+
+DispatchPointerLo            = $25
+BoundsRightPtrLo             = $25
+
+DispatchPointerHi            = $26
+BoundsRightPtrHi             = $26
+
+BoundsTopPtrLo               = $27
+BoundsTopPtrHi               = $28
+BoundsBottomPtrLo            = $29
+BoundsBottomPtrHi            = $2A
+
+RoundIndex                   = $3C
+
+CurrentObjectIndex           = $3E
+SequencePlayerIndex          = $3E
+
+PlayerCountMinusOne          = $40
+PlayerActiveFlags            = $41
+
+SelectedRecordIndex          = $43
+
+SequenceStep                 = $46
+SequenceValueLo              = $47
+SequenceValueHi              = $48
+
+SelectedRecordIndexCopy      = $49
+ScaledRecordValue            = $4A
+
 PpuDestinationHi             = $50
 PpuBufferReadOffset          = $52
 PpuBufferWriteOffset         = $53
 PpuCommandAddressHi          = $54
 PpuCommandAddressLo          = $55
 PpuCommandLength             = $56
-Temp12                       = $12

-; Temporary forward references outside the decoded block
-MainInitialization           = $F1D4
-UpdatePpuTransferSources     = $D60D
-BuildFrameOam                = $D798
-WaitForFrame                 = $F465
-InitializeOrQueueObject      = $D6DE
-SortOrInitializeRecords     = $C579
-InitializeAudio              = $F4A5
-UpdateGameplayObjects        = $E691
-UpdateSpecialObjectSystem    = $C6F9
-ReflectObjectYVelocity       = $CA4F
-GetRandomValue               = $F1B3
+RoundHudCommandAddressHi     = $57
+HudCommandAddressHi          = $57
+PpuCommandData0              = $57

-; Sorted five-byte record table helpers
-RecordIndex                  = $12
-ReverseRecordIndex           = $13
-RecordPtrLo                  = $1D
-RecordPtrHi                  = $1E
-DestinationPtrLo             = $1F
-DestinationPtrHi             = $20
-SelectedRecordIndex          = $43
-SelectedRecordIndexCopy      = $49
-ScaledRecordValue            = $4A
-RoundSeedValue               = $0559
-SortedRecordTable            = $0700
-CurrentRecord                = $0003
+RoundHudCommandAddressLo     = $58
+HudCommandAddressLo          = $58
+PpuCommandData1              = $58

-; Temporary forward references used by the decoded record helpers
-UpdateRoundSeedSource        = $D0E2
-DivideOrScaleRecordValue     = $D77C
+RoundHudCommandLength        = $59
+HudCommandLength             = $59
+PpuCommandData2              = $59
+
+RoundHudTile                 = $5A
+HudCommandTile0              = $5A
+
+HudCommandTile1              = $5B
+HudCommandTile2              = $5C
+
+PpuBufferHead                = $5D
+
+SequencePointerLo            = $68
+SequencePointerHi            = $69

-; Carrier/rescue sequence state
 PlayerLifecycleState         = $7F
+
 CarrierDisplayMode           = $87
 PlayerSlotState              = $88
 CarrierPhase                 = $89
+
 PlayerPosX                   = $91
 Player0PosX                  = $92
+
 CarrierTargetX               = $99
 PlayerPosY                   = $9A
 Player0PosY                  = $9B
+
 CarrierPosY                  = $A2
+RoundSpawnRandomLimit        = $A3
+SelectedSpawnIndex           = $A4
+SelectedSpawnIndexCopy       = $A5
+
+RoundSpawnBaseX              = $B2
+RoundSpawnBaseY              = $B5
+RoundSpawnDelay              = $B8
+SpawnSelector                = $BA
+
+PlayerCollisionDisable       = $BD
+SequenceState                = $BE
+
+BonusEffectCounter           = $CB
+GameplayObjectCollisionFlags = $CC
+BoundsCandidateIndex         = $CD
+
+SoundRequestFlags0           = $F0
+SoundRequestFlags1           = $F1
 SoundRequestFlags2           = $F2
+SoundRequestFlags3           = $F3
+
+OamBuffer                    = $0200
+ParticleOamBase              = $0250
+OamEntryE0Y                  = $02E0
+OamEntryE4Y                  = $02E4
+OamEntryE8Y                  = $02E8
+
+PlayerHorizontalImpulse      = $041B
+PlayerVerticalImpulse        = $042D
+
+PlayerVariantTable           = $0448
+CarrierSavedValue            = $0450
+PlayerAnimationState         = $0451
+PlayerStateTimer             = $045A

 CarrierSequenceActive        = $0489
 CarrierMode                  = $048A
 CarrierTargetPlayer          = $048B
 CarrierDropPending           = $048C
 CarrierSequenceTimer         = $048D
-CarrierSavedValue            = $0450
-PlayerVariantTable           = $0448
-PlayerAnimationState         = $0451
-
-; Forward references used by the carrier display/update code
-BuildObjectMetasprite        = $E3A4
-
-; Round initialization state
-RoundIndex                   = $3C
-CurrentObjectIndex           = $3E
-RoundSpawnDelay              = $B8
-SpawnSelector                = $BA
-SoundRequestFlags3           = $F3
-GameplayObjectAuxState       = $0544
-OamEntryE0Y                  = $02E0
-OamEntryE4Y                  = $02E4
-OamEntryE8Y                  = $02E8
-
-; Forward references used by round initialization
-SpawnRoundObjects             = $C77A
-
-; Round spawner and HUD state
-RoundSpawnRandomLimit        = $A3
-SelectedSpawnIndex           = $A4
-SelectedSpawnIndexCopy       = $A5
-RoundHudTile                 = $5A
-
-; Three-byte HUD command staged at $57-$59 before buffer append
-RoundHudCommandAddressHi      = $57
-RoundHudCommandAddressLo      = $58
-RoundHudCommandLength         = $59
-SoundRequestFlags0           = $F0
-SoundRequestFlags1           = $F1

+GameplayObjectPosX           = $0490
+GameplayObjectPosY           = $04A4
 GameplayObjectVelocityFracY  = $04B8
 GameplayObjectVelocityIntY   = $04CC
+GameplayObjectVelocityY      = $04E0
+GameplayObjectVelocityX      = $04F4

-; Temporary forward references for round spawn parameter tables
+GameplayObjectParameter      = $0508
+GameplayObjectPosXHi         = $051C
+GameplayObjectState          = $0530
+GameplayObjectAuxState       = $0544

-; Round-object renderer state
-CurrentRoundObjectTile       = $12
-RoundSpawnBaseX              = $B2
-RoundSpawnBaseY              = $B5
-OamBuffer                    = $0200
+ParticleSequenceIndex        = $0558
+RoundSeedValue               = $0559
+ParticleSequenceValue        = $0559
+ParticleScrollDelta          = $055A
+SequenceDataLo               = $055B
+SequenceDataHi               = $055C

-; Forward tables and routines used by the round-object renderer
+EffectObjectState            = $055D
+ParticleState                = $055D

-; Table-driven gameplay-object boundary tests
-BoundsLeftPtrLo              = $23
-BoundsLeftPtrHi              = $24
-BoundsRightPtrLo             = $25
-BoundsRightPtrHi             = $26
-BoundsTopPtrLo               = $27
-BoundsTopPtrHi               = $28
-BoundsBottomPtrLo            = $29
-BoundsBottomPtrHi            = $2A
-GameplayObjectCollisionFlags = $CC
-BoundsCandidateIndex         = $CD
+EffectObjectPosX             = $0567
+ParticlePosX                 = $0567

-; Forward routine at the next decoded boundary
+ParticlePosXFrac             = $0571

-; Gameplay-object/player interaction state
-CollisionDeltaX              = $12
-CollisionDeltaY              = $13
-PlayerCollisionDisable       = $BD
-PlayerStateTimer             = $045A
-PlayerHorizontalImpulse      = $041B
-PlayerVerticalImpulse        = $042D
+EffectObjectPosY             = $057B
+ParticlePosY                 = $057B
+
+ParticlePosYFrac             = $0585
+ParticleVelocityXHi          = $058F
+ParticleVelocityXLo          = $0599
+
+ParticleVelocityYLo          = $05B7
+ParticleVelocityYHi          = $05C1
+
+ParticleSpawnRemaining       = $05CB
+ParticleSpawnCountdown       = $05CC
+PlayerParticleHitCount       = $05CD
+PlayerParticleHitCount2      = $05CE

-; Bonus-object subsystem
-BonusEffectCounter           = $CB
 ActiveBonusObjectIndex       = $05D1
 BonusObjectPosX              = $05D2
 BonusObjectPosY              = $05DC
 BonusHudAddressLo            = $05E6
 BonusHudAddressHi            = $05F0
 BonusObjectPhase             = $05FA
+
 BonusObjectTimer             = $0604
 BonusObjectPhaseTimer        = $060E

-; Bonus HUD command staged at $57-$5C
-HudCommandAddressHi          = $57
-HudCommandAddressLo          = $58
-HudCommandLength             = $59
-HudCommandTile0              = $5A
-HudCommandTile1              = $5B
-HudCommandTile2              = $5C
+SortedRecordTable            = $0700

-; Forward references used by interaction and bonus-object code
 AbsoluteDifference           = $F08E
+UpdateSignedMotionAccumulator = $F1A6
+GetRandomValue               = $F1B3
+MainInitialization           = $F1D4
+WaitForFrame                 = $F465
+InitializeAudio              = $F4A5
+
+SortOrInitializeRecords      = $C579
+SpawnRoundObjects            = $C77A
+UpdateRoundSeedSource        = $D0E2
+UpdatePpuTransferSources     = $D60D
+InitializeOrQueueObject      = $D6DE
+BuildFrameOam                = $D798
+DivideOrScaleRecordValue     = $D77C
+
+BuildObjectMetasprite        = $E3A4
+UpdateGameplayObjects        = $E691
 ApplyBonusEffect             = $E983
 AdjustPlayerHorizontalState  = $EBB2
 AdjustPlayerVerticalState    = $EBBB

-; Ten-slot particle/effect subsystem
-RandomState                  = $1B
-MotionDeltaLo                = $12
-MotionDeltaHi                = $13
-ParticleScrollDelta          = $055A
-ParticleState                = $055D
-ParticlePosX                 = $0567
-ParticlePosXFrac             = $0571
-ParticlePosY                 = $057B
-ParticlePosYFrac             = $0585
-ParticleVelocityXHi          = $058F
-ParticleVelocityXLo          = $0599
-ParticleVelocityYLo          = $05B7
-ParticleVelocityYHi          = $05C1
-ParticleSpawnRemaining       = $05CB
-ParticleSpawnCountdown       = $05CC
-ParticleOamBase              = $0250
-
-; Forward references used by the particle subsystem
-UpdateSignedMotionAccumulator = $F1A6
-
-; Particle result/sequence state
-ParticleSequenceIndex        = $0558
-ParticleSequenceValue        = $0559
-SequenceDataLo               = $055B
-SequenceDataHi               = $055C
-PlayerParticleHitCount       = $05CD
-PlayerParticleHitCount2      = $05CE
-SequencePlayerIndex          = $3E
-SequenceStep                 = $46
-SequenceValueLo              = $47
-SequenceValueHi              = $48
-SequencePointerLo            = $68
-SequencePointerHi            = $69
-SequenceState                = $BE
-
-; Forward parameter tables for the next sequence-data block
-
-; Shared player-count and PPU staging aliases used by the particle sequence
-PlayerCountMinusOne          = $40
-PlayerActiveFlags            = $41
-PpuCommandData0              = $57
-PpuCommandData1              = $58
-PpuCommandData2              = $59
-PpuBufferHead                = $5D
+ReflectObjectYVelocity       = $CA4F
+UpdateSpecialObjectSystem    = $C6F9
@@ -154,7 +154,7 @@ NmiHandler:
    lda PpuBufferReadOffset       ; $00A3: A5 52
    cmp PpuBufferWriteOffset      ; $00A5: C5 53
    beq Label_C0AC                ; $00A7: F0 03
-    jsr Sub_C17C                  ; $00A9: 20 7C C1
+    jsr FlushPpuCommandPreserved    ; $00A9: 20 7C C1
 Label_C0AC:
    jsr UpdatePpuTransferSources  ; $00AC: 20 0D D6
    jsr BuildFrameOam             ; $00AF: 20 98 D7
@@ -340,7 +340,7 @@ SetPpuMask:
 ;===============================================================================

 WaitForFrameAndSetPpuMask:
-    jsr Sub_C154                  ; $0119: 20 54 C1
+    jsr BuildPpuCommand           ; $0119: 20 54 C1
    ldy #$00                      ; $011C: A0 00
 Label_C11E:
    lda $0057,y                   ; $011E: B9 57 00
@@ -439,26 +439,27 @@ Label_C144:
    tax                           ; $0152: AA
    rts                           ; $0153: 60
 ;===============================================================================
-; Sub_C154
+; BuildPpuCommand
 ;
 ; Global:
-;   Reachable game-engine routine identified during recursive Pass-1 tracing.
+;   Builds a PPU command-buffer entry from the pending command address/length.
 ;
 ; Local:
-;   Performs the control flow beginning at CPU $C154; detailed semantics are
-;   refined as its RAM and table dependencies are traced.
+;   Formats the PPU command (address high byte with $20 prefix, address low
+;   byte, length) and writes it into the command buffer at $0300.
 ;
 ; Parameters:
-;   Caller-defined register and global RAM state.
+;   PpuCommandAddressLo/Hi ($55/$54), PpuCommandLength ($56),
+;   PpuBufferWriteOffset ($53).
 ;
 ; Returns:
-;   Routine-specific result; register preservation remains provisional.
+;   PpuBufferWriteOffset advanced; command bytes appended to $0300 buffer.
 ;
 ; PRG offset: $0154
 ; CPU address: $C154
 ;===============================================================================

-Sub_C154:
+BuildPpuCommand:
    ldx PpuBufferWriteOffset      ; $0154: A6 53
    lda #$00                      ; $0156: A9 00
    sta Temp12                    ; $0158: 85 12
@@ -505,26 +506,26 @@ AppendPpuAddressAndLength:
    inx                           ; $017A: E8
    rts                           ; $017B: 60
 ;===============================================================================
-; Sub_C17C
+; FlushPpuCommandPreserved
 ;
 ; Global:
-;   Reachable game-engine routine identified during recursive Pass-1 tracing.
+;   Flushes the PPU command buffer while preserving the X and Y registers.
 ;
 ; Local:
-;   Performs the control flow beginning at CPU $C17C; detailed semantics are
-;   refined as its RAM and table dependencies are traced.
+;   Saves X/Y, calls PreserveXYAndFinalizePpuCommand to walk the $0300 command
+;   buffer and write pending PPU updates, then restores X/Y.
 ;
 ; Parameters:
-;   Caller-defined register and global RAM state.
+;   PpuBufferReadOffset/WriteOffset ($52/$53).
 ;
 ; Returns:
-;   Routine-specific result; register preservation remains provisional.
+;   X and Y preserved; PPU command buffer drained.
 ;
 ; PRG offset: $017C
 ; CPU address: $C17C
 ;===============================================================================

-Sub_C17C:
+FlushPpuCommandPreserved:
    tya                           ; $017C: 98
    pha                           ; $017D: 48
    txa                           ; $017E: 8A
@@ -978,35 +979,38 @@ SpawnAtRandomPosition:
    jsr GetRandomValue            ; $03F7: 20 B3 F1
    and #$7F                      ; $03FA: 29 7F
    cmp #$04                      ; $03FC: C9 04
-    bcc Sub_C40C                  ; $03FE: 90 0C
+    bcc SpawnRandomObject                  ; $03FE: 90 0C
    cmp #$18                      ; $0400: C9 18
-    bcs Sub_C40C                  ; $0402: B0 08
+    bcs SpawnRandomObject                  ; $0402: B0 08
    asl a                         ; $0404: 0A
    asl a                         ; $0405: 0A
    asl a                         ; $0406: 0A
    sta SpawnPixelPosition        ; $0407: 85 15
    jsr AllocateEffectObject      ; $0409: 20 6B C4
 ;===============================================================================
-; Sub_C40C
+; SpawnRandomObject
 ;
 ; Global:
-;   Reachable game-engine routine identified during recursive Pass-1 tracing.
+;   Spawns a gameplay object at a randomized screen position.
 ;
 ; Local:
-;   Performs the control flow beginning at CPU $C40C; detailed semantics are
-;   refined as its RAM and table dependencies are traced.
+;   Picks a random Y position in the valid band, snaps it to a 32-pixel grid,
+;   derives a spawn parameter from random state and the spawn selector table,
+;   allocates a gameplay-object slot, then retries (optionally reflecting Y
+;   velocity) until the object is placed or the slot pool is exhausted.
 ;
 ; Parameters:
-;   Caller-defined register and global RAM state.
+;   RandomState ($1B), SpawnSelector ($BA), SpawnSelectorAdjustmentTable.
 ;
 ; Returns:
-;   Routine-specific result; register preservation remains provisional.
+;   A gameplay object allocated and initialized; X = slot ($00-$13) or $FF if
+;   the pool is full.
 ;
 ; PRG offset: $040C
 ; CPU address: $C40C
 ;===============================================================================

-Sub_C40C:
+SpawnRandomObject:
    jsr GetRandomValue            ; $040C: 20 B3 F1
    and #$3F                      ; $040F: 29 3F
    cmp #$02                      ; $0411: C9 02
@@ -1025,9 +1029,9 @@ Sub_C40C:
    jsr $C486                     ; $042A: 20 86 C4
    jsr GetRandomValue            ; $042D: 20 B3 F1
    lsr a                         ; $0430: 4A
-    bcc Sub_C40C                  ; $0431: 90 D9
+    bcc SpawnRandomObject                  ; $0431: 90 D9
    jsr ReflectObjectYVelocity    ; $0433: 20 4F CA
-    jmp Sub_C40C                  ; $0436: 4C 0C C4
+    jmp SpawnRandomObject           ; $0436: 4C 0C C4
 Label_C439:
    rts                           ; $0439: 60
 SpawnSelectorAdjustmentTable:
@@ -1112,7 +1116,7 @@ SpawnPatternNoneAlt:
 ;===============================================================================

 InitializeSpecialObject:
-    jsr Sub_C40C                  ; $045F: 20 0C C4
+    jsr SpawnRandomObject           ; $045F: 20 0C C4
    jsr GetRandomValue            ; $0462: 20 B3 F1
    and #$7F                      ; $0465: 29 7F
    sta $0508,x                   ; $0467: 9D 08 05
@@ -1210,17 +1214,19 @@ AllocateGameplayObject:
    sta GameplayObjectPosY,x    ; $04A9: 9D A4 04
    rts                         ; $04AC: 60

-; Preserve the remaining undecoded PRG bytes.
-;===============================================================================
-; SpawnCommandStreamData_C4AD
+; Round spawn command stream
 ;
-; Structured spawn/object command data preceding the sorted-record helpers.
-; The exact record boundaries and gameplay meanings remain provisional.
+; Command data consumed by SpawnFromCommandStream ($C3C9) to initialize
+; round objects. Each command byte: top 3 bits give the spawn Y position,
+; bits 7-6 select object type (%10 = effect object via AllocateEffectObject,
+; %00 = gameplay object via AllocateGameplayObject), and any other value
+; terminates the stream.
 ;
 ; PRG offsets: $04AD-$0526
 ; CPU range:   $C4AD-$C526
 ;===============================================================================
-SpawnCommandStreamData_C4AD:
+
+RoundSpawnCommandStream:
    .byte $00, $00, $09, $00, $08, $8C, $00, $07; $04AD: 00 00 09 00 08 8C 00 07
    .byte $18, $00, $18, $00, $19, $00, $1A, $00; $04B5: 18 00 18 00 19 00 1A 00
    .byte $84, $94, $1A, $00, $1A, $00, $1A, $00; $04BD: 84 94 1A 00 1A 00 1A 00
@@ -1384,8 +1390,6 @@ Label_C5AE:
    bpl Label_C5AE                    ; $05B4: 10 F8
    rts                               ; $05B6: 60

-; Preserve the remaining undecoded PRG bytes.
-;===============================================================================
 ; Carrier display-selection tables
 ;===============================================================================
 NormalDisplayModeTable:
@@ -1604,8 +1608,6 @@ Label_C6B3:
 Label_C6B7:
    rts                                 ; $06B7: 60

-; Preserve the remaining undecoded PRG bytes.
-;===============================================================================
 ; Carrier animation remap table
 ; Maps player animation states to the carrier-sequence animation states.
 ;===============================================================================
@@ -1759,8 +1761,6 @@ Label_C72E:
    lda #$03                            ; $0743: A9 03
    jmp ConfigureRoundPresentation      ; $0745: 4C 56 C8

-; Preserve the remaining undecoded PRG bytes.
-;===============================================================================
 ; Round spawn lookup tables
 ;===============================================================================
 RoundObjectCountTable:
@@ -2010,8 +2010,6 @@ AppendRoundHudValue:
 Label_C88A:
    rts                                   ; $088A: 60

-; Preserve the remaining undecoded PRG bytes.
-;===============================================================================
 ; Round spawner and sprite lookup tables
 ;===============================================================================
 RoundHudTileTable:
@@ -2215,8 +2213,6 @@ IntegrateGameplayObjectPosition:
    sta GameplayObjectPosY,x                ; $09D9: 9D A4 04
    rts                                     ; $09DC: 60

-; Preserve the remaining undecoded PRG bytes.
-;===============================================================================
 ; Round-object sprite tables
 ;===============================================================================
 RoundObjectTileTable:
@@ -2426,8 +2422,7 @@ Label_CB0C:
 Label_CB18:
    jmp Label_CAE1                           ; $0B18: 4C E1 CA

-; Preserve the remaining undecoded PRG bytes.
-; $0B1B is the RTS terminating TestGameplayObjectAgainstBounds.
+; $0B1B: RTS terminating TestGameplayObjectAgainstBounds.
    rts                                      ; $0B1B: 60

 ;===============================================================================
@@ -2867,8 +2862,6 @@ AdvanceHudCommandAddress:
 Label_CD25:
    rts                                      ; $0D25: 60

-; Preserve the remaining undecoded PRG bytes.
-;===============================================================================
 ; Bonus-object HUD tile triplets
 ;
 ; Each four-byte table is indexed by BonusObjectPhase ($00-$03). The three
@@ -2900,7 +2893,6 @@ BonusHudRow2Tile1Table:
 BonusHudRow2Tile2Table:
    .byte $A7, $24, $24, $24             ; $0D46: A7 24 24 24

-; Preserve the remaining undecoded PRG bytes.
 ;===============================================================================
 ; InitializeParticleSlots
 ;
@@ -3152,8 +3144,6 @@ Label_CE99:
    sta $0259,y                              ; $0EAA: 99 59 02
    rts                                      ; $0EAD: 60

-; Preserve the remaining undecoded PRG bytes.
-;===============================================================================
 ; Particle rendering tables
 ;===============================================================================
 ParticleInitialVelocityTable:
@@ -3502,7 +3492,6 @@ Label_D104:
    sta PlayerParticleHitCount2               ; $1109: 8D CE 05
    rts                                       ; $110C: 60

-; Preserve the remaining undecoded PRG bytes.
 ; Sequence parameter tables
 ParticleSequenceIndexTable:
    .byte $03, $05, $07, $07, $07 ; $110D: 03 05 07 07 07
@@ -4172,7 +4161,6 @@ GetNametableAddressForIndex:
    sta $51                                   ; $1659: 85 51
    rts                                       ; $165B: 60

-; Preserve the remaining undecoded PRG bytes.
 NametableAddressPairTable:
    .byte $63, $21, $A5, $21, $CB, $20, $B7, $20 ; $165C: 63 21 A5 21 CB 20 B7 20
    .byte $7D, $21, $9B, $22, $F2, $20, $49, $22 ; $1664: 7D 21 9B 22 F2 20 49 22
@@ -0,0 +1 @@
+../balloon.nes
@@ -0,0 +1,52 @@
+; PPU registers 
+PPUCTRL = $2000
+PPUMASK = $2001
+PPUSTATUS = $2002
+OAMADDR = $2003
+OAMDATA = $2004
+PPUSCROLL = $2005
+PPUADDR = $2006
+PPUDATA = $2007
+OAMDMA = $4014
+JOY1 = $4016
+JOY2 = $4017
+
+APUPC1BASE = $4000
+APUPC1SWEEP = $4001
+APUPC1TLOW = $4002
+APUPC1THIGH = $4003
+
+APUPC2BASE = $4004
+APUPC2SWEEP = $4005
+APUPC2LOW = $4006
+APUPC2HIGH = $4007
+
+APUTRIBASE = $4008
+APUTRILOW = $400A
+APUTRIHIGH = $400B
+
+APUNOISEBASE = $400C
+APUNOISELOOP = $400E
+APUNOISELENGTH = $400F
+
+APUDMABASE = $4010
+APUDMALOAD = $4011
+APUDMAADDR = $4012
+APUDMALEN = $4013
+
+APUCTRL = $4015
+APUSTATUS = $4015
+APUFRAMECNT = $4017
+
+; Controller Masks
+PAD_RIGHT=$01
+PAD_LEFT=$02
+PAD_DOWN=$04
+PAD_UP=$08
+PAD_START=$10
+PAD_SELECT=$20
+PAD_B=$40
+PAD_A=$80
+PAD_HORIZONTAL=PAD_LEFT|PAD_RIGHT
+PAD_VERTICAL=PAD_UP|PAD_DOWN
+PAD_DPAD=PAD_HORIZONTAL|PAD_VERTICAL