disasm/NROM/Pac-Man (USA) (Namco)/README.md

Pac-Man (USA) (Namco) — Game Flow from Power-On

This document describes the execution flow of the disassembled Pac-Man (USA) (Namco) 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 (14,332 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	$C10E	NmiHandler
RESET	$C033	Reset
IRQ / BRK	$C17E	IrqHandler (just rti — unused)

Additional ROM data at $FFF6–$FFF9:

• $FFF6/$FFF7 = $ECEC (little-endian), used by DrawMazeNametable as a source pointer ($00/$01)
• $FFF8/$FFF9 = $C10E (little-endian)

---

2. Build Status

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

Verification result: BYTE-IDENTICAL — reconstructed.nes matches rom.nes exactly (header + PRG + CHR).

---

3. Reset — CPU $FFFC → $C033

Reset ($C033)

On power-on or reset:

1. ldx #$00 / stx PPUCTRL — disable PPU rendering/NMI.
2. sei / cld — disable maskable interrupts, clear decimal mode.
3. dex / txs — initialize stack pointer to $FF.
4. nop x3 — three NOP padding bytes.
5. Wait for two VBlanks — @WaitForPpu loop: set PPUMASK=$06, poll PPUSTATUS bit 7 twice (X counts down from 2). This is the PPU warm-up delay.
6. Clear low RAM — @ClearLowRam: zero $0000–$003D.
7. Clear RAM pages — @ClearRamPages: using indirect pointer at $00/$01, clear pages starting at $0100 upward until high byte reaches $08 (effectively clearing $0100–$07FF).
8. PPUMASK=$06, scroll=$00 — enable background + sprites, reset scroll.
9. Warm-start signature check — @CheckRamSignature: compare RAM at $0052 against the 15-byte string "HIROKI AOYAGI" plus $AA,$55 (stored at RamSignature, $C354–$C366):
   • If all 15 bytes match → warm start: skip full RAM clear, go to @SignatureAlreadyPresent.
   • If any byte differs → cold start: @InitializeRamSignature clears all of zero page, then copies the signature string to $0052–$0060.
10. Set $64=$01 (some flag), set gameState=$00.
11. Set $45=$07, then check cocktail/active-player flags at $46/$47. If both nonzero, perform a 16-byte swap loop (@SwapLoop) swapping bytes between $67,y and $77,y for Y=0..15.
12. APUCTRL=$1F, APUFRAMECNT=$C0 — enable all APU channels, set frame counter mode.
13. jsr InitAudio ($EE8C) — set up the audio engine's pointers and workspace.
14. jsr ClearAudioWorkspace ($EEB4) — clear the 16 bytes of audio workspace.
15. Set PPUCTRL=$88, ppuCtrlShadow=$88 — enable NMI, $2000 nametable base.
16. Set $48=$FF (gameplay suspended flag), clear $023F and $024B (PPU update buffers).
17. Set $36=$01 (some state flag).
18. jmp MainEntry — transfer control to the main program.

RamSignature ($C354): .byte "HIROKI AOYAGI", $AA, $55 — developer credit / warm-start validation signature.

---

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

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

1. Save registers (A, X, Y on stack).
2. PPUMASK=$1E — enable background + sprites with specific emphasis settings.
3. OAM DMA: write $00 to OAMADDR ($2003), $00 to $40, then lda $45 / sta OAMDMA ($4014) — DMA from page $45 (i.e., $4500–$45FF) to sprite RAM.
4. jsr FlushGameplayPpuUpdates ($DE3B region) — flush pending PPU gameplay update blocks at $023F and $0245.
5. jsr ReadNearbyNametableTiles — read nametable tile data around Pac-Man (likely for collision/tunnel logic).
6. jsr UpdatePalettes — upload palette data from RAM buffers $0299 and $02A9 to PPU palette $3F00/$3F10 when those buffers are marked active ($0F marker).
7. Restore scroll: write $41 and $42 to PPUSCROLL (two writes — horizontal then vertical).
8. Construct PPUCTRL: lda $47 / and $46 / and #$01 / asl / ora $43 — builds the PPUCTRL value from shadow/flag bits, writes to PPUCTRL.
9. Controller strobe: write $01 then $00 to JOY1 ($4016).
10. Read both controllers — 8 iterations each:
    • Controller 1: read JOY1, mask with #$03, compare with #$01, rotate into $4D (currentInput).
    • Controller 2: read APUFRAMECNT ($4017), mask with #$03, compare with #$01, rotate into $4E.
11. Select active controller: X = currentInput ($4D) by default; if cocktailModeFlag ($46) & activePlayerFlag ($47) both nonzero, X = newlyPressedInput ($4E). Store X to previousInput ($4F).
12. inc frameCounter ($4B) — increment per-frame counter.
13. $48 gate: if $48 (gameplaySuspended) != 0, skip to @NmiDone.
14. jsr RunLevelScript ($EED0) — scan and activate the audio channel slots.
15. @NmiDone: restore registers (Y, X, A), rti.

The label IrqHandler appears at the rti following NMI's register restore — it is the same code address, just an alternate entry label for the IRQ vector (which points to the same rti).

UpdatePalettes

Conditionally uploads 16-byte palette blocks from RAM $0299 (to PPU $3F00) and $02A9 (to PPU $3F10) when the corresponding buffer marker byte equals $0F. After upload, resets the marker and PPU address to $3000.

---

5. Main Entry — MainEntry ($C573)

After Reset, control transfers to MainEntry. This is the foreground state-machine entry:

1. $40=$01 — set the NMI sync flag (NMI will clear it each frame).
2. @WaitForInitialNmi — spin until NMI clears $40 to $00 (synchronize to first VBlank).
3. PPUCTRL=$88 / ppuCtrlShadow=$88 — enable NMI.
4. PPUMASK=$00 — disable rendering.
5. Clear OAM page — fill $0700–$07FF with 0.
6. cocktailModeFlag=$00, then call:
   • jsr ClearGameplayNametables
   • jsr WriteMazeAttributeTable ($C30B)
   • jsr DrawMazeGraphics ($C2A6)
   • jsr $E419 — additional init (address-named; see §14).
7. Initialize palette buffers — copy 32 bytes from TitleScreenPalette to RAM $0299–$02B8.
8. Set actorStatusDisplay ($6C–$6F) = $2D, set $023F=$FF, gameplaySuspended=$FF.
9. Clear $47, $46, $42, $41, stateTimer ($4C), $87, $88.
10. PPUCTRL selection: if gameState ($3F) != 0, use $8A; else use $8A as well (both paths end up with $8A; the bne is effectively a no-op in current code). Write to PPUCTRL and ppuCtrlShadow.
11. MainDispatchLoop ($C645):
    • $40=$01, spin until NMI clears it (@WaitForNmi).
    • Y = gameState ($3F), load 16-bit handler address from MainStateHandlerTable ($C267) into $10/$11.
    • jmp ($0010) — indirect jump to the state handler.

MainStateHandlerTable ($C267–$C26E) — 4 entries, indexed by gameState as a byte offset (even values $00, $02, $04, $06):

Offset	Handler	Description
$00	InitialStateHandler	Title/input-wait state
$02	PlayerSelectionState	1P/2P selection
$04	State04Handler	Substate dispatch machine
$06	TimedStateTransition	Timed state transition

---

6. Main State Handlers

TimedStateTransition ($C27A) — state offset $06

• Decrement $0F countdown. If nonzero, return to MainDispatchLoop.
• When zero: set gameState=$02, return to MainDispatchLoop.
• This is a timed transitional state: another state places a duration in $0F and selects state $06; this handler counts down before advancing to state $02.

InitialStateHandler ($C27A region, actually at $C27A? No — at $C27A is TimedStateTransition; InitialStateHandler is at $C27A? Let me re-check)

Actually from the listing:

• TimedStateTransition is at $C27A
• InitialStateHandler is at $C27A? No. Let me re-read:

Line 730: TimedStateTransition: is at $C27A (based on comment "$C27A-$C2A5: Timed State Transition Handler" — wait, the comment says $C27A but the code shows dec $0F at line 731. Then line 740: ; $C27A-$C2A5: Initial/Input State Handler and line 766: InitialStateHandler:.

So there's a discrepancy in comments. The actual code:

• TimedStateTransition = dec $0F / bne MainDispatchLoop / lda #$02 / sta gameState / jmp MainDispatchLoop — this is state $06's handler.
• InitialStateHandler = checks controller bits $0C; if set → gameState=$06, $0F=$5A, jump MainEntry. Else increment $42; if $42 reaches $F0 → reset $42, ppuCtrlShadow=$88, gameState=$06, $0F=$5A. Otherwise return to MainDispatchLoop.

PlayerSelectionState ($C546 region) — state offset $02

• If $87|$88 != 0 → @AdvanceTimeout (16-bit timeout counter).
• Else (first entry): copy PlayerCountSelectionDisplayData ($C507–$C50E) to RAM $024B until $FF terminator. Capture controller bits $04 and $08 into pacmanRequestedDirection ($50) and pacmanDirection ($51).
• @AdvanceTimeout: increment 16-bit counter at $87/$88. If high byte reaches $02 → reset counter, set gameState=$04, jump MainDispatchLoop.
• @CheckSelectionInput: if controller bit $04 changed → store as pacmanRequestedDirection, reset counter, set $87=$01, toggle activePlayerFlag ($47) between 0/1, update display marker tiles at $024D/$0251 from PlayerCountSelectionMarkerTiles ($C50F–$C511).
• @CheckConfirmInput: if controller bit $08 changed → store as pacmanDirection. If bit $08 now active → clear gameplaySuspended, jsr ClearAudioWorkspace, jump GameModeEntry.

PlayerCountSelectionDisplayData ($C507): $22,$0A,$5C,$00, $22,$4A,$20,$FF — copied to $024B on entry. PlayerCountSelectionMarkerTiles ($C50F): $5C,$20,$5C — selection marker toggle data.

State04Handler ($C52E region) — state offset $04

• If controller bits $0C set → gameState=$02, jump MainEntry (restart).
• Else: Y = $87 (substate offset), load 16-bit handler from State04SubstateTable ($C52E), jump indirect via $10/$11.

State04SubstateTable ($C52E) — 12 entries indexed by even offsets $00–$16:

Offset	Handler
$00	State04Initialize
$02–$12	State04TimedSubstate (shared, 6 entries)
$14	State04LongDelay
$16	State04FinalPhase

• State04Initialize ($C573): sync to NMI via $40, PPUCTRL=$08, disable rendering, clear $88, call $C5D8, InitializeState04PpuData ($C608), LoadState04DisplayData ($C5A6), advance $87 by 2, PPUCTRL=$88, return to loop.
• State04TimedSubstate ($C589): increment $88; at $30 frames → clear $88, call $C5A6, advance $87 by 2.
• State04LongDelay ($C5A6): increment $88; at $80 frames → advance $87 by 2 to substate $16.
• State04FinalPhase ($C5D7): sets $47=$01, tail-jumps to GameModeEntry.
• SetSelectionFlagAndContinue ($C5D7): activePlayerFlag=$01, jmp GameModeEntry.

LoadState04DisplayData ($C5A6)

Uses $87 as offset into CharacterIntroDisplayDataTable ($C687), copies $FF-terminated stream to RAM $024B. Optional secondary copy of 16 bytes from CharacterIntroSpriteData based on substate offset.

CharacterIntroDisplayDataTable ($C687) — 10 pointers to display streams for characters/nicknames (SHADOW, BLINKY, SPEEDY, PINKY, etc.) plus scoring legend.

---

7. Game Mode Entry — GameModeEntry ($C328)

Reached from SetSelectionFlagAndContinue (state $04 final phase). This transitions from the attract/selection sequence into gameplay:

1. PPUCTRL=$88, ppuCtrlShadow=$88.
2. Wait for VBlank.
3. PPUMASK=$00, gameState=$00, cocktailModeFlag=$00, $69=$00, $4A=$00.
4. jsr ClearGameplayNametables, jsr DrawGameplayHudLabels, jsr DrawGameplayScoreFields.
5. If gameplaySuspended != 0 → roundNumber=$01 (continue existing game).
6. Else → clear 32 bytes starting at roundNumber ($67–$86), set roundNumber=$03, $77=$03, clear $0600/$0601.
7. Common init: roundDisplayValue=$FF, $78=$FF, $0245=$FF, ppuCtrlShadow=$88, PPUCTRL=$88.
8. GameModeFrameSync ($C360): $40=$01, wait for NMI clear ($@WaitForNmi`), then:
   • If gameplaySuspended != 0 AND controller bits $0C set → gameState=$02, jump MainEntry (restart).
   • If stateTimer ($4C) != 0 → decrement, return to @WaitForNextFrame.
   • Else @DispatchState: Y = gameState, load handler from GameModeStateTable ($CAD7) into $10/$11, indirect jump.

GameModeStateTable ($CAD7) — 8 entries indexed by even offsets $00–$0E:

Offset	Handler
$00	GameModeState00
$02	GameModeState02
$04	GameModeState04
$06	GameModeState06
$08	GameModeState08
$0A	GameModeState0A
$0C	GameModeState0C
$0E	InitializeGameplayTransitionState

GameModeState04 ($CAE9) — pause/per-frame handler

• If $060F != 0 → return to GameModeFrameSync.
• Else: edge-detect controller bit $08 using $49 as previous state. On new press → increment $4A, install pause display commands at $024B, toggle pause display via bit 0 of $4A.
• When not paused and bit 0 of $4A clear → call gameplay helper chain before returning to GameModeFrameSync.
• Adjacent data at $CB5B contains tile values for "PAUSE" text — confirms this is the pause-state handler.

---

8. PPU / Rendering

DrawMazeNametable ($E2E4)

Draws the maze nametable using compressed data:

• PPU destination selected based on cocktail mode ($47 & $46): $2000 or $2080.
• Source pointer from MazeDataPointerBytes at $FFF6–$FFF7 ($ECEC → points to ROM data).
• Each row: set PPU address, decode 2-bit-run-length-encoded bytes from the source (2 bits = repeat count-1, 6 bits = tile value), write $16 (22) bytes per row.
• Advance PPU destination by $20 per row.

FlushGameplayPpuUpdates ($DE3B)

• If $48 (gameplaySuspended) == 0 → process update block at $023F (6 bytes + terminator to PPU).
• Else → jump to UpdateAnimatedGameplayPpuFields.
• Block at $0245 processed similarly if nonzero.

---

9. Audio System

InitAudio ($EE8C):

• Clear audio request pointer ($F0/$F1 = $0006), channel table pointer ($F2/$F3 = $0620), sequence table pointer from ROM $F100/$F101.
• audioWorkValue=$40, APUSTATUS=$1F, APUFRAMECNT=$C0.
• Clear 16 bytes through ($F0), clear 16 entries at 8-byte stride through ($F2).

RunLevelScript ($EED0):

• Clear audio channel flags and work values, scan 16 eight-byte slots through ($F2).
• Slots with values $01–$04 activate a channel: copy 4-byte parameters through indirect pointer $F6.
• Falls through to runtime command processing at $EF2D.

UpdateAudioChannels ($EF33):

• For each active slot: decrement countdown, fetch command byte from sequence table, decode command ($F0+ = special, $C0+ = delay, else = note/frequency), update APU registers ($4000–$400F).

UpdateAudio ($F8DE):

• APUFRAMECNT=$C0, update Pulse 1, Pulse 2, Noise, Sound Effect channels.
• Clear $FF–$FB; if $07FF != 0 → APUDMALOAD, decrement $07FF.

Audio data tables at $FF00–$FFF5 (period/mask tables), $FF64–$FFEA (sequences/instruments), $F450–$F49A (runtime command data).

---

10. Zero-Page / RAM Symbols

Address	Symbol	Use
$00–$01	workPtr0/1	General indirect pointers
$02–$09	workValue0–5	General scratch values
$0A	pathCompareValue	Maze pathfinding
$0B	pathFallbackValue	Maze pathfinding
$0C	legalDirections	Maze pathfinding
$10	dispatchVector	State dispatch indirect pointer
$12–$15	arithmeticValue/Operand	16-bit arithmetic
$1A–$2D	pacmanMotion–ghost4Motion	Actor motion records (4 bytes each)
$2E–$2F	pacmanTargetRow/Column	Pac-Man maze target
$32	pacmanSpriteFrame	Pac-Man sprite frame
$33	ghostSpriteFrames	Ghost sprite frames
$39	ghostDirectionFlags	Ghost direction/control state
$3F	gameState	Main gameplay state
$40	—	NMI sync flag ($01=pending, NMI clears to $00)
$41	ppuCtrlShadow	PPUCTRL mirror
$42	—	Second PPUSCROLL write
$46	cocktailModeFlag	Cocktail cabinet mode
$47	activePlayerFlag	Active player (0/1)
$48	gameplaySuspended	Gameplay suspended flag
$4B	frameCounter	Per-frame counter
$4C	stateTimer	State countdown timer
$4D	currentInput	Controller 1 input
$4E	newlyPressedInput	Newly pressed input
$4F	previousInput	Previous input state
$50	pacmanRequestedDirection	Requested direction
$51	pacmanDirection	Current direction
$61	highScoreDigits	High score digits
$67	roundNumber	Round number
$68	roundDisplayValue	Round display value
$6A	pelletsRemaining	Pellets remaining
$6B	extraLifeAwarded	Extra life flag
$6C–$6F	actorStatusDisplay	Actor status display
$70	playerScoreDigits	Player score digits
$F0–$F7	audioRequestPtr…audioWorkValue	Audio engine pointers/values
$F8	audioChannelFlags	Audio channel flags
$FC	audioRequestIndex	Audio request index
$FD	audioChannelOffset	Audio channel offset
$FE–$FF	audioIndirectPtr	Audio indirect pointer

---

11. Data Tables and Pass 3 data-table inventory

The PRG is 27.6% code / 72.4% data (4,525 / 11,859 bytes). Every data block in the PRG is listed below. The names are the labels now in prg.s; a - means the block is left unnamed in the source because no instruction in this dump reads it, or because its layout could not be established from this dump.

The two PPU-update record formats

The game paints its screens with byte streams that are replayed into the PPU. Two formats are in use, and both are decoded from the consuming code.

Title-screen format (SubCC2E7, $C2E7): a record is [PPU address high][PPU address low][tile bytes…][$FF]. lda $C3B0,y at $C2EA and $C2F1 write the two address bytes to $2006, the inner loop at $C2F8–$C303 writes tile bytes to $2007 until it meets $FF, and the outer loop at $C2E1–$C308 repeats it nine times (lda #$09 / sta Zp00).

Character-intro format (SubCC5A6, $C5A6): the same shape, but the stream is reached through a pointer table and the copy stops at $FF; a $00 byte after the $FF means "this character also has a palette", in which case 16 palette bytes are copied from $C72E into $0760 (SubCC5CD).

Pass 3 data-table inventory

Address	Size	Name	Structure	Read by
$C000–$C032	51 B	-	The ASCII string COPYRIGHT 1980 1993 NAMCO LTD. ALL RIGHTS RESERVED followed by $A2 and $00, at the very head of the PRG image, immediately before the reset entry at $C033.	not referenced by any instruction — the on-screen copyright line is a different string, in TitleScreenPpuUpdateTable
$C0FF–$C10D	15 B	WarmStartSignature	13 ASCII bytes HIROKI AOYAGI followed by the two bytes $AA, $55. The reset path compares this 15-byte pattern against the RAM at $0052–$0060; a match means "warm start", a mismatch means the RAM is cleared and the pattern is written there.	lda $C0FF,y at $C08B (the comparison loop, cpy #$0F at $C094) and lda $C0FF,y at $C0A5 (the copy into $0052)
$C267–$C26E	8 B	MainStateHandlerTable	Four little-endian 16-bit handler addresses, one per main game state: $C27A (state $00, the attract loop), $C477 (state $02, player-count selection), $C512 (state $04, the character intro) and $C26F (state $06).	lda $C267,y at $C25A and lda $C268,y at $C25F; the two bytes are combined into $10/$11 and dispatched with jmp (Zp10) at $C264
$C27A–$C2A2	41 B	-	Code the tracer could not reach: the state-$00 attract-loop handler. It is only entered through the jmp (Zp10) of the handler table, which a static tracer cannot follow. It decodes cleanly as 20 instructions.	reached only through jmp (Zp10) at $C264
$C326–$C3AF	138 B	TitleScreenTileRows	6 rows × 23 tile indices. SubCC2A6 ($C2A6) writes them to nametable 0 starting at $20E5, adding $20 to the address after each row, so the rows land at $20E5, $2105, $2125, $2145, $2165 and $2185.	lda $C326,y at $C2C5 (23 bytes per row, dec Zp03 at $C2CC)
$C3B0–$C43E	143 B	TitleScreenPpuUpdateTable	Nine PPU-update records in the title-screen format: the PAC-MAN logo at $2065 (21 tiles), 1 PLAYER at $220C, 2 PLAYERS at $224C, TM © 1980 1993 NAMCO LTD at $22E3, NAMCO HOMETEK © INC at $2327, LICENSED BY NINTENDO at $2366, two tiles at $2293, eight tiles at $22AC and two tiles at $20FC.	lda $C3B0,y at $C2EA, $C2F1 and $C2F8
$C43F–$C45E	32 B	TitleScreenInitialPalette	The 32-byte master palette image that is copied into the palette buffer at $0299 when the title screen is set up.	lda $C43F,y at $C215 (32 iterations, cpy #$20 at $C21C), stored to $0299,y
$C45F–$C476	24 B	TitleScreenAttributeTable	The 24 attribute bytes of one nametable, written straight to $23C8.	lda $C45F,y at $C31A (24 iterations, cpy #$18 at $C321)
$C507–$C50E	8 B	PlayerCountSelectionPpuRecords	Two PPU-update records for the player-count screen: tile $5C at $220A, tile $00 at $220B, and tile $20 at $224A, then the $FF terminator.	lda $C507,y at $C47F, copied into the record buffer at $024B until the $FF at $C50E
$C50F–$C511	3 B	PlayerCountCursorTiles	The tile pair $5C, $20 and the duplicate $5C: the two cursor tiles and the tile the other player slot is set to.	lda $C50F,x at $C4D5 and lda $C510,x at $C4DB (X is 0 or 1 depending on which player is highlighted)
$C52E–$C545	24 B	State04SubstateHandlerTable	Twelve little-endian 16-bit addresses: the timed character-introduction substates. $C546 is the first, $C573 is used by eight of them, $C589 by one and $C792 by the last.	lda $C52E,y at $C521 and lda $C52F,y at $C526; dispatched with jmp (Zp10) at $C52B
$C573–$C5A5	51 B	-	Code the tracer could not reach: the state-$04 substate handler that eight of the table entries point at. Reached only through jmp (Zp10) at $C52B.	reached only through jmp (Zp10) at $C52B
$C667–$C686	32 B	CharacterIntroHeaderTiles	32 tile indices written straight to $2007 — the header strip of the character-introduction screen.	lda $C667,y at $C64B (32 iterations, cpy #$20 at $C652)
$C687–$C69A	20 B	CharacterIntroDisplayPointerTable	Ten little-endian 16-bit pointers to the per-character display records: $C69B, $C6B3, $C6BE, $C6C9, $C6D4, $C6DE, $C6EA, $C6F3, $C6FD, $C707. The index is Zp87, which the substate handler increments by two, so the entries are read at $C687+Zp87 and $C688+Zp87.	lda $C687,y at $C5A8 and lda $C688,y at $C5AD
$C69B–$C72D	147 B	CharacterIntroDisplayData	The ten per-character display records. Each is a PPU-update record — [addr high][addr low][text…][$FF] — optionally followed by a $00 that marks the end of the record set and asks for the palette to be loaded. The text reads CHARACTER ; NICKNAME, SHADOW, BLINKY, SPEEDY, PINKY, :POKEY, CLYDE, plus the two 10 PTS / 50 PTS score legends.	copied by the loop at $C5B4–$C5BC (lda (Zp00),y / cmp #$FF), which is entered with the pointer from CharacterIntroDisplayPointerTable
$C72E–$C76D	64 B	CharacterIntroPaletteTable	The per-character sprite palettes. Each entry is four bytes (two sprite colours and two background colours); the copy at $C5CD takes 16 bytes from $C72E+(index−2)*4 into $0760+(index−2)*4, so the 16 bytes are shared between neighbouring characters and only the first four differ.	lda $C72E,y at $C5CD, stored to $0760,y at $C5D0
$C76E–$C791	36 B	CharacterIntroNameTiles	36 tile indices written straight to $2007 — the row of character names.	lda $C76E,y at $C614 (36 iterations, cpy #$24 at $C61B)
$C792–$C8DB	330 B	-	Code the tracer could not reach: the rest of the character-introduction handlers, entered only through the indirect jumps of the substate and display tables.	reached only through jmp (Zp10)
$C9D8–$C9ED	22 B	PlayerScorePpuRecords	Two PPU-update records for the player-score boxes: eight tile-$2D tiles at $22AD and eight at $22ED.	copied into the record buffer at $024B by the score-drawing code
$C9EE–$C9F1	4 B	PlayerScoreDigitTiles	The four score digit tiles $2D, $2F, $32, $34.	lda $C9EE,y at $C918
$C9F2–$C9F5	4 B	PlayerScoreMarkerPpuRecord	A four-byte PPU-update record: address $22C7, tile $20, terminator $FF.	lda $C9F2,y at $C9CB, copied into $024B as the record prefix
$CA40–$CA53	20 B	-	20 tile indices (values $00–$1F) used by the score/bonus display. The code indexes it with (counter & 7) + base, where base is $00 or $0A, and separately with base + 8; the layout beyond "two eight-entry groups plus a two-entry group" is not established from this dump, so the block is left unnamed.	lda $CA40,y at $CA0E and $CA29
$CAD7–$CAE6	16 B	GameModeStateHandlerTable	Eight little-endian 16-bit addresses: the eight states of the game-mode state machine entered from GameModeEntry ($C328).	lda $CAD7,y at $CACA and lda $CAD8,y at $CACF; dispatched with jmp (Zp10) at $CAD4
$CAE7–$CB85	159 B	-	Code the tracer could not reach: the game-mode state handlers, entered only through the jmp (Zp10) of the table above.	reached only through jmp (Zp10) at $CAD4
$CC9C–$CCAD	18 B	MazeWallTileTable	The first of the two maze tile-index arrays, 16 bytes indexed by the actor's row segment (inc Zp05 at $CBB8). The values $B0–$C7 are the distinct wall-corner and wall-edge tiles of the maze.	lda $CC9C,x at $CB9F, written to the nametable buffer at (Zp00),y
$CCAE–$CCBF	18 B	MazePathTileTable	The second maze tile-index array, 16 bytes indexed the same way. The values are only $00 (empty corridor) and $02 (the pellet tile), so this array carries the maze's paths while MazeWallTileTable carries its walls.	lda $CCAE,x at $CBA5
$CCC0–$CCC5	6 B	MazeColumnOffsetTable	Three pairs of bytes: the column offset and the base row of each of the three vertical wall runs of the maze ($44/$88, $44/$60, $50/$70).	lda $CCC0,x at $CB88 and lda $CCC1,x at $CB8D (X = Zp06, stepped by two)
$CCC6–$CCCB	6 B	MazeRowRepeatTable	Six repeat counts ($06, $06, $03, $C0, $C1, $C2) — how many rows each of the maze's horizontal wall runs occupies.	lda $CCC6,x at $CB94 (X = Zp07)
$CCD1–$CCD8	8 B	MazeTargetPositionTable	Four little-endian 16-bit nametable positions: $2317, $2319, $231B, $2357. The code loads the high byte and adds a run-time offset to it.	lda $CCD1,y at $CC32 and lda $CCD2,y at $CC3A (Y = (Zp67−1)×2)
$CCD9–$D289	1,457 B	-	Code the tracer could not reach: the maze-drawing and game-loop routines that follow the tables above, entered only through indirect jumps.	reached only through jmp (Zp10)
$D29C–$D3A5	266 B	-	Code the tracer could not reach: decodes cleanly as instructions and is entered through an indirect jump.	reached only indirectly
$D40E–$D415	8 B	LevelHandlerPointerTable	Four little-endian 16-bit addresses ($D416, $D41A, $D435, $D431), indexed by a level/state byte in Zp51 times two.	lda $D40E,y at $D401 and lda $D40F,y at $D406; dispatched with jmp (Zp10) at $D40B
$D416–$D505	240 B	-	Code the tracer could not reach: the four level handlers the table above points at.	reached only through jmp (Zp10) at $D40B
$D51F–$D556	56 B	-	28 two-byte records. The first byte of each record is loaded into ZpE3 and the low two bits of the second give a direction code (and #$03 at $D51A). The record layout is not established from this dump, so the block is left unnamed.	lda $D51F,y at $D512 and lda $D520,y at $D517
$D557–$D595	63 B	-	Code the tracer could not reach: the routine that uses the record table above.	reached only indirectly
$D5A1–$D763	451 B	-	Code the tracer could not reach: decodes cleanly as instructions and is entered through an indirect jump.	reached only indirectly
$D871–$D880	16 B	DirectionPairTable	Eight two-byte records, each a pair of distinct values drawn from {0,1,2,3}: (3,2), (2,3), (3,0), (0,3), (1,2), (2,1), (1,0), (0,1). These are the eight direction-pair codes used by the ghosts' movement logic.	lda $D871,y at $D7E5
$D881–$D884	4 B	-	Two little-endian 16-bit values ($0000 and $2C08) used as a pointer pair. The table is only two entries long and its role is not established, so it is left unnamed.	lda $D881,y at $D77E and lda $D882,y at $D783
$D885–$D913	143 B	-	Code the tracer could not reach: the routine that uses the pointer pair above.	reached only indirectly
$D953–$D95A	8 B	ActorHandlerTable	Four little-endian 16-bit addresses: $D95D three times and $D5A1 once — the per-actor-type movement handlers.	lda $D953,y at $D946 and lda $D954,y at $D94B; dispatched with jmp (Zp10) at $D950
$D95B–$D98D	51 B	-	Code the tracer could not reach: the actor movement handlers.	reached only through jmp (Zp10) at $D950
$D9C6–$D9CB	6 B	-	Six bytes $00, $00, $00, $01, $01, $00 added to a base value to give a position. The table is read as a byte array indexed by a direction code; its role is not established, so it is left unnamed.	lda $D9C6,y at $D9BD
$D9FA–$DA01	8 B	ActorStateHandlerTable	Four little-endian 16-bit addresses: $DA21 three times and $DA2D once — the per-actor-state handlers.	lda $D9FA,y at $D9ED and lda $D9FB,y at $D9F2; dispatched with jmp (Zp10) at $D9F7
$DA02–$DA3F	62 B	-	Code the tracer could not reach: the actor-state handlers.	reached only through jmp (Zp10) at $D9F7
$DBEE–$DCFD	16 B	PacManSpriteTileTable	The tile byte of each OAM sprite record, 16 entries per actor type, indexed by actor × 16 + frame. The values $4C,$03,$08,$07 … are Pac-Man's animation tiles.	lda $DBEE,y at $DB5C, stored into byte 1 (the tile byte) of the OAM record at (Zp02)
$DCFE–$DD0D	16 B	GhostSpriteTileTable	The tile byte of each OAM sprite record for the ghosts: $4D,$4E,$53,$54,$4E,$52,$55,$4C …	lda $DCEE,y at $DB7F, stored into the tile byte of the OAM record
$DD22–$DD31	16 B	SpriteAttributeTable	The attribute byte of each OAM sprite record: the values $00,$40,$80,$C0 are the NES attribute bits (palette, horizontal flip, vertical flip). The same 16 bytes are also read as a tile source at $DB39, which is a genuine ROM quirk.	ora $DD22,y at $DB6A (combined with the base attribute $0292,y and stored into byte 2 of the OAM record); also lda $DD22,y at $DB39
$DE22–$DE31	16 B	GhostSpriteAttributeTable	The attribute byte of the ghosts' OAM records, same $00/$40/$80/$C0 encoding.	ora $DE22,y at $DB8D
$DE32–$DE55	36 B	-	The remaining sprite tables and the code of the sprite-building routine.	not referenced by any instruction
$DF6C–$DF7B	16 B	ActorVramAddressTable	Eight little-endian 16-bit PPU addresses — one per actor on screen: $20B4, $20A2, $22D4, $22C2, $28B4, $28A2, $2AD4, $2AC2. These are the nametable positions the actors' sprites are drawn at.	lda $DF6C,y at $DF2A and lda $DF6D,y at $DF30, both written to $2006
$DF7C–$E0A9	302 B	-	Code the tracer could not reach: the routine that draws the actors' sprites.	reached only indirectly
$E0E6–$E1CD	232 B	-	Code the tracer could not reach: decodes cleanly as instructions and is entered through an indirect jump.	reached only indirectly
$E2E2–$E384	163 B	-	Code the tracer could not reach: decodes cleanly as instructions and is entered through an indirect jump.	reached only indirectly
$E49F–$E4B0	18 B	-	Nine 16-bit values whose second byte takes only the values $61, $70 and $80; they are loaded as a pair into $02/$03 and passed to the sprite routine at $E474. The meaning of the values is not established, so the block is left unnamed.	lda $E49F,x at $E447 and lda $E4A0,x at $E44C
$E53C–$E549	14 B	PlayerIntroPpuStream	Two PPU-update records in the character-intro format: eight tiles $B4–$BB at $2076, three tiles $B0,$B3,$B2 at $20F7 and three tiles $B1,$B3,$B2 at $2177 — the player-name strip of the player-one / player-two screen.	lda $E53C,y at $E506, $E513, $E51A and $E520
$E54A–$EA18	1,231 B	-	Code the tracer could not reach: the rest of the player-introduction routine.	reached only indirectly
$EA94–$EB9E	267 B	-	Code the tracer could not reach: decodes cleanly as instructions and is entered through an indirect jump.	reached only indirectly
$EBB6–$EE8B	726 B	-	726 bytes whose first bytes are all in the range $00–$07 — the shape of the per-level ghost-behaviour table — but no instruction in this dump reads it, and its internal layout is not established. Recorded as unreferenced data.	not referenced by any instruction
$F01E–$F03D	32 B	SoundHandlerTable	Sixteen little-endian 16-bit addresses: $F03E (the "no sound" routine) followed by $F04B, $F063, $F07B, $F093, $F0A3, $F0B3, and then $F03E eight more times. Indexed by (A & $0F) × 2, i.e. by the sound request number.	lda $F01E,x at $F011 and lda $F01F,x at $F016; dispatched with jmp (ZpFE) at $F01B
$F03E–$F048	11 B	-	Code the tracer could not reach: the "no sound" routine that nine of the table entries point at.	reached only through jmp (ZpFE) at $F01B
$F063–$F090	46 B	-	Code the tracer could not reach: decodes cleanly as instructions and is entered through an indirect jump.	reached only indirectly
$F0A3–$F0B0	14 B	-	Code the tracer could not reach: decodes cleanly as instructions and is entered through an indirect jump.	reached only indirectly
$F0E8–$F101	26 B	NotePeriodTable	Thirteen little-endian 16-bit note periods: $03F9, $03C0, $038A, $0357, $0327, $02FA, $02CF, $02A7, $0281, $025D, $023B, $021B, $02F1. The differences between consecutive entries shrink monotonically, which is the signature of a scale; the last entry ($02F1) is the base period the sound engine starts from.	lda $F0E8,x and lda $F0E9,x at $EFB4/$EFB9; the base period is read as lda $F100 at $EE9C and lda $F101 at $EEA1
$F102–$FFF9	3,848 B	-	$FF fill to the end of the PRG image.	not referenced by any instruction
$FFFA–$FFFF	6 B	CpuVectors	The three interrupt vectors: NMI = $C10E (NmiHandler), RESET = $C033 (Reset), IRQ/BRK = $C17E (IrqHandler, a bare rti).	the CPU fetches them from $FFFA–$FFFF when an interrupt is taken

11.1 Data structures in RAM (not ROM tables)

• The PPU-update record buffer at $024B and the score/actor state at $028C–$0293
• The palette buffer at $0299 (32 bytes), filled from TitleScreenInitialPalette
• The character palettes at $0760–$076F, filled from CharacterIntroPaletteTable
• The warm-start signature at $0052–$0060, compared against WarmStartSignature
• The sound-engine base period at $F4/$F5, loaded from the last entry of NotePeriodTable

---

12. Summary of Execution Flow

Power On / Reset
    │
    ▼
Reset ($C033) ───────────────────────────────────────────────┐
    │ sei, cld, disable PPU, wait 2× VBlank                   │
    │ clear RAM $0000–$003D, clear pages $0100–$07FF          │
    │ PPUMASK=$06, scroll=$00                                 │
    │ check warm-start signature "HIROKI AOYAGI" + $AA,$55    │
    │   valid → skip full clear; invalid → clear + save sig   │
    │ set flags, optional 16-byte swap ($67↔$77)              │
    │ APUCTRL=$1F, APUFRAMECNT=$C0                            │
    │ jsr InitAudio, jsr ClearAudioWorkspace                  │
    │ PPUCTRL=$88 (NMI enabled), $48=$FF (suspended)          │
    │ jmp MainEntry                                           │
    │                                                         │
MainEntry ($C573)                                             │
    │ $40=$1, wait for NMI to clear it                        │
    │ PPUCTRL=$88, PPUMASK=$00, clear OAM                     │
    │ clear cocktail/player flags, $41/$42/$4C/$87/$88        │
    │ init nametables, attributes, palette buffers            │
    │ select PPUCTRL ($8A), set ppuCtrlShadow                 │
    │                                                         │
MainDispatchLoop ($C645) ─────────────────────────────────────┤
    │ $40=$1, wait for NMI                                    │
    │ Y = gameState ($3F)                                     │
    │ load handler from MainStateHandlerTable ($C267)         │
    │ jmp ($0010) → state handler                             │
    │                                                         │
    ├─ State $00: InitialStateHandler                         │
    │   ├─ controller bits $0C → gameState=$06, $0F=$5A      │
    │   │   → jump MainEntry (restart sync)                  │
    │   └─ else inc $42; if $42==$F0 → reset, gameState=$06 │
    │                                                         │
    ├─ State $02: PlayerSelectionState                        │
    │   ├─ 1P/2P selection via controller bits $04/$08       │
    │   ├─ timeout ($87/$88 reaches $0200) → gameState=$04   │
    │   └─ confirm (bit $08) → clear suspended, jsr ClearAudioWorkspace,
    │       jmp GameModeEntry                                 │
    │                                                         │
    ├─ State $04: State04Handler                              │
    │   ├─ controller bits $0C → gameState=$02, restart      │
    │   └─ Y=$87 → dispatch via State04SubstateTable ($C52E) │
    │       ├─ $00: State04Initialize (PPU setup, $87+=2)    │
    │       ├─ $02–$12: State04TimedSubstate ($30 frames)    │
    │       ├─ $14: State04LongDelay ($80 frames)            │
    │       └─ $16: State04FinalPhase → $47=$1,              │
    │           jmp GameModeEntry                             │
    │                                                         │
    └─ State $06: TimedStateTransition                        │
        │ dec $0F; if nonzero → MainDispatchLoop              │
        │ else gameState=$02 → MainDispatchLoop               │
    │                                                         │
    └─ loop back to MainDispatchLoop                          │
    │                                                         │
GameModeEntry ($C328) [from SetSelectionFlagAndContinue]      │
    │                                                         │
    ├─ PPUCTRL=$88, wait VBlank, PPUMASK=$00                  │
    ├─ clear gameplay state, HUD labels, score fields         │
    ├─ if not suspended: clear player state, roundNumber=$3   │
    │   else: roundNumber=$1                                  │
    ├─ common init: roundDisplayValue=$FF, PPUCTRL=$88       │
    │                                                         │
GameModeFrameSync ($C360) ────────────────────────────────────┤
    │ $40=$1, wait for NMI                                    │
    │                                                         │
    ├─ if suspended && controller bits $0C → gameState=$02,  │
    │   jmp MainEntry (restart)                               │
    │                                                         │
    ├─ if stateTimer != 0 → dec, return to @WaitForNextFrame │
    │                                                         │
    └─ Y = gameState → dispatch via GameModeStateTable ($CAD7)│
        │                                                     │
        ├─ $00: GameModeState00                               │
        ├─ $02: GameModeState02                               │
        ├─ $04: GameModeState04 (pause/input handler)         │
        │     ├─ $060F != 0 → return to frame sync            │
        │     ├─ edge-detect controller bit $08 ($49)         │
        │     │   → new press: inc $4A, install pause cmds   │
        │     │   → bit 0 of $4A toggles pause display        │
        │     └─ not paused, bit0 of $4A clear → gameplay     │
        │       helper chain → return to frame sync           │
        ├─ $06–$0C: GameModeState06/08/0A/0C                  │
        └─ $0E: InitializeGameplayTransitionState             │
        │                                                     │
        └─ loop back to GameModeFrameSync                     │
    │                                                         │
    └─ (eventually enters gameplay via $0E handler)           │
                                                              │
NMI ($C10E) [once per frame]                                  │
    │                                                         │
    ├─ save A, X, Y                                           │
    ├─ PPUMASK=$1E                                            │
    ├─ OAM DMA ($4500–$45FF → $0200–$02FF)                   │
    ├─ jsr FlushGameplayPpuUpdates ($DE3B)                   │
    ├─ jsr ReadNearbyNametableTiles                           │
    ├─ jsr UpdatePalettes ($3F00/$3F10 from $0299/$02A9)     │
    ├─ restore scroll ($41,$42 → PPUSCROLL)                   │
    ├─ construct PPUCTRL from $47,$46,$43                     │
    ├─ strobe JOY1, read both controllers (8 bits each)       │
    │   → $4D (current), $4E (newly pressed)                  │
    ├─ select active controller → $4F (previousInput)         │
    ├─ inc frameCounter ($4B)                                 │
    ├─ if $48==0: jsr RunLevelScript                        │
    ├─ restore registers, rti                                 │
    │                                                         │
IrqHandler ($C17E): rti (unused)                              │
                                                              │
Audio Engine (from NMI via RunLevelScript/ClearAudioWorkspace)│
    ├─ 16 eight-byte channel slots scanned                    │
    │   │ values $01–$04 activate a channel                   │
    │   │ 4-byte parameters copied via $F6 pointer            │
    ├─ UpdateAudioChannels ($EF33):                          │
    │   │ decrement countdowns, fetch command bytes,          │
    │   │ decode ($F0+=special, $C0+=delay, else=note),       │
    │   │ write APU registers $4000–$400F                     │
    └─ UpdateAudio ($F8DE): 4 channels + SFX + DMA trigger    │

---

13. Notes

• Build verification: make in copilot/ produces reconstructed.nes, compared whole-ROM against rom.nes.
• Pass 3 data tables: every data block in the PRG is interpreted and listed in the Pass 3 data-table inventory (section 11), with the address range, the name, the structure and the consuming instruction for each. The PPU-update record formats, the maze tile tables, the sprite tile/attribute tables and the note-period table are all decoded from the consuming code; the blocks that no instruction in this dump reads are recorded as unreferenced data, and the blocks that decode cleanly as instructions are recorded as code the tracer could not reach (the ROM reaches them through jmp (Zp10) indirect jumps, which a static tracer cannot follow).
• Vectors confirm NMI at $C10E, RESET at $C033, IRQ at $C17E (a bare rti, unused).
• The foreground main loop (MainDispatchLoop at $C645) is strictly NMI-synchronized via $40: NMI clears it each frame, and the main code spins waiting for it to clear before dispatching to the next state handler.
• GameModeEntry ($C328) is a second, separate state machine entered from the state-$04 final phase. It has its own frame sync ($40) and its own 8-state dispatch table (GameModeStateHandlerTable at $CAD7), leading into gameplay initialization.
• State $04 contains a nested secondary state machine (State04SubstateHandlerTable at $C52E) with 12 substate offsets, implementing a timed character-introduction sequence (GHOST names, nicknames, scoring legend).
• The warm-start signature "HIROKI AOYAGI" at $0052 allows the game to preserve RAM across a soft reset; the pattern itself lives in the ROM at WarmStartSignature ($C0FF).
• Many routine labels are address-based (State04TimedSubstate, LoadState04DisplayData, 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, controller masks, and extensive zero-page symbol definitions.

Power-on flow analysis

Derived from the disassembly by _tools/derive_poweron.py; the call graph is walked from the reset entry.

---

14. Naming residue — address-derived entry points

Every jsr/jmp target in this project now carries a semantic name except 4, which keep the honest address-derived SubCCXXXX form because the dump does not reveal what they are for:

Label	Address	Why the dump does not settle the name
SubCC5D8	$C5D8	Points PPUADDR at VRAM $20C0 and sets a count of $17 (23) tiles, then writes that many tiles from the following table. The screen that owns VRAM $20C0 is not identified by anything in this dump, so naming it "the screen that writes 23 tiles at $20C0" would only restate the code.
SubCDA5A	$DA5A	Compares the position at $0274 with the position at ($00),y and computes the signed difference; the caller treats it as a distance test, but the code does not name the two things being compared.
SubCE419	$E419	Points the score writer at VRAM $2083 with a stride of $09 and at the player-2 score variable. The dump does not identify the screen row that block occupies.
SubCEA19	$EA19	Adds the 16-bit word at $001A (Pac-Man's motion record) to the word at $0274 and then tests the high byte against $C0. The two words are positions, but the dump does not say whose positions they are.

The other 41 entry points are named, and the names follow the analysis already in this document: UpdatePalettes ($C17F), FlushGameplayPpuUpdates ($DE7E), ReadNearbyNametableTiles ($E2A2), LoadState04DisplayData ($C5A6), InitializeState04PpuData ($C608), BuildOamBuffer ($E1DA), InitAudio ($EE8C), RunLevelScript ($EED0), UpdateAudioChannels ($EF33), ApplyAudioCommand ($EFA2) and ReadScriptParam ($F0C3) among them.