@liyong2077: M4 MacBook Air 上运行《塞尔达传说：王国之泪》：秒加载、90 FPS。现已开源！快来试试——在 GitHub 搜索 MacNativeGames。

《塞尔达传说 王国之泪》在 M4 MacBook Air 上:秒加载、90 FPS。现已开源!去试试吧——在 GitHub 搜索 MacNativeGames。 https://t.co/XyZHahEkkS https://t.co/YzPrkCF37Y — # ly05010419/MacNativeGames Source: https://github.com/ly05010419/MacNativeGames #MacNativeGames

请使用你的 AI 助手帮你完成 Mac App 的构建。推荐 Claude Code、Codex,或其他你喜欢的 AI 助手。

English | 中文

在 Apple 芯片的 Mac 上原生运行你自己拥有的**《塞尔达传说 王国之泪》**。准备好游戏文件(XCI 或 NSP)和你的 prod.keys,一个脚本就把它们变成一个 Mac App。

项目目前只支持 Mac。这不是模拟器:游戏自身的 ARM64 代码直接运行在 Apple 芯片上(仅在 macOS 有要求的地方做了改写),Switch 的系统服务由一个小型宿主应答,游戏的 NVN 图形在 Metal 4 上重建。本仓库不含任何游戏内容,项目与 Nintendo 无关联。

更新历史:

• 10 月 18 日:新增 1.4.3 支持,并加入首次游玩前的着色器预热(约 10 分钟)。
• 10 月 17 日:新增 1.0.0 和 1.1.2 支持。首次启动的着色器预热尚不可用,因此新场景可能出现卡顿。刚开始游玩或进入新场景时出现卡顿是预期行为——新的着色器正在编译,不必惊讶。 随着缓存变热,性能通常会逐步提升。

音频修复

针对 content://Sound/... 路径的流式音乐和对白查找问题已修复。在 1.0.0 版本上本地验证了打开对白和音乐;其他版本和场景仍需验证。请用原始游戏输入重新构建 App 以应用此修复。详见音频排障与验证。

本地测试

已在 MacBook Air M4 和 Mac mini M4 上测试。本地测试共收集了 8,582 个着色器,在着色器预热后性能约为 90 FPS,菜单中可达 120 FPS。这些是较早的本地观察结果,并不构成对任何版本或场景的稳定帧率承诺。1.4.3 版本的测量数据和编译卡顿单独记录在测试笔记中。

游玩时着色器会被自动收集、编译并缓存。回到此前到访过的场景,帧率和流畅度通常会有明显提升,因为缓存的着色器可以复用。8,582 是目前本地测试中收集到的数量,而不是游戏的着色器总数,也不是收集上限;随着你继续探索,缓存会不断增长。

首次启动的着色器预热: 构建 App 时会从你选定的游戏数据中自动准备至少 8,000 个着色器,并打包进 App。即使用户缓存为空,首次启动也会在渲染第一帧之前发现并预热这些着色器;管线清单中兼容的条目也会一并预热。无需预先试玩,也不用手动拷贝缓存。当前的 1.4.3 构建准备了 8,290 个着色器。首次 GPU 预热可能需要几分钟;详见准备与测试细节。

这是可提取的游戏着色器集合,并非游玩过程中遇到的所有绑定相关变体;新场景仍可能编译额外的着色器。游玩时新遇到的着色器和管线会加入你本地的 pso_collected.tsv,并在后续启动时复用。若想分享你收集的列表,请发送 ~/Library/Application Support/MacNativeGames/TOTK/shader-cache/rt-totk-native-v4-unverified/pso_collected.tsv。其中只包含着色器和管线标识符,不含游戏存档或已编译的着色器二进制。列表与对应的翻译链版本绑定。

iPhone 和 iPad 支持即将推出。即将推出的 iPhone 版本建议使用 iPhone 16 或更新的机型。

你需要准备什么

