RustBoyAdvance-NG: a Game Boy Advance emulator and debugger in Rust

A GBA emulator whose selling point is the debugger

RustBoyAdvance-NG is a Nintendo Game Boy Advance emulator and debugger written in Rust. Most emulators are written in C or C++, and the author says plainly that the C++ project NanoboyAdvance by fleroviux was used for debugging while building this one, which is a hint that the goal was a different kind of system rather than a faster clone of an existing emulator.

The debugger is the differentiator. The key bindings list a function key that opens a custom debugger, which requires the debugger feature to be enabled at compile time, and another that spawns a gdbserver, marked as experimental and also behind a feature flag. There are also bindings to save and load snapshot files. So the project is usable as a plain emulator, but it is also built to be driven from a debugger, which is what you want if you are writing GBA software yourself.

The emulator core follows the ARM7TDMI, the processor in the GBA. The author credits the ARM7TDMI Technical Reference Manual as a primary reference and links GBATEK, the single page written by the no$gba developer Martin Korth, which he describes as having pretty much everything, and TONC, the comprehensive GBA development guide he used heavily to understand the system. There is also a mention of the Eggvance gba-suite, an arm7tdmi interpreter test suite by Julian Smolka, described as incredible and used for the interpreter.

That reference list tells you what kind of project this is. It is written by someone who needed a faithful ARM7TDMI implementation for their own development work, and the emulator is the vehicle for it. The topics list arm7-tdmi and emulator-programming alongside gameboy-advance-emulator and rust, and the licence is MIT with the LICENSE file at the root of the repository.

The project also ships a WebAssembly demo, deployed from a workflow, so the same core can run in a browser.

One core, one CPU crate and a row of platform front ends

The repository is a Cargo workspace, and the workspace file is the clearest map of the project. The members are core, arm7tdmi, utils, the SDL2 platform, the libretro platform, the WebAssembly platform, the JNI bindings, the terminal front end, and an fps_bench crate. The minifb front end is present but commented out and marked as deprecated, and the default member is the SDL2 desktop application.

The README describes the same split in prose. The core crate ties everything together. The arm7tdmi crate is the emulation of the processor. The platform directory holds the executables and applications built on top of the core crate, and it contains the web emulator powered by WebAssembly, the desktop application built with SDL2, a desktop application built with minifb that is explicitly not maintained, Java JNI bindings for the emulator, a full in-terminal frontend implemented with crossterm and viuer contributed by FRoith, and an Android application that is described as a proof of concept.

Two members of that list are easy to miss and both matter. The libretro platform puts the emulator behind the libretro interface, which is how it becomes usable inside a frontend that expects libretro cores rather than as a standalone program. And fps_bench is a separate crate for frame rate measurement, which tells you the author cared enough about performance to isolate the measurement from the emulator itself.

The Cargo profiles reinforce the same point. The dev profile sets an optimisation level of 2 rather than 0, the release profile turns off debug info, and there are additional release-dev and release-lto profiles for people who want debug symbols in an optimised build or link-time optimisation.

There is also a libretro entry, a utils crate, and a Dockerfile.android plus an external/ directory with .gitmodules, so the project carries a fair amount of build infrastructure alongside the emulator itself.

Building the desktop application on Linux, macOS and Windows

The README asks for a stable Rust toolchain of version 1.51 or later, and the repository also carries a rust-toolchain.toml so the toolchain is pinned for contributors. The default build target is the SDL2 desktop application.

On Linux you need the SDL2 development packages:

sudo apt-get -y install libsdl2-dev libsdl2-image-dev

On macOS the equivalent is a Homebrew install plus an explicit library path, which matters on Apple silicon where the libraries land under /opt/homebrew/lib:

brew install SDL2 SDL2_image
export LIBRARY_PATH="$LIBRARY_PATH:/opt/homebrew/lib"

Windows needs no extra setup at all, because the README says the SDL2 runtime binaries are included in the repository. That is a convenience for Windows developers and a reason the checkout is larger than a pure source tree.

With the dependencies in place, the run command is a normal cargo invocation:

$ cargo run --release -- path/to/rom

The README is emphatic that release mode matters, stating that performance is terrible in the dev profile, and the Cargo file explains why the dev profile is not unusable: it still optimises at level 2, it just keeps debug symbols.

The command takes a path to a ROM. The desktop application also accepts drag and drop of ROM files, and of zip archives containing .gba files, onto the emulator window, which then loads a new ROM.

The BIOS binary you have to supply yourself

There is a step in the README that is easy to skim past and impossible to skip: you need to obtain a GBA bios binary.

The file goes into the repository root and must be named gba_bios.bin, or you can point the emulator at one with the -b command line option. The README also notes that an open source GBA bios is available and supported, pointing at the binary published in the ReGBA repository, which is the practical route for anyone who does not want to dig out their own dump.

The design choice here is worth naming. Emulating the BIOS means reimplementing the undocumented startup code, the memory initialisation and the interrupt handling that the real cartridge BIOS performs, and any inaccuracy shows up as subtle breakage in a game rather than as an obvious error. Using a real BIOS binary sidesteps that work, and the price is that the emulator cannot be self-contained.

