This tutorial is meant to be a brief overview of the HexManiacAdvance user interface. It was written with version 0.3.7 in mind. It will introduce terms and concepts that will be useful throughout your time with HexManiacAdvance, but won't try and complete any specific task.

HexManiacAdvance supports editing any of the following English gba pokemon roms:

• Ruby 1.0
• Ruby 1.1
• Sapphire 1.0
• Sapphire 1.1
• FireRed 1.0
• FireRed 1.1
• LeafGreen 1.0
• LeafGreen 1.1
• Emerald

To simplify the tutorial, all the examples will be from FireRed 1.0. But the other games are equally supported.

Pokemon FireRed is 16 MB long, or 16777216 bytes. Each byte can have a value from 0 to 255. These numbers are a bit unwieldy when written in base-10, where each digits in 0123456789. Since computers work rather well with powers of 2, we can use the 16 digits in 0123456789ABCDEF to store numbers in a way that's both more compact and easier to remember. By convention, these base 16 numbers (called hexadecimal) begin with a 0x prefix, to help us remember that they're in base 16. With this information, we can write the length of the rom (16 MB) as 0x1000000. Each byte can now have a value that ranges from 0x00 to 0xFF.

Generally speaking, HexManiacAdvance is a Hex Editor. In the main body of the window (called the Hex Content), you can see individual cells, each with a single byte that ranges from 0x00 to 0xFF. The 0x prefix is left off in these cells to make the values more compact.

However, even just in this initial view of the very beginning of the FireRed rom, you'll notice a few things about the values displayed in the Hex Content.

• The values 00 and FF are displayed in a different color. Many times the values 00 and FF have a special meaning to the game. To help you pick them out easier, they're displayed a bit differently, to help them stand out. B5 is also displayed slightly differently (it's underlined), because B5 is often the second byte of a thumb subroutine.
• "POKEMON FIRE" and other text is readable. In a few cases, HexManiacAdvance will display a formatted value in a cell instead of a raw hex value. These values tell you what the data in that cell actually represents in the game. You can still see the raw hex by selecting those bytes and looking in the bottom right corner of the application.

This second capability, the ability to interpret the value of bytes, is what makes HexManiacAdvance so powerful and useful.

Scrolling down just a little bit, you'll notice another set of formatted data: sets of four bytes, displayed in blue, wrapped in <> angle braces, with names inside. You can hover to see the full name.

These are called Pointers. A pointer is always 4 bytes long. These 4 bytes, instead of representing a value themselves, represent a link to another location in the rom. You can Ctrl+Click to follow the link, or double-click. Go ahead and do so now, which will bring you to another part of the rom. For example, if you followed the data.pokemon.names pointer, your screen will look something like this:

Ignore the tool panel (on the left) for now and focus on the HexContent. You'll notice a few more changes.

• The number of bytes per row changed. While a standard hex editor will always show you 16 bytes per line, HexManiacAdvance will automatically adjust the number of bytes per line to help align the data.
• The row headers now contain names instead of addresses. This can help you quickly orient yourself while looking at the data, by helping you understand the purpose of an entry in the table instead of just the absolute location in the rom. But don't worry: the absolute address is always visible in the footer bar at the bottom of the window.
• The start of the table is marked with a blue ^ character. This is called an anchor. Any time you see an anchor, you can expect that some place in the rom points here. In this case, we already knew that, since we used a pointer to get here. But if you right-click on an anchor, you can get a list of all the addresses that point to it, and you can choose one to jump there. This can be a very useful way to navigate through the rom, letting you see the code that points to various tables.
• Above the Hex Content is the anchor with a data format, listed in a text box. This is the magic text that tells HexManiacAdvance how it should interpret the data. In this example, the full text is ^data.pokemon.names[name""11]412, which means:
  • ^: this is an anchor
  • data.pokemon.names: call this location 'data.pokemon.names' and allow other anchors to reference it.
  • [name""11]: this memory is a table of text blocks, called 'names', that are each 11 bytes long.
  • 412: there are 412 items in this table.

A more complete explanation of anchors and formats can be found in the Formats page.

Once HexManiacAdvance has opened your rom once, it'll create a .toml file for your rom, which will live next to your rom. It stores all the metadata about your game, including addresses of various tables and how all the data is related. You can edit the .toml file to adjust how your rom is interpreted. But most importantly: when you make a backup of your rom, make a backup of your rom's .toml file too! This will keep the metadata in sync with your changes. For more information, see TOML and You: How Metadata works.

