Skip to content

NS Port Builder v0.4.1 — Animal Crossing verified on an iPhone, archive reuse

Choose a tag to compare

View all tags
@LNPANDY LNPANDY released this 24 Oct 07:35
· 329 commits to main since this release
v0.4.1
6ba2575

The third verified game, the host fix that got it there, and a pack step that stops redoing multi-GB work.

Verified: Animal Crossing: New Horizons

3.0.3 builds, installs and runs smoothly on an iPhone — 103,645 files into 72 archive shards (tested with Happy Home Paradise). Getting there took one more host fix:

  • The bug: every file-existence check (stat) against the archive passed a path with a leading slash, while the archive's binary search expects paths without one — so every stat against a packed file answered "not found", and the title crashed at boot.
  • How it was isolated: on a Mac host the same game ran clean from a plain romfs tree (2100+ frames) but crashed from the archive at the identical program counter — pinning the fault to the archive layer, a one-line fix.

New: the archive pack reuses its work

The pack step now writes a fingerprint (.packstamp) next to the shards. When the extracted RomFS is unchanged — same NSPs, same versions — the next build skips the whole multi-GB shard pack and reports how many files were reused. Change an NSP or the DLC selection and it packs again automatically. The first pack after upgrading to this version writes the stamp, so expect exactly one repack, then none.

What this build is

NS-Port-Builder-macOS-arm64.zip — the app itself, ad-hoc signed, Apple Silicon, macOS 13+. Unzip, then right-click → Open on first launch (or xattr -dr com.apple.quarantine "NS Port Builder.app").

This is a front end only. It drives the scripts of NX2Apple, so clone that repository on the same Mac; the app finds it automatically and otherwise you pick it once with Choose repository….

Verified games

Game Update required Status
Tears of the Kingdom 1.4.3 (v720896) Verified — builds, installs and runs on an iPhone; 304,243 files into 127 archive shards, byte-verified
Hades II 1.0.137848 (v1) Verified — builds, installs and runs on an iPhone; 33-file archive
Animal Crossing: New Horizons 3.0.3 (v2228224) Verified — builds, installs and runs smoothly on an iPhone; 103,645 files into 72 archive shards

Every other game is unverified by this fork. Twenty-odd are reported playable upstream; the full table with per-game versions is in the README. If you try another title, expect to bring it up yourself, and please report what you find.

Requirements

  • An Apple Silicon Mac, macOS 13+
  • Python 3.9+ with lz4, capstone, fontTools, and zstd (compression.zstd on 3.14+, backports.zstd before) — the dependency panel manages a venv with all of this
  • .NET SDK 10 (Homebrew, .pkg and dotnet-install.sh all work)
  • ~6 GB free beyond the NSPs; the shader compile is the long step
  • Your own game files and prod.keys — nothing is bundled

Legal

No Nintendo code, assets, firmware or keys are included anywhere. The pipeline requires your own dumps and your own keys and talks to no server. Not affiliated with or endorsed by Nintendo; trademarks belong to their owners. Personal-backup laws differ by country — you are responsible for your jurisdiction, and the outputs are for your own hardware only. See the README's Legal section for the full statement, including takedown handling.

中文说明

第三个完整验证的游戏、让它跑起来的宿主修复，以及一个不再重复打包几十 GB 的构建步骤。

已验证：集合啦！动物森友会

3.0.3 构建、安装、在 iPhone 上流畅运行——103,645 个文件归档成 72 片（实测含 Happy Home Paradise）。走到这一步又修了一个宿主 bug：

  • 问题所在：所有针对归档的文件存在性检查（stat）传入的路径带前导斜杠，而归档的二分查找要求不带斜杠的相对路径——于是对已打包文件的每次 stat 都回答「找不到」，游戏一启动就崩。
  • 怎么定位的：Mac 宿主上同一游戏用纯目录 romfs 跑得干干净净（2100+ 帧），换归档就在同一个程序计数器处崩溃——把问题钉死在归档层，一行修复。

新增：归档打包会复用成果

打包步骤现在会在分片旁边写一个指纹（.packstamp）。提取出的 RomFS 没变——同样的 NSP、同样的版本——下一次构建就跳过整个几十 GB 的分片打包，并显示复用了多少文件。换了 NSP 或 DLC 选择就自动重打。升级到这个版本后的第一次打包会补写指纹，所以只会重打这一次，之后不再有。

这个包是什么

NS-Port-Builder-macOS-arm64.zip 就是 App 本身，ad-hoc 签名，Apple Silicon，macOS 13+。解压后首次启动右键 → 打开（或执行 xattr -dr com.apple.quarantine "NS Port Builder.app"）。

这只是前端。 它调用 NX2Apple 的脚本，所以同一台 Mac 上需要 clone 那个仓库；App 会自动发现，找不到就点 Choose repository… 选一次。

已验证的游戏

游戏 需要的更新包 状态
塞尔达传说：王国之泪 1.4.3 (v720896) 已验证 —— 构建、安装、在 iPhone 上运行；304,243 个文件归档成 127 片，逐字节校验通过
Hades II 1.0.137848 (v1) 已验证 —— 构建、安装、在 iPhone 上运行；33 个文件的归档
集合啦！动物森友会 3.0.3 (v2228224) 已验证 —— 构建、安装、在 iPhone 上流畅运行；103,645 个文件归档成 72 片

其他游戏本 fork 均未验证。 二十余个上游报告 iPhone 可玩；完整表格（含每个游戏的版本）在 README。试别的游戏请做好自行 bring-up 的准备，欢迎反馈。

环境要求

  • Apple Silicon Mac，macOS 13+
  • Python 3.9+，装有 lz4、capstone、fontTools，以及 zstd（3.14+ 用内置 compression.zstd，更早用 backports.zstd）——依赖面板通过 venv 全部管理
  • .NET SDK 10（Homebrew / .pkg / dotnet-install.sh 三种都支持）
  • 除 NSP 外约 6 GB 空间；shader 编译是最慢的一步
  • 你自己的游戏文件和 prod.keys——不含任何数据

法律

任何地方都不包含任天堂的代码、资源、固件或密钥。流水线需要你自己的导出文件和自己的密钥，不连接任何服务器。与任天堂无关联、未获认可；商标归权利人所有。个人备份的法律各地不同——请自行确认所在地法律，产物仅用于自己的硬件。完整声明（含下架处理）见 README 的法律一节。

Assets 3
Loading