disasm/NROM/Excitebike (JU)/README.md

Excitebike (JU) — Game Flow from Power-On

This document describes the execution flow of the disassembled Excitebike (JU) PRG bank (16 KB, mapped at CPU $C000–$FFFF), starting from power-on. It is based entirely on prg.s in the repository (13,992 lines after the 2026-10-20 audit-trail repair; pre-repair counts in older copies differ). The rebuild is verified byte-identical to the original whole ROM (rom.nes).

---

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	Vertical
PRG bank start	CPU $C000
Source file	prg.s (13,992 lines)
Output	reconstructed.nes (whole ROM: 16-byte header + 16,384-byte PRG + 8,192-byte CHR)

Interrupt vectors (CPU $FFFA–$FFFF)

Vector	Address	Handler
NMI	$C23B	NMI
RESET	$C184	Reset
IRQ / BRK	$FFF0	($FFF0 — points into audio data region, unused)

---

2. Build Status

make in this folder assembles prg.s with ca65, links with ld65, and verifies against rom.nes.

Verification result: BYTE-IDENTICAL — reconstructed.nes matches rom.nes exactly (headers, CHR, and all PRG bytes).

Build fix applied

The original source contained a bpl LookupTableEntry_FAF5 branch at CPU $FAB4 (line 9425 of prg.s), but the symbol LookupTableEntry_FAF5 was undefined. The branch target CPU $FAF5 fell in the middle of what the disassembler classified as lda #$16 (A9 at $FAF4, 16 at $FAF5). The fix:

• Replaced bpl LookupTableEntry_FAF5 with bne *-$1B at CPU $FAB4, producing the exact original bytes d0 e3 (the disassembler had mislabeled bne as bpl).

2026-10-20 fix (final byte-596 mismatch + audit trail + naming)

Three follow-up repairs closed the project out:

1. Byte-596 whole-ROM mismatch: PRG $0243/$024A (CPU $C242/$C249) — the NMI mask block — emitted A5 0A/85 0A (PpuMaskShadow) where the ROM has A5 11/85 11. $11 is a second PPU-mask shadow touched only there (NMI reads it, ORs $1A, writes it back and to $2001); it is now its own symbol, NmiMaskShadow = $11 beside the neutral Zp11 = $11 in locals.inc.
2. Audit-trail repair: 4,401 lines carried doubled ?? comment tails and 6,339 of 6,478 comment groups were systematically shifted against their mnemonics (the trail had been generated against an earlier, shorter source layout). Re-anchored from the ca65 -l listing via _tools/repair_audit_comments.py, which validates every comment against prg.bin and preserves non-audit notes such as ; state $02.
3. Operand naming: all 58 raw jsr/jmp $XXXX operands were substituted with routine labels, plus 15 sub-entry equates in locals.inc (sub-entries are equates rather than mid-routine labels — a mid-routine Name: label re-scopes every @local after that point and breaks forward @refs). The four jmp ($0000) indirect dispatches became jmp (IndirectJumpPtr) ($00/$01 built from RAM by DispatchIndirectHighByte).

apply_symbols.py remains unapplied for this project (inline prg.s definitions conflict with locals.inc); zero-page operands stay numeric as documented Pass 3 residue.

---

3. Reset — CPU $FFFC → $C184

Reset ($C184)

On power-on or reset:

1. sei — disable maskable interrupts.
2. cld — clear decimal mode.
3. lda #$00 / sta PPUCTRL — disable PPU rendering and NMI.
4. ldx #$FF / txs — initialize stack pointer to $FF.
5. Wait for two VBlanks — poll PPUSTATUS bit 7 twice (@vblank1, @vblank2). This is the PPU warm-up delay.
6. Reset magic check — compare ResetMagic1 ($05CE) against $A5 and ResetMagic2 ($05CF) against $5A:
   • If both match → warm start: set Y = $04 (preserve more RAM)
   • If either mismatches → cold start: set Y = $07 (clear more RAM)
