Getting started with GBAx

This guide takes you from a downloaded GBAx package to a game you can launch, control and save. The desktop app combines a local game library with an mGBA-derived emulator. The website’s browser player is a separate option; installing the desktop app does not automatically move its library or saves into the browser.

For your first session, use one game file you can identify easily. A small, known starting point makes it much easier to confirm that installation, scanning, controls and saving are all working before adding a large collection.

Choose the package for your computer

Open the Downloads page and read the release name, channel and requirements before selecting a file. Preview 1 has four native packages: Windows x64, Linux x86_64, macOS Apple Silicon and macOS Intel. “Preview” means it is a testing release; keep your existing saves and a working setup while you evaluate it.

Keep all Windows DLLs and resource folders alongside the executable. On Linux, a system without FUSE can launch the AppImage with APPIMAGE_EXTRACT_AND_RUN=1. The Mac preview packages are ad-hoc signed test builds, not Developer ID signed or notarized, so macOS may display a warning or block them. Those are package-specific details, not symptoms of a missing game file.

Desktop packages contain the application and its dependencies, not games or Nintendo BIOS files. You do not need to compile the source to use a ready-to-run package.

Prepare a simple library folder

Create or choose a normal user folder for your game collection. Keep it separate from the extracted application, a mounted DMG or a temporary download directory. A stable location makes scans and backups easier and avoids confusing an application update with a change to your games.

For the first test, place one recognised game file in that folder. The desktop release includes GBA, GB and GBC support and ZIP/7z loading. If an archive causes trouble, test the game file outside the archive to separate an extraction problem from an emulation problem.

Add the folder to GBAx

1. Open Settings in the launcher.
2. Under Library, choose Choose ROM Folder and select your collection folder.
3. Enable Scan subfolders automatically if your games are organised in nested folders.
4. Select Scan Library, then return to Installed.
5. Search for your test game and open it.

The expected result is an installed-library entry that points to your local file. The broader Browse Games catalogue and the Installed list serve different purposes: seeing a title in a catalogue does not by itself establish that a playable local file is linked to it.

If the entry is missing, check the selected folder and subfolder option before changing emulation settings. If the entry appears but launch fails, note the exact error and test that file directly. Those two symptoms lead to different investigations.

Let artwork finish in the background

GBAx can download missing covers and prepare thumbnails while you browse. An entry without artwork is not necessarily an unplayable game. Give the artwork queue time to complete, then use Download Missing Artwork in Settings if needed.

The artwork cache is separate from the game files. The settings screen includes Open Artwork Folder for inspecting it. A cover mismatch should be investigated as a metadata/artwork issue before renaming or replacing a working game file.

Confirm controls before settling into a game

Open Settings → Open Emulator Settings to inspect the running emulator’s input configuration. Test directions, A, B, Start, Select and the shoulder buttons. If you use a controller, confirm both launcher navigation and in-game input: they are separate contexts.

Open the quick menu and return to the game once. Also test fullscreen and returning to the launcher. These small checks make it easier to notice a focus or mapping issue before you have a long unsaved session. The controller guide explains the supplied launcher shortcuts.

Make and verify your first save

Use the game’s own save command when you reach a suitable point. Exit normally, reopen the game and confirm that its Continue or Load option finds the expected progress. This tests persistence across a real restart.

You can then try a save state through the quick menu. A state is a snapshot of the emulator, while the normal save is data written by the game. Keep both concepts separate and preserve a backup before moving between builds. See Saves, states & backups for the full workflow.

Adjust appearance after the basics work

Once launch, controls and saving are confirmed, choose your preferred launcher accent and presentation settings. Performance Mode reduces launcher blur and heavier visual effects; it does not change the emulated GBA’s instruction set or automatically repair a game-compatibility issue.

If a problem appears, change one setting at a time and repeat the same test. Keep the build name, operating system and game revision with your notes. The troubleshooting guide helps identify whether the issue belongs to installation, the library, input, emulation or the browser player.