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).

MAPPER8/Mermaids of Atlantis (U)/Makefile

@@ -19,7 +19,10 @@ verify: reconstructed.nes rom.nes
 	cmp reconstructed.nes rom.nes
 	@echo "Byte-identical ROM verified."
 
+regen:
+	./regen.sh
+
 clean:
 	rm -f *.o reconstructed.nes reconstructed_prg.bin reconstructed.map reconstructed.lbl
 
-.PHONY: all verify clean
+.PHONY: all verify clean regen

MAPPER8/Mermaids of Atlantis (U)/README.md

@@ -1,61 +1,157 @@
 # Mermaids of Atlantis (U)
 
+*Imagineering, 1991 - "The Riddle of the Magic Bubble"*
+
 ## Status
 
-**Pass 1 complete.** The code/data split has been produced by `nesdis.py` and
-the project builds byte-identical to the original ROM. `prg.s` now contains
-traced code with audit comments and `.byte` data blocks for unreached bytes.
-
-`make` assembles `header.s`, `prg.s`, `chr.s`, links them with `ld65` and compares the
-result against `rom.nes`:
+**Pass 3 complete.**  The code/data split comes from a Mesen Code Data
+Logger capture, every routine and branch target carries a name, the
+zero-page aliases that the dump proves are applied, and `make` rebuilds the
+whole ROM byte for byte:
 
 ```
 Byte-identical ROM verified.
 ```
 
+`prg.s` is 8 075 bytes of disassembled code out of the 64 KB PRG image
+(12.3 %), in 494 routines.  The rest of the image stays as `.byte` blocks
+with their ROM provenance: the bytes the emulator never reached are not
+guessed at.
+
 ## ROM
 
 | Property | Value |
 |----------|-------|
 | Format | iNES |
-| Mapper | 8 |
-| Board | MAPPER8 |
+| Mapper | 8 (MMC3) |
+| PRG | 64 KB (8 x 8 KB banks), at file offset $0010 |
+| CHR | 64 KB (8 x 8 KB banks) |
 | Mirroring | Vertical |
-| Four-screen VRAM | no |
-| Battery | no |
-| PRG | 64 KB (4 x 16 KB), at file offset $0010 |
-| CHR | 64 KB (8 x 8 KB) |
 | Trainer | none |
-| Footer | none |
-| NMI vector | $8189 |
-| RESET vector | $FF00 |
+| Reset vector | $FF00 |
+| NMI vector | $808F (see "The two vector tables") |
 | IRQ vector | $8036 |
 | ROM file | `Mermaids of Atlantis (U).nes` |
 | SHA-256 | `53f5d22650063aba89b91762f133d1b6b2680c505b193d88a472580d09701122` |
 
-### Header notes
+## The banking
 
-- none
+The cartridge is an MMC3 with 64 KB of PRG - eight 8 KB banks.  The file is
+laid out in banks, and the game uses them like this:
 
-## Open work
+| Bank | File | CPU window | Role |
+|------|------|------------|------|
+| R0 | $0000-$1FFF | $8000-$9FFF | the game code, first half |
+| R1 | $2000-$3FFF | $A000-$BFFF | the game code, first half |
+| R2 | $4000-$5FFF | $C000-$DFFF | the game code, first half |
+| R3 | $6000-$7FFF | $E000-$FFFF | **the fixed bank**: the reset stub, the vectors, the text table |
+| R4 | $8000-$9FFF | $8000-$9FFF | the game code, second half |
+| R5 | $A000-$BFFF | $A000-$BFFF | the game code, second half |
+| R6 | $C000-$DFFF | $C000-$DFFF | unused |
+| R7 | $E000-$FFFF | $E000-$FFFF | a second copy of the fixed bank's tail |
 
-- **Pass 2** - replace the address-derived `Label_XXXX` names and the raw
-  `$XXXX` call operands.
-- **Pass 3** - semantic zero-page aliases (applied only at the sites where
-  their role is proven) and named data tables.
-- **Promotion** to `NROM/<name>/` once Pass 3 is done, as `git mv`.
+The mapper register is written through the fixed bank: `SwitchPrgBank`
+($FF70) does `ora #$30; sta $4100`, so the mode bits are forced on and the
+bank number is the low three bits of A.  `BankedCall` ($8004) is the game's
+own far-call: it stores the handler index in `HandlerIndex` ($2D), switches
+the PRG bank to the one in `PrgBankNumber` ($2C) and lets the caller fall
+into the new bank's code at the same CPU address.
+
+Because two banks can be visible at the same CPU address, the disassembly
+gives each bank its own label namespace: bank 0, 1, 2 and the fixed bank use
+plain names, banks 4 to 7 use the `Bank4_` .. `Bank7_` prefixes.  Every bank
+has its own segment (`PRG0` .. `PRG7`) and 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.
+
+## The two vector tables
+
+The image carries the reset stub and the vectors **twice**:
+
+| File | NMI | RESET | IRQ |
+|------|-----|-------|-----|
+| $7FFA (R3, the fixed bank) | $808F | $FF00 | $8036 |
+| $FFFA (R7, the last bank) | $8189 | $FF00 | $8036 |
+
+The fixed bank is the one the CPU sees, so the live NMI vector is **$808F**
+and the NMI handler is `NmiHandler` at $808F in bank 0.  The copy at the end
+of the image is what a mapper that fixes the *last* 8 KB of the PRG would
+use; it names an NMI handler at $8189, which is a `BRK` in the first half of
+the image.  The two stubs are byte identical from $FF00 to $FF7F, and the
+fixed bank carries one routine the last bank does not: `SwitchPrgBankKeepA`
+at $FF80.
+
+## Power-on flow
+
+```
+$FF00  Reset            ldx #$FF / txs / sei / cld
+                        clears PPUCTRL and PPUMASK
+                        SwitchPrgBank ($30) - the first PRG bank
+                        WaitForBankSwitch - the bank switch counter
+$FF2F  SelectChrBanks   picks the CHR banks of the first stage
+$FF3E  StartGame        SwitchPrgBank ($30), StartBankSwitchDelay,
+                        jmp $8036
+$8036  InitializeGame   sei / cld / WaitForVBlank
+                        clears the PPU and the work RAM
+                        InitGameVariables - the sound, scroll and sprite registers
+$8083  IdleWaitLoop     inc IdleCounter / jmp $8083 - the game waits for the NMI
+```
+
+From then on the frame handler does the work:
+
+```
+$808F  NmiHandler       StartVramWrite when the tile set changed
+                        UpdateNametable / UploadOam when the screen changed
+                        writes PPUCTRL, PPUSCROLL and PPUMASK
+                        ReadControllers - the pad bits
+                        UpdateGameState - the mode machine
+                        UpdateActorSprites / UpdateSprites
+                        BankedCall ($02) - the sound engine
+                        writes PPUCTRL and counts the frame
+```
+
+`$8036` is also the IRQ vector, so an interrupt re-runs the power-on path.
+
+## Data tables
+
+| Table | Where | What it holds |
+|-------|-------|---------------|
+| the digit and tile table | $F1D6, in the fixed bank | "0123456789" and the tile indices of the font |
+| the bank switch table | $8026, in banks 0 and 4 | the bank numbers, eight per half |
+| the handler jump tables | $8095 (bank 4), $9234, $C2AC | the addresses the dispatchers jump to |
+| the sprite table | $0338 | the 16 sprite slots: tile, attributes, position |
+| the actor table | $0358, $03A8 | the actors and the bubble slots |
+| the player table | $0400 | the player's position and direction |
+| the level script | $05E2-$05E9 | the stage, the wave and the timers |
+| the sound tables | $0700-$07FF | the sound engine of the second half |
 
 ## Files
 
 | File | Purpose |
 |------|---------|
