Emerald Source Code Commentary

by 0xabad1dea, begun April 2023, last update November 2024

The Emerald Source Code Commentary is a book in the spirit of "A Commentary on the Sixth Edition Unix Operating System" that examines and explains the source code of one of the most popular video games ever made, based on the decompilation work of PRET. Please check the "Chapters" dropdown up top if you're looking for something specific.

Introduction

Video games are a crucial component of modern art and culture. They deserve to be preserved, they deserve to be accessible, and they deserve to be studied.

In the 1977 Commentary that introduced so many students to operating systems, J. Lions laid out the case for studying Unix in particular:

• it runs on a system which is already available to us;
• it is compact and accessible;
• it provides an extensive set of very usable facilities;
• it is intrinsically interesting, and in fact breaks new ground in a number of areas.

Pokemon Emerald is a similarly ideal case study for the structure and implementation of video games:

• the GBA platform can be emulated on absolutely anything;
• the game is modest in scope and written in C rather than assembly;
• it embodies every system expected of a 2D tile-based RPG;
• Pokemon is intrinsically interesting.

Released in 2004, Emerald rests at the balance point between small games written entirely in assembly and the modern AAA behemoth. At the ancient end, one spends too much time keeping mental track of registers and status flags to perceive the game; at the other extreme, the code in its totality (to include all the underlying drivers and libraries) is so large that not one single person actually does understand all of it. There is nothing running underneath a GameBoy Advance game. The hardware only runs a boot routine to display the logo and check that the cartridge appears to be valid before jumping to its entry point, at which point the game has absolute control. The BIOS burned into the hardware also contains some utility functions that it was expected almost every game would need; they are well-documented. Absolutely everything else needed to run the game is inside the game itself.

It is recommended to check out a general overview of GBA hardware capabilities. The GBATEK document contains the nittiest of grit.

Decompiliation

It may be surprising to see a commentary on the source code of a closed-source commercial game, especially from such a notoriously jealous and vengeful company. It so happens that the real, full original source code of Emerald is available on the internet. It's... unauthorized, obviously. Aside from that, there are a few reasons to hesitate from referencing it heavily: some of the functionality is unlocalized, the comments are in Japanese and in a pre-Unicode encoding that will not render correctly in modern editors, the way in-game text is represented is a nightmare and the variables (which in C must always be in ascii) are written in improvised wasei-eigo indecipherable to anyone but the original programmers:

case ITEM_GOOZYASUBOORU:
        tblno = EF_GOUJYASU_BALL;
        break;

(Note the two wildly different spellings of the same item name.)

Therefore, this commentary is built on the stellar work of PRET (Pokemon Reverse Engineering Tools) to produce a new body of decompiled source code that compiles exactly to the official English release of the Emerald ROM down to the last byte. You can browse the code base, download your own copy, compile it, and freely make changes. The comments and variable names follow English coding conventions. Reverse engineering the game to this level of perfection was an enormous amount of work and it was not done by the author of the Commentary. Please check the contributors page for more information.

Due to ongoing improvements in matters such as variable names and file structure, the current state of the PRET repository may not be identical to the code as quoted in the Commentary. However, since it is a round-trip decompiliation (that is, it recompiles to its exact original state), the code as a whole will always be functionally identical.

Since the decomp is based on the commercial release, all the debug tooling present in beta builds of the game is absent. Check The Cutting Room Floor for information on the Japanese-only debug tooling present in the leaked original source code. You can also consult the debug functionality present in Ruby/Sapphire.

Like all Pokemon games, Emerald is riddled with bugs. In addition to reproducing the original ROM, the PRET code base also supports alternate compilation settings to fix logic bugs and avoid undefined behavior that angers a modern, more standards-compliant compiler. You will see these optional code snippets inside #IFDEF blocks.

Continue on to Overall Structure and Layout.