tmerritt/disasm
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
691b2bc23ca267436de0dcc424e42f65d4b2f5d8
disasm/CHANGELOG.md
T
tmerritt 691b2bc23c Xevious (U): Pass 1 disassembly 
The first _wip project to get a real disassembly.  4,165 instructions /
8,444 code bytes (25.8%), 24,324 data bytes, 0 unclassified -- every byte
of the 32 KB PRG is now classified as code or data.

The split needed three stages, all recorded in prg.s's header:

  * nesdis.py --undocumented --auto-seed at base $8000 gave 3,272
    instructions / 6,555 bytes.  The undocumented opcodes matter here: the
    trace stops dead at the first one it cannot decode.
  * Four hand-seeded entries ($C08B, $DC1E, $E0D5, $E134).  Each is a
    branch target from decoded code that sat inside an untraced data run,
    so the tracer never reached it.
  * A merged four-session Mesen Code Data Logger capture (kept as
    xevious_mesen.cdl) promoted 1,902 bytes from data to code and
    demoted 22 the trace had called code.

Two tool bugs fell out and are fixed here:

  * nesdis.py emitted the undocumented single-byte NOPs ($1A/$3A/$5A/
    $7A/$DA/$FA) as `nop`, which ca65 assembles as the *official* $EA --
    the rebuild stopped being byte-identical at $DF82.  The check now
    keys on the opcode byte, not just the addressing mode.  All three
    `make regen` pipelines (MUSCLE, Pyramid, Urban Champion) are
    unaffected and still reproduce prg.s byte for byte.

  * cdl_reclass.py left the original data-block header in place when the
    CDL split that block, so the file ended up with two region headers
    describing overlapping spans (20 of them here).  The header is now
    dropped with the block it describes; the promoted projects that use
    the tool are byte-for-byte unchanged.

The project README has the power-on flow analysis.  The most interesting
find is at $FC45: the reset path compares RAM $0100-$0107 against the
ASCII string "Kei Cros", and the copyright text at $FF1E reads
"MAIN: KEI CROSS.  SOUND: UHOHOY OHNOGI."  The OAM is at $0700, not
$0200 -- the NMI handler does LDA #$07 / STA $4014.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add explicit `make wip` / `make wipclean` targets for the _wip tier

The root Makefile's all / clean / <MAPPER> targets deliberately name only
the promoted mapper folders, so nothing in them reaches into _wip/.  Give
the pre-promotion tier its own opt-in targets instead of the manual
`for d in _wip/*/*/; do make -C "$d"; done` loop:

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

Both the Makefile and the four documents that describe the tier (README,
TODO, WIP, AGENTS) are updated together, so the tree stays consistent.

The same commit records Xevious (U) reaching Pass 2 in those documents:
all 487 labels named, every branch and call symbolic, zero Label_XXXX and
zero raw $XXXX operands left.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update the _wip/ tier documentation; fix the make wip target and the mirroring bug

The WIP tier's four documents (WIP.md, README.md, TODO.md, AGENTS.md) had
drifted away from the tree.  Every number in them was re-derived from the
ROMs and the folder layout rather than carried forward.

Counts and structure
  - The tier holds 854 projects across 29 mapper folders, not "856 across
    30".  Xevious (U) and Zanac (U) were promoted on 2026-10-20 and their
    _wip/ folders were left behind as residue -- "git mv" moves only the
    tracked files, so the old folder survived with its build artifacts and a
    stale README.  Both are removed now; the promotion procedure documents
    the step so it does not recur.
  - _wip/MAPPER8/ holds a copy of the already-promoted Mermaids of
    Atlantis (U) and is excluded from every count and table.
  - Pass 0 skeletons: 852 (was 855).  Xevious (U) left the tier, so the
    two projects with a real disassembly are Golf (JU) and Volleyball (U).
  - PRG sizes 2 / 150 / 42 / 522 / 127 / 10 / 1; 226 projects with no CHR;
    38 keep the CPU-address linker layout; 37 are mapper 0.
  - Every inventory row was re-checked against its ROM: PRG/CHR size,
    mirroring, all three vectors, and the battery / four-screen / footer
    notes.  854 of 854 rows now match.

Fixes
  - The root Makefile used $(WIP) but never defined it, so "make wip" and
    "make wipclean" expanded to "for m in /*/" -- they walked the
    filesystem root instead of the tier.  "WIP := _wip" is now defined, and
    "make wip" builds and verifies the whole tier: 855 of 855 passed, 0
    failures.
  - make_skeleton.py masked header byte 6 with 0x03, so the battery bit
    (bit 1) leaked into the mirroring value and 56 battery-backed ROMs'
    READMEs claimed "Four-screen" while their own "Four-screen VRAM" row
    said "no".  The mask is now 0x01 and the 56 READMEs are corrected.
  - Golf (JU)'s README still described the pre-flatten copilot/ folder and
    the old PRG-only compare; it now describes the whole-ROM build.
  - Pyramid (U)'s audit comments are canonical again, so Golf (JU) is the
    only project in the tree still on the pre-canonical spelling.

New in WIP.md
  - Byte 7's lower nybble is non-zero on 58 of the ROMs -- 55 carry the
    literal "DiskDude!" watermark, two "DisNi0330", one "byKH+KEN".  Only
    the upper nybble carries mapper bits, so the noise is harmless.
  - The twelve ROMs that set the four-screen bit, split by whether their
    board actually supports four-screen VRAM.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Promote Volleyball (U) from _wip/NROM/ to NROM/

Volleyball (U) reached Pass 3 before promotion, so this is a promotion of a
finished disassembly rather than a Pass 0 skeleton.

The disassembly
  - 11,395 instructions / 23,926 code bytes (73.0 % of the PRG image),
    8,842 data bytes, 0 unclassified.
  - The split needed the game-state dispatch table at $85E1 declared to the
    tracer (--table 85E1:11) -- without it only 66 % of the image traced --
    plus a Mesen Code Data Logger capture taken while a random-input bot
    played the attract demo, which promoted 1,757 bytes from data to code.
  - Pass 2 named all 1,989 labels: 730 read out of the code by hand, 1,221
    internal branch targets derived mechanically.  Zero Label_XXXX, zero raw
    $XXXX call or branch operands, zero SubC residue.
  - Pass 3 named the zero page, the $0500 ball structure and all 37 data
    blocks.  apply_symbols.py --report: 0 pending substitutions, 0
    multi-alias residue.  align_audit_comments.py: no column drift.
  - cdl_check.py cross-checks the finished prg.s against the capture: 0
    CDL-code bytes not covered by an instruction, 0 CDL-data bytes that
    start one.
  - 29 neutral ZpXX zero-page slots remain, each with its reason recorded
    in locals.inc, as the promotion rules allow.

The promotion
  - git mv "_wip/NROM/Volleyball (U)" "NROM/Volleyball (U)".  Mapper 0, so
    it lands in NROM/.  The whole-ROM build was already in place, so there
    was no build surgery; the project builds byte-identically at its new
    home and the old folder is gone (git mv moves the untracked build
    artifacts too, so no residue was left behind).
  - Root README.md: new inventory row 39 and a per-project detail section,
    plus the WIP-tier counts.  The detail sections for Xevious (U) and
    Zanac (U) were numbered one too high against the inventory rows and
    are now aligned; a leftover editing note in the same place is gone.
  - WIP.md: the Volleyball row leaves the inventory, and the tier is now
    853 projects across 29 mapper folders (36 in _wip/NROM/), 852 of them
    Pass 0 skeletons.  Golf (JU) is the only project left in the tier with
    a real disassembly.
  - TODO.md and AGENTS.md: the same counts, and the promoted tier is now
    40 projects (39 under NROM/).