-| `prg.s` | Pass 1 PRG disassembly (traced code + data blocks) |
-| `header.s` | iNES header include |
-| `chr.s` | CHR include |
-| `prg.bin` | 65536 bytes (64 KB) PRG image |
-| `chr.bin` | 65536 bytes (64 KB) CHR image |
-| `rom.nes` | byte-identical copy of the original ROM |
-| `linker.cfg` | HEADER / PRG / CHR memory areas |
-| `symbols.inc` | NES hardware register names |
-| `locals.inc` | zero-page aliases (5 ZpXX aliases at Pass 1) |
-| `Makefile` | build and byte-identity check |
+| `prg.s` | the disassembly, one segment per bank |
+| `header.s` | the iNES header |
+| `chr.s` | the CHR image |
+| `prg.bin` | the 64 KB PRG image |
+| `chr.bin` | the 64 KB CHR image |
+| `rom.nes` | a copy of the original ROM |
+| `linker.cfg` | one memory area per bank, at the file offsets |
+| `symbols.inc` | the NES hardware register names |
+| `locals.inc` | the zero-page aliases |
+| `routinemap.tsv` | the hand-written Pass 2 names |
+| `routinedesc.tsv` | the hand-written routine descriptions |
+| `labelmap.tsv` | the full Pass 2 map (generated) |
+| `regen.sh` | rebuilds `prg.s` from the ROM and the CDL capture |
+| `Makefile` | the build and the byte-identity check |
+
+## Rebuilding
+
+```
+make          # build and verify against rom.nes
+./regen.sh    # re-derive prg.s from the ROM and a Mesen CDL capture
+```
+
+`regen.sh` needs a Mesen CDL capture of the game; the file is not kept in
+the repository.  Take it with Mesen (load the ROM, play for a while, then
+`mesen_cdl_file(action='save', memoryType='NesPrgRom', filepath=...)`) and
+point `CDL=` at it.

MAPPER8/Mermaids of Atlantis (U)/derived_names.tsv

@@ -1,17 +0,0 @@
-label	Label_801B	Sub_801B_Entry_801B
-label	Label_8036	Sub_8036_Entry_8036
-label	Label_8038	Sub_8036_OnNonnegative_8038
-label	Label_8057	Sub_8036_JoinBranchPaths_8057
-label	Label_8062	Sub_8036_OnNonzero_8062
-label	Label_806B	Sub_8036_OnCarrySet_806B
-label	Label_8083	Sub_8083_StoreAndContinue_8083
-label	Label_8189	Sub_8083_Entry_8189
-label	Label_FF2F	Sub_8764_OnCarryClear_FF2F
-label	Label_FF3E	Sub_FF3E_CallNext_FF3E
-label	Label_FF49	Sub_FF49_JumpNext_FF49
-label	Label_FF4C	Sub_FF4C_StoreAndContinue_FF4C
-label	Label_FF4E	Sub_FF4C_OnNonzero_FF4E
-label	Label_FF50	Sub_FF4C_OnNonzero_FF50
-label	Label_FF57	Sub_FF57_Return_FF57
-label	Label_FF60	Sub_FF57_OnNonzero_FF60
-label	Label_FF62	Sub_FF62_Return_FF62

MAPPER8/Mermaids of Atlantis (U)/derived_names2.tsv

@@ -1 +0,0 @@
-

MAPPER8/Mermaids of Atlantis (U)/label_map.tsv

@@ -1,17 +0,0 @@
-label	Label_801B	Sub_801B_Entry_801B
-label	Label_8036	Sub_8036_Entry_8036
-label	Label_8038	Sub_8036_OnNonnegative_8038
-label	Label_8057	Sub_8036_JoinBranchPaths_8057
-label	Label_8062	Sub_8036_OnNonzero_8062
-label	Label_806B	Sub_8036_OnCarrySet_806B
-label	Label_8083	Sub_8083_StoreAndContinue_8083
-label	Label_8189	Sub_8083_Entry_8189
-label	Label_FF2F	Sub_8764_OnCarryClear_FF2F
-label	Label_FF3E	Sub_FF3E_CallNext_FF3E
-label	Label_FF49	Sub_FF49_JumpNext_FF49
-label	Label_FF4C	Sub_FF4C_StoreAndContinue_FF4C
-label	Label_FF4E	Sub_FF4C_OnNonzero_FF4E
-label	Label_FF50	Sub_FF4C_OnNonzero_FF50
-label	Label_FF57	Sub_FF57_Return_FF57
-label	Label_FF60	Sub_FF57_OnNonzero_FF60
-label	Label_FF62	Sub_FF62_Return_FF62

MAPPER8/Mermaids of Atlantis (U)/labelmap.tsv

