nxnative README

The project's README from github.com/seedds/nxnative. As one markdown file: README.md.

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.

Acknowledgements

This project is built on other people's work:

Games

All of these are tested on an iPhone and playable:

Game NSPs to put in the folder IPA Notes
Super Mario Bros. Wonder base game + update 1.2.1 ~4 GB
Fire Emblem Engage base game + update 2.0.0 (+ Expansion Pass DLC) ~15 GB Upgraded to 60 fps (30 fps on Switch)
Metroid Dread base game + update 2.1.0 ~5 GB
13 Sentinels: Aegis Rim base game + update 1.10 ~5 GB
Super Mario 3D World + Bowser's Fury base game + update 1.2.2 ~3 GB
The Legend of Zelda: Breath of the Wild base game + update 1.9.0 (+ DLC) ~16 GB Upgraded to 60 fps (30 fps on Switch)
The Legend of Zelda: Link's Awakening base game + update 1.1.0 ~6 GB

Being ported, not playable yet: Super Mario Odyssey (base game + update 1.4.1).

Super Mario Bros. Wonder
Super Mario Bros. Wonder
Fire Emblem Engage
Fire Emblem Engage
Metroid Dread
Metroid Dread
13 Sentinels: Aegis Rim
13 Sentinels: Aegis Rim
Super Mario 3D World + Bowser's Fury
Super Mario 3D World + Bowser's Fury
The Legend of Zelda: Breath of the Wild
The Legend of Zelda: Breath of the Wild
The Legend of Zelda: Link's Awakening
The Legend of Zelda: Link's Awakening

Needs iOS / iPadOS 26 or later. 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.

Pack an IPA

1. Get nxnative and its tools (once, on a Mac with Xcode and Homebrew):

git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd spirv-cross
brew install --cask dotnet-sdk
python3 -m pip install lz4 capstone fonttools

2. Put one game's NSPs in a folder, base game and update (and any DLC):

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

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, later ones about 10. 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).

Play

Touch controls. Tap 2D / 3D at the top to switch layouts; the app remembers your choice. 3D World and Breath of the Wild start in 3D, the other games in 2D. A connected game controller hides the touch controls and keeps every button.

Known issues

For developers

How it works, the script's options, running games on the Mac, adding a game, and per-game notes: docs/development.md. In-depth bring-up and debugging notes: docs/agents.

License

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


中文说明

在 iPhone 和 iPad 上原生运行你自己的 Nintendo Switch 游戏。准备好游戏(NSP 文件)和你的 prod.keys,一个脚本就能把它们打包成 IPA,再侧载安装。

这不是模拟器:游戏自己的代码直接跑在苹果芯片上,Switch 的图形在 Metal 上重建。本仓库不含任何游戏内容,项目与任天堂及各游戏发行商无关。

致谢

本项目建立在他人的工作之上:

游戏

以下游戏都已在 iPhone 上测试,可以正常游玩:

游戏 文件夹里放的 NSP IPA 大小 备注
超级马力欧兄弟 惊奇 本体 + 1.2.1 更新 约 4 GB
火焰纹章 Engage 本体 + 2.0.0 更新(+ 扩展通行证 DLC) 约 15 GB 升级到 60 fps(Switch 上 30 fps)
密特罗德 生存恐惧 本体 + 2.1.0 更新 约 5 GB
十三机兵防卫圈 本体 + 1.10 更新 约 5 GB
超级马力欧 3D 世界 + 狂怒世界 本体 + 1.2.2 更新 约 3 GB
塞尔达传说 旷野之息 本体 + 1.9.0 更新(+ DLC) 约 16 GB 升级到 60 fps(Switch 上 30 fps)
塞尔达传说 织梦岛 本体 + 1.1.0 更新 约 6 GB

正在移植、还不能玩:超级马力欧 奥德赛(本体 + 1.4.1 更新)。

超级马力欧兄弟 惊奇
超级马力欧兄弟 惊奇
火焰纹章 Engage
火焰纹章 Engage
密特罗德 生存恐惧
密特罗德 生存恐惧
十三机兵防卫圈
十三机兵防卫圈
超级马力欧 3D 世界 + 狂怒世界
超级马力欧 3D 世界 + 狂怒世界
塞尔达传说 旷野之息
塞尔达传说 旷野之息
塞尔达传说 织梦岛
塞尔达传说 织梦岛

