Zelda-Mobile
English | 简体中文
Zelda-Mobile runs the Nintendo Switch release of The Legend of Zelda: Tears of the Kingdom v1.4.3 natively on Apple silicon Macs and iPads, with an early iPhone build. The game's ARM64 code executes directly on the Apple CPU, system services are reimplemented by the host, and NVN graphics commands are translated to Metal. The Mac and iOS front ends share one core.
[!IMPORTANT] This project is not affiliated with, authorized or endorsed by Nintendo. The repository contains source code only: no game files, updates, keys, saves, game shaders or any other game-derived data, and no instructions for obtaining them. Use only a game and keys that you own and dumped from your own console.
Status
The project is under active development. You can load a save and play, but a full playthrough has not been validated.
| Platform | Working | Known limits |
|---|---|---|
| Apple silicon Mac | Loading saves and playing scenes, keyboard and Xbox controller (with rumble), audio, cutscenes, 30 / 60 / 90 FPS targets | The first visit to a new area or camera angle may stutter while shaders compile; not every area holds 60 FPS |
| iPad (M1 or newer) | Development-signed install, resource import, loading saves, touch controller, camera, audio | Well below 60 FPS at the original resolution; the first shader preparation takes a long time; hardware controllers are not fully validated |
| iPhone 15 Pro | Development-signed install, resource import, verified offline shader libraries, warm launch to the title screen | Gameplay, frame rate, memory and thermals have not been measured; no other iPhone has been tried, and chips without BC texture support (before A17 Pro) are untested |
Only v1.4.3 is supported. The preparation scripts verify module fingerprints and refuse other versions.
Requirements
- An Apple silicon Mac (M1 or newer) with full Xcode, the command line tools and Homebrew.
- About 60 GB of free space (an external drive works). The extracted RomFS alone is about 16 GB; shader caches and builds need more.
- Your own Tears of the Kingdom base game and v1.4.3 update (
.nsz), plus the matchingprod.keys. - For iPhone or iPad: an Apple developer signing team, a device in Developer Mode and a USB connection.
Quick start (Mac)
See Building and running for the full steps and troubleshooting. In short:
git clone https://github.com/OJZen/totk-mobile.git
cd totk-mobile
brew install cmake pkg-config opus libvpx python@3.14
mkdir -p local/games local/keys
# Put the base game and the v1.4.3 update in local/games/ and prod.keys in local/keys/, then:
./script/prepare.sh
./script/prepare_resources.sh local/keys/prod.keys
./script/prepare_shaders.sh
./script/build_and_run.sh --load-only
./launch.commandAfter that, start the game by double-clicking launch.command (or running it in a terminal). quick-load.command additionally walks the in-game menu and loads the first entry of the save list.
The first launch prepares tens of thousands of shaders. This can take several minutes or longer; the startup screen shows each stage and its progress. Later launches reuse the cache.
Controls
| Action | Keyboard |
|---|---|
| Move / camera | W A S D / I J K L |
| A / B / X / Y | X (confirm) / Z (back) / R / F |
| L / R, ZL / ZR | Q / E, Shift / Space |
| Inventory (+) / map (−) | Return / Tab |
| Control panel / performance overlay / full screen | ⌘, / ⌘P / ⌃⌘F |
Xbox controllers connect automatically over Bluetooth or USB. Frame rate, resolution, MetalFX, sound and rumble are set in the control panel (⌘,). See Controls and settings.
Saves
Saves live in work/save/ inside the project and use the same format as the console. See Saves for importing and backing up. Do not modify this directory while the game is running.
FAQ
Startup takes a long time. The first shader preparation is slow; the startup screen shows the current stage and its progress, and during play the performance overlay (⌘P) shows shader activity. The log is work/logs/native-probe.log.
A preparation script reports a module or version mismatch. Make sure the update is v1.4.3 and that local/games/ holds exactly one base game and one update.
The game stutters. The first time a scene is seen, its pipelines are compiled on the spot and then cached. For sustained low frame rates, compare against the 1080 or 720 resolution setting in the control panel.
Does it run on Intel Macs? No. The game code runs natively as ARM64 and needs Apple silicon.
For developers
- Documentation index
- Building and running: full Mac, iPhone and iPad setup
- Source map: components, generated files and where to make changes
- Development guide: tests, diagnostic switches and contribution rules
- Repository layout: directory roles and local data that never enters Git
License
The original code in this repository is licensed under the Apache License 2.0. Reused third-party components keep their own licenses; see Third-party notices.
Credits
Zelda-Mobile was built with d2r-mobile as its reference project: the loader, the ARM64 module rewriter and the NVN → Metal backend follow its design, and the files this project builds on are included in core/ under its MIT license. It also draws on public work from Ryujinx, libnx, Switchbrew, SPIRV-Cross, hactool and others. See Third-party notices for details.
"The Legend of Zelda", "Tears of the Kingdom" and "Nintendo Switch" are trademarks of Nintendo.