retrodisasm

name	retrodisasm
description	Disassemble retro ROMs (NES, CHIP-8) into bit-perfect reassemblable assembly with retrodisasm. Use when the user wants to disassemble a ROM, reverse-engineer NES code, inspect ROM internals, batch-process ROMs, verify reassembly, or convert binaries to assembly source.

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/:

Platform	Path
Windows	{skill_dir}/tools/win/retrodisasm.exe
macOS	{skill_dir}/tools/macos/retrodisasm
Linux	{skill_dir}/tools/linux/retrodisasm

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

System	Flag	Assemblers
NES	-s nes	ca65 (default), asm6, nesasm, retroasm
CHIP-8	-s chip8	retroasm

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

Assembler Selection

Choose the assembler with -a:

Assembler	Flag	Reassembly command
ca65	-a ca65 (default)	ca65 out.asm -o out.o && ld65 out.o -t nes -o out.nes
asm6	-a asm6	asm6f out.asm out.nes
nesasm	-a nesasm	nesasm out.asm -o out.nes
retroasm	-a retroasm	retroasm out.asm -o out.nes

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

Flag	Effect
-nohexcomments	Omit hex opcode bytes from comments
-nooffsets	Omit file offsets from comments
-z	Include trailing zero bytes in banks (default: omit)

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

Flag	Effect
-debug	Enable debug logging for troubleshooting
-q	Quiet mode, suppress non-error output

File Reference

File	What it covers
Output .asm	Reassemblable assembly source
Input .cdl	Code/data log from FCEUX/Mesen
Input .cfg	ca65 linker configuration

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