disasm/Donkey Kong Jr. (JU)/OVERVIEW.md

# Donkey Kong Jr. (JU) — Game Flow from Power-On

This document describes the execution flow of the disassembled Donkey Kong Jr. (JU) PRG bank (16 KB, mapped at CPU **$C000–$FFFF**), starting from power-on. It is based entirely on `copilot/prg.s` (13,634 lines) in the repository, originally generated by `pass1_trace.py` from the interrupt vectors and refined through Pass 2/3 semantic labeling. The rebuild is verified **byte-identical** to the original `rom.nes` (`make` in `copilot/` produces `reconstructed.nes` matching `rom.nes` exactly).

Listing: project **11** in the top-level `OVERVIEW.md` index. NROM cartridge (mapper 0), iNES flags: 1 × 16 KB PRG, 1 × 8 KB CHR, vertical mirroring (flag 6 = $01).

ROM SHA-256: `7d5f77878af7646296d994da14b25213741f6e0e0bc5deadd32a406d044a5788`

Current label status — **all 1,035 top-level labels are semantically named**; every data region is emitted as explicit `.byte` data with its ROM provenance in comments (no `.incbin` blocks remain), and 688 local `Label_` branch targets are routine-internal.

---

## 1. Reset Vector — CPU $FFFC → $C66E

**`ResetHandler`** ($C66E–$C6B3)

Unlike most projects in this repository (whose reset handlers sit at $C000 or nearby entrypoints such as $C40B), Donkey Kong Jr.'s reset entry is at **$C66E**. On power-on or reset, the 6502 jumps to `$C66E`. The reset routine performs cold-start hardware initialization:

| Step | Code | Purpose |
|------|------|---------|
| 1 | `sei / cld` | Disable interrupts, clear decimal mode |
| 2 | `lda #$10 / sta PPUCTRL` | Disable NMI and PPU rendering immediately |
| 3 | `ldx #$FF / txs` | Initialize stack pointer |
| 4 | Poll `$2002` until bit 7 set | Wait for one VBlank period (PPU warm-up) |
| 5–8 | Indirect clear loop via `$00/$01` pointer | Clear all of RAM `$0000–$07FF` (8 pages, walked downward from $0700) |
| 9 | `jsr InitializePpuOamAndDmc` ($C6B6) | PPU, shadow-OAM, and DMC initialization (see §2) |
| 10 | `lda #$6F / sta TitleCursorY` | Initialize the title-cursor sprite Y position ($6F) |
| 11 | `lda #$18 / sta GameModeTimer` | Set attract-sequence timer (24) |
| 12 | `lda #$01 / sta PlayerLivesOrModeCount, sta PendingGameMode` | Arm the pre-game attract path |
| 13 | `lda #$00 / sta GameMode` | Set current game mode to 0 |
| 14 | Toggle `$2000` bit 7 via `PPUControlShadow` | **Enable NMI** — actual execution begins |
| 15 | `Label_C6B0: jsr AdvanceRandomLfsr / jmp` | Idle loop; the reset path never returns |

**Architectural note:** After reset, the CPU idles forever (`jmp Label_C6B0`); the loop body's only activity is `jsr AdvanceRandomLfsr` to churn the 8-byte PRNG. *All* game logic — attract screen, titles, gameplay, sound — runs entirely inside the **NMI handler**, which is the opposite of most NES titles in this collection (where the NMI flag merely paces a foreground main loop).

---

## 2. Initialization — `InitializePpuOamAndDmc` ($C6B6–$C6E5)

Called from `ResetHandler`:

1. **PPU control**: `PPUCTRL = $10`, saved to `PPUControlShadow` ($10)
2. **PPU mask**: `PPUMASK = $06` (background + sprite rendering), shadow at $11
3. **Scroll**: both scroll registers cleared, shadows at $12/$13
4. **Shadow OAM fill**: fills `$0200–$02FF` with `$FF` (all sprites hidden)
5. `jsr ClearGameplayNametable` ($CA16) — clears the background nametable
6. `APUDMALOAD = $00` (`$4011`, DMC volume/level reset)

---

## 3. Interrupt Vectors — CPU $FFFA–$FFFF

Located at the end of the bank (PRG offset $3FFA):

