Graphics and Audio

GBA graphics pipeline, sprites, tilesets, and M4A audio.

pokeemerald targets the GBA’s 2D tile engine and the M4A (mp2k/Sappy) audio driver. Understanding how both pipelines work is essential when adding or modifying visual and sound assets.

GBA graphics overview

The GBA renders graphics using 8×8 pixel tiles stored in VRAM. Each tile uses either 4 bits per pixel (16-color palette) or 8 bits per pixel (256-color palette). The hardware composites up to four background layers and 128 sprites per frame.

All source artwork must be indexed-color PNG files. The tools/gbagfx tool converts them to the packed tile formats the GBA hardware expects.

Sprite sheets

Sprite sheets live under graphics/ as indexed PNG files. The Makefile converts them automatically using rules defined in graphics_file_rules.mk and spritesheet_rules.mk.

1. Create or edit the PNG

   Export a power-of-two indexed PNG from your image editor. Ensure the color count matches the target palette depth (16 or 256 colors).

2. Check the conversion rule

   Open graphics_file_rules.mk or spritesheet_rules.mk to verify the rule for your target file. Rules look like:

   $(POKEEMERALD_GFX)/sprites/%.4bpp: $(POKEEMERALD_GRAPHICS)/sprites/%.png
       $(GBAGFX) $< $@
   
3. Run make

   make
   

   tools/gbagfx will convert the PNG to the appropriate 4bpp or 8bpp tile format.

Tilesets

Each map uses two tilesets: a primary tileset shared across a region and a secondary tileset specific to an area. Tileset definitions are in data/tilesets/.

Primary tileset

Contains tiles common to an entire region (e.g. grass, water, paths). Loaded once when entering a region and shared by all maps using the same primary.

Secondary tileset

Contains tiles unique to a specific map or area. Loaded in addition to the primary tileset when a map is entered.

Map layout data is stored as JSON and processed by tools/jsonproc via rules in json_data_rules.mk. The resulting binary is assembled into the ROM.

Build tools — graphics

gbagfx

Converts indexed PNG files to GBA 4bpp/8bpp tile format and back. The primary graphics conversion tool for all sprites and tilesets.

rsfont

Processes font files used by the game’s text engine. Converts font sheets to the internal format.

bin2c

Converts arbitrary binary files into C byte arrays for embedding data directly in source.

jsonproc

Processes JSON map layout data (from porymap or hand-edited files) into binary data assembled into the ROM.

gbagfx usage

# PNG → 4bpp GBA tiles
tools/gbagfx input.png output.4bpp

# PNG → 8bpp GBA tiles
tools/gbagfx input.png output.8bpp

# Extract palette from PNG
tools/gbagfx input.png output.pal

M4A audio engine

The M4A engine (also called mp2k or Sappy) is the standard GBA audio driver used in nearly all first-party GBA titles. pokeemerald’s implementation lives in:

File	Role
src/m4a.c	Main driver: mixer, channel management, sequencer
src/m4a_tables.c	Lookup tables (frequency, volume, envelope)
src/m4a_1.s	ARM assembly mixer core
src/sound.c	Game-level sound API (PlaySE, PlayBGM, etc.)

Song data pipeline

1. Write or obtain a MIDI file

   MIDI source files live in sound/songs/midi/. Compose or edit using any standard MIDI sequencer. The M4A sequencer supports a subset of MIDI events.

2. Convert MIDI to AGB format

   tools/mid2agb input.mid output.s
   

   This produces an ARM assembly file with the song’s event sequence.

3. Convert WAV samples

   Instrument samples are stored as GBA-compatible PCM. Convert a WAV file with:

   tools/wav2agb input.wav output.s
   
4. Register the song

   Add the song constant to include/constants/songs.h:

   #define MUS_MY_NEW_SONG  (XXX)
   

   Then reference the assembled data in data/sound_data.s.

Sound data assembly

data/sound_data.s is the central file that assembles all song and sample data into the ROM. It #includes the .s output files produced by mid2agb and wav2agb.

Game-level sound API

src/sound.c exposes the functions used throughout the game:

Function	Description
PlayBGM(u16 songNum)	Start a background music track
PlaySE(u16 songNum)	Play a sound effect
StopMapMusic(void)	Stop the current map BGM
FadeOutBGM(u8 speed)	Fade out BGM over time
FadeOutBGMTemporarily(u8 speed)	Fade out BGM temporarily (resumes after)

Song numbers are the constants defined in include/constants/songs.h.

M4A uses a fixed number of mixing channels. Adding too many simultaneous sound effects will silently drop the lowest-priority channels. Keep SE channel counts in mind when composing.