7. Clear RAM — clear zero page and one page ($0000–$00FF, or $0000–$06FF depending on warm/cold start) using indirect pointer at $00/$01.
8. Persistent RAM init — if reset magic was valid, jsr InitializePersistentRam ($C278):
   • Copy 31-byte template (PersistentRecordInitialDataC091 at $C091) to both PersistentRecord0 ($0580) and PersistentRecord1 ($05A3)
   • Fill PersistentBuffer ($06E0) with $40, set byte at $07AF to $09
   • Set reset magic bytes to $A5/$5A
   • Zero tail bytes of both persistent records
9. sta APUDMALOAD — disable DMC.
10. lda #$06 / sta PPUMASK / sta $18 — enable background + sprites, set $18.
11. jsr InitializeRuntimePpuState — fill OAM shadow with $F8, process PPU entries, zero scroll/render fields.
12. lda #$90 / jsr SetPpuControl — set PPUCTRL = $90 (NMI enabled, $2000 base).
13. Falls into @main ($C1A4) — the permanent main loop.

---

4. Main Loop — @main ($C1A4)

After reset, Reset never returns. It enters the infinite main loop:

@main ($C1A4):
    jsr ShiftRuntimeState        ; $E8BC — shift runtime bytes $18-$1F right
    lda NmiSyncState             ; $48
    bmi @main                    ; loop if $FF (NMI_SYNC_PENDING)
    beq @main                    ; loop if $00
    ; NmiSyncState == $01 (NMI_SYNC_COMPLETE): proceed
    jsr DisableNmi               ; $C362 — clear NMI bit in PPUCTRL
    lda NmiSyncState
    cmp #NMI_SYNC_COMPLETE       ; $01
    bne @alternate               ; if not complete, receive instead
    jsr TransmitRuntimeDataCode  ; $C6C8 — serial transmit runtime data
    jmp @finish
@alternate:
    jsr ReceiveRuntimeDataCode   ; $C739 — serial receive runtime data
@finish:
    lda #NMI_SYNC_PENDING        ; $FF
    sta NmiSyncState             ; $48 — reset sync flag for next frame
    jsr WaitForVblankEndAndEnableNmi  ; wait for VBlank, set NMI bit
    jmp @main                    ; loop forever

The main loop is NMI-synchronized: it blocks until NmiSyncState ($48) becomes $01 (set by NMI each frame), then performs serial I/O (transmit or receive runtime data), resets the sync flag to $FF, waits for the next VBlank, enables NMI, and repeats.

ShiftRuntimeState ($E8BC)

Shifts runtime state bytes $18–$1F right by one bit. The carry-in is derived from controller bit 1 ($19 bit 2), enabling serial/data shifting tied to controller input.

---

5. NMI / Frame Heartbeat — NMI ($C23B)

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

1. jsr DisableNmi ($C362) — clear bit 7 of PpuControlShadow ($10), write to PPUCTRL ($2000). NMI is disabled during the handler to prevent re-entry.
2. PPU mask: if $45 == 0, PPUMASK = PpuMaskShadow | $1A (enable background + sprites); otherwise skip.
3. OAM DMA: write $00 to OAMADDR ($2003), then $02 to OAMDMA ($4014) — copy $0200–$02FF to sprite RAM.
4. jsr NmiPpuUpdate ($C27E) — process one PPU update command stream (indexed by $45), then reset $0300/$0301/$45 and PPU address to $3F00.
5. Optional rider/lane update: if $47 != 0, jsr UpdateRiderLanePositionStates and jsr NmiRuntimeUpdate.
6. Runtime counters: if $03B1 | $03B2 == 0, increment $3F and jsr UpdateRuntimeCounters.
7. jsr ReadControllers ($E8E5) — read both controller ports ($4016/$4017), update Controller1Held ($14), Controller1Pressed ($15), Controller2Held ($16), Controller2Pressed ($17).
8. jsr UpdateAudio ($F8DE) — update all four APU channels (Pulse 1, Pulse 2, Noise, Sound Effect) plus sound effects and DMA.
9. jsr DispatchNmiState ($C2A9) — dispatch to the current NMI state handler (see below).
10. Read PPUSTATUS ($2002) to reset the address latch.
11. jsr WaitForVblankEndAndEnableNmi — wait for VBlank end, set NMI bit in PPUCTRL.
12. rti — return from interrupt.

NmiPpuUpdate ($C27E)

Processes a single PPU update command:

