NX2Apple README

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

NX2Apple, by nxnative

Your Switch games, running on your iPhone.

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

Stars Forks Issues License Games

中文 English Svenska Deutsch Français Italiano

NX2Apple — Switch games on iPhone and Mac

🆕 Latest highlights

  • Windows launcher (NX2Apple-windows-x64.zip): Build iPhone and iPad IPAs on Windows with the same 1.2 interface, a bundled engine tree (no git needed), guided first-run setup, multi-core NSO rewriting, and in-app self-update (NX2Apple.exe).
  • Switch 2 games: Pick a Switch 2 game folder or .nup file in the Mac or Windows launcher, with no prod.keys needed, and play on Mac, iPhone, or iPad.
  • Custom touch controls, split Joy-Con, and Steam Controller (2026): Resize buttons, move the left stick, or arrange every control in the visual layout editor on iPhone and iPad. Physical controllers support per-game or global button remapping, split a Bluetooth Joy-Con pair into two sideways controllers on Mac, and support the Steam Controller (2026).
  • One app for iPhone and iPad: All your games live inside one shell app (or export an unsigned IPA for AltStore and SideStore), each carrying its own host framework so engine updates never force a rebuild, with Cover Flow in landscape, per-game settings and mods, safe game deletion that keeps your saves, and 7 languages.
  • Console mode: Plug in a controller and press Select, or start directly in console mode. The library goes full-screen like a Switch home menu, and holding Home for 2 seconds quits a game.

Every release is in the changelog.


What NX2Apple is

NX2Apple runs Nintendo Switch games on your Mac and iPhone from your own game dumps. It is not an emulator: the game's own code runs natively on Apple silicon, and Metal draws it. A Mac app, the launcher, does the build in a few clicks (unpack, rewrite, translate the shaders, pack) and then keeps your games in a library you start with Play, the way a Switch does.

The launcher: a library of built games, one build in progress

