新晋黑马

Objective-C

seedds/nxnative

Switch games running natively on iPhone, iPad and Mac: an NSP folder becomes an unsigned IPA (NSO rewriter, Horizon HLE host, NVN→Metal)

7851语言：Objective-C来源：GitHub收录于 2026年10月28日

访问项目主页 → ← 返回首页

站内导读

中文 nxnative 让 Switch 游戏在 iPhone、iPad 上原生运行：不是模拟器，游戏代码直接跑在 Apple 芯片上，图形经 Metal 重建。用户提供 NSP 与 prod.keys，脚本将其打包成可侧载的 IPA。需 iOS 26 及 A17 Pro 或 M1 以上设备，适合愿意用命令行的开发者。

README · 详细文档

来源 · 查看原文

nxnative

Play your own Nintendo Switch games natively on iPhone and iPad. Bring your game (its NSP files) and your prod.keys; one script turns them into an IPA that you sideload.

It is not an emulator: the game's own code runs directly on the Apple chip, with Switch graphics rebuilt on Metal. Nothing from any game is in this repository, and the project is not affiliated with Nintendo or any game publisher.

[!TIP] Prefer an app to the command line? NX2Apple is a community Mac app that builds your games for the iPhone, iPad or Mac, keeps the Mac games in a library and starts them with their settings. It is a separate project that follows this one; this page describes nxnative's own command-line way. Building a front end of your own: Front ends.

Acknowledgements

This project is built on other people's work:

d2r-mobile (MIT) developed this native-execution approach, for Diablo II: Resurrected. nxnative started as a copy of its generic parts: the NSO rewriter, the host that stands in for Horizon, the NVN-on-Metal layer and the iOS app shell. Fixes go both ways.
Ryujinx (MIT): its shader translator (Ryujinx.Graphics.Shader, Ryujinx.Common and Spv.Generator 1.3.2, in dm/third_party/ryujinx with a few fixes listed in its README) turns the games' Maxwell shaders into SPIR-V. Its emulation of the kernel and system services is also a reference when the host's behaviour is in doubt.
Atmosphère: its kernel, mesosphère, is the reference for Horizon's synchronization semantics (address arbiter, condition variables).
yuzu: Maxwell instruction encodings for the shader reference tool, and a cross-check for kernel behaviour.
LibHac: reads NSPs and layers updates over the base game in dm/tools/nx_extract. hactool did the first extractions.
SPIRV-Cross: SPIR-V to Metal Shading Language. glslang compiles the GLSL of OpenGL games to SPIR-V for it.
deko3d (zlib): its texture layout size algorithm is ported in dm/gfx/nvn/nvn_tex.c.
libvpx (VP9 movies), stb_vorbis (movie sound), the Vulkan headers and NVIDIA FLIP ship in dm/third_party with their licenses (list).
Capstone, lz4, fontTools and XcodeGen are used by the build.

Games

Games tested on Mac or iPhone. See the per-game notes for tested platforms, progress and known issues:

Needs iOS / iPadOS 26 or later on an iPhone 15 Pro or newer (A17 Pro chip or later) or an iPad with an M1 chip or later: the games' textures are BC-compressed, and older iPhones can't read that format. Other games aren't supported yet. For them the script writes a survey and still tries its best to pack an IPA, guessing the game's settings; such an IPA may not start.

Under each game: the IPA's size, and "60 fps with 1.2.0" where the game runs at 60 fps (30 on the Switch) with that update.

