|data1 = [[GBA]]

|label2= Runs on

−

|data2 = [[Nintendo DS]]

|data2 = [[Nintendo DS, DSi, 3DS]]

|label3 =Developer

|data3 = [https://gbatemp.net/members/280844/ Gericom]

|label4 = Source code

|data4 = [https://github.com/Gericom/GBARunner2 GitHub]

−

|label5 = Latest version

|label5 = Latest stable version

−

|data5 = [https://github.com/Gericom/GBARunner2/releases/tag/~~v20190707~~-~~130214_916020e~~ Commit ~~916020e~~ (~~2019~~/07/07) build ]

|data5 = [https://github.com/Gericom/GBARunner2/releases/tag/v20200812-131430_6e4ce45 Commit 6e4ce45 (2020/08/12) build]

|label6 = Discussion thread

|data6 = [https://gbatemp.net/threads/gbarunner2.451970/ GBATemp.net]

'''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.

−

= Usage =

= Setup and Usage =

−

* Place a GBA bios on your sd card. Either /bios.bin or /gba/bios.bin will work.

−

** '''Note:''' Do not use Normmatt's open-source GBA BIOS. It won't work, as many patches are applied at fixed addresses. The right checksums are listed below.

−

* If you have a gba folder on the root of your sd, this folder will be opened by default

−

* Make sure your games are SRAM patched if needed, this is most likely only the case for FLASH1M_V103 (use [http://www.no-intro.org/gbadat/tools/gbata7a-en.zip gbata])

−

* If you are using GBARunner2 with TWiLightMenu on a DSi or 3DS with the SD card, make sure you use the dldi on ARM7 build

−

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

== Basic Setup ==

*Grab a GBARunner2 .nds file from the link above or the [https://github.com/Gericom/GBARunner2/releases github '''releases''' page]. Pick the one that has your system at the end of the file name.

**For example, for 3DS pick the one named 'GBARunner2_arm7dldi_'''3ds'''.nds'.

* Place the GBARunner2 .nds file anywhere on your SD card, except for in sd:/_gba.

**'''NB!''' If using Twilightmenu++ GBARunner2 will come bundled with it in the sd:/_nds folder.

*** If you are using GBARunner2 with TWiLightMenu on a DSi or 3DS with the SD card, make sure you use the dldi on ARM7 build. This will be bundled with it.

*Run the GBARunner .nds file through your kernel

* If you have a folder named 'GBA' on the root of your sd card, this folder will be opened by default when running GBARunner2. You can put your ROMs here.

* Do '''NOT''' use SRAM patches unless stated for that ROM on the wiki. They cause problems with the internal patching of GBARunner2 and may actually break saving.

* 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.

== Border Frames ==

GBARunner2 supports custom border frames if put in sd:/_gba/frames. An example of one can be found in [https://gbatemp.net/threads/gbarunner2.451970/page-134#post-8988124 this post].

FrescoASF wrote [https://docs.google.com/document/d/1owjiW-1fHEbokrkK2ZuPFjR2-N9s1dXCCAM3ghWRtxk/edit?usp=sharing a Google Doc guide] on how to make them yourself. macOS/Linux users can use the following terminal commands for the same results:

<pre>

# Convert an image to "gbaframe.*.bin", replace $1 with your file name

grit $1 -gt -gB8 -mLs -mRf -ftb -fh! -ogbaframe.bin

# Concatenate the ".pal.bin", ".map.bin", and ".img.bin" files together

cat gbaframe.pal.bin gbaframe.map.bin gbaframe.img.bin > gbaframe.bin

# Remove the unneeded files

rm gbaframe.pal.bin gbaframe.map.bin gbaframe.img.bin

</pre>

The TWLHelper bot on the [https://discord.gg/yD3spjv DS⁽ⁱ⁾ Mode Hacking!] Discord server has a command, <code>.border</code>, to automatically convert from an image file to a border.<ref>https://github.com/DS-Homebrew/TWLHelper/blob/main/cogs/convert.py#L485-L528</ref>

== Game Covers ==

GBARunner2 supports game covers that you put in sd:/_gba/covers. A collection of covers can be found under [[GBARunner2#Downloads|'Downloads']].

== BIOS ==

*GBARunner2 has integrated Normatt's open-source GBA BIOS, however, many ROMs will not boot or will present issues if you only use this.

*For better compatibility you should put your backed up GBA BIOS on your SD card with the lower-case name ''''bios.bin''''.

*Place this GBA bios on your SD card in either sd:/bios.bin, sd:/gba/bios.bin, or sd:/_gba/bios.bin.

**To verify that your BIOS is the right one that works for GBARunner2 see the [[GBARunner2#BIOS_Checksums|checksums]] listed below.

== Navigating and Usage ==

*When starting a GBARunner2 .nds file you will be in the file browser and from here you can scroll with the dpad. The other buttons do the following:

**'''A''' - Run a ROM, enter a folder or change a setting in settings.

**'''B''' - Go back a folder level or return from settings.

**'''R''' - 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 [[GBARunner2#Input_Mapping|Input Mapping]].

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

== 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, as explained above in [[GBARunner2#Navigating_and_Usage|Navigating and Usage]].

** 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 sd:/_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 'sd:/_gba'.

**'''NB!''' The text file will have to be in '''Unix (LF) file format'''. On Windows this can be changed with a source code editor like [https://notepad-plus-plus.org/ Notepad++] by right clicking 'Windows (CR LF)' on the bottom status bar of the window and selecting Unix (LF).

[emulation]

useBottomScreen=false

frame=true

centerMask=true

mainMemICache=true

wramICache=true

gbaColors=false

skipIntro=false

[input]

buttonA=0

buttonB=1

buttonL=11

buttonR=10

buttonStart=3

buttonSelect=2

</syntaxhighlight>

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

{| class="mw-collapsible mw-collapsed wikitable"

! DS Keys ||

| '''Key''' || '''Value'''

| A || 0

| B || 1

| X || 10

| Y || 11

| L || 9

| R || 8

| Start || 3

| Select || 2

== Cheats ==

* 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. You can follow [https://gbatemp.net/threads/how-to-use-cheats-with-gba-virtual-console.476624/ this guide] which works for GBARunner2. [https://github.com/Mte90/GBAATM-Rebirth/releases A newer fork of GBAATM] has been made but it is untested in this usage case.

* 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.

= BIOS and ROM Quality =

== Dumping the BIOS ==

To get your own GBA BIOS here are some possibilities:

* [https://glazedbelmont.github.io/gbabiosdump/ GBA/DS/DS Lite with GBA flashcart or 3DS]

** It is '''not''' possible to dump the GBA BIOS on a DSi

* [https://github.com/FIX94/gba-link-cable-dumper Wii (not Family edition)/GameCube, GBA, and link cable dumper]

== BIOS Checksums ==

−

The BIOS used should have the following checksums (checking one should be enough):

You can check if any file matches another by calculating something called their checksum hashes. These alphanumeric sequences are so specific that if two files match then you can be certain that they are the same. This is necessary because sometimes when downloading or transferring files they get corrupted. Even a small change in the file will greatly change the file's checksum hash. Different algorithms exist for doing this (e.g. {{w|MD5}}, {{w|CRC32}}).

The GBA BIOS used should have the following checksums (checking one should be enough):

'''If dumped from a GBA, GBA SP, Game Boy Micro, or Game Boy Player:'''

* CRC32: <code>81977335</code>

* MD5: <code>a860e8c0b6d573d191e4ec7db1b1e4f6</code>

* SHA256: <code>fd2547724b505f487e6dcb29ec2ecff3af35a841a77ab2e85fd87350abd36570</code>

−

~~You can check the~~ MD5 ~~with [http~~://~~www.winmd5.com~~/ ~~WinMD5Free] for example.~~

'''If dumped from a DS, DS Lite, or 3DS Family console:'''

* CRC32: <code>a6473709</code>

* MD5: <code>1c0d67db9e1208b95a1506b1688a0ad6</code>

* SHA1: <code>c11531d5261006810cdc954bd4bec0afe3187b35</code>

* SHA256: <code>782eb3894237ec6aa411b78ffee19078bacf10413856d33cda10b44fd9c2856b</code>

−

= Compiling the ~~latest version~~ =

You can use [https://www.7-zip.org/ 7-Zip] 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 [http://www.winmd5.com/ WinMD5Free]. There are also [https://emn178.github.io/online-tools/crc32_checksum.html websites] that provide this service.

== Verifying Quality of ROMs ==

* '''NB!''' Some games have Release Team Intros/CrackTros added to them. These intros use code that is not supported by the DS builds yet, but they are by the 3DS and DSi builds if you disable ''''center and mask'''' in settings.

**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 [https://datomatic.no-intro.org/ 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 and linked to above in the 'BIOS Checksum' part. 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.

= Builds =

== Compiling the Latest Version ==

1. Make sure you have devkitpro installed.

3. Run make in the root.

−

= Downloads =

== Downloads ==

−

New commits are now automatically ~~build~~ and can be downloaded on the [https://github.com/Gericom/GBARunner2/releases github release page].

New commits are now automatically built and can be downloaded on the [https://github.com/Gericom/GBARunner2/releases github release page].

Download link for gbarunner2 compatible '''cover art''': https://mega.nz/#!Q8dnHALK!kA4UuEpqo7JQwScxLiorZ_qj4lWBsBr7B6Sb_BgAzsw

* To run large ROMs like '''Pokémon Emerald''' on your DS/DSLite you should use this fork of the '''ROM3M''' branch of GBARunner2 called DSL enhanced edition by Void Star: https://github.com/unresolvedsymbol/GBARunner2-DSL-Enhanced/releases

=== Legacy Builds ===

* Commit 5abecad (2019/07/05), (Fixes the contra title screen, partially the advance wars intro, Madden NFL Note that bitmap bg transforms are currently not supported) posted [https://github.com/Gericom/GBARunner2/releases/tag/commit_5b06bb4bd12d8fe12574b0564e0ce0fb7fb02760 here].

* [https://gbatemp.net/attachments/gbarunner2-zip.72394/ Commit 78945c3 (2016/12/18)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-2#post-6933255 here].

−

= Changelog =

</div>

== Changelog ==

See [https://github.com/Gericom/GBARunner2/commits/master GitHub timeline].

−

= Compatibility list =

= Compatibility lists =

== 3DS and DSi Compatibility List ==

<big>'''[[GBARunner2/DSi_3DS_Compatibility_List|The 3DS and DSi have their own compatibility list! Click Here!]]'''</big>

== DS Compatibility List ==

{|width="25%" cellspacing="1" border="1px"

== Retail games ==

−

* '''! A save error message (and sometimes other crashes too) means that your game must be sram patched (every game not using sram should be patched so check that before reporting) - check the Usage section for the appropriate tool !'''

−

* '''! Some games have Release Intro´s attached to themselve. Those Intros use a Code that is not supported yet. Try using the GBATA tool to remove the Intro to get the Game to work. Use an Emulator to see if a Game has a Rom Intro or not !'''

−

~~== Retail games ==~~