S2Arm Puts the Emulator in the Build

Instead of interpreting a Switch game at runtime, S2Arm rewrites its ARM64 code ahead of time and runs it natively on an iPhone, iPad, or Mac. The hard translation happens once, before you press play.

Apache-2.0 · ~11 min read • View on GitHub • More from jhaizhou-ops

A wide editorial illustration in black ink on white: a long wooden workbench read left to right. On the left an opened game cartridge spills a ribbon of tiny instruction glyphs across the bench. The ribbon feeds through a large metal lathe in the center whose gears and cutting tools reshape it. On the right the ribbon emerges as a single smoothly machined part that slots directly into a thin phone, with no adapter between them.
The thesis in one image: raw guest instructions go into a build-time lathe and come out as a native part that fits the phone directly. The missing adapter is the missing interpreter.
Key Takeaways

The Emulator Is the Build

A conventional Switch emulator pays for translation on every frame, forever. It fetches a guest instruction, decodes it, dispatches it, and repeats. That interpreter loop is the cost of admission, and it sits between the game and the CPU on every draw call and every physics tick for as long as the app runs.

S2Arm does not emulate. It pays the translation cost once, at build time. The game's ARM64 code is rewritten ahead of time into native code that the host CPU executes directly. What ships to the device is a native app with no interpreter in the loop. The performance shape of the whole program changes when you remove that layer, because the steady-state work stops including a per-instruction tax.

The game's own ARM64 code is rewritten at build time and then runs directly on the processor in your iPhone, iPad or Mac.

S2Arm project, Project README · jhaizhou-ops/S2Arm on GitHub

That single decision is the project. Everything else in the repository, the launchers, the shared iOS library, the per-game Android APK, the automation surface, is downstream of choosing to translate at build time instead of at runtime.

Where the Work Goes

If the interpreter is gone, the translation has to live somewhere else. S2Arm splits it into three tracks. First, guest ARM64 instructions are rewritten into native code before the app is ever launched. Second, graphics calls that the game makes through NVN, Nintendo's graphics API, are translated to Metal on Apple platforms and to Vulkan on Android. Third, system services that a game would normally ask the guest operating system for are answered by a native host instead.

Three translation tracks, all resolved before launch: CPU code rewritten to native, NVN graphics mapped to Metal or Vulkan, and system services handled by a native host.

The repository layout mirrors this split. The shared NVN frontend lives in graphics/nvn/gfx/nvn/, with a Metal backend in nvn_mtl.m and a Ryujinx-derived Vulkan backend under graphics/vulkan/. The ARM64 rewriter sits in runtime/. C# services, built with NativeAOT, live in cs/. The Android host code is mostly C and Java under android/.

One build file makes the split concrete. android/CMakeLists.txt builds a single native library and refuses to accept an old backend value, failing the build with a message instead of silently falling back. That is the project's stated rule applied to build configuration: report red, do not fall back.

The Repo That Writes Itself

The second surprise is who the repository is written for. Two files, AGENTS.md and android/AGENTS.md, are written as instructions to AI coding agents. They read less like a style guide and more like operating law, and they encode rules that look like guardrails written after recurring failures.

A close-up editorial illustration in black ink on white: a drafting table viewed from above. Three slender mechanical drafting pens on articulated metal arms draw code across a blueprint. A single human hand enters from the right holding a rubber stamp shaped like a gate, poised over the finished sheet.
Agents draft the code; a human holds the gate. The AGENTS.md files set the rules the assistants work inside, and the merge stamp stays in a person's hand.

The rules are specific. Never push to main. Keep branches short, one PR equals one thing, aim to merge in hours. If main turns red, fix main first. Do not hard-code game addresses or intercept guest SDK functions by name. Unimplemented services must report red rather than return a success fallback. Performance changes must bring numbers, with power readings taken over at least three runs and the median reported, plus the thermal state and charging state recorded.

The Android file adds a layering model, sorting code into shared, should-be-shared-but-currently-duplicated, and platform-specific buckets. It then draws a hard scope line: Android only does direct paths, and the generic Ryujinx-based backend is not to be fixed for Android. That is a deliberate tradeoff, and it sits in tension with the goal of avoiding forks.

The tooling matches the governance. The s2armctl CLI is built to be driven by an AI assistant, and the README says an assistant can use it to import, build, install, track progress, and inspect errors. The people set the gates; the agents do the drafting.

A .so That Is Not a .so

One file in the Android build proves how deep the engineering runs. The capability-probe helper is a standalone executable, but it ships inside the APK under the name libs2a_capprobe.so. It is not a shared library. It is a binary wearing a disguise.

The reason is mechanical. The Android Gradle Plugin packages only CMake SHARED targets into the APK, so an executable has to be smuggled in through the jniLibs source directory to get placed under lib/<abi>/. The build keeps it uncompressed and 16 KB page-aligned, then launches it without a direct exec. Instead the native code calls posix_spawn on the system dynamic linker, linker64, and passes the in-APK path as the first argument.

The build comment records exactly why. An executable placed in the app's private files/ directory was blocked from exec once targetSdk reached 29, and a device reading showed exit:127. The workaround is documented at the level of the failing exit code, which is the kind of detail that tells you the team hit the wall and measured it rather than guessing.

Not an Emulator, Not a Port

S2Arm is not alone in this space, and it is not the same shape as the projects around it. The field splits into conventional emulators, which keep the interpreter loop, and game-specific recompilation scripts, which rewrite one title at a time. S2Arm's bet is a general, packaged build-and-install pipeline, especially for iPhone and iPad, plus an automation surface for agents.

S2ArmConventional emulator (Ryujinx-style)Game-specific recomp project
Execution modelBuild-time rewrite to nativeRuntime interpretationPer-game rewrite
Where translation happensOnce, at buildEvery framePer-game build script
Graphics pathNVN to Metal or VulkanRuntime shader translationGame-specific path
Target platformsiPhone/iPad/Mac, Android arm64, Windows launcherDesktopSingle OS
ScopeGeneral supported-game workflowFull libraryOne title
What the user suppliesOwn games and keysOwn games and keysOwn games and keys
DistributionLauncher + single-app library + per-game APKEmulator binaryScript

The lineage is worth naming because it explains the parts. S2Arm credits nxnative for the direct graphics path to Metal, Ryujinx for system services and shader translation, and d2r-mobile for pioneering the broader technical direction. The newer game-specific projects around it are mostly parallel efforts, not descendants.

What It Refuses to Promise

The honest counterweight matters as much as the pitch. Support is narrow. Only 64-bit AArch64 games are in scope. There is no 32-bit ARM support, and no support for games that need a 36-bit address space. You bring your own games and keys. The project ships neither, and it is not affiliated with or endorsed by Nintendo.

The numbers are project-reported. The README describes a survey of 211 games with a 95% first-try build success rate, plus thousands of device-test runs, but none of that is independently verified. Treat it as a claim with a source, not a benchmark.

There is also a branding problem the project flagged itself. A separate site is using the S2Arm name, and the README warns that it is unaffiliated and solicits donations.

S2Arm is free and open source. We never accept donations and have no commercial offering; anyone collecting money in the name of S2Arm has nothing to do with us.

S2Arm project, Project README · jhaizhou-ops/S2Arm on GitHub

That is the shape of the project: a real technical bet, a genuinely unusual development process, and a set of limits it states plainly rather than burying. It does not claim to be a universal Switch. It claims to move the emulator into the build, and it does.

Your own Switch games, running natively on iPhone, iPad and Mac.

S2Arm project, Project README · jhaizhou-ops/S2Arm on GitHub