Files
disasm/NROM/Pyramid (U)/routinemap.tsv
T
tmerrittandClaude Opus 4.8 49e117bfcc Fix Pass 3 symbol application and add promotion criteria to PROMPTS.md
- Apply symbols.inc hardware register names to Defender 2 (U) (51 operands)
- Apply symbols.inc hardware register names to Donkey Kong 3 (JUE) (36 operands)
- Add APU register symbols (-) to Defender 2 (U) and Donkey Kong 3 (JUE) symbols.inc
- Apply symbols to Donkey Kong Jr. Math (U) (80 operands: 11 single + 69 hardware)
- Apply symbols to Excitebike (JU) (786 operands: 785 single + 1 hardware)
- Add promotion criteria to PROMPTS.md: symbol/local substitution,
  ROM-specific semantic naming, and verification checklist

Add branch/jump target naming requirement to PROMPTS.md

All branches and jumps must target symbolic labels with descriptive names
derived from program flow role (e.g., _Loop, _Next, _Done, _Store, _Return),
never raw address literals. Adds criterion 8 to verification checklist.

Rename all OVERVIEW.md to README.md; add root README content to top-level

- Rename all OVERVIEW.md files to README.md throughout the repo (47 files)
- Prepend README.md content to top-level OVERVIEW.md before rename
- Fix apply_symbols.py NAME_RE regex to handle spaced assignments
- Apply symbols.inc to Defender 2 (U) (51 hardware operands)
- Apply symbols.inc to Donkey Kong 3 (JUE) (36 hardware operands)
- Apply symbols.inc to Donkey Kong Jr. Math (U) (80 operands: 11 single + 69 hardware)
- Apply symbols.inc to Excitebike (JU) (786 operands: 785 single + 1 hardware)
- Add missing Zp18/FrameCounter aliases to Excitebike prg.s
- Build all 27 top-level projects: byte-identical

Promote Donkey Kong Jr. Math back to _wip tier

Moves code from `copilot` folder and verifies each builds after

Add pre-commit hook for byte-identical verification

Add .git/hooks/pre-commit that runs 'make' then 'make clean' in each
project directory before committing. This ensures every project builds
byte-identical before any commit is accepted.

Also includes all file moves from the Donkey Kong Jr. Math (U) demotion
and other file restructuring from the session.

moves code out of copilot folder, its all AI generated.
Moves NROM games into NROM folder

removes copilot folder from Lunar Pool
Adds makefile to build all projects recursively

Updates docs to reflect changes in layout

Repromotes Donkey Kong Jr Math
Repromotes Excitebike
Promotes Popeye (JU) (PRG 1)
Updates Makefile to provide summary of build failure/success

Promote Raid on Bungeling Bay (U): Pass 2/3 partial, whole-ROM byte-identical

Move _wip/NROM/Raid on Bungeling Bay (U) to NROM/ and switch the build
from a PRG-only compare to a whole-ROM one:

  - header.s/chr.s added (one-line .incbin of header.bin / chr.bin)
  - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000)
    areas ahead of PRG ($C000, $4000)
  - rom.nes symlink to the space-containing original ROM name
  - Makefile builds header.o/prg.o/chr.o into reconstructed.nes and
    compares it against rom.nes ('Byte-identical ROM verified.')
  - one leftover neutral indirect operand jmp (Zp01) at $E2EC becomes
    jmp (IndDispatch01); apply_symbols.py reports 0 substitutions pending

README.md / TODO.md / AGENTS.md updated: 29 promoted, 7 in _wip/.

Pac-Man (U): Pass 2 complete (label renaming) + Pass 3 partial (ZP aliases, table names)

Pass 2 — fresh map derived from the committed split, not from any drafted
map (the drafted maps in other projects were audited and found not
applicable):

  - all 194 address-derived Label_XXXX definitions renamed to semantic
    routine-entry names plus <Routine>_<Role>_<addr> internal branch
    targets; zero Label_ remains
  - all 49 jsr/jmp call sites resolved from raw $XXXX to labels; zero
    raw $XXXX call operands remain
  - routinemap.tsv / derived_names.tsv record the derivation

Pass 3 (partial):

  - 15 proven semantic zero-page aliases added to locals.inc
    (GameState, NmiFlag, ScrollX/Y, PpuCtrlShadow, OamDmaPage,
    CocktailModeFlag, ActivePlayerFlag, GameplaySuspended, FrameCounter,
    StateTimer, Player1/2Input, ActiveInput, CopyrightVerified)
  - 112 operands substituted into prg.s (11 single + 101 hardware)
  - key data tables named: ProgrammerSig ($C0EB), GameStateDispatchTable
    ($C253), TitleScreenData ($C2FD), EntityPtrTable ($D912),
    AudioCommandTable ($EFDD)

Also corrects the README's claim that the RESET vector points at padding:
$FF00 holds real boot code (sei/cld, PPU off, double vblank wait, then
jmp ColdStart at $C042).

.gitignore: ignore reconstructed_prg.bin (build artifact of the _wip
Makefiles; '**/reconstructed.*' does not match the underscore form).

Promote Pac-Man (U): Pass 2/3 complete, whole-ROM byte-identical

