retrodisasm

retrodisasm is a tracing disassembler for NES and CHIP-8 ROMs. It traces execution flow to distinguish code from data, producing assembly that reassembles to a bit-identical binary.

Binary Resolution

This skill ships prebuilt binaries in tools/:

Always prefer the bundled binary. Resolve the platform automatically (uname -s → MINGW*/MSYS* = win, Darwin = macos, Linux = linux) and use the corresponding path. The command examples below use retrodisasm as a placeholder — substitute with the actual binary path.

If the bundled binary is missing or unsuitable for the current platform:

# Option A: download latest prebuilt release from GitHub
#   https://github.com/retroenv/retrodisasm/releases
#   -> extract into {skill_dir}/tools/<platform>/

# Option B: install via Go
go install github.com/retroenv/retrodisasm@latest

Quick Start

# Basic disassembly (auto-detects NES from .nes extension)
retrodisasm -o output.asm game.nes

# Explicit system and assembler
retrodisasm -s nes -a ca65 -o output.asm game.nes

# Output to stdout
retrodisasm -o - game.nes

# Verify output reassembles to identical binary
retrodisasm -o output.asm game.nes -verify

If -o is omitted, output defaults to <input>.asm.

Supported Systems and Assemblers

Auto-detection by extension: .nes → NES, .ch8 / .rom → CHIP-8.

Assembler Selection

Choose the assembler with -a:

Important: asm6 output requires asm6f v1.6 (modifications v03) or later. retroasm does not support -verify.

NES-Specific Options

Code/Data Log Files

Use a .cdl file from FCEUX or Mesen to guide disassembly with known code/data boundaries:

retrodisasm -o output.asm game.nes -cdl game.cdl

ca65 Linker Config

Specify a custom linker configuration for ca65 output:

retrodisasm -o output.asm game.nes -c custom.cfg

Undocumented 6502 Opcodes

# Emit mnemonics instead of .byte directives (incompatible with -verify)
retrodisasm -o output.asm game.nes -output-unofficial

# Stop tracing at unofficial opcodes unless explicitly branched to
retrodisasm -o output.asm game.nes -stop-at-unofficial

Binary Mode

Disassemble raw binary data without an NES/CHIP-8 header:

# PRG-ROM at standard NES CPU address
retrodisasm -binary -base 8000 -o prg.asm prg.bin

# Custom base address
retrodisasm -binary -base 0200 -o ram.asm ramdump.bin

Use -binary any time the input lacks a recognized file header.

Batch Processing

Process multiple ROMs with a glob pattern:

retrodisasm -batch "roms/*.nes"

Each ROM produces <romname>.asm in the same directory.

Output Formatting

Default output format shows address, hex bytes, and instruction:

Reset:
  sei                            ; $8000 78
  cld                            ; $8001 D8
  lda #$10                       ; $8002 A9 10
  sta PPU_CTRL                   ; $8004 8D 00 20

Verification

-verify reassembles the output with the chosen assembler and compares it to the original input. The assembler must be installed and on PATH.

retrodisasm -o output.asm game.nes -verify

Not compatible with -output-unofficial or -a retroasm.

Logging

File Reference

Limitations

• Mapper support is experimental and may not handle all banking scenarios
• Complex self-modifying code may not disassemble perfectly
• retroasm does not support verification
• -output-unofficial is incompatible with -verify