SkyEmu: a Game Boy Advance emulator aiming at cycle-accurate PPU timing

Accuracy first, and the GBA is where the work went

SkyEmu is described as a low level Game Boy, Game Boy Color, Game Boy Advance and DS emulator, whose primary focus is to preserve these systems for future generations while providing a good user experience through a good mixture of tradeoffs of accuracy, performance, features and usability.

That mixture is worth unpacking, because the feature list is where the priorities show.

The GBA section of the README is by far the longest. It claims a per pixel PPU implementation capable of both scan line and mid scan line effects, and notes that SkyEmu and NanoBoyAdvance are the only GBA emulators released to support this. It passes the AGS Aging Test ROM, with SkyEmu being the second software based GBA emulator to ever pass it. It can run difficult to emulate titles such as the NES Classics Series, Golden Sun and Hello Kitty Miracle Fashion Maker. It passes all ArmWrestler tests, all FuzzARM tests, and arm.gba and thumb.gba. And it passes all 2020 of 2020 GBA Suite timing tests when using the official GBA BIOS, which the README notes is something only one of the few emulators capable of passing can do.

The GB section is shorter and the claims are of a different kind. It passes all of Blargg's CPU instruction tests, the DMG and GBC acid2 PPU conformance tests, and MBCtest. The PPU is dot clock based, and the audio synthesis is anti-aliased with support for APU changes per sample, which the README says is what allows Pikachu's voice in Pokemon Yellow and Pokemon Pinball.

The two sections are not the same kind of claim. The GBA list is about a machine that is hard to emulate, and the GB list is about standard test ROMs. The README is candid about the gap: it states that the GBA emulation is significantly more accurate than the GB and GBC emulation, and that native builds are experimental currently.

Seven platforms, and a web build that is a real build

The build matrix is the widest thing about this project, and it is worth reading as a deliberate design choice rather than a list.

The badges at the top of the README point to Windows, macOS, Linux, FreeBSD, iOS and Android release archives, all built by GitHub Actions workflows named deploy_win, deploy_mac, deploy_linux, deploy_freebsd, deploy_ios and deploy_android. A seventh target is the web, with a deploy_web workflow, and the web build is hosted at web.skyemu.app.

The web build is not a thin client. The web app emulates everything locally on your machine using web assembly and javascript, so all files stay local to your machine like the regular native build, with the stated cost that there is a performance cost to performing the emulation inside a web browser.

The progressive web app point is the practical one. The latest version of the emulator can be played without installing at web.skyemu.app as a progressive web app, and on mobile platforms it is recommended to add this to the home screen and launch from there, which prevents the web browser from auto deleting save files and makes the app full screen.

That last point is a real constraint of running an emulator in a browser. Browser storage is evictable, and a save file that vanishes because the browser reclaimed it is a corrupted game. Launching from the home screen installs the app properly, and that advice is the author telling you the naive route loses data.

The repository supports Nix as well, with a default.nix, flake.nix and flake.lock, and there is a skyemu_libretro.info file, which is the metadata for the libretro core format, so the emulator can be used as a RetroArch core.

Save files, BIOS dumps and the naming convention you must follow

The file handling rules are strict, and they differ between the web and native builds in a way that catches people out.

On web builds, save files and the BIOS can be loaded by dragging them onto the page or loading them using the ROM file picker. The GBA BIOS must be named gba_bios.bin for the emulator to pick it up. Save files must be named the name of the rom file with the extension .sav, so for example if the ROM was MyRomFile.gba the save file must be called MyRomFile.sav.

On native builds the same naming convention still applies, but the save and BIOS files must be located in the same folder as the ROM file, instead of being dragged or loaded in the emulator itself.

The BIOS question has a nuance that matters for how the emulator feels. Platform BIOS and firmware files are not required as SkyEmu bundles open source replacement BIOS and stubs. However, it is strongly recommended to dump the official BIOS or firmware as the open source replacements lack many of the features of the native firmware, such as colorizing GB games and the startup splashes, and are not as accurate.

That is the honest trade. The bundled stubs mean the emulator runs with no setup and no proprietary dump, which is convenient and legally simpler. What you lose is the Game Boy colourisation that the real boot ROM performs on Game Boy games, the startup splashes, and some measure of accuracy. The accuracy claims in the README are themselves qualified on this point, since the GBA Suite timing result is stated as applying when utilizing the official GBA BIOS.