| Vector | Address | Handler |
|--------|---------|---------|
| NMI | $C6E6 | `NmiHandler` |
| RESET | $C66E | `ResetHandler` |
| IRQ | $FFF0 | `IrqHandler` (single `asl a` byte; see the deferred-task note in §6.1) |

The IRQ's apparent "oddity" is now explained: `DeferredTaskHandlerTable` deliberately addresses its entry 0 at mirrored CPU **$BFFE**, which is the IRQ-vector word at PRG $3FFE. The table leverages the address mirror so that a zero task type falls through to the unused `asl a` byte at $FFF0 — a register-saving trick rather than a real handler.

---

## 4. NMI / Frame Heartbeat — `NmiHandler` ($C6E6–$C76D)

The NMI is the *entire* per-frame scheduler. It:

1. **Preserves state**: pushes A, X, Y, **plus zero page $00–$07** (an 11-byte save; other projects only save the registers)
2. **Suspends NMI**: clears bit 7 of `PPUControlShadow` and writes `$2000` — prevents re-entrancy while the frame logic runs
3. **OAM DMA**: `jsr PerformOamDma` ($EEB0) — sprite DMA from shadow OAM $0200
4. **VRAM queue flush**: `jsr FlushQueuedVramCommands` ($EE9C) — drains the $0300 command queue during rendering
5. `jsr WriteInvertedRenderingMask` ($CA7A) — redraws PPUMASK state
6. `jsr UpdateAudioFrame` ($F91F) — per-frame audio channel update
7. **Controllers**: `jsr ReadControllers` ($F219) — serial pad read for both ports
8. **Frame logic dispatch** (see §5) based on `PendingGameMode` ($47), `GameMode` ($46), and `GameplaySubmode` ($4D)
9. `jsr ProcessQueuedTask` ($EE3A) — pops one pending task from the $0300 queue (see §6.1)
10. **Resumes NMI**: re-enables bit 7 of `PPUControlShadow` / `$2000` — allows the next frame
11. **Restores $00–$07, A, X, Y, `rti`**

---

## 5. Frame State Machine (inside the NMI)

The frame-mode dispatch at $C71B–$C748:

```
lda PendingGameMode ($47)
    │
    ├─ non-zero ── pending attract boot ──┬─ PlayerLivesOrModeCount == 0 → UpdateGameModeTransition ($C897)
    │                                     │                                (sound timers only)
    │                                     └─ PlayerLivesOrModeCount != 0 → UpdateTitleScreenAndStartSelection ($C773)
    │                                                                     + TickSoundTimers ($F1AF)
    │
    └─ zero ── lda GameMode ($46)
              │
              ├─ zero → UpdateAttractModeState ($C932)  (attract / inter-stage sequencer)
              │
              └─ non-zero ── lda GameplaySubmode ($4D)
                             ├─ zero → UpdateGameplayFrame ($CD6E)   (normal gameplay frame chain)
                             └─ non-zero → UpdateStageTransition ($CFC1)  (stage-intro / submode-6 path)
```

After the mode dispatch, `ProcessQueuedTask` ($EE3A) executes one queued gameplay task, then $2000 bit 7 is restored.

---

## 6. Subsystems

### 6.1 Deferred Task / VRAM Queue Systems ($0331, $0300)

Two cooperating RAM queues at $0300 fill during VBlank-adjacent time and are consumed during rendering:

- **Deferred gameplay tasks**: `EnqueueTask` ($EE7F) appends a tagged task byte (address in $0301, data in $0302). `ProcessQueuedTask` ($EE3A) pops one per frame: the task's high nibble selects a handler from `DeferredTaskHandlerTable` ($C000), the low nibble becomes its final data byte, and the dispatcher performs an indirect `jmp ($00):($02)` with a synthetic `$39EE` return address. Queue positions wrap at offset $2E.
- **`DeferredTaskHandlerTable` ($C000)** — five typed handlers:

  | Task type | Handler | Address |
  |-----------|---------|---------|
  | 1 | `InitializeBoundingBox` | $F044 |
  | 2 | `UpdateExistingBoundingBox` | $F040 |
  | 3 | `TestObjectBoundingBoxOverlap` | $F138 |
  | 4 | `QueueSelectedHudFields` | $EF50 |
  | 5 | `FillNametableAndClearAttributes` | $EEBB |

  Entry 0 (task type 0) is deliberately routed through the mirror at $BFFE to the IRQ-vector word — see §3.
