SNES Disassembler

A powerful Super Nintendo (SNES) ROM disassembler with AI-enhanced analysis capabilities for 65816 assembly code.

Features

• 🎮 Complete SNES ROM Support - Handles .smc, .sfc, and .fig ROM formats
• 🔧 Multiple Output Formats - CA65, WLA-DX, BASS, HTML, JSON, XML, CSV, and Markdown
• 🚀 Enhanced Disassembly - AI-powered pattern recognition and MCP server insights
• 🎨 Asset Extraction - Graphics, audio, and text extraction from ROMs
• 📊 Advanced Analysis - Function detection, data structure recognition, and quality reports
• 🎵 BRR Audio Support - Decode SNES BRR audio files to WAV format
• 💻 Interactive CLI - User-friendly interactive interface with session management
• 🛠️ Non-Interactive Mode - Perfect for automation and CI/CD pipelines
• 🏦 Bank-Aware Addressing - Full 24-bit addressing support
• 📝 Comprehensive Documentation - Auto-generated docs for discovered functions

Installation

Quick Start (Global Installation)

# Clone the repository
git clone https://github.com/your-username/snes-disassembler.git
cd snes-disassembler

# Install dependencies and build
npm install
npm run build

# Install globally
npm run install-global

After installation, you can use snes-disasm from anywhere:

snes-disasm --help

Local Development Installation

# Install for local development
npm install
npm run build

# Run locally
npm run cli

Usage

Interactive Mode

Launch the interactive CLI for guided disassembly:

snes-disasm interactive
# or
snes-disasm --interactive
# or
snes-disasm i

Non-Interactive Mode

Perfect for automation and scripting:

# Basic disassembly
snes-disasm /path/to/rom.sfc --format ca65 --output-dir ./output

# Advanced analysis with enhanced features
snes-disasm rom.sfc \
  --format html \
  --analysis \
  --enhanced-disasm \
  --bank-aware \
  --detect-functions \
  --generate-docs \
  --output-dir ./analysis

# Extract assets
snes-disasm rom.sfc \
  --extract-assets \
  --asset-types graphics,audio,text \
  --output-dir ./assets

# BRR audio decoding
snes-disasm --decode-brr audio.brr --brr-output music.wav --brr-sample-rate 32000

Command Line Options

Usage: snes-disasm [options] [command] [rom-file]

Arguments:
  rom-file                               SNES ROM file to disassemble

Options:
  -V, --version                          output the version number
  -o, --output <file>                    Output file (default: <rom-name>.<ext>)
  -d, --output-dir <directory>           Output directory
  -f, --format <format>                  Output format: ca65, wla-dx, bass, html, json, xml, csv, markdown
  -s, --start <address>                  Start address (hex, e.g., 8000)
  -e, --end <address>                    End address (hex, e.g., FFFF)
  --symbols <file>                       Load symbol file (.sym, .mlb, .json, .csv)
  --analysis                             Enable full analysis
  --quality                              Generate code quality report
  -v, --verbose                          Verbose output
  --labels <file>                        Load custom labels file
  --comments <file>                      Load custom comments file
  --extract-assets                       Extract assets from ROM
  --asset-types <types>                  Asset types: graphics,audio,text
  --enhanced-disasm                      Use enhanced algorithms with MCP insights
  --bank-aware                           Enable 24-bit addressing
  --detect-functions                     Automatic function detection
  --generate-docs                        Generate documentation
  --decode-brr <file>                    Decode BRR audio to WAV
  -i, --interactive                      Run in interactive mode

Commands:
  interactive|i                          Run interactive CLI
  brr-to-spc <input-dir> <output-spc>    Convert BRR files to SPC format
  set-output-dir <directory>             Set global output directory
  clear-output-dir                       Clear global output directory
  show-output-dir                        Show current output directory
  preferences|prefs                      Configure user preferences
  show-preferences                       Display current preferences

Output Formats

| Format | Description | Use Case | |--------|-------------|----------| | ca65 | CA65 Assembly | Compatible with cc65 assembler | | wla-dx | WLA-DX Assembly | Compatible with WLA-DX assembler | | bass | BASS Assembly | Compatible with BASS assembler | | html | HTML Report | Interactive web documentation | | json | JSON Data | Machine-readable format | | xml | XML Data | Structured data format | | csv | CSV Data | Spreadsheet-compatible | | markdown | Markdown | Human-readable documentation |

