A Game Boy ROM disassembler.
- Generates assembly code compatible with RGBDS (v0.3.8+ recommended, see Notes)
- Supports ROMs with multiple banks
- Supports .sym files to define labels, code, data, text and image blocks
- Outputs a makefile to rebuild the ROM
- Uses defines from hardware.inc v2.7 for hardware registers (source)
- Slow on large ROMs
Disassemble a ROM:
Default output is to the
disassembly directory. You can verify the result of the disassembly by running
make and then checking the
game.gbc) file created:
cd disassembly && make
There are also a number of options available to control the formatting and instruction style of the generated assembly code. You can view these by running:
Symbol files allow you to indicate where code, data, test and image data blocks are in the ROM.
The instructions of the Game Boy CPU (SM83) have different lengths, and data can be interleaved with code in the ROM, so it is not possible to always accurately identify where an instruction starts and stops. Defining code blocks in a symbol file can help to avoid problems with mgbdis trying to disassemble in the middle of an instruction.
If you do not have a symbol file, you can try generating one with my Game Boy emulator - Beaten Dying Moon. It can generate a symbol file with code block definitions based on the the addresses of the instructions that have actually been executed while you have been playing the game, avoiding instruction alignment issues.
To use a symbol file with mgbdis, it should exist in the same directory as the ROM and have the same name, except change the extension to be
All values (except for image widths) should be in hexadecimal. Entries start with a bank number followed by the address in memory.
Block types can be defined by using the
.image magic labels, followed by the length of the block in bytes.
Adding a label for some code:
Adding a label for 512 bytes of data:
0d:4800 Level_Data 0d:4800 .data:200
Adding a label for 16 bytes of text:
00:3d00 Character_Name 00:3d00 .text:10
.image magic label allows you to define blocks of 1 or 2 bits per pixel tile data in the ROM. Images are output as PNG files in the
/gfx directory of the disassembly, and are converted back to 1bpp or 2bpp tile data by the makefile using rgbgfx. If a label is specified at the address of the image block then it will be used for the name of the PNG file.
The block length in bytes should be a multiple of 16, as each tile requires 16 bytes of image data.
The image width in pixels can be specified as a decimal number prefixed with
w. The width value should be a multiple of 8, and the combination of block length and image width must result in a rectangluar image without any empty tiles. The default image width is
128 pixels, or if the block length indicates an odd number of tiles, then an image with a single row of tiles will be generated.
The palette is a byte sized value which selects the shades of grey to use when generating the image. It uses the same format as the BGP register at
0xFF47. The value can be specified in hexidecimal prefixed with
p. The default palette is
The default is to treat it as 2 bits per pixel tile data. A
1bpp option can be supplied to treat the data as 1 bit per pixel tile data.
Adding a label for 1280 bytes of tile data, with a width of 128 pixels and palette 0xE4:
02:791a Title_Screen_Tile_Data 02:791a .image:500:w128,pe4
Example for 1bpp tile data:
05:4000 Font 05:4000 .image:200:w128,1bpp
- For constant expressions, RGBDS will by default optimise instructions like
LDH [$FF00+40],a, so these are encoded as data bytes using a macro to ensure exact reproduction of the original ROM (thanks to ISSOtm). RGBDS >= v0.3.7 has an option to disable this optimisation. Use
--disable-auto-ldhwith mgbdis to disable the macro.
- RGBDS automatically adds
HALT, so the disassembler will output these as data bytes if the instruction is not followed by a
NOPin the original ROM. Use
--disable-halt-nopswith mgbdis to instruct RGBDS to disable inserting automatic
- RGBDS v0.3.6 has an off by one error for some
JRinstructions, causing the assembled ROM to not match the original.
- RGBDS v0.3.7
rgbfixgenerates an invalid global checksum in the ROM header, causing the assembled ROM to not match the original.