What is Metadata?

The rom includes lots of data. HexManiacAdvance uses Pointers and Anchors to provide navigation through this data, but also to be able to tell what the data is.

There are lots of different kinds of metadata, but what metadata is available is based on your rom.

• Tracks locations of useful data.
• Tracks formats of data so it can be displayed correctly.
• Tracks movement of data when when you expand or repoint it.

The most important thing to remember about metadata is:

HexManiacAdvance stores ROM specific metadata in a .TOML that lives with your ROM.

Example: If you're editing a file called FireRed.gba, then you can expect HexManiacAdvance to create a file next to it called FireRed.toml that it uses to store the metadata.

Whenever you make a backup of your rom, you should make a backup of your TOML. Whenever you revert to using a backup because something broke, you should also revert your TOML. Whenever you rename your rom, you should rename your TOML. Treat this file as an extension of your rom.

Where does the original TOML file come from?

Inside HexManiacAdvance's 'resources' folder is a file called default.toml and tableReference.txt. The default.toml file contains things loaded into the toml file that are the same for all the games: for example, the names of the evolution methods. tableReference.txt stores addresses and formats (most of which are tables, but that's not actually required). Note that the addresses found within tableReference are NOT the expected location of formatted data: instead, it's the expected location of a pointer to the formatted data. This is important, because it means that the initial guesses are more likely to be correct, and you rarely need to worry about editing this file.

Once the TOML file is created, it'll store the addresses and lengths of various data within your rom. You're free to edit this file if some of the addresses, formats, or lengths are incorrect. But edit at your own risk: HexManiacAdvance will trust whatever you put in this file. If you tell it that there's some formatted data called 'wombat' at a given address that contains a bunch of text and pointers, it'll believe you.

Editing Data vs editing Metadata

Most of the time, you don't want to edit the metadata directly. Your metadata will update automatically as you edit your rom. However, sometimes you notice that the metadata is wrong, and you want to change it. This section covers how to do that.

There are three main ways to edit the metadata without editing the data:

• Close HexManiacAdvance and edit the TOML file using Notepad.exe or any other text editor. This lets you see all the addresses and formats of everything in your ROM all at once. This is suggested for making large changes, such as updating the location of data after editing it with another tool.
• Click on an anchor ^ in the editor and edit the content of the Anchor editor. This lets you see your changes in the editor live as you make them. This is suggested for making single changes to existing formats.
• Go to an addresses and then type ^ followed by a name and a format. This is capable of working through in an automated fashion with copy/paste, so it's the recommended method of sharing metadata changes with others over the internet.

Note that other interactions with the editor will make changes to the data along with the metadata.

• Clicking "add new" in the table tool is a data edit: it will see that the next row of bytes isn't all FF, so it'll repoint the table and add a new element at the bottom.
• Changing the number at the end of the table format is a metadata edit: it will interpret the next row of bytes as a member of that table, without moving anything.

Add new metadata

The easiest way to add new metadata is inline in HexManiacAdvance.

Click anywhere in the file, then type ^ followed by the name for the anchor, then press space or enter to save. This new, blank anchor will get stored in the TOML. Already this is useful:

• You can now use Edit -> Goto (or Ctrl+G) to jump back to this spot in the data.
• HexManiacAdvance will look for any pointers to that location and display the name in the pointer instead of the address.
• This anchor name will be remembered next time you open HexManiacAdvance.

If you want to add more complex metadata, take a look at the list of available formats by either browsing your TOML file or looking at the Formats page.