Play Tears of the Kingdom Natively on Mac: A MacNativeGames Build Guide

If you want to play Tears of the Kingdom on a Mac, MacNativeGames offers a way to build a native app from your own game files. It adapts the game’s ARM64 code to run on Apple silicon, renders its graphics through Metal, and packages the result as an app you can open in Finder. Most of the setup happens during the first build.

This guide is for Mac users who may be unfamiliar with build tools. It covers installing dependencies, building the base game or an updated version, and setting up controls, graphics, and save backups. It covers the Mac version only.

1. Check the requirements

Hardware and storage

Item	Requirement
Mac	An Apple silicon model, such as M1, M2, M3, M4, or M5; this workflow does not cover Intel Macs
System	macOS 26 or later, using the project’s Metal 4 backend
Memory	The project recommends at least 16 GB; an 8 GB machine may use substantial swap during the build
Storage	About 25 GB beyond the original game files for a base build, or about 40 GB for a fresh base-plus-update build
Network	Required to install dependencies and fetch pinned build sources

These storage estimates assume the work folder and finished app are on the same APFS volume, where cloning can share large data files. If cloning is unavailable or you put the app on another volume, allow roughly another 17 GB for the app copy. Make room before starting if your disk is nearly full.

Game files

Have these ready:

• Your own version 1.0.0 base game, as an uncompressed XCI or NSP, with title ID 0100F2C0115B6000.
• Your own prod.keys.
• For an updated build, a separate cumulative update package for 1.1.2, 1.2.1, or 1.4.3, in NSP or NSZ format.
• System shared fonts if you use an NSP base, as explained below.

The revision used here does not support compressed NSZ/XCZ base games, DLC, combined packages, or personalized tickets. NSZ support applies to updates. To build 1.4.3, supply the 1.0.0 base and the separate cumulative 1.4.3 update; intermediate updates are unnecessary.

2. Install the build tools

Open Terminal and install the Xcode command line tools:

xcode-select --install

If macOS says they are already installed, continue. Otherwise, wait for the installer to finish.

Install Homebrew using its official instructions, including the shell setup printed at the end. Its default Apple silicon prefix is /opt/homebrew; see the Homebrew installation documentation.

Check that Terminal can find it, then install the dependencies:

brew --version
brew install opus libvpx [email protected]
python3.14 --version

The final command should report Python 3.14.x. Use python3.14 throughout this guide to avoid selecting another Python installation.

This revision’s Mac build does not require .NET, CMake, or the iOS toolchain. The script prepares its remaining environment, and the finished app does not need Python to run.

Optional: install the Metal toolchain

If you have the full Xcode application, install the Metal toolchain following Apple’s additional-component documentation:

xcodebuild -downloadComponent MetalToolchain

The project uses this to compile startup shaders into the app. If you only have the command line tools, you can skip this step. The build can still proceed using the Mac’s Metal cache for the app’s location, which matters if you move the app later.

3. Download the source and organize your files

The following puts the source under ~/Projects. If you already downloaded it elsewhere, enter that directory instead.

mkdir -p "$HOME/Projects"
cd "$HOME/Projects"
git clone https://github.com/ly05010419/MacNativeGames.git
cd MacNativeGames
git checkout 30a1b93d0776150fbaffd7c20f9a5ca0841c21c9

The final command selects the revision used in this article. Git may display a detached HEAD notice; that is normal when selecting a specific commit and does not prevent building.

The examples below assume this layout. Replace the sample filenames and paths with your own.

~/Games/TOTK/
  base.xci            Base game; base.nsp for the NSP route
  update-1.4.3.nsp     Optional separate update
  firmware/           Needed for the NSP route; contains unpacked .nca files

~/keys/
  prod.keys

Create a personal Applications folder for the finished app:

mkdir -p "$HOME/Applications"

~/Applications is inside your home directory and differs from the system-wide /Applications. It normally needs no administrator privileges. Building directly to the intended location also reduces the need to rebuild location-dependent shader caches later.

4. Choose your build command

Run the following from the MacNativeGames source directory. Choose the command that matches your files; you do not need to run every example.

XCI base: build version 1.0.0

python3.14 build_app.py "$HOME/Games/TOTK/base.xci" \
  -k "$HOME/keys/prod.keys" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

This builds 1.0.0. An XCI usually supplies shared fonts through its system update partition. If that partition is missing, add --firmware or --shared-fonts as described next.

NSP base: supply the shared fonts

An NSP base does not include system shared fonts, so provide an unpacked firmware directory:

python3.14 build_app.py "$HOME/Games/TOTK/base.nsp" \
  -k "$HOME/keys/prod.keys" \
  --firmware "$HOME/Games/TOTK/firmware" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

