🎮 NX2Apple

Your Switch games, running on your iPhone.

Not an emulator. No terminal. A macOS app does the whole build in a few clicks.

New in v0.4.5

• 🖥️ Mac app output — build a double-clickable .app instead of an IPA
• 📱 Older iPhones and iPads — turn on BC texture decoding when building

A macOS app takes your own game dumps and does the whole thing with a few clicks — unpack, rewrite the game's code for Apple silicon, translate its shaders to Metal, pack a slim IPA plus a sharded RomFS archive that a phone can actually install (even a 16 GB game), and then tells you the three steps to get it onto the device.

中文用户请看这里：简体中文 README

Formerly nxnative-romfs-archive — old links redirect here.

This is a community fork of nxnative — the NSO rewriter, the Horizon host, the NVN-on-Metal layer and the per-game profiles are upstream work, and this fork follows upstream automatically. What it adds:

• 🖱️ A GUI app for everyone. nxnative for Mac is a game library and a build tool in one window: pick a game's folder, choose This Mac or iPhone / iPad, and the build runs with live progress from the script's own counts. Finished Mac games appear in the library with their eShop key art, start with Play, and keep per-game launch options (the iPhone launcher's settings: frame rate, console mode, upscaling, …). Device dependencies are detected and installed with one click; English or Chinese, following the system. It also downloads the repository for you and updates itself — no git knowledge needed.
• 📦 A RomFS archive. Tears of the Kingdom's 304,243 files become 127 shards — the difference between an iOS install that fails with PackageExtractionFailed and one that works (details below).
• ⏸️ Interrupted builds resume. Extraction, DLC, module rewrite and shader compilation are kept and reused: a failed or stopped build continues where it left off, and a rebuild after a tweak reuses everything unchanged (upstream's pipeline; the app drives it with its own build folder).
• 🔄 Follows upstream automatically. A daily GitHub Actions job re-applies the fork's features onto upstream's tree, verifies the result (script parse, archive reader test, a macOS host build) and pushes — or opens an issue with the log when a patch no longer fits.
• 🎯 79 game profiles with the required update version listed per game. Three are verified end to end on this fork; 45 are reported playable on an iPhone upstream.

• ✨ Features at a glance
• 🚀 Quick start
• 🎮 Supported games
• 🔧 How it works
• 📝 Update history
• 🤝 Contributing shaders and game support
• ⚠️ Limitations
• 🙏 Credits
• ⚖️ Legal

1. Download the app — latest release (NS-Port-Builder-macOS-arm64.zip). Unzip, right-click → Open the first time.
2. Let it fetch the project — the repository group has a Download repository button (a shallow clone into ~/NX2Apple). Slow GitHub? The panel shows the manual ZIP route.
3. Pick your game files — base game, update, DLC and prod.keys, separately or as one folder.
4. Press build, then follow the three install steps it prints.

Requirements: an Apple Silicon Mac on macOS 13+, Xcode with the iOS SDK, Python 3.9+, .NET SDK 10. The app's dependency panel detects each of these and installs what it can. Your own game files and prod.keys — nothing is bundled.

3 verified end to end on this fork (build → install → play on a real iPhone), 29 reported playable upstream, 58 profiles in total. The full table with the exact update version each game needs is below.

frontend/ is a macOS app that does steps 2–5 below with a window instead of a terminal, for people who would rather not read a build log: four inputs picked separately (base game, update, DLC, prod.keys), a dependency panel that detects and installs what is missing, the script's real stage list with live percentages, and the archive shards produced at the end.

romfs.idx        28 MB   header, name pool, file table, directory table
romfs.00 ... .125        126 shards, 200 MiB each, source bytes verbatim

frontend/ is a macOS app that does the build steps with a window instead of a terminal, for people who would rather not read a build log: a library of your games with their key art, a build page (one game folder, or base game, update, DLC and prod.keys picked separately; Mac or iPhone), the script's real stage list with live counts and time left, per-game launch options for Mac builds, and a settings page that detects and installs what is missing.

cd frontend && swift run          # or double-click frontend/nxnative.app

The interface is bilingual: it follows the system language (Chinese for any Chinese variant, English for everything else).

It runs the same scripts the command line does, so everything below still applies; see frontend/README.md. The prebuilt app, and the release notes in English and Chinese (including which games are verified), are on the releases page and in docs/RELEASE_NOTES.md.

Newest first. The fork follows upstream daily, so its game list and host fixes arrive automatically.

Each new game needs its own bring-up: a profile (build IDs, memory layout, texture slots), a shader reader if it packs them in a form we do not read, and patch points. Two ways to help, both useful:

• Report a game that works — if you got a title outside the verified list running, open an issue with the title ID, the update version, and what you did. It becomes a profile others can use.
• Send the shaders that are missing — if a game runs but stutters on first use of an effect, its shader variants are missing from the map. The host can dump what it cannot find (DM_NVN_SHDUMP=<dir>); attach those and we add them to shader_map.tsv for everyone.

Issues with a full Documents/log.txt get looked at first — that log usually names the exact missing piece.

A scheduled GitHub Actions workflow (.github/workflows/sync-upstream.yml, daily 21:30 UTC, also runnable by hand) follows seedds/nxnative: it re-applies this fork's features onto upstream's tree through scripts/sync_upstream.py, verifies the result (Python 3.9 parse of every script, bash -n, the archive reader test, a macOS host build) and pushes — or opens an issue with the log when a patch no longer fits, pushing nothing. The repo is a fresh repository rather than a true fork, so GitHub's own "Sync fork" does not apply here; the last synced upstream commit lives in .upstream-ref.

The archive feature does not change the normal build. 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
brew install xcodegen zstd spirv-cross
brew install --cask dotnet-sdk
python3 -m pip install lz4 capstone fonttools backports.zstd

Three things, none of which ship with the repository:

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 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.keys is 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.

python3 dm/tools/romfs_arc.py pack <RomFS dir> <output base> --shard-mib 200

<RomFS dir> is the directory nx_extract wrote (the one holding Pack/, Banc/, Sound/, …). The tool writes <base>.idx and <base>.00, <base>.01, … Files are grouped by top-level directory and cut so no shard passes --shard-mib, so one shard holds one kind of content.

Check the result before copying anything:

python3 dm/tools/romfs_arc.py verify <base> <RomFS dir>   # byte-compares every file
python3 dm/tools/romfs_arc.py list   <base> [path]        # list one directory

The main build script packs a slim IPA by default (no RomFS inside; the app reads the game files from Documents/romfs), so step 1 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> \
  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.

Put the whole set in the app's Documents/romfs/, keeping the base name:

Documents/romfs/romfs.idx
Documents/romfs/romfs.00
...
Documents/romfs/romfs.125

The app looks for romfs.idx first (dm/ios/Sources/main.m, romfs_locate). A plain directory tree is still accepted when there is no index, so nothing changes for existing games.

The index may sit at any of these places; the reader tries them in order:

<DM_ROMFS>.idx
<DM_ROMFS>/romfs.idx
<DM_ROMFS>/romfs/romfs.idx

Touch controls. Two layouts (tap the button at the top centre to switch): 2D (left stick, A/B/X/Y, shoulders, − / +) and 3D (adds a D-pad, a right stick and L3 / R3). With no controller connected, touches outside the controls go to the game's touch screen.

Physical controllers (GameController framework: Xbox, PlayStation, Switch Pro and MFi pads all work) hide the touch controls entirely while connected and bring them back when disconnected; meanwhile every touch goes to the game's touch screen. Buttons map by position, as on a Switch controller: bottom = B, right = A, left = Y, top = X, and the D-pad and right stick are kept.

Settings without rebuilding: Documents/env.txt, one KEY=VALUE per line. Common ones:

DM_LANG=zh-Hans        # Chinese (en-US by default)
DM_FPS_TARGET=30       # cap the frame rate (saves battery; the profile's fps_target by default)
DM_OPMODE=0            # handheld mode: 720p render instead of the docked 1080p

Saves and logs are in the Files app under the app's name: save/ and log.txt. When something goes wrong, send log.txt (the previous run is log.prev.txt). Short stutters the first time a new scene appears are normal: the app compiles graphics for it once and remembers them.

The archive format has nothing game-specific in it: the packer walks whatever directory you give it and the reader looks paths up in that tree. To switch games:

1. Extract the new game's NSPs with nx_extract as usual (upstream's script does this).
2. Pack that game's RomFS with romfs_arc.py.
3. Rebuild the IPA with the new GAME= profile (the slim package is the default).
4. Copy the new archive into Documents/romfs/.

Three things to watch for:

• The shard count must stay at or below 256. The reader keeps one fd slot per shard (MAX_SHARDS in romfs_arc.h). The packer now refuses to write an index above that and tells you which --shard-mib would fit. Tears of the Kingdom needs 126 at 200 MiB; a game about twice its size would need 256 MiB shards.
• DLC is not archived. Add-on content still goes into the package (DmIOS.app/aoc/<index>/) and is mounted as a directory. Most DLC is small enough that this does not affect installation; if you hit the installer limit again, drop the DLC from the package and it stays unowned.
• zip_store is per game. The profile lists extensions that are already compressed and should be stored rather than deflated (.zs, .bwav, .mc, .webm, .metallib for Tears of the Kingdom). This only affects the package the shader libraries and tables go into, not the archive.

Games from upstream's tested list (4–6 GB) need roughly 20–30 shards at 200 MiB, well inside the limit, and their memory footprint is far below the per-app budget that stops Tears of the Kingdom.

Five files added, four modified. The fs layer keeps its normal path handling: when an archive is open, host_path_ex hands out a synthetic path (@romfsarc:<guest path>) for entries on the archive mount, and OpenFile / GetEntryType / OpenDirectory / the directory calls route those to the archive. File handles for archive entries are tagged with bit 63 so they never collide with real fds, and ReadFile clamps to the file size (a shard is a flat container, so an unclamped read past the end would return the next file's bytes).

The mount is recognised by its directory, not its name: titles differ (rom for most games, content for Tears of the Kingdom).

79 game profiles ship with this repository. A profile is what makes a build possible — the game's build IDs, memory layout, shader tables and per-game switches — and this fork adds the RomFS archive layer on top, so a large game can be installed at all.

The update column is the version the build actually checks: the update NSP's display version must match the profile's registered build (the base game's own version does not matter — the update layers over it). "无（v0）" = the base game alone is enough.

• Tears of the Kingdom (0100F2C0115B6000, v1.0.0 + update 1.4.3): 304,243 files packed into 127 files; all 304,243 byte-compared against the source (verify: OK); the game runs from the archive on macOS (1,905 frames at 30 fps).
• Hades II (0100A00019DE0000, base + update 1.0.137848): 5,258 files packed into 33 files, byte-compare OK, and the game runs from the archive on macOS (2,100 frames, 1,772 archive reads). The update needs no special handling: nx_extract already layers the update NCA over the base with OpenFileSystemWithPatch, so the extracted RomFS — and therefore the archive — is the merge. Playable on an iPhone (12 GB device, AltStore Classic 2.3) once the memory entitlement is in effect — see below.
• The C reader walks all 304,243 Tears of the Kingdom files and 2,667 directories in 7.6 s.

The jetsam budget is the limit on big titles, and it can be raised. Without com.apple.developer.kernel.increased-memory-limit an iPhone gives this app ~3,375 MB (measured on a 12 GB device: Tears of the Kingdom was killed entering the world map at 3,342 MB resident with 33 MB of headroom; lowering the render scale to 0.5 did not change it, so the limit is the guest heap, not the GPU). The app requests the entitlement and build_ipa.sh embeds it in a placeholder ad-hoc signature — an unsigned binary has no signature for a sideloader to read entitlements from, so without that step the request would be lost. AltStore Classic 2.2+, Impactor and Xcode with a Personal Team keep it; SideStore with a free Apple ID needs a one-time App ID fix; Sideloadly does not. See dm/ios/ENTITLEMENTS.md for the steps and how to tell from Documents/log.txt (resident + headroom: ~3,375 MB = not in effect, 6–8 GB = it is).

What to expect before you start:

• Verified ≠ all 58 games. Three are verified end to end here; the rest are profiles, most reported playable upstream. A title outside the table needs bring-up work of its own.
• Apple Silicon Mac required. The build pipeline is macOS-only (Xcode, Metal).
• iOS 26+ and a recent iPhone. The host targets current iOS; older devices are untested.
• Your own files. No game data, firmware or keys are included or downloaded.

About the archive:

• Read-only. The archive is never written; saves and temp data go to their own mounts as before.
• Case-sensitive lookup. Names are stored as the source tree had them, so the host's case-insensitive alias machinery (for APFS) is bypassed for archive entries.
• Symlinks are followed at pack time. No supported game's RomFS has any.
• The index is held in memory. 28 MB for Tears of the Kingdom (17.9 MB of it names). Shards are not.
• No dedup or compression. Shards are the source bytes verbatim, so verify is a plain comparison and a repack is deterministic.

Community contributors — this project's code is not one maintainer's output:

• v0lumehi — the Mac front end's launcher (PR #27, 40 files): a game library with key art, per-game launch options, a real progress stream, and a Stop that ends the whole build's process group. The Mac app went from "a build form" to the first version of a launcher that opens like a Switch.
• m1guelpf (Miguel Piedrafita) — two HLE fixes (PRs #24 and #26): the missing EnableAlbumImageTakenNotification and CreateWithAdjustableSystemClock entries plus their snapshot type byte — each would have read a null in games that call them, and each came with a test.

Want on this list? Contributing says how to start; reports with a full log and fixes with a test move fastest.

All of the emulation work is other people's. This repository adds the archive subsystem on top:

• nxnative (MIT) — the native-execution toolchain this repository is built from: the NSO rewriter, the Horizon host layer, NVN-on-Metal, the per-game profiles and the iOS shell.
• d2r-mobile (MIT) — the original native-execution approach that nxnative grew out of.
• Ryujinx (MIT) — the shader translator that turns Maxwell shaders into SPIR-V.
• Atmosphère — the reference for Horizon's synchronization semantics.
• LibHac — reads NSPs and layers updates in nx_extract.
• SPIRV-Cross — SPIR-V to Metal Shading Language.
• yuzu, deko3d, libvpx, stb_vorbis, libdeflate — see upstream's acknowledgement list for what each contributes.

dm/third_party ships other projects with their licenses (list).

What this project is. A build tool for games you already own. It reads dumps you made of your own cartridges and purchases, on your own machine, and produces a package for your own device. Nothing in this repository, in the app, or in any release contains or distributes Nintendo's code, art, text, data, shaders, firmware, keys or any other copyrighted material.

What it cannot do. The pipeline has no source of games or keys: it requires the user's own prod.keys and their own NSP/XCI dumps, and it talks to no server. It does not bypass, strip or redistribute any protection — LibHac opens the user's own dumps with the user's own keys, the same operation a console performs on a cartridge.

Trademarks. Not affiliated with, sponsored by or endorsed by Nintendo. "Nintendo Switch" and game titles are trademarks of Nintendo Co., Ltd.; all other trademarks belong to their respective owners.

Your responsibility. Laws on making a personal backup copy differ by country; some places do not allow it at all. You are responsible for knowing and following the law where you live, and for never distributing game files, keys or the packages built from them — the project's outputs are for personal use on your own hardware only. If you enjoy a game, buy it.

Takedowns. If you believe anything in this repository infringes your rights, open an issue or contact the maintainer directly; valid claims will be actioned promptly, up to removing content or the repository.

No warranty. The software is provided "as is" under the licenses in LICENSE (this fork adds to upstream's; see the credits) — without warranty of any kind, express or implied. Use it at your own risk.