> ## 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.

# Debug and Tools

> Debugging options, config flags, and the pokeemerald toolchain.

pokeemerald ships with a set of compile-time configuration flags and a bespoke toolchain for building and manipulating GBA assets. This guide covers how to enable debug output, what the config flags do, and what each tool in `tools/` is for.

## Config flags (`include/config.h`)

All compile-time options live in `include/config.h`.

### NDEBUG

```c theme={null}
#define NDEBUG
```

`NDEBUG` is defined by default, which **disables** all AGBPrint debug features. To enable printf-style debugging, comment it out:

```c theme={null}
// #define NDEBUG
```

<Warning>
  Do not ship a ROM with `NDEBUG` commented out. AGBPrint calls are no-ops on real hardware but can cause crashes on emulators that do not support the feature.
</Warning>

### Debug options (only active when NDEBUG is not defined)

When `NDEBUG` is absent, two additional switches become available:

**`PRETTY_PRINT_HANDLER`** — selects the printf formatter:

| Constant                   | Value | Notes                                                                       |
| -------------------------- | ----- | --------------------------------------------------------------------------- |
| `PRETTY_PRINT_MINI_PRINTF` | `0`   | Custom mini\_printf; supports `%S` for preproc-encoded strings              |
| `PRETTY_PRINT_LIBC`        | `1`   | Standard libc printf; may fail to link with some dkp arm-libc distributions |

**`LOG_HANDLER`** — selects where debug output is sent:

| Constant                   | Value | Target                        |
| -------------------------- | ----- | ----------------------------- |
| `LOG_HANDLER_AGB_PRINT`    | `0`   | AGBPrint hardware debug units |
| `LOG_HANDLER_NOCASH_PRINT` | `1`   | no\$gba emulator              |
| `LOG_HANDLER_MGBA_PRINT`   | `2`   | mGBA emulator (recommended)   |

The defaults when `NDEBUG` is undefined:

```c theme={null}
#define PRETTY_PRINT_HANDLER (PRETTY_PRINT_MINI_PRINTF)
#define LOG_HANDLER          (LOG_HANDLER_MGBA_PRINT)
```

### BUGFIX and UBFIX

```c theme={null}
// Uncomment to fix some identified minor bugs
//#define BUGFIX
```

Uncomment `BUGFIX` to apply fixes for identified minor vanilla bugs. `UBFIX` is automatically defined whenever `MODERN` or `BUGFIX` is set and corrects undefined-behavior issues that could prevent compilation with newer compilers:

```c theme={null}
#if MODERN || defined(BUGFIX)
#ifndef UBFIX
#define UBFIX
#endif
#endif
```

### Locale (ENGLISH)

```c theme={null}
#define ENGLISH
```

Defining `ENGLISH` sets:

* `UNITS_IMPERIAL` — distances and weights shown in imperial units
* `CHAR_DEC_SEPARATOR` to `CHAR_PERIOD` — period used as decimal separator

Remove `ENGLISH` to switch to metric units and a comma decimal separator.

## Debug printing with mGBA

<Steps>
  <Step title="Comment out NDEBUG">
    In `include/config.h`:

    ```c theme={null}
    // #define NDEBUG
    ```
  </Step>

  <Step title="Set LOG_HANDLER to mGBA">
    ```c theme={null}
    #define LOG_HANDLER (LOG_HANDLER_MGBA_PRINT)
    ```
  </Step>

  <Step title="Use AGBPrint functions in code">
    The functions declared in `include/gba/isagbprint.h` become active:

    ```c theme={null}
    mgba_printf(MGBA_LOG_INFO, "warp id: %d", gSaveBlock1Ptr->location.warpId);
    ```
  </Step>

  <Step title="Open the mGBA log viewer">
    In mGBA go to **Tools → Game Boy Advance → View logs** to see your output in real time.
  </Step>
</Steps>

<Tip>
  mGBA also supports GDB remote debugging. Build with `make modern DINFO=1` to include DWARF symbols, then connect GDB to the mGBA GDB stub.
</Tip>

## Build tools (`tools/`)

The `tools/` directory contains all first-party tooling built as part of the pokeemerald build system.

<CardGroup cols={2}>
  <Card title="gbagfx" icon="image">
    Converts indexed PNG graphics to GBA 4bpp/8bpp tile format and back. Used for every sprite, tileset, and font graphic in the project.
  </Card>

  <Card title="preproc" icon="code">
    Custom C preprocessor that handles pokeemerald's string encoding. Converts string literals with special characters into GBA-compatible byte sequences.
  </Card>

  <Card title="scaninc" icon="search">
    Scans source files for `#include` directives to generate accurate Makefile dependency lists.
  </Card>

  <Card title="mid2agb" icon="music">
    Converts Standard MIDI Files (.mid) to AGB audio format (.s) for use with the M4A sound engine.
  </Card>

  <Card title="wav2agb" icon="volume-2">
    Converts WAV audio samples to the GBA PCM format used by M4A instrument voices.
  </Card>

  <Card title="jsonproc" icon="braces">
    Processes JSON map layout files (produced by porymap) into binary data that is assembled into the ROM.
  </Card>

  <Card title="rsfont" icon="type">
    Handles font file conversion for the game's text rendering system.
  </Card>

  <Card title="bin2c" icon="file-code">
    Converts arbitrary binary files to C byte arrays, useful for embedding small binary blobs in source.
  </Card>

  <Card title="ramscrgen" icon="terminal">
    Generates RAM script data used for dynamically constructed scripts at runtime.
  </Card>

  <Card title="gbafix" icon="wrench">
    Fixes the GBA ROM header (Nintendo logo, checksum) so the ROM is accepted by hardware and emulators.
  </Card>

  <Card title="mapjson" icon="map">
    Converts map data between the internal binary format and JSON, enabling round-trip editing with external tools.
  </Card>
</CardGroup>

## Recommended external tools

<CardGroup cols={2}>
  <Card title="porymap" icon="map" href="https://github.com/huderlem/porymap">
    Visual map editor for pokeemerald and pokefirered. Edits map layouts, object events, connections, and wild encounters, and exports JSON consumed by `tools/jsonproc`.
  </Card>

  <Card title="poryscript" icon="scroll" href="https://github.com/huderlem/poryscript">
    High-level scripting language that compiles to GBA script binary. Strongly recommended for new event scripts. A VS Code extension is available.
  </Card>

  <Card title="Tilemap Studio" icon="grid-2x2" href="https://github.com/Rangi42/tilemap-studio">
    GUI tilemap viewer and editor. Useful for inspecting and modifying tilesets and map blocks outside of porymap.
  </Card>

  <Card title="mGBA" icon="gamepad-2" href="https://mgba.io">
    The best GBA emulator for pokeemerald development. Supports GDB remote debugging, a memory viewer, a tile viewer, and the `LOG_HANDLER_MGBA_PRINT` debug output channel.
  </Card>
</CardGroup>

<Info>
  All of these tools are listed under **Useful additional tools** in `INSTALL.md`.
</Info>