Verified: make wip builds and verifies the whole tier (854 of 854 passed,
0 failures) and make builds the promoted tier (39 of 39 passed).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Rename NROM/Pyramid (U) to NROM/Pyramid (U) (Sachen)

The promoted inventory row had read "Pyramid (U) (Sachen)" since the
project was promoted on 2026-10-20, but the folder was named "Pyramid (U)" --
so the row pointed at a folder that did not exist.  The folder now matches
the row, and the project's own README title, its ROM file name
("Pyramid (U) (Sachen).nes") and the parenthetical convention the rest of
the promoted tier already uses (Popeye (JU) (PRG 0/1), Raid on Bungeling
Bay (U) [a2], Pac-Man (Tengen) (U)).

What changed inside the project
  - The Makefile's regen target passes --project "Pyramid (U) (Sachen)", so
    the tracer writes the matching header line.  prg.s and locals.inc were
    updated to that header line and nothing else -- the disassembly is
    byte-identical to before.
  - make regen still reproduces prg.s and locals.inc byte for byte.
  - The project's README's build-verification line now names the new folder.

References updated: the root README.md (inventory prose, the row-33 detail
section, the build-status table, and the notable-observations bullet),
TODO.md (the promoted-projects table and the Pyramid notes) and AGENTS.md
(the recently-promoted list and the unlicensed-titles quirk).

Verified: make builds the promoted tier (39 of 39 passed) and the project
rebuilds byte-identically at its new path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Rebuild Mermaids of Atlantis (U): bank-aware Pass 1, Pass 2/3 names

The promoted project did not build: a Pass 2 rename had been applied
half-way, leaving eight undefined symbols and two jumps that pointed at
the wrong routine, while the root README already claimed the project was
byte identical.  The _wip copy still built, because it held the un-renamed
Pass 1 source.

The disassembly is now derived from the ROM itself, with the Mesen Code
Data Logger as the oracle for the code/data split:

* _tools/banked_dis.py traces every MMC3 bank separately, each with the CPU
  window it is visible at, seeded from a CDL capture so the code a static
  trace cannot reach is disassembled too.  The CDL is the authority: a
  decode the CPU never fetched is dropped, and so is the fall-through
  behind a call whose target never returns (the game's dispatchers have
  their jump table right behind the call).
* One segment per bank (PRG0..PRG7) with its own .org, so the assembler
  knows the CPU address of every label while the linker still writes the
  bytes to the bank's file offset.  A flat segment cannot do both: a call
  would encode the file offset instead of the CPU address.
* Pass 2 names every label - 494 routines, no Label_XXXX and no raw
  $XXXX branch or jump operand left.  Pass 3 applies 13 semantic zero-page
  aliases and writes the routine headers.
* 8,075 bytes of code (12.3% of the 64 KB PRG), up from 200 bytes.

The banking turned out to be unusual and is documented: the fixed bank is
the fourth 8 KB bank (file $6000-$7FFF), not the last one, and the image
carries the reset stub and the vector table twice.  The live NMI vector
is $808F - the frame handler - while the copy at the end of the image
names $8189, which is a BRK in the first half.  The game's text table
lives at CPU $F1D6, which is the fixed window, and that is what settles
the question.

Also: the leftover _wip/MAPPER8 folder is removed, as it is for every
other promotion.

The project builds byte identical:

    Byte-identical ROM verified.

Add CHANGELOG.md: the pass history of every project

A project goes through four milestones - Pass 1 (the code/data split),
Pass 2 (the labels replaced by names), Pass 3 (the semantic naming) and
Promotion (the move into the top-level mapper folder) - and the history
of those milestones was scattered over the commit log, the project
READMEs and the root README.

CHANGELOG.md gathers it: one section per project with a row for each
milestone, the date, and a sentence saying what the milestone produced.
The numbers are the ones the project README and the root README already
carry - instruction count, code coverage, named labels, semantic
zero-page aliases, named data tables - so a reader can see at a glance
which projects are done and which are not.  Golf (JU), the only project
still in _wip/ with a real disassembly, is listed with its open
milestones, and the other 852 _wip/ projects are covered as a tier.

The requirement is now part of the workflow contract: PROMPTS.md gains a
"Pass 3: Changelog entry" section and a ninth checklist item, and
AGENTS.md points at the file.  A milestone and its changelog row go in
the same commit, so the changelog and the source never disagree.

Balloon Fight (JU): repair the audit trail and complete the routine headers

The per-instruction audit trail was stale by two bytes from
ResetInitializationData ($C085) onward.  5,944 of the 6,007 comments named
the wrong CPU address and PRG offset, because the three-byte .byte "HAL"
signature at $C082-$C084 had been counted as one byte when the trail was
first generated - the routine headers and the linker labels were right all
along, so the source and its own headers disagreed with each other.  The
trail was rebuilt from the ca65 -l listing with
_tools/repair_audit_comments.py, and every rewritten comment was re-checked
against prg.bin.  The comments were also moved into the canonical column-35
field: they had sat two spaces after the mnemonic, with no column discipline
at all, unlike every other promoted project.

All 63 routine headers now carry a ; Clobbers: block, so the headers carry
the full template AGENTS.md describes.  The blocks are derived, not written by
hand.  The new _tools/derive_clobbers.py takes the opcode from the audit
comment's byte list, so the addressing mode is exact and a data directive is
never mistaken for an instruction; it resolves the operand through
locals.inc and symbols.inc to name what is written; it follows the real
control flow, so a jsr to another named entry is a call (the callee's
clobbers count) while a branch or a fall-through is not; and it models
register preservation, so NmiHandler reports *no register* - it saves and
restores A, X and Y around the frame - and FlushPpuCommandPreserved reports
only A, because X and Y come back unchanged.

Two tools changed.  derive_clobbers.py is new.  align_audit_comments.py had
an off-by-one: it tested the indented code length against 31 instead of
against 35, so code texts of 28-31 characters were never padded into the
column.

The change is comments only.  The code text of all 8,538 lines is unchanged,
make still prints "Byte-identical ROM verified.", the 6,007 audit comments
still re-check against prg.bin, all 63 routine headers agree with the
instructions they describe, and every label agrees with reconstructed.lbl.
ReflectObjectYVelocity and UpdateSpecialObjectSystem moved out of locals.inc
and became labels in prg.s at their real addresses.

CHANGELOG.md becomes the repository's running log: a Pending list of the
changes to be put in the next commit, a History of the commits already made,
and the per-project milestone index at the end.  The next commit's message is
written from the Pending entries, so the two cannot drift apart.  PROMPTS.md
and AGENTS.md describe the new shape.  WIP.md drops the _wip/MAPPER8/ note:
the folder held a copy of Mermaids of Atlantis (U) that had already been
promoted.

World Class Track Meet (U): Pass 1, the code/data split

Pass 1 is done.  The split is 8,400 instructions / 18,028 code bytes (55.0 %)
of the 32 KB PRG, with 884 routine entries, 55 data blocks and 102 zero-page
aliases.  The PRG is CNROM (mapper 3) and maps whole at $8000-$FFFF, so the
linker moved the PRG segment from a .nes file offset to $8000 and the build
still compares byte identical.

