jonathanpeppers/dotnes/nes-decompile

NES ROM Decompiler

Decompile .nes ROM files into complete C# projects that can be rebuilt through dotnes.

Decompiler Tool

The decompiler lives at src/dotnes.decompiler/ and is a .NET CLI tool.

Running the Decompiler

dotnet run --project src/dotnes.decompiler -- <input.nes> [output-directory]

• `<input.nes>` — Path to the NES ROM file (required)
• `[output-directory]` — Where to write the C# project (optional; defaults to the ROM filename without extension)

Examples:

# Decompile a sample ROM (build it first if needed)
cd samples/hello && dotnet build && cd ../..
dotnet run --project src/dotnes.decompiler -- samples/hello/bin/Debug/net10.0/hello.nes hello-decompiled
 
# Decompile any .nes ROM
dotnet run --project src/dotnes.decompiler -- path/to/game.nes game-decompiled
 
# Decompile with default output directory (uses ROM filename)
dotnet run --project src/dotnes.decompiler -- myrom.nes

Output Files

The decompiler generates a complete, buildable C# project:

What Gets Recovered

The decompiler recognizes these NESLib API calls:

String literals in vram_write() are recovered from ROM data when the bytes are printable ASCII. VRAM addresses passed to vram_adr() are decompiled back to NTADR_A(x, y) macro form when they match the nametable pattern 0x2000 + y*32 + x.

What Is NOT Recovered

• Original variable names, control flow structures, or algorithm intent
• User-defined functions (inlined into main)
• Local variables and complex expressions
• Non-NESLib subroutine calls (appear as comments)
• Classes, objects, or BCL usage (NES doesn't support these)

Common Workflows

Decompile a dotnes sample ROM

Build the sample, then decompile its ROM output:

# Build the sample
cd samples/hello && dotnet build && cd ../..
 
# Decompile the ROM
dotnet run --project src/dotnes.decompiler -- samples/hello/bin/Debug/net10.0/hello.nes hello-decompiled
 
# Inspect the output
cat hello-decompiled/Program.cs

Round-trip test (transpile → decompile → retranspile)

Verify the decompiler produces code that builds back to an equivalent ROM:

# 1. Build original sample
cd samples/hello && dotnet build && cd ../..
 
# 2. Decompile the ROM
dotnet run --project src/dotnes.decompiler -- samples/hello/bin/Debug/net10.0/hello.nes hello-roundtrip
 
# 3. Build the decompiled project
cd hello-roundtrip && dotnet build && cd ..
 
# 4. Compare the two ROMs
python scripts/compare_rom.py samples/hello/bin/Debug/net10.0/hello.nes hello-roundtrip/bin/Debug/net10.0/hello.nes

If the round-trip produces an identical ROM, the decompiler recovered all observable behavior.

Decompile an external .nes ROM

Any iNES-format ROM can be parsed, but the decompiler only recognizes dotnes/neslib patterns:

dotnet run --project src/dotnes.decompiler -- external-game.nes game-output
cat game-output/Program.cs

For ROMs not built with dotnes, the output will contain fewer recognized API calls and more comments for unrecognized subroutines.

Inspect ROM metadata without full decompilation

Use the decompiler's console output to quickly check ROM properties:

dotnet run --project src/dotnes.decompiler -- myrom.nes 2>&1 | Select-Object -First 6

This shows PRG/CHR bank counts, mapper number, mirroring mode, and interrupt vectors.

How the Decompiler Works

The decompiler uses a three-phase algorithm:

Phase 1: Build Symbol Table

• Assembles the known neslib built-in subroutines to determine their addresses
• Finds main() by scanning the initlib block for the first JSR to an address past the built-ins
• Pattern-matches final built-ins (pusha, pushax, popa, vram_write, etc.) using byte signatures

Phase 2: Decompile Main

• Collects all 6502 instructions from main until the infinite loop (JMP to self)
• Uses look-ahead pattern matching to recognize multi-instruction sequences:
• LDA #imm / JSR pusha → 8-bit argument push
• LDA #lo / LDX #hi / JSR pushax → 16-bit pointer push
• LDX #hi / LDA #lo / JSR <sub> → call with 16-bit register argument
• LDA #imm / JSR <sub> → call with immediate argument

Phase 3: Generate C#

• Converts the recognized patterns into NESLib API calls with recovered arguments
• Reconstructs string literals and NTADR_A macro addresses
• Wraps everything in the standard dotnes program structure

MSBuild Properties in Generated .csproj

The decompiler reads ROM metadata and sets appropriate MSBuild properties:

Related Skills

• nes-rom-debug — Low-level 6502 disassembly and byte-level ROM inspection
• nes-emu-debug — Run ROMs in MesenCE emulator to verify runtime behavior