EN PT
← cd ../

~/labs/workshops/gba-firered/00-comece-aqui

Start hereWorkshop overview, prerequisites, and lesson order.

This is the workshop material. It teaches, from zero, how to take a Game Boy Advance game (we will use Pokemon FireRed) and discover how it works internally, up to the point where you change the game’s behavior with your own patch.

You do not need to know Assembly before you start. The material explains each concept in the order it appears.

What you will be able to do by the end

  1. Understand how the GBA boots, loads the ROM, and runs the game.
  2. Read ARM and Thumb instructions and know what each one does.
  3. Import the ROM into Ghidra and navigate through the game’s code.
  4. Find a value in memory (a Pokemon’s HP) during battle.
  5. Discover the exact instruction that writes that value.
  6. Reconstruct the in-battle Pokemon data structure.
  7. Close the function in Ghidra and make the decompile readable with names and a struct.
  8. Write, assemble, and install a patch that makes the enemy faint in one hit.

Lesson order

Follow the chapters in this order. Each one depends on the previous one.

01-arquitetura-do-gba.md      The hardware, CPU, and memory map.
02-arm-e-thumb.md             How to read CPU instructions.
03-ferramentas.md             mGBA, Ghidra, Python, GDB.
04-analise-estatica.md        Import into Ghidra and map the boot path into the game.
05-analise-dinamica.md        Find HP in RAM with mGBA and GDB.
06-encontrando-a-funcao.md    Close and clean up the HP function in Ghidra.
07-primeiro-patch.md          Write and install the damage patch.

The README.md at the project root has the detailed boot map and ROM hashes. RAM.md has the HP hunt written in detail. The chapters below stitch all of that into a single lesson path.

Before you begin

You need three things:

1. A legitimate dump of your own Pokemon FireRed USA 1.0 cartridge.
   SHA1: 41cb23d8dccc8ebd7c649cd8fbb58eeace6e2fdc
   Place it at: rom/PokemonFireRed.gba

2. A battle-ready save file (.sav), so you do not have to play through the whole
   tutorial during class. See notes/save-prep.md.

3. The tools installed. See chapter 03.

Do not distribute commercial ROMs. Each participant uses their own dump.