nxnative README

项目的 README,来自 github.com/seedds/nxnative。合并为一个 markdown 文件:README.md。

nxnative

Play your own Nintendo Switch and Switch 2 games natively on Apple silicon Macs, iPhone and iPad. One script packs your game into a Mac app or an unsigned 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.

Games · Community front ends · Requirements · How to play · Discussions · For developers

Games

The full tested games table includes original Switch games, tested builds, engines and graphics APIs. Each game's note records its tested platforms, progress and known issues.

These Switch 2 games have passed Mac gameplay testing. Build them from a .nup file or a dump folder:

Community front ends

Community projects build on nxnative with tools to turn your games into apps for your iPhone, iPad or Mac without the command line, and libraries to organize and launch them. They are separate projects: questions and bugs about them go to their own pages.

Requirements

The games' textures are BC-compressed, which older iPhones cannot read. Switch 2 builds are tested on the Mac; check each game's note for device-specific validation.

For a game without a profile, the script writes a survey and tries a provisional build with guessed settings. That build may not start; see Port another game.

How to play

Switch 2 games are built from one .nup file or a folder of their files, not from NSPs, and are tested on the Mac only: see Switch 2 games.

Build from the command line

You need a Mac with macOS 26.6 or later, Xcode 27.2, Homebrew and Python 3.12 or newer (an arm64 one, not an Intel Homebrew's). An iPhone build also needs Xcode's iOS platform (Xcode → Settings → Components).

The shaders are built with Xcode 27.2's Metal compiler. Select it before step 1: sudo xcode-select -s /Applications/Xcode.app. With several Xcode versions installed, name this one Xcode-27.2.app and select it with sudo xcode-select -s /Applications/Xcode-27.2.app.

1. Install the tools (only once), in Terminal:

xcodebuild -downloadComponent MetalToolchain
git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd glslang
python3 -m pip install lz4 "capstone>=5,<6" fonttools nsz zbic "backports.zstd; python_version < '3.14'"

2. Put your game in a folder: the game, plus its update and DLC if you have them (.nsp, .xci, .nsz or .xcz):

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

3. Build, with your game folder and your prod.keys:

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

The IPA appears in the game's folder. The first build takes 30–60 minutes and needs free disk space of about twice the game's size plus 10 GB; building again is much faster.

To play on the Mac instead, add --platform mac-app: you get a Mac app of the game to open from Finder. All options: The packing script in detail.

Install

Install the IPA on your iPhone or iPad with a sideloading tool such as AltStore, Sideloadly or LiveContainer. If your tool offers Increased Memory Limit, turn it on: the bigger games need it.

Game too big to install? Build again with --romfs separate, and run the command the script prints once to copy the game files to your phone (Quick reinstalls). With AltServer, also add --shader-files: it cannot install a file of 2 GiB or more.

Controls, saves and settings: Playing.

Switch 2 games

A Switch 2 game is built from one NUP container (a .nup file) or a folder of its files, not from NSPs. Neither needs prod.keys. A game this project has no profile for is surveyed and gets a provisional profile, as NSPs do (Port another game), which may not boot. You get a Mac app; iPhone and iPad are untested.

From a .nup file, which holds the base game, its updates and DLC in one file. Give the file, or a folder that holds it:

python3 scripts/build_ipa_from_nsp.py ~/Games/DonkeyKongBananza.nup --platform mac-app

Hyrule Warriors: Age of Imprisonment is played this way: its 47 GB NUP unpacks in under five minutes. A NUP that carries the game's control data (its NACP) and icon gives the app the game's name and icon; otherwise the name comes from the game's profile and the app has no icon unless you give it one with --icon <image> (ICON in Spyder; a JPEG or PNG of any size).

A Nintendo Switch 2 Edition of a Switch 1 game can hold both of its programs in one NUP: the Switch 1 program with the game data, and the Switch 2 program, which reads that data from the Switch 1 program and its Switch 2 files from the upgrade add-on. The script packs the Switch 2 program, with the Switch 1 program's game files beside its own and the add-on as DLC; --program 0 packs the Switch 1 program instead.

A NUP without the base game also works, when its base package is empty or it has none and its updates are marked standalone_update: the update is taken as the whole game, and the script says so. If the game then stops on missing files, that update holds only what changed: pack a NUP with the base game. The newest update is selected by default; --package v<N> selects another version in the container. Such a container has no v0 (base game) to select.

From a folder of files. The script expects this layout (updates and dlc are optional):

~/Games/DonkeyKongBananza/
  base/exefs/                     main, main.npdm, sdk, rtld
  base/romfs/
  updates/458752/exefs/           the update's version, as a decimal number
  updates/458752/romfs/           the patched RomFS, not a patch
  dlc/040074a01bf13001/0/romfs/   the DLC's title ID
python3 scripts/build_ipa_from_nsp.py ~/Games/DonkeyKongBananza --platform mac-app

An update's folder alone will do (no base/), and so will exefs/ and romfs/ directly in the folder, as nup extract writes them, which count as base/. The app has no icon, because the folder holds none; --icon <image> (ICON in Spyder) gives it one. To turn such a folder into a NUP: nup pack ~/Games/DonkeyKongBananza game.nup.

Discussions

Questions, how a game runs on your Mac or iPhone, and ideas go in Discussions; Issues are for bugs, with the log. Ocarina of Time's performance (frame rate, resolution, which Macs hold 60 fps) is followed in Ocarina of Time: state on main.

For developers

How it works · Game notes · Bring-up and debugging · Front ends · Contributing

Acknowledgements

This project is built on other people's work (licenses):

License

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

nxnative (seedds/nxnative)

正在搜索数据库…

这是什么?nxnative 可以把你自己的任天堂 Switch 游戏文件(NSP)转换成未签名的 IPA,你可以通过侧载安装到 iPhone、iPad 或 Mac 上,让游戏自身的代码在苹果硬件上原生运行,并基于 Metal 重新构建图形。
这是像 Ryujinx 或 yuzu 那样的模拟器吗?不是。它不是模拟器:它会重写游戏的原生代码,并以主机的形式重新实现 Horizon OS,因此原版 Switch 程序直接在苹果芯片上运行,而不是被逐条解释执行。
我要怎么把游戏打包成 IPA?在装有 Xcode 和 Homebrew 的 Mac 上,获取 nxnative 及其工具,把游戏的基础 NSP 以及更新(和 DLC)放进一个文件夹,然后运行打包脚本;IPA 会生成在同一个文件夹中。
除了 Mac 上的工具,我还需要准备什么?你需要自己的游戏 NSP 文件和 prod.keys;代码仓库本身不包含任何游戏内容。
所有 Switch 游戏都能运行吗?只有一小部分经过测试的游戏被确认可以运行;对于未测试的游戏,脚本会尝试猜测设置,生成的 IPA 可能根本无法启动,而且需要 iOS/iPadOS 26 或更高版本。
玩游戏必须侧载吗?是的,生成的 IPA 未经苹果签名,因此必须使用侧载工具安装。
这个游戏在 Mac 上也能运行吗,还是只能在 iPhone/iPad 上运行?生成的应用可以在 iPhone、iPad 和 Mac 上原生运行,但 IPA 本身必须先在装有 Xcode 的 Mac 上构建。
目前哪些游戏被确认可以运行?Super Mario Bros. Wonder、Fire Emblem Engage、Metroid Dread、13 Sentinels: Aegis Rim、Super Mario 3D World + Bowser's Fury、Breath of the Wild 和 Link's Awakening 都已经过测试,可以正常游玩;Super Mario Odyssey 仍在移植中。
打包需要多长时间,需要多少磁盘空间?游戏的首次构建需要 30–60 分钟(之后的重新构建约需 10 分钟),所需空闲磁盘空间约为 NSP 大小的两倍再加 10 GB。
如果重新安装应用,我的存档会怎样?有些侧载工具在重新安装应用后会分配一个新的数据文件夹,因此你需要手动把旧的 save/ 文件夹和 psouser.tsv 复制过去,才能保留游戏进度。
有已知的 bug 吗?不支持 amiibo 和联机游戏;Fire Emblem Engage 在切换应用再切回来后可能会丢失部分声音;Super Mario 3D World 在 World 1-1 中可能会出现小的洋红色方块。
作者
seedds
大小
304 MB
星标
16K
更新
提交Nov 18
时长
1个月
提交 · 90 天