@@ -0,0 +1,601 @@
+
+FF00	Reset
+FF2F	SelectChrBanks
+FF3E	StartGame
+FF49	WritePrgBankReg
+FF4C	DelayOuterLoop
+FF50	DelayInnerLoop
+FF57	WaitForBankSwitch
+FF62	StartBankSwitchDelay
+FF70	SwitchPrgBank
+FF80	SwitchPrgBankKeepA
+
+8004	BankedCall
+801B	SelectPrgBankByIndex
+8036	InitializeGame
+8038	WaitForVBlank
+8057	ClearRamLoop
+8062	ClearRamPageDone
+806B	InitGameVariables
+8083	IdleWaitLoop
+808F	NmiHandler
+80A6	UploadOam
+811C	RunGameLogic
+85DD	TickAnimationCounter
+8606	ApplyGraphicsMode
+8A5F	InitLevelState
+8E34	CopyStackPage
+9621	TickLevelTimer
+97EC	ResetLevelTimers
+813F	ReadControllers
+814D	ReadControllerBits
+8173	DispatchByJumpTable
+8188	ClearOamShadow
+81B1	UpdateNametable
+82E9	UpdateSprites
+83C3	UpdateActorSprites
+849D	StartVramWrite
+84A4	WriteVramTiles
+89FC	AnimatePalette
+90A9	ReadPlayerInput
+91AC	BuildOamBuffer
+9228	ClearSpriteSlots
+962E	LoadSpriteTable
+967C	SetGraphicsMode
+9786	UpdateGameState
+981B	SetTablePointer
+
+AEC7	ClearBubbleSlots
+BB4F	ClearActorSlots
+BB5B	ClearActorTable
+BB68	SoundTimerTick
+BB7E	PlaySoundEffect
+BB94	LoadActorTemplate
+BB9E	CopyActorToSpriteTable
+BBFA	UpdatePlayerState
+BC1C	HandleDemoMode
+BC38	HandlePlayerInput
+BC44	CountPlayerFrames
+BCF9	MovePlayer
+BD26	ApplyPlayerDirection
+BD70	ComputePlayerPosition
+BDE1	StorePlayerSprite
+BEE4	BuildBubbleTable
+BF17	UpdateBubbles
+BF53	PlayBubbleSound
+BF67	SpawnBubble
+BF83	DrawBubble
+BF9A	DispatchBubbleHandler
+BFAF	ResetLevel
+BFBA	ClearSpriteTable
+
+C000	ClearNametableRam
+C00F	PlayStageMusic
+C2A7	DispatchLevelScript
+C2BF	ResetPpuAndLoadTiles
+C3C8	SetVramPointer
+C414	ClearSpriteEntry
+C456	TickStageDelay
+C505	UpdateStageMode
+C62A	DisablePpuRendering
+CC11	SetPlayerActive
+CC56	CheckPlayerActive
+CCCF	TickSoundOnEvenFrame
+CD18	UpdateSoundEngine
+CF32	CheckActorCount
+D0E7	TickActorsOnEvenFrame
+D1B0	InitPlayerPosition
+D21A	TickTimerOnEvenFrame
+D2C0	ResetScrollOnEvenFrame
+D507	InitBubbleState
+D537	UpdateBubbleFrame
+D563	TickHudOnEvenFrame
+D5CF	TickSpritesOnEvenFrame
+D615	SetSoundChannels
+
+
+
+Bank4:800D	Bank4_CallBankedHandler
+Bank4:80A7	Bank4_StartVramWrite
+Bank4:8161	Bank4_UpdateNametable
+Bank5:A726	Bank5_UpdateSound
+Bank5:A784	Bank5_ReadSoundTable
+Bank5:AB50	Bank5_SetSoundMode
+Bank7:FF70	Bank7_SwitchPrgBank
+
+# ---- derived internal branch-target names ----
+8004	BankedCall
+801B	SelectPrgBankByIndex
+8025	Sub_8025
+8036	InitializeGame
+8038	WaitForVBlank
+8057	ClearRamLoop
+8062	ClearRamPageDone
+806B	InitGameVariables
+8083	IdleWaitLoop
+808F	NmiHandler
+8097	NmiHandler_Loop
+80A6	UploadOam
+80BC	UploadOam_Loop
+80C4	UploadOam_Loop2
+811C	RunGameLogic
+813F	ReadControllers
+814D	ReadControllerBits
+8153	ReadControllerBits_OnNonzero
+8173	DispatchByJumpTable
+8188	ClearOamShadow
+818C	ClearOamShadow_OnNonzero
+81B1	UpdateNametable
+81B8	UpdateNametable_OnNonzero
+81D7	UpdateNametable_OnCarryClear
+81E4	UpdateNametable_OnNonzero2
+8204	UpdateNametable_Loop
+820F	UpdateNametable_Loop2
+8214	UpdateNametable_Loop3
+8215	UpdateNametable_OnNonzero3
+8270	UpdateNametable_Loop4
+8276	UpdateNametable_OnNonzero4
+829A	UpdateNametable_OnNonzero5
+82A7	UpdateNametable_OnNonzero6
+82C8	Sub_82C8
+82E9	UpdateSprites
+82F7	UpdateSprites_Loop
+82F9	UpdateSprites_Loop2
+82FB	UpdateSprites_OnCarryClear
+8303	UpdateSprites_Loop3
+830C	Sub_830C
+8349	UpdateSprites_OnNonzero
+8378	UpdateSprites_Loop4
+837B	UpdateSprites_Loop5
+838B	UpdateSprites_Loop6
+838D	Sub_838D
+839F	UpdateSprites_Loop7
+83A1	Sub_83A1
+83C2	UpdateSprites_Loop8
+83C3	UpdateActorSprites
+83C7	UpdateActorSprites_OnCarryClear
+83CF	UpdateActorSprites_Loop
+840B	UpdateActorSprites_OnNonzero
+840C	Sub_840C
+8424	UpdateActorSprites_Loop2
+8451	UpdateActorSprites_Loop3
+848C	Sub_848C
+8492	UpdateActorSprites_OnNonzero2
+849D	StartVramWrite
+84A4	WriteVramTiles
+84BF	Sub_84BF
+84D2	WriteVramTiles_Loop
+84DB	WriteVramTiles_Loop2
+84E3	Sub_84E3
+8534	WriteVramTiles_Loop3
+8552	Sub_8552
+855D	Sub_855D
+858A	Sub_858A
+85A7	Sub_85A7
+85C4	Sub_85C4
+85D2	WriteVramTiles_OnCarryClear
+85DD	TickAnimationCounter
+85E4	TickAnimationCounter_Loop
+8606	ApplyGraphicsMode
+8663	Sub_8663
+8676	ApplyGraphicsMode_OnNonzero
+867D	ApplyGraphicsMode_OnZero
+8686	ApplyGraphicsMode_OnNonzero2
+86D1	ApplyGraphicsMode_Loop
+86F0	ApplyGraphicsMode_Loop2
+8709	ApplyGraphicsMode_Loop3
+872C	ApplyGraphicsMode_Loop4
+8745	ApplyGraphicsMode_OnNonzero3
+874E	ApplyGraphicsMode_Loop5
+89FC	AnimatePalette
+8A35	AnimatePalette_Loop
+8A5F	InitLevelState
+8A66	InitLevelState_Loop
+8A75	InitLevelState_OnNonzero
+8A93	InitLevelState_OnNonzero2
+8AE1	Sub_8AE1
+8B0E	InitLevelState_Loop2
+8E34	CopyStackPage
+8E36	CopyStackPage_OnCarryClear
+9084	Sub_9084
+90A9	ReadPlayerInput
+90BB	ReadPlayerInput_Loop
+90C9	ReadPlayerInput_Loop2
+90D9	ReadPlayerInput_Loop3
+90EA	ReadPlayerInput_Loop4
+90F6	ReadPlayerInput_Loop5
+90FC	Sub_90FC
+91AC	BuildOamBuffer
+91B4	BuildOamBuffer_OnCarryClear
+91D7	BuildOamBuffer_OnNonzero
+91F0	BuildOamBuffer_OnNonzero2
+920D	BuildOamBuffer_Loop
+920F	BuildOamBuffer_Loop2
+9228	ClearSpriteSlots
+922B	ClearSpriteSlots_OnNonzero
+9621	TickLevelTimer
+962D	TickLevelTimer_Loop
+962E	LoadSpriteTable
+9634	LoadSpriteTable_OnCarryClear
+964E	LoadSpriteTable_Loop
+9650	LoadSpriteTable_OnNonzero
+9671	LoadSpriteTable_Loop2
+967C	SetGraphicsMode
+9687	SetGraphicsMode_Loop
+9692	SetGraphicsMode_Loop2
+969C	SetGraphicsMode_Loop3
+96A6	SetGraphicsMode_Loop4
+96AD	SetGraphicsMode_OnCarryClear
+96C8	SetGraphicsMode_Loop5
+96D9	SetGraphicsMode_Loop6
+96DF	SetGraphicsMode_Loop7
+96E3	Sub_96E3
+9703	Sub_9703
+9706	SetGraphicsMode_OnCarryClear2
+970F	Sub_970F
+9712	SetGraphicsMode_OnCarryClear3
+9786	UpdateGameState
+97A6	UpdateGameState_Loop
+97AE	UpdateGameState_Loop2
+97BA	UpdateGameState_Loop3
+97C3	UpdateGameState_Loop4
+97C8	UpdateGameState_Loop5
+97DE	UpdateGameState_Loop6
+97DF	UpdateGameState_Loop7
+97EC	ResetLevelTimers
+97F3	ResetLevelTimers_Loop
+981A	ResetLevelTimers_Loop2
+981B	SetTablePointer
+9829	SetTablePointer_Loop
+9830	SetTablePointer_OnCarryClear
+9841	SetTablePointer_Loop2
+A78F	Sub_A78F
+AEC7	ClearBubbleSlots
+AECA	ClearBubbleSlots_OnCarryClear
+BB4F	ClearActorSlots
+BB52	ClearActorSlots_OnCarryClear
+BB5B	ClearActorTable
+BB68	SoundTimerTick
+BB6E	SoundTimerTick_Loop
+BB7D	SoundTimerTick_Loop2
+BB7E	PlaySoundEffect
+BB94	LoadActorTemplate
+BB9E	CopyActorToSpriteTable
+BBA6	CopyActorToSpriteTable_OnNonzero
+BBBA	CopyActorToSpriteTable_Loop
+BBFA	UpdatePlayerState
+BC09	UpdatePlayerState_Loop
+BC11	Sub_BC11
+BC19	UpdatePlayerState_Loop2
+BC1C	HandleDemoMode
+BC38	HandlePlayerInput
+BC44	CountPlayerFrames
+BC56	CountPlayerFrames_Loop
+BC5A	CountPlayerFrames_Loop2
+BC68	CountPlayerFrames_Loop3
+BC84	CountPlayerFrames_Loop4
+BC8D	CountPlayerFrames_Loop5
+BC98	CountPlayerFrames_Loop6
+BCA9	CountPlayerFrames_Loop7
+BCB8	CountPlayerFrames_Loop8
+BCD6	CountPlayerFrames_Loop9
+BCE1	CountPlayerFrames_Loop10
+BCF1	CountPlayerFrames_Loop11
+BCF9	MovePlayer
+BD0B	MovePlayer_Loop
+BD21	MovePlayer_Loop2
+BD26	ApplyPlayerDirection
+BD36	ApplyPlayerDirection_Loop
+BD3E	ApplyPlayerDirection_Loop2
+BD4F	ApplyPlayerDirection_Loop3
+BD57	ApplyPlayerDirection_Loop4
+BD5F	ApplyPlayerDirection_Loop5
+BD70	ComputePlayerPosition
+BD88	ComputePlayerPosition_OnNonzero
+BD9F	ComputePlayerPosition_Loop
+BDAD	ComputePlayerPosition_Loop2
+BDBD	ComputePlayerPosition_Loop3
+BDCC	ComputePlayerPosition_OnCarrySet
+BDCF	ComputePlayerPosition_Loop4
+BDE1	StorePlayerSprite
+BDF1	StorePlayerSprite_OnNonzero
+BEE4	BuildBubbleTable
+BEE8	BuildBubbleTable_OnCarryClear
+BF17	UpdateBubbles
+BF21	UpdateBubbles_OnCarryClear
+BF29	UpdateBubbles_OnNonnegative
+BF49	UpdateBubbles_Loop
+BF53	PlayBubbleSound
+BF59	PlayBubbleSound_Loop
+BF67	SpawnBubble
+BF73	SpawnBubble_Loop
+BF83	DrawBubble
+BF9A	DispatchBubbleHandler
+BFAF	ResetLevel
+BFBA	ClearSpriteTable
+BFDC	ClearSpriteTable_Loop
+BFE6	ClearSpriteTable_OnCarryClear
+C000	ClearNametableRam
+C006	ClearNametableRam_OnCarryClear
+C00E	ClearNametableRam_Loop
+C00F	PlayStageMusic
+C015	PlayStageMusic_Loop
+C019	PlayStageMusic_OnCarryClear
+C035	PlayStageMusic_Loop2
+C061	Sub_C061
+C064	PlayStageMusic_OnCarryClear2
+C0F2	Sub_C0F2
+C100	PlayStageMusic_OnCarryClear3
+C10E	PlayStageMusic_Loop3
+C136	PlayStageMusic_Loop4
+C140	Sub_C140
+C16E	PlayStageMusic_Loop5
+C2A7	DispatchLevelScript
+C2BF	ResetPpuAndLoadTiles
+C308	ResetPpuAndLoadTiles_OnNonzero
+C319	ResetPpuAndLoadTiles_OnNonzero2
+C32B	ResetPpuAndLoadTiles_Loop
+C33E	ResetPpuAndLoadTiles_Loop2
+C357	ResetPpuAndLoadTiles_OnCarryClear
+C366	ResetPpuAndLoadTiles_OnNonzero3
+C37D	ResetPpuAndLoadTiles_Loop3
+C3A5	ResetPpuAndLoadTiles_Loop4
+C3B7	ResetPpuAndLoadTiles_Loop5
+C3C3	ResetPpuAndLoadTiles_Loop6
+C3C8	SetVramPointer
+C3E2	SetVramPointer_Loop
+C40A	SetVramPointer_Loop2
+C414	ClearSpriteEntry
+C456	TickStageDelay
+C460	TickStageDelay_Loop
+C468	TickStageDelay_Loop2
+C505	UpdateStageMode
+C513	UpdateStageMode_Loop
+C519	UpdateStageMode_OnNonzero
+C531	UpdateStageMode_Loop2
+C544	UpdateStageMode_Loop3
+C54A	UpdateStageMode_OnCarryClear
+C556	UpdateStageMode_Loop4
+C55B	UpdateStageMode_Loop5
+C59E	UpdateStageMode_Loop6
+C59F	UpdateStageMode_Loop7
+C5D2	Sub_C5D2
+C62A	DisablePpuRendering
+C671	DisablePpuRendering_Loop
+C68B	DisablePpuRendering_OnCarryClear
+C694	DisablePpuRendering_Loop2
+C6B7	Sub_C6B7
+C6BA	DisablePpuRendering_OnCarryClear2
+C6C3	DisablePpuRendering_OnCarryClear3
+C7EA	Sub_C7EA
+C7FF	DisablePpuRendering_Loop3
+C800	DisablePpuRendering_Loop4
+C80D	DisablePpuRendering_Loop5
+C81D	DisablePpuRendering_Loop6
+C839	DisablePpuRendering_Loop7
+C83A	Sub_C83A
+C840	DisablePpuRendering_Loop8
+CBC4	Sub_CBC4
+CBD9	DisablePpuRendering_Loop9
+CBE8	DisablePpuRendering_Loop10
+CBF8	DisablePpuRendering_Loop11
+CC11	SetPlayerActive
+CC1D	SetPlayerActive_Loop
+CC48	SetPlayerActive_Loop2
+CC56	CheckPlayerActive
+CC68	CheckPlayerActive_Loop
+CC86	CheckPlayerActive_Loop2
+CC8B	CheckPlayerActive_Loop3
+CC93	CheckPlayerActive_Loop4
+CCBC	CheckPlayerActive_Loop5
+CCBD	CheckPlayerActive_Loop6
+CCCF	TickSoundOnEvenFrame
+CCD5	TickSoundOnEvenFrame_Loop
+CCDC	TickSoundOnEvenFrame_Loop2
+CD02	TickSoundOnEvenFrame_Loop3
+CD18	UpdateSoundEngine
+CD1C	Sub_CD1C
+CD27	UpdateSoundEngine_OnNonzero
+CD52	UpdateSoundEngine_Loop
+CD59	Sub_CD59
+CD6D	UpdateSoundEngine_Loop2
+CD7E	UpdateSoundEngine_Loop3
+CDA0	UpdateSoundEngine_OnCarryClear
+CDB6	Sub_CDB6
+CDC8	UpdateSoundEngine_OnCarryClear2
+CDE2	UpdateSoundEngine_OnCarryClear3
+CDF0	Sub_CDF0
+CE01	UpdateSoundEngine_OnCarryClear4
+CE0D	Sub_CE0D
+CE13	UpdateSoundEngine_Loop4
+CE30	UpdateSoundEngine_OnNonzero2
+CE42	UpdateSoundEngine_Loop5
+CE51	UpdateSoundEngine_OnCarryClear5
+CE8B	Sub_CE8B
+CE91	UpdateSoundEngine_Loop6
+CE9A	UpdateSoundEngine_OnNonzero3
+CEE0	UpdateSoundEngine_OnCarryClear6
+CF32	CheckActorCount
+CF4D	CheckActorCount_Loop
+CF4F	CheckActorCount_OnCarryClear
+CF5D	CheckActorCount_Loop2
+CF89	CheckActorCount_Loop3
+CF8F	Sub_CF8F
+CF9B	CheckActorCount_Loop4
+CF9C	CheckActorCount_Loop5
+CFFD	Sub_CFFD
+D001	CheckActorCount_OnCarryClear2
+D00E	CheckActorCount_Loop6
+D015	CheckActorCount_Loop7
+D022	CheckActorCount_OnNonzero
+D042	CheckActorCount_Loop8
+D046	Sub_D046
+D04E	CheckActorCount_OnNonzero2
+D05B	CheckActorCount_Loop9
+D07E	CheckActorCount_Loop10
+D084	CheckActorCount_Loop11
+D08D	CheckActorCount_Loop12
+D0A5	CheckActorCount_Loop13
+D0B3	CheckActorCount_Loop14
+D0D1	CheckActorCount_OnNonnegative
+D0E2	CheckActorCount_Loop15
+D0E7	TickActorsOnEvenFrame
+D0ED	TickActorsOnEvenFrame_Loop
+D106	TickActorsOnEvenFrame_Loop2
+D110	TickActorsOnEvenFrame_Loop3
+D112	TickActorsOnEvenFrame_OnCarryClear
+D122	TickActorsOnEvenFrame_Loop4
+D12C	TickActorsOnEvenFrame_OnNonzero
+D15B	TickActorsOnEvenFrame_Loop5
+D15F	Sub_D15F
+D16D	TickActorsOnEvenFrame_OnNonnegative
+D181	Sub_D181
+D183	TickActorsOnEvenFrame_OnNonnegative2
+D1B0	InitPlayerPosition
+D1B8	InitPlayerPosition_OnCarryClear
+D1C3	InitPlayerPosition_OnNonzero
+D1D1	InitPlayerPosition_OnNonzero2
+D1E6	InitPlayerPosition_Loop
+D1F8	InitPlayerPosition_Loop2
+D204	InitPlayerPosition_Loop3
+D219	InitPlayerPosition_Loop4
+D21A	TickTimerOnEvenFrame
+D220	TickTimerOnEvenFrame_Loop
+D22A	TickTimerOnEvenFrame_OnCarryClear
+D22F	TickTimerOnEvenFrame_OnCarrySet
+D241	TickTimerOnEvenFrame_Loop2
+D24B	TickTimerOnEvenFrame_OnZero
+D27F	TickTimerOnEvenFrame_Loop3
+D28A	TickTimerOnEvenFrame_Loop4
+D294	TickTimerOnEvenFrame_Loop5
+D2AB	TickTimerOnEvenFrame_Loop6
+D2AF	TickTimerOnEvenFrame_Loop7
+D2C0	ResetScrollOnEvenFrame
+D2C6	ResetScrollOnEvenFrame_Loop
+D2CD	ResetScrollOnEvenFrame_OnNonnegative
+D2DC	ResetScrollOnEvenFrame_Loop2
+D2E9	ResetScrollOnEvenFrame_OnNonzero
+D2FB	ResetScrollOnEvenFrame_Loop3
+D327	ResetScrollOnEvenFrame_OnNonzero2
+D339	ResetScrollOnEvenFrame_Loop4
+D33E	ResetScrollOnEvenFrame_OnNonnegative2
+D34D	ResetScrollOnEvenFrame_OnNonzero3
+D35F	ResetScrollOnEvenFrame_Loop5
+D374	ResetScrollOnEvenFrame_OnCarryClear
+D399	ResetScrollOnEvenFrame_OnCarryClear2
+D45E	Sub_D45E
+D464	ResetScrollOnEvenFrame_OnNonnegative3
+D470	ResetScrollOnEvenFrame_Loop6
+D485	ResetScrollOnEvenFrame_Loop7
+D4EE	Sub_D4EE
+D507	InitBubbleState
+D50F	InitBubbleState_OnNonzero
+D52B	InitBubbleState_Loop
+D52C	InitBubbleState_Loop2
+D537	UpdateBubbleFrame
+D559	UpdateBubbleFrame_Loop
+D55A	UpdateBubbleFrame_Loop2
+D560	UpdateBubbleFrame_Loop3
+D563	TickHudOnEvenFrame
+D569	TickHudOnEvenFrame_Loop
+D595	Sub_D595
+D59B	TickHudOnEvenFrame_OnNonzero
+D5A5	TickHudOnEvenFrame_Loop2
+D5AF	Sub_D5AF
+D5B3	TickHudOnEvenFrame_OnNonzero2
+D5B4	TickHudOnEvenFrame_OnNonnegative
+D5C0	TickHudOnEvenFrame_Loop3
+D5C6	TickHudOnEvenFrame_Loop4
+D5CF	TickSpritesOnEvenFrame
+D5D5	TickSpritesOnEvenFrame_Loop
+D5E3	TickSpritesOnEvenFrame_OnNonnegative
+D5EF	TickSpritesOnEvenFrame_Loop2
+D609	TickSpritesOnEvenFrame_Loop3
+D60D	TickSpritesOnEvenFrame_Loop4
+D615	SetSoundChannels
+FF00	Reset
+FF2F	SelectChrBanks
+FF3E	StartGame
+FF49	WritePrgBankReg
+FF4C	DelayOuterLoop
+FF4E	DelayOuterLoop_OnNonzero
+FF50	DelayInnerLoop
+FF57	WaitForBankSwitch
+FF60	WaitForBankSwitch_Loop
+FF62	StartBankSwitchDelay
+FF70	SwitchPrgBank
+FF80	SwitchPrgBankKeepA
+Bank4:800D	Bank4_CallBankedHandler
+Bank4:801B	Bank4_Sub_801B
+Bank4:8088	Bank4_Sub_8088
+Bank4:80A7	Bank4_StartVramWrite
+Bank4:80C9	Bank4_Sub_80C9
+Bank4:80E3	Bank4_Bank4_StartVramWrite_OnZero
+Bank4:80F2	Bank4_Bank4_StartVramWrite_OnNonzero
+Bank4:8100	Bank4_Bank4_StartVramWrite_Loop
+Bank4:8107	Bank4_Bank4_StartVramWrite_OnNonzero2
+Bank4:8110	Bank4_Bank4_StartVramWrite_Loop2
+Bank4:8111	Bank4_Sub_8111
+Bank4:8117	Bank4_Bank4_StartVramWrite_Loop3
+Bank4:8118	Bank4_Sub_8118
+Bank4:8126	Bank4_Bank4_StartVramWrite_OnCarryClear
+Bank4:8161	Bank4_UpdateNametable
+Bank4:8167	Bank4_Bank4_UpdateNametable_OnZero
+Bank4:817A	Bank4_Bank4_UpdateNametable_OnNonzero
+Bank4:8186	Bank4_Bank4_UpdateNametable_Loop
+Bank5:A71A	Bank5_Sub_OnZero
+Bank5:A726	Bank5_UpdateSound
+Bank5:A75B	Bank5_Sub_A75B
+Bank5:A768	Bank5_Bank5_UpdateSound_OnNonnegative
+Bank5:A784	Bank5_ReadSoundTable
+Bank5:A7FB	Bank5_Bank5_ReadSoundTable_Loop
+Bank5:A7FF	Bank5_Sub_A7FF
+Bank5:A817	Bank5_Bank5_ReadSoundTable_Loop2
+Bank5:A827	Bank5_Bank5_ReadSoundTable_Loop3
+Bank5:A828	Bank5_Bank5_ReadSoundTable_Loop4
+Bank5:A830	Bank5_Bank5_ReadSoundTable_OnZero
+Bank5:A831	Bank5_Bank5_ReadSoundTable_Loop5
+Bank5:A839	Bank5_Bank5_ReadSoundTable_Loop6
+Bank5:A83C	Bank5_Bank5_ReadSoundTable_Loop7
+Bank5:A858	Bank5_Bank5_ReadSoundTable_Loop8
+Bank5:A871	Bank5_Bank5_ReadSoundTable_Loop9
+Bank5:A87B	Bank5_Bank5_ReadSoundTable_Loop10
+Bank5:A887	Bank5_Bank5_ReadSoundTable_OnCarryClear
+Bank5:A892	Bank5_Bank5_ReadSoundTable_Loop11
+Bank5:A8A8	Bank5_Bank5_ReadSoundTable_Loop12
+Bank5:A8AF	Bank5_Bank5_ReadSoundTable_Loop13
+Bank5:A8C7	Bank5_Bank5_ReadSoundTable_Loop14
+Bank5:A8CF	Bank5_Bank5_ReadSoundTable_Loop15
+Bank5:A8D5	Bank5_Bank5_ReadSoundTable_Loop16
+Bank5:A8DC	Bank5_Bank5_ReadSoundTable_Loop17
+Bank5:A8E8	Bank5_Bank5_ReadSoundTable_OnNonzero
+Bank5:A8F1	Bank5_Bank5_ReadSoundTable_Loop18
+Bank5:A913	Bank5_Bank5_ReadSoundTable_OnZero2
+Bank5:A92B	Bank5_Bank5_ReadSoundTable_Loop19
+Bank5:A932	Bank5_Bank5_ReadSoundTable_Loop20
+Bank5:A93E	Bank5_Bank5_ReadSoundTable_Loop21
+Bank5:A954	Bank5_Bank5_ReadSoundTable_Loop22
+Bank5:A976	Bank5_Bank5_ReadSoundTable_Loop23
+Bank5:A989	Bank5_Bank5_ReadSoundTable_Loop24
+Bank5:A99C	Bank5_Bank5_ReadSoundTable_Loop25
+Bank5:A9A9	Bank5_Bank5_ReadSoundTable_Loop26
+Bank5:A9B6	Bank5_Bank5_ReadSoundTable_Loop27
+Bank5:A9C3	Bank5_Sub_A9C3
+Bank5:A9D5	Bank5_Bank5_ReadSoundTable_Loop28
+Bank5:A9E9	Bank5_Sub_A9E9
+Bank5:AA05	Bank5_Bank5_ReadSoundTable_Loop29
+Bank5:AA15	Bank5_Bank5_ReadSoundTable_Loop30
+Bank5:AA4D	Bank5_Bank5_ReadSoundTable_Loop31
+Bank5:AA53	Bank5_Bank5_ReadSoundTable_OnZero3
+Bank5:AA54	Bank5_Bank5_ReadSoundTable_OnZero4
+Bank5:AA66	Bank5_Bank5_ReadSoundTable_Loop32
+Bank5:AA7A	Bank5_Sub_AA7A
+Bank5:AA81	Bank5_Bank5_ReadSoundTable_OnNonzero2
+Bank5:AA8E	Bank5_Bank5_ReadSoundTable_OnNonzero3
+Bank5:AAF1	Bank5_Sub_AAF1
+Bank5:AB11	Bank5_Sub_AB11
+Bank5:AB27	Bank5_Bank5_ReadSoundTable_OnNonzero4
+Bank5:AB43	Bank5_Bank5_ReadSoundTable_Loop33
+Bank5:AB46	Bank5_Bank5_ReadSoundTable_Loop34
+Bank5:AB50	Bank5_SetSoundMode
+Bank7:FF70	Bank7_SwitchPrgBank

