AGBA

AGBA is a Game Boy Advance emulator with a very normal frontend and a deeply unreasonable backend: the runtime hardware core is almost entirely handwritten x86-64 NASM.

CPU execution (ARM/THUMB), the memory bus, DMA, timers, interrupts, PPU, APU, save hardware, RTC/GPIO, and the HLE BIOS SWI handlers all live in over 15k lines of handrolled assembly. The remaining C side is solely for the chores. This is limited to ROM/save loading, SDL3 setup, presentation, input, audio submission, and process glue.

This is not a sensible emulator, and that is part of the point.

Accuracy

AGBA was intended to be highly accurate and have wide commercial-game compatibility. Test-suite results and comparisons against other popular emulators can be found in ACCURACY.md.

TLDR: the emulator is more accurate than it probably has any right being considering the circumstances, but this should not be read as a guarantee that every game in the GBA library is perfect (I haven't tested 2000 games). There are only a couple remaining suite inaccuracies, both of which run into the limits of the current instruction-bucket timing model.

Though if there is a severe emulator problem or a game crash, make an issue on GitHub with the details if you care enough, and I will more than likely look into it.

BIOS

By default AGBA uses its own HLE BIOS stub and HLE SWI handlers. This is fine in most cases as the HLE BIOS was intentionally written to be pretty accurate.

But loading an official BIOS dump is available too:

$env:AGBA_REAL_BIOS = "1"
.\cmake-build-debug\agba.exe path\to\game.gba

AGBA_REAL_BIOS=1 loads roms/gba_bios.bin. Any other nonzero value is treated as an explicit BIOS path (if you want to keep your BIOS file elsewhere). Unset or 0 uses the default HLE BIOS path.

This repository does not include any commercial ROMs or copyrighted BIOS dumps.

Building

Requirements:

• CLion, or CMake 3.21+ with Ninja and a MinGW-w64 toolchain
• NASM
• SDL3 MinGW development package placed in the source root

For SDL3, download the SDL3-devel-<version>-mingw asset from the official SDL releases, then extract/copy it so this directory exists in the project root:

SDL3/x86_64-w64-mingw32

The easiest setup is through CLion. Just open the project, let CLion configure its Debug or Release profile, and build the agba target. The executable lands in one of the usual CLion build directories:

• cmake-build-debug/agba.exe
• cmake-build-release/agba.exe

If you don't have CLion and want to build from PowerShell instead, run from a shell where Ninja and MinGW's gcc are on PATH, then force the Ninja generator. A plain cmake -S . -B build on Windows can pick Visual Studio, which might work but is not the setup this project is built around.

cmake -S . -B cmake-build-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build cmake-build-debug --target agba

cmake -S . -B cmake-build-release -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --target agba

CMakeLists.txt copies SDL3.dll next to the built executable after linking.

Running

.\cmake-build-debug\agba.exe path\to\game.gba

Controls

GBA input	Keyboard
A	Z
B	X
Select	Backspace
Start	Enter
D-pad	Arrow keys
L	A
R	S
Quit	Escape

Layout

• src/asm/ - CPU, memory, PPU, DMA, timers, APU, save, RTC, and BIOS SWI backend.
• src/ - C glue for ROM/save loading, the HLE BIOS image, SDL3 frontend code, and startup.
• include/emu.h - shared emulator state layout and C/ASM entry points.
• tools/ - small build-time helpers for generated ASM offsets.

Note

This is an emulator that should be looked at as an interesting artifact, not as a replacement for some other mature emulator. Lots of QOL features that you most likely take for granted will not be found here.

This emulator plays games, it plays them better and more accurately than it probably should, but that's about it.

Images