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

#define NDEBUG

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

// #define NDEBUG

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.

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:

#define PRETTY_PRINT_HANDLER (PRETTY_PRINT_MINI_PRINTF)
#define LOG_HANDLER          (LOG_HANDLER_MGBA_PRINT)

BUGFIX and UBFIX

// 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:

#if MODERN || defined(BUGFIX)
#ifndef UBFIX
#define UBFIX
#endif
#endif

Locale (ENGLISH)

#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

1. Comment out NDEBUG

   In include/config.h:

   // #define NDEBUG
   
2. Set LOG_HANDLER to mGBA

   #define LOG_HANDLER (LOG_HANDLER_MGBA_PRINT)
   
3. Use AGBPrint functions in code

   The functions declared in include/gba/isagbprint.h become active:

   mgba_printf(MGBA_LOG_INFO, "warp id: %d", gSaveBlock1Ptr->location.warpId);
   
4. Open the mGBA log viewer

   In mGBA go to Tools → Game Boy Advance → View logs to see your output in real time.

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

Build tools (tools/)

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

gbagfx

Converts indexed PNG graphics to GBA 4bpp/8bpp tile format and back. Used for every sprite, tileset, and font graphic in the project.

preproc

Custom C preprocessor that handles pokeemerald’s string encoding. Converts string literals with special characters into GBA-compatible byte sequences.

scaninc

Scans source files for #include directives to generate accurate Makefile dependency lists.

mid2agb

Converts Standard MIDI Files (.mid) to AGB audio format (.s) for use with the M4A sound engine.

wav2agb

Converts WAV audio samples to the GBA PCM format used by M4A instrument voices.

jsonproc

Processes JSON map layout files (produced by porymap) into binary data that is assembled into the ROM.

rsfont

Handles font file conversion for the game’s text rendering system.

bin2c

Converts arbitrary binary files to C byte arrays, useful for embedding small binary blobs in source.

ramscrgen

Generates RAM script data used for dynamically constructed scripts at runtime.

gbafix

Fixes the GBA ROM header (Nintendo logo, checksum) so the ROM is accepted by hardware and emulators.

mapjson

Converts map data between the internal binary format and JSON, enabling round-trip editing with external tools.

Recommended external tools

porymap

Visual map editor for pokeemerald and pokefirered. Edits map layouts, object events, connections, and wild encounters, and exports JSON consumed by tools/jsonproc.

poryscript

High-level scripting language that compiles to GBA script binary. Strongly recommended for new event scripts. A VS Code extension is available.

Tilemap Studio

GUI tilemap viewer and editor. Useful for inspecting and modifying tilesets and map blocks outside of porymap.

mGBA

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.

All of these tools are listed under Useful additional tools in INSTALL.md.