disasm/Lunar Pool (U)/OVERVIEW.md

Lunar Pool (U)

ROM: Lunar Pool (U).nes (24,592 bytes, iNES). Status: PASSES 1-3 COMPLETE; PROMOTED TO THE TOP LEVEL 2026-10-18 — 5,300 instructions / 11,077 code bytes (67.6%) / 5,301 data bytes / the 6 vector bytes as .word, byte accounting exact (11,077 + 5,301 + 6 = 16,384), and BYTE-IDENTICAL for the whole ROM (header + PRG + CHR) via cmp reconstructed.nes rom.nes. Pass 2 named all 705 labels — Label_<addr> is gone — and Pass 3 named 33 data structures and finished the zero-page audit (38 semantic aliases, 66 deliberately neutral ZpXX, ten former phantom aliases deleted). The ~354 bytes the CDL could not settle stay .byte on purpose; they are itemised under Known remaining gaps.

ROM Facts

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

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

Vector	Target	Note
NMI	$FF65	per-frame heartbeat
RESET	$E80C	non-$C000 entry — the tracer has to seed it explicitly (--extra-seed 0xE80C)
IRQ	$FF64	a bare rti sitting immediately before the NMI handler, so IRQs are effectively ignored

Pass Status

Pass	Status	Description
Pass 0	Superseded	prg.s was a 12-line .incbin of the whole PRG — no disassembly at all
Pass 1	Complete	Static code/data split, then reclassified against a Mesen Code Data Logger capture (see below). As Pass 1 delivered it: 5,285 instructions / 11,041 bytes emitted as instructions (67.4%) / 5,343 bytes emitted as data (.byte, plus the six vector bytes as .word); 11,041 + 5,343 = 16,384 exactly. Labels: 640 Label_<addr> plus Reset/NmiHandler/IrqHandler.
Pass 2	Complete	NES hardware constants in symbols.inc; zero-page aliases in locals.inc; and all 705 labels named — Label_<addr> is gone from the file. 17 dispatch targets that carried no label at all (UpdateObjects_Render_Sound $C05C, SetupRound $EB60, PrintStageNumber $E21A, SetPpuAddr $F989, …) were given labels and routine headers. Naming rule used: PascalCase for jsr/jmp targets and logical block heads, <Block>_<Role> (_Loop, _Next, _Alt, _Done, _Skip, _Return, _Store, …) for targets inside a routine; jsr/jmp operands stay raw numeric — this file's convention, as in Joypad Test Cartridge (U) — while branch operands are symbolic. (Earlier revisions claimed 218 entries renamed, 195 of them SubC<addr>; no SubC label ever existed — git log -S SubC finds no commit that added one.)
Pass 3	Complete	Zero-page audit: 38 semantic aliases (object core, VRAM write queue, VRAM read-back, PPU helpers) and 66 neutral ZpXX whose roles are documented as deliberately unproven in locals.inc. Data structures: 33 tables/blocks named (table below). Vectors are .word NmiHandler, Reset, IrqHandler. What is still unnamed is the residue listed under Known remaining gaps — it stays .byte on purpose.

Pass 3 — the named data structures

33 tables and blocks were named. The code in this ROM bases several tables one entry early (lda $C478,y, lda $D4F8,y, lda $E9B9,x), so entry 0 is dead and the label sits on the first live entry; that is noted per table in prg.s.