<table> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/mario-kart-8-deluxe.jpg" width="256" alt="Mario Kart 8 Deluxe"> Mario Kart 8 Deluxe ~11.9 GB · no Mii heads</td> <td align="center" valign="top" width="33%"><img src="docs/images/mario-vs-donkey-kong.jpg" width="256" alt="Mario vs. Donkey Kong"> Mario vs. Donkey Kong ~1.6 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/paper-mario-the-thousand-year-door.jpg" width="256" alt="Paper Mario: The Thousand-Year Door"> Paper Mario: The Thousand-Year Door ~5 GB · 60 fps with 1.0.1</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/super-mario-3d-world.jpg" width="256" alt="Super Mario 3D World + Bowser's Fury"> Super Mario 3D World + Bowser's Fury ~3 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/super-mario-bros-wonder.jpg" width="256" alt="Super Mario Bros. Wonder"> Super Mario Bros. Wonder ~4 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/super-mario-galaxy.jpg" width="256" alt="Super Mario Galaxy"> Super Mario Galaxy ~3 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/super-mario-galaxy-2.jpg" width="256" alt="Super Mario Galaxy 2"> Super Mario Galaxy 2 ~3 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/super-mario-odyssey.jpg" width="256" alt="Super Mario Odyssey"> Super Mario Odyssey ~6 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/zelda-breath-of-the-wild.jpg" width="256" alt="The Legend of Zelda: Breath of the Wild"> The Legend of Zelda: Breath of the Wild ~16 GB · 60 fps with 1.9.0</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/zelda-links-awakening.jpg" width="256" alt="The Legend of Zelda: Link's Awakening"> The Legend of Zelda: Link's Awakening ~6 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/zelda-tears-of-the-kingdom.jpg" width="256" alt="The Legend of Zelda: Tears of the Kingdom"> The Legend of Zelda: Tears of the Kingdom ~17 GB · 60 fps with 1.4.3</td> <td align="center" valign="top" width="33%"><img src="docs/images/13-sentinels.jpg" width="256" alt="13 Sentinels: Aegis Rim"> 13 Sentinels: Aegis Rim ~5 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/absolum.jpg" width="256" alt="Absolum"> Absolum ~2 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/ace-attorney-investigations.jpg" width="256" alt="Ace Attorney Investigations Collection"> Ace Attorney Investigations Collection ~7 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/advance-wars-1-2-re-boot-camp.jpg" width="256" alt="Advance Wars 1+2: Re-Boot Camp"> Advance Wars 1+2: Re-Boot Camp ~7.1 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/ai-the-somnium-files.jpg" width="256" alt="AI: THE SOMNIUM FILES"> AI: THE SOMNIUM FILES ~8.3 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/ai-the-somnium-files-nirvana-initiative.jpg" width="256" alt="AI: THE SOMNIUM FILES - nirvanA Initiative"> AI: THE SOMNIUM FILES - nirvanA Initiative ~11.6 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/animal-crossing-new-horizons.jpg" width="256" alt="Animal Crossing: New Horizons"> Animal Crossing: New Horizons ~10.5 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/animal-well.png" width="256" alt="ANIMAL WELL"> ANIMAL WELL ~54 MB</td> <td align="center" valign="top" width="33%"><img src="docs/images/astral-chain.png" width="256" alt="ASTRAL CHAIN"> <a href="dm/games/01007300020FA000/README.md">ASTRAL CHAIN</a> ~9.7 GB · 60 fps target with 1.0.1</td> <td align="center" valign="top" width="33%"><img src="docs/images/balatro.jpg" width="256" alt="Balatro"> Balatro ~82 MB · played by touch</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/ball-x-pit.jpg" width="256" alt="BALL x PIT"> BALL x PIT ~1.1 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/bayonetta.jpg" width="256" alt="Bayonetta"> Bayonetta ~8.8 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/bayonetta-2.jpg" width="256" alt="Bayonetta 2"> Bayonetta 2 ~12.5 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/bayonetta-3.jpg" width="256" alt="Bayonetta 3"> Bayonetta 3 ~14.2 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/big-brain-academy-brain-vs-brain.jpg" width="256" alt="Big Brain Academy: Brain vs. Brain"> Big Brain Academy: Brain vs. Brain ~0.8 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/brain-memory-training-academy.jpg" width="256" alt="Brain Memory Training Academy"> Brain Memory Training Academy ~0.1 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/captain-toad-treasure-tracker.jpg" width="256" alt="Captain Toad: Treasure Tracker"> Captain Toad: Treasure Tracker ~2 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/catherine-full-body.jpg" width="256" alt="Catherine: Full Body"> Catherine: Full Body ~14 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/celeste.jpg" width="256" alt="Celeste"> Celeste ~0.9 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/cuphead.jpg" width="256" alt="Cuphead"> Cuphead ~5 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/dark-souls-remastered-creation.jpg" width="256" alt="DARK SOULS: REMASTERED"> DARK SOULS: REMASTERED ~4 GB · 60 fps with 1.0.3</td> <td align="center" valign="top" width="33%"><img src="docs/images/digimon-story-cyber-sleuth.jpg" width="256" alt="Digimon Story Cyber Sleuth: Complete Edition"> Digimon Story Cyber Sleuth: Complete Edition ~5 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/donkey-kong-country-tropical-freeze.jpg" width="256" alt="Donkey Kong Country: Tropical Freeze"> Donkey Kong Country: Tropical Freeze ~7.3 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/dragon-quest-vii-reimagined.jpg" width="256" alt="DRAGON QUEST VII Reimagined"> DRAGON QUEST VII Reimagined ~5.9 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/dragon-quest-xi-s.jpg" width="256" alt="DRAGON QUEST XI S: Echoes of an Elusive Age – Definitive Edition"> DRAGON QUEST XI S: Echoes of an Elusive Age – Definitive Edition ~15 GB · 60 fps with 1.0.4</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/final-fantasy-resonance.jpg" width="256" alt="FINAL FANTASY RESONANCE"> FINAL FANTASY RESONANCE ~10 GB · 60 fps with 1.0.1</td> <td align="center" valign="top" width="33%"><img src="docs/images/final-fantasy-tactics.jpg" width="256" alt="FINAL FANTASY TACTICS - The Ivalice Chronicles"> FINAL FANTASY TACTICS - The Ivalice Chronicles ~11 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/fire-emblem-engage.jpg" width="256" alt="Fire Emblem Engage"> Fire Emblem Engage ~15 GB · 60 fps with 2.0.0</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/fire-emblem-three-houses.jpg" width="256" alt="Fire Emblem: Three Houses"> Fire Emblem: Three Houses ~13 GB · 60 fps with 1.2.0</td> <td align="center" valign="top" width="33%"><img src="docs/images/ghost-trick-phantom-detective.jpg" width="256" alt="Ghost Trick: Phantom Detective"> Ghost Trick: Phantom Detective ~3 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/the-great-ace-attorney-chronicles.jpg" width="256" alt="The Great Ace Attorney Chronicles"> The Great Ace Attorney Chronicles ~4 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/hades.jpg" width="256" alt="Hades"> Hades ~4 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/hades-ii.jpg" width="256" alt="Hades II"> Hades II ~4 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/hollow-knight-silksong.jpg" width="256" alt="Hollow Knight: Silksong"> Hollow Knight: Silksong ~6.4 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/hyrule-warriors-age-of-calamity.jpg" width="256" alt="Hyrule Warriors: Age of Calamity"> Hyrule Warriors: Age of Calamity ~15 GB · 60 fps with 1.3.0</td> <td align="center" valign="top" width="33%"><img src="docs/images/kirby-and-the-forgotten-land.jpg" width="256" alt="Kirby and the Forgotten Land"> Kirby and the Forgotten Land ~6.4 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/luigis-mansion-3.jpg" width="256" alt="Luigi's Mansion 3"> Luigi's Mansion 3 ~7.5 GB · 60 fps with 1.4.0</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/metroid-dread.jpg" width="256" alt="Metroid Dread"> Metroid Dread ~5 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/monster-hunter-rise.jpg" width="256" alt="Monster Hunter Rise"> Monster Hunter Rise ~22 GB · 60 fps with 16.0.2</td> <td align="center" valign="top" width="33%"><img src="docs/images/monster-train-2.jpg" width="256" alt="Monster Train 2"> Monster Train 2 ~1.6 GB · 60 fps with 1.1.1</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/octopath-traveler.jpg" width="256" alt="OCTOPATH TRAVELER"> OCTOPATH TRAVELER ~3.6 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/octopath-traveler-0.jpg" width="256" alt="Octopath Traveler 0"> Octopath Traveler 0 ~4 GB · 60 fps with 1.0.5</td> <td align="center" valign="top" width="33%"><img src="docs/images/octopath-traveler-ii.jpg" width="256" alt="Octopath Traveler II"> Octopath Traveler II ~5.9 GB · 60 fps with 1.1.1</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/patricks-parabox.jpg" width="256" alt="Patrick's Parabox"> Patrick's Parabox ~0.2 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/persona-5-royal.jpg" width="256" alt="Persona 5 Royal"> Persona 5 Royal ~14.9 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/pikmin-4.jpg" width="256" alt="Pikmin 4"> Pikmin 4 ~10.8 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/pokemon-brilliant-diamond.jpg" width="256" alt="Pokémon Brilliant Diamond"> Pokémon Brilliant Diamond ~4.6 GB · 60 fps with 1.3.0</td> <td align="center" valign="top" width="33%"><img src="docs/images/pokemon-legends-z-a.jpg" width="256" alt="Pokémon Legends: Z-A"> Pokémon Legends: Z-A ~6 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/pokemon-scarlet.png" width="256" alt="Pokémon Scarlet"> Pokémon Scarlet ~7.0 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/pokemon-sword.jpg" width="256" alt="Pokémon Sword"> Pokémon Sword ~12.4 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/pokemon-shield.jpg" width="256" alt="Pokémon Shield"> Pokémon Shield ~12.4 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/portal.jpg" width="256" alt="Portal"> Portal ~2.6 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/raging-loop.jpg" width="256" alt="Raging Loop"> Raging Loop ~0.9 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/rhythm-heaven-groove.jpg" width="256" alt="Rhythm Heaven Groove"> Rhythm Heaven Groove ~3 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/romance-of-the-three-kingdoms-8-remake.jpg" width="256" alt="ROMANCE OF THE THREE KINGDOMS 8 REMAKE"> ROMANCE OF THE THREE KINGDOMS 8 REMAKE ~16.8 GB · controller only</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/sea-of-stars.jpg" width="256" alt="Sea of Stars"> Sea of Stars ~5.1 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/shin-megami-tensei-v-vengeance.jpg" width="256" alt="SHIN MEGAMI TENSEI V: Vengeance"> SHIN MEGAMI TENSEI V: Vengeance ~14.6 GB · 60 fps with 1.0.3</td> <td align="center" valign="top" width="33%"><img src="docs/images/stardew-valley.jpg" width="256" alt="Stardew Valley"> Stardew Valley ~0.6 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/steins-gate-reboot.jpg" width="256" alt="STEINS;GATE RE:BOOT"> STEINS;GATE RE:BOOT ~6 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/super-smash-bros-ultimate.jpg" width="256" alt="Super Smash Bros. Ultimate"> Super Smash Bros. Ultimate ~17.5 GB · offline</td> <td align="center" valign="top" width="33%"><img src="docs/images/taiko-risshiden-v-dx.jpg" width="256" alt="Taiko Risshiden V DX"> Taiko Risshiden V DX ~3.3 GB · Japanese · played by touch</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/unicorn-overlord.jpg" width="256" alt="Unicorn Overlord"> Unicorn Overlord ~4 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/yoshis-crafted-world.jpg" width="256" alt="Yoshi's Crafted World"> <a href="dm/games/01006000040C2000/README.md">Yoshi's Crafted World</a> ~6.1 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/nier-automata.png" width="256" alt="NieR:Automata The End of YoRHa Edition"> NieR:Automata The End of YoRHa Edition ~10.9 GB · 60 fps with 1.0.3</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/zelda-echoes-of-wisdom.jpg" width="256" alt="The Legend of Zelda: Echoes of Wisdom"> The Legend of Zelda: Echoes of Wisdom ~7.8 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/donkey-kong-country-returns-hd.png" width="256" alt="Donkey Kong Country Returns HD"> Donkey Kong Country Returns HD ~11.6 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/mario-rabbids-sparks-of-hope.jpg" width="256" alt="Mario + Rabbids Sparks of Hope"> Mario + Rabbids Sparks of Hope ~9.8 GB</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/xenoblade-chronicles-2.jpg" width="256" alt="Xenoblade Chronicles 2"> Xenoblade Chronicles 2 ~17.1 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/xenoblade-chronicles-3.jpg" width="256" alt="Xenoblade Chronicles 3"> Xenoblade Chronicles 3 ~19.2 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/final-fantasy-crystal-chronicles.jpg" width="256" alt="FINAL FANTASY CRYSTAL CHRONICLES Remastered Edition"> FINAL FANTASY CRYSTAL CHRONICLES Remastered Edition</td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/return-of-the-obra-dinn.png" width="256" alt="Return of the Obra Dinn"> <a href="dm/games/010032E00E6E2000/README.md">Return of the Obra Dinn</a> ~0.9 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/blasphemous-2.png" width="256" alt="Blasphemous 2"> <a href="dm/games/010040801A4C8000/README.md">Blasphemous 2</a> ~1.5 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/silver-pines.jpg" width="256" alt="Silver Pines"> <a href="dm/games/0100D5B026844000/README.md">Silver Pines</a></td> </tr> <tr> <td align="center" valign="top" width="33%"><img src="docs/images/blasphemous.jpg" width="256" alt="Blasphemous"> <a href="dm/games/0100698009C6E000/README.md">Blasphemous</a> ~0.9 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/final-fantasy-x-x2-hd-remaster.jpg" width="256" alt="FINAL FANTASY X/X-2 HD Remaster"> <a href="dm/games/0100BC300CB48000/README.md">FINAL FANTASY X/X-2 HD Remaster</a> ~26.5 GB</td> <td align="center" valign="top" width="33%"><img src="docs/images/mario-rabbids-kingdom-battle.jpg" width="256" alt="Mario + Rabbids Kingdom Battle"> <a href="dm/games/010067300059A000/README.md">Mario + Rabbids Kingdom Battle</a> ~5 GB</td> </tr> </table>

