disasm/_wip/Raid on Bungeling Bay (U)/OVERVIEW.md

# 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 `copilot/prg.s` in the repository. The rebuild is verified **byte-identical** to the original `prg.bin` at the PRG level.

---

## 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` (target $C2C0 — verify during Pass 1) |

---

## 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 | `Zp00` | RAM clear pointer / general |
| $01 | `Zp01` | RAM clear page counter |
| $1B | `Zp1B` | Indirect dispatch ($001B) |
| $17 | `Zp17` | Indirect dispatch ($0017) |
| $19 | `Zp19` | Indirect dispatch ($0019) |
| $01 | `Zp01` | Indirect dispatch ($0001) |
| $55 | `Zp55` | Frame sub-counter/timer |
| $C2 | `ZpC2` | PPUCTRL shadow |
| $C4 | `ZpC4` | NMI path selector (0=minimal, ≠0=full) |
| $D6 | `ZpD6` | Game state (2 = palette) |
| $EA | `ZpEA` | VBlank wait counter |
| $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 and Residue

**Pass 1 complete** — 14,396 lines, 868 `Label_` definitions, canonical audit comments, 64.6% code. 6 seeded routine entries from table references.

**Pass 2 outstanding** — No semantic names applied; all 868 labels remain address-derived `Label_XXXX`.

**Pass 3 outstanding** — No semantic zero-page aliases; `locals.inc` holds neutral `ZpXX` names.

**Indirect dispatch** (not followed statically):
- `jmp ($001B)` at $E7A3
- `jmp ($0017)` at $E79D
- `jmp ($0019)` at $E7A0
- `jmp ($0001)` at $E2EC

**Promotion outstanding** — Add `header.s`/`chr.s` + HEADER/PRG/CHR `linker.cfg`, switch `make` to whole-ROM `cmp`, move `_tools` paths from `../../../_tools/` to `../../_tools/`.

Build verification: `make` in `copilot/` produces `reconstructed_prg.bin`, compared against `prg.bin` (PRG byte-identical).