Move _wip/NROM/Pac-Man (U) to NROM/ and switch the build from a PRG-only
compare to a whole-ROM one:

  - header.s/chr.s added (one-line .incbin of header.bin / chr.bin)
  - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000)
    areas ahead of PRG ($C000, $4000)
  - rom.nes symlink to 'Pac-Man (U) [!].nes' (the original ROM name
    contains a space and brackets)
  - Makefile builds header.o/prg.o/chr.o into reconstructed.nes and
    compares it against rom.nes
  - reconstructed.nes is 24,592 bytes, MD5 a69d310f8cae9397fbd39f204672b5c7
    - equal to the original ROM; the header/prg/chr splits were checked
    against the original before promotion and are byte-exact

Pass 3 residue closed.  The last 7 multi-alias zero-page operands are
resolved per site through a new sites.tsv, each proven from context
rather than guessed:

  - jmp ($0010) at $C250/$D3CA/$D90F/$D9B6 -> (DispatchPtrLo); each
    is immediately preceded by sta DispatchPtrLo/sta DispatchPtrHi
  - jmp ($00FE) at $EFDA -> (AudioHandlerPtrLo); preceded by
    sta AudioHandlerPtrLo/sta AudioHandlerPtrHi
  - sta a:$0000,y at $C048/$C089 -> a:Zp00,y; the literal zero-page
    base in the two ZP clear loops, so the neutral name is used rather
    than the semantic WorkPtrLo.  The 'a:' prefix survives the
    substitution, so the bytes stay 99 00 00 (sta abs,Y)

apply_symbols.py now reports 119 operands substituted (101 hardware,
11 single-name, 7 site) and 0 residue.

New tool _tools/align_audit_comments.py: re-aligns the audit comment to
column 35 after a substitution lengthens an operand (nesdis.py pads each
instruction to 31 characters).  Whitespace-only, so the byte identity
cannot change.  405 lines re-aligned in this project; all 2,387 audit
comments still match prg.bin at the stated PRG offset, 0 mismatches.

Docs: root README.md / TODO.md / AGENTS.md updated - 30 promoted, 6 in
_wip/; a per-project detail entry for Pac-Man (U) added; the stale
'Donkey Kong 3 (JUE) has no README.md' claim corrected (it has a
318-line one).

Promote Raid on Bungeling Bay (U) [a2]: Pass 3 complete, whole-ROM byte-identical

Move _wip/NROM/Raid on Bungeling Bay (U) [a2] to NROM/ and switch the build
from a PRG-only compare to a whole-ROM one:

  - header.s/chr.s added (one-line .incbin of header.bin / chr.bin)
  - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000)
    areas ahead of PRG ($C000, $4000)
  - rom.nes symlink to 'Raid on Bungeling Bay (U) [a2].nes' (the original
    ROM name contains spaces and brackets)
  - reconstructed.nes is 24,592 bytes, MD5 659d340a1e9d420eee28df13319b0094
    - equal to the original ROM; the header/prg/chr splits were checked
    against the original before promotion and are byte-exact

Pass 3 - 15 semantic zero-page aliases, each applied only at the sites
where its role is proven:

  - PpuCtrlShadow ($C2), 15 sites: the reset entry primes it right after
    'sta PPUCTRL', and every other use is an ora/and/eor followed by
    'sta PPUCTRL'
  - NmiPathSelector ($C4), 5 sites: written 1 at $C3E9 and 0 at $C962
  - GameState ($D6), 6 sites: 'cmp #$02' and used as an index at $C4C7
  - FrameSubCounter ($55), 6 sites: set to $0A at $C520, decremented per
    NMI at $C07B
  - PrngPeriodCounter ($EA) / PrngSeedB ($EB) / PrngState ($EC), 13 sites:
    the PRNG state
  - PtrLo ($00) / PtrHi ($01), 8 sites: the 16-bit pair $1C13 and $1610
    compared at $E785/$E791
  - IndDispatch01 ($01) / IndDispatch02 ($02), 3 sites: the computed
    dispatch at $E2EC
  - IndDispatch1B ($1B) / IndDispatch1C ($1C), 6 sites: the dispatch at
    $E7A3
  - IndDispatch17 ($17) / IndDispatch19 ($19): the dispatches at $E79D
    and $E7A0

Addresses that carry two names keep the neutral ZpXX name 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 at $E895/$E8D0.

New tool _tools/apply_zp_aliases.py does the per-site substitution:
apply_symbols.py only rewrites *numeric* operands, so it cannot rename an
operand that is already written as a neutral ZpXX name.  The tool keeps the
ca65 'a:' prefix (dropping it would turn 'sta a:Zp17,y' into a zero-page
store and change the bytes) and rewrites only the operand token, so the
audit comment survives byte for byte.