MAPPER8/Mermaids of Atlantis (U)/linker.cfg

@@ -1,10 +1,24 @@
 MEMORY {
   HEADER: start = $0000, size = $0010, fill = yes;
-  PRG:    start = $0010, size = $10000, fill = yes;
+  PRG0:   start = $0010, size = $2000, fill = yes;
+  PRG1:   start = $2010, size = $2000, fill = yes;
+  PRG2:   start = $4010, size = $2000, fill = yes;
+  PRG3:   start = $6010, size = $2000, fill = yes;
+  PRG4:   start = $8010, size = $2000, fill = yes;
+  PRG5:   start = $A010, size = $2000, fill = yes;
+  PRG6:   start = $C010, size = $2000, fill = yes;
+  PRG7:   start = $E010, size = $2000, fill = yes;
   CHR:    start = $10010, size = $10000, fill = yes;
 }
 SEGMENTS {
   HEADER: load = HEADER, type = ro;
-  PRG:    load = PRG,    type = ro;
+  PRG0:   load = PRG0,   type = ro;
+  PRG1:   load = PRG1,   type = ro;
+  PRG2:   load = PRG2,   type = ro;
+  PRG3:   load = PRG3,   type = ro;
+  PRG4:   load = PRG4,   type = ro;
+  PRG5:   load = PRG5,   type = ro;
+  PRG6:   load = PRG6,   type = ro;
+  PRG7:   load = PRG7,   type = ro;
   CHR:    load = CHR,    type = ro;
 }

