This guide expects the reader to be using Microsoft Windows operating system to hack. If you are using Mac or a Linux distro, congrats! It is doable now! Though you may need to perform some workarounds.

This guide is written for use with MAGE 1.4.0. At the time of writing MAGE only supports USA ROMs.

Create a rom hacking folder of some kind. The name and the way it gets organized doesn't matter much.

This ensures you do not misplace any important files, and they all stay in one place.

You must either dump your ROM or search online. Check the first footnote to see how to dump your ROMs. ¹⁾

Make sure you can see file extensions!
On Windows 10, launch File Explorer, click on the View tab, then tick ☑ File Name Extensions. On Windows 11, open File Explorer, and then click View > Show > File Name Extensions.

The ROM should be Metroid - Zero Mission (U) [!].gba. The (U) is short for USA, and [!] means verified good dump. .gba means it's a gameboy advance ROM.

The ROM's sha1 hash should be 5DE8536AFE1F0078EE6FE1089F890E8C7AA0A6E8. To verify your ROM, use Quickhash GUI. Go to the File tab. Drag-and-drop your ROM over the application. Copy the sha1 hash from this wiki page to your clipboard, and paste it into the text box below Expected Hash Value. A message will appear on the screen telling you if it matches. If it does NOT MATCH, you either need to dump the cart again, or you have the wrong ROM.

Once you have the correct ROM, you should put it someplace safe, and only edit copies of it. NEVER edit the original. If you follow this practice, you will not have to re-dump or re-download your ROM when you accidentally corrupt or otherwise destroy a copy of it. I personally stick it into a Vanilla ROMs folder, and NEVER open it with ANY editors. When I need a clean slate, I go into that folder, copy the rom, and then paste it into my romhacking folder.

Download mGBA. It loads fast, is cross-platform, and accurate enough. For the easiest experience, download and run the installer.

Once installed, set mGBA as the default program to open GBA files.

This can be done by right-clicking a GBA rom and selecting Open with…. If mGBA does not appear on the list, Scroll down and select More Apps ⬇. If mGBA is still not there, scroll down and select Look for another app on this PC.

If you used the 64-bit installer, Browse to C:\Program Files\mGBA and select mgba.exe.
If you used the 32-bit installer, Browse to C:\Program Files (x86)\mGBA and select mgba.exe.

If successful, the thumbnail of gba ROMs should now look like mGBA. mGBA should be able to open and play your ROM.

MAGE can be downloaded here.

MAGE Requires .NET 3.0 to be able to function. If your system does not have it installed, Windows 10 will prompt you to install the .NET Framework 3.5 (Includes 2.0 and 3.0) feature. Once it is completed, the window will disappear, and you should be able to open MAGE.

Use File → Open ROM… to find and select your Metroid Zero Mission ROM. Alternatively, drag and drop your ROM over MAGE once it is open.
If all is well, you should be loaded into the very first room in Brinstar.

Move your mouse pointer somewhere in the room and then press the T key. The very first time you do this, a message will appear:

------------------------------------------------------------------
GBA emulator path has not been set. Would you like to set it now?
------------------------------------------------------------------
            +=========+              +========+
            |   Yes   |              |   No   |   
            +=========+              +========+

Select Yes, then look for mGBA.

If you installed 64-bit mGBA, it will be located at C:\Program Files\mGBA\mGBA.exe.
If you installed 32-bit mGBA, it will be located at C:\Program Files (x86)\mGBA\mGBA.exe.

If successful, mGBA will launch your test ROM. You can close mGBA.