Naming correction in the promoted sibling.  Finishing this dump showed that
$EA was misnamed 'VBlankWaitCounter': the routine at $C412 is the game's
pseudo-random generator (the classic eor/asl/php/lsr/plp/rol scrambler,
called from thirteen gameplay sites, twice in a row at $CDF4/$CDF9 with the
second result masked #$07), so $EA is the scrambler's phase counter.
Renamed PrngPeriodCounter in both dumps and named $EB/$EC PrngSeedB /
PrngState.  The sibling's two 'sta a:IndDispatch17,y' operands were also
wrong - they are absolute stores to RAM $0017, not the dispatch pointer -
and are now 'a:Zp17,y', matching the file's 'a:' = absolute convention.

Audit-comment alignment re-done with _tools/align_audit_comments.py (1,040
lines here, 1,080 in the sibling).  Both files still match prg.bin at every
stated PRG offset: 5,467 and 5,483 audit comments, 0 mismatches.

Docs: root README.md / TODO.md / AGENTS.md updated - 31 promoted, 5 in
_wip/; per-project detail entries added for both Raid dumps.

Promote Pac-Man (Tengen) (U): Pass 2/3 from scratch, whole-ROM byte-identical

Move _wip/NROM/Pac-Man (Tengen) (U) to NROM/ and switch the build from a
PRG-only compare to a whole-ROM one:

  - header.s/chr.s added (one-line .incbin of header.bin / chr.bin)
  - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000)
    areas ahead of PRG ($C000, $4000)
  - rom.nes symlink to 'Pac-Man (Tengen) (U) [!].nes'
  - reconstructed.nes is 24,592 bytes, MD5 d34e7a74d8d2c231b6cc601210e28ad0
    - equal to the original ROM; the header/prg/chr splits were checked
    against the original before promotion and are byte-exact

Disassembled from scratch.  No name, map or file was carried over from the
sibling 'Pac-Man (U)' dump; the map was derived from this dump's own
committed split and the two were only compared afterwards.

Pass 2 (new tool _tools/apply_pass2_map.py):
  - all 194 Label_XXXX definitions renamed to semantic routine entries plus
    <Routine>_<Role> branch targets; zero Label_ remains
  - all 48 raw $XXXX jsr/jmp operands resolved to labels; zero raw $XXXX
    call or branch operands remain
  - the map is in routinemap.tsv

Pass 3:
  - 30 semantic zero-page aliases, each applied only at the sites where its
    role is proven (per-site choice in sites.tsv; the addresses that carry
    two roles keep the neutral ZpXX name elsewhere).  _tools/
    derive_zp_aliases.py records how the set was derived, and locals.inc
    records the reason for every remaining neutral slot
  - 28 data tables named (new tool _tools/name_data_region.py), including
    CharacterDataTable ($C66A) and CharacterNameStrings ($C67E), where the
    ROM itself names Blinky, Pinky, Inky and Clyde - which is why the four
    indexed entities are called ghosts and not 'actors'
  - apply_symbols.py reports 0 substitutions pending and 0 residue
  - audit-comment alignment re-done with _tools/align_audit_comments.py;
    all 2,479 audit comments still match prg.bin at the stated PRG offset

Pass 1 correction - six command handlers recovered (new tool
_tools/recode_region.py).  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 six
handlers tile $F00A-$F081 exactly.  The same gap exists in the promoted
'Pac-Man (U)' dump, which has not been corrected - recorded in both READMEs.

Residue (documented, not guessed): 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 promoted 'Pac-Man (U)' dump.  Re-deriving it is a Pass 1 job;
a Mesen Code Data Logger capture is the tool the repo uses for it.

Docs: root README.md / TODO.md / AGENTS.md updated - 32 promoted, 4 in
_wip/; a per-project detail entry added for the Tengen dump.

Promote Pyramid (U): Pass 1 corrected, Pass 2/3 complete, whole-ROM byte-identical

Move _wip/NROM/Pyramid (U) to NROM/ and switch the build from a PRG-only
compare to a whole-ROM one:

  - header.s/chr.s added (one-line .incbin of header.bin / chr.bin)
  - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000)
    areas ahead of PRG ($C000, $4000)
  - rom.nes symlink to 'Pyramid (U) (Sachen).nes'
  - reconstructed.nes is 24,592 bytes, MD5 aa285ff17f25dd05da5996b7466c59e2
    - equal to the original ROM; the header/prg/chr splits were checked
    against the original before promotion and are byte-exact

Pass 1 correction - the committed split was a strict subset of the correct
one.  This game dispatches through 'jmp' trampoline tables that live
*inside* the data regions, and the tracer cannot follow a jmp there, so
828 bytes of code were still marked as data.  Four such tables were found
($C01E 3 entries, $C02A 6, $C042 2, $C054 5) plus ten more entries at
$C000-$C01B; all sixteen targets decode as valid instructions.  Seeding
them, the $C800 boot mainline and six further code starts recovers the
whole lot, plus a five-byte stub at $DF89 (lda $33 / jmp $DECB) that sat
in a hole between two routines.  The re-trace loses NO committed code byte
and takes the split from 34.5% to 39.6% (3,130 instructions / 6,493 code
bytes).  'make regen' reproduces it, so the split stays verifiable.

Pass 2 - a fresh map derived from this dump's own committed split:
  - 428 Label_XXXX definitions renamed; zero Label_ residue
  - 320 raw $XXXX jsr/jmp operands resolved; zero raw $XXXX branch
    operands remain
  - 431 routine entries and the 32 data blocks named from the code
  - the internal branch-target names are derived mechanically from the
    branch that reaches them by the new _tools/derive_branch_names.py
    (beq -> OnZero, bne -> OnNonzero, bcc/bcs -> the carry cases, a
    backwards branch -> Loop)
  - recorded in routinemap.tsv

