tmerritt/disasm
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
42 Commits 1 Branch 0 Tags
0a49ee6da7f410f960029d8ad0c35fc56b1c61b7
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE
tmerritt 0a49ee6da7 Pass 2 _wip: Slalom (U), Kung Fu (U), Othello (U) label replacement complete 
Pass 3 _wip: Slalom (U), Kung Fu (U), Othello (U) semantic naming complete
Pass 3 _wip: apply symbols (0 residue) for Slalom (U), Kung Fu (U), Othello (U)
Pass 2/3 _wip: 10 NROM projects (Elevator Action, 1942, Tag Team Wrestling, Galaga, Kung Fu a1, Stack-Up, Magmax, Ms Pac-Man Namco, Soccer, Sqoon)
Promote 13 _wip/NROM projects to NROM/ (Slalom, Kung Fu, Othello, Elevator Action, 1942, Tag Team Wrestling, Galaga, Kung Fu a1, Stack-Up, Magmax, Ms Pac-Man Namco, Soccer, Sqoon)
Pass 2/3 _wip: 5 CNROM games (Tiger-Heli, Paperboy, Last Starfighter, Mighty Bomb Jack, Kung-Fu Heroes)
Docs: document CDL capture + re-trace workflow in TODO.md
Adds more code for
 - Elevator Action (U)
 - Kung Fu (U)
 - Othello (U)
 - Slalom (U)
 - Sqoon (U)
2026-10-21 14:42:00 -04:00
_tools
…
_wip
…
CNROM/World Class Track Meet (U)
…
MAPPER8/Mermaids of Atlantis (U)
…
NROM
Pass 2 _wip: Slalom (U), Kung Fu (U), Othello (U) label replacement complete
2026-10-21 14:42:00 -04:00
UNROM/Zanac (U)
…
.gitignore
…
AGENTS.md
…
CHANGELOG.md
Pass 2 _wip: Slalom (U), Kung Fu (U), Othello (U) label replacement complete
2026-10-21 14:42:00 -04:00
default_project.tar.gz
…
Makefile
…
opencode.json
…
PROMPTS.md
…
README.md
…
TODO.md
…
WIP.md
…

README.md

Disassembly Project 1

This is a set of disassembled NES roms using AI to translate.

This is not for distribution.

This is not for you.

Layout changed 2026-10-20: projects moved into mapper directories (NROM/, AOROM/, CNROM/, MMC1/, MMC3/, MMC5/, UNROM/), project folders were flattened (the old copilot/ subfolder is gone — everything sits directly in the project folder), every project's OVERVIEW.md became its README.md, and a root Makefile now builds and verifies all projects at once (make, make clean, make <MAPPER>); the git pre-commit hook drives it. Older docs, commit messages and paths in this file's per-project notes may still reference the previous layout — mentally strip the copilot/ prefix.

Disassembly Project Index — /home/tmerritt/Projects/disasm/

This document provides a consolidated overview of the promoted NES disassembly projects in the repository. Projects are organized by mapper into a folder per project under NROM/, AOROM/, CNROM/, MMC1/, MMC3/, MMC5/, UNROM/ or MAPPER8/ — 38 of the 41 promoted projects are mapper 0 and live in NROM/, with World Class Track Meet (U) in CNROM/ (mapper 3), Zanac (U) in UNROM/ (mapper 2) and Mermaids of Atlantis (U) in MAPPER8/ (mapper 8). The pre-promotion tier mirrors the structure under _wip/<MAPPER>/<Project>/ and is documented separately in WIP.md (851 projects across 29 mapper folders). Each project folder is flat: the source (prg.s, plus header.s/chr.s where present), the build config (linker.cfg, symbols.inc, locals.inc, Makefile) and the ROM splits all sit directly in the folder. Each project carries its own README.md (the file was called OVERVIEW.md before 2026-10-20) with a detailed power-on execution flow analysis. The pass history of every project — Pass 1, Pass 2, Pass 3 and Promotion, with the date and what each milestone produced — is in CHANGELOG.md.

Project Inventory

Mirroring is the iNES arrangement value taken from header byte 6, bit 0 (0 = Horizontal, 1 = Vertical), the convention AGENTS.md fixes. Several per-project README files (then named OVERVIEW.md) previously carried the opposite mirroring-direction wording; all were normalized to this column on 2026-10-19.

# Project Region/Version PRG Size CHR Size Mirroring Build Status Vectors (NMI / RESET / IRQ)
1 Balloon Fight (JU) Japan 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass complete) $C094 / $C000 / $C0F7
2 Baseball (UE) USA/Europe 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass complete) $C046 / $C40B / $C43E
3 Bomberman (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $C01A / $C000 / $FFF9
4 Burger Time (U) USA 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass complete) $FF7F / $FD24 / $FD24
5 Clu Clu Land (JU) Japan 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass complete) $C1F1 / $C196 / $C196
6 Defender 2 (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $CAA1 / $C983 / $CA9E
7 Excitebike (JU) Japan 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $C23B / $C184 / $FFF0
8 Tennis (JU) Japan 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $C07D / $C000 / $C000
9 Pac-Man (USA) (Namco) — 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass complete) $C10E / $C033 / $C17E
10 Donkey Kong 3 (JUE) Japan / USA / Europe 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $C08D / $C000 / $C000
11 Donkey Kong Jr. (JU) Japan 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $C6E6 / $C66E / $FFF0
12 CIRCUS — 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $C05A / $C000 / $4CB7
13 Wild Gunman (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 3 complete, 49.3% code) $C086 / $C000 / $C000
14 Joypad Test Cartridge (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 3 complete) $CCF7 / $C000 / $C000
15 NES PowerPad Test Card (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $E06E / $E000 / $E000
16 MUSCLE (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass complete) $86CB / $8000 / $8764
17 Lunar Pool (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 2 complete, Pass 3 tables named) $FF65 / $E80C / $FF64
18 Donkey Kong (JU) Japan 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 2/3 complete, 76.3% code) $C85F / $C79E / $FFF0
19 Donkey Kong Jr. Math (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 3 complete) $C4A9 / $C41E / $FFF0
20 Duck Hunt (JUE) Japan / USA / Europe 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 3 complete) $C086 / $C000 / $C000
21 Ice Climber (JE) — 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 3 complete) $C076 / $C014 / $FFF0
22 Ice Climber (U) USA 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 3 complete) $C076 / $C014 / $FFF0
23 Lode Runner (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 2/3 complete) $C02C / $C000 / $FFF9
24 Pinball (JU) Japan 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 2/3 complete) $C1ED / $C000 / $C1ED
25 Millipede (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 2/3 complete, 74.6% code) $C7F1 / $C735 / $FFF0
26 Popeye (JU) (PRG 0) — 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 2/3 complete, 72.3% code) $C701 / $C649 / $FFF0
27 Popeye (JU) (PRG 1) — 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 2/3 complete, 72.3% code; promoted from _wip 2026-10-20) $C701 / $C649 / $FFF0
28 Golf (JU) Japan 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 1+2+3 complete; promoted from _wip 2026-10-21) $C0A6 / $C000 / $C0C4
29 Hogan's Alley (JU) Japan 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 2 complete, Pass 3 partial, 49.1% code; promoted 2026-10-20) $C088 / $C000 / $C000
30 Mario Bros (JU) Japan 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 2 complete, Pass 3 partial, 78.4% code; promoted 2026-10-20) $C07D / $C000 / $C000
31 Pac-Man (Tengen) (U) USA 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 2 complete, Pass 3 partial, 20.0% code; promoted 2026-10-20) $C0FA / $C033 / $C16A
32 Pac-Man (U) USA 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 2 complete, Pass 3 partial, 19.6% code; promoted 2026-10-20) $C0FA / $FF00 / $C16A
33 Pyramid (U) (Sachen) — 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 2 complete, Pass 3 partial, 39.6% code; promoted 2026-10-20) $D72E / $FF00 / $FF00
34 Raid on Bungeling Bay (U) USA 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 2/3 partial, 64.6% code; promoted 2026-10-20) $C04C / $C000 / $C2C0
35 Raid on Bungeling Bay (U) [a2] — 16 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 2 complete, Pass 3 partial, 64.3% code; promoted 2026-10-20) $C04C / $C000 / $C2C0
36 Urban Champion (JU) Japan 16 KB 8 KB Vertical BYTE-IDENTICAL (Pass 3 complete, 33.9% code) $CA91 / $CA00 / $CA00
37 Xevious (U) USA 32 KB 8 KB Horizontal BYTE-IDENTICAL (Pass 3 complete, 38.0% code) $FC4E / $FAF6 / $FF1D
38 Zanac (U) USA 128 KB none Horizontal BYTE-IDENTICAL (Pass 3 complete, 34.5% code) $CE8D / $E7BF / $CEC4
39 Volleyball (U) Japan 32 KB 8 KB Vertical BYTE-IDENTICAL (Pass 3 complete, 73.0% code; promoted 2026-10-21) $8053 / $8000 / $FFFF
40 Mermaids of Atlantis (U) USA 64 KB 64 KB Vertical BYTE-IDENTICAL (Pass 3 complete, 12.3% code; promoted 2026-10-20, rebuilt 2026-10-21) $808F / $FF00 / $8036
41 World Class Track Meet (U) USA 32 KB 32 KB Horizontal BYTE-IDENTICAL (Pass 1+2+3 complete, 55.0% code; promoted from _wip 2026-10-21) $F803 / $F6FD / $C0C0 (dead)

