tmerritt/disasm
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9eb04ea7ef9d632b6b094498fb691b02be906ece
disasm/Urban Champion (JU)/OVERVIEW.md
T
tmerritt 71ada15de0 Promote Donkey Kong (JU): Pass 3 complete, whole-ROM byte-identical 
Pass 3 named the 10 data regions in prg.s, then the project was promoted
out of _wip/ so `make` now proves header + PRG + CHR against the original
ROM instead of only the PRG bank.

Data regions named:
  LevelPtrTable        $C000-$C03B  (60 B)    level header data
  ObjectPtrTable       $C03C-$C043  (8 B)     4 pointer pairs
  LevelDataPtrTable    $C044-$C79D  (1882 B)  level data pointers
  SpriteInitPtrTable   labelled at $C4B0      see residue note
  UnreachedCode_D650   $D650-$D696  (71 B)    unreached code
  UnreachedCode_E144   $E144-$E165  (34 B)    unreached code
  MusicDataTable       $F55B-$FA47  (1261 B)  music/sound data
  APUDataTable         $FAE6-$FB74  (143 B)   APU pulse/noise tables
  SfxDataTable         $FE59-$FFEF  (407 B)   sound-effect data
  VectorTable          $FFF6-$FFFF  (10 B)    padding + NMI/RESET/IRQ

Promotion (per the AGENTS.md checklist):
  - git mv "_wip/Donkey Kong (JU)" "Donkey Kong (JU)"
  - add copilot/rom.nes -> ../Donkey Kong (JU).nes symlink
  - add header.s / chr.s (one-line .incbin of header.bin / chr.bin)
  - linker.cfg gains HEADER ($0000/16 B) and CHR ($0000/8 KB)
  - Makefile switched from `cmp reconstructed_prg.bin prg.bin` to
    `cmp reconstructed.nes rom.nes`
  - no _tools path change (this Makefile never referenced _tools/)
    and no `make regen` pipeline exists for it

Doc corrections:
  - project OVERVIEW.md said Mirroring Vertical; header byte 6 = $00
    means Horizontal (the root index was right) — fixed
  - root OVERVIEW.md: row 18 now BYTE-IDENTICAL, tier paragraph and
    summary table refreshed (they had drifted around the Lunar Pool and
    Urban Champion promotions), new per-project detail entry
  - counts corrected to 19 top-level / 17 _wip in OVERVIEW.md,
    TODO.md and AGENTS.md

Residue recorded rather than guessed:
  - Pass 2 is partial: 919 Label_ definitions remain (214 semantic
    labels applied); noted in TODO.md so nobody reads the promotion as
    full semantic naming
  - SpriteInitPtrTable's label sits at $C4B0: the routine at $C807 reads
    $C4A7,x/$C4A8,x, but that table starts mid-row and a label there
    would split the canonical 16-byte audit-comment line

Verification:
  make clean && make  -> "Byte-identical ROM verified."
  verify_pass1.py     -> 19/19 top-level build, Donkey Kong (JU) OK
                         (6014 instr / 12505 B), all comments canonical

Doc-drift sweep: build tiers, mirroring, and stale status tails

Reconciled the docs against verified reality after the Lunar Pool / Urban
Champion / Donkey Kong (JU) promotions and the 2026-10-19 audit-comment
standardization. No source behaviour changed except the two build fixes below.

Build tier (whole-ROM vs PRG-only)
  - AGENTS.md: the 17 `_wip/` projects are real disassemblies at the PRG-build
    tier, not "skeletons"; header.s/chr.s/rom.nes are promotion additions;
    verify_pass1.py covers the top-level projects.
  - Root OVERVIEW.md: `_wip` prose, audit-comment narrative and summary table
    refreshed (37.5% figure, SEEDED vs OK wording, re-trace false alarm).
  - Promoted projects whose build blocks still claimed `make` emits
    `reconstructed_prg.bin` compared to `prg.bin` (Balloon Fight, Baseball,
    CIRCUS, Clu Clu Land, Excitebike, NES PowerPad, Pac-Man (USA), Tennis):
    now describe the whole-ROM `reconstructed.nes` vs `rom.nes`.
  - Lunar Pool / Urban Champion / CIRCUS also had stale `cd "_wip/..."`
    build paths and "Promotion" items; retargeted to their top-level folders.