MAPPER8/Mermaids of Atlantis (U)/locals.inc

@@ -1,37 +1,171 @@
-; Zero-page aliases for this project.
-; Pass 1+ adds proven semantic names here;
-; addresses whose role is not yet determined keep the neutral ZpXX
-; form.
+; Mermaids of Atlantis (U) - zero-page aliases.
+;
+; Pass 1 names every zero-page operand ZpXX; the names below are the
+; semantic ones the dump proves.  An address whose role is the same at
+; every reference is renamed everywhere; an address the game reuses for
+; several roles keeps the neutral ZpXX name and is listed at the end.
 
+ButtonState1     = $26 ; player 1 button bits, read from $4016
+ButtonState2     = $27 ; player 2 button bits, read from $4017
+PrevButton1      = $28 ; player 1 buttons of the previous frame
+PrevButton2      = $29 ; player 2 buttons of the previous frame
+NewButton1       = $2A ; player 1 buttons pressed this frame
+NewButton2       = $2B ; player 2 buttons pressed this frame
+PrgBankNumber    = $2C ; the MMC3 PRG bank the game switches to
+HandlerIndex     = $2D ; the index the banked call dispatches on
+IdleCounter      = $2F ; the counter the idle loop spins on
+FrameCounter     = $31 ; the frame counter, incremented at the end of the NMI
+ControllerBits   = $05 ; the eight button bits assembled by the pad reader
+ControllerByte   = $07 ; the raw byte read from $4016/$4017
+GameMode         = $6A ; the game mode flag (0 = playing, 1 = demo)
+
+; ---------------------------------------------------------------------------
+; The addresses below are used for more than one purpose in this dump, so
+; they keep the neutral name.
+;
+;   $00-$01  the RAM-clear pointer (and the banked-call scratch)
+;   $02      the PPUMASK shadow
+;   $06      the PRG bank shadow in the banked call
+;   $11-$14  indirect pointers: the VRAM pointer, the dispatch table pointer
+;            and the sound table pointer share the two pairs
+;   $19-$1F  scroll, sprite and bubble coordinates, reused per actor
+;   $20-$2E  per-actor scratch: the tile, the position and the frame counters
+;   $30-$3F  per-actor state: the sprite index, the direction and the timers
+;   $40-$5F  the level script variables: the stage, the wave and the score
+;   $60-$7F  the game state: the mode flags, the player state and the timers
+;   $80-$9F  the same, for the second half of the image
+;   $A0-$DF  the sound engine state
+; ---------------------------------------------------------------------------
+
+Zp2E    = $2E
 Zp00    = $00
 Zp01    = $01
 Zp02    = $02
