Project Structure

Navigate the pokeemerald source tree.

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

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

make

Output: pokeemerald.gba (in the repository root)

Modern (non-matching) build

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)

Clean

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.