Mirroring (header byte 6 bit 0: 0 = Horizontal, 1 = Vertical)
  - Corrected DK Jr. prose "horizontal mirroring (flag 6 = $01)" -> vertical,
    and both `_wip/Pac-Man` variant notes "Both use vertical mirroring" ->
    horizontal (both are byte-6 = $00).
  - Re-audited every project OVERVIEW: 0 rows and 0 prose claims now disagree.

Stale status tails
  - Retitled/restatused the `_wip` OVERVIEWs to their real `prg.s` (Golf,
    Ice Climber (U), Lode Runner, Millipede, Pac-Man Tengen, Pac-Man (U),
    Popeye 0/1, Raid, Raid a2, Hogan's Alley, Mario Bros); Golf's
    skeleton-era contents rows and Next Steps corrected.
  - Dropped the skeleton-era "## Next Steps (per `PROMPTS.md`)" heading and
    the "(from the skeleton)" wording across all project OVERVIEWs.
  - Rewrote Lunar Pool / Urban Champion Next Steps (both already Pass 1-3
    complete and promoted; their tails still described pending Pass 2 and
    promotion); fixed root row 13 (Wild Gunman) and row 20 (Duck Hunt).

Also lands two code fixes carried with this sweep:
  - `_wip/Hogan's Alley (JU)`: $E9F1-$E9FD and $EA13-$EA14 reclassified as
    data with canonical audit comments (the seeded build had decoded a data
    table base as code, breaking the build since 2ae09f7). `make` ->
    BYTE-IDENTICAL again; reconstructed_prg.bin/.lbl refreshed.
  - `_wip/Pyramid (U)`: `Label_D72E` -> `NMI:` (byte-identical).

Verification:
  make (Hogan's Alley, Pyramid)      -> BYTE-IDENTICAL, BYTE-IDENTICAL
  _tools/verify_pass1.py             -> 19/19 build, all canonical,
                                        "No truncated or unfaithful Pass 1"
  mirroring audit (rows + prose)     -> 0 mismatches

Donkey Kong (JU): complete Pass 2 — all 919 Label_ definitions named

The last non-zero Label_ residue in the repo is now gone. Every one of the
919 address-derived definitions in copilot/prg.s is replaced:

* 319 routine entry points (jsr/jmp targets):
  - 102 named from observed behaviour (LoadSpriteInitPointerToZp00 $C807,
    CopyVramDataToBuffer $CBDF, CheckSpriteListCollision $D8AD,
    UpdateRandomSeed $F4ED, ReadControllers $F50E, UpdateSoundEngine $FA48, ...)
  - 217 left as SubC<addr> — honest residue where the body is too
    context-dependent to name without guessing (Golf: 108, Mario Bros: 223)
  - the 77 already-named entries untouched
* 600 internal branch targets named <Routine>_Block / <Routine>_Block_n in
  address order within their owning routine (DK Jr./Balloon Fight convention).
  Ownership is control-flow containment, so a loop that physically precedes
  its own entry lands correctly (FlushPpuBuffer_Block $F1EC under $F228).
* Two proposal collisions disambiguated by indexing zero-page slot:
  UpdateObjectListZp5D/DispatchObjectStateZp5E ($DA16/$DA4C) vs
  UpdateObjectListZpAE/DispatchObjectStateZpAF ($E1E9/$E250).

jsr/jmp operands stay numeric (Wild Gunman style); only branch operands are
symbolic. Applied with _tools/pass2.py apply (919 defs + 2,622 refs rewritten,
comments re-aligned); the ROM still rebuilds byte-identically and
verify_pass1.py reports 19/19 canonical with no truncated split.

Docs synced: project OVERVIEW.md gains a Pass 2 Details section, root
OVERVIEW.md rows + conventions, TODO.md section 4 closed. dk_full_map.tsv now
records the complete applied map (its zp rows remain unapplied proposals).

_wip status correction: five false "Pass 2 complete" claims + map audit

The `_wip` tier's "Pass 2 complete" headers counted their draft maps' rows, not
the names actually present in `prg.s`, and described the count of *neutral*
`ZpXX` slots in `locals.inc` as "zero-page semantic aliases". Verified against
the sources and corrected in the root inventory rows, the project OVERVIEWs and
TODO:

  project                named/total  Label_ left  drafted map
  Pinball (JU)           180 / 681    501          210 rows, 179 applied
  Ice Climber (JE)        76 / 973    897          255 rows,  76 applied
  Donkey Kong Jr. Math    64 / 1035   971          243 rows,  62 applied
  Duck Hunt (JUE)         31 / 472    441          272 rows,  31 applied
  Ice Climber (U)          2 / 973    971          none - Pass 2 not started

No `_wip` project is Pass 2 complete. Ice Climber (U) was the worst case: the
2026-10-19 sweep itself restated it "Pass 2 complete" while describing its 971
`Label_` definitions in the same paragraph - a copy-paste from (JE); (U) has no
map file at all.

Drafted maps audited row by row against the committed split: they are not
applicable. 100/243 (DK Jr. Math), 96/255 (Ice Climber (JE)) and 17/210
(Pinball) rows point at addresses that are not instruction boundaries - they
were built against an older code/data split - while most of the rest are
unlabelled boundaries that no operand references, or (Duck Hunt) competing
candidate names for one label (`Label_C2BF` alone carries 205). Rows that are
both insertable and corroborated by control flow: 0 in every map. Recorded as
stale and kept for provenance; Pass 2 here needs a fresh map derived from the
committed split.

Also corrected while verifying:
- Mario Bros entry counts (docs said 252 / 90 + 165 / 477 sites / 156 neutral
  slots; the file holds 262 distinct `jsr`/`jmp` targets = 39 semantic + 223
  `SubC<addr>`, 478 sites, 151 slots).
- root `_wip` prose line/label ranges (4,482-17,180 lines, 192-971 `Label_`,
  11,126 total) and the Ice Climber code figure (74.6% / 6,112 instr, not
  74.7% / 6,113).
- TODO §4 re-scoped to the promoted tier, with the `_wip` residue table added.

Verification: `make` across all 17 `_wip` projects -> BYTE-IDENTICAL (17/17);
`_tools/verify_pass1.py` -> 19/19 build, all canonical, "No truncated or
unfaithful Pass 1 found". No source bytes changed.

Balloon Fight (JU): apply locals.inc/symbols.inc names to prg.s (Pass 3)

Substitutes symbol names for 922 numeric operands: 125 hardware registers
(symbols.inc) and 797 of 813 zero-page/RAM operands (locals.inc). The 15
multi-alias addresses were resolved per routine; 16 operands stay numeric
because $13 is used there as a plain high-byte scratch beside Temp12 and
none of its three aliases fits.

- _tools/apply_symbols.py: the substitution tool (dry run by default;
  --sites supplies per-routine choices for multi-alias addresses, --report
  lists the residue). Only the operand token is rewritten, so the
  `; CPU:$.... PRG:....  XX XX` audit comments survive byte for byte.
- prg.s: operand tokens only. make prints "Byte-identical ROM verified."
- OVERVIEW.md (project): instruction quotes now match prg.s, new
  alias-reuse table, and section 10 rewritten from the stale "497 Label_"
  prose to the real naming state and the 16-site residue.
- OVERVIEW.md (root), TODO.md, AGENTS.md: status, counts, tool list.

verify_pass1.py: 19/19 OK, all audit comments canonical.

Bomberman (U): apply locals.inc/symbols.inc names to prg.s (Pass 3)

Substitutes 362 zero-page operands in copilot/prg.s with the names already
declared in copilot/locals.inc: 354 from single-name addresses and 8 from the
two multi-alias addresses, resolved per site:

  $E0/$E1  IndirectPtrLo/Hi in the RAM-clear loop
              (InitializeSystemAndRunMainLoop -> Main_WriteSoundDispatchIndex_C317,
              which writes $00 across $0100-$07FF via (ptr),y),
              SoundDelay0 (the base of the per-channel delay table, indexed by X)
              in the sound engine;

No symbols.inc substitution was needed: copilot/prg.s contains no numeric
hardware operands ($2000-$4017) at all. All 362 operands were already written
with two hex digits, so no ca65 `a:` prefix was required.

make -> Byte-identical ROM verified. Operand token only; mnemonics, spacing and
the trailing `; CPU:$.... PRG:....  XX XX` audit comments are untouched.

Remaining numeric operands (758) address bytes that no .inc file names:
505 zero-page (133 addresses), 171 RAM $0100-$07FF (46 addresses) and 82
table reads in $8000+ (54 addresses).

Bomberman (U): substitute 24 in-file table labels at ROM operand sites

Uses the new `--labels` option of `apply_symbols.py` with the
ld65 `-Ln` output (`reconstructed.lbl`). Only labels that prg.s
actually defines and that live in the PRG (+) are considered,
so CHR/header segment labels cannot leak in.

24 numeric operands (`lda ,x`, `adc ,y`, etc.) now read
`lda SystemPaletteData,x`, `adc GameplayObjectClassTable,y`, etc.
All 24 point at exact label addresses; the remaining 58 ROM-space
numeric operands point at interior bytes or unlabelled tables and
stay numeric.

make -> Byte-identical ROM verified.

Bomberman (U): update docs for Pass 3 symbol application

- Project OVERVIEW.md: corrected source file from main.s to prg.s/header.s/chr.s;
  output name from reconstructed_bomberman.nes to reconstructed.nes;
  rewritten §10 Zero-Page/RAM Symbols table to match locals.inc (with aliases
  and unnamed residue documented);
  fixed §4 step 1/4 to use IndirectPtrLo/Hi and SoundDelay0 names;
  fixed §11 InesHeader location (now header.s);
  added §2 Pass 3 summary table;
  added §13 notes on legacy main.s and Main_WriteSoundDispatchIndex_C317 misnomer.

- Root OVERVIEW.md §3: updated source line count (7,553), file list, and added
  Pass 3 summary.

Both builds verified byte-identical.

Pass 3 symbol application to all 19 top-level projects (2026-10-19)

Ran _tools/apply_symbols.py --write on all 19 promoted projects to substitute
symbolic names from symbols.inc (hardware registers) and locals.inc (zero-page
RAM aliases, forward references) into prg.s operands. The tool preserves the
canonical audit comments (; CPU:$XXXX PRG:XXXX AA BB) and preserves byte
identity — all projects still rebuild byte-identical to their original ROMs.

Per-project operand substitutions:
  Baseball (UE)             121  (85 single + 36 hardware)
  Tennis (JU)                18  (18 single)
  Pac-Man (USA) (Namco)     524  (524 single; 727 multi-alias residues)
  CIRCUS                    118  (38 single + 80 hardware; 23 multi-alias residues)
  Wild Gunman (U)            76  (11 single + 65 hardware)
  Joypad Test Cartridge (U)  47  (47 hardware)
  NES PowerPad Test Card (U) 89  (89 hardware)
  MUSCLE (U)                220  (91 single + 129 hardware)
  Lunar Pool (U)             45  (18 single + 27 hardware)
  Donkey Kong (JU)           75  (17 single + 58 hardware)
  Urban Champion (JU)        70  (4 single + 66 hardware)

Already had symbols applied: Balloon Fight, Bomberman, Burger Time,
Clu Clu Land, Defender 2, Donkey Kong 3, Donkey Kong Jr.

Skipped: Excitebike (JU) — inline prg.s definitions conflict with locals.inc
values and source operands don't match ROM byte encodings; automatic
substitution breaks byte identity.

Documentation updated:
  OVERVIEW.md — added Pass 3 symbol notes to all 19 project entries,
  added Urban Champion as section #36
  TODO.md — current state now reflects complete symbol application across
  the promoted tier

Verification: python3 _tools/verify_pass1.py reports all 19 projects OK/SEEDED,
all canonical comments, no truncated or unfaithful Pass 1.
2026-10-19 14:55:08 -04:00

13 KiB
Raw Blame History

Urban Champion (JU) — Pass 3 Complete

ROM: Urban Champion (JU)/Urban Champion (JU).nes (24,592 bytes, iNES). Status: Pass 3 complete — all data tables/structures named; promoted to the top level (row 36), whole ROM byte-identical. copilot/prg.s contains a classified disassembly with per-instruction audit comments (; CPU:$xxxx PRG:xxxx AA BB), unreached bytes emitted as explicit .byte blocks with provenance (33.9% code / 5,546 bytes, 66.1% data / 10,838 bytes). make verifies header + PRG + CHR against copilot/rom.nes.

ROM Facts

Property Value
Mapper 0 (NROM) — from the iNES header
PRG 16 KB (header claims map at CPU $C000–$FFFF)
CHR 8 KB
Mirroring Vertical
Battery-backed flag clear
ROM SHA-256 3ec5ac8db623dae34a0f4a4909f0af4569b2af0cee6c56bae512c87b7cff8749
PRG SHA-256 13e7f2a77b01784a479895c0535357978af32f5139d971edf5f5b1936585357e

Interrupt Vectors (taken from PRG $3FFA–$3FFF)

Vector Target Note
NMI $CA91 per-frame heartbeat
RESET $CA00 non-$C000 entry at $CA00 — trace from here in Pass 1
IRQ $CA00 redirects to RESET — unused placeholder

copilot/ Contents

File Purpose
Urban Champion (JU).nes original ROM image (reference)
prg.bin / header.bin / chr.bin split image, produced by _tools/splitnes.py
prg.s Pass 1: classified code/data split, 2,716 instructions, 436 labels, audit comments on every emission; Pass 2: all 519 labels renamed to semantic names
symbols.inc shared NES hardware constants (PPU/APU/controller)
locals.inc 153 zero-page aliases + 10 semantic aliases (Pass 2)
linker.cfg PRG at $C000, 16 KB, fill = yes
Makefile links reconstructed.nes and cmps it against rom.nes (whole ROM)
reconstructed.nes build output from the last verified build

This project is promoted: copilot/ links header.s + prg.s + chr.s and make compares the whole reconstructed.nes against rom.nes, so header, PRG and CHR are all proven.

Build

cd "Urban Champion (JU)/copilot"
make        # → cmp reconstructed.nes rom.nes → "Byte-identical ROM verified."

Pass 1 Details

  • Tracer seeds: RESET ($CA00), NMI ($CA91), plus --auto-seed recovered 34 table-referenced routines.
  • Forced data override: $CB70+$3C (a cascade of bne instructions that are actually a branch table/data, not code). The fall-through through this region was incorrectly classified as code; forced to data with --data 0xCB70:60.
  • Overlaps: 6 overlap regions remain (e.g. $CB8F lsr overlaps $CB91), all in the forced-data region — the conflicting decodes are suppressed in the output.
  • Invalid opcodes: 7 addresses reached via static trace but decoding invalid opcodes ($C658, $CAF9, $CB4D, $CC61, $D21B, $DBCE, $DE24). These are marked .byte with the invalid opcode in the audit comment.
  • Indirect jumps: 3 jmp ($xxxx) sites at $CDFB ($0014), $C318 ($00EB), $C332 ($00ED) — targets not statically resolvable.
  • Zero-page aliases: 153 entries in locals.inc (auto-generated by tracer).

Next Steps

Passes 1-3 are complete and the project is promoted to the top level (row 36, kept its tail number); make compares the whole reconstructed.nes against rom.nes. No pass work is pending.

Pass 3 Details (2026-10-18)

Data Tables Named (55 labels applied via data_label_map.tsv)

Address Range Size Name Description
$C006-$C025 32 B InitData_C006 Early init data (APU/frame counter)
$C032-$C04D 28 B InitData_C032 Early init data (controller tables)
$C06A-$C06D 4 B SoundPointerTable Pointers to sound data ($E84F, $E854, $E859, $E85E)
$C0A1-$C0AD 13 B InitData_C0A1 Early init data
$C100-$C18C 141 B ControllerKeyTable Controller key mapping table (indexed by Y)
$C1FE-$C20E 17 B InitData_C1FE Early init data
$C22F-$C24C 30 B InitData_C22F Init routine (converted from data via CDL)
$C26A-$C287 30 B InitData_C26A Init routine (converted from data via CDL)
$C2A8-$C2DD 54 B InitData_C2A8 Init routine (converted from data via CDL)
$C2F9-$C30B 19 B InitData_C2F9 Init routine (converted from data via CDL)
$C36E-$C375 8 B APUFrameCounterData APU frame counter init values
$C42C-$C443 24 B InitData_C42C Init routine data
$C4F8-$C507 16 B InitData_C4F8 Init routine data
$C521-$C52C 12 B InitData_C521 Init routine data
$C5A0-$C5A3 4 B InitData_C5A0 Tiny init data
$C658-$C9FF 936 B SpriteMetatileTable Major table: sprite/metatile definitions (indexed by Y, 16-byte entries with pointer+data)
$CA02-$CA33 32 B TitleScreenData_CA02 Title screen init data
$CA34-$CA9C 61 B TitleScreenData_CA34 Title screen data
$CB70-$CBAC 61 B BranchTableOffsets Branch offsets for dispatch table (DATA, never executed)
$CC61-$CC66 6 B InvalidOpcode_CC61 Invalid opcode bytes
$CF32-$CF4D 28 B InitData_CF32 Init routine data
$CFC3-$D011 79 B InitData_CFC3 Init routine (converted from data via CDL)
$D027-$D02F 9 B InitData_D027 Init routine data
$D067-$D079 19 B InitData_D067 Init routine data
$D09D-$D173 215 B UpdateScrollData Scroll update routine (converted from data via CDL)
$D21B-$D242 40 B InvalidOpcode_D21B Invalid opcode bytes
$D26E-$D27A 13 B InitData_D26E Init routine data
$D344-$D34A 7 B InitData_D344 Init routine data
$D361-$D366 6 B InitData_D361 Init routine data
$D36A-$D391 40 B InitData_D36A Init routine data
$D469-$D7DA 882 B GameplayCode_D469 Major routine missed by static trace (converted from data via CDL)
$D834-$DA24 497 B GameplayCode_D834 Major routine missed by static trace (converted from data via CDL)
$DA34-$DAA6 115 B TitleScreenData_DA34 Title screen data
$DAB7-$DB47 145 B SpriteDMATable Sprite DMA source data (referenced by lda $F940,y at $DBAA)
$DBCB-$DBDC 18 B UpdateTimersData Timer update data
$DBFD-$DCF5 249 B ProcessInputsData Process inputs routine (converted from data via CDL)
$DD7D-$DD8B 15 B InitData_DD7D Init routine data
$DDAC-$DE02 87 B InitData_DDAC Init routine data
$DE24-$DE34 17 B InvalidOpcode_DE24 Invalid opcode bytes
$DE36-$DEC8 147 B InitData_DE36 Init routine (converted from data via CDL)
$DED8-$DF4B 116 B InitData_DED8 Init routine (converted from data via CDL)
$DF56-$DF73 30 B InitData_DF56 Init routine data
$DFEA-$E03F 86 B InitData_DFEA Init routine data
$E11D-$E1CC 176 B HandlePlayerCode Handle player routine (converted from data via CDL)
$E350-$E40D 190 B HandleGameOverData Game over data
$E4C0-$E4E1 34 B InitData_E4C0 Init routine data
$E700-$E70B 12 B InitSpriteDataTable Sprite data init table
$E78A-$E792 9 B InitData_E78A Init routine data
$E813-$FFFF 6125 B SpritePatternTable Major table: sprite/pattern/metatile data (pointers at start, then pattern bytes)

Key Structures Identified

  1. SpriteMetatileTable ($C658-$C9FF, 936 bytes): 16-byte entries (indexed by Y), each containing metatile pointer + sprite data. Referenced by lda $C658,y at $C1C1 etc.

  2. SpritePatternTable ($E813-$FFFF, 6125 bytes): Large sprite/pattern data. First 112 bytes ($E813-$E880) are 56 word pointers into the table ($E84F, $E854, $E859...), followed by pattern/palette data.

  3. ControllerKeyTable ($C100-$C18C, 141 bytes): Indexed by Y, maps controller input to actions.

  4. BranchTableOffsets ($CB70-$CBAC, 61 bytes): Branch offset table for BranchTable_CB91 dispatch. Confirmed DATA by CDL (never executed as opcodes). Entry point is $CB91 via jmp $CB91 at $CADE.

  5. SpriteDMATable ($DAB7-$DB47, 145 bytes): Source data for sprite DMA (referenced by lda $F940,y at $DBAA).

  6. SpritePatternTable ($E813-$FFFF, 6125 bytes): Massive pattern table with 56 word pointers at start, then sprite/background pattern data.

CDL-Verified Code Regions (Converted from Data)

The following regions were misclassified as data by static trace but are CODE per Mesen CDL:

  • $D469-$D7DA (882 B): GameplayCode_D469 - massive gameplay routine
  • $D834-$DA24 (497 B): GameplayCode_D834 - gameplay routine
  • $DBFD-$DCF5 (249 B): ProcessInputsData - process inputs
  • $DE36-$DEC8 (147 B): init routine
  • $DED8-$DF4B (116 B): init routine
  • $E11D-$E1CC (176 B): HandlePlayerCode - player handling

Remaining Work

Pass 3 named all data tables/structures above, so nothing structural is outstanding; make verifies the whole ROM. This file could gain an expanded power-on flow narrative.

Pass 2 Details (2026-10-18)

  • Label renaming: All 519 labels renamed to semantic names using pass2.py apply with a mapping file (label_map.tsv). Key renamed routines:
    • RESET/NMI: Reset, NmiHandler
    • System init: InitSystem, WaitPPUReady, InitStack, LoadGameConfig, InitVariables, SetupInitialState
    • RAM clearing: ClearRAM, ClearRAMLoop
    • APU init: InitAPU, ClearControllerState, InitAPURegisters, SetAPUVolume, SetAPUSweep, InitAPUWaveform
    • Controller: UpdateControllerState, CheckControllerStart, ProcessControllerInput
    • Game loop: MainGameLoop, TitleScreenLoop, GameModeDispatcher, GameplayFrame, CheckRoundEnd, UpdateRoundTimer
    • NMI: NmiHandler, NmiFrameUpdate, NmiVBlankOnly, NmiExit, UpdateScroll
    • Sprites: InitSprites, SpriteDMA
    • Players: UpdatePlayers, HandlePlayer1, HandlePlayer2, UpdatePlayerPositions
    • Collision: CheckCollisions
    • Sound: InitSound, PlaySoundEffect, UpdateMusic
  • Zero-page semantic aliases: 10 aliases added to locals.inc (see locals.inc header for full list):
    • Controller: Joy1State ($F3), Joy2State ($EF), Joy1DPad ($F6), Joy2DPad ($F7)
    • Game state: GameMode ($24), RoundIndex ($26), DispatchIndex ($C0)
    • Player arrays: PlayerState ($16), PlayerInput ($25), PlayerData ($2A)
    • Pointers: TempPtrLo ($00), TempPtrHi ($01)
  • No Label_ entries remain — all 519 labels have semantic names.

Mesen CDL Verification (2026-10-18)

A Code Data Logger capture was taken during gameplay (~15 seconds, all buttons pressed). Key findings vs. static trace:

Static Trace CDL (Gameplay) Disposition
$C006-$C025 (32 B data) CODE Missed init routine — convert to code in Pass 2
$C032-$C04D (28 B data) CODE Missed init routine — convert to code in Pass 2
$C22F-$C24C (30 B data) CODE Missed routine — convert to code in Pass 2
$C26A-$C287 (30 B data) CODE Missed routine — convert to code in Pass 2
$C2A8-$C2DD (54 B data) CODE Missed routine — convert to code in Pass 2
$C2F9-$C30B (19 B data) CODE Missed routine — convert to code in Pass 2
$CFC3-$D011 (79 B data) CODE Large missed routine — convert to code in Pass 2
$D09D-$D173 (215 B data) CODE Large missed routine — convert to code in Pass 2
$D469-$D7DA (882 B data) CODE Very large missed routine — convert to code in Pass 2
$DBFD-$DCF5 (249 B data) CODE Missed routine — convert to code in Pass 2
$DE21-$DEC8 (168 B data) CODE Missed routine — convert to code in Pass 2
$DED8-$DF4B (116 B data) CODE Missed routine — convert to code in Pass 2
$E11D-$E1CC (176 B data) CODE Missed routine — convert to code in Pass 2
$E350-$E40D (190 B data) CODE Missed routine — convert to code in Pass 2
$CB70-$CB90 (data) DATA Confirmed: branch offsets, never executed as opcodes
$CB91-$CBAC (data) CODE (jump target + linear) Critical: jmp $CB91 at $CADE enters here; executes linearly as a branch table. Current static trace has entire $CB70-$CBAC as one data block with dead branch-target labels inside. Pass 2 must split: $CB70-$CB90 = data (branch offsets), $CB91-$CBAC = code (real branch table entered via jmp $CB91).

CDL coverage: 28.2% code (4,614 bytes) vs static trace 33.9% (5,546 bytes). The static trace over-reaches via fall-through into the branch cascade; the CDL confirms the cascade is dead (branch at $CB6E always taken to $CB4E), but reveals $CB91-$CBAC is live code entered via the jmp at $CADE.

Reference in new issue View Git Blame Copy Permalink