disasm/_wip/Mario Bros (JU)/OVERVIEW.md

Mario Bros (JU) — Game Flow from Power-On

This document describes the execution flow of the disassembled Mario Bros (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 at the PRG level.

---

1. Reset Vector — CPU $FFFC → $C000

Reset ($C000–$C06A)

On power-on or reset, the 6502 jumps to $C000. The reset routine performs cold-start hardware initialization:

Step	Code	Purpose
1–2	cld / sei	Clear decimal mode, disable interrupts
3–6	WaitVblank1 ($C002): poll $2002 via bpl *-3	Wait for first VBlank (PPU warm-up)
7–8	ldx #$00 / txs	Initialize stack pointer to $01FF
9–10	ldx Zp70 / ldy #$06 / sty Zp01 / ldy #$00 / sty Zp00	Zp00/Zp01 = $0600 (RAM clear pointer); X = Zp70 ($70)
11–15	ClearRamPageLoop ($C01D): clear RAM via (Zp00),Y	Clear 6 pages ($0000–$05FF); dec Zp01 loops pages
16	txa / bne Label_C02B	If Zp70 was non-zero, skip full clear
17	ldx #$5F	Alternate init value for warm start
18	stx $0500	Store signature at $0500
19	jsr SubCCA1B / jsr SubCCA2B	Initialize game systems
20	ldy #$00 / sta $2005 ×2	PPUSCROLL = 0,0
21	iny / sty Zp30	Zp30 ($30) = 1
22	lda #$0F / sta $4015	Enable all APU channels
23	lda #$90 / sta $2000 / sta Zp09	PPUCTRL: NMI on, sprite $0000, BG $1000 + shadow in Zp09
24	lda #$06 / sta Zp0A	Zp0A ($0A) = $06

Warm-start signature: Byte at $0500 survives RAM clear via Zp70 ($70). On soft reset, if non-zero, the game clears only 6 pages instead of 7 and uses X=$5F.

---

2. Post-Reset Initialization — SubCC04F ($C04F) onward

SubCC04F ($C04F):
    lda #$00 / sta Zp20 ($20)
    lda Zp30 ($30)
    beq Label_C05D          ; if 0: jsr SubCF8A7
    lda Zp50 ($50)
    cmp #$01 / bne Label_C060  ; if 1: jsr SubCF8A7
Label_C060:
    jsr SubCCD88            ; title/init
    jsr SubCC4B8            ; gameplay init
    lda #$01 / sta Zp22 ($22)  ; NMI phase flag = 1 (gameplay)

Then falls through to main loop entry.

---

3. Interrupt Vectors — CPU $FFFA–$FFFF

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

Vector	Address	Handler
NMI	$C07D	NmiHandler
RESET	$C000	Reset
IRQ	$C000	Reset (reused — unused placeholder)

---

4. NMI / Frame Heartbeat — NmiHandler ($C07D)

The NMI fires once per frame and implements a two-phase structure controlled by Zp22 ($22):

NmiHandler ($C07D):
    pha / txa / pha / tya / pha           ; preserve A,X,Y
    lda #$00 / sta $2003 (OAMADDR)
    lda #$02 / sta $4014 (OAMDMA)         ; sprite DMA from $0200
    lda Zp22 ($22)
    beq Label_C0AC                        ; phase 0: minimal
    jsr SubCCB58                          ; gameplay update 1
    jsr SubCEE6A                          ; gameplay update 2
    jsr SubCCCFF                          ; gameplay update 3
    jsr SubCCA66                          ; gameplay update 4
    jsr SubCCE09                          ; gameplay update 5
    jsr SubCCCC5                          ; gameplay update 6
    jsr SubCCAF7                          ; gameplay update 7
    ldy #$01 / sty Zp20 ($20)             ; main loop flag = 1
    dey / sty Zp42 ($42)                  ; Zp42 = 0
Label_C0AC:
    lda #$01 / sta Zp23 ($23)             ; NMI done flag
    pla / tay / pla / tax / pla / rti     ; restore, return

Phase 0 (Zp22=0): Title/attract — only OAM DMA, no game logic. Phase 1 (Zp22=1): Gameplay — 7 gameplay update calls, sets main loop flag Zp20=1.

---

5. NMI Phase Dispatcher — NmiPhaseDispatch ($C0B6)

Called from main loop to synchronize with NMI:

NmiPhaseDispatch ($C0B6):
    lda ZpB0 ($B0)
    beq Label_C0BF                        ; if 0: jmp NmiPhaseHandlerA
    lda $0320 / bne Label_C0C2            ; check $0320
Label_C0BF:
    jmp NmiPhaseHandlerA                  ; $C149
Label_C0C2:
    lda #$20 / sta Zp14 ($14)
    lda #$03 / sta Zp15 ($15)
    lda #$01 / sta Zp11 ($11)
    ldy #$0B / ldx #$08 / jsr SubCC44A
    sta $05F7 / ora #$00 / beq NmiPhaseHandlerA
    lda ZpC6 / ora $0336 / beq Label_C0F3
    ...

ZpB0 ($B0) = NMI phase (0=title, non-zero=gameplay). $0320 = Additional state check.

---

6. Main Game Loop

The main loop runs in the main thread, synchronized with NMI via Zp20/Zp22/Zp23:

Main Loop (entry via SubCC06A / SubCC06D area):
    ; Wait for NMI to set Zp20=1 (frame complete)
    ; Process game logic
    ; Clear Zp22 (NMI phase) for next frame
    ; Loop

Key synchronization points:

• Zp20 ($20): Set to 1 by NMI phase 1; main loop waits for this
• Zp22 ($22): NMI phase flag (set to 1 by reset init, cleared by main loop)
• Zp23 ($23): NMI completion flag

---

7. Key Subsystems

7.1 Gameplay Update Chain (NMI Phase 1)

Seven sequential calls from NMI:

1. SubCCB58 ($CB58) — Player/enemy physics
2. SubCEE6A ($EE6A) — Collision detection
3. SubCCCFF ($CCFF) — Platform/pipe logic
4. SubCCA66 ($CA66) — Sprite animation
5. SubCCE09 ($CE09) — Bonus/coin logic
6. SubCCCC5 ($CCC5) — Score/HUD update
7. SubCCAF7 ($CAF7) — Audio trigger

7.2 Audio Engine — $F800+ region

• SubCF8A7 ($F8A7): Audio init (called from reset)
• SubCCD88 ($CD88): Title music
• SubCC4B8 ($C4B8): Gameplay music
• APU registers at $4000–$4013, frame counter at $4017

7.3 Stack-Based Dispatch — $CDB1 (jmp ($0014))

Indirect jump through ZP pointer at $0014. The target address is pushed on stack by callers — cannot be followed statically. This is the main dispatch mechanism for 27.8% of unreached code.

7.4 JSR Thunk Table — $C5A3

20-entry table of jsr/rts pairs. Seeding this recovered major code blocks.

7.5 Controller Input

Read via $4016 strobe/shift in NMI or main loop. Button state stored in ZP ($10–$15 area).

---

8. Memory Map (Key Zero Page / RAM)

Address	Name	Use
$00–$01	Zp00/Zp01	16-bit pointer (RAM clear)
$09	Zp09	PPUCTRL shadow ($90)
$0A	Zp0A	Init constant ($06)
$10	Zp10	PPUCTRL working copy
$11	Zp11	State flag
$14–$15	Zp14/Zp15	NMI dispatch parameters
$20	Zp20	Main loop sync flag (set by NMI)
$22	Zp22	NMI phase (0=title, 1=gameplay)
$23	Zp23	NMI done flag
$30	Zp30	Reset signature check result
$42	Zp42	Cleared by NMI phase 1
$50	Zp50	Game mode (0=title, 1=gameplay)
$70	Zp70	Warm-start signature ($0500)
$B0	ZpB0	NMI phase dispatch selector
$B1	ZpB1	Heavily used (88 refs) — gameplay state
$B2–$BF	ZpB2–ZpBF	Object positions, velocities, timers
$C0–$CF	ZpC0–ZpCF	Enemy/bonus state arrays
$F0–$FF	ZpF0–ZpFF	Audio engine ZP
$0200	OAM buffer	Sprite DMA source
$0300+	Game state	Platforms, pipes, enemies, bonuses
$0500	Warm-start signature	Must match Zp70 for warm start

---

9. Data Tables

Table	Address	Description
JSR Thunk Table	$C5A3	20 entries of jsr target / rts
Stack Dispatch Targets	(dynamic)	Pushed on stack, jumped via jmp ($0014) at $CDB1
Audio Sequences	$F800+	Music/sound data
Level Layout	$0300+	Platform positions, pipe connections

---

10. Summary of Execution Flow

Power On / Reset
    │
    ▼
Reset ($C000) ────► cld/sei, wait VBlank, stack=$FF
    │
    ├─ Check Zp70 ($70) warm-start signature at $0500
    │     ├─ Zero: Clear 7 pages ($0000–$06FF), X=$00
    │     └─ Non-zero: Clear 6 pages ($0000–$05FF), X=$5F
    │
    ├─ stx $0500 (signature)
    ├─ jsr SubCCA1B, SubCCA2B (system init)
    ├─ PPUSCROLL = 0,0
    ├─ Zp30 = 1
    ├─ APU enable ($4015=$0F)
    ├─ PPUCTRL = $90 (NMI on) → Zp09
    ├─ Zp0A = $06
    │
    ▼
SubCC04F ($C04F) ──► Zp20=0
    │
    ├─ Zp30=0 or Zp50=1 → jsr SubCF8A7 (audio init)
    │
    └─ jsr SubCCD88, SubCC4B8 (title/gameplay init)
       lda #$01 / sta Zp22 (NMI phase = gameplay)
       │
       ▼ (fall through to main loop)

Main Loop ────────────────────────────────────────────────────┐
    │                                                         │
    ├─ Wait for Zp20=1 (set by NMI phase 1)                  │
    ├─ Process frame logic                                    │
    ├─ Call NmiPhaseDispatch ($C0B6)                          │
    │     ZpB0=0 → NmiPhaseHandlerA ($C149)                  │
    │     ZpB0≠0 → check $0320, setup Zp14/15/11, jsr SubCC44A │
    ├─ Clear Zp22 (NMI phase) for next frame                 │
    └─ Loop                                                   │

NMI ($C07D) [once per frame]
    ├─ Preserve A,X,Y
    ├─ OAM DMA ($4014 from $0200)
    ├─ lda Zp22
    │     ├─ =0 (Title): Label_C0AC → set Zp23=1, rti
    │     └─ =1 (Gameplay):
    │          jsr SubCCB58 (physics)
    │          jsr SubCEE6A (collision)
    │          jsr SubCCCFF (platforms)
    │          jsr SubCCA66 (sprites)
    │          jsr SubCCE09 (bonus)
    │          jsr SubCCCC5 (HUD)
    │          jsr SubCCAF7 (audio trigger)
    │          ldy #$01 / sty Zp20 (signal main loop)
    │          dey / sty Zp42 (=0)
    ├─ lda #$01 / sta Zp23 (NMI done)
    └─ Restore A,X,Y, rti

---

11. Naming and Residue

Pass 1 complete — 5,735 instructions / 11,829 code bytes (72.2%), byte accounting exact. 937 labels, 937 routine headers. Reached via:

• Vectors + direct jsr/jmp/branch, official opcodes: 1,185 instr (14.6%)
• --undocumented (105 extra NMOS opcodes): 1,210 instr (14.9%)
• --auto-seed (61 table-referenced entries): 4,187 instr (51.1%)
• --extra-seed 0xC0B6,0xC5A3: 5,735 instr (72.2%)

Pass 2 substantial — 262 call entry points named (verified 2026-10-19):

• 39 semantic names: Audio routines in $F8xx-$F9xx, gameplay helpers (CheckZpB3Return, CheckRangeReturn012, ToggleZpFC_Bit3)
• 223 SubC<addr> address-based names for remaining jsr/jmp targets
• 667 Label_Cxxxx internal branch targets remain — local control-flow targets within routines
• Zero raw $XXXX call operands remain (all 478 jsr/jmp sites resolved to labels)

Pass 3 outstanding — Data regions in 4,555 unreached bytes need naming; 151 neutral ZpXX aliases in locals.inc.

Indirect dispatch (not followed statically): jmp ($0014) at $CDB1 — table pointer arrives via pla, only knowable in caller's frame.

Tracer fixes required (in _tools/nesdis.py):

• Control-flow targets win over fall-through (fixed bne at $C4BA targeting $C528 vs fall-through NOP #$A5 at $C527)
• Branch targets inside surviving instruction must be pruned (otherwise Label_C528 undefined)

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).