|data1 = [[GBA]]
 
  |data1 = [[GBA]]
 
  |label2= Runs on
 
  |label2= Runs on
−
  |data2 = [[Nintendo DS]]
+
  |data2 = [[Nintendo DS, DSi, 3DS]]
 
  |label3 =Developer
 
  |label3 =Developer
 
  |data3 = [https://gbatemp.net/members/280844/ Gericom]
 
  |data3 = [https://gbatemp.net/members/280844/ Gericom]
 
  |label4 = Source code
 
  |label4 = Source code
 
  |data4 = [https://github.com/Gericom/GBARunner2 GitHub]
 
  |data4 = [https://github.com/Gericom/GBARunner2 GitHub]
−
  |label5 = Latest version
+
  |label5 = Latest stable version
−
  |data5 = [https://gbatemp.net/attachments/gbarunner2_arm9dldi_wramicache-nds-zip.148184// Commit 6522414 (2018/11/01) (if arm9 doesn´t work, try arm7 below.)]
+
  |data5 = [https://github.com/Gericom/GBARunner2/releases/tag/v20200812-131430_6e4ce45 Commit 6e4ce45 (2020/08/12) build]
 
  |label6 = Discussion thread
 
  |label6 = Discussion thread
 
  |data6 = [https://gbatemp.net/threads/gbarunner2.451970/ GBATemp.net]  
 
  |data6 = [https://gbatemp.net/threads/gbarunner2.451970/ GBATemp.net]  
 
}}
 
}}
   −
'''GBARunner2''' is a GBA hypervisor for DS (like Nintendont for GC on Wii).
+
'''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 =
   −
1. Make sure your SD card is fat32 formatted.
+
== 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.
   −
2. Put a GBA bios as bios.bin in the "gba" folder in the root of your sd card.(*)
+
== Border Frames ==
   −
3. Put GBARunner2.nds on your sd card. If you are running TWiLight Menu++/DSiMenu++/SRLoader, GBARunner2.nds should be in the "_nds" folder (should be already)
+
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].
   −
4. '''Some Games need to be sram patched if the game didn't already use sram for saving''' [https://filetrip.net/gba-downloads/tools-utilities/download-gbata-gba-tool-advance-0-7a-f223.html GBATA]. This prevents some Error Messages.
+
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:
   −
5. By default, GBARunner2 will look for a "gba" directory on the root of your sdcard, otherwise it will open the root of your sdcard.
+
<pre>
 +
# Convert an image to "gbaframe.*.bin", replace $1 with your file name
 +
grit $1 -gt -gB8 -mLs -mRf -ftb -fh! -ogbaframe.bin
   −
6. Run gbarunner2.nds. If you are running TWiLight Menu++/DSiMenu++/SRLoader, touch the GBA icon (DSi and 3DS themes), select the 3rd icon (R4 theme), or select GBARunner2 in the menu (Acekard theme).
+
# Concatenate the ".pal.bin", ".map.bin", and ".img.bin" files together
 +
cat gbaframe.pal.bin gbaframe.map.bin gbaframe.img.bin > gbaframe.bin
   −
With Commit a61e70e Version it is possible to load your save files. They should have the same name as the gba file but instead of .gba they should be .sav. The games need to be sram patched to recognise the sav files.
+
# Remove the unneeded files
 +
rm gbaframe.pal.bin gbaframe.map.bin gbaframe.img.bin
 +
</pre>
   −
(*) Do not use Normmatt's open-source GBA BIOS, as some patches are applied to the BIOS at hardcoded addresses. The MD5 of the BIOS you must use is A860E8C0B6D573D191E4EC7DB1B1E4F6. Use [http://www.winmd5.com/ WinMD5Free] to check the MD5.
+
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>
−
== Work in Progress ==
+
−
- Saving on SD card '''Although it is tested, there is no guarantee that it will work fine in all cases,
+
−
so use it at your own risk. A backup of your sd is recommend!'''
+
   −
== Not implemented yet ==
+
== Game Covers ==
−
- GUI.
+
   −
= Compiling the latest version =
+
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).
 +
 
 +
<syntaxhighlight lang='ini'>
 +
[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 ==
 +
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>
 +
* SHA1: <code>300c20df6731a33952ded8c436f7f186d25d3492</code>
 +
* SHA256: <code>fd2547724b505f487e6dcb29ec2ecff3af35a841a77ab2e85fd87350abd36570</code>
 +
 
 +
'''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>
 +
 
 +
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.
 
1. Make sure you have devkitpro installed.
 
3. Run make in the root.
 
3. Run make in the root.
   −
= Downloads =
+
== Downloads ==
 +
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 ===
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="max-width: 600px; overflow:auto;">
 +
 
 +
* 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].
 +
* Commit 5b06bb4 (2019/07/03), (Changed dma behavior on invalid addresses again, still not completely) posted [https://github.com/Gericom/GBARunner2/releases/tag/commit_5b06bb4bd12d8fe12574b0564e0ce0fb7fb02760 here].
 +
* Commit 03f8646 (2019/07/01), (Optimized the abort handler a little more) posted [https://github.com/Gericom/GBARunner2/releases/tag/commit_03f86467974caba8ae6c4463b5b5d42ad49ab826 here].
 +
* Commit e592198 (2019/07/01), (Set up CI with Azure Pipelines) posted [https://github.com/Gericom/GBARunner2/releases/tag/commit_e59219891e31d3d30b248b4c6a8bb9289b4d4b80 here].
 +
* [https://gbatemp.net/attachments/2019-06-30-897403a-zip.171803// Commit 897403a (2019/06/30) (master branch)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-82#post-8698213 here].
 +
* [https://gbatemp.net/attachments/gbarunner2-zip.171425// Commit 09c3fb7 (2019/06/26) (feature/newabort2 branch) (experimental arm7dldi_wramicache Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-80#post-8692494 here].
 +
* [https://gbatemp.net/attachments/gbarunner2-zip.171378// Commit 6084943 (2019/06/26) (feature/newabort2 branch) (experimental arm7dldi_wramicache Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-80#post-8691975 here].
 +
* [https://gbatemp.net/attachments/2019-06-14-8e4d520-zip.169862// Commit 8e4d520 (2019/06/14) (sd_save branch)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-77#post-8676640 here].
 +
* [https://gbatemp.net/attachments/2019-06-10-8175479-zip.169640// Commit 8175479 (2019/06/10) (sd_save branch)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-74 here].
 +
* [https://gbatemp.net/attachments/gbarunner2-zip.168926// Commit unspecified (2019/06/03) (sd_save branch)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-70 here].
 +
* [https://gbatemp.net/attachments/dd42c5c-02-06-2019-zip.168858// Commit dd42c5c (2019/06/02) (sd_save branch)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-69 here].
 +
* [https://gbatemp.net/attachments/gb_audio-d5d99e7-02-04-2019-zip.162672// Commit d5d99e7 (2019/04/02) (gb audio branch, no saving!)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-67 here].
 
* [https://gbatemp.net/attachments/gbarunner2_arm9dldi_wramicache-nds-zip.148184// Commit 6522414 (2018/11/01) (arm9wramicache Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-57#post-8359865 here].
 
* [https://gbatemp.net/attachments/gbarunner2_arm9dldi_wramicache-nds-zip.148184// Commit 6522414 (2018/11/01) (arm9wramicache Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-57#post-8359865 here].
−
* [https://gbatemp.net/attachments/gbarunner2_arm9dldi-nds-zip.148183/ Commit 6522414 (2018/11/01) (arm9Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-57#post-8359865 here].
+
* [https://gbatemp.net/attachments/gbarunner2_arm9dldi-nds-zip.148183/ Commit 6522414 (2018/11/01) (arm9 Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-57#post-8359865 here].
 
* [https://gbatemp.net/attachments/gbarunner2_arm7dldi_wramicache-nds-zip.148182// Commit 6522414 (2018/11/01) (arm7wramicache Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-57#post-8359865 here].
 
* [https://gbatemp.net/attachments/gbarunner2_arm7dldi_wramicache-nds-zip.148182// Commit 6522414 (2018/11/01) (arm7wramicache Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-57#post-8359865 here].
 
* [https://gbatemp.net/attachments/gbarunner2_arm7dldi-nds-zip.148181/ Commit 6522414 (2018/11/01) (arm7 Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-57 here].
 
* [https://gbatemp.net/attachments/gbarunner2_arm7dldi-nds-zip.148181/ Commit 6522414 (2018/11/01) (arm7 Version)], posted [https://gbatemp.net/threads/gbarunner2.451970/page-57 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].
 
* [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].
 
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"
 
{|width="25%" cellspacing="1" border="1px"
 
!Legend
 
!Legend
 
|-
 
|-
−
|align="center" style="background:#4CAF50"|Very Playable - Full Speed. Very Good Audio. No GFX Glitches.
+
|align="center" style="background:#4CAF50"|Very Playable - Full Speed. Very Good Audio. No gfx glitches.
 
|-
 
|-
−
|align="center" style="background:#B4EEB4"|Playable - Full Speed. Very Good Audio with a little Noise/stuttering. A Few GFX Glitches.
+
|align="center" style="background:#B4EEB4"|Playable - Full Speed. Good Audio with a little Noise/stuttering. Few gfx glitches. Gameboy Sounds are missing.
 
|-
 
|-
−
|align="center" style="background:#FFEB3B"|Playable - Minor Performance issues. Gameboy Sounds missing.
+
|align="center" style="background:#FFEB3B"|Playable - Minor Performance issues. Gameboy Sounds are missing.
 
|-
 
|-
 
|align="center" style="background:#FFB142"|Working/Unplayable - Game is very slow/laggy/glitched up.
 
|align="center" style="background:#FFB142"|Working/Unplayable - Game is very slow/laggy/glitched up.
 
|}
 
|}
    +
== Retail games ==