disasm/NROM/MUSCLE (U)

MUSCLE (U) — Pass 3 (data names and structures)

ROM: MUSCLE (U)/M.U.S.C.L.E. (U).nes (24,592 bytes, iNES). Status: PASS 3 COMPLETE — byte-identical, including the bytecode VM layer. All three passes are done: Pass 1 split code from data, Pass 2 replaced every Label_XXXX and 87 zero-page aliases, Pass 3 named and structured every data region, finished the routine descriptions, and resolved the reused zero page and the unreachable stubs.

The 69 data blocks the tracer left are now accounted for one by one in Pass 3 data-table inventory below: every block carries a name, a structure and the address of the instruction that reads it, or the evidence that nothing reads it. Two blocks that had been given bytecode-program names turned out not to be bytecode at all and were renamed - DeathSequenceVramStream and LevelOamTemplateTable.

make regen in copilot/ replays Pass 1 → Pass 3 from prg.bin and is byte-for-byte reproducible. Every instruction still carries its ; CPU:$xxxx PRG:xxxx AA BB audit comment, so none of this touched a byte.

	Result
Code	10,634 bytes (5,253 instructions) across 705 routines — 0 Label_XXXX remaining
Data	5,750 bytes across 69 named regions — 0 unlabelled blocks, 69 rows in the inventory
Structured tables	127 .word entries emitted one per line with their resolved target
Routine descriptions	0 boilerplate ; Global: lines remaining (94 hand-written, 606 generated from call sites)
Zero page	163 aliases: 89 named, 1 reused byte carrying two names, 73 ZpXX
Build	Byte-identical ROM verified.

Power-on flow analysis

Derived from the disassembly by _tools/derive_poweron.py; the call graph is walked from the reset entry.

RESET is at $8000 (Reset). The CPU comes here out of reset with the PPU and APU in their power-on state and the zero page and RAM uninitialised.

The reset path calls:

Address	Routine
$800E	WaitForFirstPpuWarmup (falls through)
$8019	WaitForSecondPpuWarmup (falls through)
$802C	InitializeGameState (falls through)
$803B	InitializeGameState_OnNonzero_803B (falls through)

NMI is at $86CB (NmiHandler). It is the per-frame handler; what it calls:

Address	Routine
$8759	FinishNmiRegisters

IRQ is at $8764 (IrqHandler) - a different address from RESET.

ROM Facts

Property	Value
Mapper	0 (NROM)
PRG	16 KB, mapped low at $8000–$BFFF (mirrored to $C000–$FFFF)
CHR	8 KB
Mirroring	Vertical
Battery / trainer	none
ROM SHA-256	d3da17f2b67d517e4d519659407d6f0e3cd7a2a4d89d31da6bb2727afce798dd
PRG SHA-256	c9061b6d3d06f56e3c2f89337d8e59c159f494ff9efad50852fcd19621f0b03e

The skeleton's $C000 assumption was wrong. A 16 KB NROM PRG is normally mirrored from $C000, but the RESET vector is $8000, so this image is wired to $8000 and every address in the source (and in linker.cfg) is $8000-based. The CPU still fetches the vectors from the mirror at $FFFA, which is why InterruptVectors is the last six bytes of the PRG.

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

Vector	Target	Note
NMI	$86CB (NmiHandler)	the entire per-frame update; see flow below
RESET	$8000 (Reset)	confirms the low mapping
IRQ	$8764 (IrqHandler)	a single RTI, shared with the NMI epilogue; see below

Power-On Flow

Reset ($8000):

1. sei, ldx #$FF, stx $0320, txs — X points the stack at the top of page 1 and $0320 is set to $FF as the "an NMI already fired during init" latch.
2. Two lda $2002 / bpl spin loops blank the PPU and confirm vblank. Each write is followed by a nop before its poll ($800D, $8018) — the align-before-read habit of the original assembler.
3. $4017 = $40 (APU frame counter IRQ inhibit), $4010 = 0, and zero the DMC address/length pair at zero page $FA/$FB (the same two bytes the controller reader later reuses).
4. Clear $0326, $032B, $032C, zero page $FF, then fill $0300-$032C with zero.
5. Set SourcePointerLo/Hi = $9E/$B8 and DestinationPointerLo/Hi = $00/$04, then run UpdateNametableFromStream, which decodes the compressed nametable into $0400.
6. If the stream actually changed VRAM, latch the tighter scroll bound into $0328-$032A, reset the frame counters to 0/1/2/3, and fall into StartStageSequence.

NmiHandler ($86CB):

1. Push A, X, Y in that order.
2. lda $0320 / beq $86D8 / jmp $8759. Reset leaves $0320 = $FF, so the first NMI skips the frame update entirely; from then on $0320 is cleared each frame (see 6) and this is a fall-through.
3. Set $0320 = $FF and bump the 16-bit FrameCounterLo/Hi in zero page $24/$25.
4. $2001 = 0 (blank rendering), $2003 = 0, $4014 = $02 — OAM DMA from $0200.
5. Dispatch on the game state at $0322: zero goes to the SubModeFlag test, negative jumps to the object-list housekeeping at $86AD, positive falls into UpdateRoundLogic. The branches call PollControllerAndAdvance, UpdateStageActors, UpdateObjectCollisions, RunGameStateDispatcher, BuildOamList and PlayDeathSequence in turn.
6. FinishNmiUpdates ($8751): lda $0321 / bne $8759 — the $0320 latch is cleared only when $0321 is zero, so a frame that requested continued work stays latched. Then lda $2002 to release the PPU address latch, jsr UpdateSoundFrame, and pla/tay/pla/tax/pla.