• Load pointer from PpuUpdatePointerLow/High ($C0F6/$C111 tables) indexed by $45.
• Call ProcessPpuUpdateStream ($D3C1) which reads the command stream and writes bytes to $2007.
• Zero out $0300, $0301, and $45.
• Reset PPU address to $3F00 (four writes to $2006).

---

6. NMI State Machine — DispatchNmiState ($C2A9)

The NMI dispatcher supports two modes based on NmiDispatchMode ($40):

Mode 0 — Direct state dispatch (DispatchNmiState @ $C2A9)

If NmiDispatchMode == 0:

• Load NmiState ($41), double it, use as index into NmiStateHandlerTable ($C000–$C01B).
• Jump indirect through zero-page $00/$01 (high byte left in A, stored to $01 by code at $CB36).

NMI State Handler Table ($C000–$C01B) — 14 entries for states $00–$0D:

State	Handler Address	Purpose
$00	NmiState00	Menu/title — selection handling
$01	$C395	Menu horizontal input
$02	UpdateGameplayRuntime	Main gameplay update
$03	DispatchNmiSequenceStep	Sequence step dispatch
$04	NmiState04_07	Shared state $04/$07 handler
$05	UpdateGameplayRuntime	Main gameplay update
$06	DispatchNmiSequenceStep	Sequence step dispatch
$07	NmiState04_07	Shared state $04/$07 handler
$08	$C3BD	Menu vertical input
$09	UpdateRaceRuntime	Race gameplay update
$0A	UpdateGameplayRuntime	Main gameplay update
$0B	DispatchNmiSequenceStep	Sequence step dispatch
$0C	$C43D	Serial handshake state $0C
$0D	$C41C	Serial handshake state $0D

Mode 1 — Sequence dispatch

If NmiDispatchMode != 0:

• Disable PPU rendering.
• Wait until $30 == 0 (not busy).
• Look up sequence pointer from NmiStateToSequenceIndex + NmiSequencePointerLow/High tables.
• Call the sequence handler at the current NmiSequenceStep ($44).
• If step < 0 (after increment/decrement), go to InitializeRuntimePpuState.

NMI Sequence Pointers ($C03C–$C07F) — 9 sequences:

Index	Address	Handlers
0	$C03C	$C2BD, $C514
1	$C040	SetSerialUpdateSelector06, $C3F3, $C514
2	$C046	SerialUpdateSelectorCluster, ClearRuntimeZeroPage, InitializeCourseRuntime, SetSerialUpdateSelector17, SetSerialUpdateSelector0E, InitializeGameRuntime
3	$C052	SetSerialUpdateSelector06, SetSerialUpdateSelector04, SelectNmiUpdateForState, CallC92CWithZero, CompareAndUpdateRecord
4	$C05C	SetSerialUpdateSelector06, SetSerialUpdateSelector09, Prepare0300Structure, $C514
5	$C064	$C551, ClearRuntimeZeroPage, InitializeCourseRuntime, SetSerialUpdateSelector17, $C562, $C5C2
6	$C070	SetSerialUpdateSelector06, $C575, $C514
7	$C07A	ClearRuntimeZeroPage, RestoreWorkingRecordFields, $C518
8	$C076	$C582, $C518

---

7. Key NMI State Handlers

NmiState00 ($C346)

Title/menu state:

• If $31 == 0: initialize $43, $4A = 0, $03F7 = $0F, NmiState = 2 (gameplay).
• Else: jsr UpdateMenuSelection with count 3; if no input change, set sprite 0 Y from MenuInitialYTable; otherwise handle selection done and advance state.

NmiState01 ($C397)

Menu horizontal input:

• Filter controller buttons, jsr UpdateMenuSelection (count 5).
• If input changed, move horizontal marker; else store MenuSelectionIndex to $43 and advance to next NMI state, entering sequence mode.

NmiState08 ($C3BD)

Menu vertical input:

• jsr UpdateMenuSelection (count 6).
• Based on selection: advance state, jump to sequence entry, or handle choice 5 (reset runtime, preserve selection).

NmiState04_07 ($C465)

Shared handler for states $04/$07:

• If $34 == 0: advance NMI state and enter sequence mode; clamp state to max 7.
• Else: jsr $C92C, check bit 4 of $3F, either return or jmp StateHelperCAFA.

