nes-rom-debug

name

nes-rom-debug

description

Disassemble and debug NES ROM files (.nes) produced by the dotnes transpiler. Use this skill whenever the user wants to disassemble a .nes ROM, inspect 6502 machine code, compare two NES ROMs side-by-side, debug transpiler output, investigate byte differences between a cc65 reference ROM and a dotnes ROM, or understand what 6502 instructions the transpiler emitted. Also use when the user mentions disasm, disassembly, PRG ROM, ROM bytes, NES addresses, or wants to look at the hex/binary output of a build. Even if the user just says something like "the ROM looks wrong" or "what did the transpiler emit", this skill applies.

NES ROM Debug

Tools and knowledge for disassembling NES ROMs and debugging dotnes transpiler output.

Available Scripts

disasm.py — 6502 Disassembler

Disassembles the PRG ROM section of an iNES (.nes) file into human-readable 6502 assembly.

python scripts/disasm.py <file.nes> [start_hex] [end_hex]

• file.nes — Path to the NES ROM file
• start_hex — (Optional) Start NES address in hex, default 8000
• end_hex — (Optional) End NES address in hex, default end of PRG

Examples:

Note: .nes files are build outputs — run dotnet build in the sample directory first.

# Disassemble the entire PRG ROM
python scripts/disasm.py samples/hello/hello.nes

# Disassemble only the main() region
python scripts/disasm.py samples/hello/hello.nes 8500 8600

# Disassemble the interrupt vectors area
python scripts/disasm.py samples/hello/hello.nes FF00 FFFF

Output format:

$8500: A9 02     LDA #$02
$8502: 20 61 85  JSR $8561
$8505: 85 17     STA $17
$8507: D0 F7     BNE $8500

Each line shows: $ADDR: HEX_BYTES MNEMONIC OPERAND

compare_rom.py — Side-by-Side ROM Comparison

Compares two NES ROMs with byte-level and instruction-level analysis. Use this to verify dotnes output against a cc65 reference ROM.

python scripts/compare_rom.py <reference.nes> <dotnes.nes>

Output includes:

1. File sizes
2. Total byte differences (header / PRG / CHR breakdown)
3. Contiguous diff groups with NES addresses
4. Side-by-side disassembly of the largest diff region with match/mismatch markers
5. Instruction mismatch count (ignoring absolute addresses, since the two compilers may place subroutines at different offsets)

ildump.cs — IL Opcode Dumper

Dumps the .NET IL opcodes from a compiled DLL — useful for understanding what IL the transpiler will process.

dotnet run scripts/ildump.cs -- <path-to-dll>

NES ROM Format (iNES)

Understanding the binary layout helps interpret disassembly output:

Offset    Size     Content
0x00      16       iNES header (starts with "NES\x1A")
0x10      32768    PRG ROM (mapped to NES $8000-$FFFF)
0x8010    8192     CHR ROM (pattern tables for tiles/sprites)

Key NES addresses:

• $8000-$85AD — neslib runtime and built-in subroutines (palette, PPU, NMI handler, stack ops)
• $85AE+ — main() and user code (exact layout varies per sample)
• $FFFA — NMI vector (2 bytes, little-endian)
• $FFFC — RESET vector (2 bytes, little-endian — entry point)
• $FFFE — IRQ vector (2 bytes, little-endian)

File offset → NES address: nes_addr = 0x8000 + (file_offset - 16) NES address → file offset: file_offset = (nes_addr - 0x8000) + 16

Common Debugging Workflows

"The ROM doesn't match the reference"

1. Run compare_rom.py to identify where bytes differ
2. Use disasm.py on both ROMs targeting the diff region to see the instructions
3. Check if differences are just address relocations (compare_rom normalizes these) or actual logic differences

python scripts/compare_rom.py reference.nes output.nes
# If diff at $8600-$8620:
python scripts/disasm.py reference.nes 85F0 8630
python scripts/disasm.py output.nes 85F0 8630

"What did the transpiler emit for my code?"

1. Build the sample: cd samples/hello && dotnet build
2. Dump the IL to see what C# compiled to: dotnet run scripts/ildump.cs -- samples/hello/bin/Debug/net10.0/hello.dll
3. Disassemble the ROM to see the 6502 output: python scripts/disasm.py samples/hello/bin/Debug/net10.0/hello.nes 8500

"Where is main() in the ROM?"

The RESET vector at $FFFC points to the startup code, which eventually jumps to main. To find it:

# Look at the last few bytes for the vectors
python scripts/disasm.py myrom.nes FFF0 FFFF

# The RESET vector value tells you where startup is
# Then disassemble from there to find the JMP to main

"Comparing test output against verified snapshot"

When TranspilerTests.Write fails, the test produces a .received.bin alongside the .verified.bin. Compare them:

# The test DLLs are in src/dotnes.tests/Data/
# Build the test project to get the .received.bin
python scripts/compare_rom.py path/to/verified.bin path/to/received.bin

6502 Quick Reference

The most common instructions you'll see in dotnes output:

Opcode	Mnemonic	Meaning
A9	LDA #imm	Load accumulator with immediate value
A5	LDA zpg	Load accumulator from zero page
AD	LDA abs	Load accumulator from absolute address
85	STA zpg	Store accumulator to zero page
8D	STA abs	Store accumulator to absolute address
20	JSR abs	Jump to subroutine
60	RTS	Return from subroutine
4C	JMP abs	Jump to address
D0	BNE rel	Branch if not equal (Z=0)
F0	BEQ rel	Branch if equal (Z=1)
C9	CMP #imm	Compare accumulator with immediate
E6	INC zpg	Increment zero page location
C6	DEC zpg	Decrement zero page location

Zero page addresses used by dotnes:

• $17 — TEMP
• $22-$23 — sp (cc65 software stack pointer)
• $0325+ — Local variables