All you have to do is click File → Create Backup. The filename of the backup is a timestamp, in the format YYYY-MM-DD_HH-MM-SS.gba
Alternatively, you can right-click your ROM and select 'copy'. After that, right-click a second time and select 'paste'. The filename of the backup is in the format filename (copy #).gba

It cannot be stressed enough how important it is to create regular back-ups of the ROM that you're working on. Make regular and frequent ROM back-ups a habit. Back-ups are your friend, and they will spare you so much pain. There is no reason to not make back-ups.

In addition to on your computer, keep back-ups of your hack stored on USB thumb drives, extra hard drives, web servers, email them to yourself, burn them to CDs or DVDs if you need to. You do not want to lose a thousand collective hours of work on a hack because your computer broke and you didn't have a copy of your hacked ROM anywhere else except on your dead computer's hard drive.

IF YOU ARE EVER ABOUT TO APPLY A PATCH OR MAKE AN EDIT THAT YOU ARE EVEN SLIGHTLY UNSURE OF, CREATE A BACK-UP FIRST. Preventing catastrophe is just that easy. If hard drive space is an issue, you can create back-up IPS patches of your hack instead (see IPS patch creation).

Stay calm and don't let it get you down! It is pretty much impossible to avoid experiencing all of these things and more as you journey through creating your own Metroid Zero Mission hack. Constant experimentation especially - you will need to test everything constantly as you're working on it, or you might waste huge amounts of time stepping backwards through your edits to figure out the problem. TEST EVERYTHING, ALWAYS.

Sometimes, you may make a mistake. That's OK, happens to the best of us! You can quickly reload your rom by selecting it in File → Recent Files

Until you understand the limits of the game you're hacking, your ideas might seem impossible or at least very hard to code. Most people won't want to go through the trouble of coding it for you unless they believe your project has real potential. Learning these limits takes time, but if your ideas are simple or you're willing to use a simplified version of your original idea, it becomes much more feasible. It's helpful to initially assume your ideas might not be possible (while still checking with experienced hackers). As more of your ideas get refined or ruled out, you'll start to see what's realistically achievable. You should try using what's already in the game to do the thing you want. It may not be perfect, but will hopefully get the job done.

You should consider all of this now and spare yourself a LOT of possible wasted time later. Is this hobby really for you? Real talk: overwhelmingly, most of the people who try to hack Metroid have either given up, or they released something they didn't really want to release, and then they gave up. You are probably going to give up. Hacking Metroid is not extremely difficult, but it is also not something that you can do fast. You will probably be at this for years if your goal is to make something lastingly notable and polished. Be ready for the possibility of restarting projects repeatedly, being unable to solve problems for weeks or months until you've learned more, and giving up on dream ideas that are impossible to do.

Personal satisfaction is also probably the most important thing there is about this hobby. If you don't like Metroid enough to consider working on it as an unpaid, illegal side-career, then you will probably lose the motivation to keep working on your project after awhile. Knowing your audience is also a big deal, because it allows you to scale your expectations.

Do you want to make a hack that tons of people will play and enjoy for years? If so, MAKE YOUR HACK EASY, MAKE YOUR HACK PRETTY, MAKE YOUR HACK WELL. That's all there is to it. You are creating a game, not a hack. The difficulty is in the simplicity of actually sticking to those three simple rules above all else, and not becoming tempted by other ideas later that compromise your initial vision. If your hack is extremely easy for you to play through, then that means it should be about average difficulty for somebody who only played and enjoyed Metroid a long time ago, but recently discovered that ROM hacks of it exist.

Do you want to make a hack that challenges veteran Metroid players? If so, get rid of any expectations you have about how people will feel about your hack. Almost everyone will simply not like it because it's too difficult, and there is nothing you can do to make them enjoy it or appreciate the amount of time and work you put into it - at the end of the day, you still created something that they do not feel is worth taking their time to play through. This happens because proportionally rewarding the player for accomplishing difficult tasks becomes much harder to do unless you know assembly programming, which means that you just have to hope that the player's personal sense of achievement is enough to keep them interested in your hard game. Almost always, it will not be.

It will probably always be a bad decision to try making a fun hard hack as your first project. Hard hacks are only interesting to veteran players of the game, which is a very small number of people. If that is your intended audience, go for it, but don't expect your hard hack to gain much attention. Difficulty is more often just… difficult, and not that fun.

If you discover a crash or some kind of bug with MAGE itself, click “Help → About Mage → https://forum.metroidconstruction.com/index.php/topic,3969.0.html” and write out a clear description of the error that you experienced. Can the bug be done consistently, or did it only happen once? Is it possible to take a screenshot of the error?

Note: Some editors will tell you Changes Saved. Don't panic! The ROM you are editing in MAGE is a temporary copy. MAGE will only save edits to your ROM if you explicitly tell it to.
If you broke your ROM, or made some undesirable change, you can reset the internal copy by reopening your ROM in MAGE.

Note: You cannot use both BG editing mode and Object editing mode at the same time. You pick one or the other

Notes: Only one of the special clipdata views can be used at a time.
Viewing Mothership hatches will not set the room to use them; it will just show them that way in the editor.

Notes:

Notes: In the header editor, if the property (prop) value of a BG layer is 0x10, it is RLE compressed. If the value has 0x40, it is LZ77 compressed. BG 1 and 2 are always RLE, BG3 is always LZ77, and BG0 can be either.

For importing tilesets / backgrounds from images, you can game it to generate palettes that are just as uniform as those already in the game. Organize the tileset into sections based on what palette blocks use, and from there keep the top left of each section blank. For each section with a different palette, draw an 8×8 tile with the palette in the order you want it to generate, from left to right top to bottom. The top leftmost pixel should be left as the first color, which acts as blank/transparent.

Quick access to editors and frequently used actions with interactible icons.

Note: Click the small arrow ▼ to undo/redo multiple steps at a time.

Switch between editing blocks (speedbooster) or objects (morphball). You will be using this a LOT.
When a sprite is added in object editor mode, you can quickly change it with [ or ]
On QWERTZ keyboard, the keys for this are “ß” and “´”
Door Exit Distances: 10- Right, no hatch 20- Right, hatch E0- Left, hatch F0- Left, no hatch

▶ More information: Header Editor

▶ More information: Tileset Editor

▶ More information: Graphics Editor

▶ More information: Palette Editor

▶ More information: Tile Table Editor

▶ More information: Animation Editor

▶ More information: Sprite Editor

▶ More information: Spriteset Editor

▶ More information: Connection Editor

▶ More information: Minimap Editor

▶ More information: Text Editor

▶ More information: Demo Editor

▶ More information: Physics Editor

▶ More information: Weapon Editor

With Object editing mode, you can move and place objects like enemies and interactibles- MAGE calls them sprites.
The type of sprites used in a room are determined by spritesets, which are set in the header for the room.
If a room uses more than one, you use this drop-down menu to switch spritesets in the room editor.
This allows you to edit the layout of sprites for each spriteset.
Each spriteset has its own unique layout.

Clipdata is the physical properties of a block.
Use this dropdown to select the type of clipdata you want to place.
You must also pick a tile with Tile Select, and make sure that Edit → Clip is checked ☑ or else you won't be able to place your clipdata.

This displays the current tileset and is used to pick the block(s) you intend to place.
Click to select, Click+drag to select multiple blocks.
Make sure that you have edit checked ☑ for the layer you want to place blocks on, otherwise they either won't place or they will be on the wrong layer.

From left to right:
Coordinates (X / Y) of currently highlighted tile
Size (W x H) of current selection
Clipdata ID of currently highlighted tile

Current position of your mouse pointer in the room.

Small box of text that appears if you idle your mouse pointer over a block.
BG0: Current tile placed on BG0 layer of this block
BG1: Current tile placed on BG1 layer of this block
BG2: Current tile placed on BG2 layer of this block
Clip: Current clipdata of this block

Hovering over the tileset in Tile Select will show a tooltip of the current block ID you're hovering over.

BACKGROUND DATA

POINTER

PROP (BG PROPERTY)

SPRITESET DATA

POINTER

SET

EVENT

MISCELLANEOUS

The screen to the left of a visible room in MAGE will look like this.

• Red- View selection (use to view certain layers)

• Orange- Edit selection (use to select a layer to edit and whether or not to edit clipdata)

• Yellow- Spriteset selection

• Green- Clipdata selection (only active if clipdata edit is selected)

• Blue- Tile selection; chosen from available tiles in tile set

Backing up your ROM is as easy as clicking on Create Backup. The filename of the backup is a timestamp, in the format YYYY-MM-DD_HH-MM-SS.gba

Sometimes, you may make a mistake. That's OK, happens to the best of us! You can quickly reload your rom by selecting it in Recent Files

When Use Selected Clipdata is activated, tiles placed will use the clipdata value from the drop-down list.

Can be used to view clipdata in 3 different ways:

• Collision (Outlines)

• Breakable (Reveals hidden breakable blocks)

• Values (Clipdata value and color)

You can also show or hide Sprites, Sprite Outlines, Doors and Scrolls.

To ensure that a room fits the screen, or to determine its shape in map tiles, you can turn on Screen Outlines.

If your room uses space pirate mothership hatches, you can select Mother Ship Hatches to swap to them.

You can also adjust Zoom level of the room to better see what you are doing.

You can Disable Tooltips if you find them annoying.

If you find that the default view of MAGE shows too much or not enough, you can adjust the Default View. This includes visible background layers, outlines, clipdata, objects, scrolls, screen outlines and doors.

You also have the option of changing the Number Base from hexadecimal to decimal.

</WRAP>