NmiState0C / NmiState0D ($C41C / $C43D)

Serial handshake states:

• State $0C: if sequence step == 0, set sync complete; else if sync pending, copy record tails and continue handshake.
• State $0D: similar handshake with persistent record synchronization.

---

8. Gameplay Runtime

UpdateGameplayRuntime ($C99A)

Called from NMI states $02, $05, $0A:

• jsr $CA08 (update four rider slots).
• If $03B1 | $03B2 != 0: jump to PPU update tail.
• Otherwise: jsr $D918, jsr $DD8D, jsr UpdateAllRiderScriptStateE733, jsr $E927.
• If $52 != 0: jsr StateHelperCA9B.
• If $03F2 != 0: optional updates ($DA9F, $DBC4, $DEBB).
• jsr UpdateGlobalCounters, jsr BuildGlobalDisplayEAC5, jsr CompareRuntimeSlots, jsr CheckSlotState.
• jsr UpdateTriggeredSlots, jsr UpdateFourSlots, jsr UpdateFourSlotPositionsE96C, jsr UpdateDisplayState, jsr UpdateFourSlot8CE836, jsr BuildFourSlotSpritesEA44, jsr ProcessCourseDefinition, jsr UpdateSlotPairState, jsr UpdateGlobalFC, jsr UpdateGlobalDisplay, jsr ProcessRuntimeEntries, jsr PrepareSortedSlots, jsr UpdateRuntimeSlots, jsr UpdateRiderCourseStateE70B, jsr UpdatePpuState, jsr ProcessRiderSlots, jmp ProcessSortedSlots.

UpdateRaceRuntime ($C8D6)

Race-specific update:

• jsr $CA1B, jsr UpdateGlobalRuntimeEB17, jsr UpdateAccumulator, jsr UpdateGlobalPosition, jsr UpdateRiderCourseStateE70B, jsr ProcessCourseDefinition, jsr $F68D, jsr $F755, jsr $C229, then jmp UpdatePpuState.

---

9. Audio System

UpdateAudio ($F8DE) — called from NMI:

1. APUFRAMECNT ($4017) = $C0.
2. jsr UpdatePulse1Channel, jsr UpdatePulse2Channel, jsr UpdateNoiseChannel, jsr UpdateSoundEffect.
3. Zero out $FF, $FE, $FD, $FB.
4. If $07FF != 0: sta APUDMALOAD ($4011), decrement $07FF.

Audio channel configuration uses tables at $FF00+ (period tables) and $FF3E+ (mask tables). Audio sequence/data lives at $FF64–$FFE9.

---

10. Serial I/O System

Excitebike uses the controller port $4016 for serial communication (likely the Famicom 3D System or a similar serial peripheral — peripheral identity unknown):

Transmit path (TransmitRuntimeDataCode at $C6C8):

• Configure a 64-byte block from $0060, transmit it.
• Configure a 20-byte block from $05E0 (working buffer), transmit it.
• Uses pulse-length encoding: long pulse = 1, short pulse = 0, MSB first.
• Preamble: short pulses, then long pulses, then short pulses, then one long pulse.

Receive path (ReceiveRuntimeDataCode at $C739):

• Disable NMI, configure receive blocks, receive data.
• Validate 5-byte header against ReceiveHeaderTableBaseC17F ($C17F: $E8).
• If valid: set state variables ($A0–$A3), set $45 = $1A, wait for NMI update.
• Receive second block (working buffer), validate checksum, return success/failure.

Serial helpers: TransmitByte ($C66E), ReceiveByte ($C6A5), TransmitPulseShort ($C64E), TransmitPulseLong ($C653), ReceiveSerialBit ($C691), SerialWaitPulse ($C639).

---

11. Zero-Page / RAM Symbols

