A Super Nintendo (SNES) ROM disassembler for 65816 assembly
npm install snes-disassemblerA powerful Super Nintendo (SNES) ROM disassembler with AI-enhanced analysis capabilities for 65816 assembly code.
- š® 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
``bashClone the repository
git clone https://github.com/your-username/snes-disassembler.git
cd snes-disassembler
After installation, you can use
from anywhere:`bash
snes-disasm --help
`$3
bash
Install for local development
npm install
npm run buildRun locally
npm run cli
`Usage
$3
Launch the interactive CLI for guided disassembly:
bash
snes-disasm interactive
or
snes-disasm --interactive
or
snes-disasm i
`$3
Perfect for automation and scripting:
bash
Basic disassembly
snes-disasm /path/to/rom.sfc --format ca65 --output-dir ./outputAdvanced analysis with enhanced features
snes-disasm rom.sfc \
--format html \
--analysis \
--enhanced-disasm \
--bank-aware \
--detect-functions \
--generate-docs \
--output-dir ./analysisExtract assets
snes-disasm rom.sfc \
--extract-assets \
--asset-types graphics,audio,text \
--output-dir ./assetsBRR audio decoding
snes-disasm --decode-brr audio.brr --brr-output music.wav --brr-sample-rate 32000
`$3
Usage: snes-disasm [options] [command] [rom-file]Arguments:
rom-file SNES ROM file to disassemble
Options:
-V, --version output the version number
-o, --output Output file (default: .)
-d, --output-dir Output directory
-f, --format Output format: ca65, wla-dx, bass, html, json, xml, csv, markdown
-s, --start Start address (hex, e.g., 8000)
-e, --end End address (hex, e.g., FFFF)
--symbols Load symbol file (.sym, .mlb, .json, .csv)
--analysis Enable full analysis
--quality Generate code quality report
-v, --verbose Verbose output
--labels Load custom labels file
--comments Load custom comments file
--extract-assets Extract assets from ROM
--asset-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 Decode BRR audio to WAV
-i, --interactive Run in interactive mode
Commands:
interactive|i Run interactive CLI
brr-to-spc Convert BRR files to SPC format
set-output-dir 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 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
$3
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
$3
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
$3
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
$3
`bash
Disassemble to CA65 format
snes-disasm chrono_trigger.sfc --format ca65 --output-dir ./ct_disasmGenerate HTML report with analysis
snes-disasm super_metroid.sfc --format html --analysis --output-dir ./sm_analysis
`$3
bash
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
`$3
bash
Extract all assets
snes-disasm final_fantasy_6.sfc \
--extract-assets \
--asset-types graphics,audio,text \
--output-dir ./ff6_assetsExtract only graphics
snes-disasm mario_world.sfc \
--extract-assets \
--asset-types graphics \
--asset-formats 4bpp,8bpp \
--output-dir ./mario_graphics
`$3
bash
Set global output directory
snes-disasm set-output-dir ~/rom_analysisConfigure preferences
snes-disasm preferencesShow current settings
snes-disasm show-preferences
`Development
$3
bash
Install dependencies
npm installBuild the project
npm run buildRun tests
npm testLint code
npm run lintType checking
npm run type-checkGenerate documentation
npm run docs:generate
`$3
-
- 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$3
`
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
$3
- SMC: Super Magicom format with 512-byte header
- SFC: Super Famicom format (headerless)
- FIG: Super Fighter format$3
- Full 65816 instruction set
- 8-bit and 16-bit modes
- Direct page addressing
- Bank switching
- Interrupt vectors$3
- 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 (
)
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 RequestLicense
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`---
Happy Disassembling! š®āØ