Project Structure

pokeemerald is a GBA decompilation of Pokémon Emerald. The repository separates C source, assembly stubs, binary assets, and build tooling into distinct directory trees.

Top-level layout

pokeemerald/
├── src/                  # C source files (300+ files)
├── asm/                  # ARM assembly stubs and macros
├── data/                 # Scripts, map data, tilesets, sound
├── include/              # C headers
│   ├── constants/        # Numeric constants
│   └── gba/              # GBA hardware abstraction
├── graphics/             # Sprite sheets and tilemaps (PNG + binary)
├── sound/                # MIDI songs
├── tools/                # Build tools
├── Makefile              # Build system entry point
├── ld_script.ld          # Linker script (retail-matching build)
├── ld_script_modern.ld   # Linker script (modern/non-matching build)
└── build/                # Generated output — created at build time

Directory reference

src/ — C source files

All game logic written in C, organized by subsystem. Over 300 .c files cover the battle engine, Pokémon data, overworld, UI screens, save system, and scripting.Key files:

File	Purpose
`src/main.c`	Entry point — hardware init, main game loop, callback dispatch
`src/battle_main.c`	Battle engine core — turn processing, battler actions
`src/pokemon.c`	`GetMonData` / `SetMonData`, `CreateMon`, `CalculateMonStats`
`src/overworld.c`	Field (overworld) game loop
`src/save.c`	Save file read/write and sector management
`src/script.c`	Script VM entry points and context management

asm/ — ARM assembly stubs

Hand-written or not-yet-decompiled ARM Thumb assembly files (.s). Also contains asm/macros/ with .inc files that define the domain-specific assembly languages used in data/.

Macro file	Used for
`asm/macros/battle_script.inc`	Battle script bytecode commands
`asm/macros/battle_anim_script.inc`	Battle animation sequencing
`asm/macros/battle_ai_script.inc`	Battle AI script commands
`asm/macros/event.inc`	Map event scripts
`asm/macros/movement.inc`	NPC and player movement sequences
`asm/macros/function.inc`	ARM function entry/exit macros
`asm/macros/m4a.inc`	M4A audio driver macros
`asm/macros/map.inc`	Map header macros

data/ — scripts, map data, tilesets, sound data

Binary and text data consumed by the C source.

data/
├── battle_scripts_1.s      # Core battle script bytecode
├── battle_scripts_2.s      # Additional battle scripts
├── battle_anim_scripts.s   # Animation sequences for all moves
├── battle_ai_scripts.s     # AI decision scripts
├── maps/                   # Per-map headers, events, and scripts
├── layouts/                # Per-map tile layout binaries
├── tilesets/               # Primary and secondary tileset binaries
├── scripts/                # Global and town-level event scripts
├── text/                   # All in-game strings
└── sound_data.s            # Sound table and music track data

include/ — C headers

All .h files. Two important sub-trees:

include/constants/ — numeric constant definitions: species.h, moves.h, items.h, flags.h, vars.h, abilities.h, maps.h, songs.h, battle.h
include/gba/ — GBA hardware register definitions and I/O macros (display, DMA, timers, interrupts)

include/global.h is the universal prelude. It pulls in the GBA headers, game type definitions, fixed-point math macros, and all constant headers.

graphics/ — sprite sheets and tilemaps

PNG source images and precompiled binary tilesets. gbagfx converts these to .4bpp, .8bpp, and .bin files that are INCBIN-embedded into the ROM at build time.

sound/ — MIDI songs

MIDI song files (.mid) and raw audio samples. mid2agb and wav2agb convert these to the GBA m4a sound driver format during the build.

tools/ — build tools

Custom tools compiled from C and invoked by the Makefile:

Tool	Purpose
`gbagfx`	Converts PNG graphics to GBA tile formats
`preproc`	Custom C preprocessor for Pokémon string encoding
`scaninc`	Dependency scanner for `.s` include files
`mid2agb`	MIDI to AGB sound driver format converter
`jsonproc`	Processes JSON data files into C arrays
`rsfont`	Font bitmap generator
`wav2agb`	WAV to AGB PCM sample converter

Build system

The Makefile at the repository root drives the entire build and targets the arm-none-eabi toolchain.

Standard (matching) build
Modern (non-matching) build
Clean

Produces a byte-for-byte identical ROM to the original Pokémon Emerald release.

make

Output: pokeemerald.gba (in the repository root)

Relaxes matching constraints. Useful for modding without worrying about ROM equivalence. Uses ld_script_modern.ld.

make modern

Output: pokeemerald_modern.gba (in the repository root)

make clean

Key Makefile variables:

TITLE      := POKEMON EMER
GAME_CODE  := BPEE
MAKER_CODE := 01
REVISION   := 0
FILE_NAME  := pokeemerald
BUILD_DIR  := build

The standard matching build requires the arm-none-eabi toolchain at a specific version. See the repository README for version requirements and setup instructions.

Linker scripts

File	Purpose
`ld_script.ld`	Retail build — places every section at addresses matching the original ROM
`ld_script_modern.ld`	Modern build — relaxed placement, compatible with current GCC

Build output

The build/ directory is created automatically:

build/
├── emerald/            # Object files for the default (agbcc) build
├── modern/             # Object files for the modern build
pokeemerald.gba         # Final ROM image (in the repository root)

Add build/ to your editor’s file exclude list to prevent indexing thousands of generated object files.

Get Started

Codebase Overview

Guides

Contributing

Top-level layout

Directory reference

Build system

Linker scripts

Build output

Build docs developers (and LLMs) love

Get Started

Codebase Overview

Guides

Contributing

Documentation Index

​Top-level layout

​Directory reference

​Build system

​Linker scripts

​Build output

Build docs developers (and LLMs) love

Top-level layout

Directory reference

Build system

Linker scripts

Build output