Address	Symbol	Use
$00–$01	TMP00/TMP01	General scratch / indirect pointer
$08–$09	SerialBitCountLo/Hi	Serial bit counter
$0E	SerialBlockPtr	Serial block pointer
$0D	SerialBlockLength	Serial block length
$10	PpuControlShadow	$2000 mirror
$11	NmiMaskShadow	Second $2001 mirror used by NMI (read at $C242, OR $1A, written back at $C249); PpuMaskShadow = $0A remains the main shadow
$12–$1F	—	Runtime state bytes (shifted each frame by ShiftRuntimeState)
$14	Controller1Held	Controller 1 held buttons
$15	Controller1Pressed	Controller 1 newly pressed
$16	Controller2Held	Controller 2 held buttons
$17	Controller2Pressed	Controller 2 newly pressed
$31	—	Menu/timing state
$34	—	Menu selection state
$3F	—	Runtime counter
$40	NmiDispatchMode	NMI dispatch mode (0=direct, 1=sequence)
$41	NmiState	Current NMI state ($00–$0D)
$42	MenuSelectionIndex	Current menu selection
$43–$4A	—	State/temp variables
$44	NmiSequenceStep	Current NMI sequence step
$45	—	PPU update index
$47	—	Optional update flag
$48	NmiSyncState	$FF=PENDING, $01=COMPLETE
$49	InputActionLatch	Menu input latch
$A4	RiderMotionState	Rider motion state ($01=disabled, $02=active, $03=transition, $04=complete)
$0100	—	DMA/APU scratch
$0200	OamBuffer	OAM shadow / sprite DMA source
$0300–$0301	—	PPU update command structure pointer
$03B1–$03B2	—	Timed update flag
$0580	PersistentRecord0	First persistent record (31 bytes + tails)
$05A3	PersistentRecord1	Second persistent record
$05CE–$05CF	ResetMagic1/2	$A5/$5A warm-start signature
$05E0	WorkingBuffer	Working buffer for serial I/O
$06E0	PersistentBuffer	Persistent buffer (256 bytes)
$07FF	—	Audio DMA trigger

---

12. PPU / Rendering

• OAM DMA: Every NMI, DMA from $0200–$02FF via OAMDMA ($4014).
• PPU update streams: Indexed pointer tables at $C0F6 (low) / $C111 (high), 27 entries. Processed by ProcessPpuUpdateStream ($D3C1) during NMI.
• Scroll: PpuControlShadow ($10), PpuMaskShadow ($0A) and NmiMaskShadow ($11) are software mirrors, updated during NMI and written to $2000/$2001. $11 is touched only by the NMI's mask OR ($C242/$C249) and was the source of the byte-596 rebuild mismatch.
• OAM shadow: Filled with $F8 (offscreen) by FillOamShadowWithF8 during runtime PPU init.

---

13. Summary of Execution Flow

Power On / Reset
    │
    ▼
Reset ($C184) ────────────────────────────────────────┐
    │ sei, cld, disable PPU/NMI, stack=$FF            │
    │ wait 2× VBlank (PPU warm-up)                    │
    │ check reset magic ($A5,$5A at $05CE/$05CF)      │
    │   valid → warm start (preserve more RAM)        │
    │   invalid → cold start (clear more RAM)         │
    │ clear RAM ($0000–$00FF or $0000–$06FF)          │
    │ if valid: InitializePersistentRam               │
    │   (copy template to both persistent records)    │
    │ disable DMC, PPUMASK=$06, PPUCTRL=$90 (NMI on)  │
    │ InitializeRuntimePpuState                       │
    │                                                 │
    ▼                                                 │
@main ($C1A4) ────────────────────────────────────────┤
    │                                                 │
    ├─ jsr ShiftRuntimeState   ($E8BC) ──────────────┐
    │   shift $18-$1F right, carry from controller    │
    │                                                 │
    ├─ lda NmiSyncState ($48)                          │
    ├─ bmi @main      (if $FF = PENDING, loop)        │
    ├─ beq @main      (if $00, loop)                  │
    │   (only proceed when NMI set it to $01)         │
    │                                                 │
    ├─ jsr DisableNmi     ($C362)                     │
    ├─ if NmiSyncState == $01:                        │
    │     jsr TransmitRuntimeDataCode ($C6C8)         │
    │   else:                                         │
    │     jsr ReceiveRuntimeDataCode ($C739)          │
    │                                                 │
    ├─ lda #NMI_SYNC_PENDING ($FF)                    │
    │   sta NmiSyncState                              │
    ├─ jsr WaitForVblankEndAndEnableNmi               │
    └─ jmp @main   ◄──────────────────────────────────┘
                                                        │