Advanced Features

Enhanced Disassembly Engine

The enhanced disassembly engine provides:

• AI Pattern Recognition - Identifies game-specific patterns and structures
• MCP Server Integration - Leverages external analysis servers
• Control Flow Analysis - Tracks program flow and dependencies
• Function Detection - Automatically identifies and labels functions
• Data Structure Recognition - Detects tables, arrays, and data patterns

Asset Extraction

Extract various asset types from SNES ROMs:

• Graphics: Sprites, backgrounds, tiles (2bpp, 4bpp, 8bpp)
• Audio: Music, sound effects, BRR samples
• Text: Dialogue, strings, compressed text

BRR Audio Processing

SNES uses BRR (Bit Rate Reduction) for audio compression:

• Decode BRR files to standard WAV format
• Support for looping samples
• Configurable sample rates
• Batch processing capabilities

Examples

Basic ROM Disassembly

# Disassemble to CA65 format
snes-disasm chrono_trigger.sfc --format ca65 --output-dir ./ct_disasm

# Generate HTML report with analysis
snes-disasm super_metroid.sfc --format html --analysis --output-dir ./sm_analysis

Advanced Analysis

# Full analysis with all features
snes-disasm zelda_alttp.sfc \
  --enhanced-disasm \
  --bank-aware \
  --detect-functions \
  --generate-docs \
  --analysis \
  --quality \
  --format html \
  --output-dir ./zelda_full_analysis

Asset Extraction

# Extract all assets
snes-disasm final_fantasy_6.sfc \
  --extract-assets \
  --asset-types graphics,audio,text \
  --output-dir ./ff6_assets

# Extract only graphics
snes-disasm mario_world.sfc \
  --extract-assets \
  --asset-types graphics \
  --asset-formats 4bpp,8bpp \
  --output-dir ./mario_graphics

Session Management

# Set global output directory
snes-disasm set-output-dir ~/rom_analysis

# Configure preferences
snes-disasm preferences

# Show current settings
snes-disasm show-preferences

Development

Building from Source

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Type checking
npm run type-check

# Generate documentation
npm run docs:generate

Available Scripts

• npm run build - Build the project
• npm run build:watch - Build with file watching
• npm run dev - Run in development mode
• npm test - Run tests
• npm run test:watch - Run tests with watching
• npm run test:coverage - Generate test coverage
• npm run lint - Lint and fix code
• npm run format - Format code with Prettier
• npm run cli - Run the CLI locally
• npm run interactive - Run interactive mode locally
• npm run install-global - Build and install globally

Project Structure

src/
├── cli.ts                 # Main CLI interface
├── disassembler.ts        # Core disassembler engine
├── validation-engine.ts   # SNES reference validation
├── enhanced-disassembly-engine.ts  # AI-enhanced features
├── output-formats/        # Output format handlers
├── asset-handler.ts       # Asset extraction
├── brr-decoder.ts         # BRR audio processing
├── cli/                   # CLI utilities
│   ├── session-manager.ts
│   ├── preferences-manager.ts
│   └── help-system.ts
└── utils/                 # Shared utilities

Technical Details

Supported ROM Formats

• SMC: Super Magicom format with 512-byte header
• SFC: Super Famicom format (headerless)
• FIG: Super Fighter format

65816 CPU Support

• Full 65816 instruction set
• 8-bit and 16-bit modes
• Direct page addressing
• Bank switching
• Interrupt vectors

Memory Mapping

• LoROM and HiROM detection
• FastROM support
• SRAM mapping
• Special chip detection (DSP, SA-1, etc.)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• SNES development community for comprehensive documentation
• 65816 instruction set references
• BRR audio format specifications
• Contributors and testers

Support

• 📖 Documentation: Check the docs/ directory after running npm run docs:generate
• 🐛 Issues: Report bugs on GitHub Issues
• 💬 Discussions: Join GitHub Discussions for questions and ideas
• 📧 Contact: Reach out for collaboration opportunities

Happy Disassembling! 🎮✨