需要 iOS / iPadOS 26 或更高版本。其他游戏暂不支持。脚本会为它们写一份分析报告,并猜测游戏的设置,尽力打出一个 IPA;这样的 IPA 可能启动不了。

打包 IPA

1. 获取 nxnative 和所需工具(只需一次,在装有 Xcode 和 Homebrew 的 Mac 上):

git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd spirv-cross
brew install --cask dotnet-sdk
python3 -m pip install lz4 capstone fonttools

2. 把一个游戏的 NSP 放进一个文件夹,本体和更新(有 DLC 也放进去):

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

3. 运行脚本:

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

IPA 会出现在同一个文件夹里(这里是 ~/Games/MarioWonder/SMBWMobile.ipa)。第一次打包要 30–60 分钟,之后约 10 分钟。需要的空闲磁盘空间约为 NSP 大小的两倍再加 10 GB。-o(输出路径)、--app-name 等选项用 -h 查看。

4. 安装:用你的侧载工具(AltStore、Sideloadly、LiveContainer 等)安装 IPA。App 会带上游戏的名字、图标和版本号(用更新的版本号,例如马力欧惊奇是 1.2.1;没有更新时用本体的)。

游玩

触屏按键。 点顶部的 2D / 3D 切换布局,App 会记住你的选择。3D 世界和旷野之息默认 3D 布局,其他游戏默认 2D。 连上游戏手柄后,触屏按键会隐藏,手柄上的所有按键都能用。

已知问题

开发者

工作原理、脚本的全部选项、在 Mac 上运行游戏、添加新游戏、各游戏的技术笔记:docs/development.md。更深入的移植和调试笔记:docs/agents。

许可证

MIT(见 LICENSE)。第三方代码保留各自的许可证,见 dm/third_party。

nxnative (seedds/nxnative)

homebrew
Searching Database…

What is this?nxnative turns your own Nintendo Switch game files (NSP) into an unsigned IPA you can sideload onto iPhone, iPad or Mac, so the game's own code runs natively on Apple hardware with its graphics rebuilt on Metal.
Is this an emulator, like Ryujinx or yuzu?No. It is not an emulator: it rewrites the game's native code and reimplements the Horizon OS as a host, so the original Switch binary runs directly on the Apple chip instead of being interpreted.
How do I pack a game into an IPA?On a Mac with Xcode and Homebrew, get nxnative and its tools, put the game's base NSP plus its update (and DLC) in a folder, then run the packaging script; the IPA appears in that same folder.
What do I need to provide besides the Mac tooling?You need your own copy of the game's NSP files and your prod.keys; the repository itself contains no game content.
Does it work with any Switch game?Only a short list of tested games is confirmed playable; for untested titles the script tries to guess settings and may produce an IPA that doesn't even start, and you need iOS/iPadOS 26 or later.
Is sideloading required to play?Yes, the built IPA has to be installed with a sideloading tool since it isn't signed by Apple.
Does the game run on Mac too, or only iPhone/iPad?The resulting app runs natively on iPhone, iPad and Mac, though the IPA itself must be built on a Mac with Xcode first.
Which games are confirmed playable right now?Super Mario Bros. Wonder, Fire Emblem Engage, Metroid Dread, 13 Sentinels: Aegis Rim, Super Mario 3D World + Bowser's Fury, Breath of the Wild and Link's Awakening are all tested and playable; Super Mario Odyssey is still being ported.
How long does packaging take and how much disk space is needed?The first build of a game takes 30–60 minutes (later rebuilds about 10 minutes), and you need roughly twice the NSP size plus 10 GB of free disk space.
What happens to my save data if I reinstall the app?Some sideloading tools give a reinstalled app a fresh data folder, so you need to manually copy the old save/ folder and psouser.tsv over to keep your progress.
Are there any known bugs?There's no amiibo or online play support, Fire Emblem Engage can lose some sound after you switch apps and back, and Super Mario 3D World can show small magenta squares in World 1-1.
Creator
seedds
Size
12.6 MB
Stars
395
Updated
CommitOct 19
Age
6d
Commits · 90 Days