NMI ($C23B) [once per frame]                            │
    │                                                 │
    ├─ jsr DisableNmi   (PPUCTRL bit7 = 0)            │
    ├─ PPUMASK = PpuMaskShadow \| $1A (if $45==0)     │
    ├─ OAM DMA ($0200-$02FF → $4014)                  │
    ├─ jsr NmiPpuUpdate ($C27E)  [PPU update stream]  │
    ├─ if $47 != 0:                                     │
    │     jsr UpdateRiderLanePositionStates           │
    │     jsr NmiRuntimeUpdate ($D14E)                │
    ├─ if $03B1|$03B2 == 0: inc $3F, jsr UpdateRuntimeCounters │
    ├─ jsr ReadControllers ($E8E5)                    │
    ├─ jsr UpdateAudio ($F8DE)  [4 channels + SFX]    │
    ├─ jsr DispatchNmiState ($C2A9)                   │
    │     ├─ NmiDispatchMode==0: direct state table   │
    │     │   $00=NmiState00 (menu/title)             │
    │     │   $01=$C395 (menu horiz)                  │
    │     │   $02=$C99A (UpdateGameplayRuntime)       │
    │     │   $03=DispatchNmiSequenceStep             │
    │     │   $04/$07=NmiState04_07                   │
    │     │   $05=$C99A (UpdateGameplayRuntime)       │
    │     │   $06=DispatchNmiSequenceStep             │
    │     │   $07=NmiState04_07                       │
    │     │   $08=$C3BD (menu vert)                   │
    │     │   $09=$C8D6 (UpdateRaceRuntime)           │
    │     │   $0A=$C99A (UpdateGameplayRuntime)       │
    │     │   $0B=DispatchNmiSequenceStep             │
    │     │   $0C=$C43D (serial handshake)            │
    │     │   $0D=$C41C (serial handshake)            │
    │     └─ NmiDispatchMode!=0: sequence dispatch    │
    │         (9 sequences at $C03C-$C07F)            │
    │                                                 │
    ├─ read PPUSTATUS                                 │
    ├─ WaitForVblankEndAndEnableNmi                   │
    │   (set NmiSyncState = $01 implicitly via        │
    │    main loop's view of completion)              │
    └─ rti                                            │

Serial I/O (from main loop, once per frame)
    ├─ TransmitRuntimeDataCode ($C6C8)  [when sync complete]
    │     ├─ 64-byte block from $0060                 │
    │     └─ 20-byte block from $05E0 (working buffer)│
    └─ ReceiveRuntimeDataCode ($C739)  [alternate]
          ├─ validate 5-byte header ($C17F)           │
          ├─ receive second block                     │
          └─ checksum verify                          │

Audio (from NMI via UpdateAudio at $F8DE)
    ├─ Pulse 1 channel ($4000-$4003)                 │
    ├─ Pulse 2 channel ($4004-$4007)                 │
    ├─ Noise channel ($400C-$400F)                   │
    ├─ Sound effect                                 │
    └─ DMC load if $07FF != 0                        │

---

14. Notes

• Build verification: make in this folder produces reconstructed.nes, compared whole-ROM against rom.nes.
• Vectors confirm NMI at $C23B, RESET at $C184, IRQ at $FFF0 (points into audio data region — likely a placeholder or unused).
• The main loop (@main at $C1A4) is strictly NMI-synchronized via NmiSyncState ($48): it loops until the NMI sets the state to $01 (COMPLETE), performs serial I/O, resets to $FF (PENDING), waits for VBlank, and repeats.
• Serial I/O uses controller port $4016 for pulse-length encoded data transmission/reception — likely for the Famicom 3D System or a similar serial peripheral.
• The NMI state machine supports both direct state dispatch (14 states via table at $C000) and sequence dispatch (9 sequences via tables at $C03C–$C07F).
• Many routines carry address-based labels (NmiState04_07, UpdateSideScrollingGameplay_C073, etc.) reflecting the automated first-pass disassembly; semantic naming is provisional.
• symbols.inc (embedded at the top of prg.s) provides NES hardware register names and key zero-page symbols.
• One build fix was required: an undefined branch target LookupTableEntry_FAF5 was replaced with a PC-relative bne *-$1B to produce the original d0 e3 bytes.