-Zp2F    = $2F
-Zp6A    = $6A
-
-; ---------------------------------------------------------------------------
-; Semantic zero-page aliases (Pass 3)
-;
-; Every alias below was read out of this dump's own code.  An address whose
-; role is the same at every reference is renamed everywhere; an address that
-; is reused for several roles keeps the neutral ZpXX name outside the
-; routines where the role is proven, and the per-site choice is recorded in
-; sites.tsv.
-; ---------------------------------------------------------------------------
-
-TempVar0        = $00 ; semantic alias for Zp00 (general-purpose zero-page temp, used at $804D,$8057,$806B)
-TempVar1        = $01 ; semantic alias for Zp01 (general-purpose zero-page temp, used at $804F,$8062,$8066,$806D,$807D)
-TempVar2        = $02 ; semantic alias for Zp02 (general-purpose zero-page temp, used at $8076)
-LoopCounter     = $2F ; semantic alias for Zp2F (incremented at $8083, likely frame/loop counter)
-StatusByte      = $6A ; semantic alias for Zp6A (stored at $8081, likely status/flags register)
-
-; Clean marker section placeholder - will be filled by tools if needed
-; ---------------------------------------------------------------------------
-; Semantic zero-page aliases (Pass 3)
-;
-; Every alias below was read out of this dump's own code.  An address whose
-; role is the same at every reference is renamed everywhere; an address that
-; is reused for several roles keeps the neutral ZpXX name outside the
-; routines where the role is proven, and the per-site choice is recorded in
-; sites.tsv.
-; ---------------------------------------------------------------------------
+Zp03    = $03
+Zp04    = $04
+Zp06    = $06
+Zp08    = $08
+Zp09    = $09
+Zp10    = $10
+Zp11    = $11
+Zp12    = $12
+Zp13    = $13
+Zp14    = $14
+Zp15    = $15
+Zp16    = $16
+Zp17    = $17
+Zp18    = $18
+Zp19    = $19
+Zp1A    = $1A
+Zp1B    = $1B
+Zp1C    = $1C
+Zp1D    = $1D
+Zp1E    = $1E
+Zp1F    = $1F
+Zp20    = $20
+Zp21    = $21
+Zp22    = $22
+Zp23    = $23
+Zp24    = $24
+Zp25    = $25
+Zp30    = $30
+Zp32    = $32
+Zp33    = $33
+Zp34    = $34
+Zp35    = $35
+Zp36    = $36
+Zp37    = $37
+Zp38    = $38
+Zp39    = $39
+Zp3A    = $3A
+Zp3B    = $3B
+Zp3C    = $3C
+Zp3D    = $3D
+Zp3E    = $3E
+Zp3F    = $3F
+Zp40    = $40
+Zp41    = $41
+Zp42    = $42
+Zp46    = $46
+Zp47    = $47
+Zp48    = $48
+Zp49    = $49
+Zp4A    = $4A
+Zp4B    = $4B
+Zp4C    = $4C
+Zp4D    = $4D
+Zp4E    = $4E
+Zp52    = $52
+Zp56    = $56
+Zp58    = $58
+Zp59    = $59
+Zp5A    = $5A
+Zp5B    = $5B
+Zp5C    = $5C
+Zp5D    = $5D
+Zp5E    = $5E
+Zp5F    = $5F
+Zp60    = $60
+Zp61    = $61
+Zp62    = $62
+Zp63    = $63
+Zp64    = $64
+Zp65    = $65
+Zp66    = $66
+Zp67    = $67
+Zp68    = $68
+Zp69    = $69
+Zp6C    = $6C
+Zp6E    = $6E
+Zp6F    = $6F
+Zp70    = $70
+Zp71    = $71
+Zp72    = $72
+Zp73    = $73
+Zp74    = $74
+Zp75    = $75
+Zp76    = $76
+Zp78    = $78
+Zp7E    = $7E
+Zp80    = $80
+Zp85    = $85
+Zp86    = $86
+Zp91    = $91
+Zp93    = $93
+Zp94    = $94
+Zp95    = $95
+Zp96    = $96
+Zp97    = $97
+Zp99    = $99
+Zp9A    = $9A
+Zp9D    = $9D
+ZpA7    = $A7
+ZpAF    = $AF
+ZpB7    = $B7
+ZpB9    = $B9
+ZpBE    = $BE
+ZpC8    = $C8
+ZpC9    = $C9
+ZpCA    = $CA
+ZpCB    = $CB
+ZpCC    = $CC
+ZpCD    = $CD
+ZpCE    = $CE
+ZpCF    = $CF
+ZpD0    = $D0
+ZpD4    = $D4
+ZpD5    = $D5
+ZpD6    = $D6
+ZpD7    = $D7
+ZpD8    = $D8
+ZpD9    = $D9
+ZpDA    = $DA
+ZpDB    = $DB
+ZpDC    = $DC
+ZpDD    = $DD
+ZpDE    = $DE
+ZpDF    = $DF
+ZpE0    = $E0
+ZpE2    = $E2
+ZpE3    = $E3
+ZpE7    = $E7

