tmerritt
9aef410424
Adds remaining NROM as _wip Update gitignore to not keep object files Adds AGENTS.md as this is an AI helped project
325 lines
24 KiB
Markdown
325 lines
24 KiB
Markdown
# 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, horizontal 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/`.
|