For an emulator developer this is a reasonable trade. For a user who wants a double click experience, it is friction, and it is the step most likely to trip up someone trying the project for the first time.

The BIOS also interacts with the key bindings, because the -b option is the only command line flag the README documents for pointing the emulator at content. Everything else is keyboard driven, and the README notes plainly that the key bindings are currently not configurable.

Inside the debugger: F1, F2 and snapshot files

The special key bindings table is where the tooling shows. Holding Space disables the 60 frames per second cap, which is the obvious thing to want when you are debugging something slow. F5 saves a snapshot file and F9 loads one, so you can return to a specific state without replaying.

F1 opens the custom debugger and F2 spawns a gdbserver. Both are behind feature flags, so a plain build of the repository does not include them: the debugger requires the debugger feature and the gdbserver requires the gdb feature, and the README marks the gdbserver as experimental.

Putting these two side by side shows the project's direction. The custom debugger is the author's own interface, integrated into the emulator window and available without external tooling. The gdbserver is the interoperability path, so an existing gdb workflow or an IDE that speaks the gdb remote protocol can attach. Offering both means the project serves someone learning the hardware and someone with a debugger habit, which is a sensible spread for a tool that is also a development environment.

The GBA keys themselves are mapped in a table, and the mapping has a quirk worth knowing before you blame the emulator. The arrow keys are listed so that Left produces Right on the GBA, and Right also produces Right, so the left direction is effectively unavailable through the keyboard. Keys are Z for B, X for A, Return for Start, Backspace for Select, and A and S for the L and R shoulder buttons. A mapping bug like that is exactly the kind of thing the debugger exists to work around.

The README does not document a configuration file for these bindings, since it says they are not configurable, so the table is the whole story.

What is still unfinished: CGB audio and the Android build

The progress section is short, which is itself informative. There is a screenshot of Pokemon Emerald, and a todo list with a single entry: CGB audio, referring to the four wave generator channels. So the Game Boy Advance side is the focus, and the compatibility hardware is not yet covered.

The Android application is the other gap. The README says the android project is placed inside platform/android and that you build it by opening it with Android Studio, and you also need to set up Rust to build Android targets with the NDK. Then it says TODO, instructions. The final line of that section is literally that the instructions are not written yet, and the only tagged release in the repository is an Android debug build from 2022.

That combination is worth weighing against the rest of the project. The wasm, SDL2, terminal and libretro front ends are described as working, the wasm demo is deployed automatically, and there is a CI workflow for building and another for deploying. The Android path is the leftover, and the release history confirms it, since the single tag is an Android build labelled as a debug artefact rather than a versioned release.

Other front ends are not uniformly supported either. The minifb desktop build is explicitly marked as not maintained, and the JNI bindings exist to serve the Android proof of concept.

So the honest picture of the current state is: a working desktop and browser emulator with real debugging support for GBA software, one audio feature short of the Game Boy Color hardware, and an Android target that has not been finished or documented.

Licence, release history and what the repository commits to

The licence is MIT, with the LICENSE file at the root of the repository. This article does not interpret it, but for a project that links against SDL2 and ships runtime binaries for Windows, the licence of the surrounding dependencies is the part to check alongside it.

The release history is thin in a way that is worth understanding. The only tagged release is test-android-build, an Android debug build from 2022-08-12, which is the sort of tag a maintainer pushes to trigger a workflow rather than a version a user installs. Crates are not published to a registry as far as the README indicates; the build instructions are cargo commands against the local checkout. So there is no published version to depend on, and the repository itself is the artefact.

The project is not archived and the last push was on 2026-08-27, so work is still landing. Whether you can rely on that continuing is a judgement call, and the single-item audio todo and the unfinished Android instructions suggest a maintainer with a specific set of interests rather than a broad push for completeness.

The build infrastructure is more substantial than the release history. There is a Cargo.lock, so builds are reproducible for contributors, a .gitmodules file and an external directory, a .github directory with the build, deploy and license workflows referenced in the badges, a Dockerfile.android, and an fps_bench crate in the workspace for measuring frame rate independently of the emulator.

For anyone evaluating this as a base for their own emulator work, the ARM7TDMI crate and the test suite that validates it are the parts with lasting value. For anyone who just wants to play a game, the SDL2 build with a BIOS file and a ROM is the whole story.

Editorial conclusion

Adopt RustBoyAdvance-NG if you want to read, run and debug Game Boy Advance software from Rust, especially if you are writing a GBA homebrew application and want to step through ARM7TDMI execution with the built-in debugger or a gdbserver. Do not adopt it if you expect a finished emulator, since CGB audio is still listed as unfinished and the Android application is still a proof of concept with instructions marked as TODO. Verify first that you can supply a gba bios binary, since the emulator will not start without one, that you build in release mode because the dev profile is described as slow, and that the platform you target has a maintained front end, since the minifb build is marked not maintained, and note that the last push was on 2026-08-27 and the only tagged release is an Android debug build from 2022 under the MIT licence.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. michelhe/rustboyadvance-ng on GitHub
4. README
5. Releases