A Game Boy Advance emulator written from scratch in C, featuring Hardware X-Ray Mode: a real-time view of what the GBA hardware is actually doing while a game runs.
No other GBA emulator offers this. Every emulator is a black box. This one lets you see inside.
Built around an ARM7TDMI CPU interpreter, scanline-based PPU, and an SDL2 frontend. No external libraries beyond SDL2. Pokemon Emerald is fully playable end-to-end.
Jump to: Download · Features · Screenshots · Quick start · Building · Documentation
Ready-to-run apps for macOS (Apple Silicon), Windows and Linux are on the latest release. There's nothing else to install.
New to GitHub? Don't use the green Code button at the top of this page, and don't click Source code (zip) on the release page. Those download the program's source code, which you can't play. You want one of the files listed below.
- Go to the latest release.
- Scroll down to Assets. If you don't see the files, click Assets to open the list.
- Click the file for your computer:
| Your computer | Click this file |
|---|---|
| Mac with Apple Silicon (M1 or newer, macOS 11+) | the one ending in macOS-arm64.dmg |
| Windows (64-bit) | the one ending in Windows-AMD64.zip |
| Linux | the one ending in x86_64.AppImage |
Not sure which Mac you have? Click the Apple menu > About This Mac. If it says Chip: Apple M1 (or M2, M3 and so on) you're good. Intel Macs aren't supported yet.
Your computer may warn you the app is unsafe or could be malware. This is expected. Apple and Microsoft show this for any app whose developer hasn't paid for a signing certificate, which most free hobby projects haven't. It doesn't mean a virus was found. The steps below show how to tell your computer you trust it. You only have to do it once.
Mac
- Open the
.dmgyou downloaded and drag GBA Emulator into Applications. - Double-click GBA Emulator in Applications. macOS will refuse to open it, with a message like "GBA Emulator" Not Opened: Apple could not verify "GBA Emulator" is free of malware. Click Done (not Move to Trash).
- Open System Settings > Privacy & Security and scroll down to the Security section. You'll see "GBA Emulator" was blocked to protect your Mac. Click Open Anyway.
- Double-click the app again. Click Open Anyway once more, and type your Mac password if asked. From now on it opens normally.
Windows
- Right-click the
.zipyou downloaded and choose Extract All. The app won't run from inside the zip. - Open the extracted folder, then the
binfolder, and double-clickgba_emulator.exe. - If a blue box says Windows protected your PC, click More info, then Run anyway.
- Your browser or antivirus may also flag the download as uncommon or unsafe. In Edge or Chrome, open the downloads list, click the ... next to the file and choose Keep.
Linux
- Right-click the
.AppImage, open Properties and allow it to run as a program. - Double-click it.
The emulator doesn't come with any games. You need your own .gba game files (ROMs), which you can make from cartridges you own. A GBA BIOS file is optional, the emulator works without one.
When the app opens, click Choose folder… and pick the folder where you keep your games. Then double-click a game to play it. Your saves are stored in the same folder as the game. The default keys are in Quick start.
More detail for each system is in Installing a pre-built binary.
| Feature | Key | What it does |
|---|---|---|
| Hardware X-Ray Mode | F2 | A second window showing background layers, sprites, tiles, palettes, audio channels, CPU registers, timers, DMA and interrupts as the game runs. |
| Save states and rewind | F5 / F8, Backspace | 10 save-state slots, plus hold Backspace to rewind up to 60 seconds. |
| Fast-forward | Tab, ` |
Hold Tab to speed up, or press ` (the key left of 1) to keep it on. Screenshots and fullscreen are in the controls list. |
| Input display and frame advance | F3, \ |
Show the buttons you're holding on screen, or step through the game one frame at a time. |
| Game library | Opens when you start the app without a game, with your games folder, recently played games and a Continue playing button. | |
| Settings | Ctrl+, (Cmd+,) | Change keyboard and controller buttons, set up turbo A and B, and pick the fast-forward speed, volume and BIOS. |
| Cheats | Paste CodeBreaker, GameShark or Action Replay codes as found online. Your save is backed up before any cheat runs. | |
| ROM patches | Play IPS, UPS and BPS hacks and translations without patching the ROM. Each patched game keeps its own save. | |
| Zipped games | Open a downloaded .zip directly, no unzipping. |
|
| Link cable | Two windows on the same machine can trade and battle. | |
| Screen filters | Smooth out jagged pixel edges and match the colors of a real GBA screen. | |
| HQ music | H | Game music re-mixed in high quality for games that use the standard MP2K sound driver. |
These need the original, unmodified US/English ROM of Pokémon Emerald, FireRed (1.0) or LeafGreen (1.1). Every other game still runs normally.
| Feature | Key | What it does |
|---|---|---|
| Pokémon Companion | F9 | A side panel with live info from your game. F10 switches pages. Works with Emerald, FireRed and LeafGreen. |
| Battle | The opponent's IVs, nature, ability and held item, move matchups both ways, and in wild battles the catch odds for each ball. | |
| Damage | Predicted damage as a percent of HP on every move in a battle, with KO coloring, for your moves and the enemy's. | |
| Party | Your Pokemon's hidden stats: IVs, EVs, Hidden Power, friendship. | |
| Move relearner | The next move each Pokemon learns by level, and what the move relearner can teach it before you spend a Heart Scale. | |
| Daycare | Your Daycare Pokemon, egg odds and the next roll, what the egg will be (on Emerald even whether it's shiny) and steps until each egg hatches. | |
| Trainer card | C | Save a shareable picture of your team, as a grid or with your ace up front. |
| Route | The wild encounter table for where you are, with caught Pokemon checked off. | |
| Roaming | Where Latias, Latios or the legendary dogs are roaming right now, with their HP and status, and a heads-up when they're on your route. | |
| Mirage Island | J, twice | Which of your Pokemon raises Mirage Island today and when it next will, then jump the clock to that day. (Emerald only) |
| Nuzlocke | N | Logs each area's first encounter, every death and any reload after a death. |
| Berries | B | Every berry tree you've planted, with growth, watering and countdowns, plus a toast when berries are ripe, need water or are about to drop. (Emerald only) |
| Search | / | Type a Pokemon's name to see every wild spot with levels and odds, or how to get it by evolution or breeding. |
| Hunt | [ ] | Shiny hunting in tall grass: counts every encounter, shows the next Pokemon and when a match comes up. (Emerald only) |
| Run stats | F10 | Your playthrough's story: badge art and times, catches, faints, evolutions, an MVP and the game's own counters. |
| Overworld X-Ray | F4 | Trainer sight lines, item names, NPC gifts and the hidden Feebas tiles drawn right on the map. (Emerald only) |
| Following Pokemon | F1 | Your lead Pokemon walks behind you, talks like it does in HeartGold and SoulSilver and reacts to trainers, people, items and weather, using your own HeartGold or SoulSilver ROM (Emerald only). |
| Randomizer | Shuffle the starters, wild Pokemon and every trainer's team, per save, in Settings. Your save and ROM are never edited. (Emerald only) |
 Battle: IVs, nature and matchups for a wild Poochyena |
 Berries: a ripe Pecha, 10 hours before it drops |
 Run (FireRed): badges, story and highlights after the Hall of Fame |
 Party (LeafGreen): hidden stats on Cinnabar Island |
 Nuzlocke: every area used and what you met there |
 Mirage Island: which Pokemon raises it, and when |
 Following Pokemon: Latios in Lilycove City |
 Party: hidden stats for each Pokemon |
 Search: the list narrows as you type |
 Search: not wild? It shows the evolution path |
Open the app and pick a game from the library, or run it from a terminal:
./build/gba_emulator path/to/rom.gba --scale 3| Key | GBA button |
|---|---|
| Z / X | A / B |
| Enter / Right Shift | Start / Select |
| Arrow keys | D-Pad |
| A / S | L / R |
| Key | Does |
|---|---|
| F2 | Hardware X-Ray Mode |
| F4 | Overworld X-Ray (Pokemon Emerald) |
| F9 | Pokémon Companion (Emerald, FireRed, LeafGreen) |
| F5 / F8 | Save / load state |
| Tab (hold) | Fast-forward |
` |
Toggle fast-forward (stays on until pressed again) |
| Backspace (hold) | Rewind |
| Space | Pause |
| F11 | Fullscreen |
On macOS, hold fn with the F-keys unless your keyboard is set to use them as standard function keys. Saves are written next to the ROM. The full controls list and every command-line option are in the usage guide.
You need SDL2 2.0+, CMake 3.21+ and a Rust toolchain (brew install sdl2 cmake rust on macOS; on Linux apt install libsdl2-dev cmake plus Rust from rustup.rs).
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
makeBuild options, the architecture, the test suite and the golden-frame checks are in the development guide.
- Using the emulator: installing, the game library, command-line options, all controls, settings, screen filters, Following Pokemon, headless mode, link cable, cheats
- Pokémon Companion and Overworld X-Ray
- Hardware X-Ray Mode
- Randomizer
- HQ music
- Development: building, what's emulated, architecture, project structure, testing, roadmap, references
- Contributing: ground rules and the checks to run before opening a pull request
Bug fixes, accuracy fixes and test ROM results are welcome. For a new feature, open an issue first so we can agree on the approach. Pull requests need a green CI run (Linux, macOS, Windows, sanitizers, Rust and golden-frame checks) and a review before they merge. Never include ROMs, BIOS files, saves or data taken from a game. See CONTRIBUTING.md for the full rules and the checks to run before you open a PR.
This project is open source. See LICENSE for details.
Note: You must supply your own GBA BIOS and ROM files. They are not included in this repository.