Address	Label	What it is
$C000	ResetStub	Unreachable three-byte jmp Reset — the reset vector points at $E80C directly
$C0C0	ObjectOpcodeHandlerTable	19 words: object-script opcodes $80-$92 → handler address − 1
$C3B4	SoundChannelMask	01 02 04 08 FE FD FB F7 — APU channel mask/enable bytes
$C47A	ObjectStatePointerTable	84 words: per-object state pointers, indexed by (obj_ptr_lo + $0519,x) * 2
$C522	SpawnObjectTable	16 words: spawn-record pointers for ids 1-15 (id 0 dead), picked from the $0060-$0067 queue
$C543	StateTimerTable	Per-state timers 1,2,3,4,6,8,12,16,24,32,48,64,96,128,192,0, indexed by script opcode − $DF
$C552	AnimationPointerTable	Frame-sequence pointers
$C559	SpriteAnimationTable	Per-sprite animation descriptors used by the draw path
$CF40	VsCommandList	Inline RunCommandList script issued when loading a VS-COMP scene
$D057	DrawCellRun_TileTable	Corner tiles $3C $69 $C3 $96 selected by row bits in DrawCellRun
$D4FA	LayoutScriptTable	30 words: per-stage layout-script pointers
$D559	LayoutData	2,757 bytes of per-stage layout records
$E862	BootSignatureText	"JEMINI DAZO!!" plus the warm-boot signature compared against the RAM copy at $0440-$044F; the title attribute row at $E870-$E87F overlaps its tail
$E9A3	TitleColorCycleTable	22 colour codes cycled into the $0085-$0087 palette shadow each frame
$E9B9	StartGameAttributeRow	16 attribute bytes copied to the $0140-$014F shadow when a game starts
$EA00	TitleCommandList	Inline RunCommandList script for the title screen
$EC2A	StageAttributeTable	16 per-stage attribute bytes copied to the attribute shadow
$ED3F	SpritePaletteTable	4 × 4 sprite palettes, copied to the $0090-$009F palette shadow by Reset_LoadSpritePalettes
$EEE9	BallAppearTiles	Tiles for the ball-appear step animation (indexed by the step at $0340)
$EF2A	BallSinkTiles	Tiles for the ball-sink step animation
$F098	TileCollisionTable	27 words: collision flags per tile
$F5E4	EndingCommandList	Inline RunCommandList script for the ending screen
$F762	AimPhaseTable0	Three parallel 8-byte colour sequences shimmered into the $008B/$008F/$0092 palette shadow while aiming
$F786	StrPlayer1, StrShot, StrPlayer2, StrGameOver, StrPlayer3, StrHiScore, StrPerfect	The seven jsr $CBDC inline strings ($F786-$F861)
$FAC9	PaletteColorTable	12 rows of 4 colour codes → PPU palette entries (MapColorCodeToPalette)
$FECE	SineTable	64 entries read by GetSine
$FF90	PaddingFf	106 bytes of $FF filler between the last table and the vectors

The Pass 1 split came from a static trace only, and a static trace cannot see code that is reached through computed dispatch, nor can it tell inline string data from an instruction that happens to decode from the same bytes. Both errors were present.

Ground truth came from the emulator: Mesen's Code Data Logger marks every byte the CPU fetched as an opcode (Code) and every byte it read as data (Data). Playing the ROM through title → 1P → game over → VS COMP marked 10,028 PRG bytes Code (61.2%) and 1,534 Data; that is the classification oracle for every byte it observed. Where the CDL is silent the previous classification is kept, never guessed.

	code bytes	data bytes
As originally emitted by Pass 1	9,403	6,981
After the CDL reclassification	11,041	5,343

1,738 bytes that Pass 1 had emitted as .byte are executed code and are now instructions; 100 bytes it had emitted as instructions are read as data and are now .byte.

The result reconciles with the CDL exactly, with no disagreement in either direction:

emitted as	CDL says Code	CDL says Data	CDL never saw it
instructions	10,028	0	1,013
data (.byte/.word)	0	1,534	3,809

Every byte the CDL observed is therefore classified the way the CPU used it. The 1,013 instruction bytes the CDL never saw are Pass 1 static code plus the two inference steps below; the 3,809 unseen data bytes are the residue — 45 of them carry an undocumented opcode's disassembly in the audit comment (Pass 1 read them as code statically, but the CDL never watched the session fetch them, and ca65 V2.19 cannot encode those opcodes anyway, so they stay .byte with the disassembly recorded).

As an independent structural check, all 1,183 control-flow targets in the file — 633 jsr/jmp operands and 550 branch targets — land exactly on an instruction boundary; none points into an operand or a .byte run.

The rewrite is reproducible with _tools/cdl_reclass.py (dry run by default). Capture a CDL from the Mesen MCP with mesen_cdl_file(action:'save', memoryType:'NesPrgRom', filepath:'lunar.cdl') — the capture is cumulative, so it does not reset — then:

python3 _tools/cdl_reclass.py --dir "copilot" --cdl lunar.cdl \
  --override 0xC0C0-0xC0E5:D \
  --override 0xF81A-0xF825:C --override 0xF826-0xF82E:D --override 0xF82F-0xF83A:C \
  --override 0xF83B-0xF846:D --override 0xF847-0xF84B:C --override 0xF84C-0xF857:C \
  --override 0xF858-0xF861:D --override 0xF862-0xF866:C

Its output differs from this prg.s only in this provenance header, the .word vector split, and three jsr Label_CAA3 → jsr $CAA3 operand spellings (this file spells jsr/jmp operands as raw addresses and branch operands as Label_<addr>). Always run make afterwards.

Two inference steps were needed beyond the CDL because the capture never reached the hi-score screen. They are marked as inference, not ground truth:

• $C0C0–$C0E5 is a 19-entry little-endian 16-bit pointer table (read as lda $C0C0,y / lda $C0C1,y). Pass 1 had decoded it as a cmp (ZpXX,x) chain; the CDL only observed the few entries the current game state walked. Code resumes at $C0E6 (tax), which is a real branch target from $C101.
• $F81A (hi-score) and $F84C ("perfect") are text routines. They are never reached in normal play until a hi-score is beaten, so the CDL is silent; their inline-string structure is inferred from the CDL-confirmed twins $F77A and $F7E8.

The inline-string dispatcher (this is not a jump gate)

$CBDC (and its variant $CBC9, which also clears the PPU destination first) is a print-inline-string-and-return-after-it helper:

$CBDC  pla / sta ptr_lo        ; pop the caller's return address = the string address
$CBDF  pla / sta ptr_hi
$CBE2  jsr $CB5A               ; prepare the PPU destination
$CBE5  ldy #$00
$CBE7  lda (ptr_lo),y          ; next character
$CBE9  beq $CBF4               ; $00 terminates
$CBEB  jsr $CC29               ; emit it (advances ptr_lo/hi)
$CBEE  jsr $CB5A
$CBF1  jmp $CBE5
$CBF4  lda ptr_hi / pha        ; push the address of the byte after the $00 ...
$CBF7  lda ptr_lo / pha
$CBFA  rts                     ; ... and rts to it

So every jsr $CBDC in the image is immediately followed by a $00-terminated string that begins with the control byte $81 ($81 also acts as the word separator), and execution resumes after the terminator:

site	bytes	text
$F786	$81player$81$00	player
$F79B	$81shot$81$00	shot
$F7F4	$81player$81$00	player
$F809	$81game$81over$81$00	game over
$F826	$81player$81$00	player
$F83B	$81hi`score__$00	hi`score__
$F858	$81perfect_$00	perfect_

Earlier revisions of this document claimed a jmp ($7961) RAM-pointer dispatch at $F788/$F7F6/$F828. That was a flat-tracer phantom. The bytes after jsr $CBDC are the strings above; the decoder happened to start an instruction two bytes into player, reading $6C $61 $79 as jmp ($7961) — the operand is the middle of the word "player". Nothing in the ROM ever writes $7961/$7962, and $6000–$7FFF is unmapped on NROM, so such a jump could not work. The three sites are gone from the classification; no instruction in the corrected file is an indirect jmp.

The genuine computed dispatch that remains is small and resolved. $CBE5 re-reads its string pointer through ptr_lo/ptr_hi and re-enters its loop with it — plain code. $F193 does the reverse: it pushes Zp17/Zp16 and rtses, so a caller sets that pair and the rts transfers control to it; the pattern is named in locals.inc and every target is inside CDL-covered code.

Code the CDL proved but Pass 1 missed (largest runs)

Range	Bytes	What it is
$EA00–$EBAF	432	VS-COMP / select-screen logic ($EB16 is still unreached and stays data)
$EBF3–$ED4E	348	menu/round state machine
$CE35–$CF9A	358	collision/entity maths
$D4FA–$E01D	2,852	$D4FA 30-entry pointer table ($D4FA–$D535), the 35-byte code helper at $D536–$D558, then variable-length records from $D559
$F897–$F98F	249	high-score / attract handling
$C0F2–$C18C	155	object update chain (branches back to $C0E6)
$D325–$D391, $D2A0–$D2D3, $D1BB–$D209	240	further record/table walkers

