Reading the repo
Reading the repo
How to install on macOS
Play your own Tears of the Kingdom and Breath of the Wild natively on Apple silicon Mac, iPhone and iPad. Not an emulator: the game's ARM64 code runs directly, NVN rebuilt on Metal. Bring your own game.
Saved setup from 3 h ago
Will it work on my device?
docs/install.mdThis 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.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 |
--update you get 1.0.0.nsz -D).--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 .nca files (unzip it first), or an installed firmware registered folder.--shared-fonts <folder>: the six .bfttf files an earlier Tears of the Kingdom build extracted, in TOTK_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.
On Mac, Tears of the Kingdom 1.4.3 and Breath of the Wild 1.6.0 / 1.9.0 include native 5K (5120×2880 canvas, UI and scene, plus the 4K modes) by default when the build Mac has 32 GB of memory or more. A 16 GB or 24 GB Mac keeps the 4K default. --native-5k enables it on a smaller Mac; --no-native-5k leaves it out, and --no-native-4k also disables automatic 5K. This adds a resolution choice, without changing the saved selection or automatically selecting 5K. On Tears of the Kingdom, it reserves about 2.7 GiB more guest memory at every start, even at a lower selected resolution; physical pages are committed on demand. This does not enable HDR or guarantee 120 FPS.
A runtime update remembers an explicit 5K on/off choice. Without one, it adds the 4K/5K resources on a 32 GB-plus Mac when the work folder still holds this app's matching, verified game files; no new game container or keys are needed. An existing 5K app keeps that capability on a smaller Mac. If that cache is missing or the app has modded heap overlays, an automatic update keeps the installed canvas and explains that a full rebuild is needed. For Tears of the Kingdom, update_runtime.py --native-5k requires a usable cache; Breath of the Wild enables its code-owned heaps without generating RomFS overlays; --no-native-5k removes 5K while keeping 4K. Both leave the saved resolution files alone.
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 |
... still running (3 min) are normal. Do not stop it.done in N min: <path of the app>.5. Open the app from Finder.
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:
brew install xcodegen cmake ninja.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 (v143 for 1.4.3; ls "<work folder>/totk/extracted"). The first install copies the 17 GB image once.--wifi installs over Wi-Fi anyway; it is slow, and the game data copy can drop.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:
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 (v121 or v143) instead of v0.
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.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's main up to upstream (git pull --ff-only), runs update_runtime.py (with --seed when 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 needs update_runtime.py run once by hand to know its checkout.git pull with git reflog (the line just below the pull line), git checkout <that commit> (git calls this a "detached HEAD"; that is expected) and run python3.14 update_runtime.py "<the app>" again, with --seed if it asks for it. Then git 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.build_app.py again with the new --update aNeeds Git: xcode-select --install
git clone https://github.com/ly05010419/MacNativeGames.git cd MacNativeGames
We couldn't spot a known stack. Start with the README, or ask an AI below to go through it with you.
The install skill (
.claude/skills/install-zelda/SKILL.md) is a short guide written for the assistant: which of your files goes where, the command for your case, how long each step takes (a build is 20–40 minutes; it must not be stopped), and the fix for each common error. Claude Code finds it by itself (or type/install-zelda). With any other assistant, start with: "Read .claude/skills/install-zelda/SKILL.md and follow it to install Tears of the Kingdom for me."Red Alert 2 has its own:
.claude/skills/install-ra2/SKILL.md(/install-ra2), for the Mac and iPhone / iPad builds, the movies made smaller for the phone and the Chinese languages. "Read .claude/skills/install-ra2/SKILL.md and follow it to install Red Alert 2 for me."
No reports for macOS yet.
Opens a chat with this manual already filled in, for macOS. It uses your own account; gitmanual sends nothing.