> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pret/pokeemerald/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<AccordionGroup>
  <Accordion title="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                  |
  </Accordion>

  <Accordion title="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                 |
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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                   |
  </Accordion>
</AccordionGroup>

## Build system

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

<Tabs>
  <Tab title="Standard (matching) build">
    Produces a byte-for-byte identical ROM to the original Pokémon Emerald release.

    ```bash theme={null}
    make
    ```

    Output: `pokeemerald.gba` (in the repository root)
  </Tab>

  <Tab title="Modern (non-matching) build">
    Relaxes matching constraints. Useful for modding without worrying about ROM equivalence. Uses `ld_script_modern.ld`.

    ```bash theme={null}
    make modern
    ```

    Output: `pokeemerald_modern.gba` (in the repository root)
  </Tab>

  <Tab title="Clean">
    ```bash theme={null}
    make clean
    ```
  </Tab>
</Tabs>

Key Makefile variables:

```make theme={null}
TITLE      := POKEMON EMER
GAME_CODE  := BPEE
MAKER_CODE := 01
REVISION   := 0
FILE_NAME  := pokeemerald
BUILD_DIR  := build
```

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

## 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)
```

<Tip>
  Add `build/` to your editor's file exclude list to prevent indexing thousands of generated object files.
</Tip>