Pack an IPA

Prefer a graphical interface to the command line? NX2Apple is a community fork with a macOS app that runs this whole pipeline for you and packs the game files into a sharded RomFS archive for a slimmer IPA. It is a separate project that follows this one; the steps below are nxnative's own command-line way.

1. Get nxnative and its tools (once, on a Mac with macOS 26.6 or later, Xcode 27.1 and Homebrew). The shaders are tested with Xcode 27.1's Metal compiler. The script stops on another version and explains how to install the tested toolchain. Corruption reported with another compiler in #242 is still under investigation.

xcodebuild -downloadComponent MetalToolchain
git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd glslang
brew install --cask dotnet-sdk
python3 -m pip install lz4 capstone fonttools "backports.zstd; python_version < '3.14'"

Use Python 3.12 or newer. Extraction writes one RomFS.img directly; the build reads it and bundles it as romfs.img in the IPA. The app reads the image in place, so neither the Mac build nor the iPhone expands it into a RomFS folder.

2. Put one game's NSPs in a folder: the base game (an NSP, or an XCI cartridge dump), plus its update and DLC if you have them:

~/Games/MarioWonder/
  Super Mario Bros. Wonder [010015100B514000][v0].nsp
  Super Mario Bros. Wonder [010015100B514800][v327680].nsp

