ScarletNX

Wimsy, the ScarletNX mascot

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 translation layer for 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. Setup device 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. The NX executable is also installed as scarletnx-switch, and on Linux and macOS as scarletnx-3ds and scarletnx-gnuabi, the one program running the driver its name says.

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 CIA menu entry support decrypted application CIA extraction (scarletnx-3ds -x game.cia) 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

• yuzu, Suyu, Torzu, Ryujinx, Ryubing (Ryujinx's continuation), Citron and Eden.
• Atmosphère
• LibHac.
• MZ Labs for SwitchRecomp, which we started from. Its code has since been replaced by our own.
• NeXium for research and development.
• Switchbrew for research.
• Azahar and Citra, for all of the 3DS emulation.
• Vita3K, for the PS Vita's GXM and shader translation, and vita-headers for its NIDs.

Wimsy, the mascot and the runtime's icon (dist/wimsy.svg) was drawn by Liz.