Repository navigation
Releases
armGBA-3DS 0.0.6-alpha
armGBA on the New Nintendo 3DS: Game Boy Advance games on armGBA's own core with its recompiler, and Game Boy and Game Boy Color games on Gambatte. The game is on the top screen and the menu on the bottom one.
This is an alpha. The recompiler changes in 0.0.6 were played on a New 3DS in GBA DS for the 3DS (Super Mario Advance 3: Yoshi's Island for about 4 minutes, Mario Kart: Super Circuit for several races) and checked on 52 games against the exact CPU (below). Keep copies of saves you care about.
New since 0.0.5-alpha
- Fewer pauses in games that fill the recompiler's memory. Compiled code is kept in 1 MB stretches, each with a part for the code a game spends its time in and a part for the rest. When one part filled, whatever the other had left went unused: in Yoshi's Island about 40% of the memory. That room is now used. In Yoshi's Island the memory filled every 20-40 seconds, and emptying it cost a 100-170 ms pause.
- "Careful" copies take at most a third of that memory. These are the copies of code the game's timers and interrupts keep landing in. Past that share, the exact CPU steps to the event instead, as it already did before a block earned a copy. Yoshi's Island made thousands of them.
- Together: Yoshi's Island played about 4 minutes on a New 3DS with no pause after starting, and spends 13-15 ms a frame emulating instead of 15-17. Mario Kart's code now levels off at about 8 MB.
What you need
- A New 3DS, New 3DS XL or New 2DS XL with Luma3DS. The original 3DS and 2DS are too slow and aren't supported.
- For sound: the DSP firmware at
sdmc:/3ds/dspfirm.cdc(run the DSP1 homebrew once). - Your own games, anywhere on the SD card.
Install / upgrade
- FBI: Remote Install > Scan QR Code, with the QR code on this page (
armGBA-3DS-qr.png). - Or copy
armGBA-3DS.ciato the SD card and install it with FBI, or putarmGBA-3DS.3dsxinsdmc:/3ds/for the Homebrew Launcher. - Upgrading: install over 0.0.5. Settings, saves and the warm lists are kept.
How it was checked
On 52 games, 3000 frames each (tests/determinism.sh): the recompiler matches the exact CPU every frame (with and without the BIOS, and with the picture drawn on threads), the picture and sound are the same with the drawing threads and the sound thread as without, and every frame's picture and sound is the same as upstream armGBA's. Also with the recompiler's memory cut to 2 MB in a test build, so it fills and is emptied dozens of times a game: all 52 games matched the exact CPU for 3000 frames. These changes are in MagnominusGit/armGBA#9.
Install with FBI
FBI > Remote Install > Scan QR Code:
Or download armGBA-3DS.cia (HOME Menu) or armGBA-3DS.3dsx (Homebrew Launcher).
armGBA-3DS 0.0.5-alpha
armGBA on the New Nintendo 3DS: Game Boy Advance games on armGBA's own core with its recompiler, and Game Boy and Game Boy Color games on Gambatte. The game is on the top screen and the menu on the bottom one.
This is an alpha. The recompiler changes in 0.0.5 were played on a New 3DS in GBA DS for the 3DS (Mario Kart: Super Circuit, several races) and checked on 52 games against the exact CPU (below). Keep copies of saves you care about.
New since 0.0.4-alpha
- No more long pauses a couple of minutes into a game. The recompiler compiled the same code over and over from wherever the game's interrupts and timers happened to land, and kept slow "careful" copies of code they had ever landed in. In Mario Kart that filled its memory every couple of minutes; emptying it cost a 100-300 ms pause, and the new code came in 50-150 ms frames. Now it compiles about half as much: a whole race fits with room to spare.
- Slightly less time spent per frame in busy games (Mario Kart's races: about 5% less).
What you need
- A New 3DS, New 3DS XL or New 2DS XL with Luma3DS. The original 3DS and 2DS are too slow and aren't supported.
- For sound: the DSP firmware at
sdmc:/3ds/dspfirm.cdc(run the DSP1 homebrew once). - Your own games, anywhere on the SD card.
Install / upgrade
- FBI: Remote Install > Scan QR Code, with the QR code on this page (
armGBA-3DS-qr.png). - Or copy
armGBA-3DS.ciato the SD card and install it with FBI, or putarmGBA-3DS.3dsxinsdmc:/3ds/for the Homebrew Launcher. - Upgrading: install over 0.0.4. Settings, saves and the warm lists are kept.
How it was checked
On 52 games, 3000 frames each (tests/determinism.sh): the recompiler matches the exact CPU every frame (with and without the BIOS, and with the picture drawn on threads), the picture and sound are the same with the drawing threads and the sound thread as without, and every frame's picture and sound is the same as 0.0.4's. These changes are in MagnominusGit/armGBA#7.
Install with FBI
FBI > Remote Install > Scan QR Code:
Or download armGBA-3DS.cia (HOME Menu) or armGBA-3DS.3dsx (Homebrew Launcher).
armGBA-3DS 0.0.4-alpha
armGBA on the New Nintendo 3DS: Game Boy Advance games on armGBA's own core with its recompiler, and Game Boy and Game Boy Color games on Gambatte. The game is on the top screen and the menu on the bottom one.
This is an alpha. 0.0.4 has been run in the Azahar emulator; the core under it was checked on 52 games against armGBA's own main (below). Keep copies of saves you care about.
New since 0.0.3-alpha
- Up to date with armGBA's main (after 1.6): everything upstream has added since, for the Game Boy Advance and the Game Boy alike.
- Faster in busy scenes: while the two drawing cores catch up, the game's own core now draws lines too, and takes over a line a drawing core is late with (Mario Kart's races spent 2-6 ms of every frame waiting).
- No more sound drop-outs every half minute in Mario Kart: a silent noise channel was caught up all at once (20-40 ms on a New 3DS) when the game next touched it.
- Low Lag (Settings > 3DS Screens, on by default): frames are timed to the screen's refresh and started as late as they can be, with less sound queued: less delay from a button to the picture and the sound.
- The sound mixed on its own core, with the game's core standing in when it's late.
- Text backgrounds drawn faster; a few recompiler routines shorter.
- Fixed: with two drawing threads, a line of the picture could now and then come from the frame before; save states taken while two threads drew could differ from run to run. Neither changed how a game plays.
What you need
- A New 3DS, New 3DS XL or New 2DS XL with Luma3DS. The original 3DS and 2DS are too slow and aren't supported.
- For sound: the DSP firmware at
sdmc:/3ds/dspfirm.cdc(run the DSP1 homebrew once). - Your own games, anywhere on the SD card.
Install / upgrade
- FBI: Remote Install > Scan QR Code, with the QR code on this page (
armGBA-3DS-qr.png). - Or copy
armGBA-3DS.ciato the SD card and install it with FBI, or putarmGBA-3DS.3dsxinsdmc:/3ds/for the Homebrew Launcher. - Upgrading: install over 0.0.3. Settings and saves are kept.
How it was checked
On 52 games, 3000 frames each (tests/determinism.sh): the recompiler matches the exact CPU every frame (with and without the BIOS, and with the picture drawn on threads), the picture and sound are the same with the drawing threads and the sound thread as without, and every frame's picture and sound is the same as armGBA main's. Save states are laid out the same on 32-bit and 64-bit builds (tests/state-layout.sh).
Install with FBI
FBI > Remote Install > Scan QR Code:
Or download armGBA-3DS.cia (HOME Menu) or armGBA-3DS.3dsx (Homebrew Launcher).
armGBA-3DS 0.0.3-alpha
armGBA on the New Nintendo 3DS: Game Boy Advance games on armGBA's own core with its recompiler, and Game Boy and Game Boy Color games on Gambatte. The game is on the top screen and the menu on the bottom one.
This is an alpha. What 0.0.3 changes in the core has been played on one New 3DS under two other apps built on it (PokeDaisy and GBA DS). The armGBA-3DS app itself has only been run in the Azahar emulator with this version. Keep copies of saves you care about.
New since 0.0.2-alpha
- A freeze fixed: with two drawing threads, one could sleep through its wake-up, and the game then waited for it for good.
- Fast Flash Saves (on in the 3DS app): saving in Pokémon Ruby, Sapphire, FireRed, LeafGreen and Emerald no longer slows the game for seconds. The bytes saved are the same; the game's timing while it saves is not, so the core leaves it off unless a frontend turns it on.
- Render hooks for frontends that show a game across two screens (GBA DS): layers and sprites left out of the picture, and a second picture drawn from the same frame. Nothing changes for a frontend that doesn't set them, and save states are laid out as before.
What you need
- A New 3DS, New 3DS XL or New 2DS XL with Luma3DS. The original 3DS and 2DS are too slow and aren't supported.
- For sound: the DSP firmware at
sdmc:/3ds/dspfirm.cdc(run the DSP1 homebrew once). - Your own games, anywhere on the SD card.
Install
- FBI: Remote Install > Scan QR Code, with the QR code on this page (
armGBA-3DS-qr.png). - Or copy
armGBA-3DS.ciato the SD card and install it with FBI, or putarmGBA-3DS.3dsxinsdmc:/3ds/for the Homebrew Launcher.
Install with FBI
FBI > Remote Install > Scan QR Code:
Or download armGBA-3DS.cia (HOME Menu) or armGBA-3DS.3dsx (Homebrew Launcher).
armGBA-3DS 0.0.2-alpha
armGBA on the New Nintendo 3DS: Game Boy Advance games on armGBA's own core with its recompiler, and Game Boy and Game Boy Color games on Gambatte. The game is on the top screen and the menu on the bottom one.
This is an alpha. 0.0.1 was played on one New 3DS, with Mario Kart: Super Circuit and Advance Wars measured at full speed. What 0.0.2 adds has run in the Azahar emulator and in tests on a PC, and has not yet been measured on a console. Keep copies of saves you care about.
New since 0.0.1-alpha
- Threaded Audio (on by default): the sound is mixed on its own thread, on a core the game's thread doesn't use. The sound, the picture and save states are the same with it on or off.
- Shorter recompiled code: games' compiled code runs 10 to 16% fewer processor cycles.
- Frame Skip: Auto now skips only when a frame is actually late. Before, one slow moment could leave it dropping frames for seconds.
- Upstream armGBA merged, up to its commit of 2026-11-11: Fast-Forward Skip, a Frame Skip that keeps the renderer's line state, Device Motion for tilt and gyro cartridges, and fixes to save states.
- A development build's log now carries the processor's own counters and the sound thread's timing.
What you need
- A New 3DS, New 3DS XL or New 2DS XL with Luma3DS. The original 3DS and 2DS are too slow and aren't supported.
- For sound: the DSP firmware at
sdmc:/3ds/dspfirm.cdc(run the DSP1 homebrew once). - Your own games, anywhere on the SD card. The browser starts in
sdmc:/roms.
Known limits
- Link cable options are hidden: none has been tried on a console.
- A game's first minutes can stutter while its code is compiled; the app remembers what it compiled and prepares it at the next start.
- If something goes wrong, the app's log is at
sdmc:/3ds/armgba/log.txt.
Full instructions and settings: platform/3ds/README.md.
Install with FBI
FBI > Remote Install > Scan QR Code:
Or download armGBA-3DS.cia (HOME Menu) or armGBA-3DS.3dsx (Homebrew Launcher).
3DS Initial Release
armGBA-3DS
armGBA on the New Nintendo 3DS: Game Boy Advance games on armGBA's own core, with its recompiler
rebuilt for the 3DS's ARM11, and Game Boy and Game Boy Color games on Gambatte, as in the libretro
core. It's a standalone app (a .cia for the HOME Menu, or a .3dsx for the Homebrew Launcher)
with a small frontend of its own: the game on the top screen, the menu on the bottom one.
Status: 0.0.1-alpha. Played on one New 3DS, with two games measured closely (Mario Kart:
Super Circuit and Advance Wars, both at full speed). Everything else has only run in the Azahar
emulator. Expect bugs; keep copies of saves you care about. Reports are welcome, with
sdmc:/3ds/armgba/log.txtattached.
What you need
- A New 3DS, New 3DS XL or New 2DS XL with Luma3DS. The recompiler needs to make memory
executable, which Luma3DS allows homebrew to do. The original 3DS and 2DS aren't supported: the
app starts on them, but their 268 MHz CPU, with no cores to spare for drawing, is far too slow. - For sound: the DSP firmware dumped to
sdmc:/3ds/dspfirm.cdc(run the DSP1 homebrew once).
Without it the games run silent. - Your own games. armGBA-3DS comes with no games and downloads none.
Install
- HOME Menu: install
armGBA-3DS.ciawith FBI. Each release's page has a QR code: FBI >
Remote Install > Scan QR Code installs it straight from there. - Homebrew Launcher: copy
armGBA-3DS.3dsxtosdmc:/3ds/.
Put games anywhere on the SD card; the browser starts in sdmc:/roms and remembers the last folder.
It opens .gba, .gb, .gbc, .bin and .agb files, and the first game inside a .zip or
.7z, so a No-Intro set works as it is.
The app keeps its files in sdmc:/3ds/armgba/:
| Path | What |
|---|---|
system/ |
Optional BIOS and boot ROMs: gba_bios.bin, and the Game Boy ones as the libretro core names them. Without them armGBA uses its own open-source ones |
saves/ |
Game saves, <game>.srm and .rtc, the same files RetroArch makes: copy them either way |
states/ |
Save states, <game>.state (slot 0) to .state9 |
warm/ |
For each game, a list of the code the recompiler has translated, so the next time it's translated ahead of need (see How the port works). Safe to delete |
config.ini |
The screen settings and the core options that differ from the defaults |
log.txt |
What happened last run (log-prev.txt: the run before): attach it to a bug report |
Controls
| 3DS | Game |
|---|---|
| A, B, L, R, Start, Select | The same buttons |
| D-pad or Circle Pad | D-pad |
| Y in the game browser | Settings |
| X, Y (held) | Turbo A, turbo B |
| ZL, ZR (held) | Fast-forward |
| Touch the bottom screen | The menu |
While a game runs the bottom screen is dark, with its backlight off; touching it still opens the
menu. The menu has save and load state (ten slots), the screen (see below), smoothing,
Settings, restart, and close game. Settings (also Y in the game browser) holds armGBA's
options under headed sections: Display (the 3DS screens, Video, LCD Effects), Game (System, Clock,
Audio, Input) and Saves. Each option shows its values and its help text; L and R step ten values
at a time through the long lists, X puts an option back to its default (a * marks one that
isn't). Options that do nothing for the game loaded are hidden, as in RetroArch.
Settings > 3DS Screens > Bottom Screen in a Game > Performance shows the frame rate and where
each frame's time goes (emulation, waiting for the picture, translating, drawing on each core),
and writes the same to log.txt once a second.
The picture
- Pixel for pixel, Fit (as large as fits, 1.5x for the GBA) and Stretch, with optional
smoothing. - LCD3x: libretro's
lcd3xshader, as the 3DS can draw it. The 3DS's GPU has no programmable
pixel shaders, so a GLSL/slang shader can't be loaded; instead the top screen runs in its
800-column mode, the game is drawn three columns to a pixel (lcd3x's 3x across), and a mask
holding lcd3x's own factors at every screen pixel multiplies it on the GPU: the red, green and
blue stripes across ((4 + sin)/5) and the scanlines down ((16 + sin)/17). Across it's exact; down,
the screen has 1.5 rows to a GBA pixel, so the scanlines are sampled there. It costs the CPU
nothing. - armGBA's CPU LCD Effects (Settings > Display > LCD Effects): ghosting, interlaced rows, the
pixel grid and gaps, subpixels and the pixel shadow. LCD Scale is Off or Fit Screen here (the
top screen's size). They run on the CPU and cost a lot of it: try LCD Ghosting alone first.
Defaults that differ from the libretro core, for the 3DS: Skip BIOS Intro is on, Frame
Skip is Auto (the core skips drawing frames when the sound is about to run short), and
Threaded Video is On (see below; One Frame Late is there too).
Performance
Measured on a New 3DS, from the app's own log, each frame having 16.7 ms:
| Frame rate | Emulation, a frame | Drawing, each of two cores | |
|---|---|---|---|
| Mario Kart: Super Circuit, races | 59.7 fps | 9 to 12.6 ms (14.5 while a first lap is translated) | 3.7 to 5.7 ms |
| Advance Wars | 59.7 fps | 12.6 ms on average | about 2 ms |
| Advance Wars, the intro scene with an interrupt every line | 59.7 fps | 14.6 to 15.3 ms | about 2 ms |
With Threaded Video off (everything on one core) the same Mario Kart races took 14.5 to 16.1 ms
and the Advance Wars scene 16.5 ms, dropping to 58 fps. The first time a game reaches new code it
is translated, which can cost a few frames (a Mario Kart race's first start fell to 56 fps for a
second); the warm list is there so that happens once.
If a game runs slow, try in Settings: Frame Skip (Auto is on), CPU Clock below 100% (eases
slowdown in the game itself), and leave CPU LCD Effects and GBA Color Correction off.
Building
With Docker, from the repository's root:
docker run --rm -u $(id -u):$(id -g) -v $PWD:/src -w /src/platform/3ds devkitpro/devkitarm make -j4
That makes platform/3ds/armGBA-3DS.3dsx. make JIT=0 builds the interpreter alone (about 12
times slower, but useful to check the recompiler against). make cia also makes
armGBA-3DS.cia, with bannertool and makerom (from Project_CTR) on the PATH; makerom's
release binaries need glibc 2.38 or newer, so run that step on the host or in a newer container.
The icon, the banner and its chime are drawn by art/make.py (Python with Pillow).
The GitHub workflow (.github/workflows/3ds.yml) builds both on every push. A release is a
tag named 3ds-v<version> with a GitHub release published for it: the workflow attaches the
.cia and .3dsx and adds to the release's page a QR code of the .cia's download link, for
FBI to scan. The version itself is RELEASE (and MAJOR, MINOR, MICRO) in the Makefile.
Development builds
make LOG_URL=http://<host>:<port>/log builds one that, at start, POSTs the last run's log
(log-prev.txt, kept when a new run starts) and the new one to that URL, to see what happened on a
console without taking its SD card out (source/logupload.c), and that logs each second's
performance whether or not the bottom screen shows it. Any server that takes a POST will do.
Release builds leave all of it out: nothing in them uses the network.
How the port works
Most of armGBA builds for the 3DS unchanged. The changes, each behind __3DS__ or the ARM
architecture version unless said otherwise, so the other builds are untouched:
Getting it to run
- The recompiler on ARMv6. The 3DS's ARM11 MPCore is ARMv6K. The A32 backend was written for
ARMv7, and of what it emits only three instructions are ARMv7's: MOVW and MOVT (32-bit constants)
and UBFX (bit fields).src/cpu/a32/emit.hreplaces them when built for ARMv6: a constant becomes
MOV and up to three ORRs (or MVN and BICs, whichever is shorter), and a bit field two shifts, or
one shift or an AND where that's enough. - Executable memory. There's no
mmapon the 3DS.source/jitmem.ctakes the code memory
from the heap (up to 24 MiB) and makes it executable withsvcControlProcessMemoryon Luma3DS.
After code is written, one kernel routine cleans the data cache and invalidates the instruction
cache for just the lines written: block links and patches are a word or two, thousands of times
a second, and flushing whole ranges through the usual calls cost milliseconds a frame.
Before the app ends the memory is made read-write again: a process left with executable memory
hung the system on "Closing software". - Memory. The app asks for the 80 MB mode (the 124 MB one was granted only on some launches).
The core used to keep every game in a 32 MiB buffer, the whole cartridge space; the buffer is
now the game's size (reads past it are checked), and the frontend reads or unzips a game
straight into it and hands it to the core without a copy. The recompiler's bookkeeping takes
about 0.4 bytes of heap per byte of code, so it also flushes when the heap runs low, not only
when the code memory is full. -fwrapv. The core keeps its clocks in 32-bit counters that wrap after 2^31 cycles (128
seconds of play) and compares them by subtracting, which needs signed overflow to wrap.
devkitARM's GCC 16 optimized those comparisons away, and every game hung 128 seconds in.- Closing from the HOME Menu. Once the system has asked the app to close, it no longer has the
GPU: a frame submitted then never finishes. Nothing is drawn after that. - The Dolphin link's LAN search skips
getifaddrs, which the 3DS hasn't got.
Getting it to full speed (each measured on the console, through the development build's log)
- Drawing on the other cores. armGBA's Threaded Video l...




