# Raid on Bungeling Bay (U) — Game Flow from Power-On This document describes the execution flow of the disassembled Raid on Bungeling Bay (U) PRG bank (16 KB, mapped at CPU **$C000–$FFFF**), starting from power-on. It is based entirely on `prg.s` in the repository. The rebuild is verified **byte-identical to the whole ROM** (`reconstructed.nes` = `rom.nes`, header and CHR included). --- ## 1. Reset Vector — CPU $FFFC → $C000 **`Reset`** ($C000) → **`Label_C6E3`** ($C6E3) The RESET vector points to $C000, which contains a single `jmp $C6E3`. The actual reset routine begins at **$C6E3**: | Step | Code | Purpose | |------|------|---------| | 1 | `lda #$10` / `sta $2000` / `sta ZpC2` | PPUCTRL = $10 (NMI off, sprite $0000, BG $0000) + shadow in ZpC2 | | 2–5 | `Label_C6EA`: `inc ZpEA` / `lda $2002` / `bpl` | Wait for VBlank (poll PPUSTATUS bit 7), increment ZpEA | | 6–7 | `ldx #$FF` / `txs` | Initialize stack pointer to $01FF | | 8 | `inx` / `txa` | X=0, A=0 | | 9–13 | `Label_C6F6`: `sta Zp00,x` / `inx` / `cpx #$EA` / `bne` | Clear $0000–$00E9 (234 bytes) | | 14 | `jsr $C98E` | Initialize game systems | | 15–18 | `lda $026D` / `ora $0273` / `cmp #$23` / `beq Label_C719` | Check signature at $026D/$0273; if $23, warm start | | 19–22 | `lda #$23` / `ldx #$0B` / `Label_C70E`: `sta $0268,x` / `dex` / `bpl` / `lda #$25` / `sta $026F` | Cold start: write $23 to $0268–$0273, $25 to $026F | | 23–26 | `Label_C719`: `ldx #$FF` / `txs` / `jsr $C98E` / `lda #$01` / `ldx #$06` | Warm start: re-init stack, systems, set A=1, X=6 | | 27+ | Falls through to main loop | Continue initialization | **Warm-start signature:** Two bytes at $026D/$0273. If their OR equals $23, the game treats it as a warm start (skips full clear, re-initializes stack and systems). --- ## 2. Main Loop After reset initialization, the main loop runs continuously, synchronized with NMI via ZpC4 flag. The loop calls various gameplay subroutines for helicopter control, enemy AI, base building, etc. --- ## 3. Interrupt Vectors — CPU $FFFA–$FFFF Located at PRG offset $3FFA (end of 16 KB bank): | Vector | Address | Handler | |--------|---------|---------| | NMI | $C04C | `NmiHandler` | | RESET | $C000 | `Reset` (jumps to $C6E3) | | IRQ | $C2C0 | `IrqHandler` | --- ## 4. NMI / Frame Heartbeat — `NmiHandler` ($C04C) The NMI fires once per frame and implements a state machine based on **ZpC4** ($C4): ``` NmiHandler ($C04C): pha / txa / pha / tya / pha ; preserve A,X,Y lda ZpC4 ($C4) bne Label_C05F ; ZpC4≠0: Path B lda #$00 / sta $2003 (OAMADDR) lda #$07 / sta $4014 (OAMDMA) ; sprite DMA from $0700 ... (Path A: minimal) Label_C05F: ; Path B: full frame update lda $0200 / ldx #$00 / stx $0200 ; read/clear $0200 lsr a / bcs Label_C0C1 ; bit 0 lsr a / bcs Label_C0A8 ; bit 1 lsr a / bcs Label_C0A6 ; bit 2 lsr a / bcs Label_C0A6 ; bit 3 (same as bit 2) lda ZpC4 / bne Label_C0A3 ; if ZpC4 still set lda Zp55 ($55) / beq Label_C09A ; check Zp55 dec Zp55 / lsr a / bcs Label_C0A0 ; decrement, check bit lda #$3F / sta $2006 / ldx #$00 / stx $2006 / ldx #$10 / lda #$14 Label_C08E: jsr $C006 / dex / bne Label_C08E ; write 16 bytes to PPUDATA ($3F00) jsr $C4E4 / jmp $C17A Label_C09A: lda ZpD6 ($D6) / cmp #$02 / bne Label_C0A3 Label_C0A0: ... (palette/sprite updates) Label_C0A3: ... (gameplay updates) Label_C0A6: ... (sprite updates) Label_C0A8: ... (enemy updates) Label_C0C1: ... (collision/game logic) ``` **Two NMI Paths:** - **Path A (ZpC4=0):** Minimal — only OAM DMA from $0700 - **Path B (ZpC4≠0):** Full — reads $0200 as state bitmap, dispatches to handlers for bits 0–3: - Bit 0 → `Label_C0C1` (collision/game logic) - Bit 1 → `Label_C0A8` (enemy updates) - Bit 2/3 → `Label_C0A6` (sprite updates) - If ZpC4 still set → `Label_C0A3` (gameplay) - Zp55 check → `Label_C09A` (timer-based) - ZpD6=2 → `Label_C0A0` (palette) **Key ZP Flags:** - `ZpC4` ($C4): NMI path selector (0=minimal, ≠0=full) - `Zp55` ($55): Frame sub-counter/timer - `ZpD6` ($D6): Game state (2 = palette update) - `ZpEA` ($EA): VBlank wait counter - `ZpC2` ($C2): PPUCTRL shadow --- ## 5. Key Subsystems ### 5.1 PPU Helper — `$C006` / `$C003` - `$C006`: Write A to PPUDATA ($2007), RTS - `$C003`: `lda $0200,x` (read from $0200+X) ### 5.2 Sprite/OAM System - OAM DMA from $0700 (Path A) or $0200 (Path B) - Sprite updates at `Label_C0A6`, `Label_C0A8` ### 5.3 Palette Updates — `$C08E` / `$C4E4` - When Zp55 expires or ZpD6=2: writes 16 bytes to PPU $3F00 (palette) - Data from $0200+ area ### 5.4 Gameplay Logic - `$C0C1`: Collision detection, helicopter physics - `$C0A8`: Enemy/factory AI - `$C0A6`: Sprite animation - `$C17A`: Base/building logic - `$C98E`: System initialization (called at reset and warm start) ### 5.5 Indirect Dispatch (multiple) Multiple `jmp (zp)` not followed statically: - `jmp ($001B)` at $E7A3 - `jmp ($0017)` at $E79D - `jmp ($0019)` at $E7A0 - `jmp ($0001)` at $E2EC Target addresses in ZP set by callers; require runtime tracing. --- ## 6. Memory Map (Key Zero Page / RAM) | Address | Name | Use | |---------|------|-----| | $00 | `PtrLo` | RAM clear pointer / general pointer low (alias `Zp00`) | | $01 | `PtrHi` / `IndDispatch01` | RAM clear page counter; also the `jmp (ptr)` target for the Sub_8764 computed dispatch at $E2EC | | $1B | `IndDispatch1B` | Indirect dispatch ($001B) | | $17 | `IndDispatch17` | Indirect dispatch ($0017) | | $19 | `IndDispatch19` | Indirect dispatch ($0019) | | $55 | `FrameSubCounter` | Frame sub-counter/timer | | $C2 | `PpuCtrlShadow` | PPUCTRL shadow | | $C4 | `NmiPathSelector` | NMI path selector (0=minimal, ≠0=full) | | $D6 | `GameState` | Game state (2 = palette) | | $EA | `PrngPeriodCounter` | PRNG phase counter — incremented and wrapped at $77 by the PRNG update routine at $C412 (also bumped by the reset vblank-wait loop at $C6EA) | | $EB | `PrngSeedB` | PRNG seed byte — decremented and reloaded with $75 by $C412 | | $EC | `PrngState` | PRNG state byte — xored and stored back at $C43D | | $0200 | State bitmap | Read in NMI Path B (bits 0–3 dispatch) | | $0268–$0273 | Warm-start signature | $23 bytes for warm start detection | | $026D/$0273 | Signature check | OR'd together, compared to $23 | | $026F | `Zp6F` | Gameplay parameter ($25 init) | | $0700 | OAM source (Path A) | Sprite DMA from $0700 when ZpC4=0 | --- ## 7. Summary of Execution Flow ``` Power On / Reset │ ▼ Reset ($C000) ────► jmp $C6E3 │ ▼ Label_C6E3 ($C6E3) ──► PPUCTRL=$10, wait VBlank, stack=$FF │ ├─ Clear $0000–$00E9 (234 bytes) ├─ jsr $C98E (system init) ├─ Check $026D/$0273 signature: │ ├─ OR = $23: Warm start │ │ ldx #$FF / txs / jsr $C98E / A=1, X=6 │ └─ Else: Cold start │ Write $23 to $0268–$0273, $25 to $026F │ ▼ Main Loop (VBlank synchronized via ZpC4) │ ▼ (NMI fires once per frame) NMI ($C04C) ├─ Preserve A,X,Y ├─ lda ZpC4 │ ├─ =0 (Path A): OAM DMA from $0700, minimal │ └─ ≠0 (Path B): │ lda $0200 / stx $0200 (read/clear state bitmap) │ lsr ×4 → dispatch on bits 0–3: │ bit 0: Label_C0C1 (collision/logic) │ bit 1: Label_C0A8 (enemies) │ bit 2/3: Label_C0A6 (sprites) │ ZpC4 still set → Label_C0A3 (gameplay) │ Zp55=0 → Label_C09A (timer) │ dec Zp55, check bit → Label_C0A0 (palette) │ ZpD6=2 → Label_C0A0 (palette) │ Palette: $3F00, 16 bytes via $C006 │ └─ Restore, rti ``` --- ## 8. Naming, Pass 3 State, and Promotion (updated 2026-10-20) **Promoted 2026-10-20** — whole-ROM byte-identical on the first promoted build (`header.s`/`chr.s` + HEADER/PRG/CHR `linker.cfg` added; `make` composes `reconstructed.nes` and `cmp`s it against `rom.nes`). **Naming state** (per `PROMPTS.md`): - 616 global label definitions: 255 `SubC` entry points (address-derived entry names, retained per the promotion bar — `PROMPTS.md` allows `SubC0400`-style names "if no better semantic name exists") plus 361 semantic/branch names (`Reset`, `NmiHandler`, `TransmitByte`, `Sub_8764_OnCarrySet_E2D8`-style conditional-flow labels, table names). - Live prg.s has **no `Label_CXXXX` residue** and **no raw `$XXXX` jsr/jmp/branch operands**. The four indirect-dispatch sites use the `IndDispatchXX` aliases; `jmp (Zp01)` at $E2EC became `jmp (IndDispatch01)` on 2026-10-20. - `locals.inc`: 177 equates — 166 neutral `ZpXX` (roles genuinely undetermined) plus 11 semantic aliases (`PtrLo`, `PtrHi`, `IndDispatch01`/`17`/`19`/`1B`, `FrameSubCounter`, `PpuCtrlShadow`, `NmiPathSelector`, `GameState`, `PrngPeriodCounter`, `PrngSeedB`, `PrngState`). - `apply_symbols.py` reports 0 substitutions available: all zero-page operands are already normalized (1,178 `ZpXX` references in `prg.s`). **Naming correction (2026-10-20, with the `[a2]` dump):** `$EA` was named `VBlankWaitCounter` until the sibling dump was finished. The evidence says otherwise: the routine at `$C412` is the game's pseudo-random generator — it runs the classic 6502 scrambler (`eor` / `asl` / `php` / `lsr` / `plp` / `rol`, twice) over `$EB` and `$EC` and folds `$EA` in twice, and its callers ask for random bytes (`$CDF4`/`$CDF9` call it twice in a row and mask the second result with `#$07`). `$C412` is called from thirteen gameplay sites, not once per frame, so `$EA` is the scrambler's phase counter, not a frame timer. Renamed `PrngPeriodCounter`, and `$EB`/`$EC` were named `PrngSeedB` / `PrngState` at the same time. The same correction was applied to the `[a2]` dump. Two `sta` operands at `$E895`/`$E8D0` were also corrected: they read `a:IndDispatch17,y`, which claimed the dispatch pointer's name for what is really an absolute store to RAM `$0017` (the two-byte copy loop at `$E890`). They now read `a:Zp17,y`, matching the file's `a:` = absolute convention, and `Zp18` was added for the adjacent store to `$0018`. **Residue (documented):** 380 raw absolute operand uses against 91 distinct RAM addresses in $0000–$07FF ($02xx entity/page buffers, $0268–$0273 warm-start signature, $0700 OAM mirror). These have no `locals.inc` names yet; their roles are only partially traced, so they remain numeric rather than guessable — same residue class accepted in `Pinball (JU)` (408 uses) and `Ice Climber (U)` (508 uses). 44 explicit `; ---- data $XXXX-$YYYY` regions and 387 `.byte` lines carry ROM provenance. **Indirect dispatch** (not followed statically — pointers built at runtime): - `jmp (IndDispatch17)` at $E79D - `jmp (IndDispatch19)` at $E7A0 - `jmp (IndDispatch1B)` at $E7A3 - `jmp (IndDispatch01)` at $E2EC (table-walk at $E2EF, four $E3xx entries) Build verification: `make` in this folder produces `reconstructed.nes`, compared whole-ROM against `rom.nes` — **byte-identical**.