NSZ and XCZ files (compressed NSPs and XCIs) work too: the script converts them once with nsz (python3 -m pip install nsz) and keeps the NSPs in <title ID>_build/nsp/, which takes their full size on disk.

Any version works, with or without an update: the script packs the newest version in the folder. DLC is optional too: the DLC in the folder is packed, and without it the game sees none, as on a Switch without it. Each game was tested on one version (an update named in the table above is the one its 60 fps needs). With another version the script builds the game with that version's own shaders and says that the version was not tested; fixes made for the tested version's code, such as the 60 fps ones, don't apply to it.

3. Run the script:

python3 scripts/build_ipa_from_nsp.py ~/Games/MarioWonder -k ~/keys/prod.keys

The IPA appears in the same folder (here ~/Games/MarioWonder/SMBWMobile.ipa). The first build takes 30–60 minutes. A later one reuses every step whose inputs did not change, so after a pull that changes only the host it takes about a minute. The small .idx file beside the IPA (.app.key beside a Mac app) records what was packed; keep it for the next build. You need free disk space of about twice the NSPs' size plus 10 GB. Options such as -o (output path) and --app-name are listed by -h.

4. Install the IPA with your sideloading tool (AltStore, Sideloadly, LiveContainer, …). The app gets the game's name, icon and version (the update's version, for example 1.2.1 for Mario Wonder; the base game's when there is no update). Sign it with the Increased Memory Limit capability (com.apple.developer.kernel.increased-memory-limit) if your tool can: without it iOS gives the app about 3.4 GB and closes the bigger games (Hyrule Warriors: Age of Calamity and Hades II use more, Breath of the Wild and Cuphead come close); with it a recent iPhone gives about 6 GB.