Thirty-six of the 41 rows are mapper 0 with a 16 KB PRG, 8 KB CHR and no trainer. The exceptions: Xevious (U) and Volleyball (U) are mapper 0 with a 32 KB PRG; World Class Track Meet (U) is mapper 3 (CNROM) with a 32 KB PRG and 32 KB CHR (its header's CHR-size field overstates the CHR by 32 KB); Zanac (U) is mapper 2 with a 128 KB PRG and no CHR; Mermaids of Atlantis (U) is mapper 8 with a 64 KB PRG, 64 KB CHR and eight 8 KB banks.

All 41 rows are promoted and BYTE-IDENTICAL — make compares the whole reconstructed ROM against rom.nes in the project folder. The last two to leave _wip/ were Golf (JU) (row 28) and World Class Track Meet (U) (row 41), both promoted on 2026-10-21. (Urban Champion, row 36, kept its tail number, so the promoted numbering is no longer a single contiguous range.)

Still true after the 2026-10-20 reorganization. The mapper reorganization moved Donkey Kong Jr. Math (U) (row 19) into _wip/NROM/ — it was fixed the same day (its four jsr $F218 call sites had been labelled SubCF218_Block = $F1DC; repointed to the true entry SubCF218) and promoted back into NROM/. Popeye (JU) (PRG 1) was promoted from _wip/NROM/ the same day (row 27) — its whole-ROM compare passes on the first build. Excitebike (JU) (row 7) — the repo's one open block after being returned to NROM/ with a broken mid-repair build (duplicate symbol) — was finished the same day: the byte-596 mismatch ($0A operands where the ROM uses $11, now aliased NmiMaskShadow) is fixed, the 4,401 damaged audit comments were re-anchored via _tools/repair_audit_comments.py, and 58 raw jsr/jmp $XXXX operands were substituted with labels/equates. All 38 projects under NROM/ now verify byte-identical.

How to read this table. The vectors are the three little-endian words at the end of the 16 KB PRG ($FFFA-$FFFF in the $C000 mirror) — not fields in the iNES header, whose bytes 0-9 carry only sizes, mirroring and mapper. Regenerate the whole column with:

python3 - <<'EOF'
import os
MAPPERS = ('NROM', 'AOROM', 'CNROM', 'MMC1', 'MMC3', 'MMC5', 'UNROM')
for base in MAPPERS:
    if not os.path.isdir(base):
        continue
    for p in sorted(d for d in os.listdir(base) if os.path.isdir(os.path.join(base, d))):
        rom = open(f"{base}/{p}/rom.nes", 'rb').read()
        prg = rom[16:16 + rom[4]*16384]; vo = len(prg) - 6
        v = [prg[vo+i] | (prg[vo+i+1] << 8) for i in (0, 2, 4)]
        print(f"{p:30s} {'Vertical' if rom[6] & 1 else 'Horizontal':10s} "
              + " / ".join("$%04X" % x for x in v))
EOF

Five rows were wrong before this pass, all from copy-paste duplication of a neighbouring row's vectors, and are corrected above:

Project Was Actually
Burger Time (U) $C046 / $C40B / $C43E (Baseball's) $FF7F / $FD24 / $FD24
Clu Clu Land (JU) $C1F1 / $C000 / $FFF9 $C1F1 / $C196 / $C196
Excitebike (JU) $C1F1 / $FD24 / $FD24 $C23B / $C184 / $FFF0
Pac-Man (USA) (Namco) $C10E / $C000 / $C17E $C10E / $C033 / $C17E
Donkey Kong 3 (JUE) $C07D / $C000 / $C000 $C08D / $C000 / $C000

Donkey Kong Jr.'s mirroring was also wrong (Horizontal, actually Vertical). Odd vector targets are not mistakes: Burger Time's $FF7F NMI and CIRCUS's $4CB7 IRQ point into unused/data space, which is common in this set — see "Notes" under Per-Project Details.

Region/Version comes from the folder-name suffix (JU/U/UE/JUE); these mapper-0 headers do not encode region, so CIRCUS — whose folder carries no suffix — is left as — rather than guessed.

Per-Project Details

1. Balloon Fight (JU)

  • Folder: NROM/Balloon Fight (JU)/
  • ROM: balloon.nes (24,592 bytes)
  • Source: prg.s (8,543 lines)
  • Linker: PRG at $C000, 16 KB; single segment
  • Vectors: NMI → $C094 (NmiHandler), RESET → $C000 (Reset), IRQ → $C0F7 (IrqHandler, self-loop)
  • Key subsystems: NMI-driven frame loop with PPU command buffer, round spawner ($C790), bonus objects ($CB74), carrier/rescue sequence ($C6F9), particle system ($CDAA), sound driver ($FFF7 banked)
  • Build fix: None needed; byte-identical out of the box. Pass 1 verified complete 2026-10-16 — 5,303 instructions / 11,260 code bytes (68.7%), which is more than the complete-opcode static tracer finds (5,277 / 11,202); the 166 tracer-only bytes are genuine data (command scripts at $D437/$D45A, the $C3B5 pointer table, the arithmetic table at $FBCA), not missed code. The last two .incbin spans were converted to explicit classified bytes (TrailingFillBeforeApuTables at $F4C5, SoundEngineTailBytes at $F5FC), so no ROM byte is hidden
  • Pass 3 symbols (2026-10-19): every operand symbols.inc/locals.inc defines is now named in prg.s — 125 hardware-register operands and 797 of 813 zero-page/RAM operands. The 15 multi-alias addresses were resolved per routine (--sites in _tools/apply_symbols.py). 16 operands are left numeric: $13 used as a plain high-byte scratch beside Temp12, where none of its three aliases fits. Rebuild stays byte-identical.
  • Audit-trail repair (2026-10-21): the per-instruction audit comments were stale by two bytes from ResetInitializationData ($C085) onward — 5,944 of the 6,007 comments named the wrong CPU address/PRG offset, because the 3-byte .byte "HAL" signature at $C082–$C084 was counted as one byte when the trail was generated. The routine headers and the linker labels were correct, so source and headers disagreed. _tools/repair_audit_comments.py rebuilt the trail from the ca65 -l listing (validated against prg.bin) and _tools/align_audit_comments.py restored the canonical column-35 layout. Comment-and-whitespace only: the code text of all 8,544 lines is unchanged and make still prints Byte-identical ROM verified. All 6,007 comments now re-check against prg.bin, all 65 routine headers agree with the instructions they describe, and every label agrees with reconstructed.lbl. A related off-by-one in align_audit_comments.py was fixed (it tested the indented code length against 31 instead of 35, so 28–31-character code texts were never padded into the column).
  • Routine headers completed (2026-10-21): all 63 routine headers now carry the full template AGENTS.md describes — global, local, parameters, returns and clobbers. The ; Clobbers: blocks are derived, not written by hand: _tools/derive_clobbers.py takes the opcode from the audit comment's byte list (so the addressing mode is exact), resolves the operand through locals.inc/symbols.inc to name what is written, follows the real control flow (a jsr to another named entry is a call; a branch or a fall-through is not), and models register preservation — so NmiHandler reports no register (it saves and restores A, X and Y) and FlushPpuCommandPreserved reports only A (X and Y come back unchanged). The flags are named individually. Comment-only change: the code text of all 8,538 lines is unchanged and make still prints Byte-identical ROM verified.
  • Details: Balloon Fight (JU)/README.md

2. Baseball (UE)

  • Folder: NROM/Baseball (UE)/
  • ROM: baseball.nes (24,592 bytes)
  • Source: prg.s (21,624 lines — largest source)
  • Linker: PRG at $C000, 16 KB; single segment
  • Vectors: NMI → $C046 (NMI), RESET → $C40B (Reset), IRQ → $C43E (IRQ, rti)
  • Key subsystems: Queued event system ($EB66–$EB9C) as the main frame driver, round/state machine ($C5FE), batting/pitching ($C6044–$C6414), object sorting ($C339), sound driver ($F9D0–$FE2x)
  • Build fix: None needed; byte-identical out of the box
  • Pass 3 symbols (2026-10-19): 121 operands substituted (85 single-name + 36 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: Baseball (UE)/README.md

3. Bomberman (U)

  • Folder: NROM/Bomberman (U)/
  • ROM: bomberman.nes (24,592 bytes)
  • Source: prg.s (7,553 lines), header.s, chr.s
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C01A (NmiHandler), RESET → $C000 (Reset), IRQ → $FFF9 (IrqHandler, rti)
  • Key subsystems: NMI-driven PPU command queue and VRAM transfers, main loop at $C368 with state dispatch table ($C75D), bomb/object slots (80 slots at $03E6), sound driver ($E642–$FE2x) with dispatch table ($E6AD)
  • Build fix: One-byte mismatch at CPU $E71B (dec $E4 vs dec $54) — resolved by adding RandomStateAlt = $E4 to locals.inc alongside RandomState0 = $54 (zero-page reuse); also renamed ControllerState → ControllerState1, Main_HandleControl_C368 → MainGameLoop, Gameplay_HandleControl_C79D → GameplayUpdate, Sound_HandleControl_E65F → SoundUpdate
  • Pass 3: Applied 354 single-name + 8 site-resolved multi-alias operands from locals.inc; 24 in-file table labels from reconstructed.lbl; 0 hardware substitutions needed. Residue: 758 unnamed operands (179 distinct addresses).
  • Details: Bomberman (U)/README.md

4. Burger Time (U)

  • Folder: NROM/Burger Time (U)/
  • ROM: Burger Time (U) [!].nes (24,592 bytes)
  • Source: prg.s (9,323 lines), header.s, chr.s
  • Linker: HEADER, PRG at $C000 (0x3FFA), VECTORS at $FFFA, CHR
  • Vectors: NMI → $FF7F (points into the vector page itself — not a real handler; NMI is effectively unused), RESET → $FD24 (ResetHandler, sei prologue), IRQ → $FD24 (reuses Reset)
  • Key subsystems: Event-driven main loop via CommonEngineExit ($EB6A) and queued events ($EB9D), title screen / round state machine ($C5FE), object arrays ($03E6 state, $0436/$0486 position), audio engine ($F9D0–$FE2x) with music sequencer ($FD34)
  • Build fix: None needed; byte-identical. Requires symlink burger_time.nes → "../Burger Time (U) [!].nes" due to spaces in ROM filename
  • Details: Burger Time (U)/README.md

5. Clu Clu Land (JU)

  • Folder: NROM/Clu Clu Land (JU)/
  • ROM: rom.nes (24,592 bytes)
  • Source: prg.s (9,151 lines)
  • Linker: PRG at $C000, 16 KB; single segment (no separate HEADER/CHR segments in cfg, but CHR data is embedded inline at end of prg.s)
  • Vectors: NMI → $C1F1 (NMIHandler), RESET → $C196 (ResetEntry, shared with the IRQ handler), IRQ → $C196 (IrqHandler, reuses Reset)
  • Key subsystems: State-machine main loop via dispatch table at $C000–$C00D, NMI-driven PPU command queue + VRAM transfers, object pools ($03E6 state, $0436/$0486 position), sound driver ($E642–$F7C0) with dispatch table ($E6AD)
  • Build fix: One bpl branch to undefined label at CPU $FAB4 — replaced with bne *-$1B to produce original d0 e3 bytes (disassembler mislabeled bne as bpl)
  • Details: Clu Clu Land (JU)/README.md

6. Defender 2 (U)

  • Folder: NROM/Defender 2 (U)/
  • ROM: Defender 2 (U).nes (24,592 bytes)
  • Source: prg.s (11,905 lines)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (0x3FFA), VECTORS at $FFFA, CHR at $0000
  • Vectors: NMI → $CAA1 (NmiHandler), RESET → $C983 (ResetHandler), IRQ → $CA9E (IrqHandler, reuses Reset)
  • Key subsystems: Event-driven main loop (UpdateSideScrollingGameplay_CA6A at $CA6A) waiting on NMI flag, side-scrolling gameplay ($C073–$C324 family), PPU streaming ($F20B–$F7C0), audio engine ($E642–$F7C0) with dispatch table ($E6AD)
  • Build fix: Same bpl → bne *-$1B fix at CPU $E811 as Clu Clu Land (disassembler mislabeled bne as bpl)
  • Details: Defender 2 (U)/README.md

7. Excitebike (JU)

  • Folder: NROM/Excitebike (JU)/
  • ROM: rom.nes (24,592 bytes)
  • Source: prg.s (13,992 lines)
  • Linker: PRG at $C000, 16 KB; single segment
  • Vectors: NMI → $C23B (NMI), RESET → $C184 (Reset), IRQ → $FFF0 (points into audio data region — likely placeholder/unused)
  • Key subsystems: NMI-driven state machine with dispatch table at $C000–$C00D (14 states), title/menu system ($C346–$C454), gameplay update chain ($C99A), race update ($C8D6), audio engine ($F8DE) with 4 channels + SFX, serial I/O over controller port $4016
  • Build fix: Same bpl → bne *-$1B fix at CPU $FAB4 (same pattern as Clu Clu Land/Defender 2). On 2026-10-20 the last whole-ROM mismatch (byte 596) was fixed — two NMI operands the ROM spends on $11, a second PPU-mask shadow, were emitted with PpuMaskShadow ($0A); $11 is now aliased NmiMaskShadow in locals.inc. The same day the audit trail was re-anchored from the ca65 listing via _tools/repair_audit_comments.py (6,339 shifted comments + 4,401 doubled-?? forms) and all 58 raw jsr/jmp $XXXX operands were substituted with routine labels/locals.inc sub-entry equates.
  • Details: Excitebike (JU)/README.md

8. Tennis (JU)

  • Folder: NROM/Tennis (JU)/
  • ROM: Tennis (JU).nes (24,592 bytes)
  • Source: prg.s (9,268 lines)
  • Linker: PRG at $C000, 16 KB; single segment
  • Vectors: NMI → $C07D (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (Reset reused)
  • Key subsystems: NMI-synchronized main loop (MainLoop at $C04F), game state machine via MainStateHandlerTable ($C101, 12 states), game mode state machine via GameModeStateTable ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
  • Build fix: None needed; byte-identical out of the box
  • Pass 3 symbols (2026-10-19): 18 single-name operands substituted from locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: Tennis (JU)/README.md

9. Pac-Man (USA) (Namco)

  • Folder: NROM/Pac-Man (USA) (Namco)/
  • ROM: rom.nes (24,592 bytes)
  • Source: prg.s (9,268 lines)
  • Linker: PRG at $C000, 16 KB; single segment
  • Vectors: NMI → $C10E (NmiHandler), RESET → $C033 (Reset; locals.inc defines ResetOffset = $C033), IRQ → $C17E (IrqHandler)
  • Key subsystems: NMI-synchronized main loop (MainLoop at $C04F), game state machine via MainStateHandlerTable ($C101, 12 states), game mode state machine via GameModeStateTable ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
  • Build fix: None needed; byte-identical out of the box
  • Pass 3 symbols (2026-10-19): 524 single-name operands substituted from locals.inc via _tools/apply_symbols.py — 727 multi-alias residues left numeric (addresses with 2+ aliases, e.g. $00 = workPtr0/Zp00). Rebuild stays byte-identical.
  • Details: Pac-Man (USA) (Namco)/README.md

10. Donkey Kong 3 (JUE)

  • Folder: NROM/Donkey Kong 3 (JUE)/
  • ROM: Donkey Kong 3 (JUE).nes (24,592 bytes)
  • Source: prg.s (9,952 lines)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C08D (NmiHandler; the prg.s header block records it as "Pass 2 control-flow entry at CPU $C08D"), RESET → $C000 (Reset), IRQ → $C000 (Reset reused)
  • Key subsystems: Main loop with object/game state management at $C02E–$C18D, object movement and geometry calculations ($C28E–$C683), audio engine ($F8DE+) with sound channels ($F0–$FF), PPU command buffer streaming ($C3F4+)
  • Build fix: Build split main.s into header.s, prg.s, chr.s; added RandomStateAlt = $E4 for dec $E4 at CPU $E71B (zero-page reuse with RandomState0 = $54). 2026-10-16 — one-byte branch-target bug fixed: the project was recorded as BYTE-IDENTICAL but had never built byte-identical. The bne at CPU $C14C (PRG $014C) was annotated D0 12 (target $C160) but assembled as D0 0D, because it was labelled StoreSelectedPlayerAndScreenFlags ($C15B) instead of the routine actually at $C160. Retargeted to ClearAudioSetGameMode — which is also the semantically correct target for a "mode != $01" test. cmp now passes.
  • Details: Donkey Kong 3 (JUE)/README.md

11. Donkey Kong Jr. (JU)

  • Folder: NROM/Donkey Kong Jr. (JU)/
  • ROM: Donkey Kong Jr. (JU).nes (24,592 bytes)
  • Source: prg.s (12,807 lines; 6,135 instructions, 266 routines, 68 data labels, 0 conflicts)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C6E6 (NmiHandler), RESET → $C66E (ResetHandler), IRQ → $FFF0 (stray byte, effectively unused)
  • Key subsystems: Reset idles in a PRNG-advance loop — the entire frame state machine (title/attract/gameplay/sound) runs inside the NMI handler; VRAM/event queue at $0300 with dispatch table at $BFFE; 8-byte PRNG at $18–$1F; sound timers at $F1AF
  • Build fix: None needed; byte-identical out of the box (make in the project folder). Pass 1 verified complete 2026-10-16 — a full byte-accounting audit of prg.s confirms all 16,384 PRG bytes are emitted exactly once (6,199 instructions + 3,889 .byte + 16 .word), every emitted value equals the ROM byte, and there are zero audit-comment mismatches or duplicate addresses. No .incbin remains. A complete-opcode static tracer independently reaches 6,135 instructions / 12,358 code bytes (75.4%) — every one of which is already present in the file, and the file carries 121 further code bytes the tracer does not find (reached via the DeferredTaskHandlerTable dispatch at $BFFE). Pass 2/3 naming is complete; Pass 3 tables are named (DeferredTaskHandlerTable, HudDigitDescriptorTable, …)
  • Details: Donkey Kong Jr. (JU)/README.md

12. CIRCUS

  • Folder: NROM/CIRCUS/
  • ROM: rom.nes (24,592 bytes)
  • Source: prg.s (~12,755 lines)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C05A (NmiHandler), RESET → $C000 (Reset), IRQ → $4CB7 (outside mapped space — effectively unused)
  • Key subsystems: NMI-driven frame state machine — main loop is a spin loop at $C057, all per-frame work runs in NMI; main state dispatcher at $C0D0 with 16-state pointer table; controller input with edge flags at $09; menu system with text table at $C763 ("CONTINUE", "STAGE", "SELECT", "PLAY"); palette/screen transfer via descriptor streams; VRAM queue processing; variant object state machine at $DC3F–$FE7B; audio engine with sequence data at $FABB–$FFFB
  • Build fix: None needed; byte-identical out of the box (make in the project folder). Pass 1/2/3 complete — full code/data classification, semantic routine naming, and data table naming all done
  • Pass 3 symbols (2026-10-19): 118 operands substituted (38 single-name + 80 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — 23 multi-alias residues left numeric (addresses with 2 aliases: $E4=Controller1Shift/ZpE4, $7C=WorkPointer0Lo/Zp7C, $7E=WorkPointer1Lo/Zp7E). Rebuild stays byte-identical.
  • Details: CIRCUS/README.md

13. Wild Gunman (U)

  • Folder: NROM/Wild Gunman (U)/
  • ROM: rom.nes (24,592 bytes)
  • Source: prg.s (~3,000 lines with routine headers)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C086 (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (reuses Reset)
  • Key subsystems: NMI-driven frame loop — main loop is a spin loop waiting on NMI phase flag ($20); NMI handler does OAM DMA ($4014), PPU updates, and calls game logic subroutines ($C29F, $C233, $C3AC, $C265); main state dispatcher at $C0B3 based on GameMode ($30); reset copies sprite/OAM data from $C844 to $05F0; APU enabled via $4015 = $0F
  • Build fix: None needed; byte-identical out of the box (make compares the whole ROM in the project folder: cmp reconstructed.nes rom.nes). Pass 1 redone 2026-10-16 — the original tracer followed only RESET/NMI/IRQ and jsr/jmp/branch targets and knew just the 151 documented opcodes, so it missed Wild Gunman's runtime dispatch (Label_C341's pla-based computed goto puts the jump table inline right after each jsr $C341) and filed ~4.9 KB of real code as .byte data. Code coverage went 1,597 instr / 3,352 B (20.5%) → 3,956 instr / 8,085 B (49.3%). Pass 2 complete — all 733 labels carry names (zero Label_Cxxxx/SubCxxxx remain), routine headers on every entry point, zero-page aliases in locals.inc (GameMode=$30, NmiPhase=$20, NmiFlag=$22, Timer2F=$2F, etc.). Pass 3 complete — data tables named: SpriteAttributeTable ($C6AC), NoteVolumeTable ($F3EF), VolumeEnvelopeTable ($F48F), SpritePositionTable ($F77C); the OAM sprite block at $C844 is documented in-place as a comment rather than a label
  • Pass 3 symbols (2026-10-19): 76 operands substituted (11 single-name + 65 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: Wild Gunman (U)/README.md

14. Joypad Test Cartridge (U)

  • Folder: NROM/Joypad Test Cartridge (U)/
  • ROM: rom.nes (24,592 bytes)
  • Source: prg.s (4,401 lines; 202 routines, all with described headers)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $CCF7 (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (reuses Reset)
  • Key subsystems: NMI-driven frame loop — main loop spins waiting on NMI phase; NMI handler does OAM DMA ($4014), PPU scroll/control latch, and burst VRAM writes from table at $0302; VramPtrWrite ($CD3F) uses a return-address modification trick at RetAddrUpdate ($CDC8) for runtime-computed dispatch; VramWrite ($CDEE) sets PPU address and writes data to PPUDATA; reset clears RAM, initializes PPU ($2000=$10, $2001=$00), triggers OAM DMA, and enters main loop
  • Build fix: Byte-identical out of the box, but Pass 1 was badly truncated and has been redone. It claimed 282 instructions / 580 bytes (3.5%); the tracer halted at $C09E on DCP $3C20 ($CF), an undocumented opcode used as ordinary code, and filed 3,256 bytes of real code as .byte. Now 1,773 instructions / 3,836 bytes (23.4%), verified against a fresh trace. nesdis.py --undocumented supplies the 105 undocumented NMOS opcodes; ca65 V2.19 encodes none of them, so the 4 affected instructions are emitted as explicit .byte with the disassembly in the comment. Pass 2 then renamed all 202 labels (zero Label_Cxxxx left) and rewrote all 202 routine headersr all labels, semantic naming for key routines, zero-page aliases in locals.inc (VramPtrLo=$00, PpuCtrlShadow=$EF, FrameCounterLo=$53, etc.)
  • Pass 3 symbols (2026-10-19): 47 hardware operands substituted from symbols.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: Joypad Test Cartridge (U)/README.md

15. NES PowerPad Test Card (U)

  • Folder: NROM/NES PowerPad Test Card (U)/
  • ROM: rom.nes (24,592 bytes)
  • Source: prg.s (8,842 lines)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $E06E (NmiHandler), RESET → $E000 (Reset), IRQ → $E000 (reuses Reset)
  • Key subsystems: Minimal NMI-driven test cartridge — NMI reads PowerPad via $4016, processes transitions, updates score/lives display; APU at $4015=$0F; 7.2% code coverage
  • Build fix: None needed; byte-identical out of the box
  • Pass 3 symbols (2026-10-19): 89 hardware operands substituted from symbols.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: NES PowerPad Test Card (U)/README.md

16. MUSCLE (U)

  • Folder: NROM/MUSCLE (U)/
  • ROM: M.U.S.C.L.E. (U).nes (24,592 bytes); rom.nes is a relative symlink ../M.U.S.C.L.E. (U).nes
  • Source: prg.s (Pass 1/2/3 output, with 42 bytecode listings above the .byte data)
  • Linker: HEADER at $0000 (16 bytes), PRG at $8000 (16 KB), CHR at $0000 (8 KB) — the one ROM in the set mapped low
  • Vectors: NMI → $86CB (NmiHandler), RESET → $8000 (Reset), IRQ → $8764 (a bare RTI that doubles as the NMI epilogue). Vectors themselves sit in the $C000 mirror at $FFFA.
  • Key subsystems: bytecode VM — 40 opcodes at $C8-$EF handled through a table at $9237, everything else a literal operand. Gameplay dispatches through three jump tables plus two zero-page jmp (zp) calls a static descender cannot follow: 38-entry token-program pointer table at $8CEF, 40-entry opcode handler table at $9237, 16-entry handler table at $9F2B, 3-entry per-level VRAM-writer table at $AC35. Compressed-VRAM RLE decoder at $AC82 with a 12-byte fill table at $ACBD; division by 20 restored at $82AC; four-channel sound engine with per-channel state in zero page $C4-$EF.
  • Build fix: the skeleton's $C000 linker assumption was wrong — RESET is $8000, so linker.cfg had to move. Makefile tool paths were ../../../_tools/ while in _wip/; promotion to top-level required ../../_tools/. make regen (pass1→pass2→pass3) reproduces prg.s byte-for-byte.
  • Pass 3 symbols (2026-10-19): 220 operands substituted (91 single-name + 129 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: MUSCLE (U)/README.md

17. Lunar Pool (U)

  • Folder: NROM/Lunar Pool (U)/ (promoted out of _wip/ 2026-10-18 by git mv, so the relative rom.nes symlink is live and tool paths are ../../_tools/)
  • ROM: Lunar Pool (U).nes (24,592 bytes)
  • Source: prg.s (5,300 instructions, 67.6% code / 11,077 bytes; 705 labels, zero Label_ residue, 38 semantic zero-page aliases + 66 neutral, 33 named data tables)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $FF65 (NmiHandler), RESET → $E80C (non-$C000 entry), IRQ → $FF64 (bare rti, adjacent to NMI)
  • Key subsystems: NMI-driven frame loop with PPU command queue and VRAM transfers; main loop at $E80C; side-scrolling / pool gameplay; audio engine; print-inline-string helper at $CBDC/$CBC9
  • Build fix: Promotion from _wip/ added header.s, chr.s, HEADER/PRG/CHR linker.cfg, and whole-ROM cmp; rebuilt from Mesen CDL capture (10,028 bytes Code). Pass 1/2/3 complete — byte-identical at whole-ROM level.
  • Pass 3 symbols (2026-10-19): 45 operands substituted (18 single-name + 27 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: Lunar Pool (U)/README.md

18. Donkey Kong (JU)

  • Folder: NROM/Donkey Kong (JU)/ (promoted out of _wip/ 2026-10-19 by git mv, so the relative rom.nes → ../Donkey Kong (JU).nes symlink survived)
  • ROM: Donkey Kong (JU).nes (24,592 bytes)
  • Source: prg.s (6,014 instructions, 76.3% code / 12,505 bytes; 1,015 labels with zero Label_ residue, 145 zero-page slots with neutral ZpXX names, 10 named data regions)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C85F (NmiHandler), RESET → $C79E (non-$C000 entry, like DK Jr.), IRQ → $FFF0 (vector-page padding, unused)
  • Key subsystems: reset enters at $C79E; NMI-driven frame loop; dispatchers at $C807/$C815/$C823/$C831/$C847 load 16-bit pointers from ObjectPtrTable ($C03C) and from $C4A7,x; large level-data pointer block $C044–$C79D; sound engine over MusicDataTable ($F55B), APUDataTable ($FAE6), SfxDataTable ($FE59)
  • Pass 2 (2026-10-19): all 919 Label_XXXX definitions named — 102 new semantic routine names + 217 SubC<addr> entry names (honest residue) + 600 derived <Routine>_Block[_n] internal branch targets; jsr/jmp operands stay numeric (Wild Gunman (U) style). Applied with _tools/pass2.py apply; make still byte-identical
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink, and the whole-ROM cmp; no _tools path change (the Makefile never referenced _tools/) and no make regen target. Mirroring was recorded as Vertical in the project README (then named OVERVIEW) but header byte 6 = $00 says Horizontal — corrected at promotion
  • Pass 3 symbols (2026-10-19): 75 operands substituted (17 single-name + 58 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: Donkey Kong (JU)/README.md

31. Pac-Man (Tengen) (U)

  • Folder: NROM/Pac-Man (Tengen) (U)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
  • ROM: Pac-Man (Tengen) (U) [!].nes (24,592 bytes), reached through the rom.nes symlink
  • Source: prg.s (4,595 lines; 1,637 instruction lines covering 3,273 code bytes = 20.0%; 227 labels — 199 routine entries + 28 branch targets — zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands, 2,479 canonical audit comments, 0 byte mismatches against prg.bin)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C0FA (NmiHandler), RESET → $C033 (Reset — the boot sequence is inline here; there is no boot code at $FF00 in this build), IRQ → $C16A (IrqHandler)
  • Key subsystems: NMI frame loop with two controller reads; game-state dispatch through GameStateDispatchTable ($C253); maze graphics (MazeTileGraphics $C2FD, AttributeTableData $C387, BorderPattern $C432); ghost AI with the target search at $C8AA and the four-ghost slots; UpdateMazeTiles ($DAB0) rewriting the maze through the four overlay tables; score/attribute VRAM writes; the level-script interpreter at $EE8F dispatching through ScriptCommandTable ($EFDD)
  • Variant: a different build of the same game as row 32 — 56 PRG bytes differ in 8 runs, all of them code-versus-licensee-text ($C3E3-$C408 is 26 spaces here against LICENSED BY NAMCO AMERICA INC there; $FF00-$FF16 is $FF padding here against the boot code there), and the RESET vector differs to match. The CHR is identical
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 d34e7a74…28ad0)
  • Pass 2 (2026-10-20): a fresh map derived from this dump's own committed split — no name, map or file was carried over from the row-32 dump. All 194 Label_XXXX definitions renamed to semantic routine entries plus <Routine>_<Role> branch targets, and all 48 raw $XXXX call operands resolved. Recorded in routinemap.tsv
  • Pass 3 (2026-10-20): 30 semantic zero-page aliases, each applied only at the sites where its role is proven (the per-site choice is in sites.tsv; the addresses that carry two roles keep the neutral ZpXX name elsewhere, and locals.inc records the reason for every remaining neutral slot). 28 data tables named — including CharacterDataTable ($C66A) and CharacterNameStrings ($C67E), where the ROM itself names Blinky, Pinky, Inky and Clyde. apply_symbols.py reports 0 residue
  • Pass 1 correction (2026-10-20): six command handlers recovered. ScriptCommandTable ($EFDD) is read by the traced instruction at $EFCC, and six of its entries point at $F00A, $F022, $F03A, $F052, $F062 and $F072 — all of which the tracer had left as data, and two of which it had mis-split across the jmp $EF61 at $F01F and $F04F. Those 120 bytes are code here, decoded straight from the ROM. The same gap exists in the promoted row-32 dump, which has not been corrected
  • Residue: the unreached main game logic at $C45A–$C55F is still .byte data. It is code — the tracer's own decoder walks it cleanly and the dispatch table at $C511 points into it — but nothing reaches it, so it cannot be entered without a guess. The same gap exists in the row-32 dump. Re-deriving it is a Pass 1 job; a Mesen Code Data Logger capture is the tool the repo uses (_tools/cdl_reclass.py)
  • Details: Pac-Man (Tengen) (U)/README.md

32. Pac-Man (U)

  • Folder: NROM/Pac-Man (U)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv; tool paths stay ../../_tools/)
  • ROM: Pac-Man (U) [!].nes (24,592 bytes), reached through the rom.nes symlink
  • Source: prg.s (4,511 lines; 1,549 audited instruction lines covering 3,058 code bytes, plus 49 jsr/jmp call sites — 19.6% code by the Pass 1 tracer's accounting; zero Label_ residue, zero raw $XXXX call operands)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C0FA (NmiHandler), RESET → $FF00 (Reset — real boot code at the vector-page tail, not padding: sei/cld, PPU off, double vblank wait, jmp ColdStart at $C042), IRQ → $C16A (IrqHandler)
  • Key subsystems: NMI-driven frame loop; game-state dispatch through GameStateDispatchTable ($C253) via jmp (DispatchPtrLo); entity dispatch through EntityPtrTable ($D912) and a second table at $D9B9; palette upload from $0299/$02A9; VRAM write queue at $026B/$0272; audio engine with AudioCommandTable ($EFDD) dispatched via jmp (AudioHandlerPtrLo); 15-byte copyright signature ProgrammerSig ($C0EB) checked against RAM at $0052
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 a69d310f8cae9397fbd39f204672b5c7)
  • Pass 2 (2026-10-20): fresh map derived from the committed split (not from a drafted map): all 194 Label_XXXX definitions renamed to semantic routine entries plus <Routine>_<Role>_<addr> internal branch targets, and all 49 jsr/jmp call sites resolved to labels. Recorded in routinemap.tsv / derived_names.tsv
  • Pass 3 symbols (2026-10-20): 119 operands substituted (101 hardware + 11 single-name + 7 multi-alias resolved per site via sites.tsv) — apply_symbols.py reports 0 residue. The 7 site resolutions are all proven from context: four jmp ($0010) immediately preceded by sta DispatchPtrLo/sta DispatchPtrHi, one jmp ($00FE) preceded by sta AudioHandlerPtrLo/sta AudioHandlerPtrHi, and two sta a:$0000,y zero-page clears that take the neutral Zp00. Audit-comment alignment was re-done afterwards with the new _tools/align_audit_comments.py (whitespace-only)
  • Details: Pac-Man (U)/README.md

29. Hogan's Alley (JU)

  • Folder: NROM/Hogan's Alley (JU)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
  • ROM: Hogan's Alley (JU).nes (24,592 bytes), reached through the rom.nes symlink
  • Source: prg.s (10,920 lines; 3,950 instruction lines covering 8,041 code bytes = 49.1%; 681 labels, zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands, 4,490 canonical audit comments, 0 byte mismatches against prg.bin)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C088 (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (the same address)
  • Key subsystems: the frame heartbeat — the NMI sets GameFramePending ($20) and the main loop spends it, with NmiPhaseFlag ($22) stopping the per-frame work from running twice; an inline dispatch architecture — IndirectCall at $C34D pops the return address of the jsr that called it and reads a 16-bit handler pointer from the word that follows, so the six handler tables live inside the code stream ($C124 19 entries, $C219 4, $C89C 14, $CDD1 1, $D234 2, $D3D6 14); the Zapper on $4017 (ReadZapper $CF3E) with the controller debounced over five frames into Player1Buttons ($16); a three-accumulator sound engine (SoundFlag0/1/2 at $F0–$F2) fed by 24 one-bit stubs and read at $F9FF/$FC48/$FAFC, with the note records in NoteParameterTable ($FCC8)
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical
  • Pass 1 correction (2026-10-20): the static trace classified only 41.8 % of the PRG as code. A fresh Mesen Code Data Logger capture was merged with the four captures already in the folder (hogans_merged.cdl, the OR of five per-byte flag arrays, 6,544 code bytes) and _tools/cdl_reclass.py rewrote the split to match what the CPU actually fetched: 1,216 bytes moved from data to code, five moved the other way and 59 labels were emitted. The four branch targets the tool could not prove were turned into labels by the new _tools/resolve_raw_branches.py
  • Pass 2 (2026-10-20): a fresh map derived from this dump's own committed split: 206 routine entries hand-named and 413 internal branch targets derived mechanically by _tools/derive_branch_names.py, 630 Label_XXXX definitions gone, 484 raw $XXXX call operands resolved, 15 call targets the tracer had never labelled given a label. Recorded in routinemap.tsv
  • Pass 3 (2026-10-20): 60 semantic zero-page aliases, each applied only where its role is proven (zp_aliases.inc and zp_alias_sites.tsv); the slots that stay neutral are each listed with the reason. 34 data tables named — SubStateHandlerTable, ModeHandlerTable, HandlerDispatchTable, ActorCommandTable, TargetBehaviourTable, NoteParameterTable and the rest — and recorded in data_region_names.tsv. apply_symbols.py reports 1 residue: sta a:$00B4,y at $C203, the same address as Zp40/ActorPalette but forced to absolute addressing, so it must stay numeric
  • Residue: no make regen target. The Pass 1 split here is the static trace corrected by a CDL capture, and the base the correction was applied to is not what the current _tools/nesdis.py produces, so a regen pipeline could not reproduce prg.s byte for byte. prg.s is the maintained source of truth
  • Details: Hogan's Alley (JU)/README.md

30. Mario Bros (JU)

  • Folder: NROM/Mario Bros (JU)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
  • ROM: Mario Bros (JU).nes (24,592 bytes), reached through the rom.nes symlink
  • Source: prg.s (16,345 lines; 6,210 instruction lines covering 12,847 code bytes = 78.4%; 1,025 labels, zero Label_ residue and zero SubC residue, zero raw $XXXX jsr/jmp/branch operands, 6,458 canonical audit comments, 0 byte mismatches against prg.bin)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C07D (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (the same address)
  • Key subsystems: the frame heartbeat — the NMI sets FramePendingFlag ($20) and the main loop spends it, with NmiPhaseFlag ($22) stopping the NMI handler from doing its per-frame work twice; an inline dispatch table — the handler pointers sit in the middle of the code stream, right after the call that reads them, so the static tracer cannot follow them (GameStateHandlerTable $C510 and its five continuation blocks); a script interpreter that drives the enemies (SetupScriptPointer $CB85, FetchScriptByte $E9FA, RunScript $E9D3) with the command byte compared against $AA and $BB; the Zapper-free controller read with a five-frame debounce into Zp10/Zp11; a per-note sound engine at $F8A7–$FD27 working from the note table at $FCC8
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical
  • Pass 1 correction (2026-10-20): the committed split was a strict subset of the correct one — only 72.0% of the PRG was classified as code. A Mesen Code Data Logger capture of this ROM (mario_mesen.cdl, 10,915 code bytes) showed 1,010 bytes the tracer had left as data were code; the two branch targets the capture never reached ($E4CB and $E639) were forced with --override and account for 57 more, so 1,067 bytes moved from data to code and 22 moved the other way. The biggest single win is $D508–$D56D, a hundred bytes that decode as a coherent routine, and $CA3B–$CA5D, the tile-drawing routine. The three branch targets the reclassifier could not prove were turned into labels by _tools/resolve_raw_branches.py
  • Pass 2 (2026-10-20): a fresh map derived from this dump's own committed split: 206 routine entries and 519 internal branch targets, 931 Label_XXXX definitions gone, 51 raw $XXXX call operands resolved and 12 call targets the tracer had never labelled given a label. Zero SubC residue: the 185 entries the previous session had left as address-derived residue were all named from the code. Recorded in routinemap.tsv
  • Pass 3 (2026-10-20): 25 semantic zero-page aliases, each applied only where its role is proven (zp_aliases.inc); the slots that stay neutral are each listed with the reason. 35 data tables named — GameStateHandlerTable, EnemyBehaviourTable, EnemyScriptTable, EnemyTypePointerTable, SoundRoutineTable, NoteFrequencyTable and the rest — and recorded in data_region_names.tsv. apply_symbols.py reports 0 residue
  • Details: Mario Bros (JU)/README.md

33. Pyramid (U) (Sachen)

  • Folder: NROM/Pyramid (U) (Sachen)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv; the folder was renamed from NROM/Pyramid (U) on 2026-10-21 to match the inventory row)
  • ROM: Pyramid (U) (Sachen).nes (24,592 bytes), reached through the rom.nes symlink
  • Source: prg.s (8,253 lines; 3,130 instruction lines covering 6,493 code bytes = 39.6%; 463 labels, zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands, 3,762 canonical audit comments, 0 byte mismatches against prg.bin)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $D72E (NmiHandler), RESET → $FF00 (Reset), IRQ → $FF00 (the same address — sei is never undone, so the IRQ never fires)
  • Key subsystems: the unlicensed Sachen boot (sta $4100 mapper unlock with a delay loop at $FF4C, the "A"/"V" check on RAM $0120/$0121 at $FF57, the seed at $FF69, the clear at $FF74, the hand-off to the game's own entry at $C800); a task table of jmp trampolines that live inside the data regions ($C01E, $C02A, $C042, $C054) plus ten more at $C000–$C01B; two queued-event dispatchers that jump through the zero page with jmp ($0002) ($C3A3 with TaskVectorTable1 $C3A6, $CCCA with TaskVectorTable2 $CCD5); a VRAM command list assembled in the $0700 buffer and flushed by FlushVramCommandList; the actor grid at $0436 with the actor tables at $D320/$D4EE/$D5D5; a four-voice sound engine with its period, envelope and sample tables
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 aa285ff1…6c59e2)
  • Pass 1 correction (2026-10-20): the committed split was a strict subset of the correct one — 828 bytes of code were still marked as data, because the tracer cannot follow a jmp that sits inside a data region. Re-tracing with the sixteen jmp-table targets, the $C800 boot mainline and six further code starts seeded by hand recovers them (plus a five-byte stub at $DF89 in a hole between two routines), and the re-trace loses no committed code byte. make regen reproduces the split, so it stays verifiable
  • Pass 2 (2026-10-20): a fresh map derived from this dump's own committed split: 431 routine entries and the 32 data blocks named, 428 Label_XXXX definitions gone, 320 raw $XXXX call operands resolved. The internal branch-target names are derived mechanically from the branch that reaches them by _tools/derive_branch_names.py. Recorded in routinemap.tsv
  • Pass 3 (2026-10-20): 24 semantic zero-page aliases, each applied only where its role is proven (zp_aliases.inc); the 57 slots that stay neutral are each listed with the reason. 32 data tables named — TaskVectorTable1/TaskVectorTable2, LevelScriptData, MusicPeriodTable, SoundEnvelopeTable, the actor tables — and recorded in data_region_names.tsv. apply_symbols.py reports 0 residue
  • Residue: the zero page is reused heavily — 410 references still carry a neutral name, mostly the general-purpose scratch of the shift and arithmetic helpers. 482 absolute operands point at RAM and stay numeric. sta $4100 stays a raw operand: it is outside the $2000-$4017 range PROMPTS.md asks to be symbolic, and no hardware name would describe a mapper unlock
  • Details: Pyramid (U) (Sachen)/README.md

34. Raid on Bungeling Bay (U)

  • Folder: NROM/Raid on Bungeling Bay (U)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
  • ROM: Raid on Bungeling Bay (U).nes (24,592 bytes), reached through the rom.nes symlink
  • Source: prg.s (~14,300 lines; 255 SubC<addr> entry points, 612 Sub_<Role>_<addr> branch names, zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C04C (NmiHandler), RESET → $C000 (Reset → ResetEntry at $C6E3), IRQ → $C2C0 (IrqHandler)
  • Key subsystems: NMI frame loop with two paths (NmiPathSelector $C4: minimal vs full); state bitmap at $0200 dispatching on bits 0–3; PPU helper at $C006; sprite/OAM update at $C08E; palette update at $C4E4; main game logic at $C17A; PRNG at $C412; four computed indirect jumps at $E2EC / $E79D / $E7A0 / $E7A3
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 77285503…885000ac)
  • Pass 3 (2026-10-20): 11 semantic zero-page aliases added to locals.inc and applied at the proven sites. One of them was corrected while the [a2] sibling was finished: $EA had been named VBlankWaitCounter, but the routine at $C412 is the game's PRNG (the classic eor/asl/php/lsr/plp/rol scrambler, called thirteen times from gameplay code, twice in a row at $CDF4/$CDF9 with the second result masked #$07), so $EA is the scrambler's phase counter. Renamed PrngPeriodCounter, and $EB/$EC were named PrngSeedB/PrngState. Two sta a:IndDispatch17,y operands that were absolute stores to RAM $0017 were also corrected to a:Zp17,y
  • Details: Raid on Bungeling Bay (U)/README.md

35. Raid on Bungeling Bay (U) [a2]

  • Folder: NROM/Raid on Bungeling Bay (U) [a2]/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
  • ROM: Raid on Bungeling Bay (U) [a2].nes (24,592 bytes), reached through the rom.nes symlink
  • Source: prg.s (14,326 lines; 5,079 instruction lines covering 10,536 code bytes = 64.3%; 866 labels — 252 SubC<addr> entries + 610 Sub_<Role>_<addr> branch names — zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands, 5,467 canonical audit comments, 0 byte mismatches against prg.bin)
  • Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
  • Vectors: NMI → $C04C (NmiHandler), RESET → $C000 (Reset → ResetEntry at $C6E3), IRQ → $C2C0 (IrqHandler)
  • Key subsystems: same structure as row 34 — NMI frame loop with two paths, state bitmap at $0200, PPU helper at $C006, sprite/OAM update at $C08E, palette update at $C4E4, main game logic at $C17A, PRNG at $C412, four computed indirect jumps
  • Variant: a different build of the same game as row 34 — 150 of the 16,384 PRG bytes differ, in 7 runs, all of them code-versus-copyright-text at $C67D–$C6D8 and $C73B–$C779; the CHR differs too; header byte 6 is $00 (Horizontal) against row 34's $01 (Vertical). The zero-page reference sets are otherwise identical
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 659d340a1e9d420eee28df13319b0094)
  • Pass 3 (2026-10-20): 15 semantic zero-page aliases added to locals.inc and applied at the proven sites — every alias is applied only where its role is proven, and the addresses that carry two names keep the neutral name at the sites where the other role applies ($01 is PtrHi at the 16-bit compare and IndDispatch01 at the dispatch; $17 is IndDispatch17 at the dispatch and Zp17 for the absolute RAM $0017 store in the copy loop). The new _tools/apply_zp_aliases.py does the per-site substitution, because apply_symbols.py only rewrites numeric operands
  • Details: Raid on Bungeling Bay (U) [a2]/README.md

36. Urban Champion (JU)

  • Folder: NROM/Urban Champion (JU)/
  • ROM: Urban Champion (JU).nes (24,592 bytes)
  • Source: prg.s (~4,000 lines)
  • Linker: PRG at $C000, 16 KB; single segment
  • Vectors: NMI → $CA91 (NmiHandler), RESET → $CA00 (Reset), IRQ → $CA00 (reuses Reset)
  • Key subsystems: NMI-driven frame loop with simple fight game logic; minimal code (33.9%)
  • Build fix: None needed; byte-identical out of the box
  • Pass 3 symbols (2026-10-19): 70 operands substituted (4 single-name + 66 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
  • Details: Urban Champion (JU)/README.md

37. Xevious (U)

  • Folder: NROM/Xevious (U)/ (promoted out of _wip/NROM/Xevious (U)/)
  • ROM: Xevious (U).nes (32,768 bytes)
  • Source: prg.s (Pass 3; 868 labels)
  • Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
  • Vectors: NMI → $FC4E (NmiHandler), RESET → $FAF6 (Reset), IRQ → $FF1D (IrqHandler)
  • Key subsystems: NMI-driven frame loop with OAM DMA, PPU scroll/control latch, controller reading with shift register on $4016/$4017; two computed-dispatch mechanisms: jmp ($fe) through a 16-entry table at $BA8B (sprite attribute dispatch), jmp ($4) through a 64-entry table at $CA0A (object update dispatch); game mode state machine (title/game/demo) driven by GameMode ($10) and GameSubMode ($1B); object iteration, movement and drawing; sprite attribute packing into OAM
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp
  • Pass 1 correction: static trace from vectors reached only 13.6% of PRG. Declaring both jump tables via --table plus 92 hand-seeded entry points recovered code behind computed dispatch, reaching 34.5%. On 2026-10-21 the split was redone from the project's Mesen CDL with _tools/cdl_reclass.py: 1,158 bytes data→code, 48 code→data, 42 labels emitted, giving 12,455 code bytes (38.0%) and 6,002 instructions; the 45 recovered entries are named Sub_XXXX, so no Label_ remains
  • Pass 3 tables: 32 named data tables, including the $A74B-$B8AA block split into VramWritePtrTable, VramWriteData, DataStreamPtrTable, ObjTilePtrTable, ObjTileData and DataStreamData; the 4-entry pointer table at $D833; ObjSpeedTable/ObjSpeedTable2/SpriteLayoutPtrTable/SpriteLayoutData at $F957-$FAF5; PaletteData/OamAttrTable at $FEE6-$FF1C; and TextTileData at $F5D8 (font tile indices decoding to PLAYER, GAME OVER, READY, SOLVALOU, LEFT, PAUSE)
  • Residue: 20,313 bytes (62.0%) remain .byte data (pattern/graphics data at $8000-$A2BF, sprite attribute table at $BB55-$BEFA, streams at $ACFB-$B8AA, and miscellaneous small regions). Six CDL-silent raw call operands remain and five regions (Sub_C626, $D24B, Sub_D61B, Sub_D63E, Sub_EA9F) still decode as code although their bytes form tables; both are documented in the project README. Six addresses contain undocumented/illegal opcodes not decoded by the tracer: $9848, $A2C3, $CD89, $E0FF, $E3B5, $F230
  • Details: Xevious (U)/README.md

38. Zanac (U)

  • Folder: UNROM/Zanac (U)/ (promoted out of _wip/UNROM/Zanac (U)/)
  • ROM: Zanac (U).nes (131,072 bytes)
  • Source: prg.s + prg.07.s (Pass 3; bank 7 traced with 391 labels, banks 0-6 as raw data)
  • Linker: HEADER at $0000, PRG at $0010-$1C000, PRG7 at $1C010-$20000
  • Vectors: NMI → $CE8D (NmiHandler), RESET → $E7BF (Reset), IRQ → $CEC4 (IrqHandler)
  • Key subsystems: NMI-driven frame loop with OAM DMA, PPU scroll/control latch, controller reading with shift register on $4016/$4017; vertical scrolling shooter with attract mode; object iteration, movement and drawing; sprite attribute packing into OAM
  • Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 3. Promotion added header.s, chr.s, a HEADER/PRG/PRG7 linker.cfg, the rom.nes symlink and the whole-ROM cmp
  • Pass 1 correction: static trace from vectors reached only 37.9% of bank 7. Banks 0-6 remain as raw .byte data pending bank-switch analysis
  • Residue: ~65.5% of bank 7 remains .byte data. Seven addresses contain undocumented/illegal opcodes not decoded by the tracer: $D506, $D876, $E15B, $E44B, $E520, $E909, $F0FE
  • Details: Zanac (U)/README.md

39. Volleyball (U)

  • Folder: NROM/Volleyball (U)/ (promoted out of _wip/NROM/Volleyball (U)/)
  • ROM: Volleyball (U).nes (40,976 bytes)
  • Source: prg.s (Pass 3; 1,989 labels, all semantic — 730 read out of the code by hand, 1,221 internal branch targets derived mechanically)
  • Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
  • Vectors: NMI → $8053 (NmiHandler), RESET → $8000 (Reset), IRQ → $FFFF (not a handler — the last byte of the PRG image; the APU frame counter is never IRQ-enabled)
  • Key subsystems: the whole game runs from the NMI handler — the main loop at $81B5 only re-arms $DF and refreshes eight zero-page bytes. OAM shadow at $03FF uploaded by DMA, a VRAM update-script interpreter driven from a four-byte command block at $05C0-$05C3, controller reading with a shift register on $4016/$4017, a per-frame crowd animation, and an eleven-entry game-state dispatch table at $85E1 keyed by GameState ($2B) and GameSubState ($2C)
  • Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
  • Pass 1 correction: the static trace reached only 66% of the PRG image. Declaring the game-state dispatch table (--table 85E1:11) plus a Mesen Code Data Logger capture taken while a random-input bot played the attract demo promoted 1,757 further bytes from data to code, reaching 73.0% (11,395 instructions / 23,926 code bytes, 8,842 data bytes, 0 unclassified)
  • Verification: _tools/cdl_check.py cross-checks the finished prg.s against the CDL — 0 CDL-code bytes not covered by an instruction and 0 CDL-data bytes that start one. apply_symbols.py --report reports 0 residue; align_audit_comments.py reports no column drift
  • Residue: the ten copies of the per-nation player-movement and ball routines are named by their position in the ROM, not mapped to the ten selectable nations — the copies differ only in a few constants, so the mapping would need a per-copy behavioural trace. BallHitOffsetTable and the speed tables hold values whose exact meaning is still inferred from the surrounding code
  • Details: Volleyball (U)/README.md

_wip/ Projects

The pre-promotion tier is documented in WIP.md. It now holds 851 projects across 29 mapper folders:

Folder Mapper Projects
_wip/NROM/ 0 35
_wip/MMC1/ 1 221
_wip/UNROM/ 2 97
_wip/CNROM/ 3 57
_wip/MMC3/ 4 239
_wip/MMC5/ 5 10
_wip/MAPPER7/ … _wip/MAPPER232/ 7-232 192

All 851 build byte-identical for the whole ROM — the tier was moved off the old PRG-level-only compare on 2026-10-20, so the header and CHR are now proven for every project here, exactly as in the promoted tier. All 851 of them are Pass 0 skeletons: the folder shape and the build are proven, but prg.s is still a single .incbin "prg.bin". Volleyball (U) was the last project to leave the tier with a full disassembly: Pass 1 + Pass 2 + Pass 3, promoted to NROM/Volleyball (U) on 2026-10-21; Golf (JU) and World Class Track Meet (U) followed on 2026-10-21, promoted to NROM/Golf (JU)/ and CNROM/World Class Track Meet (U)/ respectively.

Two things are worth knowing before touching a _wip/ project:

  • Most of the tier is a banked mapper with a PRG image larger than the 6502's address space. Only two projects have a 16 KB PRG; 149 have 32 KB, 522 have 128 KB and one (Action 52 (U) [!]) has 1.5 MB. Those projects link their MEMORY areas at file offsets rather than CPU addresses, which is both the only option and the honest model. See "Two linker layouts" in WIP.md.
  • 226 projects have no CHR at all — the mapper supplies CHR RAM.

The tier is deliberately not built by the root Makefile's all/clean/ <MAPPER> targets — MAPPERS names only the promoted mapper folders. The pre-promotion tier has its own explicit targets:

make wip          # build + verify every _wip/<MAPPER>/<Project>/
make wipclean     # clean the build artifacts in the tier

Both are driven by WIP := _wip at the top of the root Makefile; without that variable the loop expands to for m in /*/, which walks the filesystem root instead of the tier.

(The old manual loop, for d in _wip/*/*/; do make -C "$d"; done, still works as an equivalent.)

Promotion is now just git mv plus the disassembly work: the whole-ROM build, the header.s/chr.s sources, the HEADER/PRG/CHR linker.cfg and the rom.nes copy are already in place. No _tools path change is needed, because both tiers sit two levels deep, so ../../_tools/ is correct either way. Lunar Pool (U), Donkey Kong (JU), Popeye (JU) (PRG 1), Raid on Bungeling Bay (U), Pac-Man (U), Raid on Bungeling Bay (U) [a2], Pac-Man (Tengen) (U), Pyramid (U) (Sachen), Hogan's Alley (JU) and Mario Bros (JU) (all 2026-10-20) went through exactly that and came out whole-ROM byte-identical on the first promoted build. Xevious (U) and Zanac (U) followed on 2026-10-20, Mermaids of Atlantis (U) on 2026-10-20, and Volleyball (U) on 2026-10-21.

git mv only moves the tracked files, so the old _wip/ folder survives with its untracked build artifacts (*.o, reconstructed.nes, reconstructed.lbl, reconstructed.map) and sometimes with a stale README.md left behind. Delete the leftover folder — otherwise it counts as a project in every tier tally while having no source to build. Xevious (U) and Zanac (U) both left one behind on 2026-10-20; both were cleaned up on 2026-10-21.

Notable vector/header observations for Pass 1 work:

  • Pac-Man (U) RESET at $FF00 — the vector-page tail, but not padding: $FF00 holds real boot code (sei/cld, PPU off, double vblank wait, jmp ColdStart at $C042). The Tengen variant RESETs at $C033 and has no boot code at $FF00 at all (that region is $FF padding) — the same boot sequence is inline at $C033. The two PRGs differ in 56 bytes in 8 runs, all of them code-versus-licensee-text.
  • Lunar Pool (U) NMI $FF65 / IRQ $FF64 are adjacent in the vector page; RESET $E80C.
  • NES PowerPad Test Card (U) — at Pass 2/3: minimal code (~7.2%), data-heavy test cartridge. RESET at $E000 (non-$C000 entry). NMI handler reads controllers via shift register, processes pad transitions, draws score/lives. See NES PowerPad Test Card (U)/README.md.
  • Lunar Pool (U) — Pass 2 and Pass 3 complete; promoted to the top level 2026-10-18: RESET at $E80C (not $C000), NMI $FF65, IRQ $FF64 (a bare rti just before the NMI handler, so IRQs are ignored). There is no jmp ($7961) RAM-pointer gate (an earlier claim): those three sites fell out of decoding two bytes into the word "player". $CBDC/$CBC9 is a print-inline-string-and-return-after-it helper, so a jsr $CBDC is always followed by a $81-prefixed, $00-terminated string ("player", "shot", "game over", "hiscore__", "perfect_"). The split was re-derived from a Mesen CDL capture (10,028 bytes Code): now **5,300 instructions / 11,077 bytes (67.6%)**, 5,301 data bytes and the six vector bytes as .word. Pass 2 named all **705** labels — Label_is gone from the file — and Pass 3 named 33 tables plus the zero-page aliases (38 semantic, 66 neutral, ten former phantom aliases deleted). Residue, recorded rather than guessed: 73 bytes of *reachable* code are still.byte ($EA9A, $EADC, $EAE5, $EAED, $EB04, $EB16-$EB4F— the CDL capture never fetched them), another 75 bytes of ending-screen code sit at$F5F9-$F643, and ~206 bytes of unreached-but-clearly-code stubs stay data. The full 24,592-byte ROM (header + PRG + CHR) rebuilds byte-identically. See Lunar Pool (U)/README.md`.
  • Ice Climber (JE) vs (U): byte-identical PRG and header — only the CHR differs (~regional title graphic).
  • Popeye (JU) PRG 0 vs PRG 1: different PRG binaries (and mirroring); same vectors.
  • Raid on Bungeling Bay (U) vs [a2]: [a2] differs in mirroring only per header, but PRGs differ — separate builds.
  • Pyramid (U) (Sachen) — promoted 2026-10-20: the unlicensed Sachen boot pokes a mapper unlock at $4100, checks the RAM bytes $0120/$0121 against "A"/"V", and dispatches through two queued-event tables with jmp ($0002). It also dispatches through jmp trampoline tables that live inside the data regions — 828 bytes of code that the tracer could not reach were recovered by hand. See NROM/Pyramid (U) (Sachen)/README.md.
  • CIRCUS — at Pass 2/3: full recursive disassembly complete. NMI-driven frame state machine (main loop is a spin loop at $C057). Menu text at $C763 ("CONTINUE", "STAGE", "SELECT", "PLAY"). Object state machine at $DC3F–$FE7B. Audio sequence data at $FABB–$FFFB. See CIRCUS/README.md.
  • Mermaids of Atlantis (U) — promoted 2026-10-20, rebuilt 2026-10-21: mapper 8 (MMC3) with 64 KB of PRG, so the PRG is eight 8 KB banks and two of them can be visible at the same CPU address. The image carries the reset stub and the vector table twice: at file $7FFA (the fixed bank) the NMI vector is $808F — that is the live one, and $808F is the frame handler — while the copy at file $FFFA names $8189, which is a BRK in the first half of the image. The fixed bank is the fourth 8 KB bank ($6000-$7FFF), not the last one, which is why the game's text table lives at CPU $F1D6: that is the fixed window, and the code reads it there. Mesen maps the fixed bank the same way, and the dump's own code is what settles it. The disassembly therefore has one segment per bank (PRG0..PRG7), each with its own .org for the CPU window, and banks 4 to 7 carry a Bank4_..Bank7_ label prefix. See MAPPER8/Mermaids of Atlantis (U)/README.md.
  • Joypad Test Cartridge (U) — Pass 3 complete: minimal code (23.4%), data-heavy test cartridge. Data region $CF06–$FFFF broken into 20 named sub-blocks; VRAM command stream opcode set decoded via RetAddrUpdate return-address modification trick at $CDC8. See Joypad Test Cartridge (U)/README.md.
  • Wild Gunman (U) — Pass 1 redone, Pass 2/3 complete: NMI-driven frame loop. Gates its code behind runtime computed-goto tables — see the prg.s header block and its README.md.
  • Mario Bros (JU) — Pass 1 corrected, Pass 2/3 complete, promoted 2026-10-20: the engine's handler tables sit inline, right after the jsr that reads them, so the static tracer could not follow them. A Mesen Code Data Logger capture showed 1,067 bytes the tracer had left as data were code, taking the split from 72.0% to 78.4%. Pass 2 named every label (zero Label_, zero SubC) and Pass 3 added 25 semantic zero-page aliases and named 35 data tables. Code is gated behind stack-based indirect dispatch at $CD9E and a 20-entry JSR thunk table at $C5A3. Audio routines in $F8xx-$F9xx clearly identifiable from APU register writes. See NROM/Mario Bros (JU)/README.md.

Common Patterns Across All Projects

Memory Map

Every project uses a single 16 KB PRG bank mapped at CPU $C000–$FFFF, with 8 KB CHR. All builds are NROM (no bank switching).

Interrupt Structure

All projects follow the same NES interrupt pattern:

  • NMI fires once per frame and is the real-time heartbeat — handles OAM DMA, PPU updates, controller reading, and audio.
  • RESET performs cold-start hardware init, RAM clearing, and enters the main loop.
  • IRQ is almost always unused (either rti or a self-loop).

Two exceptions worth noting from branches of this family:

  • Excitebike uses a state-dispatch table at $C000 rather than a conventional inline main loop, and its IRQ vector points into a data region (unused).
  • Donkey Kong Jr. is the extreme case: its reset path idles forever in a PRNG-advance loop, and the entire frame state machine (title, attract, gameplay, sound) executes inside the NMI handler itself. Its reset entry is also at $C66E rather than $C000.

Build Toolchain

All projects use the same toolchain:

  • ca65 (6502 assembler)
  • ld65 (linker with .cfg memory map)
  • All rebuilds are verified byte-identical to the original prg.bin / ROM PRG bank.

Disassembly Style

All sources are "Pass-1" style disassemblies:

  • Every instruction annotated with PRG offset, CPU address, and emitted bytes
  • Inline .byte/.word/.res data blocks interleaved with code
  • Address-based labels where semantics are not yet resolved: Label_Cxxxx (unrenamed internal targets), SubC<addr> / Sub_Cxxxx (unnamed entry points), <Routine>_Block[_n] (internal blocks under a named parent routine)
  • Zero-page symbol files (locals.inc) and hardware symbol files (symbols.inc)

Navigation

Each project is a flat folder under its mapper directory — e.g. NROM/Balloon Fight (JU)/ — containing:

  • prg.s — disassembly source; header.s, chr.s and the raw header.bin / chr.bin / prg.bin splits (where present)
  • symbols.inc, locals.inc — hardware constants and application symbols
  • linker.cfg, Makefile — memory map and build script
  • rom.nes — space-free copy/symlink of the original ROM used by the compare
  • README.md — detailed per-project power-on execution flow analysis

To rebuild any one project:

cd /home/tmerritt/Projects/disasm/NROM/<Project>
make

To build and verify every project at once (all mapper directories):

cd /home/tmerritt/Projects/disasm
make          # all projects, all mappers
make clean    # clean them all
make MMC3     # one mapper tier only
make wip      # the pre-promotion tier under _wip/

The root Makefile covers the promoted tier only — make, make clean and make <MAPPER> never touch _wip/. The pre-promotion tier under _wip/ is built explicitly with make wip (and cleaned with make wipclean):

for d in _wip/*/*/; do make -C "$d"; done   # equivalent manual loop

See WIP.md for the _wip/ tier's layout, its quirks and its open work.

Pass 1 methodology note (2026-10-16)

The original Pass 1 disassembler had two limitations that silently understated code coverage. Both are worth knowing before trusting a coverage percentage:

  1. Documented opcodes only. Its table held the 151 documented 6502 opcodes. These ROMs also use the 54 undocumented opcodes and the 26 unofficial NOPs as 2/3-byte padding; a tracer that halts on them strands the real code behind.
  2. No runtime dispatch. It followed only vectors and direct jsr/jmp/branch targets. Games here dispatch through computed jumps — jmp ($0014), the pla-based inline-table gotos in Wild Gunman (Label_C341), and task tables like Donkey Kong Jr.'s DeferredTaskHandlerTable at $BFFE.

Effect measured per project (old tracer → complete-opcode dispatch-aware tracer):

Project Old Complete Action taken
NES PowerPad Test Card (U) 546 instr 559 Pass 1 already sound
Joypad Test Cartridge (U) 282 instr 1,773 Pass 1 redone (23.4% code); Pass 2 complete; Pass 3 complete
Wild Gunman (U) 1,600 instr 4,083 Pass 1 redone (49.3% code)
Balloon Fight (JU) 5,216 instr 5,277 hand-done file was already better
Donkey Kong Jr. (JU) 6,135 instr 6,135 file already complete

Joypad Test Cartridge (U) was the last project carrying the old, truncated Pass 1, and has now been redone. Its recorded "3.5% code" was really 23.4%: the tracer stopped at $C09E on DCP $3C20 ($CF), an undocumented opcode used as ordinary code, and 3,256 bytes of real code were filed as .byte data. Redoing it also invalidated its Pass 3, which had described $C09E–$C173 and $C17F–$CCF6 as data — both are code. Pass 3 is now the outstanding work.

The fix generalises: nesdis.py --undocumented decodes all 105 undocumented NMOS opcodes. It is default off so that projects whose prg.s is already regen-stable keep reproducing byte-for-byte under make regen.

_tools/verify_pass1.py checks the top-level projects — it selects the project folders under each mapper directory (NROM/, AOROM/, CNROM/, MMC1/, MMC3/, MMC5/, UNROM/) that carry a Makefile and a prg.bin/rom.nes, so _wip/ projects are not covered (they are checked by plain make, now at the whole-ROM level). Current run, 2026-10-20: all 35 NROM/ projects build, all canonical, and no truncated or unfaithful Pass 1. The last two carryovers are gone — Joypad Test Cartridge, the last project holding an old truncated Pass 1, was redone, and Excitebike, the last source with uncommented instructions, was commented.

The comment-spelling report used to claim that no project follows the canonical ; CPU:$xxxx PRG:xxxx AA BB convention. That was a bug in the checker, not a fact about the sources: the canonical pattern ends with $ but was compiled without re.MULTILINE, so it could only ever match once — at end of file — and every project fell through to whichever laxer spelling matched most lines. Fixed with re.M, the true split was 8 canonical / 3 pipe / 2 short / rom / bytes / colon / slash; the 2026-10-19 standardization (_tools/audit_comment_tool.py over 9 projects, plus hand fixes to CIRCUS and Excitebike) closed it out, so the checker now reports all canonical.

Inside _wip/, none of the 851 projects have instructions to comment at all — they are all Pass 0 skeletons. (Golf (JU) and World Class Track Meet (U) used to be the two exceptions, but both were promoted on 2026-10-21 and their comments are canonical.) (Xevious (U), which used to be the second project in the tier with instructions, was promoted to NROM/ on 2026-10-20.)

The old claim that "Excitebike and Pac-Man carry no byte comments at all" is stale on both counts. Pac-Man (USA) (Namco) is complete (4,695/4,695 instructions commented), and Excitebike's 1,013-line gap was closed on 2026-10-19 — all 5,376 instruction lines now carry a canonical comment.

The earlier-reported re-trace crash on MUSCLE (U) / Donkey Kong Jr. (JU) (ValueError: invalid literal for int() with base 16: ':$0010') was a false alarm: nesdis.operand_value() already strips the emitter's a: prefix via token.removeprefix("a:").lstrip("$"), so re-tracing all promoted projects is clean.

Resolved — audit comments for Excitebike and Pac-Man (2026-10-19)

Both were hand-written sources with semantic labels but no byte-identity audit trail. Both now carry canonical ; CPU:$xxxx PRG:xxxx AA BB comments on every instruction, and verify_pass1.py reports all-canonical across the top level, so this section is closed.

The ca65 -l listing route described here was abandoned, for the reason recorded in AGENTS.md: the listing carries no source line numbers, so entries cannot be keyed back to source lines. The comment tooling went through the tracer instead (_tools/audit_comment_tool.py, tracer as ground truth). The invariant still holds and is the check to keep: after inserting comments, make must still print Byte-identical ROM verified., and each comment's byte list must match prg.bin at the stated offset — a wrong offset that still assembles is the failure mode.

Summary

Thirty-nine projects sit under NROM/, and all 39 rebuild byte-identical to their original ROMs (rows 1-27 below plus row 29 Hogan's Alley (JU), row 30 Mario Bros (JU), row 31 Pac-Man (Tengen) (U), row 32 Pac-Man (U), row 33 Pyramid (U) (Sachen), rows 34 and 35 Raid on Bungeling Bay (U) and Raid on Bungeling Bay (U) [a2] — all promoted 2026-10-20 — and rows 36 and 37 (Urban Champion and Xevious (U)) which kept their tail numbers when they were promoted; row 7 Excitebike (JU) was fixed on 2026-10-20 — the byte-596 mismatch was two $0A/$11 PPU-mask-shadow operands, see NROM/Excitebike (JU)/README.md).

The pre-promotion tier holds 851 projects under _wip/, and as of 2026-10-21 all 851 verify byte-identical for the whole ROM as well (make wip builds and verifies the whole tier: 851 of 851 passed, 0 failures). None of the 851 carry a real disassembly — they are all Pass 0 skeletons; Golf (JU) (row 28) and World Class Track Meet (U) (row 41) were promoted from this tier on 2026-10-21. The whole tier — its layout, its quirks and its open work — is documented in WIP.md. Folder locations changed on 2026-10-20 (mapper directories, flat project folders), but each row's build-status claim in this table is the state at its own promotion; verify against the tree with make if in doubt.

# Project Build Status Pass 3
1 Balloon Fight (JU) BYTE-IDENTICAL complete; symbols applied 2026-10-19 (16 $13 operands left numeric)
2 Baseball (UE) BYTE-IDENTICAL complete; symbols applied 2026-10-19 (121 operands)
3 Bomberman (U) BYTE-IDENTICAL complete
4 Burger Time (U) BYTE-IDENTICAL complete
5 Clu Clu Land (JU) BYTE-IDENTICAL complete
6 Defender 2 (U) BYTE-IDENTICAL complete
7 Excitebike (JU) BYTE-IDENTICAL complete (Pass 2/3 complete); byte-596 $0A/$11 mask-shadow fix + audit-trail re-anchor + 58 jsr/jmp operands symbolized 2026-10-20
8 Tennis (JU) BYTE-IDENTICAL complete; symbols applied 2026-10-19 (18 operands)
9 Pac-Man (USA) (Namco) BYTE-IDENTICAL complete; symbols applied 2026-10-19 (524 operands; 727 multi-alias residues)
10 Donkey Kong 3 (JUE) BYTE-IDENTICAL complete
11 Donkey Kong Jr. (JU) BYTE-IDENTICAL complete (Pass 1 verified)
12 CIRCUS BYTE-IDENTICAL complete; symbols applied 2026-10-19 (118 operands; 23 multi-alias residues)
13 Wild Gunman (U) BYTE-IDENTICAL complete (Pass 1 redone); symbols applied 2026-10-19 (76 operands)
14 Joypad Test Cartridge (U) BYTE-IDENTICAL Pass 3 complete; symbols applied 2026-10-19 (47 operands)
15 NES PowerPad Test Card (U) BYTE-IDENTICAL complete; symbols applied 2026-10-19 (89 operands)
16 MUSCLE (U) BYTE-IDENTICAL complete; symbols applied 2026-10-19 (220 operands)
17 Lunar Pool (U) BYTE-IDENTICAL complete (tables named); symbols applied 2026-10-19 (45 operands)
18 Donkey Kong (JU) BYTE-IDENTICAL complete (Pass 2/3, promoted 2026-10-19); symbols applied 2026-10-19 (75 operands)
19 Donkey Kong Jr. Math (U) BYTE-IDENTICAL complete (Pass 3 complete); promoted into NROM/ 2026-10-20 after fixing the mislabeled SubCF218 call sites
20 Duck Hunt (JUE) BYTE-IDENTICAL complete (Pass 3 complete)
21 Ice Climber (JE) BYTE-IDENTICAL complete (Pass 3 complete)
22 Ice Climber (U) BYTE-IDENTICAL complete (Pass 3 complete)
23 Lode Runner (U) BYTE-IDENTICAL complete (Pass 2/3 complete)
24 Pinball (JU) BYTE-IDENTICAL complete (Pass 2/3 complete)
25 Millipede (U) BYTE-IDENTICAL complete (Pass 2/3 complete, 74.6% code)
26 Popeye (JU) (PRG 0) BYTE-IDENTICAL complete (Pass 2/3 complete, 72.3% code)
27 Popeye (JU) (PRG 1) BYTE-IDENTICAL complete (Pass 2/3 complete, 72.3% code); promoted 2026-10-20
28 Golf (JU) BYTE-IDENTICAL complete (Pass 1+2+3 complete; promoted from _wip 2026-10-21; 4,217 instructions / 13,541 lines; 0 residue)
31 Pac-Man (Tengen) (U) BYTE-IDENTICAL partial (Pass 2 complete, Pass 3 partial — 30 zero-page aliases, 28 named data tables, 0 residue, 20.0% code); promoted 2026-10-20
32 Pac-Man (U) BYTE-IDENTICAL partial (Pass 2 complete, Pass 3 partial — 119 operands, 0 residue); promoted 2026-10-20
34 Raid on Bungeling Bay (U) BYTE-IDENTICAL partial (Pass 2/3 partial, 64.6% code); promoted 2026-10-20
33 Pyramid (U) (Sachen) BYTE-IDENTICAL partial (Pass 2 complete, Pass 3 partial — 24 zero-page aliases, 32 named data tables, 0 residue, 39.6% code); promoted 2026-10-20
35 Raid on Bungeling Bay (U) [a2] BYTE-IDENTICAL partial (Pass 2 complete, Pass 3 partial — 15 zero-page aliases, 0 residue, 64.3% code); promoted 2026-10-20
30 Mario Bros (JU) BYTE-IDENTICAL partial (Pass 2 complete, Pass 3 partial — 25 zero-page aliases, 35 named data tables, 0 residue, 78.4% code); promoted 2026-10-20
29 Hogan's Alley (JU) BYTE-IDENTICAL partial (Pass 2 complete, Pass 3 partial — 60 semantic zero-page aliases, 34 named data tables, 0 residue, 49.1% code); promoted 2026-10-20
36 Urban Champion (JU) BYTE-IDENTICAL complete; symbols applied 2026-10-19 (70 operands)
37 Xevious (U) BYTE-IDENTICAL complete (Pass 3 complete, 38.0% code; 143 semantic entry points, 32 named data tables, ~20 semantic ZP aliases; split corrected from Mesen CDL 2026-10-21)
38 Zanac (U) BYTE-IDENTICAL complete (Pass 3 complete, 34.5% code; 133 semantic entry points, 26 named data tables, 14 semantic ZP aliases)
39 Volleyball (U) BYTE-IDENTICAL complete (Pass 3 complete, 73.0% code; 1,989 semantic labels, 37 named data blocks, 0 residue; promoted 2026-10-21)
40 Mermaids of Atlantis (U) BYTE-IDENTICAL mapper 8; Pass 3 complete (12.3% code, 494 named routines, 13 semantic zero-page aliases; 8 banked segments; rebuilt 2026-10-21)
41 World Class Track Meet (U) BYTE-IDENTICAL complete (Pass 1+2+3 complete; promoted from _wip 2026-10-21; 8,400 instructions / 18,028 code bytes, 55.0% code; 24 semantic ZP aliases, 78 neutral ZpXX with reasons; 0 residue)
42 Slalom (U) USA 32 KB
43 Kung Fu (U) USA 32 KB
44 Othello (U) USA 32 KB
45 Elevator Action (U) USA 32 KB
46 1942 (JU) Japan 32 KB
47 Tag Team Wrestling (U) USA 32 KB
48 Galaga (U) USA 32 KB
49 Kung Fu (U) (a1) USA 32 KB
50 Stack-Up (JU) Japan 32 KB
51 Magmax (U) USA 32 KB
52 Ms Pac-Man (Namco) (U) USA 32 KB
53 Soccer (JU) Japan 32 KB
54 Sqoon (U) USA 32 KB

Row 28 (Golf (JU), now promoted to NROM/Golf (JU)/) rebuilds byte-identical at the whole-ROM level. Row 41 (World Class Track Meet (U), now promoted to CNROM/World Class Track Meet (U)/) rebuilds byte-identical as well. The other 851 _wip/ projects are Pass 0 skeletons and need Pass 1 from scratch. See WIP.md. Use _tools/verify_pass1.py to re-check any of this at any time; it rebuilds each project and re-traces it, and reports TRUNCATED when a project's committed split claims less code than the tracer can reach.

Reference in new issue View Git Blame Copy Permalink
S
Description
No description provided
Readme
534 MiB
0 Stars 1 Watchers 0 Forks
Languages
Assembly 95.5%
POV-Ray SDL 2.9%
PHP 0.6%
Makefile 0.5%
Python 0.4%