MacNativeGames 完整构建指南:Apple 芯片 Mac 如何一次跑通《塞尔达传说:王国之泪》原生运行

MacNativeGames 完整构建指南:Apple 芯片 Mac 如何一次跑通《塞尔达传说:王国之泪》原生运行

【免费下载链接】MacNativeGames 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. 【免费下载链接】MacNativeGames 项目地址: https://gitcode.com/gh_mirrors/mac/MacNativeGames

MacNativeGames 是一个让《塞尔达传说:王国之泪》在 Apple 芯片 Mac 上原生运行的开源项目:游戏自身的 ARM64 代码直接跑在苹果芯片上,图形层 NVN 重建在 Metal 之上,不是模拟器。你自备游戏文件与密钥,一条命令就能构建出可玩的 Mac App,从环境核对到构建完成,顺利的话一两个小时可跑通。读完本文,你会知道该准备哪些文件、装哪些依赖、构建命令怎么写,以及常见报错怎么对症处理。

⚖️ 合规提示:你必须拥有正版《王国之泪》,并使用从你自己 Switch 导出的 prod.keys 与系统文件。仓库内不含任何游戏内容,构建出的 App 仅供个人使用,请勿分享。

快速上手:一条命令构建 TOTK App

先克隆仓库,再运行构建脚本(下面以 XCI 本体为例,这是最短路径):

git clone https://gitcode.com/gh_mirrors/mac/MacNativeGames
cd MacNativeGames
python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys

命令参数逐个解释:

  • ~/Games/totk.xci:第一个位置参数,游戏文件路径。要求是 1.0.0 本体(标题 ID 0100F2C0115B6000)、未压缩的 XCI 或 NSP
  • -k ~/keys/prod.keys:你从自己 Switch 导出的密钥文件路径,构建全程不会打印密钥值
  • 默认输出就在游戏文件旁边的 Tears of the Kingdom.app,无需其他参数

脚本启动时会逐项检查环境(芯片、系统版本、依赖、空间),任何一项不达标都会立即报错停止,所以下面的环境表建议先核对一遍。构建分 4 大步:1/4 代码(提取并改写三个代码模块)→ 2/4 数据(解密 17 GB RomFS)→ 3/4 着色器(翻译启动着色器)→ 4/4 打包(组装、签名、macOS 首次检查),每步日志写入 TOTK_build/logs/。工作目录 TOTK_build 默认建在游戏文件旁,可用 --work 改位置;再跑一次会复用已完成步骤,可以断点续跑。

环境要求:硬件、系统与文件核对表

检查项要求不满足的后果
芯片Apple silicon(M 系列)报错 needs a Mac with Apple silicon,Intel Mac 不支持
系统macOS 26 或更高(macOS 27 兼容)图形层依赖 Metal 4,报错 needs macOS 26 or later (Metal 4)
内存建议 16 GB 或更多游戏运行时需要较大的虚拟内存布局
磁盘工作目录约 25 GB 空闲,另加游戏文件本身报错 needs about 25 GB free for the work folder
游戏文件本体 1.0.0,未压缩 XCI 或 NSPNSZ/XCZ 报错 the base game must be an uncompressed XCI or NSP;文件损坏或非 1.0.0 报 SHA-256 校验失败
密钥你自己的 prod.keys无法完成解密,必须通过 -k 传入
更新包(可选)1.1.2 / 1.2.1 / 1.4.3 累计更新,NSP 或 NSZ版本不支持时报错,见排障表
字体来源(可选)NSP 本体需要 --firmware 或 --shared-fonts报错 NSP files do not include system shared fonts

💡 小提示:磁盘空间有一处可以"省下来"——成品 App 与游戏文件放在同一 APFS 卷时,17 GB 级数据文件通过克隆共享、不占额外空间;如果输出到其他卷,需要另留约 17 GB。XCI 本体默认从其系统更新分区提取字体,一般无需额外操作;NSP 则必须补充字体来源,这是新手最高频的卡点之一。

依赖安装:Xcode 命令行工具与 Homebrew 一键命令

必装依赖只需一次性安装,之后每次构建不再联网装环境:

xcode-select --install
brew install opus libvpx python@3.14

必装依赖及用途:

  • Xcode 命令行工具:提供 clang、git、make 等构建基础,缺失时报 the Xcode command line tools are missing
  • opus:Homebrew 包,负责游戏音频解码
  • libvpx:Homebrew 包,负责预渲染影片(VP9)解码
  • python@3.14:构建脚本指定使用 3.14(要用标准库读 zstd 流),系统自带的旧版 Python 不满足要求,缺失时报 Python 3.14 not found

构建所需的 Python 库(cryptography、lz4、capstone、nsz)由脚本自动装入工作目录的虚拟环境,你不需要手动处理,清单见 games/totk/requirements.txt。

推荐安装项:

xcodebuild -downloadComponent MetalToolchain
  • Metal 工具链(强烈推荐):装上后构建时把启动着色器预先编译进 App 内部(1.4.3 在 M4 上约 6 分钟);没有它只能编进 macOS 的 Metal 缓存,而这份缓存不跟着 App 走——之后挪动 App 或系统清理缓存,首次启动都要重新编译几分钟并可能卡顿