It is a community fork of nxnative, which does the actual work (the code rewriter, the Horizon host, NVN on Metal and every game's profile); this fork adds the launcher and a short list of patches, and follows nxnative every day.

Requirements

The app carries its own build tools and Python, so no Homebrew and no Python install; the .NET SDK 10 is the one tool it still installs for you. The launcher's dependency page checks each requirement and installs what it can with one click.

Install

  1. Download the app: NX2Apple-macOS-arm64.zip from the latest release. Unzip it.
  2. Open it once with right-click, then Open. The app is not signed with a paid Apple developer certificate, so macOS asks before the first start; after that it opens normally.
  3. Follow the setup. The launcher fetches the project it builds with (a Download repository button on the setup page, a shallow clone into ~/NX2Apple; if GitHub is slow, the page shows the manual ZIP route), checks the tools above and updates itself later. You never need git.
  4. Build a game. Pick the game's folder (or its base game, update, DLC and prod.keys one by one), choose This Mac or iPhone / iPad, and press build. The page shows the real stages and the time left, and a stopped build continues where it left off. The iPhone / iPad target is one app on the device for all your games. The launcher signs it with Xcode, installs it and copies the game in. It needs a device paired with the Mac.

Building by hand from a terminal is in BUILDING.md.

Updating a Mac game you already built. Select the game in the library and choose Rebuild. For an update NSP, keep the base game selected and choose the new NSP in Updates & add-on content. Build for This Mac in the same output folder. The update can change both game code and data, so the launcher builds the new version and reuses cached work where it can. Your saves stay in their existing folder outside the .app, keyed by the game's title ID. Rebuilding in the same library keeps that progress.

The iPhone and iPad app

The iPhone / iPad target builds one shell app that holds all your games, the way the Mac launcher does. Its library shows each game with its key art. In portrait it is one column with the chosen game at the top. On its side it is a Cover Flow. An iPad shows a grid.

The iPhone app in portrait: the library with a hero and two game covers, one game's settings, and a game that needs its game data The iPhone app on its side: Cover Flow with the covers of Breath of the Wild, Hades and Tears of the Kingdom

The app needs iOS or iPadOS 26 or later. The covers are the eShop banners the Mac launcher caches for your own games.

How to play

On the Mac, a finished game appears in the library with its key art. Play starts it. Launch options (per game, kept across rebuilds) set the frame rate, console mode (docked or handheld), render scale and upscaling, game language, controls and more; what each does is in docs/settings.md. A controller drives the launcher as well as the games.

On the iPhone, the app shows the same settings before the game starts; tap Play. Touch controls come in a 2D and a 3D layout (tap the button at the top centre), and a connected controller (Xbox, PlayStation, Switch Pro, MFi) replaces them. docs/playing.md covers touch, rumble and motion. Short stutters the first time a scene appears are normal: the app compiles graphics for it once and remembers them. The game's data (romfs.img) can live on an external drive that the Files app picks.

Game language. On the Mac, a game that has your Mac's language starts in it: the Game language row of Launch options preselects it until you pick another, and Reset to tested defaults goes back to it. A game without your Mac's language, a game built in another language (LANGUAGE), and every iPhone build start in the build's language, English by default. For anything the sheet lacks, write an env.txt of KEY=VALUE lines (for example DM_LANG=zh-Hans) in one of two places: ~/Library/Application Support/nxnative/<title ID>/env.txt wins and survives rebuilds; <App>.app/Contents/Resources/dm/env.txt is the app's own. A Mac app built before the language row existed needs one rebuild to get it. On the iPhone, the same lines go in Documents/env.txt (DM_FPS_TARGET=30 caps the frame rate to save battery, DM_OPMODE=0 picks handheld mode). That file applies to every game in the shared app. For a line that belongs to one game (a mod's DM_ROMFS_OVERLAY, for example), write it in Documents/games/<title ID>/env.txt. Where both files set a key, the game's file wins. A mod is easier: put its folder in Documents/games/<title ID>/mods/<mod name>/ (the RomFS files in a romfs/ folder inside it, or in the folder itself). The shell then sets DM_ROMFS_OVERLAY for that game only. If there are several mods, the one first by name wins where they replace the same file. Where the same key is set twice, the order is: the shell's own settings, the game's env.txt, the game's mods/ folder, the shared Documents/env.txt.

Saves and logs. A Mac game in a library folder keeps its saves and its log beside the app (log/<title ID>.log); otherwise they are in ~/Library/Application Support/nxnative/<title ID>/ and ~/Library/Logs/nxnative/<title ID>.log. On the iPhone they are in the Files app under the app's name: save/ and log.txt (the previous run is log.prev.txt).

Reporting a bug. Use the issue forms (game problem, build problem, launcher problem). Each asks for the game and its title ID, your versions and device, Settings > Copy diagnostics and the game's log; CONTRIBUTING.md says why. A report with the full log.txt is looked at first. Never attach keys, game files or anything extracted from a game.

Games

147 games have a profile. Many are reported playable on an iPhone upstream, and most have a profile that has not been tried on a phone yet. A few of them:

Game Where it runs Status
The Legend of Zelda: Tears of the Kingdom Mac and iPhone Verified here: 304,243 files, byte-checked; ~17 GB
Hades II Mac and iPhone Verified here
Animal Crossing: New Horizons iPhone Verified here: runs smoothly
Super Mario Odyssey iPhone Reported playable upstream
The Legend of Zelda: Breath of the Wild iPhone Reported playable upstream; 60 fps with 1.9.0
Mario Kart 8 Deluxe iPhone Reported playable upstream

GAMES.md has the screenshot gallery with each game's install size, and the full table with the update version each game needs: the update NSP's display version must match the profile's, or the build says so.

Switch 2 games are new in the engine. Eleven have a profile, all marked as playing on the Mac by upstream: Donkey Kong Bananza, Splatoon Raiders, Fire Emblem Fortune's Weave, Pokémon Pokopia, Hyrule Warriors: Age of Imprisonment, Mario Kart World, Mario Tennis Fever, Star Fox, Yoshi and the Mysterious Book, The Legend of Zelda: Ocarina of Time and Kirby Air Riders. Choose the game's folder of files (base/, updates/, dlc/) or its .nup file on the Builds page. No prod.keys are needed for them. The library marks them Switch 2. Only Donkey Kong Bananza was tried on this fork. The owner built and played it through the launcher on a Mac, an iPhone and an iPad, with no problems on the Mac and the iPhone and almost none on the iPad. The other Switch 2 games were not tried here. GAMES.md has the details.

Limitations

For developers

Credits

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

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

Community projects — maintained by their authors, outside this repository:

All of the engine work is other people's. This repository adds the launcher and the patch queue on top:

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.

NX2Apple (LNPANDY/NX2Apple)

正在搜索数据库…

这是什么?NX2Apple 是一个 macOS 工具,它接收你自己转储的 Nintendo Switch 游戏文件,经过一套流程为 Apple 芯片重写游戏代码、把着色器翻译成 Metal,并把所有内容打包成一个可以安装到 iPhone 或 iPad 上的应用。
这是命令行流程还是图形界面应用?两者都有:保留了上游原本的命令行脚本,另外还提供一个名为 NS Port Builder 的 macOS 图形界面应用(位于 frontend/ 目录),让你无需打开终端,就能完成选择输入、检测依赖和构建等步骤。
我该如何构建并安装游戏?先按照上游 README 的说明安装 Xcode、Homebrew 工具和 Python 包,构建 macOS 应用,然后把基础游戏、更新、DLC 和 prod.keys 交给应用(四个输入可以分别选择,也可以选一个文件夹统一提供)。应用会依次解包、重写、打包成精简的 IPA,并对 RomFS 进行分片,最后显示安装步骤。
除了应用本身,我还需要在硬盘上准备什么?你需要从自己的主机上转储出来的 prod.keys,以及从自己的卡带或 eShop 购买中转储出来的游戏 NSP 文件,另外还要安装 Xcode 和 iOS SDK。这些都不随代码仓库提供。
所有游戏都能顺利安装和复制吗?《塞尔达传说:王国之泪》这类体量很大的 RomFS 目录在 iOS 上完全无法安装;分片归档的修复最多只支持 256 个分片,附加 DLC 仍会以未归档的形式保留在包内。
我需要自己的游戏转储文件吗?项目里会附带游戏吗?需要自备游戏:本项目只能处理你自己从卡带或 eShop 购买中转储的 NSP,以及你自己主机的 prod.keys,不附带任何游戏文件。
为什么《王国之泪》需要特殊的 RomFS 归档?它的 304,243 个文件会导致 iOS 的软件包安装器失败(PackageExtractionFailed)。因此工具会把这些文件打包成 127 个大分片文件,它们可以正常安装,并且复制到手机上时是一个文件夹,而不是几十万个独立条目。
实际支持多少款游戏?仓库内提供了 48 个游戏配置文件;其中两款已在本分支上完成端到端验证,另有大约二十款据上游项目反馈可以在 iPhone 上运行。
如果构建中途被打断会怎样?解包、DLC、模块重写和着色器编译这几个阶段的结果都会缓存在构建文件夹中,因此中断或失败的构建会从上次停下的地方继续,而不必从头开始。
作者
LNPANDY
大小
262.7 MB
星标
7.6K
时长
29天
提交 · 90 天