Pass 3:
  - 24 semantic zero-page aliases, each applied only where its role is
    proven; the 57 slots that stay neutral are each listed with the reason
    in locals.inc (the neutral set lives in zp_aliases.inc so that
    'make regen' can rebuild locals.inc from prg.bin)
  - 32 data tables named - TaskVectorTable1/2, LevelScriptData,
    MusicPeriodTable, SoundEnvelopeTable, the actor tables - recorded in
    data_region_names.tsv
  - apply_symbols.py reports 0 substitutions pending and 0 residue; no
    hardware register is left as a raw literal
  - the audit comments are now canonical on every line, data included
    (the old file carried only 'PRG:$xxxx' on its 1,358 data lines);
    all 3,762 audit comments match prg.bin at their stated PRG offset

Kept as-is, not 'cleaned up':
  - sta $4100 stays a raw operand.  The iNES header claims mapper 0 but
    the boot code writes past the NES register space; the ROM does not
    explain it, so it is recorded rather than guessed
  - the 'A'/'V' check on RAM $0120/$0121 and its seed/clear routines
    are named for what they do, not for what they are for
  - the ninth entry of the $C3A6 task vector table ($D820) is a junk
    slot and stays data

Docs: root README.md / TODO.md / AGENTS.md updated - 33 promoted, 3 in
_wip/; a per-project detail entry added.

Hogan's Alley (JU): Pass 1 correction, Pass 2, Pass 3, promoted to NROM/