MAPPER8/Mermaids of Atlantis (U)/regen.sh

@@ -0,0 +1,51 @@
+#!/bin/sh
+# Regenerate prg.s from the ROM and the Mesen CDL capture.
+#
+# The pass order is the one the repo uses:
+#   1. Pass 1 - banked_dis.py traces every MMC3 bank separately, seeded from
+#      the Mesen Code Data Logger capture, and writes prg.s.
+#   2. Pass 2 - derive_branch_names.py adds the mechanical branch-target names
+#      to the hand-written routine map, apply_pass2_map.py renames the file.
+#   3. The audit comments are re-aligned, because the rename makes the
+#      operands longer.
+#
+# The CDL capture is not kept in the repository: it is 64 KB of emulator
+# state.  Re-take it with Mesen (see README.md) if the split has to be
+# re-derived.
+set -e
+
+PROJ="$(dirname "$0")"
+TOOLS="$PROJ/../../_tools"
+CDL="${CDL:-/tmp/opencode/mermaids_union.cdl}"
+
+python3 "$TOOLS/banked_dis.py" \
+    --prg "$PROJ/prg.bin" \
+    --cdl "$CDL" \
+    --project "Mermaids of Atlantis (U)" \
+    --out "$PROJ/prg.s" \
+    --symbols "$PROJ/symbols.inc" \
+    --undocumented \
+    --banks "0:8000,2000:A000,4000:C000,6000:E000,8000:8000,A000:A000,C000:C000,E000:E000" \
+    --prefix "8000:Bank4,A000:Bank5,C000:Bank6,E000:Bank7" \
+    --label "4000:C00E"
+
+python3 "$TOOLS/derive_branch_names.py" "$PROJ" "$PROJ/routinemap.tsv" \
+    "0:,8000:Bank4,A000:Bank5,C000:Bank6,E000:Bank7" "$PROJ/labelmap.tsv"
+
+python3 "$TOOLS/apply_pass2_map.py" "$PROJ" "$PROJ/labelmap.tsv" \
+    --bank-prefix "0:,8000:Bank4,A000:Bank5,C000:Bank6,E000:Bank7" --write
+
+# The semantic zero-page names, the routine descriptions and the audit
+# comment column are the last three passes.
+python3 "$TOOLS/apply_zp_aliases.py" "$PROJ" --write \
+    --alias ButtonState1=Zp26 --alias ButtonState2=Zp27 \
+    --alias PrevButton1=Zp28 --alias PrevButton2=Zp29 \
+    --alias NewButton1=Zp2A --alias NewButton2=Zp2B \
+    --alias PrgBankNumber=Zp2C --alias HandlerIndex=Zp2D \
+    --alias IdleCounter=Zp2F --alias FrameCounter=Zp31 \
+    --alias ControllerBits=Zp05 --alias ControllerByte=Zp07 \
+    --alias GameMode=Zp6A
+
+python3 "$TOOLS/describe_routines.py" "$PROJ/prg.s" "$PROJ/routinedesc.tsv"
+
+python3 "$TOOLS/align_audit_comments.py" "$PROJ" --write

MAPPER8/Mermaids of Atlantis (U)/routinedesc.tsv