The IRQ vector word is the NMI epilogue's RTI. After the three plas the next byte is $8764, which is both IrqHandler and the rti that ends every NMI — one RTI serving two vectors. The game never re-enables interrupts, so the IRQ is unreachable in practice.

Architecture: this ROM dispatches by jump table, not by direct call

A plain recursive trace from the vectors reaches only 50.6% of the PRG. The gap is not dead code — it is reached through four dispatch tables and two zero-page indirect jumps that a static descender cannot follow. Resolving them took code coverage to 64.9%.

Mechanism	Location	Size	Index
BytecodeProgramPointerTable	$8CEF	38 × 16-bit	(token & $3F) at $9AD8
BytecodeHandlerTable	$9237	40 × 16-bit	token - $C8 at $9AF9
SecondaryBytecodeHandlerTable	$9F2B	16 × 16-bit	(token & $0F) at $9F85
LevelVramWriterTable	$AC35	3 × 16-bit	the level byte $0326 at $AC28
DispatchThroughPointer	jmp ($001C) at $9B05	—	reached from the first three tables
jmp ($0010)	$AC32	—	reached from LevelVramWriterTable

RunBytecodeInterpreter ($9AE8) reads a token through (BytecodeStreamPointerLo),y; tokens $C8–$EF are converted to a handler address and dispatched through jmp ($001C); everything else is an operand consumed by the running handler.

The handler tables have holes. The interpreter masks the program index with $3F, so BytecodeProgramPointerTable is indexed 0–63 — but entry 38 already reads the first byte of BytecodeProgram_00, so the table is exactly 38 entries and the caller must guarantee a smaller index. BytecodeHandlerTable entries 0 and 2 hold $928D and $9287, which are the addresses of the code immediately after the table: slots the assembler never filled.

Pass 3 — Data Structure

All 69 data regions are labelled. The four composite regions from Pass 1 were split into their real tables using the readers in decoded code:

$8CEF–$9286 (1,432 bytes) → three structures

Region	Size	What it is
BytecodeProgramPointerTable $8CEF–$8D3A	76	38 × .word, targets printed per entry
BytecodeProgram_00 … BytecodeProgram_25 $8D3B–$9236	1,276	the 38 programs the table reaches, each labelled with the table index that reaches it
BytecodeHandlerTable $9237–$9286	80	40 × .word opcode handlers

The programs are recovered from the pointer table: sort the 38 entries, and each program runs from one entry to the next. All 38 entries are distinct, so the table reaches 38 distinct programs - one for every entry, and every label BytecodeProgram_00 … BytecodeProgram_25 is reached by exactly one of them.

$B0CB–$BFFF (3,893 bytes) → eleven structures