- **VRAM command streams**: `QueueSingleVramByte` ($F1C5), `QueueRectangularVramTransfer` ($EFCE), and `QueuePlayerSelectVramStream` ($CA33) build queued VRAM writes; `FlushQueuedVramCommands` ($EE9C) walks the $0331 handoff pointer into `ProcessVramCommandStreamAndRestoreScroll` ($EF3C), the generic $2006/$2007 writer used by every screen-draw path.
- **Sprite management**: `PerformOamDma` ($EEB0) performs the shadow-OAM ($0200–$02FF) → $2003/$4014 DMA each frame; `HideInactiveObjectSprites` ($EC17)/`HideObjectSpriteGroup` ($CA08) park inactive slots.

### 6.2 Attract / Inter-Stage Sequencer ($C932–$C9FF)

`UpdateAttractModeState` ($C932) runs whenever `GameMode == 0`. It is a **countdown-driven scene sequencer** using `GameStateTimer` ($39) as a descending timer with fixed thresholds:

| GameStateTimer value | Action |
|------------|--------|
| $84 | scoreboard/interlude phase (decrements per frame) |
| $6E–$6F | stage transition setup (`AdvanceAttractModeSequence`, $C969) |
| $74 | full PPU re-prep (`HideObjectSpriteGroup` $CA08 + `ClearGameplayNametable` $CA16 + `QueuePlayerSelectVramStream` $CA33) |
| $68 | `jsr InitializeGameplayRam` ($CA82), **`GameMode = $01`** — gameplay begins |

At $C988 it disables rendering and uploads per-stage VRAM via `StageBackgroundVramStreamPointerTable` ($C3BD, one 2-byte stream pointer per stage index) plus the fixed stream at $F8B6, guarded by `GameModeTimer` ($48) — this draws the "How High Can You Get??"-style inter-stage screens before the stage demo starts, then queues rendering via `QueueCollisionAndVramTasks` ($ECA4) and `QueueSingleVramByte` ($F1C5).

### 6.3 Title / Game Start ($C773–$C896)

`UpdateTitleScreenAndStartSelection` ($C773) runs while `PendingGameMode != 0` and `PlayerLivesOrModeCount != 0`:

1. **APU gate**: audio enable `$06A2`-checked; a start-up delay in $05B4 raises `APUCTRL = $0F` (all channels on)
2. First pass (`TitleScreenInitialized` ($52) == 0): disables rendering, uploads the title background via the `TitleScreenVramCommandStream` at $F266, then builds the cursor sprite ($0200/$0201/$0203 with Y from `TitleCursorY` ($ED) = $6F)
3. **SELECT** ($20 mask): advances `TitleCursorY` by $10 (wraps $AF → $6F), sets `TitleInputRepeatTimer` ($7D) = $0A, latches `StartButtonLatch` ($6A)
4. **START** ($10 mask): latches `PreviousStartButtonState` ($EC), clears the bounding-box work area ($24–$2E), derives `SelectedPlayerMode` ($EF) from `TitleCursorY` (`lsr` ×4 minus 6) and a matching `GameModeTimer` ($1C or $18), then `jsr CollisionUpdateStep_EDFF` ($EDFF)
5. **Transition to gameplay**: reseeds the PRNG ($18 = $0F, $19 = $13), clears `PendingGameMode`, `GameMode`, and the $0580–$0587 record arrays, sets `StageOrScreenIndex` ($4A) = $01, derives `DifficultyOrRoundIndex` ($4B) from `SelectedPlayerMode` parity, sets `PlayerLivesOrModeCount` ($4C) per `TwoPlayerModeFlag` ($4E); final call `HideObjectSpriteGroup` and clears the $05B4 startup delay

`UpdateGameModeTransition` ($C897) is the alternate boot chain (`PlayerLivesOrModeCount == 0`): it ticks sound timers and compares `GameStateTimer` against $75 in the same phased style as the attract sequencer.

### 6.4 Gameplay Submodes ($CD6E–$D0FF)

With `GameMode != 0`, the NMI dispatches on `GameplaySubmode` ($4D):

