disasm/MUSCLE (U)/OVERVIEW.md

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.

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

ROM Facts

Property	Value
Mapper	0 (NROM)
PRG	16 KB, mapped low at $8000–$BFFF (mirrored to $C000–$FFFF)
CHR	8 KB
Mirroring	Horizontal (header byte 6 = $01)
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_36 $8D3B–$9236	1,034	the 37 distinct programs, each labelled with the table indices that reach 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. The two duplicate entries account for 37 distinct programs.

$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 … _3	194	four token programs not in BytecodeProgramPointerTable

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 (37 in BytecodeProgramPointerTable + 4 standalone, one shared)
Opcodes decoded	377
Literal operands	937
Opcodes defined / used	40 / 40 — the opcode set is complete, nothing unused

Two of the four standalone programs (_1, 24 bytes; _3, 84 bytes) contain no byte in $C8–$EF, so the interpreter takes the literal path for every byte and the whole block is operand data rather than an instruction stream. The listing says so explicitly rather than implying they are code.

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.