Region	Size	What it is
SoundNotePeriodTable $B0CB–$B0E2	24	12 × .word tone periods (cmp #$0C bounds the index)
SoundNoteDurationTable $B0E3–$B0F2	16	note durations, index duration - $F0
ApuChannelEnableBitsSet $B0F3–$B0F6	4	OR-ed into ApuEnableMask, indexed by channel*4
ApuChannelEnableBitsClear $B0F7–$B0FA	4	AND-ed into ApuEnableMask, same index
StageNametableAndObjectData $B0FB–$B91A + _1 $B971–$BD27 + _2 $BD2A–$BEBF	3,523	the per-stage payload
StageDataFiller $B91B–$B970	86	an 86-byte $FF pad between stage blocks
StageDataPointerLow $BD28–$BD29	2	one base offset per player; $32 apart
StageDataTail $BED0–$BF8F	192	tail of the stage block
InitialOamAttributes / InitialOamTiles $BEC0–$BECF	16	8 entries each, ldx #$07
VramBlockByteCounts / VramBlockSourceLowBytes $BF90–$BF9F	16	8 transfer blocks each; high byte always $02
SoundSequenceAndLevelData $BFA0–$BFFA	91	the $B1A1/$B1B0/$B2B9/$B3B2 sequences the sound engine points at
InterruptVectors $BFFB–$BFFF	5	NMI / RESET / IRQ

The stage payload is reached through StageDataPointerLow plus the 16-bit offset the bytecode stream carries, so no constant address indexes it and its record structure is not resolvable from a static trace. That is recorded in the source rather than guessed at.

$A5F4–$A65F (108 bytes) → two structures

StageDescriptorPointerTable ($A5F4–$A617, 18 × .word) and StageDescriptorData ($A618–$A65F). Two readers share the table: one reads (A & $1E) from entry 0, the other starts at entry 9, and entry 18 already reads descriptor text — so it is exactly 18 entries. The targets sit twelve bytes apart ($A618, $A624, $A630, $A63C, $A648) with a final ten-byte record at $A654; each is a short header followed by a descending run of tile indices.

Remaining tables

Region	Size	What it is
AttributeBlockDeltaTable $8B7D–$8B91	21	7 × 3-byte {source lo, source hi, destination lo} deltas
OamShadowTemplate $9EF4–$9F13	32	the initial OAM block copied into $0300
VramRunFillValues $ACBD–$ACC8	12	the 12 fill values the VRAM run tokens $B8–$C3 select
AnimationFrameCollisionBits $AE35–$AE44	16	animation frame → collision flag bits
StandaloneBytecodeProgram … _2	110	three token programs not in BytecodeProgramPointerTable

Pass 3 data-table inventory

Every one of the 69 data blocks the tracer left in prg.s is listed here, once. Size is the byte count of the block; Name is the label in prg.s (a dash means the block has no name); Structure says what the bytes are; Read by gives the address of the instruction that reads them. Where nothing in this dump reads a block, the row says so and says what the bytes are instead.

The bytecode VM dominates the PRG, so most of the rows are token programs: a program is not a table. A byte in $C8–$EF is an opcode, handled by BytecodeHandlerTable ($9237) and dispatched by RunBytecodeInterpreter ($9AE8); every other byte is a literal operand. The listing above each program's .byte data in prg.s spells the tokens out.

Address	Size	Name	Structure	Read by
$85ED–$8638	76	StandaloneBytecodeProgram	bytecode program: 4 opcodes ($E8, $EE, $EC, $EE) and 72 literal operands - a token stream, not a table	interpreted by BytecodeHandlerTable ($9237) through RunBytecodeInterpreter ($9AE8); it is not in BytecodeProgramPointerTable, and no instruction in this dump points at it
$881F–$8836	24	DeathSequenceVramStream	compressed VRAM (nametable RLE) stream, not bytecode: it contains no byte in $C8–$EF	the source pointer is set by PlayDeathSequence ($8839/$883D) and the block is decoded by WriteCompressedVramBlocks ($ACF5) with the RLE decoder at $AC82/$AC88
$8A1E–$8A27	10	StandaloneBytecodeProgram_2	bytecode program: 1 opcode ($CD) and 9 literal operands	interpreted through BytecodeHandlerTable ($9237); not referenced by any instruction or pointer in this dump
$8B7D–$8B91	21	AttributeBlockDeltaTable	7 × 3-byte {source lo, source hi, destination lo} deltas	sbc $8B7D,x at $8B3E, sbc $8B7E,x at $8B45 and sbc $8B7F,x at $8B4C (ClearAttributeRegion)
$8CEF–$8D3A	76	BytecodeProgramPointerTable	38 × 16-bit pointers to the bytecode programs that follow	lda $8CEF,y at $9ADC and lda $8CF0,y at $9AE1 (SpawnActorPairAlt_OnNonzero_9AD8)
$8D3B–$8D3F	5	BytecodeProgram_00	bytecode program: 4 opcodes, 0 literal operands; table index 13	through BytecodeProgramPointerTable ($9ADC) and RunBytecodeInterpreter ($9AE8)
$8D40–$8D5B	28	BytecodeProgram_01	bytecode program: 16 opcodes, 4 literal operands; table index 36	as above
$8D5C–$8D8C	49	BytecodeProgram_02	bytecode program: 9 opcodes, 34 literal operands; table index 37	as above
$8D8D–$8D95	9	BytecodeProgram_03	bytecode program: 6 opcodes, 0 literal operands; table index 22	as above
$8D96–$8D9E	9	BytecodeProgram_04	bytecode program: 6 opcodes, 0 literal operands; table index 23	as above
$8D9F–$8DB5	23	BytecodeProgram_05	bytecode program: 5 opcodes, 16 literal operands; table index 33	as above
$8DB6–$8DE1	44	BytecodeProgram_06	bytecode program: 9 opcodes, 30 literal operands; table index 34	as above
$8DE2–$8E2C	75	BytecodeProgram_07	bytecode program: 9 opcodes, 60 literal operands; table index 35	as above
$8E2D–$8E78	76	BytecodeProgram_08	bytecode program: 10 opcodes, 60 literal operands; table index 14	as above
$8E79–$8EA8	48	BytecodeProgram_09	bytecode program: 12 opcodes, 30 literal operands; table index 11	as above
$8EA9–$8EF3	75	BytecodeProgram_0A	bytecode program: 26 opcodes, 32 literal operands; table index 24	as above
$8EF4–$8F19	38	BytecodeProgram_0B	bytecode program: 4 opcodes, 32 literal operands; table index 25	as above
$8F1A–$8F1F	6	BytecodeProgram_0C	bytecode program: 4 opcodes, 0 literal operands; table index 28	as above
$8F20–$8F47	40	BytecodeProgram_0D	bytecode program: 3 opcodes, 36 literal operands; table index 31	as above
$8F48–$8F70	41	BytecodeProgram_0E	bytecode program: 3 opcodes, 36 literal operands; table index 32	as above
$8F71–$8F93	35	BytecodeProgram_0F	bytecode program: 34 opcodes, 0 literal operands; table index 29	as above
$8F94–$8FFC	105	BytecodeProgram_10	bytecode program: 3 opcodes, 100 literal operands; table index 16	as above
$8FFD–$9007	11	BytecodeProgram_11	bytecode program: 7 opcodes, 0 literal operands; table index 15	as above
$9008–$9070	105	BytecodeProgram_12	bytecode program: 4 opcodes, 98 literal operands; table index 17	as above
$9071–$907C	12	BytecodeProgram_13	bytecode program: 7 opcodes, 2 literal operands; table index 27	as above
$907D–$9080	4	BytecodeProgram_14	bytecode program: 3 opcodes, 0 literal operands; table index 0	as above
$9081–$90A5	37	BytecodeProgram_15	bytecode program: 11 opcodes, 20 literal operands; table index 1	as above
$90A6–$90B8	19	BytecodeProgram_16	bytecode program: 2 opcodes, 16 literal operands; table index 26	as above
$90B9–$90C9	17	BytecodeProgram_17	bytecode program: 2 opcodes, 14 literal operands; table index 5	as above
$90CA–$90D6	13	BytecodeProgram_18	bytecode program: 9 opcodes, 0 literal operands; table index 2	as above
$90D7–$90DD	7	BytecodeProgram_19	bytecode program: 5 opcodes, 0 literal operands; table index 12	as above
$90DE–$9118	59	BytecodeProgram_1A	bytecode program: 58 opcodes, 0 literal operands; table index 3	as above
$9119–$9130	24	BytecodeProgram_1B	bytecode program: 16 opcodes, 0 literal operands; table index 4	as above
$9131–$9135	5	BytecodeProgram_1C	bytecode program: 4 opcodes, 0 literal operands; table index 6	as above
$9136–$9140	11	BytecodeProgram_1D	bytecode program: 7 opcodes, 0 literal operands; table index 7	as above
$9141–$9174	52	BytecodeProgram_1E	bytecode program: 18 opcodes, 24 literal operands; table index 8	as above
$9175–$918A	22	BytecodeProgram_1F	bytecode program: 14 opcodes, 0 literal operands; table index 18	as above
$918B–$91DF	85	BytecodeProgram_20	bytecode program: 16 opcodes, 56 literal operands; table index 19	as above
$91E0–$91EB	12	BytecodeProgram_21	bytecode program: 8 opcodes, 0 literal operands; table index 20	as above
$91EC–$922B	64	BytecodeProgram_22	bytecode program: 10 opcodes, 48 literal operands; table index 21	as above
$922C–$922E	3	BytecodeProgram_23	bytecode program: 2 opcodes, 0 literal operands; table index 9	as above
$922F–$9231	3	BytecodeProgram_24	bytecode program: 2 opcodes, 0 literal operands; table index 10	as above
$9232–$9236	5	BytecodeProgram_25	bytecode program: 4 opcodes, 0 literal operands; table index 30	as above
$9237–$9286	80	BytecodeHandlerTable	40 × 16-bit opcode handlers, index = (token − $C8)	lda $9237,x at $9AF9 and lda $9238,x at $9AFE (RunBytecodeInterpreter)
$9EF4–$9F13	32	OamShadowTemplate	the 32-byte initial OAM block copied into the shadow at $0300	lda $9EF4,y at $839B (LoadOamShadowFromTable)
$9F2B–$9F4A	32	SecondaryBytecodeHandlerTable	16 × 16-bit handlers, index = (token & $0F) × 2	lda $9F2B,y at $9F85 and lda $9F2C,y at $9F8A (MoveActorByOpcode)
$A5F4–$A617	36	StageDescriptorPointerTable	18 × 16-bit pointers into StageDescriptorData	lda $A5F4,y at $A539 and lda $A5F5,y at $A53E; the writer reads lda $A606,y at $A593 and lda $A607,y at $A598
$A618–$A65F	72	StageDescriptorData	six 12-byte descriptor records (tile/attribute runs) plus a final 10-byte record; the last record ends with the two $30 terminators	read through StageDescriptorPointerTable ($A539/$A53E/$A593/$A598)
$AB14–$AB67	84	LevelOamTemplateTable	not bytecode (no byte in $C8–$EF): ten 8-byte per-level OAM records, the level byte at $0326 selecting the record; the last four bytes, $AB64–$AB67, are the OAM slot copied to $031C	the source pointer is built at $AB85–$AB96 from $0326 and the block is copied by LoadShadowOamBlock ($AB98); $AB64 is read at $AB70/$AB74 and copied by the routine at $AB68
$AC35–$AC3A	6	LevelVramWriterTable	3 × 16-bit VRAM writers, index = the level byte at $0326	lda $AC35,x at $AC28 and lda $AC36,x at $AC2D (SelectLevelVramWriter)
$ACBD–$ACC8	12	VramRunFillValues	the 12 fill values the compressed-VRAM run tokens $B8–$C3 select, index = token − $B8	lda $ACBD,x at $ACAA (WriteVramRunToken)
$AE35–$AE44	16	AnimationFrameCollisionBits	16 animation-frame → collision-flag bit entries, index = frame & $0F	lda $AE35,x at $AE2F
$AF37–$AF3A	4	UnreachableSoundInitIsland	four bytes of orphaned code (lda $E9 / bne $AF34) that follow the rts ending InitializeSoundEngine	not referenced by any instruction
$B0CB–$B0E2	24	SoundNotePeriodTable	12 × 16-bit tone periods, index = note number (guarded by cmp #$0C)	lda $B0CC,y at $AFEA and lda $B0CB,y at $AFEF (ComputeTonePeriod)
$B0E3–$B0F2	16	SoundNoteDurationTable	16 note durations, index = (duration byte − $F0)	lda $B0E3,y at $B046 (ReadNoteDuration)
$B0F3–$B0F6	4	ApuChannelEnableBitsSet	four 1-byte masks OR-ed into the APU enable mask, index = channel × 4	ora $B0F3,x at $B05F (BuildApuChannelMask)
$B0F7–$B0FA	4	ApuChannelEnableBitsClear	four 1-byte masks AND-ed into the APU enable mask, index = channel × 4	and $B0F7,x at $AF6D (RebuildApuEnableMask)
$B0FB–$B91A	2080	StageNametableAndObjectData	a shared data pool: compressed-VRAM RLE streams, per-actor bytecode and object lists mixed together	no constant address indexes it: adc $BD28,x at $A063 forms the address from a runtime value, and the RLE reader at $AC82 walks it sequentially
$B91B–$B970	86	StageDataFiller	an 86-byte $FF pad inside the pool	not referenced by any instruction
$B971–$BD27	951	StageNametableAndObjectData_1	continuation of the shared pool	as above
$BD28–$BD29	2	StageDataPointerLow	one base offset per player; the second player's copy is $32 further on	adc $BD28,x at $A063 (ProcessBytecodeOpcode)
$BD2A–$BEBF	406	StageNametableAndObjectData_2	continuation of the shared pool	as above
$BEC0–$BEC7	8	InitialOamAttributes	8 sprite-attribute bytes (ldx #$07)	lda $BEC0,x at $89B5 (CompactOamList)
$BEC8–$BECF	8	InitialOamTiles	8 sprite-tile bytes	lda $BEC8,x at $89C0 (CompactOamList)
$BED0–$BF8F	192	StageDataTail	the tail of the shared pool, ahead of the VRAM block descriptors	not referenced by any instruction
$BF90–$BF97	8	VramBlockByteCounts	8 block sizes fed to ExecuteVramTransfer	lda $BF90,x at $89EE (ReadControllerAndInit)
$BF98–$BF9F	8	VramBlockSourceLowBytes	8 block source low bytes; the high byte is always $02	lda $BF98,x at $89F7 (ReadControllerAndInit)
$BFA0–$BFFA	91	SoundSequenceAndLevelData	the $B1A1/$B1B0/$B2B9/$B3B2 sound sequences plus the level tables, ending just before the vectors	not read by a constant address: the sound engine copies a sequence address from SoundSequencePtrLo1/Hi1 into SoundReadPointerLo/Hi ($AF76/$AF7A) and reads through it ($AF80, $B03C)
$BFFB–$BFFF	5	InterruptVectors	the three CPU vectors (NMI $86CB, RESET $8000, IRQ $8764), mirrored into the ROM at $FFFB–$FFFF	read by the CPU's reset logic, not by an instruction

What the inventory settled

• Two blocks that looked like bytecode programs are not bytecode at all. $881F is the compressed VRAM stream for the death sequence - PlayDeathSequence points the source pointer at it and WriteCompressedVramBlocks decodes it - and $AB14 is the per-level OAM template table that LoadShadowOamBlock copies into the shadow at $0300. Both contain no byte in $C8–$EF, which is the test the interpreter itself applies, so the interpreter could never have run them.
• The four handler tables are the whole dispatch mechanism, and they are the only ROM data the VM touches directly: BytecodeProgramPointerTable picks the program, BytecodeHandlerTable picks the opcode handler, and the two secondary tables serve the movement opcodes.
• The stage payload is reached only through a runtime value. Exactly one operand in $B0FB–$BEBF exists in the whole image - the adc $BD28,x at $A063 - so the record structure of that pool cannot be enumerated statically. It is recorded as a shared pool rather than as per-stage data.

What Pass 3 settled

The $14/$15 reuse. These are both the 16-bit block counter for the compressed-VRAM transfer and the accumulator for the collision bit flags. locals.inc carries both names, and zero_page_ranges.tsv applies StreamBlockCountHi only inside AdvanceCountWord, so the same byte is not mislabelled at all 53 of its other uses. This is the alias pattern AGENTS.md asks for — RandomStateAlt = $E4 beside RandomState0 = $54 — done with a range instead of a blind rename.

The four hand-seeded entries are provably dead. $8644, $8653, $9CAD and $ABF7 have no 16-bit reference anywhere in the image except jsr $8644 at $8654, and none of them appears in either bytecode handler table. They are kept as code — rts-terminated and register-plausible — but their headers now say so explicitly rather than leaving a reader to wonder.

$AF37–$AF3A stays data. lda $E9 / bne $AF34 sits right after the rts that ends InitializeSoundEngine and branches back into the middle of it. Unreachable, incoherent as a routine, and referenced by nothing. It is labelled UnreachableSoundInitIsland so the decision is visible.

Every routine header now says something. The 94 subsystem routines keep hand-written descriptions; the other 606 get a generated line naming the routine and its visible call sites, which is factual. Nothing still reads "Contextual control-flow entry identified from its parent routine".

copilot/ Contents

File	Purpose
rom.nes	symlink to ../M.U.S.C.L.E. (U).nes
prg.bin / header.bin / chr.bin	split image (_tools/splitnes.py)
prg.s	fully classified and named PRG source (12,922 lines)
header.s / chr.s	incbin of the untouched header and CHR
symbols.inc	shared NES hardware constants
locals.inc	163 zero-page aliases with read/write counts and referencing addresses
routine_names.tsv	Pass 2 routine names (address → name)
label_names.tsv	generated: the full Label_XXXX → final name map
zero_page_names.tsv	Pass 2 zero-page names with usage notes
zero_page_ranges.tsv	Pass 3 range-scoped names for reused bytes
data_regions.tsv	Pass 3 data-region labels, record formats and notes
routine_purposes.tsv	the 94 hand-written ; Global: descriptions
linker.cfg	HEADER at $0000, PRG at $8000, CHR at $0000
Makefile	all builds and byte-compares; pass1 / pass2 / pass3 / regen regenerate

Build

cd "MUSCLE (U)/copilot"
make          # header.o + prg.o + chr.o -> reconstructed.nes, cmp vs rom.nes
# "Byte-identical ROM verified."
make pass1    # re-run _tools/nesdis.py with the recorded classification flags
make pass2    # pass1 + naming + descriptions + data structuring + locals.inc
make pass3    # pass2 + _tools/bytecode_dis.py token listings over the 42 VM programs
make regen    # same as pass3; the whole pipeline is byte-for-byte reproducible

Pass 3b — the bytecode VM, decoded

The 42 token programs (BytecodeProgram_00–_25 plus StandaloneBytecodeProgram–_3) are the game's scripting layer. Each now carries a byte-for-byte token listing above its unchanged .byte data, produced by _tools/bytecode_dis.py (wired in as make pass3).

The encoding

RunBytecodeInterpreter ($9AE8) is the whole dispatch:

$9AEA  lda ($1A),y          ; fetch one byte
$9AEC  iny
$9AED  cmp #$F0 / bcs $9B08  ; >= $F0 -> literal
$9AF1  cmp #$C8 / bcc $9B08  ; <  $C8 -> literal
$9AF5  sbc #$C8 / asl a / tax
$9AF9  lda $9237,x  / sta $1C ; BytecodeHandlerTable
$9AFE  lda $9238,x  / sta $1D
$9B05  jmp ($001C)            ; run the handler

and the literal path ($9B08) pushes the byte onto the operand list:

$9B08  pha
$9B09  lda ($1A),y / iny      ; the operand byte itself
$9B0C  jsr $94C8             ; save stream position, restore the operand index
...
$9B22  sta $0033,Y           ; operand list
$9B25  jsr $9CBB             ; block/stream bookkeeping

So the encoding is one byte per element: a byte in $C8–$EF selects one of the 40 BytecodeHandlerTable entries, and every other byte is a literal operand appended to $0033[Y] (and accumulated into $003C[Y]). There are no variable-length opcodes except four.

Four opcodes take one inline operand byte. Their handler's first instructions are lda ($1A),Y / iny, so the byte after the token is consumed by the opcode itself:

Opcode	Handler	Inline byte stored in	Meaning
$CB	$946D	$7C,X (count) and $7E,X (body address)	LOOP_BEGIN
$D1	$950B	$43,X	SET_RATE
$D7	$937C	used as a count for the $A660 blit	DRAW_SPRITE
$E1	$9465	$7A,X	SET_WAIT

$CB/$C9 are the loop pair: LOOP_BEGIN marks the stream position and loads the counter, and LOOP_END ($9477) decrements $7C,X and, if still non-zero, reloads Y from $7E,X — which rewinds the interpreter to the top of the loop body.

What was decoded

Programs listed	42 blocks: 38 reached by BytecodeProgramPointerTable, plus StandaloneBytecodeProgram, StandaloneBytecodeProgram_2, DeathSequenceVramStream and LevelOamTemplateTable
Opcodes decoded	377 (372 in the 38 table programs, 4 in StandaloneBytecodeProgram, 1 in StandaloneBytecodeProgram_2)
Literal operands	937 in total, but only 829 of them are in real bytecode programs - the other 108 belong to the two blocks that turned out not to be bytecode at all
Opcodes defined / used	40 / 40 — the opcode set is complete, nothing unused

Two of the four blocks outside the pointer table contain no byte in $C8–$EF, so the interpreter could never have run them, and their listing says so explicitly rather than implying they are code. They are not bytecode: DeathSequenceVramStream ($881F, 24 bytes) is the compressed VRAM stream of the death sequence, and LevelOamTemplateTable ($AB14, 84 bytes) is the per-level OAM template table. Both were renamed once that was established - see Pass 3 data-table inventory below.

Confidence

Each mnemonic was read off its handler's own straight-line path, stopping at the handler's first jmp $9AE8 / jmp $9B25. Mnemonics that describe register-level behaviour (ACC_ADD_1_STEP, STEP_ACCUM, ROT_STEP_SUB, …) are read directly off the instructions. Those that merely tail-call a game routine are named for that routine (VM_CALL_82E1, PLAY_SEQ_BD20) rather than guessed at, because the semantic content lives in the callee, not the handler.

---

Pass 3c — tracing the stage payload

Static analysis cannot reach this region, and the trace confirms why. Across all 16 KB of code there is exactly one operand in $B0FB–$BEBF:

operands in $B0FB-$BEBF : 1
  -> $BD28    StageDataPointerLow, the literal pointer table itself

The real address is formed at runtime, $A062:

$A062  clc
$A063  adc $BD28,X      ; A (a value carried in the bytecode stream) + table byte
$A066  sta $12

so the readers are indexed by a runtime value and cannot be enumerated by searching the code.

Method

FCEUX's Lua API has no memory-read hook — only registerexec, registerexecute, registerrun and registerwrite — so it cannot observe these reads either, and with no static list of readers there is nothing to hook. _tools/trace_stage_payload.py therefore uses py65, whose ObservableMemory.subscribe_to_read fires on every read of a range and can report the CPU's PC from inside the hook.

py65 is only a 6502 core, so the tracer adds the minimum hardware to get the game running: a scanline counter driven off processorCycles, $2002 vblank asserted at scanline 241 and cleared on read, NMI fired at the same scanline (MUSCLE does its per-frame work in NmiHandler $86CB), $4014 OAM DMA, and the $2005/$2006/$2007 latches.

Without NMI the game never leaves $80E0: lda $0321 / beq $80E0, because $0321 is the flag the bytecode VM raises — so the stage data is only reachable once interrupts work.

Results (300 frames, 26.8M cycles, 4,071 NMIs)

Payload reads captured	2,548
Distinct reader PCs	44
Unique payload addresses touched	914 of 3,421 bytes in range

Reader PCs are 1-2 bytes above the real instruction, because py65 advances PC past the opcode before fetching the effective address.

What the access pattern shows

1. The payload is read through indirect pointers, confirming the static finding. The hottest reader resolves to $AC82:

$AC82  lda ($10),Y
$AC84  cmp #$C0
$AC86  bne $AC96
$AC88  lda $10 / clc / adc #$01 / sta $10    ; advance the stream pointer

This is the compressed-VRAM RLE decoder - it walks the payload sequentially (1,046 of its 1,128 reads advance by exactly +1), comparing each byte against $C0. That matches the $AC82 RLE decoder already named in the data section.

2. There is a second, backward-copy reader. $9B51 resolves to

$9B50  lda ($12),Y
$9B52  ldy $14
$9B54  sta ($10),Y
$9B56  dey

and its reads step by -1, sixty times - a reverse copy between two buffers.

3. The payload contains 8-byte-aligned record arrays. 107 distinct 8-byte blocks had all eight bytes read, and the spacing between consecutive blocks is dominated by $08:

$B1F0 $B1F8 $B200 $B208 $B210 $B218 ...   (stride $08)
$B3B8 $B3C0 $B3C8 $B3D0 ... $B5A0          (a long $08-strided run - the object lists)
$B600 $B608 $B610 ... $B638
$B8A0 $B8A8 $B8B0 ... $B910

with a second, sparser group on a $D0 stride:

$BBE0  $BCB0  $BD80  $BE50

so at least two record tables exist: a dense 8-byte-stride array and a $D0-stride array.

4. Readers use three access disciplines - sequential forward (+1), sequential backward (-1), and variable stride (+$15/+$14/+$11 at $ACB2, +2/+$4D at $AF5B/$B03D), the last consistent with a field-at-fixed-offset walk across records.

Still open

• Which reader corresponds to which semantic field is not yet pinned down; the trace gives the geometry (8-byte records, $08 and $D0 strides) but not the field names.
• Only 914 of 3,421 bytes were touched, because the run never entered every stage. A longer run that cycles through all stages would cover more and may reveal further strides.
• The compressed-VRAM payload and the object-list records are interleaved in one block; the boundary between them is not yet resolved.

FCEUX remains useful as an independent oracle for any of these conclusions - it is a complete, correct emulator where this tracer is a deliberately partial one.

---

Pass 3d — the payload is a shared pool, not stage data

Pass 3c assumed $B0FB–$BEBF was per-stage level data and that "cycle all stages" would cover it. A longer, properly-clocked run disproves that. Coverage plateaus near 40% no matter how many stages are entered, and forcing every actor index to run adds zero new bytes.

Two tracer bugs, both of which were suppressing everything

1. NMI re-armed by $2002 reads. The vblank flag must be cleared once per frame, not on every read of $2002. The main loop polls $2002 and spins on the bytecode VM flag at MainGameLoop_OnZero_8226 (lda $0321 / beq $8235); each poll clears bit 7, re-arming NMI inside the same scanline. Guarding only on not vblank produced 40,900 NMIs across 3,000 frames and silently corrupted all game state. A separate per-frame nmi_fired flag restores exactly one NMI per frame — verified: 600 frames → 600 NMIs.

2. Input went to the wrong port. The poll routine at $AA69 is

$AA69  ldx #$01 / stx $4016 / dex / stx $4016 / ldy #$08 / lda $4016,X / and #$03 / cmp #$01

so the observed reads are of $4017 (X=1) and only bits 0-1 are ever compared. Driving $4017 therefore consumes nothing: all three masks tested gave byte-identical traces. The game reads joy1 on $4016, and needs a real latch/shift register — a write with bit0 set latches, reads shift A,B,Select,Start,Up,Down,Left,Right out LSB-first. With that, START visibly matters: 47.7% coverage vs 39.0% for other masks.

Reaching a match takes two discrete START presses — title → character select → match. Rapid re-tapping does not work, and each press must be held ~3 frames.

What $BD28 actually indexes

$BD28 is not a stage table. The one operand in the window feeds:

$A04A  lda $0324 / beq $A062
$A04F  lda ActorIndex ($1E) / beq $A062
$A063  adc $BD28,X              ; X = ActorIndex
$A06A  lda PlayerActiveFlag,X ($78,X)
$A071  adc #$32                 ; +$32 when that actor is active

$BD28 = 6B 6B 6E 75 75 80 5A 78 is an 8-entry per-actor entry-offset table, and $B0FB + $BD28,n is where actor n's bytecode starts. Observed ActorIndex values over a 2,400-frame match are $00–$04, so the live actor set is 0–4.

The sound engine reads the same window

With input working, the reader list gained PCs inside $B0FB–$BEBF. These are not new code — they are the sound engine's own stream reader:

$B03C  lda (SoundReadPointerLo),Y
$B03E  cmp #$F0
$B040  bcc StoreShortNoteDuration
$B043  sbc #$F0 / tay / lda $B0E3,y     ; NoteDurationTable at $B0E3

SoundReadPointerLo ($EE/$EF) points into the payload while music plays, and the $F0 compare plus the $B0E3 duration lookup is note decoding. This is why the windows' bytes carry so many $FF terminators — $FF/$F0 are the high-nibble codes of the note stream.

So $B0FB–$BEBF is a shared data pool, mixing at least three things: per-actor bytecode scripts, the compressed-VRAM RLE stream ($AC82), and music note streams. It is not stage-specific, which is why stage cycling cannot raise coverage past ~40%.

Coverage summary

Run	Frames	NMIs	Payload reads	Readers	Coverage
Pass 3c (NMI broken)	300	4,071	2,548	44	26.3%
NMI fixed, no input	600	600	29,808	14	39.0%
Two START presses	2,000	2,000	79,192	21	40.9%
Actor sweep 0–7	2,400	2,400	98,392	14	38.7%

Largest unreached spans after the two-START run (2,161 B in 15 runs) are $BC00–$BEBF (704 B), $B980–$BB0F (400 B), $BB20–$BBEF (208 B), $B0FB–$B1A0 (166 B) and $B81E–$B89D (128 B).

What would actually close the gap

Not stage cycling. The remaining bytes need other music tracks playing and actors 2–4 in their non-default states. Both need a scripted match (moves, grapples, ring-outs), not a button-tap sequence — i.e. gameplay simulation, which is well beyond a coverage tracer.

$0326 is not a level byte: it never changes from $00 in any run, including a confirmed match. $0320 toggles $00/$FF and behaves as a boolean, not a screen-state machine.

---

Still Open

• Promote to the numbered inventory. Done — promoted to top-level MUSCLE (U)/ and added as #16 in the root inventory. copilot/Makefile tool paths moved from ../../../_tools/ to ../../_tools/ for NESDIS/PASS2/BYTECODE; make and make regen both verified after the move.
• The payload record structure is partially decoded ($B0FB–$BEBF, 3,525 bytes) — see "Pass 3d" above for what the emulator run established. It is a shared pool (per-actor bytecode + compressed VRAM + music note streams), not per-stage data; the per-record field names and the boundaries between the three uses are still unresolved.
• Two blocks are named but not fully interpreted. StageDescriptorData ($A618–$A65F) is reached through StageDescriptorPointerTable, and the six 12-byte records are known to be tile/attribute runs, but which field of which record the game reads is not pinned down. The same is true of LevelOamTemplateTable ($AB14–$AB67): the routine that copies it into the OAM shadow at $0300 is known, the eight-byte record layout is not.
• StandaloneBytecodeProgram ($85ED–$8638) and StandaloneBytecodeProgram_2 ($8A1E–$8A27) are still unreachable. Neither is in BytecodeProgramPointerTable and no instruction in the image points at either, so the VM never runs them; they are carried as bytecode because their bytes decode as tokens, but nothing in this dump says what starts them.
• The BytecodeProgramPointerTable index is masked to $3F (and #$3F at $9AD8), so an index of 38 or more would read past the 38-entry table. Nothing in the dump produces such an index, but the safety of the mask is untested.