The firmware path must point to a directory containing .nca files, or an installed firmware’s registered directory. Do not pass a firmware ZIP archive directly.

If you previously extracted the fonts, replace --firmware and its path with:

--shared-fonts "$HOME/Games/TOTK/TOTK_build/totk/extracted/firmware/shared-fonts"

That is an argument fragment to insert into the build command. The directory must contain the six files from 0-standard.bfttf through 5-nintendo-extension.bfttf. The builder validates them and can reuse valid fonts already in the work folder. Ordinary macOS fonts are not substitutes.

Base plus update: build version 1.4.3

For an XCI base and a separate update:

python3.14 build_app.py "$HOME/Games/TOTK/base.xci" \
  -k "$HOME/keys/prod.keys" \
  --update "$HOME/Games/TOTK/update-1.4.3.nsp" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

For an NSP base, keep the font argument:

python3.14 build_app.py "$HOME/Games/TOTK/base.nsp" \
  -k "$HOME/keys/prod.keys" \
  --firmware "$HOME/Games/TOTK/firmware" \
  --update "$HOME/Games/TOTK/update-1.4.3.nsp" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

If your update is an NSZ, change the --update path to that .nsz file; the builder handles decompression and verification. For 1.1.2 or 1.2.1, supply that version’s cumulative update instead. Omitting --update builds 1.0.0; updates are not selected automatically.

Argument	Purpose
File path after build_app.py	The 1.0.0 base game
-k	Your keys file
--update	Optional separate cumulative update
--firmware / --shared-fonts	Alternative font sources; use one
-o	Full output path, ending in .app
--work	Optional custom intermediate-file directory

Without -o, the app is written next to the base game. With the file layout above, the default work folder is ~/Games/TOTK/TOTK_build; it holds extracted data and build logs. After fixing a recoverable error, rerun the same command to reuse completed steps before considering removal of the whole work folder.

How long does it take?

The script extracts and verifies game data, rewrites code modules, prepares shaders, and packages and signs the app. Let it continue while progress is being reported. Memory, storage, network speed, and shader compilation all affect the first build.

The project reports that GPU shader compilation alone can take around 25 minutes on an 8 GB M1 MacBook Air. This helps explain a long wait; it is not an estimate for your complete build.

At the end, the script runs the launcher in --check mode. That completes executable checks and related startup checks. You still need to open the game to verify graphics, sound, and controls.

5. Let the first launch finish preparing

In Finder, press Command + Shift + G, enter ~/Applications, and open Tears of the Kingdom.app. Alternatively:

open "$HOME/Applications/Tears of the Kingdom.app"

The first launch verifies game data and prepares shaders. The project observed roughly 20 seconds for data verification locally; your wait depends on the machine and cache state. Allow visible progress to finish.

Shader warm-up can continue behind the title screen, with another wait when first entering the world. The builder already generates startup shaders from your game data and the shared shader list, so a cache downloaded from another player is normally unnecessary.

Unvisited scenes may still need new shader variants and briefly stutter. First-use compilation and persistently low frame rates call for different checks. If a second visit is noticeably smoother, the cache is helping. If it stays slow, investigate graphics settings, memory pressure, and the particular scene.

Can you move the app?

Yes, though choosing its destination before building is useful:

• With the Metal toolchain: the app carries its precompiled startup shader libraries and can use those after moving.
• Without the Metal toolchain: the Mac’s compiled shader cache is associated with the app’s location. Moving the app may trigger recompilation, as can a system cache cleanup.

This is why the examples use -o to build directly to the final directory. Copying across volumes can also require another copy of the game data and another macOS app check.

6. Controller and keyboard controls

Controllers: watch the confirm button’s position

Compatible controllers recognized by macOS, such as DualSense and Xbox controllers, are mapped to a Switch Pro Controller. The default face-button mapping follows position:

Physical position	Switch button	Xbox	PlayStation
Right	A: confirm / interact	B	Circle
Bottom	B: cancel / sprint	A	Cross
Top	X: jump	Y	Triangle
Left	Y: attack	X	Square

An on-screen A prompt therefore corresponds to the right-hand B button on an Xbox controller by default. Motion and rumble depend on the controller and what macOS exposes.

Custom controller mappings go in:

~/Library/Application Support/MacNativeGames/TOTK/controls.txt

For example, assign a DualSense touchpad click to the map button:

touchpad = minus

Unspecified buttons keep their defaults. Restart the game after editing. If the launcher reports an invalid line, check that line; deleting the configuration file restores the defaults.

Keyboard layout for this revision

