Metroid Intro Changed

gba_dumper is a set of utilities designed to make text modifications for Game Boy Advanced (gba) roms easier. Since gba games don't use ASCII and instead each use their own homebrew-encoding, gba_dumper streamlines the approach of translating rom byte-codes into human-readable characters.

Intended workflow

  1. Search for a string of text.
  2. Using the matches, let gba_dumper create a translation file. If there are multiple conflicting matches, gba_dumper will prompt you to choose the matching set.
  3. Using that translation file, dump a "translated" version of the rom.
  4. Using that dump, add special characters (:!@#, spaces, etc.) to the translation file and re-translate.
  5. Using the dump, note the areas of memory that hold strings you want to edit, and note the character used as a newline character in the game.
  6. Dump the memory noted in 5, edit all the strings you want, and re-upload them to a new dump.
  7. Using the modified dump, create a new rom.


-f	Path to the rom to perform operations on. This must be the uncompressed .gba file.
-r	Text to search for within the rom.
-z	When searching for text, the amount of fuzz (or allowed error) to apply.
-d	Dump the formatted bytes of the rom.
-t	Path to a valid translation file, which is newline separated list of byte_value : character values (e.g., 00FF : b).
-m	Path to a valid dump file, which is automatically generated after translating the rom.
-b	The two-byte value that the game uses for segment breaks within contiguous memory spaces.
-a	When dumping strings, the start address of memory to start dumping at.
-e	When dumping strings, the end address of memory to end dumping at.
-s	Path to a valid strings file to write back to the dump, which is a newline separated list of strings.

Code and tutorials can be found here.

I originally published this a few months back on