iPhone / iPad 构建属于额外工具链:需要完整 Xcode 26+(含 iOS 与 Metal 工具链)并执行:

brew install xcodegen cmake ninja

首次 iOS 构建需联网下载并编译设备端库,建议预留 45 GB(带更新包 60 GB)临时空间。

场景变体:NSP 字体、更新包与 iOS 打包命令

按"一个场景一条命令"整理如下:

场景 1:NSP 本体 + 固件目录补字体

python3.14 build_app.py ~/Games/totk.nsp -k ~/keys/prod.keys --firmware ~/Games/firmware

--firmware 指向固件 NCA 目录,用来补 NSP 里缺失的系统共享字体。

场景 2:NSP 本体 + 复用上次提取的六个 .bfttf 字体

python3.14 build_app.py ~/Games/totk.nsp -k ~/keys/prod.keys --shared-fonts /path/to/TOTK_build/totk/extracted/firmware/shared-fonts

场景 3:构建 1.1.2 / 1.2.1 / 1.4.3 更新版(无需先装中间版本)

python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys --update ~/Games/1.4.3.nsp

⚠️ 警告:更新包版本是按文件内容哈希识别的,把别的文件改名成 1.4.3.nsp 没有用,必须是真正的 1.4.3 更新包,否则报 unsupported update module hashes; expected 1.1.2, 1.2.1 or 1.4.3。

场景 4:直接把成品构建到 /Applications(不要构建完再拖过去)

python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys -o /Applications

-o 指定最终路径。

场景 5:构建 iOS 未签名 IPA

python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys --platform ios -o ~/Games/TOTK.ipa

报错速查:高频构建错误的原因与处理

以下报错都来自 build_app.py 的前置检查与哈希校验,看到即停、对症处理,不要盲目重试:

报错信息(节选)原因处理办法
needs a Mac with Apple siliconIntel Mac 不支持换 Apple silicon 设备
needs macOS 26 or later (Metal 4)系统版本过低升级到 macOS 26 或更高
the Xcode command line tools are missing命令行工具未装xcode-select --install
Homebrew packages missing: brew install opus libvpxHomebrew 依赖缺失按提示 brew install 补齐
Python 3.14 not found没有 Python 3.14brew install python@3.14
SHA-256 … is not the expected … (is this Tears of the Kingdom 1.0.0, and the dump complete?)游戏文件损坏、不完整或不是 1.0.0 本体重新完整导出,确认是本 1.0.0;哈希基线对照 assets 下的 expected 文件
the base game must be an uncompressed XCI or NSP本体用了 NSZ/XCZ 压缩格式换成未压缩的 XCI/NSP;NSZ 只能作 --update 更新包
NSP files do not include system shared fontsNSP 缺系统共享字体追加 --firmware <固件NCA目录> 或 --shared-fonts <字体目录>
unsupported update module hashes; expected 1.1.2, 1.2.1 or 1.4.3更新包版本不受支持准备真正的 1.1.2 / 1.2.1 / 1.4.3 更新包,改名无效
needs about 25 GB free for the work folder工作目录空间不足清理磁盘或换更大的卷,注意与输出保持同卷
needs about 40 GB free … (19 GB extra with base data cached)更新版构建空间不足清理磁盘;本体数据已缓存时只需约 19 GB
not the shader translator this repository ships (its SHA-256 differs from totk_xlate.sha256)仓库预编译的着色器翻译器 totk_xlate 不完整或被改动重新克隆仓库获取完整文件
macOS checks the new app once (a few minutes for the 16 GB bundle) 后很久没输出macOS 正在对新 App 做首次扫描正常现象,保持构建跑完

📌 误区提醒:不要看到构建慢就 Ctrl+C。中断后重跑虽能复用已完成部分,但最后一步的 macOS 扫描(约 2–3 分钟)被打断重来最浪费时间。

构建成功后:验证方法与常用文件位置

如何确认构建成功:

  1. 构建收尾时已用 --check 模式跑过一次检查,正常从访达双击 App 即可启动;第一次进入游戏会再校验游戏数据(本地测试约 20 秒)
  2. 构建时别开着其他用 Metal 的程序(比如正在玩的游戏):缓存预热会主动跳过并提示,否则白编一场
  3. 首次进新场景可能卡顿,是新着色器在编译,属预期行为;缓存写入用户目录后再次进入同一场景会明显变流畅。机制与实测见 docs/first-launch-shaders.md
  4. 构建跑完、App 能正常游玩后,TOTK_build 工作目录与游戏文件同卷时可放心清理中间产物

常用文件与日志位置,排障时直接找:

存档:       ~/Library/Application Support/MacNativeGames/TOTK/profile
着色器缓存:  ~/Library/Application Support/MacNativeGames/TOTK/shader-cache   (删除 = 全部重新翻译)
运行日志:    ~/Library/Logs/MacNativeGames/totk.log (上一次为 totk.previous.log)
构建日志:    <游戏文件旁>/TOTK_build/logs/

相关文档与源码:

【免费下载链接】MacNativeGames 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. 【免费下载链接】MacNativeGames 项目地址: https://gitcode.com/gh_mirrors/mac/MacNativeGames

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值