These are the defaults at the commit used in this guide. Keys refer to physical US keyboard positions. For other revisions, check their README and in-game shortcut display.

Mac key	Action
W, A, S, D	Move: left stick
Arrow keys	Camera: right stick
J	A: confirm / interact
K or Space	B: cancel / sprint
I	X: jump
U	Y: attack
Q / E	L / R
Option / Shift	ZL / ZR
F, T, H, G	D-pad left, up, right, down
Z / C	Left / right stick click
Return	Menu (+)
Tab or Esc	Map (−)

7. Adjust graphics one setting at a time

First enter the game with its default settings and check basic controls. Then try the number keys one at a time so you can identify the effect of each change.

Key	Function
1	Cycle full overlay, FPS only, and hidden
2	Cycle interpolation: off, 30+30, half refresh rate, unlimited
3	Cycle MetalFX 2K, native 2K, and off
4	Cycle 16:9, fit to window/display, and 21:9; versions 1.2.1 / 1.4.3
5	Toggle MetalFX temporal anti-aliasing; version 1.4.3

Two details help interpret the results:

• Interpolated frame counts include generated frames and do not directly represent the game’s logic frame rate.
• Native 2K changes the composition canvas and UI. The 3D scene has separate render scaling, so this does not force every internal render target to 1440p.

The game follows your Mac’s language. To temporarily select Simplified Chinese, fully quit the game and launch it with:

open --env TOTK_LANG=zh-Hans "$HOME/Applications/Tears of the Kingdom.app"

That environment variable applies to this launch. Running open again while the app is already running does not reload its startup environment.

8. Find and back up your saves

The app, build work folder, and personal saves are stored separately:

Content	Location
App in this guide	~/Applications/Tears of the Kingdom.app
Default work folder in this guide	~/Games/TOTK/TOTK_build
Save profile	~/Library/Application Support/MacNativeGames/TOTK/profile
Shader cache	~/Library/Application Support/MacNativeGames/TOTK/shader-cache
Current run’s log	~/Library/Logs/MacNativeGames/totk.log
Previous run’s log	~/Library/Logs/MacNativeGames/totk.previous.log

Use Command + Shift + G in Finder to open these locations.

Before changing game versions, quit the game and copy the entire profile folder somewhere safe. Before an updated version starts, the project also creates a backup beside the profile, such as profile-before-1.4.3; startup stops if that backup fails. Keep your pre-upgrade backup for a rollback: a newer save may not work with an older game version.

To update the project’s code, obtain the desired newer source and rebuild using the original base game, the same update package, and the same output path. Quit the running game first, and preserve necessary arguments such as --firmware, --shared-fonts, and --work. Building to the same path replaces the app; saves remain in the separate user directory above.

9. Troubleshooting

Terminal cannot find brew or python3.14

Complete the shell setup printed by the Homebrew installer, reopen Terminal, and repeat the version checks in section 2. An existing python3 command may point to another version. Use the Apple silicon Homebrew installation to avoid mixing dependencies from an Intel environment.

Shared fonts are missing

Check the base format. NSP requires --firmware or --shared-fonts; an XCI missing its system update partition needs them too. The firmware must be unpacked, and an extracted font directory must contain the six .bfttf files.

A version or hash check fails

Check that the base is 1.0.0, the update is a supported separate cumulative package, the files are intact, and your keys match your content. Validation detects unsupported or damaged inputs. Do not edit the expected hashes to bypass the failure.

No game window appears after opening the app

First launch, moving the app, or copying it across volumes can trigger system checks or data verification. Look for progress and inspect the log. If an explicit error appears, address it. A successful build-time --check does not establish that gameplay works.

Stutter persists or memory pressure is high

Close other memory-heavy applications and inspect memory pressure and swap in Activity Monitor. Use key 3 to disable additional 2K modes for comparison, wait for background warm-up, and revisit the same scene. Avoid judging final performance during first-use compilation. Clearing every cache is not a routine optimization: the shaders would need to be prepared again.

Effects play, but dialogue or music is missing

Check the selected macOS audio output and volume, then look for CoreAudio or decoder errors in the log. The project includes a streamed-audio path fix; see its audio troubleshooting guide. If using an early app, rebuild from source containing the fix with your original game files. Compilation stalls can also interrupt playback and need separate diagnosis.

You want to install mods

Complete a build and launch without mods first. Then follow the project’s mod documentation. Code patches are merged at build time with --mod; RomFS data has separate installation and manifest requirements. Do not drop another environment’s mod folder into the app bundle.

References

• MacNativeGames README at the revision used here
• Build script and argument definitions
• First-launch shader preparation
• Homebrew installation documentation
• Apple: downloading and installing additional Xcode components