ScarletNX
Discord: https://discord.gg/tRTRXXbyjp (my god why don't we just use IRC like good people?)
A GPLv3 static ARM64 to x86 recompiler with a Switch, GBA and GNU/Linux ABI translation layer for Solaris, Linux, Windows, FreeBSD and Android.
Quick start
Each push to main that builds everywhere becomes a nightly in scarletnx/nightly, the newest 30
kept, with each open pull request's builds. The latest:
ScarletNX-linux-x86_64.AppImage and
ScarletNX-linux-aarch64.AppImage for Linux (chmod +x it first;
ScarletNX-linux-ppc64le.AppImage,
ScarletNX-linux-riscv64.AppImage and
ScarletNX-linux-loongarch64.AppImage are
cross-built for PowerPC64 LE, RISC-V and LoongArch, when their jobs built.
ScarletNX-linux-ppc64.AppImage, for
PowerPC64 BE, not yet run on a big-endian machine),
ScarletNX-windows-x86_64.zip for Windows (run bin\scarletnx.exe)
and ScarletNX-android-universal.apk (Android).
Games need a Vulkan 1.3 driver.
Keys and games must be dumped from your own console. Started with no arguments, the program opens the
launcher. Install Keys installs your prod.keys. For NSPs, also put title.keys in
~/.switch (%USERPROFILE%\.switch on Windows). Load Switch NSP/XCI/NRO then picks a dump, extracts and
recompiles it and starts the game, which the Games tab lists from then on. See Usage for the
command line and Folders for where games, saves and settings go.
The shared ARM64 recompiler lives under src/common/. Switch Horizon HLE
and Maxwell graphics live under src/nx/. The CPU-only Linux AArch64 runtime lives
under src/gnuabi/ and builds without the Switch graphics or media dependencies:
cmake -S . -B build/gnuabi -DSNX_BUILD_NX=OFF
cmake --build build/gnuabi
build/gnuabi/scarletnx-gnuabi -L /path/to/aarch64-sysroot ./test_aarch64
It runs static and dynamically linked programs, which start other processes, talk
through pipes and read and write files through a sysroot, as QEMU's -L gives one
(linux/ of the data folder by default). See Linux ABI execution and QEMU validation
for the sysroot, the JIT and AOT modes, supported syscalls, and current limits. Every driver a build has is part
of one program, scarletnx, which runs the driver its name says. On Linux and macOS scarletnx-switch,
scarletnx-3ds, scarletnx-vita, scarletnx-gnuabi and scarletnx-agb are links to it. On Windows, which has no
links, the driver's name goes first instead (scarletnx.exe scarletnx-3ds Game.cia), as the launcher runs them.
Game Boy Advance ROMs run under the scarletnx-agb system type,
on the emulated AGB board being built under src/agb/ (licensed under MPL-2.0), see AGB board.
The recompiler is also a library on its own, libscarletnx-recompiler: a program hands
it ARM64 or AArch32 code in memory and runs the result in its own process with its own
SVC handler, with no Switch runtime behind it. See
The recompiler as a library.
Install the build tools first. On Debian/Ubuntu:
sudo apt update
sudo apt install build-essential git cmake ninja-build clang llvm-dev nasm pkg-config \
libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxfixes-dev libxss-dev libxtst-dev \
libasound2-dev libpulse-dev libpipewire-0.3-dev
If your distribution provides libsdl3-dev, install it too. Otherwise CMake builds a pinned SDL3
using the X11 and audio development packages above. SDL2 is not a substitute for SDL3. You also
need a Vulkan 1.3 driver to run games. See Build prerequisites for
Wayland, other systems, and the SDL3 troubleshooting steps.
Then build:
git clone --depth=1 https://github.com/scarletnx/ScarletNX
cd ScarletNX
cmake --preset default -B build && cmake --build build
For encrypted dumps, put prod.keys (and title.keys, for NSPs) in ~/.switch, or pass them with
--keys and --title-keys. Decrypted DNSP/DXCI content needs no keys.
./build/scarletnx "Game.xci" # extract, recompile, then play (also accepts NSP, DNSP and DXCI)
Run the same command again after an interruption. Completed extraction and recompilation are skipped,
but the game always starts anew. The driver keeps games, extractions and keys in its data folder,
~/.local/share/scarletnx on Linux (Folders). To run the steps separately, here in
folders of the current one:
./build/scarletnx -x "Game.xci" --out work/Game # -> work/Game/{exefs,romfs}
./build/scarletnx -r work/Game Game --outdir games # -> games/Game/Game
./build/scarletnx -rx "Game.xci" # prepare without playing (UNIX)
./build/scarletnx -Hs "Game.xci" # headless, wait for GDB (UNIX)
cd games/Game && ./Game
For an SDL3 menu, run ./build/scarletnx with no arguments. Select a driver with arrow keys and
Enter or hover and click, then choose drag-and-drop or the paginated games/ browser.
The GUI shows live driver/game
output and combined CPU/RAM usage. See GUI launcher.
The experimental scarletnx-3ds driver and Load 3DS game menu entry support
encrypted or decrypted application CIAs (scarletnx-3ds -x game.cia), cartridge
images (game.cci, game.3ds), bare NCCHs (game.cxi), a bundle or a z3ds
compressed game of any of them, an update partition
played as the update, and an independent
page-based memory controller. It runs the extracted titles through an experimental
extract -> offline AOT -> native run pipeline on 64-bit Linux and Windows, using an
explicit ARM11/checked-memory profile without changing shared A57 defaults.
The homebrew SuperTux draws its title and loading screens with a software port of
Azahar's PICA pipeline and plays its music through a port of Azahar's HLE DSP.
It is not playable yet: there is no input, the bottom screen is not shown, and parts of the OS are missing.
See the 3DS port for limits, build instructions and the parity roadmap.
The experimental scarletnx-vita driver and Load Vita VPK menu entry run PS Vita homebrew VPKs through the same
extract -> offline AOT -> native run pipeline, compiling code it missed at run time. It draws sceGxm's scenes
on Vulkan with a port of Vita3K's shader translator. The Lua Vita Tester draws its screen, reads input and plays sound.
See the Vita driver for what it covers.
For more detailed information please see: Build + run. For the Android app (arm64 and x86_64),
see Android. macOS and iOS build in CI. An iPhone prepares and runs a game by itself, and no game
runs on macOS yet: see macOS and iOS. Every document: docs.
Special thanks
Wimsy, the mascot and the runtime's icon (dist/wimsy.svg) was drawn by Liz.
