This page only covers turning your own game files into an app on your Mac, iPhone or iPad. One build takes 20–40 minutes, most of it waiting. Controls and settings: controls.md. What has been tested: test-records.md. AI assistants: the same steps as a checklist are in the install skill.
Contents: What you need · Build the app · Breath of the Wild · iPhone and iPad · Apple Vision Pro · Update the app · When the build stops · Where things are · Known issues
Ground rules: use only files from your own Switch and your own game. Nothing is downloaded for you, and nothing from the game is in this repository. Never edit games/totk/assets/expected-*.json or the scripts to get past a check: the error message says what is wrong. The app you build contains the game: it is for you only.
A Mac with Apple silicon and macOS 26 or later (the graphics use Metal 4). 16 GB of memory or more is recommended. On macOS 15, use the community fork by 1918662410-ship-it, which adds a Metal 3 backend (not tested here).
Your game files, dumped from your own Switch. The title ID is usually in the file name in brackets; the build reads the file itself, never its name.
| Title ID | What | On the command line |
|---|---|---|
0100F2C0115B6000 |
Tears of the Kingdom, base game 1.0.0, XCI or NSP | first argument |
0100F2C0115B6800 |
Tears of the Kingdom update 1.1.2, 1.2.1 or 1.4.3, NSP or NSZ (optional) | --update |
01007EF00011E000 |
Breath of the Wild base game, or the 1.6.0 card image (base + update + DLC in one XCI) | first argument |
01007EF00011E800 |
Breath of the Wild update 1.6.0 or 1.9.0, NSP or NSZ | --update |
01007EF00011F001, 01007EF00011F002 |
Breath of the Wild DLC packs, NSP (each optional) | --dlc, once per pack |
- For Tears of the Kingdom, 1.4.3 is recommended: it is the most tested and the only version tested on iPhone and iPad. No intermediate update is needed. Without
--updateyou get 1.0.0. - The base game must be uncompressed. Decompress an NSZ or XCZ base first (
nsz -D). - A card image that also holds its own update is fine; the version still comes from
--update.
prod.keys from the same Switch (Lockpick_RCM). Keys dumped on an old firmware can be too old for a newer update.
System fonts, needed when the base game is an NSP and always for Breath of the Wild. Give one of:
--firmware <folder>: your firmware dump as a folder of.ncafiles (unzip it first), or an installed firmwareregisteredfolder.--shared-fonts <folder>: the six.bfttffiles an earlier Tears of the Kingdom build extracted, inTOTK_build/totk/extracted/firmware/shared-fonts.
A Tears of the Kingdom XCI carries the fonts itself.
Free disk space on the volume of the work folder:
| Mac | iPhone / iPad | |
|---|---|---|
| base game only | 25 GB | 45 GB |
| with an update | 40 GB | 60 GB |
The work folder is created next to the game file (TOTK_build, or BotW_build for Breath of the Wild). Keep it and the app on the same APFS volume: the 17 GB of game data is then cloned, not copied. If your game files are on an exFAT/FAT disk or a full one, pass --work <folder> and -o <app> on an APFS disk with room.
Rather not type the command? With the tools of step 1 below installed, double-click Build Game.command in this folder (or run python3.14 -m tools.builder). A window opens: choose the game, then your game file, update, prod.keys and, when the game needs them, a firmware or shared-fonts folder (the work folder and the output app are under Advanced). Check files checks this Mac and your files and shows each problem, with the exact command that fixes it when there is one. Build app then runs build_app.py with those paths, and shows its four stages, the elapsed time and the log. When it is done, Open app and Show in Finder are one click away. Nothing is copied: the window saves the paths you chose, and the game, version, app and commit of the last successful build, in ~/Library/Application Support/MacNativeGames/Builder/settings.json. Each run's output is also saved as ~/Library/Logs/MacNativeGames/builder-<game>-<date>-<time>.log.
Cancel sends the build and everything it started an interrupt (SIGINT), then SIGKILL if it is still running 10 seconds later. The window then says how the build ended and whether that matches the signal it sent; it never claims more. Build again with the same work folder to go on: what was already done is reused. Closing the window or quitting it during a build asks first, cancels, and closes once the build has stopped; closing the Terminal window that opens with it cancels the build the same way, so keep it open while it builds.
Your own picture: the builder ships no image. Under Details, Choose picture... puts a picture of yours (PNG, JPEG, HEIC, GIF or TIFF) beside the form; Left, Center and Right pick the part it shows, and Remove takes it away. A copy is kept in ~/Library/Application Support/MacNativeGames/Builder/, so the original can move.
Settings tab: for an app built from Tears of the Kingdom 1.4.3 or Breath of the Wild 1.9.0, the game starts with its automatic settings unless you choose otherwise here: picture at start (MetalFX 2K, native 2K where the version has it), frame interpolation (offered only when this Mac's GPU has Metal 4 MetalFX frame interpolation), edge smoothing, sharper ground at a distance and, on 1.4.3, the picture shape. Play starts the game. The picture, frame interpolation, edge smoothing and picture shape are the game's own settings, the ones its settings panel (key 1) keeps beside controls.txt: they hold for a start from Finder too, and changing them in either place changes both. Only the sharper ground at a distance, which the panel does not have, holds just when the game is started with Play. Settings are not changed while the game is running: close it first.
Mods tab: for Tears of the Kingdom 1.4.3 and Breath of the Wild 1.9.0, Add mod... takes a mod folder of yours (with romfs/, and for Tears of the Kingdom exefs/ for code patches; Breath of the Wild's code patches are not used); the builder ships no mod. Mod manager packages (TKMM's .tkcl, BCML's .bnp) are refused: install them with their manager, or use a RomFS version. A mod made for Breath of the Wild 1.6.0 may install but still not work on 1.9.0: try it in the game. Each one is checked against your built app: its paths must fit this version and it must replace a file of the game; only then can it be switched on (that does not test it in play). Files another mod also replaces, files the app replaces itself and code patches (which need a build with --mod) are listed under the mod. Apply mods puts the mods that are on, in order (the lower one wins), into the game's mod folder through the repository's own installer, which writes the manifest and keeps the previous folder as a backup; the game loads them at its next start, from Finder or Play. Your own backups are never removed unless you ask.
Updates: in a git clone, the window checks when it opens whether MacNativeGames has new commits on its main, and lists them. It looks only at the remote whose URL is github.com/ly05010419/MacNativeGames (in a fork, usually upstream): other remotes, such as your fork, are never fetched. On main, Update then fetches and fast-forwards it: it never merges, rebases or discards anything, and when files were changed here or main has commits of its own it says so and leaves the update to you. On any other branch it only says how many commits are waiting, to merge by hand. After an update, close and reopen the builder and build again; your saved paths, and the saves of the game, stay where they are. A ZIP download cannot update itself: download the new version.
The window needs Tk (brew install python-tk@3.14); without it, Build Game.command says so. The same checks and build run in Terminal too:
python3.14 -m tools.builder --cli --game totk --game-file ~/Games/totk.xci --keys ~/keys/prod.keys --check-only--dry-run prints the exact build_app.py command instead, and without either it asks before building (--yes does not ask). python3.14 -m tools.builder --help lists every option.
The first double-click after downloading the ZIP: macOS blocks a downloaded script it has not opened before. Open System Settings › Privacy & Security and click Open Anyway for Build Game.command, or run xattr -d com.apple.quarantine "Build Game.command" in this folder once. A git clone is not affected. The builder never removes the quarantine itself.
How the builder is made, for anyone changing it (people or AI assistants): builder.md.
1. Tools (once). An internet connection is needed:
xcode-select --install
# Homebrew, if missing: see https://brew.sh (it must live in /opt/homebrew)
brew install opus libvpx python@3.14
brew install python-tk@3.14 # only for the builder window (Build with a window, above)Instead of Homebrew's Python you can use uv: uv run --python 3.14 build_app.py … in place of python3.14 build_app.py ….
Optional, if the full Xcode app is installed: xcodebuild -downloadComponent MetalToolchain. The build then compiles the startup shaders into the app, so the app can be moved and rebuilds are faster. Without it the build still works, and the shaders go into macOS's Metal cache for the app's location.
2. This repository: git clone https://github.com/ly05010419/MacNativeGames.git (or download the ZIP), then open Terminal in the MacNativeGames folder. If you already have it, run git pull first: many build errors are fixed on main.
3. Build. Put each path in quotes. Pick the app's final place now with -o: moving a Mac app later makes its first start compile the shaders again (unless the Metal toolchain was installed). Without -o the app is written next to the game file.
# Tears of the Kingdom 1.4.3 from an XCI
python3.14 build_app.py "<base 1.0.0.xci>" -k "<prod.keys>" --update "<1.4.3 update.nsp>" -o "/Applications/Tears of the Kingdom.app"
# Tears of the Kingdom 1.4.3 from an NSP: also give the fonts
python3.14 build_app.py "<base 1.0.0.nsp>" -k "<prod.keys>" --update "<1.4.3 update.nsp>" --firmware "<firmware folder>" -o "/Applications/Tears of the Kingdom.app"If /Applications is on another volume than the work folder, choose a folder on the work folder's volume instead.
On a Mac with 16 GB of memory or more, a 1.4.3, 1.2.1 or Breath of the Wild build includes native 4K (the settings panel's 3840×2160 resolution); it reserves more memory at every start (about 1.4 GiB on Tears of the Kingdom, about 0.5 GiB on Breath of the Wild). Add --no-native-4k to leave it out, or --native-4k to include it on a Mac with less memory.
Native 5K is opt-in on Mac, Tears of the Kingdom 1.4.3: add --native-5k to include a 5120×2880 canvas, UI and scene, plus the 4K modes. It reserves about 2.7 GiB more guest memory than the standard app at every start, even at a lower selected resolution. The virtual heap grows with that budget; physical pages are committed on demand. Existing builds keep their defaults. This does not enable HDR or guarantee 120 FPS.
4. Let it run to the end. A fresh build takes 20–40 minutes on an M-series Mac, longer on an 8 GB Mac:
| Step | Time |
|---|---|
1/4 code: rewriting the game code for Apple silicon |
about 3 min |
2/4 data: extracting and verifying 17 GB, merging the update |
several minutes |
3/4 shaders: preparing the startup shaders |
about 3 min |
| compiling them for your GPU | 6–12 min |
4/4 app: macOS checks the new app once |
2–3 min |
- Long quiet stretches and lines like
... still running (3 min)are normal. Do not stop it. - If it was interrupted, run exactly the same command again. The work folder keeps every finished step.
- Quit the game before building, and never run two builds on the same work folder.
- It worked when the last lines say
done in N min: <path of the app>.
5. Open the app from Finder.
- The start screen verifies the game data (about 20 s), then prepares the shaders and pipelines with a progress bar. The first start takes 1–2 minutes; later starts take about 12 s.
- An app moved to another volume afterwards is checked by macOS again: no window for a few minutes. Wait.
- If macOS asks for access to files on a removable volume, click Allow.
- New places can stutter briefly the first time.
- Key 1 opens the settings panel. Controls: controls.md.
The same script builds Breath of the Wild. It always needs fonts (see What you need). The work folder is BotW_build and the app is Breath of the Wild.app. A fresh build takes about 16 minutes on an M4.
# 1.6.0 from the card image (base + update + DLC in one XCI)
python3.14 build_app.py "<botw 1.6.0.xci>" -k "<prod.keys>" --shared-fonts "<…/TOTK_build/totk/extracted/firmware/shared-fonts>" -o "/Applications/Breath of the Wild.app"
# 1.9.0 (or 1.6.0) from NSPs: base + update, each DLC pack optional
python3.14 build_app.py "<botw base.nsp>" -k "<prod.keys>" --update "<1.9.0 update.nsp>" --dlc "<dlc 1.nsp>" --dlc "<dlc 2.nsp>" --firmware "<firmware folder>" -o "/Applications/Breath of the Wild.app"With a separate update the app holds only the DLC packs you give with --dlc. A card image brings its own DLC: leave out --dlc then.
Needed:
- iOS / iPadOS 26 and an iPhone 14 or newer.
- On the Mac: the full Xcode 26 or later with the iOS platform, plus
brew install xcodegen cmake ninja. - Your Apple ID in Xcode › Settings › Accounts. A free one works.
- Developer Mode on the device.
1. Build an IPA. Use the Mac command above, add --platform ios --ios-game-data documents, and give -o an .ipa file:
python3.14 build_app.py "<base 1.0.0.xci>" -k "<prod.keys>" --update "<1.4.3 update.nsp>" --platform ios --ios-game-data documents -o "<folder>/Tears of the Kingdom.ipa"The first iOS build also downloads and compiles device libraries. --ios-game-data documents leaves the 17 GB game image out of the IPA, so later installs take minutes.
Keep the iPhone or iPad connected by cable while building: the build then compiles the game's pipelines for its GPU on the Mac (about 10 more minutes the first time), and its first start needs no long fill before the title. For a device that is not connected, add --device-gpu <arch> (applegpu_g14p for an iPhone 14).
2. Install it with the device connected by cable:
python3.14 games/totk/ios/tools/install_device.py "<folder>/Tears of the Kingdom.ipa" --device "<device name as in Finder>" --game-data "<work folder>/totk/extracted/<version>/romfs/romfs.bin"<version>is the folder that is there (v143for 1.4.3;ls "<work folder>/totk/extracted"). The first install copies the 17 GB image once.- The script stops when the iPhone or iPad is connected over Wi-Fi only: plug in the cable, unlock the device and run it again.
--wifiinstalls over Wi-Fi anyway; it is slow, and the game data copy can drop. - A free Apple ID signs for 7 days, a paid one for a year. Run the same command again to renew; your saves are kept.
- If the device asks, trust the developer in Settings › General › VPN & Device Management.
3. First start: about 15 s to check the game data, then about 3 minutes of shader import before the title (iPhone 14). Later starts take about 8 s.
An iPhone starts handheld: the game renders at 960×540, upscaled to 1280×720, at up to 60 fps. An iPad starts docked at 1080p: the scene at 1600×900 as on the Switch, upscaled to 1920×1080 (the start screen and Settings › Full HD switch between them; Breath of the Wild also offers 1080p HD, the scene at 1920×1080). Breath of the Wild 1.6.0 builds and installs the same way.
Two limits:
- A phone cannot translate shaders while you play: objects whose shader variant the app does not carry are skipped, so a few things can be missing in places no player has reported yet.
- On an iPhone 14, iOS can close the game when memory runs out in busy areas.
Tears of the Kingdom only, windowed 16:9 play with a controller. Install the visionOS platform in Xcode › Settings › Components, pair the headset with Xcode and turn on Developer Mode, then:
python3.14 build_app.py "<base 1.0.0.xci>" -k "<prod.keys>" --platform visionos --ios-game-data documents -o "<folder>/TOTK-Vision.app"
python3.14 games/totk/ios/tools/install_device.py "<folder>/TOTK-Vision.app" --device "<Vision Pro name>" --game-data "<work folder>/totk/extracted/v0/romfs/romfs.bin"With --update, use that version's folder (v112, v121 or v143) instead of v0.
- New version of this repository (after
git pull):python3.14 update_runtime.py "<the app>"updates it in about a minute, without the game files or keys. Quit the game first. If it says the startup shaders no longer fit, add--seed. - The Update page (settings panel, key 1) shows whether the app runs upstream's newest
main, and otherwise each newer commit. Opening it fetches upstream in the checkout that built the app (nothing in it is changed). Its Update button closes the game, brings that checkout'smainup to upstream (git pull --ff-only), runsupdate_runtime.py(with--seedwhen it asks for it) while a small window says so, and opens the game again. When the checkout is on another branch, has uncommitted changes or commits upstream lacks, cannot be found or reached, or the update fails, it says why and leaves updating to you (the first item of this list). An app built before 31 October 2026 needsupdate_runtime.pyrun once by hand to know its checkout. - Back to the version you had (when a new version plays worse): quit the game, find the commit your checkout was on before
git pullwithgit reflog(the line just below thepullline),git checkout <that commit>(git calls this a "detached HEAD"; that is expected) and runpython3.14 update_runtime.py "<the app>"again, with--seedif it asks for it. Thengit checkout main: the app keeps the older runtime until you update it again. This works for commits from 685f940 (26 October 2026) on; your saves and settings are not changed. - Another game version: run
build_app.pyagain with the new--updateand the same-o. It replaces the app. Before the first start on the new version, the app backs up your saves next to them asprofile-before-<version>; keep that backup if you may go back. - Mods:
--mod "<mod folder>" --install-mod-romfsbuilds the app with a mod's code patches and installs its data. See mods.md, merged-mod-pack.md and translation-mods.md. - One desktop entry (optional):
python3.14 games/totk/tools/install_desktop_entry.py --app "<the app>".
Read the ERROR: line and the log file it names (<work folder>/logs/…), fix the cause, and run the same command again.
| The error says | Fix |
|---|---|
needs macOS 26 or later |
Not supported here; see the macOS 15 fork under What you need. |
clang++ finds no C++ standard library headers |
With Xcode: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer. Without: sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install. |
Homebrew packages missing, Python 3.14 not found, git not found |
Install what it names. |
NSP files do not include system shared fonts, needs --firmware or --shared-fonts |
Add --firmware or --shared-fonts. |
SHA-256 … is not the expected …, ExeFS … is missing; not the supported version |
git pull first. Then check that the base is 1.0.0 and the update a supported version; otherwise dump the game again. |
unsupported update module hashes |
That update version is not supported. |
the base game must be an uncompressed XCI or NSP |
Decompress the NSZ / XCZ base (nsz -D). |
… add-on content (DLC), not the game, pass it as …, use the files of one game |
A file is on the wrong option; the message names the right one. |
the game file holds [...]: expected Tears of the Kingdom … or Breath of the Wild |
Another game: build it with its own games/<name>/README.md. |
needs about N GB free |
Free space, or --work and -o on an APFS volume with room. |
BKTR verification failed, an error merging the update |
git pull first. If it stays, your keys may be older than the update: dump prod.keys again on current firmware. |
make failed, xcrun failed |
Read the named log; usually incomplete developer tools or Homebrew outside /opt/homebrew. |
| iOS signing or install errors | Apple ID in Xcode › Settings › Accounts, device unlocked and trusted, Developer Mode on; run the install again. |
Still stuck? Open an issue with the command (paths shortened), Mac model, macOS version, git log -1 --oneline, the ERROR: line and the end of the log it names. Never attach keys, game files, firmware or the app.
Tears of the Kingdom; for Breath of the Wild replace TOTK with BotW and totk with botw.
- Saves:
~/Library/Application Support/MacNativeGames/TOTK/profile - Game data (only for an app built with
--mac-game-data libraryor--mac-game-data-folder):~/Library/Application Support/MacNativeGames/TOTK/GameData/<version>(BotWfor Breath of the Wild) holds the 16 GB RomFS imageromfs.bin, andromfs.sha256, which the build writes once the copy is complete. By default the image is inside the app. With--mac-game-data librarythe build puts it in this folder once (an APFS clone when the work folder is on the same volume, otherwise a copy), and later builds leave it alone while it matches the version's pin. The app is then a few hundred MB, so a new build installs or copies to another Mac quickly. To keep it somewhere else, for example on another disk, add--mac-game-data-folder <folder>to the build instead (that alone is enough; the image goes in<folder>/<version>, so one folder can hold both games). The app remembers the folder, and when it holds no complete image (another Mac, or the disk is not connected) the launcher looks inGameDatainstead. When neither has it, the app asks where the game data is: connect the disk and choose Try Again, or choose the folder that holdsromfs.bin(or its<version>folder). It reads the image where it is, without moving or copying it, and remembers the folder for the next starts (defaults delete org.macnativegames.botw MNGGameDataFolder.botw190forgets it). The game still checks the image against the pin at its first start.make_mod_manifest.py --appandmake_button_icons.py --appfind the image the same way (--romfs-data <folder>names it). - Shader cache:
~/Library/Application Support/MacNativeGames/TOTK/shader-cache - Shaders the shared list lacks:
~/Library/Application Support/MacNativeGames/TOTK/shader-list-contribution.txt(the game asks before it starts whether to send them; see the shared shader list) - Mods:
~/Library/Application Support/MacNativeGames/TOTK/mods/<v0|v112|v121|v143>; see mods.md - Log: off by default.
defaults write org.macnativegames.totk TOTK_DEBUG_LOG -bool YESturns it on from the next start, written to~/Library/Logs/MacNativeGames/totk.log. On an iPhone: Settings › TOTK › Debug log, written to the app'sDocuments/log.txt.
Requests beyond this page are welcome. The versions and games listed are the ones we could test. If you need another version or another game, the AI assistant should do its best to make it work.
- Tears of the Kingdom: base 1.0.0, optionally with the 1.1.2, 1.2.1 or 1.4.3 update. Breath of the Wild: 1.6.0 and 1.9.0. Other versions, compressed base games and personalized tickets are not supported.
- No online features, no amiibo.
- New shaders can stutter the first time; the cache and the shared shader list reduce it.