open_agb_firm is a bare metal interface for natively running GBA games and homebrew using the 3DS's built-in GBA hardware.
open_agb_firm is also a complete and better alternative to GBA VC injects (AGB_FIRM), allowing for:
Unlike AGB_FIRM open_agb_firm is not affected by the famous bug where the video output wraps around leaving garbled lines at the bottom of the screen. SD cluster size doesn't matter.
open_agb_firm is currently in beta. While open_agb_firm is relatively stable and safe to use, some quirks that have not been fixed. See Known Issues for more information.
Additionally, we are not responsible for any damage that may occur to your system as a direct or indirect result of you using open_agb_firm.
open_agb_firm.firm
file to your 3DS's SD card at /luma/payloads
if you're using Luma3DS or elsewhere if you're using fastboot3DS.3ds
folder to the root of your 3DS's SD card. Merge folders if asked..gba
ROM to run.A/B/L/R/START/SELECT - GBA buttons, respectively
SELECT+Y - Dump hardware frame output to /3ds/open_agb_firm/screenshots/YYYY_MM_DD_HH_MM_SS.bmp
X+UP/DOWN - Adjust screen brightness up or down by backlightSteps
units.
X+LEFT - Turn off LCD backlight.
X+RIGHT - Turn on LCD backlight.
Hold the X button while launching a game to skip applying patches (if present)
Hold the power button to turn off the 3DS.
Settings are stored in /3ds/open_agb_firm/config.ini
.
General settings.
u8 backlight
- Backlight brightness in luminance (cd/m²)
64
20
-117
16
-142
64
are recommended.u8 backlightSteps
- How much to adjust backlight brightness by
5
bool directBoot
- Skip GBA BIOS intro at game startup
false
bool useGbaDb
- Use gba_db.bin
to get save types
true
bool useSavesFolder
- Use /3ds/open_agb_firm/saves
for save files instead of the ROM directory
true
Video-related settings.
u8 scaler
- Video scaler. 0 = none, 1 = bilinear, 2 = hardware.
2
float gbaGamma
- GBA input gamma
2.2
float lcdGamma
- Output LCD gamma
1.54
float contrast
- Screen gain
1.0
float brightness
- Screen lift
0.0
string colorProfile
- Color correction profile. none
, gba
, nds
or nds_white
.
none
Audio settings.
u8 audioOut
- Audio output. 0 = auto, 1 = speakers, 2 = headphones.
0
s8 volume
- Audio volume. Values above 48 mean control via volume slider. Range -128 (muted) to -20 (100%). Avoid the range -19 to 48.
127
Input settings. Each entry allows one or multiple buttons. Buttons are separated by a ,
without spaces.
Allowed buttons are A B SELECT START RIGHT LEFT UP DOWN R L X Y TOUCH CP_RIGHT CP_LEFT CP_UP CP_DOWN
.
TOUCH reacts to all touchscreen presses. The CP in front is short for Circle-Pad.
Note that button mappings can cause input lag of up to 1 frame depending on when the game reads inputs. For this reason the default mapping of the Circle-Pad to D-Pad is no longer provided.
A
- Button map for the A button.
none
B
- Button map for the B button.
none
SELECT
- Button map for the SELECT button.
none
START
- Button map for the START button.
none
RIGHT
- Button map for the RIGHT button.
none
LEFT
- Button map for the LEFT button.
none
UP
- Button map for the UP button.
none
DOWN
- Button map for the DOWN button.
none
R
- Button map for the R button.
none
L
- Button map for the L button.
none
Example:
[input]
RIGHT=RIGHT,CP_RIGHT
LEFT=LEFT,CP_LEFT
UP=UP,CP_UP
DOWN=DOWN,CP_DOWN
Game-specific settings. Only intended to be used in the per-game settings (romName.ini in /3ds/open_agb_firm/saves
).
u8 saveSlot
- Savegame slot (0-9)
0
u8 saveType
- Override to use a specific save type, see values for defaultSave
(0-15, 255)
255
(disabled)Options for advanced users. No pun intended.
bool saveOverride
- Open save type override menu after selecting a game
false
u16 defaultSave
- Change save type default when save type is not in gba_db.bin
and cannot be autodetected
14
(SRAM 256k)0
, 1
: EEPROM 8k2
, 3
: EEPROM 64k4
, 6
, 8
: Flash 512k RTC5
, 7
, 9
: Flash 512k10
, 12
: Flash 1m RTC11
, 13
: Flash 1m14
: SRAM 256k15
: Noneopen_agb_firm supports automatically applying IPS and UPS patches. To use a patch, rename the patch file to match the ROM file name (without the extension).
example.gba
, rename the patch file to example.ips
This section is reserved for a listing of known issues. At present only this remains:
If you happen to stumble over another bug, please open an issue or contact profi200 via other platforms.
open_agb_firm using the 3DS's built-in GBA hardware. Unfortunately, this comes with limitations compared to GBA emulators. This is a list of limitations we can't solve in software or are very hard to work around.
Most emulators output EEPROM saves differently than what open_agb_firm expects, making them incompatible. Fortunately, they are very easy to fix, using this tool by exelotl.
The tool also works vise versa, if you want to use a save generated by open_agb_firm with an emulator.
Q: Why isn't open_agb_firm a normal 3DS app?\ A: To access the 3DS's GBA hardware, open_agb_firm needs to run with full hardware access, which can only be provided by running as a FIRM.
Q: Is this safe to use?\ A: Of course! While open_agb_firm does run with full hardware access, a lot of work has been put in by several people to ensure that nothing unexpected happens. Some backend code from open_agb_firm is actually used in fastboot3ds!
Q: What games work with open_agb_firm?\ A: In theory, all of them, except those that fall within the hardware limitations.
Q: How can I increase the brightness?\
A: Increase the value of the backlight
setting in config.ini
. See Configuration for more information.
Q: Why do the colors look off?\
A: The default gamma settings are intended to make up for the washed out colors the 3DS LCD has. If they look weird to you, setting the outGamma
setting to 2.2
might help.
Q: Why do some of my ROM hacks/homebrew games have saving issues?\
A: open_agb_firm resorts to save autodetection when it can't find an entry for the game it's running in gba_db.bin
(which only contains data for official games), and it's a bit wonky for games that use EEPROM or misleading SDK save strings.
Q: Why doesn't my save file from an emulator work?\ A: There's a good chance that the save you're having issues with is an EEPROM save, which most emulators output differently. See EEPROM Fixer.
Q: My game doesn't save properly!\
A: First, please ensure that the GBA ROM you are playing is not modified in any way, and matches its No-Intro checksums. Second, make sure you aren't using an existing .SAV
file, because some may have issues for various reasons. Third, make sure your gba_db.bin
is up-to-date. If everything seems to be in order but the game still doesn't save properly, please open an issue so it can be fixed. In the meantime, the useGbaDb
and saveOverride
settings may be useful (see Configuration for more information).
If you want to test the latest changes you have 2 download options. The first is recommended.
With GitHub account\
Log into your account, go to the Actions tab at the top, click on the first entry and download the file under Artifacts
(open_agb_firm_nightly
).
Without GitHub account\ nightly.link is a thirdparty site to make builds available to everyone. I'm not affiliated with nightly.link or their developers and neither are they with GitHub. Use at your own risk.\ https://nightly.link/profi200/open_agb_firm/workflows/c-cpp/master/open_agb_firm_nightly.zip
To compile open_agb_firm, the following needs to be installed:
Additionally, p7zip
(or if available, p7zip-full
) needs to be installed to make release builds. Also, make sure that the dma330as
and firm_builder
/firmtool
binaries are in the PATH environment variable and accessible to the Makefile.
Clone this repository using git clone --recurse-submodules https://github.com/profi200/open_agb_firm
and update via git pull && git submodule update --init --recursive
.
Build open_agb_firm as a debug build via make
, or as a release build via make release
.
You may use this under the terms of the GNU General Public License GPL v3 or the terms of any later revisions of the GPL. Refer to the provided LICENSE.txt
file for further information.
Copyright (C) 2024 derrek, profi200, d0k3