- **Submode 0 — `UpdateGameplayFrame` ($CD6E)**: the full gameplay frame chain. Player state machine on `PlayerState` ($6B, states $03/$04/$05 special-cased):
  - `PlayerUpdateStep_EE10` ($EE10), `DecodePlayerDirectionalInput` ($CE6C) — input decode and object ambient updates
  - `UpdatePlayerAuxiliarySprite` ($CEA2), `InitializePlayerStateTransition` ($D251), `DispatchPlayerState` ($D412), `ProcessStageCollisions` ($D2FC), `UpdateStageEntities` ($CEF4), `DetectPlayerLoss` ($CED4) — player state, movement, and collision phase
  - `HideInactiveObjectSprites` ($EC17), `UpdateGameplaySubmode` ($CF9D), `RequestLowAltitudeSound` ($CEC9) — object OAM build and sound requests
  - death/loss handling: `UpdatePlayerDeathSequence` ($D1AE), `UpdateBonusCountdown` ($CF37)
  - `TickSoundTimers` ($F1AF)
  - Player-state bookkeeping: `PlayerStateReferenceY` ($76) copied from shadow OAM $0210, `PlayerStatePhase` ($78), `PlayerStateTransitionActive` ($79), `PlayerStateCounter` ($7E), plus the vertical-physics groups `PlayerVerticalSpeedInteger` ($7A)/`PlayerFallThreshold` ($7B)/`PlayerVerticalAcceleration*` ($7C/$82/$83)/`PlayerGravity*` ($86/$87)
  - SELECT exits via the `PendingGameMode = 1` path at $CDE4 (return to title)
  - `PauseActive` ($EB)/`PauseDebounceTimer` ($EE) gate the frame body
- **Submode != 0 — `UpdateStageTransition` ($CFC1)**: stage-intro / submode-6 path. In its early phase it gates on `PlayerState` and `PlayerStatePhase`; once the reference sprite at $0210 passes Y threshold $28, it issues a per-stage sound request into `SecondarySoundRequestFlags` ($FD) from `StageOrScreenIndex` ($02 for stage 1, $04 for stage 2, otherwise $08 — stage music), uploads a $50-byte VRAM stream (PPU address $1866 with a $00 fill value — pattern-table erase for the intro) via `QueueRectangularVramTransfer`, and sets `PlayerInputDirection` ($54) = $03. Submode 6 branches to `BeginStageClearSequence` ($D05F); entry also flows through `InitializePlayerBoundingBox` ($D04E) and `BuildPlayerCollisionBounds` ($D2BD).

### 6.5 Controllers ($F219–$F265)

Standard NES serial read through $4016 with the classic DPCM-corruption filter:

- `ReadControllers`: strobe on/off, then `ReadControllerPort` for X = 0 and 2
- `ReadControllerPort`: 8-bit shift loop in Y, then a two-sample consistency merge — a polarity-safe trick that keeps the record stable against mid-frame pad reads
- Results in `ControllerRawState` ($14) / `ControllerFilteredState` ($15) and `$16/$17` for port 2
- The $0F-mask ladder implements "button pressed this frame" persistence for directional input vs start/select

### 6.6 Sound Engine ($F1AF–$FE55)

- `UpdateAudioFrame` ($F91F): called from the NMI as the main audio service — it manages the APU channel frame state and audio effects
- `TickSoundTimers` ($F1AF): per-frame channel timer service; `SoundTimerDivider` ($34) drives the frame-based `SoundTimerArray` ($35+)
- Effect state and data: `Pulse1Effect*` ($F0–$F2), `AudioEffectTimer`/`AudioPitchAccumulator` ($F3/$F4), `Triangle*` ($F5/$F6), music sequencer state `MusicDataPointer*` ($F7/$F8)/`MusicNoisePosition` ($F9)/`MusicPulsePosition` ($FA)/`AudioLfoPhase` ($FB), and request flags `SoundRequestFlags` ($FC)/`SecondarySoundRequestFlags` ($FD)/`ObjectSoundRequestFlags` ($FE)
- Sound-effect data at the end of the bank: `SoundEffectDataPointer*` ($FE52/$FE53), `SoundEffectNoiseOffset` ($FE54), `SoundEffectSequenceData` at $FE55
- The title/APU chain programs `APUCTRL = $0F` (all channels on) at start

### 6.7 Pseudo-Random Generator ($F1F8–$F218)

