GBARunner2 3DS

From GameBrew

GBARunner2 3DS
Last Updated2020/08/12

GBARunner2 is a hypervisor that runs GBA games on DS/DSi/3DS in DS mode, basically like Nintendont does for running Gamecube games on Wii.


Note: GBARunner2 has the open source bios of Normmatt integrated, with some small modifications. A GBA bios is thus optional, but it can greatly improve compatibility with some games.

If you are using TWiLight Menu++, GBARunner2 will come bundled with it and you should find it already on the \_nds folder.

You can either replace the GBARunner2_arm7dldi_3ds.nds file on the \_nds folder, or place it anywhere on your SD card (except for in \_gba).

Place your GBA bios on your SD card (recommended for better compatibility). Either /bios.bin, /gba/bios.bin or /_gba/bios.bin will work.

If you have a folder named GBA on the root of your SD card, this folder will be opened by default when running GBARunner2 (supports .agb, .gba, .mb).

Once you have everything set up, run the .nds file through your kernel (if the .nds file is on the \_nds folder, you can just run the gba rom under TWiLight Menu++).

User guide

Save files

If you want to use existing save files, they should have the same name as the GBA ROM but instead of .gba they should be .sav (so the save for mygame.gba is mygame.sav).

GBARunner2 is directly compatible with save files from the mGBA emulator, gpsp on 3DS and open_agb_firm.

Compatibility List

GBARunner2 DSi/3DS compatibility list can be found here.

Do not use SRAM patches unless stated for that ROM on the wiki (if that is needed, use gbata). They cause problems with the internal patching of GBARunner2 and may actually break saving.


The settings are accessed by pressing R on the rom selection menu. Settings are saved when leaving the settings menu.

When running a ROM you can access the ingame menu by touching the touch screen. From here you can navigate with the D-Pad and use A, B like before and R to access settings.

  • Some games need specific settings to run well. Check your ROM in your system's respective compatibility list for this.
  • When editing a setting in the settings you will generate a settings.ini in sd/_gba . Here you can manually edit some of the settings if you open it with a notepad.
  • To see how to manually edit your input mappings look at Input Mapping.

Input Mapping

With GBARunner2 you can remap your buttons to what GBA button you want. This is done by going into settings that you can access from either the file browser or when ingame.

  • Note that you can not have one GBA button mapped to more than one button on your system (e.g. you cannot have the B button mapped to your X and Y button at the same time).
  • If you cannot access the settings menu if for example your shoulder buttons do not work or touch does not work, you can also manually edit the button mappings by opening the gbarunner2.ini file found in /_gba.
  • Below is an example of what you would find inside an ini file with the GBA L and R buttons mapped to Y and X, respectively. This can simply be pasted in a text file renamed to gbarunner2.ini and put in the folder \_gba.

Note: The text file will have to be in Unix (LF) file format. On Windows this can be changed with a source code editor like Notepad++ by right clicking Windows (CR LF) on the bottom status bar of the window and selecting Unix (LF).


Below are the DS Keys and their respective value if you want to manually make your own key mappings.

Custom Border and Covers

GBARunner2 supports custom border frames if put in sd\_gba\frames. An example of one and some pointers on how to make one yourself can be found in this post.

GBARunner2 supports game covers that you put in sd\_gba\covers. A collection of covers can be found here (from GBAtemp).


Cheats can be patched in ROMs to work with GBARunner2. However, not every game will work with cheats. This mostly depends on how big the game is and how much RAM the console you are using has.

For example Sonic Advance 3 which is around 14.5 MBs with cheats patched in works on the 3DS but not on the DSi nor DS.

To use cheats you have to patch your ROM with GBAATM.

To access the cheats menu you will have to have disabled "center and mask" in settings if not you will get a white screen and won't be able to see the ingame GBARunner2 menu. You can enable this again after leaving the menu.

Verifying Quality of ROMs

Some games may not work due to Intros/CrackTros that are added by Release Team.

  • These intros use code are supported by the 3DS and DSi builds if you disable "center and mask" in settings.
  • For the DS build, they are not yet supported and you can try using the GBATA tool to remove the Intro to get the Game to work.
  • You can use an Emulator to see if a Game has a Rom Intro or not.

Alternatively if the ROM still does not work, then you will need to verify that it is a good dump by calculating its checksum hashes (CRC32, MD5 etc.) and comparing them with the ones found on DAT-o-MATIC, which is a database of the No-Intro project of good ROM backups. Use 7zip or WinMD5 to do this as explained in the below section. This will show if your ROM has been corrupted too.

A good dump on DAT-o-MATIC will have a green colored background, a bad one will have a red one.

BIOS checksum

To verify that your BIOS is the right one that works for GBARunner2 see the checksums listed below (checking one should be enough):

  • CRC32: 81977335
  • MD5: a860e8c0b6d573d191e4ec7db1b1e4f6
  • SHA1: 300c20df6731a33952ded8c436f7f186d25d3492
  • SHA256: fd2547724b505f487e6dcb29ec2ecff3af35a841a77ab2e85fd87350abd36570

You can use 7zip to get a CRC or a SHA checksum by right clicking your file and selecting the menu called "CRC SHA" if you followed standard installation. Alternatively, you can check the MD5 with WinMD5Free. There are also websites that provide this service however we would recommend against doing that since you would essentially be uploading a BIOS online, which is copyrighted material, and therefore illegal to do.


D-Pad - Navigate in the file browser

A - Run a ROM, Enter a folder, Change a setting in settings

B - Go back a folder level, Return from settings

R - Access settings

Known issues

TWLBg Bug - Duplication of lines on the bottom of the screen when playing on a (N)2DS/3DS.

Occasionally, depending on the game, when running GBARunner2 on a system of the 3DS family of systems you might experience a bug where about 8 lines of pixels of the bottom of the screen duplicate and/or accumulate. This is the well-known TWLBg bug which is due to some bad coding by Nintendo.

However it manifests more often after this update, which started making the average number of gba cycles per frame equal to a real gba. This build fixed some issues with timer sync for audio. Several potential work-arounds are listed below. One is to revert to a version before this update. However your milage may vary if it helps depending on the ROM.

Here is the last build of the DSP branch before the commit that presents more TWLBg bug. Sticking to an older DSP build might be good if you want better audio, although your ROM might not work. If this is the case then you can try the build before the one you tried, and so on.

Alternatively you can use the currently latest master release (not DSP) which should not produce much TWLBg glitching, but it will possibly have worse audio/more desync or audio lag, but otherwise many improvements over the above linked DSP build.

The third alternative is to use the hicode hybrid build since it does not suffer from increased TWLBg bug same as the 'Master' branch builds.

Eventually it is planned (don't ask when) to fix the code that causes the bug to occur, or have an option to choose between two extra modes with the DSP build on 3DS that work without this framerate adjustment, since not all games need it.


Release notes.

External links