Tracer fixes required during Pass 1

Three undocumented opcodes were missing from _tools/nesdis.py and were added, with the --undocumented switch (default off, so existing make regen pipelines stay byte-stable):

• $72 — RRA abs (the RRA family had $63/$67/$6F/$73/$77/$7B/$7F but not $72).
• $42 — NOP #imm (the family had $80/$82/$89/$C2/$E2 but not $42).
• $FA — NOP abs,X (the family had $1C/$3C/$5C/$7C/$DC/$FC but not $FA).

One emitter fix: ca65 silently rewrites an operand whose high byte is $00 into the shorter zero-page form (sta $00FF,x becomes sta $FF,x, emitting $95 instead of $9D). render() now emits the a: prefix for ABS/ABSX/ABSY/IND operands with a high byte of $00, forcing the absolute form so the bytes match the ROM. operand_value() strips the prefix when parsing.

Known remaining gaps

• The static tracer reported two overlaps ($C3BB — resolved with --data 0xC3BB:1 — and $F0EF) and three rejected mis-aligned stubs. The residue that remains is the CDL's: 5,343 bytes (32.6%) are still emitted as data (.byte, plus the six vector bytes as .word).
• Unreached in the CDL session, therefore still unclassified: the hi-score entry screen ($F81A+ / $F84C+ are inferred by symmetry, above), the 2-player-only branches, and $EB16 (a poll loop behind beq at $EB11, emitted as a raw beq *+$05).
• locals.inc carries 104 aliases: 38 semantic (see the Pass 3 notes at the foot of the file) and 66 neutral ZpXX. Ten further aliases were deleted by the reclassification: they were phantoms — $49/$84/$8A/$AA/$C0 came from the mis-decoded $C0C0 table, and $3B/$65/$67/$72/$81 were ASCII characters of the inline strings read as operands.

copilot/ Contents

File	Purpose
Lunar Pool (U).nes	original ROM image (reference)
prg.bin / header.bin / chr.bin	split image, produced by _tools/splitnes.py
prg.s	disassembly: 5,285 instructions with per-instruction address/byte audit comments, unclassified bytes kept as .byte/.word
symbols.inc	shared NES hardware constants (PPU/APU/controller, from the skeleton)
locals.inc	project-local zero-page aliases — 38 semantic, 66 neutral ZpXX; Pass 3 evidence notes at the foot of the file
linker.cfg	PRG at $C000, 16 KB, fill = yes
Makefile	links reconstructed_prg.bin and cmps it against prg.bin
reconstructed_prg.bin	build output from the last verified build

Header/CHR are reproduced verbatim from header.bin/chr.bin (not linked): make verifies PRG bytes only at this stage, which is exactly what a skeleton proves. When this project is promoted to a full disassembly, header.s / chr.s (as e.g. Burger Time (U)) and a full-ROM make target get added.

Build

cd "_wip/Lunar Pool (U)/copilot"
make        # → cmp reconstructed_prg.bin prg.bin → "BYTE-IDENTICAL"

Next Steps (per PROMPTS.md)

1. Pass 1 — complete. The split is CDL-verified; the remaining .byte runs are either data (string/table/record bytes) or CDL-unreached code (above).
2. Pass 2 — partial: the hardware constants and the zero-page aliases are named. The remaining Pass 2 work is routine-label renaming — all 640 entries are address-derived Label_<addr>, and git log -S SubC shows this was never done for this project.
3. Pass 3 — in progress. Zero-page audit complete (38 semantic + 66 neutral), and the $FFFA–$FFFF vectors are now .word NmiHandler, Reset, IrqHandler. Remaining: name the data tables and structures — the $D4FA 30-entry pointer table and the variable-length records at $D559+, the $C0C0 entry-point table, the $C47A–$CA20 block.
4. Promotion — move to a top-level <name>/copilot/ folder, add a full-ROM build (header.s + chr.s + vectors), and write the power-on flow OVERVIEW.md in the established style; then it joins the root index's numbered inventory.