An **8-byte LFSR** at $18–$1F:

- Taps: bit 1 of `RandomLfsr0` XOR bit 1 of `RandomLfsr1`
- Shifted bit through the full `ror` chain over all eight bytes
- Stepped continuously in the reset idle loop (`Label_C6B0`)
- Seeded to `$0F $13 $00…` at game start

---

## 7. Memory Map (Key Zero Page / RAM)

| Address | Name | Use |
|---------|------|-----|
| $00–$0F | `Zp00`–`Zp0F` | Shared scratch / indirect pointers (routine-local by design) |
| $10 | `PPUControlShadow` | $2000 shadow |
| $11 | `PPUMaskShadow` | $2001 shadow |
| $12–$13 | `PPUScrollXShadow` / `PPUScrollYShadow` | $2005 shadows |
| $14/$16 | `ControllerRawState` / `Controller2RawState` | Raw serial pad bytes, ports 1/2 |
| $15/$17 | `ControllerFilteredState` / `Controller2FilteredState` | Filtered pad bytes, ports 1/2 |
| $18–$1F | `RandomLfsr0`–`RandomLfsr7` | 8-byte pseudo-random shift register |
| $20–$23 | `CollisionBounds0`–`CollisionBounds3` | Active collision bounds |
| $24–$27 | `BoundingBoxFlags` / `BoundingBoxCoord1–3` | Pending bounding box (queued tasks) |
| $2C/$2E | `PlayerVerticalFraction` / `PlayerVerticalPosition` | Player Y integration |
| $34–$38 | `SoundTimerDivider` / `SoundTimerArray` / `SharedActionTimer` / `PlayerSpriteVisibilityTimer` | Sound timers, shared timers |
| $39 | `GameStateTimer` | Attract/title countdown |
| $3A | `ObjectActiveArray` | Object active/hidden flags for sprite hiding |
| $3C | `ActionCooldown` | Object cooldown |
| $3E–$45 | `CollisionLeft/Top/Right/Bottom`, `CollisionMatchX/Y/Right/Bottom` | Collision results |
| $46 | `GameMode` | Current mode (0 = attract, 1 = gameplay) |
| $47 | `PendingGameMode` | Boot pending flag |
| $48 | `GameModeTimer` | Mode timer (attract/title countdowns) |
| $49 | `CurrentPlayerIndex` | Player selector |
| $4A | `StageOrScreenIndex` | Current stage (1-based) |
| $4B | `DifficultyOrRoundIndex` | Difficulty/round selector |
| $4C | `PlayerLivesOrModeCount` | Lives / mode count |
| $4D | `GameplaySubmode` | Gameplay submode selector |
| $4E | `TwoPlayerModeFlag` | 2-player selection |
| $4F–$51 | `DemoInputIndex` / `DemoInputTimer` / `DemoInputCode` | Attract-demo scripted input |
| $52–$53 | `TitleScreenInitialized` / `LevelObjectProgress` | Boot stage, level-object progress |
| $54–$57 | `PlayerInputDirection` / `PreviousInputDirection` / `PlayerPositionFraction` / `ObjectPositionFraction` | Input + fixed-point positions |
| $64–$6A | `BonusTickDivider` / `BonusCounter` / `DeathAnimation*` ($66/$67) / `PlayerCollisionResult` ($68) / `CollidingObjectOamOffset` ($69) / `StartButtonLatch` ($6A) | Bonus ticks, death animation, collision results |
| $6B–$70 | `PlayerState`, `PreviousPlayerState`, `PlayerFacing`, `PreviousPlayerFacing`, `PlayerClimbPhase`, `PlayerClimbDirection` | Player state machine + climbing |
| $71–$77 | `PlayerMovementSubstate`, `MovementCollisionCode`, `PlayerCollisionAnchor*` ($73/$74), `PlayerClimbOffset`, `PlayerStateReferenceY` ($76), `PlayerLandingTile` | Movement, collision anchors, landing |
| $78–$7E | `PlayerStatePhase` ($78), `PlayerStateTransitionActive` ($79), `PlayerVerticalSpeedInteger` ($7A), `PlayerFallThreshold` ($7B), `PlayerVerticalAcceleration` ($7C), `TitleInputRepeatTimer` ($7D), `PlayerStateCounter` ($7E) | State phase + vertical physics |
| $7F–$87 | `PlayerVerticalVelocityFraction` ($7F), `PlayerVerticalAcceleration*` ($82/$83), `PlayerGravity*` ($86/$87) | Vertical velocity/gravity fixed-point |
| $8C–$9F | `CarriedObjectActive` ($8C), `CollectibleSpriteTileArray` ($8D), `StageObjectDataPointer*` ($91–$93), `CollectedObject*` ($94–$9F) | Stage objects and collectibles |
| $A0–$BB | `StagePrimaryObjectCount`, `ObjectMotionStep` ($A1), `StageSecondaryObject*`, `EnemyStateArray` ($A3), `EnemyAlternateStateArray` ($A6), `EnemyDirectionArray` ($B4), `EnemySpawnDelayArray` ($B9), `Platform*` state ($AC–$BE), `StageSecondaryObjectCount` ($B0), `SpawnedEnemyCount` ($B1), `StageObjectMode` ($B2) | Stage-entity pools |
| $C3–$CF | `SpecialObjectIndex` ($C3), `SpecialObjectX` ($C4), `StageObjectAnimationMode` ($CE), `StageObjectOamOffset` ($CF) | Special objects |
| $D0–$E6 | `BonusSpriteActive` ($D0), `VramMetatileBuffer` ($D1), `StageRopeAddress*` ($DA/$DB), `PendingLevelObjectTask` ($E7) | VRAM buffers, ropes, level-object tasks |
| $E7–$EE | `DemoInputActive` ($E8), `GameplayInitializationPending` ($E9), `MovementFrameCounter` ($EA), `PauseActive` ($EB), `PreviousStartButtonState` ($EC), `TitleCursorY` ($ED), `PauseDebounceTimer` ($EE) | Flow/pause/title state |
| $EF | `SelectedPlayerMode` | Player-count selection from the title |
| $F0–$FE | `Pulse1Effect*` ($F0–$F2), `AudioEffectTimer` ($F3), `AudioPitchAccumulator` ($F4), `Triangle*` ($F5/$F6), `MusicDataPointer*` ($F7/$F8), `MusicNoisePosition` ($F9), `MusicPulsePosition` ($FA), `AudioLfoPhase` ($FB), `SoundRequestFlags` ($FC), `SecondarySoundRequestFlags` ($FD), `ObjectSoundRequestFlags` ($FE) | APU effects and music sequencer state |
| $FF | `GameplayEventFlags` | Shared gameplay event/request flags |
| $0100–$01FF | Scratch and object arrays | Object work area |
| $0200–$02FF | Shadow OAM | Cleared to $FF at reset; DMA'd every frame |
| $0300–$03FF | Deferred task / VRAM queue | Command-stream bytes and task dispatch slots ($0300 cursor, $0301 wrap index, $0302 entries×2, $0331 handoff pointer) |
| $0520+ | Stage object RAM | Object/config groups copied in via the `ObjectConfig*` tables |
| $0580–$05B5 | Per-mode record arrays | Attract/stage state records written by the title and attract sequences |
| $06A2, $05B4 | APU gate / startup delay flags | Sound enable gating used at title and gameplay entry |