The light-gun game whose engine dispatches through *inline* tables:
`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 all
six handler tables ($C124 19 entries, $C219 4, $C89C 14, $CDD1 1, $D234 2,
$D3D6 14) live inside the code stream and the static tracer cannot follow
them.

Pass 1 correction.  The committed split was a strict subset of the correct
one -- 41.8% of the PRG was classified 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 the other way, 59 labels
emitted.  The split is now 49.1% code (3,950 instructions, 8,041 bytes).
The four branch targets the reclassifier could not prove were turned into
labels by the new _tools/resolve_raw_branches.py.

Pass 2.  206 routine entries hand-named from this dump's own code 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.  No SubC<addr> residue was needed -- every entry the engine
reaches is named after what it does.

Pass 3.  60 semantic zero-page aliases, each applied only where its role is
proven (zp_aliases.inc, zp_alias_sites.tsv); the slots that stay neutral are
each listed with the reason.  All 34 data blocks named
(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.

Promotion.  header.s, chr.s and a HEADER/PRG/CHR linker.cfg added, rom.nes
symlinked to the original ROM; the whole-ROM cmp passes on the first
promoted build.  There is deliberately 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 prg.s is the maintained source of truth.

Tools changed:
  nesdis.py             --split/--note/--provenance options, so a data
                          region can carry its own name and explanation;
                          a forced-data address is no longer reported as a
                          recovered routine entry
  apply_pass2_map.py    can create the label for a call target the tracer
                          left unlabelled; no longer double-labels it
  apply_zp_aliases.py   --at-file, an address-based per-site list
  derive_branch_names.py keeps the map's own header instead of writing a
                          fixed one
  resolve_raw_branches.py  new: turns `bXX *+$NN` operands into labels
  build_hogans_map.py   new: the hand-written Pass 2 map builder

The existing regen pipelines (MUSCLE (U), Urban Champion (JU)) still
reproduce prg.s byte for byte.

Apply the symbols.inc register names at Pass 1; fix a dropped byte in cdl_reclass

nesdis.py now names the hardware registers as it renders the operands, so a
project's Pass 1 output already reads `lda PPUSTATUS` instead of `lda $2002`
and the Pass 3 apply_symbols.py step has nothing left to do for them.

  * nesdis.py --symbols FILE reads a symbols.inc-style file and substitutes
    the register names.  Only unambiguous entries in the $2000-$4017 window
    are used: $4017 is both JOY2 and APUFRAMECOUNTER, so it stays numeric
    and apply_symbols.py reports it as multi-alias residue, exactly as
    before.  The default is the symbols.inc next to --out, so a new project
    gets the names without asking; --no-symbols opts out.
  * The renderer records the operand's numeric value on the Insn, because
    operand_value() used to re-parse the operand text and could no longer
    read a name.
  * The controller bit masks in symbols.inc (PAD_A and friends) are
    constants, not addresses, and are still never substituted.

MUSCLE (U) and Urban Champion (JU) keep --no-symbols: their committed
prg.s was produced with the registers named by the Pass 3 apply_symbols.py
step, and the columns in those files reflect the in-place substitution.
Adding the missing apply_symbols.py step to both regen pipelines makes
them reproduce their committed prg.s byte for byte again - neither did
before this change (MUSCLE was 440 lines out, Urban Champion 772).

cdl_reclass.py had a bug that cost a byte: a region whose last source row
straddled the region's end was replaced by a regeneration of the region
only, so the tail of that row was dropped.  Mario Bros (JU) hit it at
$C595, where the rebuild came out one byte short and every label after it
shifted.  A region now covers the whole rows it replaces.

pass2.py reflow takes an optional column argument; the default is
unchanged (the ';' lands on the same column as before).

Mario Bros (JU): Pass 1 correction, Pass 2, Pass 3, promoted to NROM/

A two-player platformer whose handler tables are *inline*: the pointers sit
in the middle of the code stream, right after the `jsr` that reads them, so
the static tracer could never follow them.

Pass 1 correction.  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; two branch targets the
capture never reached ($E4CB and $E639) were forced with --override for 57
more, so 1,067 bytes moved from data to code and 22 moved the other way.
The split is now 78.4% code (6,210 instructions, 12,847 bytes).  The three
branch targets the reclassifier could not prove were turned into labels by
_resolve_raw_branches.py, which now refuses to put a label on a `.byte` row.

Pass 2.  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 a previous session had left as address-derived residue were
all named from this dump's own code.  Recorded in routinemap.tsv.

Pass 3.  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.

Promotion.  header.s, chr.s and a HEADER/PRG/CHR linker.cfg added, rom.nes
symlinked to the original ROM; the whole-ROM cmp passes on the first
promoted build.  There is deliberately 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 prg.s is the maintained source of truth.

Tools:
  apply_pass2_map.py     renames a label of any spelling -- SubC<addr> is
                          the honest residue form -- and its references
                          follow it; one combined pattern, so a 16,000-line
                          file does not need a substitution per label
  resolve_raw_branches.py refuses to label a data row
  build_mario_map.py      new: the hand-written Pass 2 map builder

Remove the old _wip/NROM/Mario Bros (JU) folder (promoted to NROM/)

Mario Bros (JU): add the promoted-tier header, CHR, rom.nes symlink and zero-page aliases

Moves _ROMS/<ROM> into _wip/<MAPPER>/<ROM>

Sync the docs and the skeleton tool with the 857-project _wip tier

The _wip/ tier now holds 857 projects across 30 mapper folders, all
building byte-identical for the whole ROM.  README.md, TODO.md and
AGENTS.md still described the old 39-project tier, so bring them in line
with WIP.md, which carries the tier's index.

The tier is no longer 39 projects of NROM-256 with a 16/32 KB PRG:
only two projects have a 16 KB PRG, 151 have 32 KB, 523 have 128 KB and
one has 1.5 MB, so most of it is a banked mapper whose image does not fit
the 6502's address space.  Those projects link their MEMORY areas at .nes
file offsets rather than CPU addresses, which is the only option and the
honest model; the 39 older projects keep the CPU-address layout because
their PRG really is one contiguous window.

make_skeleton.py gains the two layouts (--layout flat|cpu), the board
name for the mapper, and a fix for find_rom() mistaking the build
output reconstructed.nes for the source ROM.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-10-20 16:44:06 -04:00

12 KiB

1# Pyramid (U) (Sachen) — Pass 2 name map
2#
3# Derived from this dump's own committed split. Every name below was read
4# out of the code; nothing is generic where the ROM gives a better basis.
5#
6# Format: <CPU address><TAB><name>
7#
8# The routine entries (the task table, the engine routines and the boot
9# chain) are named by hand; the internal branch targets are derived from the
10# branch that reaches them by _tools/derive_branch_names.py:
11# beq -> OnZero bne -> OnNonzero
12# bcc -> OnCarryClear bcs -> OnCarrySet
13# bmi -> OnNegative bpl -> OnNonnegative
14# bvc -> OnOverflowClear bvs -> OnOverflowSet
15# a backwards branch (the target is below the branch) -> Loop
16#
17# The game dispatches through `jmp` trampoline tables that live inside the
18# data regions ($C000-$C01B and the data blocks at $C01E, $C02A, $C042 and
19# $C054). Those table entries are the game's *task* entries and are named
20# Task_<name>; the routines they jump to carry the plain name.
21#
22# Two vocabularies are used for the zero-page and RAM state:
23# * $02/$03 the 16-bit script pointer
24# * $00/$01 the high/low bytes of a VRAM address
25# * $04 the command-list sync flag
26# * $05/$06 the VRAM write position
27# * $0700/$0701 the VRAM command buffer (16-bit pointer)
28C000Task_PlayVramScript
29C003Task_CopyBlockToCommandBuffer
30C006Task_UploadPalette1
31C009Task_UploadPalette2
32C00CTask_FinishCommandList
33C00FTask_StrobeControllers
34C012Task_EmitVramAddressMarker
35C015Task_DrawSpriteAtPosition
36C018Task_ClearOamShadow
37C01BTask_AddToCounter
38C027Task_FlushVramCommandList
39C03CTask_Multiply16
40C03FTask_BuildVramCommandList
41C048Task_ShiftRight8
42C04BTask_ShiftLeft8
43C04ETask_SetPalette16
44C051Task_SetPaletteBlock16
45C063PlayVramScript
46C090PlayVramScript_CopyRun
47C0A0PlayVramScript_WriteData
48C0A8PlayVramScript_StoreCount
49C0ADPlayVramScript_NextCommand
50C0B3PlayVramScript_End
51C0B9CopyBlockToCommandBuffer
52C0CDCopyBlockToCommandBuffer_Loop
53C0DBUploadPalette1
54C0EDUploadPalette1_Loop
55C0FBUploadPalette2
56C10DUploadPalette2_Loop
57C11BFinishCommandList
58C122FinishCommandList_Wait
59C127FlushVramCommandList
60C139FlushVramCommandList_Loop
61C155FlushVramCommandList_WriteData
62C15BFlushVramCommandList_End
63C160StrobeControllers
64C16AReadControllers
65C188DrawSpriteAtPosition
66C192EmitVramAddressMarker
67C198BuildVramAddress
68C1B6ClearOamShadow
69C1BAClearOamShadow_Loop
70C1C1AddToCounter
71C1C4AddToCounter_Wait
72C1C9IncrementCounter16
73C1CFIncrementCounter16_End
74C1D0AdvanceScriptPointer
75C1D6AdvanceScriptPointer_Loop
76C1D7ConvertNibbleToBcd
77C1E2ConvertNibbleToBcd_Digit
78C1EAConvertNibbleToBcd_Store
79C1EFSetPpuCtrl
80C1F6WaitForVblankClear
81C1FBWaitForVblankSet
82C201SetPpuCtrlAndMask
83C205SetPpuCtrlAndMask_Alt
84C207SetPpuCtrlAndMask_Store
85C225StoreOamEntry
86C23ADrawTwoDigitNumber
87C256DrawTwoDigitNumber_Loop
88C25FDrawTwoDigitNumber_High
89C277EmitDigit
90C28AEmitDigit_SetFlag
91C28FEmitDigit_Store
92C294AddDeltaToPosition
93C2A0AddDeltaToPosition_Loop
94C2B6AddDeltaToPosition_Carry
95C2BEAddDeltaToPosition_Store
96C2E2AddDeltaToPosition_Carry2
97C2EAAddDeltaToPosition_Store2
98C2F9AddDeltaToPosition_End
99C300Multiply16
100C317BuildVramCommandList
101C31BBuildVramCommandList_SetAddress
102C32CBuildVramCommandList_Data
103C341BuildVramCommandList_Store
104C347BuildVramCommandList_End
105C34ACopyBlockToCommandBufferTail
106C354CopyBlockToCommandBufferTail_Loop
107C35FSetPaletteBlock
108C36DSetPaletteBlock_Loop
109C384ScanForButtonPress
110C386ScanForButtonPress_Loop
111C392DispatchTask1
112C3B6MoveSpriteRight
113C3C7MoveSpriteLeft
114C3D8ComputeOamSlotAddress
115C3E3MoveSpriteDown
116C3E7MoveSpriteUp
117C3EBMoveSpriteLeft2
118C3EFMoveSpriteRight2
119C3F0ClampSpriteToGrid
120C3FAClampSpriteToGrid_Redraw
121C3FDTask_ReturnStub
122C3FEBuildVramPositionWrite
123C43ESubtract16
124C460Subtract16_Loop
125C477Subtract16_Loop2
126C47ASubtract16_Loop3
127C49ASubtract16_Loop4
128C4B1Subtract16_Loop5
129C4B4Subtract16_Loop6
130C4B8ShiftRight8
131C4C0ShiftRight8_OnNonzero
132C4C7ShiftRight8_Loop
133C4D1ShiftLeft8
134C4D9ShiftLeft8_OnNonzero
135C4E4ShiftLeft8_Loop
136C4EBSetPalette16
137C4FDSetPalette16_Loop
138C50ASetPalette16_Entry
139C536SetPaletteBlock16
140C548SetPaletteBlock16_Loop
141C56DSetPaletteBlock16_Entry
142C585WriteDigitString
143C58FWriteDigitString_Loop
144C59DWriteDigitString_Loop_Loop
145C5A1WriteDigitString_Loop_Loop2
146C5ABAddDelta24
147C5B8AddDelta24_Copy
148C5C0AddDelta24_Loop
149C5E1AddDelta24_Borrow
150C614AddDelta24B
151C620AddDelta24B_Save
152C662SetPaletteEntry
153C676SetPaletteEntry_OnCarryClear
154C683SetPaletteEntry_OnCarryClear2
155C6A3SetPaletteEntry2
156C6BASetPaletteEntry2_OnNonnegative
157C6DBSetPaletteEntry2_OnCarryClear
158C800BootColdStart
159C805BootWaitForVblank
160C80ABootWaitForVblank2
161C815BootClearRam
162C835BootInitState
163C897BootFirstFrame
164C8A4BootDecCounters
165C8B8BootDecTimer
166C8D0BootCopySpriteData
167C8F2BootUploadPalette
168C90DBootCopyTableToBuffer
169C932BootCopyTableStart
170C934BootCopyTableLoop
171C9A7BootInitLevel
172CA1DBootCheckController
173CA32BootFrameCounter
174CA41BootDrawSprite
175CA61BootSetFlag
176CA68BootSelectTable
177CA80BootCopyTable
178CA97BootSetPaletteBlock
179CAF3BootInitPpu
180CB68ActorGridClear
181CB6CActorGridClear_Loop
182CB82ActorGridLookup
183CB99ActorGridRead
184CBADActorGridStart
185CBDCActorGridClamp
186CBE5ActorGridInit
187CBF9ActorGridFill
188CC11TaskScheduler
189CC3DTaskScheduler_Tick
190CC56TaskScheduler_Count
191CC5CTaskScheduler_Step
192CC71TaskScheduler_Scan
193CC73TaskScheduler_ScanLoop
194CC8BTaskScheduler_Button
195CC90TaskScheduler_Next
196CCA5TaskScheduler_Restart
197CCA8TaskScheduler_Accept
198CCB1DispatchTask2
199CCB8DispatchTask2_Build
200CCE5TaskScheduler_Return
201CCEETaskScheduler_Select
202CD07TaskScheduler_Compare
203CD18TaskScheduler_Compare_Loop
204CD23TaskScheduler_Compare_Loop2
205CD24TaskScheduler_Return2
206CD27TaskScheduler_Check
207CD43TaskScheduler_Check2
208CD72TaskScheduler_Return3
209CD75TaskScheduler_SetPointer
210CD80TaskScheduler_Wait
211CD85TaskScheduler_Wait2
212CD8ATaskScheduler_Wait3
213CDA4TaskScheduler_Finish
214CDACTaskScheduler_Advance
215CDBDTaskScheduler_Return4
216CDC0TaskScheduler_Start
217CDDCTaskScheduler_Place
218CE14TaskScheduler_CursorNext
219CE17TaskScheduler_Return5
220CE1ATaskScheduler_Move
221CE22TaskScheduler_MoveStep
222CE32TaskScheduler_Return6
223CE35TaskScheduler_Turn
224CE54TaskScheduler_TurnStep
225CE5BTaskScheduler_Return7
226CE5ETaskScheduler_Move2
227CE66TaskScheduler_Move2Step
228CE78TaskScheduler_Return8
229CE7BTaskScheduler_Turn2
230CE96TaskScheduler_Turn2Step
231CE9DTaskScheduler_Return9
232CEA0ActorPositionLookup
233CEA8ActorPositionLookup_Entry
234CED3TaskScheduler_Return10
235CED6ActorGridRebuild
236CEE0ActorGridRebuild_Row
237CEEBActorGridRebuild_Cell
238CEF6ActorGridRebuild_Next
239CF02ActorGridRebuild_NextRow
240CF0EActorGridRebuild_Column
241CF10ActorGridRebuild_ColumnStart
242CF14ActorGridRebuild_Slot
243CF29ActorGridRebuild_Copy
244CF35ActorGridRebuild_SlotEnd
245CF55ActorGridRebuild_Column2
246CF67ActorGridRebuild_Column2Loop
247CF74ActorGridRebuild_Copy2
248CF90ActorGridRebuild_Copy2End
249CF98ActorGridRebuild_Column2End
250CFC4ActorGridRebuild_End
251CFC7ActorGridNext
252CFFAActorGridNext_Reset
253CFFFActorGridNext_Start
254D020ActorGridNext_Start_Loop
255D02AActorSearch
256D036ActorSearch_Row
257D03DActorSearch_Slot
258D04AActorSearch_Match
259D074ActorSearch_Check
260D085ActorSearch_NotFound
261D087ActorSearch_Restore
262D0A0ActorSearch_Restore2
263D0ACActorSearch_Restore3
264D0ADActorSearch_Empty
265D0B6ActorSearch_Restore4
266D0B8ActorSearch_Next
267D0C3ActorSearch_Done
268D0D3ActorPositionTest
269D0DFActorPositionTest_Loop
270D0F5ActorPositionTest_Loop_Loop
271D0F8ActorPositionTest_Step
272D105ActorPositionTest_End
273D10DActorPositionTest_Match
274D134ActorPositionTest_Blocked
275D13CActorPositionTest_Taken
276D146ActorPositionTest_Compare
277D15BActorPositionTest_Blocked2
278D15EActorPositionTest_Compare2
279D16AActorPositionTest_Compare3
280D185ActorPositionTest_Next
281D190ActorPositionTest_Done
282D193RandomByte
283D1B2DrawActorRow
284D1BBDrawActorRow_Setup
285D1D7DrawActorRow_Copy
286D1ECDrawScore
287D1FDDrawLifeCount
288D20EDrawLevelNumber
289D21CDrawTileRow
290D227DrawTileRow_Loop
291D237DrawTileRow_Digit
292D23ADrawTileRow_Store
293D248DecimalSplit
294D24ADecimalSplit_Hundreds
295D253DecimalSplit_Tens
296D257DecimalSplit_Units
297D260DecimalSplit_Done
298D265DrawActorSprite
299D27FDrawActorSprite_Setup
300D2A0OamShadowClear
301D2A4OamShadowClear_Loop
302D2BFActorGridOffset
303D2EDActorGridOffset_Copy
304D3A1RandomWithinRange
305D3B5RandomWithinRange_Out
306D3B7ActorSpriteSetup
307D3BBActorSpriteSetup_Offset
308D41DActorSpriteSetup_State
309D424ActorSpriteSetup_Pos
310D42EActorSpriteSetup_Next
311D43EActorSpriteSetup_Draw
312D45AOamShadowClear2
313D45EOamShadowClear2_Loop
314D476OamShadowClear3
315D47FOamShadowClear3_Loop
316D488ActorSpriteSetup_Offset2
317D4B7OamShadowClear4
318D4BBOamShadowClear4_Loop
319D4C5ActorInitFromTable
320D50AActorUpdate
321D510ActorUpdate_Loop
322D512ActorUpdate_Slot
323D520ActorUpdate_Timer
324D530ActorUpdate_Move
325D54AActorUpdate_Next
326D555ActorUpdate_Done
327D56BActorUpdate_Anim
328D57AActorUpdate_AnimIndex
329D59AActorUpdate_Sprite
330D5ADActorUpdate_SpritePos
331D5CAActorUpdate_NextSprite
332D632ActorSpawn
333D63BActorSpawn_Setup
334D655ActorSpawn_Start
335D66DActorSpawn_Copy
336D679ActorSpawn_CopyLoop
337D6ACActorGridShift
338D6B2ActorGridShift_Row
339D6BBActorGridShift_Scan
340D6C9ActorGridShift_Next
341D6D6ActorGridShift_Dst
342D6E7ActorGridShift_Copy
343D6F6ActorGridShift_Copy_Loop
344D6FDActorGridShift_Copy2
345D720ActorGridShift_End
346D72CActorGridShift_Done
347D72ENmiHandler
348D78ANmiHandler_Body
349D793NmiHandler_Epilogue
350D79DNmiHandler_Number
351D79FNmiHandler_NumberLoop
352D7A8NmiHandler_NumberDigit
353D7B6WriteSoundRegister
354D7C5WriteSoundRegister_Loop
355D7D7SoundTableEntry
356D7E3IrqHandler
357D7EBColdStartAlternate
358DE9ASoundInit
359DEA9SoundInit_Copy
360DECBSoundPlayEffect
361DEFFSoundClearVoices
362DF0ESoundStopAll
363DF14SoundStopAll_Loop
364DF29SoundClearVoices_Loop
365DF80SoundTick
366DF89PlaySoundEffectFromSlot
367DF8ESoundTick_Voice
368DF9ASoundTick_Next
369DFA1SoundTick_Command
370DFACSoundTick_Command2
371DFB5SoundTick_Command3
372DFBFSoundTick_Command4
373DFD5SoundTick_Sample
374DFF4SoundTick_Volume
375E00CSoundTick_Volume2
376E017SoundTick_VolumeLoop
377E029SoundTick_Envelope
378E04BSoundPlayer
379E057SoundPlayer_Reset
380E05ESoundPlayer_Command
381E069SoundPlayer_Command2
382E072SoundPlayer_Command3
383E07CSoundPlayer_Command4
384E099SoundPlayer_Volume
385E0B1SoundPlayer_Volume2
386E0BCSoundPlayer_VolumeLoop
387E0CESoundPlayer_Envelope
388E0F0SoundPlayer2
389E0FCSoundPlayer2_Reset
390E103SoundPlayer2_Command
391E10ESoundPlayer2_Command2
392E117SoundPlayer2_Command3
393E121SoundPlayer2_Command4
394E13ESoundPlayer2_Volume
395E156SoundPlayer2_Volume2
396E161SoundPlayer2_VolumeLoop
397E173SoundPlayer2_Envelope
398E195SoundPlayer3
399E1A1SoundPlayer3_Reset
400E1A8SoundPlayer3_Command
401E1B7SoundPlayer3_Command2
402E1D4SoundPlayer3_Sample
403E1E9SoundPlayer3_Envelope
404E1FBSoundPlayer3_Write
405E20BSoundPlayer3_WriteLoop
406E215SoundPlayer3_Voice
407E220SoundPlayer3_VoiceLoop
408E226SoundPlayer3_VoiceLoop_OnCarryClear
409E230SoundPlayer3_Voice2
410E236SoundPlayer3_Voice2Loop
411E240SoundPlayer3_Decay
412E249SoundPlayer3_Decay2
413E24FSoundPlayer3_Decay2Loop
414E259SoundPlayer3_Done
415E25ASoundVoiceIndexAdvance
416E260SoundVoiceIndexAdvance_End
417E261SoundVoiceIndexAdvance2
418E267SoundVoiceIndexAdvance2_End
419E268SoundVoiceIndexAdvance3
420E26ESoundVoiceIndexAdvance3_End
421E26FSoundVoiceIndexAdvance4
422E275SoundVoiceIndexAdvance4_End
423ED6ESampleTableLookup
424EDB7SampleTableLookup_OnNonzero
425F891SampleTableRead
426F894SampleTableRead2
427F897SampleTableRead3
428F89ASampleTableNext
429F8A2SampleTableNext_OnNonzero
430F8ADSampleTableNext_Loop
431F8B2SampleTableNext_Loop2
432F8BCSampleTableNext_Loop3
433F8C0SampleTableNext_Loop4
434F8C4SampleTableNext_OnZero
435F8C5SampleTableNext_Loop5
436F8D8SampleTableNext_Loop6
437F8DDSampleTableNext_OnNegative
438F8EFSampleTableEnd
439F908SampleTableEnd_OnNonzero
440F914SampleTableEnd_Loop
441F922SampleTableEnd_Loop2
442F929SampleTableEnd_Loop3
443F93CSampleTableEnd_Loop4
444F941SampleTableCopy
445F942SampleDecode
446F951SampleTableCopy2
447F959SampleTableCopy2_Loop
448FF00Reset
449FF2FReset_Loop
450FF3EBootChainEntry
451FF49BootPokeMapperUnlock
452FF4CBootUnlockDelay
453FF4EBootUnlockDelay_OnNonzero
454FF50BootUnlockDelay_OnNonzero2
455FF57BootCheckStackBytes
456FF67BootCheckStackBytes_Fail
457FF69BootSeedStackBytes
458FF74ClearCheckerBytes