Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.
Building from source
The launcher (see the README) runs the same scripts a terminal does. This page is the by-hand route, for advanced users, for development, or when the launcher is not an option: the tools, your prod.keys, and the IPA built from a terminal. Contributing rules are in CONTRIBUTING.md.
Get the tools
This is the command-line route the launcher drives for you. The build is upstream's. Follow upstream's README to install Xcode, Homebrew tools and the Python packages, then pack an IPA.
git clone https://github.com/<you>/NX2Apple.git
cd NX2Apple
python3 tools/engine.py sync # the engine (nxnative at the pin plus our patches) into engine/, about 80 MB
brew bundle --file=Brewfile # xcodegen, zstd, spirv-cross, glslang (the NSP script checks for it), .NET SDK
python3 -m venv .venv # Homebrew's Python refuses global pip installs (PEP 668)
.venv/bin/python -m pip install lz4 capstone fonttools zbic nsz "backports.zstd; python_version < '3.14'"
source .venv/bin/activate # so that python3 below is the venv's (in each new terminal)
What you need on disk
Three things, none of which ship with the repository:
| What | Where it comes from | Used by |
|---|---|---|
prod.keys |
dumped from your own console (see below) | the extractor, to decrypt your game |
| The game's NSPs | dumped from your own cartridge or eShop purchases | the extractor |
| Xcode + iOS SDK | the App Store | the app build |
prod.keys is the console's key set — a text file of name = hex value lines (~230 entries:
master_key_xx, titlekek_xx, header_key, key_area_key_application_xx, …). Every Switch
homebrew tool reads this format. It is not tied to a specific game: one prod.keys decrypts
any of your games. The only requirement is that the file contains keys for the key generation
(firmware era) the game was packaged with — a current dump covers every retail game.
Where to put it is up to you. You pass the path with -k:
# any layout works, e.g.
~/keys/prod.keys
# or keep it beside the game's NSPs
~/Games/Hades2/prod.keys
python3 engine/scripts/build_ipa_from_nsp.py ~/Games/Hades2 -k ~/keys/prod.keys
How keys are dumped is documented across the Switch homebrew community (Lockpick_RCM from a hacked console is the usual route). This repository does not cover that step and ships none of it. Two practical notes from real dumps:
- Malformed lines. Some dumpers emit lines whose hex value has the wrong length (33 bad
master_kek_source_*lines in one real dump), which makes the extraction tool refuse the whole file. Delete the offending lines and keep a backup of the original. - Updates. An update NSP's ticket may carry a newer key generation than the base game's. The
extractor reads the title key straight from the common ticket inside each NSP, so in practice
both decrypt fine as long as
prod.keysis reasonably current — verified here with a base game on generation 15 and its update on 16, using a keys file that only reached 15.
backports.zstd is needed for Tears of the Kingdom's zstd dictionaries. Other games do not use it.
The experimental builder (nxbuild)
nxbuild is a build tool in Rust. It makes the same files as the build script, faster. It is off by default. The Mac launcher has the setting "Use experimental builder" (Settings, Build tools). With it on, the launcher starts one program, nxb build, and does not run the build script at all:
NXB_ENGINE=engine nxb build <NSP folder> --platform mac-app -k <prod.keys> --title-id <title ID> \
-o <app> --work-dir <build folder> --engine engine --progress json
- The program is the
nxbbinary the player chose in Settings (the binary, or the folder that holds it), else the copy inside the app, whichfrontend/nxbuild.pinnames. It needs nxb 0.6.2 or newer: the launcher readsnxb versionfirst and stops with a message when the nxb is older. - The command line is the script's own: the launcher builds the arguments it gives the script (input folder,
.nupfile or dump folder,-k,--work-dir,--platform,-o,--shell-framework,--team-id,--romfs,--env-file) and runsnxb buildwith them, so the same cases reach nxb. DLC, NSZ, XCI and merged packages in the folder are found by nxb itself. A game with no profile is surveyed by nxb, and the launcher does not pass--no-heap-check, as it does not for the script, so nxb stops with exit code 4 and names the step it cannot do yet. --progress jsonprints one JSON event per line (stage,step,progress,stage_end,say, each withcodeandseverity). The launcher shows them as its own stages and writes every line to the build log.- There is no fallback. A failure, or a game or step nxb does not take, shows nxb's exit code in words and its last error line. The exit codes are 0 done, 1 error, 2 bad arguments, 3 damaged data, 4 not supported yet, 6 missing key and 130 interrupted. Turning the setting off builds with the script again.
Build the IPA
The main build script packs a slim IPA by default (no RomFS inside, as the app reads the game's data from its folder on the device, Documents/games/<id>/), so the build above already produced it. To re-pack just the package later:
GAME=<title id> W=<work dir> PATCHED=<patched dir> \
ROMFS=<RomFS dir> MSL_IOS=<shader dir> \
engine/dm/ios/tools/build_ipa.sh <output.ipa>
--full-romfs (or DM_FULL_ROMFS=1) packs the RomFS into the package instead — upstream's
behaviour, only sensible for small games.
The RomFS no longer has to be packed into a shard archive: the build writes the game's data as a single romfs.img. Shard archives made earlier (romfs.idx with romfs.00, romfs.01, …) are no longer read; the launcher reports such a folder as having no game data, and the data is sent again once as a romfs.img.