# Clu Clu Land (JU) — Game Flow from Power-On

This document describes the execution flow of the disassembled Clu Clu Land (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. ROM and Memory Layout

| Property | Value |
|----------|-------|
| Format | iNES / NES 2.0 |
| PRG | 1 × 16 KB (mapped at CPU $C000–$FFFF) |
| CHR | 1 × 8 KB |
| Mirroring | Horizontal |
| PRG bank start | CPU $C000 |
| Source file | `copilot/prg.s` (9,150 lines) |
| Output | `reconstructed_prg.bin` (16,384 bytes) |

### Interrupt vectors (CPU $FFFA–$FFFF)

| Vector | Address | Handler |
|--------|---------|---------|
| NMI | $C1F1 | `NMIHandler` |
| RESET | $C196 | `ResetEntry` |
| IRQ / BRK | $C196 | `IRQHandler` (reuses `ResetEntry`) |

---

## 2. Build Status

`make` in `copilot/` assembles `prg.s` with `ca65`, links with `ld65`, and verifies against `prg.bin`.

**Verification result: BYTE-IDENTICAL** — `reconstructed_prg.bin` matches `prg.bin` exactly (all 16,384 bytes), and `prg.bin` matches the PRG bank of `rom.nes`.

---

## 3. Reset — CPU $FFFC → $C196

**`ResetEntry`** ($C196)

On power-on or reset:

1. `CLD` — clear decimal mode.
2. `LDA #$00 / STA PPUCTRL` — disable PPU rendering/NMI.
3. `SEI` — disable maskable interrupts.
4. `LDX #$FF / TXS` — initialize stack pointer to $FF.
5. **Wait for two VBlanks** — `InterruptPathLoop_C1A2` (`LDX #$02`, then poll `PPUSTATUS` bit 7 twice via `DEX`/`BNE`). This is the PPU warm-up delay.
6. **Clear RAM** — `LDY #$24` (or `$18` if `StartupPreserveFlag0`/$48 or `StartupPreserveFlag1`/$49 is nonzero), then `STA $0000,Y` in a loop clearing zero page + one page. The Y start value ($24 vs $18) is selected by the two preserve flags.
7. `JSR RunGameTaskRoutine_CBA6` ($C1C2) — run an initial game task routine with Y=$07, X=$06.
8. `LDA #$55 / STA FrameShiftRegister0` ($10) — initialize frame shift register 0.
9. `LDA #$12 / STA PPUCTRL / STA ShadowPPUCTRL` ($40) — set PPU control to $12 (NMI enabled, $2000 base) and shadow.
10. `LDA #$06 / STA PPUMASK / STA ShadowPPUMASK` ($41) — enable background + sprites, set mask shadow.
11. `LDA #$0F / STA APUSTATUS / STA $0100` — enable all four APU channels, write to $0100.
12. `JSR RunGameTaskRoutine_C3E4` ($C1DF) — run the C3E4 game task routine.
13. `LDA ShadowPPUCTRL / ORA #$80 / STA ShadowPPUCTRL / STA PPUCTRL` — set NMI enable bit in shadow and PPUCTRL (enables NMI).
14. Falls into **`InterruptPathDispatch_C1EB`** ($C1EB) — the permanent main loop.

---

## 4. Main Loop — `InterruptPathDispatch_C1EB` ($C1EB)

Once NMI is enabled, ResetEntry never returns. It enters an infinite loop:

```
InterruptPathDispatch_C1EB ($C1EB):
    JSR EnginePath_F58D      ; $C1EB: 20 8D F5   - frame/input processing
    JMP InterruptPathDispatch_C1EB  ; $C1EE: 4C EB C1  - loop forever
```

The real-time work happens in the **NMI** (see section 5). The main loop only repeatedly calls `EnginePath_F58D` and spins. `EnginePath_F58D` ($F58D) shifts the frame shift registers ($10–$17) right based on controller input bits ($10/$11 bit 2), producing a carry that drives rotation.

---

## 5. NMI / Frame Heartbeat — `NMIHandler` ($C1F1)

The NMI fires once per frame and is the central real-time driver. It:

1. **Save A** (`PHA`) and **save WorkPtr0Lo** ($00) onto the stack.
2. **PPU control**: `LDA ShadowPPUCTRL ($40) / AND #$7F` (clear NMI bit), store back to shadow and $2000 — this **temporarily disables NMI** during the handler to prevent re-entry.
3. **PPU mask**: `LDA ShadowPPUMASK ($41) / AND #$E7` (clear sprite/background enable bits), store to shadow and $2001 — rendering off during updates.
4. **Game state update**: `JSR UpdateGameStateRoutine_C996` ($C207) — core per-frame game state logic.
5. **OAM DMA**: write $00 to OAMADDR ($2003), then $02 to OAMDMA ($4014) — DMA $0200–$02FF to sprite RAM.
6. **Resource/level data**: `JSR ResourceAndLevelData` ($F20B) — PPU command buffer processing / nametable updates.
7. **Object paths**: `JSR ObjectPath_E113` ($E113), then `JSR ObjectPath_DDC1` ($DDC1) — object movement/collision.
8. **Restore PPU**: write ShadowPPUCTRL ($40) to $2000; `LDA ShadowPPUMASK / ORA #$18` (re-enable background + sprites), store to shadow and $2001 — rendering back on.
9. **Audio driver**: `JSR AudioDriverCode` ($F7C1) — process all audio channels.
10. **Engine path**: `JSR EnginePath_F5AE` ($F5AE) — controller strobing + input processing (`ProcessResourceStateRoutine_F5BE`).
11. **Object path**: `JSR ObjectPath_DDC1` ($DDC1) again.
12. **Game task**: `JSR RunGameTaskRoutine_C368` ($C368) — main game task dispatcher.
13. **PPU status poll**: `NMIReadPPUStatus_C234` — read PPUSTATUS (reset address latch).
14. **Re-enable NMI**: `LDA ShadowPPUCTRL / ORA #$80 / STA ShadowPPUCTRL / STA PPUCTRL`.
15. **Restore**: `PLA / STA WorkPtr0Lo ($00)`, `PLA`, `RTI`.

### AudioDriverCode ($F7C1)
Called from NMI. Processes four audio state routines in sequence:
- `ProcessAudioStateRoutine_F898`
- `ProcessAudioStateRoutine_FA2E`
- `ProcessAudioStateRoutine_FACF`
- `ProcessAudioStateRoutine_FB22`
Then clears audio request bytes $FB–$FF, handles the noise channel ($07FE, $4011), and returns.

---

## 6. Game Task Dispatcher — `RunGameTaskRoutine_C368` ($C368)

Called each NMI frame. This is the primary gameplay dispatcher with multiple entry points ($C368, $C3BC, $C3E4, $C402, $C463, $C47A, etc.). It branches on game state variables ($92, $B0, $8A, $8D, $8C, etc.) to:

- `ProcessResourceStateRoutine_F577` — resource processing
- `CoreGameCode` ($C245) — the large central object-processing routine (see section 7)
- `RunGameTaskRoutine_C6BE`, `C7EF`, `C7F3`, `C809`, `C816`, `C81A`, `C824`, `C830`, `C84B` — various sub-tasks
- `ProcessResourceStateRoutine_F40C / F408 / F31A / F77D` — resource/command buffer updates

The dispatcher uses a dense network of `CorePath*` / `UpdateGameState*` / `UpdatePlayerState*` / `RunGameTaskDispatch_*` branch targets driven by zero-page state ($8A–$8F, $90–$93, $A7, $AC–$AF, $B0, etc.).

---

## 7. Core Object Processing — `CoreGameCode` ($C245)

The largest single routine in the bank. Called from the task dispatcher. It processes objects in two main phases:

**Phase 1** ($C245–$C264):
- `JSR RunGameTaskRoutine_CBB9`
- `JSR ObjectPath_D34E`
- `JSR UpdateObjectRecord_D27D`
- Object record reads from `CurrentObjectPtrLo/Hi` ($08/$09): `ReadObjectRecord_DADA`, `ReadObjectRecord_CD7B`, `ReadObjectRecord_D11E`

**Phase 2** ($C264–$C2C2):
- `JSR ObjectPath_D06D`, `RunGameTaskRoutine_CBC6`, `ObjectPath_D34E`, `UpdateObjectRecord_D27D`
- Second set of object record reads
- Long chain of object buffer/update routines: `ObjectPath_D08F`, `ObjectPath_DD10`, `ObjectPath_DC5A`, `UpdateObjectBuffer_DB52`, `ObjectPath_D856`, `ObjectPath_D8BA`, `UpdateObjectBuffer_D64F`, `ObjectPath_D97B`, `UpdateObjectBuffer_D0C8`, `ObjectPath_CFA1`, `ObjectPath_D0B1`, `ProcessObjectStateRoutine_E6F3`, `ObjectPath_DA91`, `UpdateObjectBuffer_DBC7`, `ObjectPath_D0DF`, `ObjectPath_D1D6`, `UpdateObjectBuffer_DD8F`, `UpdateObjectBuffer_D0F6`, `UpdateGameStateRoutine_C47A`, `ObjectPath_D209`, then `RTS`.

**Object loop** (`CorePathLoop_C2C3` at $C2C3):
- `JSR RunGameTaskRoutine_C84B`
- Clears $0080–$009F (32 bytes) via indexed store
- `RoundOrSubstate` ($88) = 0
- Player/game state initialization based on `ContextIndex` ($4A)

---

## 8. PPU Command / Nametable Processing — `ResourceAndLevelData` ($F20B)

Called from NMI. Processes an embedded command stream at $0301:
- Reads PPU address high/low from $0301,Y
- Writes a counted block of bytes to $2007 (PPUDATA)
- Handles $3F-prefixed commands (palette) specially — re-writes PPUADDR
- This is the nametable/palette update pipeline driven during VBlank.

Supporting PPU helpers:
- `SetDefaultScroll` ($FFEB) — writes $08, $00 to PPUSCROLL
- `LoadPalette` style routines via `ProcessResourceStateRoutine_F40C/F408/F31A/F77D`
- `UpdateCommandBufferRoutine_F3A1`

---

## 9. Object System

Object processing is spread across many `ObjectPath_*` and `UpdateObjectBuffer_*` / `UpdateObjectRecord_*` / `ReadObjectRecord_*` / `ProcessObjectState*` routines in the $C000–$EFFF range:

| Group | Address Range | Purpose |
|-------|---------------|---------|
| ObjectPath_D06D / D08F / D0B1 / D0DF / D1D6 / D209 | $Cxxx | Object coordinate/state update |
| ObjectPath_D34E | $CD3E | Object processing core |
| ObjectPath_D856 / D8BA / D97B | $CDxx | Object buffer/rendering |
| ObjectPath_DC5A / DD10 / DDC1 | $CDxx–$DDxx | Object collision/movement |
| ObjectPath_E113 | $E113 | Object entry (called from NMI) |
| UpdateObjectRecord_D27D | $CD27D | Object record maintenance |
| ReadObjectRecord_DADA / CD7B / D11E | $CDxx–$DAxx | Object record reading |
| ProcessObjectStateRoutine_E6F3 / D1CE / D211 / D42C / D44A / D94D / DA26 | $CDxx–$E6xx | Object state machine dispatch |
| UpdateObjectBuffer_DB52 / D64F / DBC7 / DD8F / D0F6 | $CDxx–$DDxx | OAM buffer writes |
| ProcessCurrentObjectRoutine_CBE3 | $CBE3 | Current object processing |

Objects use `CurrentObjectPtrLo/Hi` ($08/$09) and `CurrentObjectIndex` ($0A) for indirect access. Object state arrays live in zero page ($90–$AF, $D0–$D8) and RAM ($0400–$07FF).

---

## 10. Zero-Page / RAM Symbols

| Address | Symbol | Use |
|---------|--------|-----|
| $00–$01 | WorkPtr0Lo/Hi | General indirect pointer (also saved across NMI) |
| $02–$03 | WorkPtr1Lo/Hi | Secondary pointer |
| $04–$05 | DataPtrLo/Hi | Data pointer |
| $06–$07 | ListPtrLo/Hi | List pointer |
| $08–$09 | CurrentObjectPtrLo/Hi | Current object pointer |
| $0A | CurrentObjectIndex | Current object index |
| $0B–$0C | AlternateObjectPtrLo/Hi | Alternate object pointer |
| $0D–$0E | TempDirection / TempClass | Temporary direction/class |
| $0F | LoopCounter | Loop counter |
| $10–$17 | FrameShiftRegister0–7 | Frame shift registers (input/frame state) |
| $20–$23 | CollisionRecordA0–A3 | Collision records |
| $24–$27 | VectorComponent0–3 | Vector components |
| $2C–$2F | TempField2C–2F | Temporary fields |
| $33–$34 | TempField33/34 | Temporary fields |
| $3F | TempField3F | Temporary field |
| $40 | ShadowPPUCTRL | $2000 mirror |
| $41 | ShadowPPUMASK | $2001 mirror |
| $42–$43 | ScrollOrRenderState0/1 | Scroll/render state |
| $44–$47 | ControllerButtonsBase/AltBase | Controller state ($44,$46 indexed) |
| $48–$49 | StartupPreserveFlag0/1 | Startup preserve flags |
| $4A | ContextIndex | Context index |
| $4B | ModeToggleFlag | Mode toggle |
| $4C | ActiveContext | Active context |
| $4D | PendingStateIndex | Pending state index |
| $4E | StateTransitionFlag | State transition flag |
| $4F | InputLockFlag | Input lock flag |
| $50 | GlobalTickDivider | Global tick divider |
| $51–$68 | TimerArrayBase / GameVar* | Timers and gameplay variables |
| $75–$7D | PlayerTimerBase / PlayerTimer1/2 / StateTimer / InputRepeatDelay | Player timers |
| $80–$8F | MatchState80–StateCounter8F | Match/game state (RoundOrSubstate=$88, GameState=$8A, GameSubstate=$8B) |
| $90–$93 | PlayerStateBase / PlayerState1 / CountdownValue / CountdownDivider | Player state |
| $9F | ObjectStateArray9F | Object state array |
| $A0–$A9 | StateVarA0–A9 | State variables |
| $AC–$AF | StateVarAC–AF | State variables |
| $B0 | ToggleStateB0 | Toggle state |
| $B2 | StateVarB2 | State variable |
| $D0–$D8 | ObjectVarD0–D8 | Object variables |
| $DA | ObjectVarDA | Object variable |
| $E9–$EF | ObjectVarE9–EF | Object variables |
| $F0–$F3 | AudioPulse1State–AudioNoiseState | Audio channel states |
| $F4 | AudioPeriodOrEnvelope | Audio period/envelope |
| $F5–$F6 | AudioSequencePtrLo/Hi | Audio sequence pointer |
| $F7 | AudioSequenceCursor | Audio sequence cursor |
| $F8–$F9 | AudioChannelCursor/Index | Audio channel state |
| $FA | AudioSequenceState | Audio sequence state |
| $FB–$FF | AudioRequest0–4 | Audio request flags |

---

## 11. Audio System

**AudioDriverCode** ($F7C1) — NMI-called audio driver:
- Strobes JOY2 ($4017 = $FF) to select noise mode
- Calls four channel processors: $F898, $FA2E, $FACF, $FB22 (pulse 1, pulse 2, triangle, noise)
- Clears audio request flags $FB–$FF
- Noise channel: reads $07FE, applies envelope from AudioNoiseState ($F3), writes to $4011

Audio workspace ($F0–$FF): channel states, sequence pointers/cursors, request flags.

Audio data tables (`AudioDataTables` at $F441 / $FF34): pitch/envelope lookup tables at $FF34–$FF40 and $FF51–$FFF0.

---

## 12. Data Regions

| Label | Address | Description |
|-------|---------|-------------|
| `DeveloperCreditText` | $C000 | "T.SAWANO." encoded credit string |
| `ResourceScriptPointerTable` | $C008 | 16 pointers into upper-PRG script area ($E75D–$EF91, $F117/$F11D) |
| `TitleOrMessageTileString` | $C044 | Encoded title/message tile values |
| `ResourceDescriptorData_C058` | $C058 | Variable-length resource descriptor records |
| `DirectionAndCoordinateTables_C0B4` | $C0B4 | Direction, coordinate, and signed-offset lookup tables |
| `StartupObjectTemplateData_C0E9` | $C0E9 | Startup object/template records |
| `MovementTables` | $C7BD | Movement-related tables |
| `ObjectEngineCodeAndTables` | $CCC8 | Object engine code + embedded tables |
| `AudioDataTables` | $F441 | Audio pitch/envelope tables |
| VectorTable | $FFFA–$FFFF | NMI=$C1F1, RESET=$C196, IRQ=$C196 |

---

## 13. Summary of Execution Flow

```
Power On / Reset
    │
    ▼
ResetEntry ($C196) ───────────────────────────────────┐
    │ CLD, disable PPU/NMI, SEI, stack=$FF            │
    │ wait 2× VBlank (PPU warm-up)                    │
    │ clear RAM (zero page + one page)                │
    │ JSR RunGameTaskRoutine_CBA6 (init task)         │
    │ FrameShiftRegister0=$55, PPUCTRL=$12 (NMI on)   │
    │ PPUMASK=$06 (bg+sprites on), APU=$0F            │
    │ JSR RunGameTaskRoutine_C3E4                     │
    │ enable NMI bit in PPUCTRL                       │
    ▼                                                 │
InterruptPathDispatch_C1EB ($C1EB) ───────────────────┤
    │                                                 │
    ├─ JSR EnginePath_F58D   (frame shift regs)       │
    └─ JMP InterruptPathDispatch_C1EB   ◄─────────────┘   (spin forever)
                                                        │
NMI ($C1F1) [once per frame]                          │
    │                                                 │
    ├─ save A, WorkPtr0Lo ($00)                       │
    ├─ PPUCTRL = shadow & #$7F  (NMI off during H)    │
    ├─ PPUMASK = shadow & #$E7 (rendering off)        │
    ├─ JSR UpdateGameStateRoutine_C996  ($C996)       │
    ├─ OAM DMA ($0200–$02FF → $4014)                  │
    ├─ JSR ResourceAndLevelData ($F20B)  [PPU cmds]   │
    ├─ JSR ObjectPath_E113   ($E113)                  │
    ├─ JSR ObjectPath_DDC1   ($DDC1)                  │
    ├─ PPUCTRL = shadow; PPUMASK = shadow | #$18      │
    │         (rendering back on)                     │
    ├─ JSR AudioDriverCode ($F7C1)  [4 channels]      │
    ├─ JSR EnginePath_F5AE   ($F5AE)  [controller I/O]│
    ├─ JSR ObjectPath_DDC1   ($DDC1)  [again]         │
    ├─ JSR RunGameTaskRoutine_C368 ($C368) [game task]│
    │                                                 │
    ├─ read PPUSTATUS                                 │
    ├─ PPUCTRL = shadow | #$80  (re-enable NMI)       │
    ├─ restore A, WorkPtr0Lo ($00)                    │
    └─ RTI                                            │

Game Task Dispatcher ($C368) [from NMI]
    ├─ branches on $92,$B0,$8A,$8D,$8C,$8F,...        │
    ├─ CoreGameCode ($C245) — main object processor   │
    ├─ many RunGameTaskRoutine_* / ProcessResource*   │
    └─ returns to NMI (which continues to RTI)
```

---

## 14. Notes

- **Build verification:** `make` in `copilot/` produces `reconstructed_prg.bin` that is **byte-identical** to `prg.bin` and to the PRG bank of `rom.nes`.
- Vectors confirm NMI at $C1F1 and both RESET/IRQ at $C196 (IRQ reuses the reset handler).
- The main loop (`InterruptPathDispatch_C1EB`) is a tight infinite loop calling only `EnginePath_F58D`; all substantive per-frame work is done in the NMI handler.
- NMI temporarily disables itself (`AND #$7F` on PPUCTRL) and rendering (`AND #$E7` on PPUMASK) while it updates PPU state and objects, then re-enables both before RTI — a classic NES VBlank update pattern.
- Many routine labels carry address-based names (`ObjectPath_D34E`, `RunGameTaskRoutine_C368`, `ProcessObjectStateRoutine_E6F3`, etc.) reflecting the automated first-pass disassembly; semantic naming is provisional.
- The disassembly includes extensive inline `.byte` data blocks interleaved with code; boundaries are marked as "conservative Pass-1 classifications."
- `locals.inc` provides verified zero-page names; `symbols.inc` provides the NES hardware register set.