Four dispatch tables had to be seeded by hand.  The event table at $F796 (5
entries) is read at $F780 and jumped to through `jmp ($001F)`.  The three
push-pointer tables - $BFC4 (16 entries), $BFE4 (2) and $E5F2 (7) - push a
handler address and `rts` into it, and the 6502's `rts` adds one to the
address it pops, so each table stores the entry address minus one; the seeds
are the table values plus one.  The tracer runs with --undocumented: the code
uses undocumented NMOS opcodes as ordinary code (ANC $37 at $BFF8, and the
RRA/RLA/SLO and NOP forms elsewhere).  Seeding the tables takes the coverage
from 27.8 % to 55.0 %.

$C0BE-$C0C5 is forced back to data: the IRQ vector $C0C0 points into the
middle of the `jmp $C047` at $C0BE, and the game never executes CLI, so the
vector is dead.  `make pass1` regenerates prg.s and locals.inc from prg.bin
and reproduces the committed prg.s byte for byte.

The project README records the split, the four dispatch tables, the dead IRQ
vector, the wrong CHR size field in the header, and what is still data.  The
milestone index in CHANGELOG.md gains the project; WIP.md, README.md and
AGENTS.md follow the tier counts and the layout.

nesdis.py gains a --mapping-note option, so the header's "PRG mapped at" line
can describe a board that is not NROM - CNROM's whole 32 KB at $8000-$FFFF is
not "mirrored to the upper half".

Replaces runs of $00 and $FF with .res <run>, <byte>

Golf (JU) and World Class Track Meet (U): Pass 2/3 complete, promoted from _wip/

- World Class Track Meet (U) - Pass 2 complete: all 884 Label_<addr>
  definitions replaced (651 semantic routine names + 233 Sub_<addr>), all 731
  raw $XXXX jsr/jmp call operands resolved to symbolic labels, all branch
  targets given role-based names; routinemap.tsv added; make stays
  byte-identical.
- World Class Track Meet (U) - Pass 3 complete: 24 semantic zero-page
  aliases applied via apply_symbols.py (0 residue), 78 neutral ZpXX slots
  documented with reasons in locals.inc, all hardware-register operands use
  symbols.inc names, project README rewritten with Pass 2/Pass 3 sections and
  data-table inventory; promoted out of _wip/CNROM/.
- World Class Track Meet (U) - project README documents the five event-table
  entries at $F796 and marks the olympics mode as not yet proven.
- Golf (JU) - audit comments converted from pre-canonical (; C000: A9 00)
  to the canonical ; CPU:$C000 PRG:0000  A9 00 form at column 35; 4,156
  comments re-aligned, comment/whitespace only, whole-ROM build stays
  byte-identical.
- Golf (JU) - 339 internal branch-target Label_ labels given role-based names
  via _tools/derive_branch_names.py; 0 raw $XXXX branch/jump operands remain.
- Golf (JU) - 275 zero-page operands substituted with locals.inc aliases via
  apply_symbols.py; 0 residue; promoted out of _wip/NROM/.
- Xevious (U) - runs of $FF padding replaced with .res <count>, $FF in prg.s;
  whole-ROM build stays byte-identical.
- Both projects promoted via git mv; leftover _wip/ folders removed; root
  README.md inventory rows added; WIP.md rows removed.

World Class Track Meet (U): apply zero-page symbol substitutions

Run apply_symbols.py to substitute ZpXX zero-page operands with
semantic locals.inc aliases (SlotState, GameMode, etc.) at proven
sites; 0 residue, whole-ROM build stays byte-identical.

Xevious (U): re-split Pass 1 from the Mesen CDL and decode the data tables

- Xevious (U) - Pass 1 re-split from the Mesen CDL (xevious_mesen.cdl) with
  _tools/cdl_reclass.py: 1,158 bytes data->code, 48 code->data, 42 labels
  emitted and 3 branch targets labelled; code 11,321->12,455 bytes
  (34.5%->38.0%), instructions 5,513->6,002. The 45 recovered entry points
  are named Sub_XXXX, so no Label_XXXX remains; six CDL-silent raw call
  operands are documented as residue.
- Xevious (U) - the 4,448-byte block at $A74B-$B8AA is split into six proven
  tables: VramWritePtrTable (15 pointers), VramWriteData, DataStreamPtrTable
  (16), ObjTilePtrTable (99), ObjTileData and DataStreamData. The $D833
  pointer table is corrected to base $D833 (4 entries; the old ObjCodePtrTable
  at $D834 was one byte late). $F957-$FAF5 is split into ObjSpeedTable,
  ObjSpeedTable2, SpriteLayoutPtrTable (19) and SpriteLayoutData;
  $FEE6-$FF1C into PaletteData and OamAttrTable. $F5D8 is decoded as
  TextTileData (font tile indices: PLAYER, GAME OVER, READY, SOLVALOU, LEFT,
  PAUSE); $F53C becomes AttrAddrTable, $F89E HandlerPtrTable and $EF3B
  SpriteLayoutData2. Project README rewritten with the corrected stats, a
  32-entry table inventory and the Pass 1 residue.
- _tools/cdl_reclass.py - preserve the data label(s) between a data-block
  header and its first .byte row when the block stays data; the $DF78 split
  dropped Data_DF78 and the rebuild failed with an undefined symbol.
- _tools/resolve_raw_branches.py - handle negative relative offsets
  (beq *-$0B); the pattern only matched *+$NN and *$NN.

Docs: refresh the tier counts to 41 promoted / 851 _wip, add the WCTM row

- Docs - tier counts refreshed to the post-promotion state across AGENTS.md,
  root README.md, WIP.md, TODO.md and CHANGELOG.md: 41 promoted projects
  (38 under NROM/, plus CNROM/World Class Track Meet (U), UNROM/Zanac (U) and
  MAPPER8/Mermaids of Atlantis (U)) and 851 _wip/ projects, every one of them
  a Pass 0 skeleton. The stale "39/40 promoted", "853 _wip", "Golf (JU) is
  still in _wip/" and "Golf is the last pre-canonical project" statements are
  corrected.
- Root README.md - the promoted inventory gained the missing World Class Track
  Meet (U) row (row 41, mapper 3, 32 KB PRG / 32 KB CHR), and the "All 38 are
  mapper 0 / 16 KB PRG" sentence is replaced with the actual split (36 of the
  41 rows are mapper 0 / 16 KB; Xevious and Volleyball are 32 KB, World Class
  Track Meet is mapper 3, Zanac mapper 2 and Mermaids mapper 8).
2026-10-21 11:36:32 -04:00

521 lines
39 KiB
Markdown
Raw Blame History