To play on a Mac with Apple silicon instead, --platform mac-app packs a Mac app of the game that you open from Finder (A Mac app). It shows the game's settings in a window before the game starts (The Mac settings window).

With an Apple developer account you can instead build and install from Xcode: --prepare-xcode makes an Xcode project for the game rather than an IPA (Build and run on a device with Xcode).

Play

Settings. A screen before the game starts offers what the game supports: frame rate, render scale, docked or handheld mode, game language, the frame-rate counter and rumble. Everything is on one scrollable screen, grouped into Game, Controls and Performance, with menus, sliders and a reset to the settings the game was tested with. Tap Play to start; the app remembers your choices. What each setting does: Settings.

Touch controls. Tap 2D / 3D at the top to switch layouts; the app remembers your choice. Wonder, Engage, Dread, 13 Sentinels, Link's Awakening, Ace Attorney Investigations Collection, Unicorn Overlord, Rhythm Heaven Groove, Octopath Traveler 0, Pokémon Legends: Z-A, Cuphead, Absolum, Blasphemous 2, Brain Memory Training Academy, The Great Ace Attorney Chronicles, STEINS;GATE RE:BOOT, Big Brain Academy: Brain vs. Brain, Patrick's Parabox, Celeste, Raging Loop and Mario vs. Donkey Kong start in 2D, the other games in 3D (STEINS;GATE RE:BOOT's quick save is R3, in the 3D layout). In 3D, the right stick (the camera in most games) is not drawn: swipe on the right third of the screen, starting anywhere off the buttons. In Super Mario Galaxy and Super Mario Galaxy 2, other touches outside the controls move the pointer; in Captain Toad: Treasure Tracker they touch the game's screen (touch blocks, stun enemies), and in Big Brain Academy: Brain vs. Brain too (its menus and activities). A connected game controller hides the touch controls and keeps every button.

Rumble. Game vibration uses the iPhone's haptic engine or a compatible connected controller. Controllers with separate left/right haptic outputs keep those effects separate. The launcher's Game rumble and Rumble strength settings control it independently of Touch feedback. Phone rumble approximates the Switch's effects; physical feel and controller compatibility still need device testing.

Motion (gyro). A controller that supplies gyro data through Apple's controller support (DualSense, DualShock 4) drives the game's motion controls, on the Mac and the iPhone: aiming and tilt puzzles in games that read the controller's motion, such as Breath of the Wild with its Motion Controls option on. A controller without one (Backbone One, Razer Kishi and other controllers the phone mounts in) uses the iPhone's own gyro, as a Switch in handheld. Motion follows the controller in docked mode, the default. DM_PHONE_MOTION=0 in Documents/env.txt stops the phone's gyro, DM_MOTION=0 all motion. If motion misbehaves, pack with --no-motion (MOTION = False in Spyder) for an app without it; DM_MOTION=1 in Documents/env.txt turns it back on.

Switch Pro Controller gyro on the Mac still needs the HID support being developed in PR #296.

Shaking. Shake the iPhone to shake the controller, in games that read its motion: Super Mario Odyssey's motion moves (such as the cap throw on a shake) need it, and Odyssey only takes them in its default docked mode. A light bump does not count; a sharp flick of the phone does.

Game language is English by default. Pick another when packing with --language (-l), by code or by name: -l ja, -l zh-Hans, -l French (LANGUAGE in Spyder). It must be one the game has; the script prints the game's languages and stops on one it lacks. To change it without rebuilding, pick another on the settings screen.
On the Mac, a game's app starts with the settings it was tested with. To choose others before it starts (frame rate, console mode, upscaling, …), start it from NX2Apple's library, or put lines like DM_FPS_TARGET=30 in ~/Library/Application Support/nxnative/<title ID>/env.txt. Its log is ~/Library/Logs/nxnative/<title ID>.log.
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 for the next launch. What it remembered, and what the game's list names, is built before the game starts, behind "Preparing shaders" and a progress bar when that takes more than half a second.
Reinstalling: some sideloading tools give a reinstalled app a new data folder. Copy save/ and pso_user.tsv over from the old one to keep your progress.
Settings in a file: lines like DM_OPMODE=0 (handheld mode: lower resolution, higher frame rate) in Documents/env.txt win over the settings screen, which then shows them greyed out. DM_FPS_TARGET=30 keeps Breath of the Wild, Tears of the Kingdom, Octopath Traveler 0 and Octopath Traveler II at their original 30 fps, which saves battery; DM_PRESENT_INTERVAL=game does the same for Monster Train 2. DM_SHOW_FPS=1 shows the frame rate at the top left (--show-fps when packing turns it on from the start). DM_LAUNCHER=0 skips the settings screen.

Known issues

No amiibo and no online features.
Fire Emblem Engage: after switching away from the app and back, some sounds may stay silent until you restart it.
Fire Emblem: Three Houses: small square patches on the ground where decals land.
Super Mario Galaxy and Super Mario Galaxy 2: effects drawn as points or lines come out one pixel wide.

For developers

How it works, the script's options, running games on the Mac and adding a game: docs/development.md. Per-game notes: dm/games. In-depth bring-up and debugging notes: docs/agents. What a graphical front end can build on: Front ends. Reporting a problem or sending a change: CONTRIBUTING.md.

License

MIT (see LICENSE). Third-party code keeps its own license; see dm/third_party.