A handful of bytes still carry deliberately neutral names (`Zp28`–`Zp5C`, `Zp58`–`Zp62`, `Zp80`–`ZpE6` members) where reuse across routines is suspected; the Pass 1 trace recorded 1,757 zero-page accesses across 186 distinct base addresses.

---

## 8. Code/Data Map

Pass-1 trace statistics (recorded during generation): **6,135 decoded instructions**, **12,358 classified code bytes**, **266 reachable routine entry points**, **68 referenced PRG data labels**, **0 overlapping-instruction conflicts**. As of the current Pass 3 source, every data region is emitted as explicit `.byte` data with its ROM provenance documented — no `.incbin` blocks remain.

| Region | Class | Size |
|--------|-------|------|
| $C000–$C66D | data (`DeferredTaskHandlerTable`, `HudDigitDescriptorTable`, `StagePlayerStartYTable`, `ObjectConfig*` tables, `StageBackgroundVramStreamPointerTable` at $C3BD) | 1,646 bytes |
| $C66E–$F137 | code (reset, NMI, mode dispatch, attract, title, gameplay) | 10,954 bytes |
| $F138–$F1AE | data (bounding-box overlap data) | 119 bytes |
| $F1AF–$F265 | code (sound timers, LFSR, controllers) | 183 bytes |
| $F266–$F91E | data (`TitleScreenVramCommandStream` at $F266, screen VRAM streams and stage data — 1,721 bytes) | 1,721 bytes |
| $F91F–$F957 | code (`UpdateAudioFrame`) | 57 bytes |
| $F958–$F959 | data | 2 bytes |
| $F95A–$F9F7 | code | 158 bytes |
| $F9F8–$FA63 | data | 108 bytes |
| $FA64–$FE50 | code (deferred task / VRAM queue engine, $EE39–$FE50) | 1,005 bytes |
| $FE51–$FFEF | data (`SoundEffectDataPointer*` $FE52–$FE53, `SoundEffectNoiseOffset` $FE54, `SoundEffectSequenceData` $FE55…) | 415 bytes |
| $FFF0–$FFFF | IRQ byte (reused by `DeferredTaskHandlerTable` entry 0) + filler + vectors | 16 bytes |