# Changelog
A running log of every change made in this repository. It covers **all**
of the projects - the promoted tier and the `_wip/` tier alike - and it is
also the staging area for the next commit.
## How this file is used
1. **As work lands**, a line goes into **Pending**: the project it touches
and what changed. Nothing else is needed - the entry is the record.
2. **At commit time**, the commit's message is written *from* the entries in
**Pending**. The entries are the summary of what the commit contains, so
the message and the log cannot drift apart.
3. **After the commit**, the entries move to **History** under the commit
they went in with, and **Pending** starts again empty.
**Pending** - the list of changes to be put in the next git commit.
**History** - the running log of the commits that have already been made.
**The milestone index** at the end - the per-project pass history: which of
the four milestones each project has reached, and when. That part is a
status table rather than a log, and it is what `PROMPTS.md` asks for when a
project reaches a milestone.
## Pending
- **Docs** - tier counts refreshed to the post-promotion state across `AGENTS.md`, root `README.md`, `WIP.md`, `TODO.md` and `CHANGELOG.md`: **41 promoted projects** (38 under `NROM/`, plus `CNROM/World Class Track Meet (U)`, `UNROM/Zanac (U)` and `MAPPER8/Mermaids of Atlantis (U)`) and **851 `_wip/` projects**, every one of them a Pass 0 skeleton. The stale "39/40 promoted", "853 `_wip`", "`Golf (JU)` is still in `_wip/`" and "`Golf (JU)` is the last pre-canonical project" statements are corrected.
- **Root `README.md`** - the promoted inventory gained the missing `World Class Track Meet (U)` row (row 41, mapper 3, 32 KB PRG / 32 KB CHR), and the "All 38 are mapper 0 / 16 KB PRG" sentence is replaced with the actual split (36 of the 41 rows are mapper 0 / 16 KB; `Xevious (U)` and `Volleyball (U)` are 32 KB, `World Class Track Meet (U)` is mapper 3, `Zanac (U)` mapper 2 and `Mermaids of Atlantis (U)` mapper 8).
## History
Entries move here when the commit they describe is made, newest first. The
commit subject is the heading; the entries are the changes it carried.
### 2026-10-21 - Xevious (U): re-split Pass 1 from the Mesen CDL and decode the data tables
- **Xevious (U)** - Pass 1 re-split from the Mesen CDL (`xevious_mesen.cdl`) with `_tools/cdl_reclass.py`: 1,158 bytes data→code, 48 code→data, 42 labels emitted and 3 branch targets labelled; code 11,321→12,455 bytes (34.5%→38.0%), instructions 5,513→6,002. The 45 recovered entry points are named `Sub_XXXX`, so no `Label_XXXX` remains; six CDL-silent raw call operands are documented as residue.
- **Xevious (U)** - the 4,448-byte block at $A74B-$B8AA is split into six proven tables: `VramWritePtrTable` (15 pointers), `VramWriteData` (descriptors written to $2006/$2007), `DataStreamPtrTable` (16 pointers), `ObjTilePtrTable` (99 pointers), `ObjTileData` and `DataStreamData`. The $D833 pointer table is corrected to base $D833 (4 entries; the old `ObjCodePtrTable` at $D834 was one byte late). $F957-$FAF5 is split into `ObjSpeedTable`, `ObjSpeedTable2`, `SpriteLayoutPtrTable` (19 pointers) and `SpriteLayoutData`; $FEE6-$FF1C into `PaletteData` and `OamAttrTable`. `$F5D8` is decoded as `TextTileData` (font tile indices: PLAYER, GAME OVER, READY, SOLVALOU, LEFT, PAUSE); `$F53C` becomes `AttrAddrTable`, `$F89E` `HandlerPtrTable` and `$EF3B` `SpriteLayoutData2`. Project README rewritten with the corrected stats, a 32-entry table inventory and the Pass 1 residue.
- **_tools/cdl_reclass.py** - preserve the data label(s) that sit between a `; ---- data` header and its first `.byte` row when the block stays data. The $DF78 split dropped `Data_DF78`, which unchanged code still referenced, so the rebuild failed with an undefined symbol.
- **_tools/resolve_raw_branches.py** - handle negative relative offsets (`beq *-$0B`); the pattern only matched `*+$NN` and `*$NN`, so backward branches could not be resolved.
### 2026-10-21 - Golf (JU) and World Class Track Meet (U): Pass 2/3 complete, promoted from `_wip/`
- **World Class Track Meet (U)** - Pass 2 complete: all 884 `Label_<addr>` definitions replaced (651 semantic routine names + 233 `Sub_<addr>`), all 731 raw `$XXXX` jsr/jmp call operands resolved to symbolic labels, all branch targets given role-based names; `routinemap.tsv` added; `make` stays byte-identical.
- **World Class Track Meet (U)** - Pass 3 complete: 24 semantic zero-page aliases applied via `apply_symbols.py` (0 residue), 78 neutral `ZpXX` slots documented with reasons in `locals.inc`, all hardware-register operands use `symbols.inc` names, project README rewritten with Pass 2/Pass 3 sections and data-table inventory; project is ready for promotion out of `_wip/CNROM/`.
- **World Class Track Meet (U)** - project README now says what the five entries of the event table at $F796 line up with (the five *single* events of the six-item menu) and marks the sixth item, the "olympics", as not yet proven: the menu's own code is still outside the traced set, so the mode that schedules several of the five task slots at once is the expected answer, not a proven one.
- **Golf (JU)** - audit comments converted from pre-canonical (`; C000: A9 00`) to the canonical `; CPU:$C000 PRG:0000 A9 00` form at column 35 via `_tools/repair_audit_comments.py` then `_tools/align_audit_comments.py`; 4,156 comments re-aligned, comment/whitespace only, whole-ROM build stays byte-identical.
- **Golf (JU)** - 339 internal branch-target `Label_` labels given role-based names (`<Routine>_Loop`, `<Routine>_OnZero`, …) via `_tools/derive_branch_names.py` from `routinemap.tsv` and applied with `_tools/apply_pass2_map.py`; 10 fall-through-only labels keep their `Label_<addr>` definitions; 0 raw `$XXXX` branch/jump operands remain.
- **Golf (JU)** - 275 zero-page operands substituted with `locals.inc` aliases via `apply_symbols.py`; all hardware-register operands already symbolic; 0 multi-alias residue; no unexplained numeric operands left.
- **Golf (JU)** - project README updated: Pass 2/Pass 3 marked complete, audit-comment and Pass 3 sections rewritten, `routinemap.tsv` added; project is ready for promotion out of `_wip/NROM/`.
- **Golf (JU)** and **World Class Track Meet (U)** - promoted out of `_wip/` (`git mv` to `NROM/Golf (JU)/` and `CNROM/World Class Track Meet (U)/`); leftover `_wip/` folders removed; root `README.md` inventory rows added; `WIP.md` rows removed.
- **Xevious (U)** - runs of `$FF` padding replaced with `.res <count>, $FF` in `prg.s`; whole-ROM build stays byte-identical.
### 2026-10-21 - World Class Track Meet (U): Pass 1, the code/data split
- **World Class Track Meet (U)** - Pass 1 done. The code/data split is 8,400
- **World Class Track Meet (U)** - four dispatch tables had to be seeded by
- **World Class Track Meet (U)** - the tracer runs with `--undocumented`: the
- **World Class Track Meet (U)** - `$C0BE-$C0C5` is forced back to data: the
- **World Class Track Meet (U)** - `make pass1` regenerates `prg.s` and
- **_tools/nesdis.py** - new `--mapping-note` option, so the header's "PRG
- **Docs** - the project README records the split, the four dispatch tables, the
### 2026-10-21 - Balloon Fight (JU): repair the audit trail and complete the routine headers
- **Balloon Fight (JU)** - the per-instruction audit trail was repaired. 5,944 of
the 6,007 comments had been stale by two bytes since the three-byte `.byte "HAL"`
signature at $C082-$C084 was counted as one, so every comment from
`ResetInitializationData` ($C085) onward named the wrong CPU address and PRG
offset; the routine headers and the linker labels were right, so the source and
its own headers disagreed. The trail was rebuilt from the `ca65 -l` listing with
`_tools/repair_audit_comments.py` and every rewritten comment was re-checked
against `prg.bin`.
- **Balloon Fight (JU)** - the audit comments were moved into the canonical
column-35 field. They had sat two spaces after the mnemonic, with no column
discipline at all, unlike every other promoted project.
- **Balloon Fight (JU)** - all 63 routine headers now carry a `; Clobbers:` block,
so the headers carry the full template `AGENTS.md` describes. The blocks are
derived, not written by hand: `_tools/derive_clobbers.py` takes the opcode from
the audit comment's byte list, resolves the operand through `locals.inc` and
`symbols.inc` to name what is written, follows the real control flow, and models
register preservation - so `NmiHandler` reports *no register* and
`FlushPpuCommandPreserved` reports only A.
- **Balloon Fight (JU)** - `ReflectObjectYVelocity` and `UpdateSpecialObjectSystem`
moved out of `locals.inc` and became labels in `prg.s` at their real addresses.
- **_tools** - new `derive_clobbers.py`, which fills in the `; Clobbers:` block of
every routine header from the source.
- **_tools** - `align_audit_comments.py` had an off-by-one: it tested the
*indented* code length against 31 instead of against 35, so code texts of 28-31
characters were never padded into the column.
- **Docs** - the project README gains the audit-trail and clobber sections, the
root README and `TODO.md` carry the same news, `AGENTS.md` and `PROMPTS.md`
describe this changelog's new shape, and `CHANGELOG.md` itself becomes the
running log with a pending list.
- **WIP.md** - `_wip/MAPPER8/` is gone; it held a copy of `Mermaids of Atlantis (U)`
that had already been promoted.
---
## The milestone index
The four milestones every project walks through, and the state of each
project against them.
### The four milestones
| Milestone | What it does | How it is checked |
|-----------|--------------|-------------------|
| **Pass 1** | The code/data split: every ROM byte is classified as an instruction or as data, with the audit comment (`; CPU:$C123 PRG:0123 AD 21 03`) on every instruction. | Every byte of the PRG image is accounted for exactly once, and the audit comments re-check against `prg.bin`. |
| **Pass 2** | The labels are replaced by names: the address-derived `Label_XXXX` definitions become semantic routine names, and the internal branch targets get role names (`<Routine>_OnNonzero`, `<Routine>_Loop`). | No `Label_XXXX` definition is left, no branch or jump operand is a raw `$XXXX`, and every label is defined exactly once. |
| **Pass 3** | The semantic naming: the data tables, the zero-page aliases and the hardware register operands get the names the dump proves, and the routine headers are written. | `apply_symbols.py` reports no unexplained residue, and every alias that is not proven is recorded with its reason. |
| **Promotion** | The project moves out of `_wip/` into its mapper folder with the whole-ROM build in place. | `make` in the project folder prints **Byte-identical ROM verified.** against `rom.nes`. |
A project is only promoted when Pass 2 and Pass 3 are done, the promotion
requirements in `PROMPTS.md` are met, and the whole ROM rebuilds byte for
byte. `PROMPTS.md` is the contract; this file is the history.
**On the dates.** A date is the day the repository records the milestone:
the commit that carried it, or the day the project README dates the work.
Where neither does, the milestone is dated to the wave it was committed
with - the 2026-10-15 build standardisation, the 2026-10-18 `_wip` pass-1
wave, the 2026-10-19 naming wave, or the 2026-10-20 promotion wave. A
milestone that is still open says so in the row.
### The tiers
- **Promoted** — 41 projects in the top level `NROM/`, `CNROM/`, `UNROM/` and
`MAPPER8/` folders. Each one below has been through all four milestones
unless its entry says otherwise.
- **`_wip/`** — 851 projects that are still Pass 0 skeletons: `prg.s` is a
single `.incbin "prg.bin"`. They have a build and a byte-identical
rebuild, but no disassembly yet. `Golf (JU)` and `World Class Track Meet
(U)` were the tier's last two real disassemblies and were both promoted on
2026-10-21, so no project in the tier carries one now.
### Balloon Fight (JU) — `NROM/Balloon Fight (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-16 | First disassembly 2026-10-09; verified complete on the 16th: 5,303 instructions / 11,260 code bytes (68.7 %). The last two `.incbin` spans were turned into explicit classified bytes, so no ROM byte is hidden. |
| Pass 2 | 2026-10-19 | Every label renamed; the zero-page aliases written into `locals.inc`. |
| Pass 3 | 2026-10-19 | 125 hardware and 797 of 813 zero-page operands substituted; the 16 that stay numeric are recorded. 2026-10-21: the audit trail was repaired - 5,944 comments had been stale by two bytes since a three byte `.byte "HAL"` signature had been counted as one. 2026-10-21: every routine header now carries a derived `; Clobbers:` block (63 of 63), so the headers carry the full template - global, local, parameters, returns, clobbers. |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. |
### Baseball (UE) — `NROM/Baseball (UE)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-09 | First disassembly; `prg.s` is the largest source in the set at 21,624 lines. |
| Pass 2 | 2026-10-19 | Labels renamed in the audit-comment standardisation wave. |
| Pass 3 | 2026-10-19 | 121 operands substituted (85 single-name + 36 hardware), zero residue. |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. |
### Bomberman (U) — `NROM/Bomberman (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-09 | First disassembly. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | 354 single-name and 8 site-resolved multi-alias operands applied, 24 table labels taken from the linker map. Residue recorded: 758 unnamed operands over 179 distinct addresses. |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. | The build fix: `RandomStateAlt = $E4` beside `RandomState0 = $54` for the reused zero page. |
### Burger Time (U) — `NROM/Burger Time (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-09 | First disassembly; byte identical out of the box. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | Symbols applied. |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. |
### CIRCUS — `NROM/CIRCUS/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-16 | Full code/data classification; the main loop is a spin loop at $C057 and every frame's work runs in the NMI. |
| Pass 2 | 2026-10-16 | Semantic routine naming. |
| Pass 3 | 2026-10-19 | 118 operands substituted (38 single-name + 80 hardware); 23 multi-alias residues recorded. |
| Promotion | 2026-10-16 | Promoted out of `_wip/`; the menu text table at $C763 and the variant object machine at $DC3F-$FE7B documented. |
### Clu Clu Land (JU) — `NROM/Clu Clu Land (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-09 | First disassembly. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | Symbols applied. |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. | The build fix: a `bpl` the flat disassembler had mislabelled at $FAB4, written as `bne *-$1B` to reproduce the ROM bytes. |
### Defender 2 (U) — `NROM/Defender 2 (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-09 | First disassembly. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | Symbols applied. |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. | The build fix: the same `bpl` mislabel, at $E811. |
### Donkey Kong (JU) — `NROM/Donkey Kong (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-18 | 6,014 instructions / 12,505 code bytes (76.3 %); the reset entry is at $C79E, not $C000. |
| Pass 2 | 2026-10-19 | All 919 `Label_XXXX` definitions named: 102 semantic routine names, 217 `SubC<addr>` entries and 600 derived internal branch targets. |
| Pass 3 | 2026-10-19 | 10 named data regions, 75 operands substituted. |
| Promotion | 2026-10-19 | `git mv` out of `_wip/`; the mirroring was corrected from Vertical to Horizontal (header byte 6 = $00). |
### Donkey Kong 3 (JUE) — `NROM/Donkey Kong 3 (JUE)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-16 | The build was split into `header.s` / `prg.s` / `chr.s`, and a one byte branch-target bug was fixed: the `bne` at $C14C was labelled `StoreSelectedPlayerAndScreenFlags` instead of the routine at $C160, so the project had never actually built byte identical. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | Symbols applied. |
| Promotion | 2026-10-15 | Top-level wave: the build was standardised and the project got its power-on README. |
### Donkey Kong Jr. (JU) — `NROM/Donkey Kong Jr. (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-16 | Verified complete by a byte-accounting audit: all 16,384 PRG bytes are emitted exactly once (6,135 instructions + 3,889 `.byte` + 16 `.word`), with no audit-comment mismatch and no `.incbin` left. 75.4 % code. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | The tables named - `DeferredTaskHandlerTable`, `HudDigitDescriptorTable` and the rest. |
| Promotion | 2026-10-16 | Promoted out of `_wip/`. Architecturally different from the rest: the reset idles in a PRNG loop and the whole frame state machine runs inside the NMI. |
### Donkey Kong Jr. Math (U) — `NROM/Donkey Kong Jr. Math (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-19 | 6,589 instructions / 13,416 code bytes (81.9 %). |
| Pass 2 | 2026-10-19 | Restarted from the committed split after the 2026-10-18 draft map was audited and found to have no safely applicable row; 1,035 labels named (64 semantic + 295 `SubC<addr>` + 676 internal). |
| Pass 3 | 2026-10-19 | 18 data tables named, 13 semantic zero-page aliases, all multi-alias operands substituted. |
| Promotion | 2026-10-19 | Top level; the whole-ROM verify closed on 2026-10-20 after four call sites that named a back-branch block instead of the routine it belongs to were repointed. |
### Duck Hunt (JUE) — `NROM/Duck Hunt (JUE)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-19 | 3,058 instructions / 6,152 code bytes (37.5 %). |
| Pass 2 | 2026-10-19 | Restarted from the committed split; 472 labels named (30 semantic + 428 `SubC<addr>` + 293 internal). |
| Pass 3 | 2026-10-19 | 20 data tables named, 18 semantic zero-page aliases. |
| Promotion | 2026-10-19 | Top level. |
### Excitebike (JU) — `NROM/Excitebike (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-09 | First disassembly. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | The audit comments were completed - 1,013 lines had none. 2026-10-20: the trail was re-anchored from the `ca65` listing (6,339 shifted comments and 4,401 doubled `??` forms) and all 58 raw `jsr`/`jmp` operands were given routine names. |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. | The build fix: two NMI operands that spend their byte on `$11` were emitted with the wrong shadow name. |
### Golf (JU) — `_wip/NROM/Golf (JU)/` — *ready for promotion out of `_wip/`*
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | The whole-ROM compare was added: the project builds byte identical. 4,217 reachable instructions in `prg.s` (13,541 lines); all remaining `.incbin` spans confirmed data with zero code entry points. |
| Pass 2 | 2026-10-21 | All 112 subroutine entries named (4 semantic + 108 `SubC<addr>`); all jsr/jmp call sites symbolic, 0 raw `$XXXX` call operands; 339 of 349 internal branch targets given role-based names (`<Routine>_Loop`, `<Routine>_OnZero`, …); 10 fall-through-only labels keep their `Label_<addr>` definitions. |
| Pass 3 | 2026-10-21 | Audit comments canonical at column 35 (4,156 re-aligned via `_tools/repair_audit_comments.py` + `_tools/align_audit_comments.py`); all hardware-register operands use `symbols.inc` names; 275 zero-page operands substituted with `locals.inc` aliases via `apply_symbols.py`, 0 residue; every branch/jump target symbolic. |
| Promotion | — | Outstanding (awaiting `git mv` to `NROM/Golf (JU)/` plus root `README.md` inventory row). |
### World Class Track Meet (U) — `_wip/CNROM/World Class Track Meet (U)/` — *ready for promotion out of `_wip/`*
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-21 | The code/data split is done: 8,400 instructions / 18,028 code bytes (55.0 %) of the 32 KB PRG, 884 routine entries, 55 data blocks, 102 zero-page aliases. The PRG is CNROM (mapper 3) and maps whole at $8000-$FFFF, so the linker moved the PRG segment from a file offset to $8000. Four dispatch tables had to be seeded by hand: the event table at $F796 (5 entries, read at $F780 and jumped to through `jmp ($001F)`) and three push-pointer tables - $BFC4 (16), $BFE4 (2) and $E5F2 (7) - which store the handler address *minus one*, because the handler is pushed and an `rts` lands on it. The tracer runs with `--undocumented`: the code uses undocumented NMOS opcodes as ordinary code. Seeding the tables takes the coverage from 27.8 % to 55.0 %. The rebuild is byte identical. |
| Pass 2 | 2026-10-21 | All 884 `Label_XXXX` definitions replaced: 651 semantic routine names (`Reset`, `NmiHandler`, `MainLoop`, `TaskDispatch`, `EventInit`, `EventTaskRun`, `SpriteSetup`, `ObjectState`, `SoundNote`, `OlympicsScheduler`, …) plus 233 `Sub_<addr>` address-derived residue. All 731 raw `$XXXX` jsr/jmp call operands resolved to symbolic labels; every branch target given a role-based name (`_Loop`, `_OnZero`, `_OnNonzero`, …); `routinemap.tsv` holds the address→name map. |
| Pass 3 | 2026-10-21 | 24 semantic zero-page aliases applied via `apply_symbols.py` (0 residue), 78 neutral `ZpXX` slots documented with reasons in `locals.inc`, all hardware-register operands use `symbols.inc` names, data-table inventory documented in the project README. |
| Promotion | — | Outstanding (awaiting `git mv` to `CNROM/World Class Track Meet (U)/` plus root `README.md` inventory row). |
### Hogan's Alley (JU) — `NROM/Hogan's Alley (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | The static trace had classified only 41.8 % of the PRG as code. A merged Mesen CDL capture (five captures, 6,544 code bytes) moved 1,216 bytes from data to code and five the other way, taking the split to 49.1 %. |
| Pass 2 | 2026-10-20 | A fresh map from this dump's own committed split: 206 routine entries hand-named and 413 internal branch targets derived. |
| Pass 3 | 2026-10-20 | 60 semantic zero-page aliases, each applied only where its role is proven. |
| Promotion | 2026-10-20 | Top level. |
### Ice Climber (JE) — `NROM/Ice Climber (JE)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-19 | 6,112 instructions / 12,230 code bytes (74.6 %). |
| Pass 2 | 2026-10-19 | Restarted from the committed split; 973 labels named (76 semantic + 212 `SubC<addr>` + 685 internal). |
| Pass 3 | 2026-10-19 | 9 semantic zero-page aliases, the hardware operands substituted, the data tables named. |
| Promotion | 2026-10-19 | Top level. The PRG and the header are byte identical to the (U) dump; only the CHR differs. |
### Ice Climber (U) — `NROM/Ice Climber (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-19 | 6,112 instructions / 12,230 code bytes (74.6 %) - the same PRG as the (JE) dump. |
| Pass 2 | 2026-10-19 | 973 labels named. |
| Pass 3 | 2026-10-19 | 9 semantic zero-page aliases and the hardware operands substituted. |
| Promotion | 2026-10-19 | Top level, together with the (JE) dump. |
### Joypad Test Cartridge (U) — `NROM/Joypad Test Cartridge (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-16 | Redone: the first pass claimed 282 instructions / 580 bytes (3.5 %), because the tracer halted on `DCP $3C20` - an undocumented opcode used as ordinary code - and filed 3,256 bytes of real code as data. Now 1,773 instructions / 3,836 bytes (23.4 %). |
| Pass 2 | 2026-10-19 | All 202 labels renamed and all 202 routine headers rewritten; the zero-page aliases written. |
| Pass 3 | 2026-10-19 | 47 hardware operands substituted, the data blocks named. |
| Promotion | 2026-10-16 | Promoted out of `_wip/`. |
### Lode Runner (U) — `NROM/Lode Runner (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-18 | 11,057 lines, 627 label definitions, 52.6 % code, canonical audit comments. |
| Pass 2 | 2026-10-20 | All 627 labels renamed: 196 semantic routine entries plus 431 derived internal branch targets. |
| Pass 3 | 2026-10-20 | 85 operands substituted, 2 semantic zero-page aliases, the data tables named. |
| Promotion | 2026-10-20 | The whole-ROM build was added and the `_tools` paths moved. |
### Lunar Pool (U) — `NROM/Lunar Pool (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-18 | The split was re-derived from a Mesen CDL capture (10,028 bytes of code) after a static trace alone had left most of the game unclassified: now 5,300 instructions / 11,077 bytes (67.6 %). |
| Pass 2 | 2026-10-18 | 705 labels named, zero `Label_` residue. |
| Pass 3 | 2026-10-18 | 33 data tables named, 38 semantic zero-page aliases; 45 operands substituted on 2026-10-19. |
| Promotion | 2026-10-18 | `git mv` out of `_wip/`; the power-on flow and the print-inline-string helper documented. |
### Mario Bros (JU) — `NROM/Mario Bros (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | The committed split was a strict subset of the correct one - only 72.0 % was classified as code. A Mesen CDL capture (10,915 code bytes) showed 1,010 bytes the tracer had left as data were code, and two branch targets the capture never reached were forced by hand, so 1,067 bytes moved from data to code: 78.4 %. The engine's handler tables sit inline, right behind the `jsr` that reads them. |
| Pass 2 | 2026-10-20 | 206 routine entries and 519 internal branch targets, 931 `Label_XXXX` definitions gone, 51 raw call operands resolved. |
| Pass 3 | 2026-10-20 | 25 semantic zero-page aliases, each applied only where its role is proven. |
| Promotion | 2026-10-20 | Top level. |
### Millipede (U) — `NROM/Millipede (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-18 | 14,744 lines, canonical audit comments, 74.6 % code. |
| Pass 2 | 2026-10-20 | All 839 address-derived labels renamed: 12 semantic routine names, 264 `SubC<addr>` entries and 577 internal branch targets. |
| Pass 3 | 2026-10-20 | 8 semantic zero-page aliases; the data tables named - `LevelData`, `ObjectInitData`, `AudioData`, `VectorPageData`. |
| Promotion | 2026-10-20 | The whole-ROM build was added and the `_tools` paths moved. |
### MUSCLE (U) — `NROM/MUSCLE (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-16 | The bytecode VM layer was decoded: 40 opcodes handled through a table at $9237, so the "data" under the bytecode is code. 5,253 instructions. |
| Pass 2 | 2026-10-18 | The Pass 1/2/3 output written with the 42 bytecode listings above the `.byte` data. |
| Pass 3 | 2026-10-16 | The data names and the structures written. 2026-10-19: 220 operands substituted, zero residue. |
| Promotion | 2026-10-16 | Promoted out of `_wip/`. The one ROM in the set mapped low (PRG at $8000), and the only project with a `make regen` target that reproduces `prg.s` byte for byte. |
### NES PowerPad Test Card (U) — `NROM/NES PowerPad Test Card (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-16 | A minimal test cartridge: the NMI reads the PowerPad over $4016 and updates the score and the lives, 7.2 % code. |
| Pass 2 | 2026-10-19 | Labels renamed with the PowerPad group. |
| Pass 3 | 2026-10-16 | The data tables and the `VramWrite` streams named. 2026-10-19: 89 hardware operands substituted, zero residue. |
| Promotion | 2026-10-16 | Promoted out of `_wip/`. |
### Pac-Man (Tengen) (U) — `NROM/Pac-Man (Tengen) (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | Six command handlers recovered - 120 bytes the tracer had left as data, two of them mis-split across the `jmp $EF61` at $F01F and $F04F. 1,637 instruction lines covering 3,273 code bytes (20.0 %). The boot sequence is inline at $C033: this build has no boot code at $FF00. |
| Pass 2 | 2026-10-20 | A fresh map from this dump's own committed split - no name, map or file was carried over from the other Pac-Man dump. 227 labels (199 routine entries + 28 branch targets), zero `Label_` residue. |
| Pass 3 | 2026-10-20 | 30 semantic zero-page aliases, each applied only at the sites where the role is proven. |
| Promotion | 2026-10-20 | `git mv` out of `_wip/NROM/`. |
### Pac-Man (U) — `NROM/Pac-Man (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | 19.6 % code; the boot code sits at $FF00, unlike the Tengen build. |
| Pass 2 | 2026-10-20 | 194 `Label_XXXX` definitions renamed to semantic routine entries plus derived internal branch targets, and all 49 `jsr`/`jmp` call sites resolved. |
| Pass 3 | 2026-10-20 | 119 operands substituted (101 hardware + 11 single-name + 7 multi-alias resolved per site). |
| Promotion | 2026-10-20 | `git mv` out of `_wip/NROM/`. |
### Pac-Man (USA) (Namco) — `NROM/Pac-Man (USA) (Namco)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-09 | First disassembly. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | 524 single-name operands substituted; 727 multi-alias residues left numeric and recorded (an address with two or more aliases, e.g. `$00` = `workPtr0`/`Zp00`). |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. |
### Pinball (JU) — `NROM/Pinball (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-18 | 4,734 instructions / 9,756 code bytes (59.5 %) - a real disassembly, not a skeleton. |
| Pass 2 | 2026-10-18 | Substantial: 180 of 681 labels carry semantic names. The "Pass 2 complete" claim of that day was corrected on 2026-10-19 after an audit of the map. |
| Pass 3 | — | Drafted only: the zero-page aliases are not in `locals.inc` yet. |
| Promotion | 2026-10-20 | The whole-ROM build was added; the pass work is still open. |
### Popeye (JU) (PRG 0) — `NROM/Popeye (JU) (PRG 0)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-18 | 14,875 lines, canonical audit comments, 72.3 % code, six routine entries seeded from table references. |
| Pass 2 | 2026-10-20 | All 878 labels renamed: 2 semantic entry names, 315 `SubC<addr>` entries and 561 internal branch targets. |
| Pass 3 | 2026-10-20 | 4 semantic zero-page aliases, 79 operands substituted, the data tables named - `LevelData`, `AudioData`, `VectorPageData`. |
| Promotion | 2026-10-15 | Top-level wave: the build was standardised and the project got its power-on README. |
### Popeye (JU) (PRG 1) — `NROM/Popeye (JU) (PRG 1)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-18 | As the PRG 0 dump, but a different PRG binary. |
| Pass 2 | 2026-10-20 | All 878 labels renamed. |
| Pass 3 | 2026-10-20 | 4 semantic zero-page aliases and the data tables named. |
| Promotion | 2026-10-20 | Promoted out of `_wip/`. |
### Pyramid (U) (Sachen) — `NROM/Pyramid (U) (Sachen)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 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 hand-seeded starts recovered them, and lost no committed code byte. 39.6 % code. |
| Pass 2 | 2026-10-20 | 431 routine entries and the 32 data blocks named, 428 `Label_XXXX` definitions gone, 320 raw call operands resolved. |
| Pass 3 | 2026-10-20 | 24 semantic zero-page aliases, each applied only where its role is proven. |
| Promotion | 2026-10-20 | Top level; renamed to `Pyramid (U) (Sachen)` on 2026-10-21. The unlicensed boot pokes a mapper unlock at $4100 and dispatches through two queued-event tables. |
### Raid on Bungeling Bay (U) — `NROM/Raid on Bungeling Bay (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | 64.6 % code. |
| Pass 2 | 2026-10-20 | Labels renamed in the same wave as the other 2026-10-20 promotions. |
| Pass 3 | 2026-10-20 | 11 semantic zero-page aliases added to `locals.inc`. |
| Promotion | 2026-10-20 | Top level. |
### Raid on Bungeling Bay (U) [a2] — `NROM/Raid on Bungeling Bay (U) [a2]/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | 64.3 % code. A different PRG from the other dump - the two differ in mirroring only per the header, but the PRGs are separate builds. |
| Pass 2 | 2026-10-20 | Labels renamed. |
| Pass 3 | 2026-10-20 | 15 semantic zero-page aliases added to `locals.inc`. |
| Promotion | 2026-10-20 | Top level. |
### Tennis (JU) — `NROM/Tennis (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-09 | First disassembly; byte identical out of the box. |
| Pass 2 | 2026-10-19 | Labels renamed. |
| Pass 3 | 2026-10-19 | 18 single-name operands substituted, zero residue. |
| Promotion | 2026-10-09 | In the top level from the start - there was no `_wip/` tier yet. The build and the per-project power-on README were standardised on 2026-10-15. |
### Urban Champion (JU) — `NROM/Urban Champion (JU)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-18 | 2,716 instructions, 33.9 % code. |
| Pass 2 | 2026-10-18 | 436 labels named. |
| Pass 3 | 2026-10-19 | 10 semantic zero-page aliases, 70 operands substituted. |
| Promotion | 2026-10-18 | Promoted with the full-ROM build. |
### Volleyball (U) — `NROM/Volleyball (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-21 | Every byte of the 32 KB PRG image accounted for as an instruction or an explicit `.byte` block: 11,395 instructions / 23,926 code bytes (73.0 %). |
| Pass 2 | 2026-10-21 | 1,989 labels named. |
| Pass 3 | 2026-10-21 | 37 named data blocks, zero residue. |
| Promotion | 2026-10-21 | Promoted out of `_wip/NROM/`. |
### Wild Gunman (U) — `NROM/Wild Gunman (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-16 | Redone: the original tracer followed only the vectors and the direct calls and knew just the 151 documented opcodes, so it missed the runtime dispatch - the `pla` based computed goto puts the jump table inline right after the `jsr` - and filed about 4.9 KB of real code as data. 1,597 instructions / 3,352 bytes (20.5 %) became 3,956 / 8,085 (49.3 %). |
| Pass 2 | 2026-10-19 | All 733 labels carry names; zero `Label_Cxxxx` or `SubCxxxx` remain, and every entry point has a routine header. |
| Pass 3 | 2026-10-19 | The data tables named - `SpriteAttributeTable`, `NoteVolumeTable`, `VolumeEnvelopeTable`, `SpritePositionTable`; 76 operands substituted, zero residue. |
| Promotion | 2026-10-16 | Promoted out of `_wip/`. |
### Xevious (U) — `NROM/Xevious (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | The static trace from the vectors reached only 13.6 % of the PRG. Declaring both jump tables with `--table` plus 92 hand-seeded entry points recovered the code behind the computed dispatch, reaching 34.5 %. Re-split on 2026-10-21 from the Mesen CDL (`_tools/cdl_reclass.py`): 1,158 data→code bytes, 38.0 % code, 6,002 instructions. |
| Pass 2 | 2026-10-20 | Every routine entry point has a semantic name and every raw `$XXXX` call operand was replaced. Re-checked after the 2026-10-21 re-split: the 45 recovered entries are named `Sub_XXXX`; six CDL-silent raw operands remain and are documented in the project README. |
| Pass 3 | 2026-10-20 | 32 named data tables (the $A74B-$B8AA block split into six proven tables on 2026-10-21) and about 20 semantic zero-page aliases. |
| Promotion | 2026-10-20 | Promoted out of `_wip/`. |
### Zanac (U) — `UNROM/Zanac (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-20 | The static trace from the vectors reached only 37.9 % of bank 7; banks 0-6 are still raw `.byte` data, pending the bank-switch analysis. |
| Pass 2 | 2026-10-20 | 133 semantic entry points. |
| Pass 3 | 2026-10-20 | 26 named data tables and 14 semantic zero-page aliases. |
| Promotion | 2026-10-20 | Promoted out of `_wip/`; the only promoted UxROM project, with the fixed bank in its own segment. |
### Mermaids of Atlantis (U) — `MAPPER8/Mermaids of Atlantis (U)/`
| Milestone | Date | Note |
|-----------|------|------|
| Pass 1 | 2026-10-21 | Redone, bank-aware: the 64 KB PRG is eight 8 KB MMC3 banks, and each is traced separately with the CPU window it is visible at, seeded from a Mesen CDL capture. 8,075 bytes of code (12.3 %) in 494 routines, up from about 200 bytes. The image carries the reset stub and the vector table twice, and the fixed bank is the fourth 8 KB bank rather than the last. |
| Pass 2 | 2026-10-21 | Every label named, no `Label_XXXX` left and no raw `$XXXX` branch or jump operand left; the banks that share a CPU window carry a `Bank4_` .. `Bank7_` prefix. |
| Pass 3 | 2026-10-21 | 13 semantic zero-page aliases, the routine headers written, the data tables listed in the project README. |
| Promotion | 2026-10-20 | Promoted - but the build was broken: a half-applied Pass 2 rename left eight undefined symbols. Rebuilt and verified on 2026-10-21. |
---
### Adding an entry
**For a change to any project**, add a line to **Pending** at the top of this
file: name the project, and say what changed. When the commit is made, its
message is written from those lines, and they move to **History**.
**For a project that reaches a milestone**, the milestone also gets a row in
the milestone index below, with the date and a sentence saying what the
milestone produced. The numbers that go in the row are the ones the project
README and the root `README.md` already carry: the instruction count, the
code coverage, the number of named labels, the number of semantic zero-page
aliases and the number of named data tables. A milestone that has not
happened gets a `-` in the date column and a note saying what is still open -
the point of the table is that a reader can see at a glance which projects
are done and which are not.
Reference in new issue View Git Blame Copy Permalink