• 一台 Apple 芯片的 Mac,macOS 26 或更高版本(图形使用 Metal 4)。建议 16 GB 及以上内存。
• 工作目录大约需要 25 GB 空闲磁盘空间(不含游戏文件)。请把输出的 App 放在同一个 APFS 卷上,以便通过克隆(cloning)共享大型数据文件。如果克隆不可用,或 App 位于其他卷,则需额外预留约 17 GB 用于 App 副本。
• 你的《王国之泪》基础游戏 1.0.0(0100F2C0115B6000),格式为 XCI 或 NSP,以及你的 prod.keys。要构建 1.1.2 或 1.4.3,请用 --update 提供对应的独立累积更新 NSP 或 NSZ,无需中间版本更新。NSZ 会在提取前解压并校验其 NCA 哈希。不支持 DLC 和整合包。
• 对于 NSP:必须一并提供其 common ticket,除非其中的 NCA 是免版权的。NSP 不包含系统共享字体:请用 --firmware 提供已解包的固件 NCA 目录,或用 --shared-fonts 提供先前提取的字体。这六个字体必须与本项目校验过的哈希匹配;工作目录中已有的有效字体会被复用。

构建 App

1. 工具(一次性):Xcode 命令行工具和 Homebrew(https://brew.sh)。安装构建依赖和获取固定版本的 SPIRV-Cross 源码需要联网:

xcode-select --install
brew install opus libvpx [email protected]

2. 下载或克隆本仓库,然后在其中的 MacNativeGames 文件夹中打开终端,用你的游戏文件和密钥运行脚本:

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

如果是 NSP,还需要一并提供共享字体:

python3.14 build_app.py ~/Games/totk.nsp -k ~/keys/prod.keys --firmware ~/Games/firmware
# 或者复用先前构建中的六个 .bfttf 文件:
python3.14 build_app.py ~/Games/totk.nsp -k ~/keys/prod.keys --shared-fonts /path/to/TOTK_build/totk/extracted/firmware/shared-fonts

--firmware 接受一个 .nca 文件目录(需先解包固件归档),或一个已安装固件的 registered 目录。--shared-fonts 接受包含 0-standard.bfttf 至 5-nintendo-extension.bfttf 的已提取目录。项目不会下载任何字体或密钥。对于 XCI,默认从其系统更新分区读取字体;若该分区缺失,也请使用上述字体选项之一。

两种输入格式都会产出一个 macOS .app。App 会出现在游戏文件旁边(Tears of the Kingdom.app;-o 可选择其他位置)。

在加入完整的着色器准备之前,一次本地干净的基础 1.0.0 构建在 M4 Mac mini 上大约需要 6 分钟(这并非当前构建的时间估计,硬件、磁盘和网络状况都会影响耗时):重写主代码模块约一分钟,解密 17 GB 游戏数据约一分钟,macOS 对成品 App 做一次性检查约两到三分钟。

构建不需要 .NET 和 cmake,完成后的游戏也不需要 Python:它的着色器翻译器是随本仓库提供的原生程序(games/totk/prebuilt)。所有中间文件都位于游戏文件旁的工作目录(TOTK_build,或用 --work 指定);再次运行脚本会复用已完成的部分。

提取出的代码模块、重写后的模块、RomFS 和共享字体都会与所选版本的 games/totk/assets/expected-v1.0.0.json、expected-v1.1.2.json 或 expected-v1.4.3.json 进行校验;预编译的着色器翻译器有自己的 SHA-256 校验。任何不匹配都会中止构建。密钥值从不会被打印。

对大型更新版 App 进行签名和校验可能额外需要几分钟。请让构建继续运行,它会持续报告进度。

3. 开玩: 在 Finder 中打开 App。构建会以 --check 模式启动启动器,检查游戏可执行文件是否存在,并让 macOS 完成其首次启动检查;它不会运行实际的游戏测试。你可以把 App 留在构建位置,也可以移动到 /Applications。把它拷贝到另一个卷会占用额外磁盘空间,并可能再次触发 macOS 检查,期间可能不出现任何窗口。首次启动游戏会校验游戏数据(本地测试中约 20 秒)。新遇到的着色器可能导致卡顿;缓存的着色器会在之后的访问中减少这部分工作。

构建 1.1.2 或 1.4.3 版本

python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys --update ~/Games/1.1.2.nsp
# 也支持 NSZ 更新:
python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys --update ~/Games/1.1.2.nsz
# 或者从同一个基础版直接构建 1.4.3:
python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys --update ~/Games/1.4.3.nsz
# 如果基础版是 NSP,请按上文保留 --firmware 或 --shared-fonts。

这会生成同样的 Tears of the Kingdom.app,其中只包含所选版本。请先退出正在运行的游戏,再重新构建到相同的 -o 路径以替换旧 App;不会出现第二个游戏条目或版本选择菜单。窗口标题会显示所选版本,例如 Ver. 1.4.3。不加 --update 时,脚本仍会构建 1.0.0。

你不需要单独下载 1.4.3 的运行时表或着色器缓存。构建会从你提供的游戏数据生成该版本专用的运行时表和首次启动着色器种子,并将其打包进 App。仓库提供 1.4.3 的补丁代码和校验过的哈希;只有你的基础游戏、更新和密钥是外部输入。

一次全新的更新构建请预留约 40 GB 空闲空间;若基础数据已缓存,则额外需要 19 GB,且 App 需在同一 APFS 卷上。

合并过程通过原始容器的受限范围读取基础 NCA,临时提取体积小得多的更新 NCA,并校验每一个 IVFC 层级。它会获取固定版本的 hactool(https://github.com/SciresM/hactool)源码,并用 clang/make 编译。临时 ticket 文件是私密的,合并后会被删除;密钥值不会出现在命令行上,也不会被打印。存档仍保存在同一个 profile 文件夹中。

在首次使用更新版启动之前,App 会在自身旁边做一次完整备份,例如 profile-before-1.1.2 或 profile-before-1.4.3;备份失败会中止启动。如果你需要回退到旧版本,请保留此备份——不要假定更新后的存档向后兼容。

若只想保留一个桌面入口,可以用可选的安装器把打包好的 App 链接起来:

python3.14 games/totk/tools/install_desktop_entry.py --app "/path/to/Tears of the Kingdom.app"

替换旧的开发版启动器时,安装器会把它的存档拷贝并校验到下文列出的标准用户 profile 中,并创建升级备份。它会保留原有的 profile,并把旧启动器归档,而不会新增另一个 App 条目。已存在的其他标准 profile 绝不会被覆盖。

源码运行时通过了基础的 Mac 检查:加载、移动/跳跃、菜单/地图、2K、存读档和死亡重试。全地图、长时游玩以及 1.0/1.1.2 的公平性能对比仍待完成;此前的 FPS 观察结果不构成对 1.1.2 性能的承诺。打包验证记录在构建笔记中。

1.4.3 移植版已在 M4 Mac 上单独通过场景加载、移动/跳跃、菜单/地图、存读档、原生 2K 画布切换以及 MetalFX 升采样/插值的测试。单一打包 App 也已测试,包括存读档、死亡重试和神庙进出。此前一个三小时版本构建和最终构建版本 30 分钟的运行记录单独保存;首次使用的编译卡顿、长时游玩的内存增长和音频欠载仍在排查中。详见1.4.3 测试记录了解测试范围与后续事项;这并非完整游戏或稳定帧率的认证。

操作

macOS 能识别的手柄(如 DualSense 和 Xbox 手柄)会被映射为 Switch Pro 手柄。震动和体感需要手柄及 macOS 暴露相应功能;并非每个手柄都有陀螺仪。

键盘映射按 US 布局的物理按键位置:

额外按键:1 显示或隐藏所有屏幕叠加信息(快捷键提示、FPS、着色器数量和系统负载读数);2 帧插值(关闭 → 30+30 → 刷新率的一半 → 无限制);3 循环切换画面模式(MetalFX 2K → 原生 2K → 关闭)。MetalFX 默认关闭,只有用 3 选择其模式时才会启动;调整窗口大小绝不会自动开启它。

文本输入(给马命名)使用 Mac 键盘。原生 2K 会把游戏的合成画布和 UI 改为 2560×1440。3D 场景仍遵循游戏自身的独立渲染缩放;这不会强制所有内部渲染目标