For people less comfortable working with the Hex Content, HexManiacAdvance also includes 4 tools that share a panel on the left side. In some cases (like when you jump to a table), HexManiacAdvance will automatically switch tools for you. The 4 tools will be briefly explained here.

The table tool extracts data for the currently selected element of a table and shows you all of the values for that element. If multiple tables are tied together such that the elements are considered the 'same' thing (for example, there are many tables related to pokemon), the table tool will load the value from all those tables and show them all at the same time. This can help you understand how data is related, and makes things easier to edit.

At the very top of the table tool is a drop-down list that includes every table loaded in the game. This can be unwieldy, but is a good way to see every table currently available in HexManiacAdvance.

1. Each table's name is shown as a section header. You can click on them to expand/collapse those sections.
2. Some table data is shown as text fields. You can freely edit these.
3. Other table data is shown as selection boxes. You can use the drop-down to select an appropriate value from the list.
4. If a value is based on some other table in the rom (for example, pokemon ability names or type names), there is a small arrow button next to the data that lets you jump to the source of that data.
5. Most tables can be extended by choosing "Add New" while the last element of the table is selected. However, many table lengths are hardcoded in various places in the game, so simply expanding the table in this way is often not sufficient to do complex things like adding new moves, tutors, items, tms, types, or pokemon.
6. Some tables are linked, such as the pokemon name, stats, and tutors. This can lead to the table tool having a lot of information in it. You can use the filter to hide fields you're not interested in, helping you quickly search through the data.
7. Images can also appear in tables. HMA can import/export images, or open an image editor tab. Or you can use the arrow next to the image pointer jump directly to the image data, and view the image in the separate image tool.

The table tool includes a few other useful features as well.

• If the table is expanded, other "matched" tables (such as all the pokemone-related tables) will automatically be expanded by the same length.
• When a table is expanded, it will automatically be repointed if needed to prevent it from overwriting other data, and pointers are updated to match.
• If a table entry points to other data, a representation of that data is often shown inline with the pointer. This can make editing that data easy without having to jump to it.

• Reading long text in the Hex Content can be difficult, with arbitrary line wraps not matching up with the lines of the text. The text tool allows you to see text close to how it will appear in the game.
• Editing text in the text tool is a snap: you can copy/paste text, delete unwanted words, and expand the text as needed. If the new text no longer fits in the original location, the text tool will repoint your text to a safe location automatically.

The image tool lets you see a loaded sprite and palette, and their addresses, in one place. When appropriate, it can show you what that sprite looks like with that palette. And when a sprite knows what palette it's supposed to use, that palette will be loaded automatically whenever you click on the sprite.

You can export an image to PNG or import an image from PNG. Importing large images that use tilemaps will automatically create tilesets and reduce colors based on the available palettes. Furthermore, if you attempt to import an image that shares a palette with another image, HexManiacAdvance will provide multiple options to control how the new image's palette needs are balanced with other images that share the palette.

Typing an address into the Image Address (or Palette Address) fields and then hitting enter, will jump to that address and attempt to interpret it for you. Additionally, once you have a loaded image, you can adjust its width/height, bitness, and other settings to make it look right. This can help in the discovery of new images that aren't initially recognized by HexManiacAdvance.

As with the other tools, the Image Tool supports automatic repointing: if the new image data does not fit in the original space, the image will be safely moved to another location, and all pointers will be updated.

The code tool is the most complex tool. Since so much of the game is code, and there are so many different kinds, the code tool is not often activated automatically. Additionally, code is rarely interpreted inline in the Hex Content, unlike other data. Instead, you need to select the appropriate type of code (thumb, script, animation, battle script, or trainer AI script), and then either highlight the bytes you would like to decompile (for thumb code), or click the first byte of the script (for non-thumb code).

Changes to the code are automatically recompiled back into the ROM, and changes can be seen live. For most code types the GBA games use, you can type the start of a command, and a list of possible commands will appear, showing you what options you have for commands that start with the letters you just typed. Commands might have parameters, and you have to make sure you specify the right number. They may be pointers, names, or numbers. Any syntax/argument errors will stop HMA from compiling changes until you fix them all.

As you are adding code in the code tool, the amount of bytes used for whatever code segment you're editing will increase, but if HMA can't fit any more bytes in the current location, HMA will either output an error saying something like "Script is 7 bytes long, but only 2 bytes are available." or move the text to free space, as defined by the "Free Space" field on the bottom left of the application.

In some cases, if you remember the name of a particular table and need to put its pointer into your code, you can type its name instead of its address. Also, you can type "<auto>" within script commands that have pointer parameters if you want to specify any address that's in free space, which is helpful for many NPC script commands.