AwesomeREA.org

Tool

mgbdis

Python disassembler that turns a Game Boy or Game Boy Color ROM, including multi-bank ROMs, into RGBDS-compatible assembly plus a Makefile that reassembles it, so the rebuilt ROM can be compared with the input. An optional .sym file beside the ROM supplies labels and marks code, data, text, padding and 1bpp/2bpp tile-image blocks; images are written as PNG files that rgbgfx converts back, text can use custom character maps, and hardware registers get hardware.inc names. The README explains that SM83 instructions vary in length and data is interleaved with code, so marked code blocks keep it from disassembling mid-instruction.

Targets
Binary · Game
Category
Game analysis tools
Relationship
Foundation tool
Sources reviewed

Requirements & limits

  • Latest release at review: v3.0, published 2025-04-22; the reviewed master commit of 2026-07-31 is 15 commits ahead of that tag and still reports version 3.0. It is a single Python script that needs Python 3.6+, and the generated assembly targets RGBDS v0.8.0 or later, whose rgbasm, rgblink, rgbfix and rgbgfx the generated Makefile calls. Options control hexadecimal case, indentation, operand alignment and mnemonic variants, and a --tiny mode handles unbanked 32 KiB ROMs.
  • The input is a ROM file the user supplies, optionally with a same-named .sym file; the repository ships no game ROMs. It bundles PyPNG's png.py and a copy of gbdev's hardware.inc, and its only test ROM is assembled during testing from the project's own assembly sources. The README suggests generating code-block symbol files with the author's separate Beaten Dying Moon emulator, which records the instructions actually executed; that emulator was not reviewed.
  • GitHub Actions installs the latest RGBDS release, builds the test ROM, disassembles it, diffs the output against committed expected files, then reassembles the disassembly and compares it byte for byte with the test ROM. This checks the tool on its own fixture, not on commercial games. The README notes that RGBDS inserts a NOP after STOP, so a STOP not followed by NOP is emitted as a data byte, and calls the tool slow on large ROMs.
  • MIT license; png.py carries its own MIT notice. mgbdis produces assembly rather than C, and labels and block boundaries come from the analyst's symbol file. No ROMs were disassembled for this record.

About this entry

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Report an outdated entry Suggest a translation fix

Primary sources

  1. README.md GitHub · mattcurrie/mgbdis · Revision 95d951a
  2. README.md#L35-L45 GitHub · mattcurrie/mgbdis · Revision 95d951a
  3. mgbdis.py#L1314-L1331 GitHub · mattcurrie/mgbdis · Revision 95d951a
  4. mgbdis.py#L1235-L1261 GitHub · mattcurrie/mgbdis · Revision 95d951a
  5. test/Makefile GitHub · mattcurrie/mgbdis · Revision 95d951a
  6. .github/workflows/test.yml GitHub · mattcurrie/mgbdis · Revision 95d951a
  7. test GitHub · mattcurrie/mgbdis · Revision 95d951a
  8. LICENSE GitHub · mattcurrie/mgbdis · Revision 95d951a
  9. https://github.com/mattcurrie/mgbdis/releases/tag/v3.0

More in Games

All 252 entries in Games