@@ -0,0 +1,111 @@
+# Mermaids of Atlantis (U) - routine descriptions.
+#
+# Name <TAB> description.  Used by the routine-header tool; the routines
+# that are not listed here get a description built from their name.
+
+# ---- fixed bank (file $6000-$7FFF, CPU $E000-$FFFF) ----
+Reset	Power-on entry: sets up the stack, clears the PPU and starts the bank switch.
+SelectChrBanks	Picks the CHR banks for the stage that is about to be drawn.
+StartGame	Switches to the first PRG bank and hands over to the game code.
+WritePrgBankReg	Writes the MMC3 PRG bank register at $4100.
+DelayOuterLoop	Outer half of the power-on delay loop.
+DelayInnerLoop	Inner half of the power-on delay loop.
+WaitForBankSwitch	Waits for the bank switch counter to run out.
+StartBankSwitchDelay	Starts the bank switch delay counter.
+SwitchPrgBank	Writes A to the MMC3 PRG bank register with the mode bits forced on.
+SwitchPrgBankKeepA	Writes X to the MMC3 PRG bank register and keeps A.
+
+# ---- bank 0 (file $0000-$1FFF, CPU $8000-$9FFF) ----
+BankedCall	Switches the PRG bank and dispatches to the handler the caller named.
+SelectPrgBankByIndex	Switches the PRG bank to the one in X.
+InitializeGame	Resets the CPU, the PPU and the work RAM, then idles for the NMI.
+WaitForVBlank	Spins until the PPU signals the start of vertical blank.
+ClearRamLoop	Clears the work RAM one 224 byte page at a time.
+ClearRamPageDone	Moves on to the next page of the RAM clear.
+InitGameVariables	Sets the sound, scroll and sprite registers up.
+IdleWaitLoop	The loop the game sits in between two NMI handlers.
+NmiHandler	The frame handler: redraws the screen, reads the pad and runs the game.
+UploadOam	Copies the sprite shadow into the OAM through the DMA register.
+RunGameLogic	Runs the game logic for the current mode.
+ReadControllers	Strobes the controller ports and reads both of them.
+ReadControllerBits	Shifts one controller byte into the button bit mask.
+DispatchByJumpTable	Jumps to the handler whose address follows the call.
+ClearOamShadow	Fills the sprite shadow at $0200 with the "empty" value $F8.
+UpdateNametable	Rewrites the nametable entries that changed.
+UpdateSprites	Walks the sixteen sprite slots and redraws the active ones.
+UpdateActorSprites	Walks the actor slots and redraws their sprites.
+StartVramWrite	Sets the PPU address for the next VRAM write.
+WriteVramTiles	Writes the tile data to VRAM.
+TickAnimationCounter	Advances the animation counter once per frame.
+ApplyGraphicsMode	Switches the PPU to the graphics mode the level asks for.
+AnimatePalette	Cycles the palette entries of the animated tiles.
+InitLevelState	Sets up the state of a new level.
+CopyStackPage	Copies the stack page so the game can use it as scratch RAM.
+ReadPlayerInput	Turns the raw button bits into the player's movement.
+BuildOamBuffer	Fills the sprite shadow from the actor and bubble tables.
+ClearSpriteSlots	Empties the sixteen sprite slots.
+TickLevelTimer	Counts the level timer and resets it when it runs out.
+LoadSpriteTable	Copies a sprite table out of the fixed bank.
+SetGraphicsMode	Switches the PPU between the background and the overlay.
+UpdateGameState	Runs the mode machine: title, demo, play and game over.
+ResetLevelTimers	Clears the level timers when a new level starts.
+SetTablePointer	Points the data pointer at a table in RAM.
+
+# ---- bank 1 (file $2000-$3FFF, CPU $A000-$BFFF) ----
+ClearBubbleSlots	Empties the bubble slots.
+ClearActorSlots	Empties the actor slots.
+ClearActorTable	Empties the actor table in RAM.
+SoundTimerTick	Counts the sound effect timer down.
+PlaySoundEffect	Starts a sound effect from the sound table.
+LoadActorTemplate	Copies an actor template out of the table.
+CopyActorToSpriteTable	Copies an actor into the sprite table.
+UpdatePlayerState	Updates the player state for the current frame.
+HandleDemoMode	Runs the attract mode when no credit is left.
+HandlePlayerInput	Turns the button bits into the player's actions.
+CountPlayerFrames	Counts the frames the player state has been in.
+MovePlayer	Moves the player by one step.
+ApplyPlayerDirection	Turns the direction bits into a movement delta.
+ComputePlayerPosition	Computes the player's position from the tile map.
+StorePlayerSprite	Stores the player's sprite in the sprite table.
+BuildBubbleTable	Builds the table of the bubbles on the screen.
+UpdateBubbles	Updates every bubble on the screen.
+PlayBubbleSound	Plays the sound of a bubble that burst.
+SpawnBubble	Puts a new bubble on the screen.
+DrawBubble	Draws one bubble.
+DispatchBubbleHandler	Jumps to the handler the bubble table names.
+ResetLevel	Resets the level and the player.
+ClearSpriteTable	Empties the sprite table in RAM.
+
+# ---- bank 2 (file $4000-$5FFF, CPU $C000-$DFFF) ----
+ClearNametableRam	Clears the nametable RAM the game writes to.
+PlayStageMusic	Runs the stage script: the music, the waves and the timer.
+DispatchLevelScript	Jumps to the level script step the game is on.
+ResetPpuAndLoadTiles	Turns the PPU off and loads the tile set.
+SetVramPointer	Points the VRAM pointer at the tile set.
+ClearSpriteEntry	Clears one entry of the sprite table.
+TickStageDelay	Counts the delay between two stage script steps.
+UpdateStageMode	Updates the mode the stage script is in.
+DisablePpuRendering	Turns the PPU off.
+SetPlayerActive	Marks the player as active.
+CheckPlayerActive	Tests whether the player is still in play.
+TickSoundOnEvenFrame	Updates the sound on every second frame.
+UpdateSoundEngine	Updates the sound engine.
+CheckActorCount	Tests how many actors are on the screen.
+TickActorsOnEvenFrame	Updates the actors on every second frame.
+InitPlayerPosition	Places the player at the start of the level.
+TickTimerOnEvenFrame	Updates the level timer on every second frame.
+ResetScrollOnEvenFrame	Resets the scroll on every second frame.
+InitBubbleState	Sets the bubble state up for a new wave.
+UpdateBubbleFrame	Updates the bubbles once per frame.
+TickHudOnEvenFrame	Updates the score display on every second frame.
+TickSpritesOnEvenFrame	Updates the sprite table on every second frame.
+SetSoundChannels	Turns the APU channels on.
+
+# ---- the second half of the image (banks 4-7) ----
+Bank4_CallBankedHandler	Switches the PRG bank and dispatches to the handler the caller named.
+Bank4_StartVramWrite	Sets the PPU address for the next VRAM write.
+Bank4_UpdateNametable	Rewrites the nametable entries that changed.
+Bank5_UpdateSound	Updates the sound engine of the second half.
+Bank5_ReadSoundTable	Reads the sound table of the second half.
+Bank5_SetSoundMode	Turns the sound channels on in the second half.
+Bank7_SwitchPrgBank	The copy of the bank switch the last bank of the image carries.

MAPPER8/Mermaids of Atlantis (U)/routinemap.tsv

@@ -0,0 +1,105 @@
+
+FF00	Reset
+FF2F	SelectChrBanks
+FF3E	StartGame
+FF49	WritePrgBankReg
+FF4C	DelayOuterLoop
+FF50	DelayInnerLoop
+FF57	WaitForBankSwitch
+FF62	StartBankSwitchDelay
+FF70	SwitchPrgBank
+FF80	SwitchPrgBankKeepA
+
+8004	BankedCall
+801B	SelectPrgBankByIndex
+8036	InitializeGame
+8038	WaitForVBlank
+8057	ClearRamLoop
+8062	ClearRamPageDone
+806B	InitGameVariables
+8083	IdleWaitLoop
+808F	NmiHandler
+80A6	UploadOam
+811C	RunGameLogic
+85DD	TickAnimationCounter
+8606	ApplyGraphicsMode
+8A5F	InitLevelState
+8E34	CopyStackPage
+9621	TickLevelTimer
+97EC	ResetLevelTimers
+813F	ReadControllers
+814D	ReadControllerBits
+8173	DispatchByJumpTable
+8188	ClearOamShadow
+81B1	UpdateNametable
+82E9	UpdateSprites
+83C3	UpdateActorSprites
+849D	StartVramWrite
+84A4	WriteVramTiles
+89FC	AnimatePalette
+90A9	ReadPlayerInput
+91AC	BuildOamBuffer
+9228	ClearSpriteSlots
+962E	LoadSpriteTable
+967C	SetGraphicsMode
+9786	UpdateGameState
+981B	SetTablePointer
+
+AEC7	ClearBubbleSlots
+BB4F	ClearActorSlots
+BB5B	ClearActorTable
+BB68	SoundTimerTick
+BB7E	PlaySoundEffect
+BB94	LoadActorTemplate
+BB9E	CopyActorToSpriteTable
+BBFA	UpdatePlayerState
+BC1C	HandleDemoMode
+BC38	HandlePlayerInput
+BC44	CountPlayerFrames
+BCF9	MovePlayer
+BD26	ApplyPlayerDirection
+BD70	ComputePlayerPosition
+BDE1	StorePlayerSprite
+BEE4	BuildBubbleTable
+BF17	UpdateBubbles
+BF53	PlayBubbleSound
+BF67	SpawnBubble
+BF83	DrawBubble
+BF9A	DispatchBubbleHandler
+BFAF	ResetLevel
+BFBA	ClearSpriteTable
+
+C000	ClearNametableRam
+C00F	PlayStageMusic
+C2A7	DispatchLevelScript
+C2BF	ResetPpuAndLoadTiles
+C3C8	SetVramPointer
+C414	ClearSpriteEntry
+C456	TickStageDelay
+C505	UpdateStageMode
+C62A	DisablePpuRendering
+CC11	SetPlayerActive
+CC56	CheckPlayerActive
+CCCF	TickSoundOnEvenFrame
+CD18	UpdateSoundEngine
+CF32	CheckActorCount
+D0E7	TickActorsOnEvenFrame
+D1B0	InitPlayerPosition
+D21A	TickTimerOnEvenFrame
+D2C0	ResetScrollOnEvenFrame
+D507	InitBubbleState
+D537	UpdateBubbleFrame
+D563	TickHudOnEvenFrame
+D5CF	TickSpritesOnEvenFrame
+D615	SetSoundChannels
+
+
+
+# ---- the second half of the image (banks 4-7) ----
+Bank4:800D	Bank4_CallBankedHandler
+Bank4:80A7	Bank4_StartVramWrite
+Bank4:8161	Bank4_UpdateNametable
+Bank5:A726	Bank5_UpdateSound
+Bank5:A784	Bank5_ReadSoundTable
+Bank5:AB50	Bank5_SetSoundMode
+Bank7:FF70	Bank7_SwitchPrgBank