---

## 9. Summary of Execution Flow

```
Power On / Reset
    │
    ▼
ResetHandler ($C66E) ──── sei, clear RAM, init PPU/shadow OAM, arm attract
    │
    ▼
enable $2000 bit 7 (NMI on)
    │
    ▼
Idle loop $C6B0 ────────► AdvanceRandomLfsr, forever   (reset path never returns)
                                                        (all action is in NMI)

NMI ($C6E6) [once per frame]
    ├─ push A/X/Y + $00–$07 save
    ├─ PerformOamDma ($EEB0) + FlushQueuedVramCommands ($EE9C)
    ├─ WriteInvertedRenderingMask ($CA7A) + UpdateAudioFrame ($F91F)
    ├─ ReadControllers ($F219)
    ├─ Mode dispatch ─┬─ PendingGameMode → UpdateTitleScreenAndStartSelection ($C773)
    │                 │                      / UpdateGameModeTransition ($C897)
    │                 ├─ GameMode == 0  → UpdateAttractModeState ($C932)  ─┐
    │                 └─ GameMode != 0  → UpdateGameplayFrame ($CD6E)      │
    │                                        / UpdateStageTransition ($CFC1) │
    ├─ ProcessQueuedTask ($EE3A) ──► DeferredTaskHandlerTable ($C000)      │
    └─ restore CPU/ram state, rti                                          │
                                                                           │
     InitializeGameplayRam ($CA82) at GameStateTimer ($39) = $68 ◄──────────┘
         │
         ▼
     GameMode = 1; NMI dispatches gameplay chains per GameplaySubmode
         (player state machine on $6B, collision bounds, stage entities,
          deferred task queue, DispatchPlayerState/ProcessStageCollisions)
```

---

## 10. Notes on Provisional Areas

- **Status:** Pass 3 — all 1,035 top-level labels (`ResetHandler`, `NmiHandler`, `UpdateGameplayFrame`, `UpdateStageTransition`, `ProcessQueuedTask`, `DeferredTaskHandlerTable`, state tables, etc.) carry semantic names, and all data regions are explicit `.byte` blocks with Pass 3 structure annotations. Remaining `ZpXX` names are deliberate (routine-reused scratch), documented in §7.
- **IRQ / deferred-task quirk:** The table entry 0 at mirrored $BFFE reuses the IRQ-vector word; the $FFF0 `asl a` byte is a table addressing artifact, not a real handler (see §3 and §6.1).
- **Remaining unknowns:** the detailed semantics of the `ObjectConfig*` per-difficulty groups copied into $0520+ RAM, the exact music-sequence encoding inside the $F266/$F95A data streams, and a few still-neutral `ZpXX` scratch bytes.

Build verification:

```bash
cd "/home/tmerritt/Projects/disassembly/Donkey Kong Jr. (JU)/copilot"
make              # builds reconstructed.nes, then cmp against rom.nes → "Byte-identical ROM verified."
```

The rebuild is **byte-identical** to `rom.nes` (ROM SHA-256 at the top of this document). The Pass-1 source verifier (`verify_pass1.py`, which re-decoded every annotated instruction byte and re-hashed the full 24,592-byte ROM against `rom.nes`) passed during generation but was not carried into `copilot/`.