A reader should treat the two configurations as different products with different accuracy ceilings.

Features aimed at the person playing, not the person implementing

Beyond emulation accuracy, the feature list is weighted towards quality of life, and several entries are unusual for an emulator.

There are high quality upscaling shaders, color correction, and screen ghosting. There is game controller and rumble support with configurable keybinds. There are four persistent save state slots with screenshot preview. There is fastforward and rewind, and the README links a video about supporting very long rewind times. There is an Action Replay cheat code engine, and support for emulating the real time clock and the solar sensor, which matters for the games that use the clock.

The rewind feature is the one that changes the character of an emulator. A rewind buffer requires the emulator to keep a history of machine state, which is possible in a reimplementation because the author controls the hardware model, but it is not a feature of real hardware and it costs memory and performance. The trade-off the project accepts is visible in the README's own framing of a mixture of tradeoffs.

The debuggers are the other developer-facing group: CPU, MMIO, and Memory Debuggers, plus support for loading official BIOS and boot ROM dumps, and support for loading roms compressed in .zip archives.

And there is the HTTP control server, documented separately as a REST-like API for asynchronous scripting and other automation. A JSON API over HTTP that can drive an emulator is a considerably more powerful thing than a local GUI, because it means the emulator can be driven by a script, a test harness or a remote frontend.

Localization covers Armenian, Chinese, Danish, Dutch, English, German, Greek, Italian, Polish, and Russian.

Building it from source, and running a ROM from the command line

The native build instructions are four lines, and the README is upfront that native builds are experimental currently.

mkdir build
cd build
cmake ..
cmake --build .

The output binaries should be in the build/bin folder, and native builds support loading roms through the command line by specifying the path to the ROM as the first argument.

./SkyEmu path/to/rom.gba

That is the whole build story, which is a good sign for a C project with a CMakeLists.txt at the root, a src/ directory, a tools/ directory, and a docs/ directory. There is also a .gitlab-ci.yml alongside the .github/ directory, so the project runs CI in two places.

The docs/ directory holds the accuracy document linked from the features list, and the HTTP control server document. The repository also has ACKNOWLEDGMENTS.md, an AGENTS.md, a SkyEmu.entitlements file, which is the macOS code signing entitlement, and a flake for Nix.

The default controls are listed, which tells you the key mapping is a deliberate ergonomic choice rather than a default. WASD is the D-Pad, J is the A button, K is the B button, the apostrophe key is Select, Enter is Start, U is the L shoulder and I is the R shoulder. That places the action buttons under the right hand and the D-pad under the left, which is the layout most people default to. On mobile platforms an onscreen touch screen controller is provided.

The project also has an AI policy section, which states that all SkyEmu code has been written by humans.

What to expect when you run a game

The compatibility statement is measured in ROM counts rather than percentages, and it comes with a caveat that is easy to miss.

SkyEmu has been tested on 100s of ROMs and most common games should be playable with no to minor bugs currently.

That is a good result for a low level emulator, and the phrasing about no to minor bugs is a careful one. It means the games that do not work are not merely the obscure ones.

The DS support is the other place to calibrate expectations. The features list grades it as DS Emulation (Beta Quality), and the accuracy section does not give the DS a per-machine breakdown at all, which is itself a signal about where the confidence lies.

So the summary of what to expect: the GBA is the strong suit, with a per-pixel PPU and passing timing suites; the GB and GBC are solid on the standard conformance ROMs but less deep; the DS is beta.

For anyone evaluating the project as a codebase rather than as a player, the per-pixel PPU and the HTTP control API are the two pieces worth reading first. The first is the hard part of the project and the reason the accuracy claims exist. The second is what turns an emulator into something you can put behind a service.

Editorial conclusion

SkyEmu suits a developer who wants to read a clean, small C emulator with an accuracy-first design, or a player who wants the AGS aging test ROM to pass and wants the same build in a browser and on a phone. It is the wrong tool for a DS or GB game, because the README grades the DS build as beta quality and states the GBA emulation is significantly more accurate than the GB and GBC emulation. Before you rely on it, note that it bundles open source replacement BIOS stubs that lack features such as Game Boy colourising and startup splashes, and that the project asks for a dumped official BIOS for real accuracy, so a build without one is convenient but visibly different from hardware.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. skylersaleh/SkyEmu on GitHub