Open-Awesome
CategoriesAlternativesStacksSelf-HostedExplore
Open-Awesome

© 2026 Open-Awesome. Curated for the developer elite.

TermsPrivacyAboutGitHubRSS
  1. Home
  2. Game Boy Development
  3. mgbdis

mgbdis

MITAssemblyv3.0

A Game Boy ROM disassembler that generates RGBDS-compatible assembly code with support for symbol files and image extraction.

GitHubGitHub
330 stars47 forks0 contributors

What is mgbdis?

mgbdis is a Game Boy ROM disassembler that converts binary game ROMs into human-readable assembly code compatible with the RGBDS assembler. It solves the problem of accurately disassembling Game Boy games, where code and data are interleaved, by supporting symbol files to define code blocks and data regions.

Target Audience

Retro gaming enthusiasts, homebrew developers, and researchers analyzing or modifying classic Game Boy and Game Boy Color games.

Value Proposition

Developers choose mgbdis for its tight integration with the RGBDS ecosystem, support for symbol files to improve disassembly accuracy, and built-in image extraction capabilities for game graphics.

Overview

Game Boy ROM disassembler with RGBDS compatible output

Use Cases

Best For

  • Disassembling Game Boy ROMs for analysis or study
  • Creating mods or hacks for classic Game Boy games
  • Extracting graphics and tile data from ROMs
  • Learning Game Boy assembly and hardware programming
  • Preserving and documenting vintage game code
  • Preparing ROMs for reassembly with the RGBDS toolchain

Not Ideal For

  • Projects disassembling ROMs from non-Game Boy systems like NES or SNES
  • Users needing fast, real-time disassembly for very large ROMs due to performance limitations
  • Developers preferring a graphical interface for interactive analysis and debugging
  • Teams seeking an all-in-one tool with built-in symbol generation, as mgbdis relies on external emulators for accurate .sym files

Pros & Cons

Pros

RGBDS Ecosystem Integration

Outputs assembly code specifically designed for reassembly with RGBDS v0.8.0 or later, ensuring seamless compatibility with the standard Game Boy development toolchain, as stated in the README.

Symbol-Driven Accuracy

Leverages .sym files to define code, data, text, and image blocks, which helps overcome the SM83 CPU's variable-length instruction challenges and improves disassembly accuracy for modding and preservation.

Graphics Extraction and Rebuild

Converts tile data to PNG images and includes makefile rules to rebuild them using rgbgfx, simplifying the process of analyzing and modifying game graphics, as demonstrated in the image examples.

Automated Makefile Generation

Creates a makefile to rebuild the original ROM from the disassembly, automating verification and reducing manual steps for developers, as mentioned in the usage instructions.

Cons

Performance Bottlenecks

The README explicitly admits mgbdis is 'slow on large ROMs,' which can hinder efficiency in extensive game analysis or batch processing scenarios.

Heavy Symbol File Dependence

Accurate disassembly relies heavily on external .sym files; without them, instruction alignment issues are common, and generating symbols requires using separate tools like the Beaten Dying Moon emulator, adding complexity.

Platform-Limited Scope

Only supports Game Boy and Game Boy Color ROMs, making it unsuitable for other retro systems or modern platforms, which limits its utility in broader reverse engineering projects.

Frequently Asked Questions

Quick Stats

Stars330
Forks47
Contributors0
Open Issues7
Last commit3 months ago
CreatedSince 2018

Tags

#python-tool#assembly#game-boy#disassembler#emulation#rgbds#game-modding#gameboy#retro-gaming#reverse-engineering

Built With

P
Python

Included in

Game Boy Development4.4k
Auto-fetched 12 hours ago

Related Projects

awakeawake

Gameboy decompiler

Stars75
Forks20
Last commit12 years ago
romusageromusage

A small command line tool for estimating usage of Game Boy (and other supported GBDK platforms) ROMs from map files, .noi files, binary ROMs and more

Stars58
Forks9
Last commit1 year ago
evunitevunit

A CPU emulator for running unit tests on Game Boy code.

Stars21
Forks7
Last commit1 year ago
evscriptevscript

An extensible bytecode-based scripting engine for the Game Boy

Stars16
Forks4
Last commit2 years ago
Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a projectStar on GitHub