Return of Samus Disassembly

A disassembly of one of my favorite Game Boy games. A first-pass over every function of code has been completed, but there are still plenty of improvements to be made to make the code more intelligible and usable. Feel free to contribute.

Build Instructions

1. Install rgbds
2. Install Python
3. Run extract.py to extract proprietary assets from a legally acquired copy of the original game.
4. Either run make all, build.bat, or build.py, depending on your preference.
5. The assembled game and a BGB compatible .sym file will appear in the out folder.

The resultant file should have this hash: md5: 9639948ad274fa15281f549e5f9c4d87

This project uses rgbds v0.9.1 and Python 3.13. Compatibility with other versions of these tools is not guaranteed.

If you wish to make a mod based on this repo, you may want to remove the lines at the bottom of the .gitignore file that blacklist proprietary assets from this repository, so that your custom assets will be tracked by your version control.

How to Contribute

1. Fork this repository (if you please).
2. Make something better. Perhaps start by doing something like:
   • Checking the issue tracker.
   • Giving a function or variable a (better) name.
   • Properly defining a RAM address (eg. labelName: ds 1).
   • Turning a magic number into a constant.
   • Turning a raw pointer (eg. $4242) into a proper label (eg. enemyAI_squeek).
   • Adding a missing label.
   • Adding informative comments.
   • etc.
3. Verify that your changes still result in a byte-for-byte identical game.
4. Submit a pull request.

Please refrain from moving any chunk of code into a separate file without first discussing it in the issue tracker.

If you have questions or comments, please drop by the #metroid-ii channel on the MetConst Discord.

Directory Structure

Subject to change.

• docs - Assorted notes regarding the game's formats and structure
• out - Output directory for the build process
• scripts - Various scripts to extra data from the game
• patches - Basic modifications to improve or change the game.
• SRC - Top level source code
• SRC/data - General data that hasn't been or can't be categorized elsewhere
• SRC/gfx - Generic tile data
• SRC/maps - Level data banks, along with the associated enemy data and door scripts
• SRC/ram - Definitions/declarations for VRAM, SRAM, WRAM, and HRAM.
• SRC/tilesets - Tile graphics, metatile definitions, and collision tables for each tileset

Resources

• mgbdis - The disassember used to create this project.
• PJ's Bank Logs - A rather extensive, but unbuildable, disassembly of the game.
• MetConst Wiki - Some of the information here is outdated.
• M2 Music Tools - A song extractor written by kkzero.
• LA DX Disassembly - A disassembly project of another game that also uses rgbds.

Editors

• M2Edit - Abandoned editor from 2004. Stable, but closed source and lacks enemy and door editing capabilities.
• ROSE - WIP editor. Web based.
• LAMP - Feature rich, Windows only, editor with support for this disassembly.
• 2DEd - Lightweight editor, designed to be used with this disassembly.