Skip to content

NS Port Builder v0.4.4 — fixes the build failure in v0.4.3, per-game data folders, 72 games

Choose a tag to compare

View all tags
@LNPANDY LNPANDY released this 26 Oct 13:24
· 1757 commits to main since this release
v0.4.4
1d4144b

Every build started from the app was failing. v0.4.3 and the commits before it contained an ordering bug in the build script that made build_ipa_from_nsp.py stop with UnboundLocalError: cannot access local variable 'work' — on the first build of every game, from the app. The command line escaped it (it passes -o), which is why it went unnoticed here. If you are on v0.4.3, update.

The fix

work is assigned before out_ipa reads it. The two statements had been swapped when --work-dir was added; the sync patcher now replaces them as one block so they cannot drift apart again.

Also since v0.4.3

  • Games per folder, so an external drive works. The game's data now lives in Documents/games/<title ID>/ — romfs/, save/, temp/, and optionally its own msl/. The build writes that layout directly, so the games folder is copied onto the phone (or into a folder the Files app exposes on an external drive) without renaming. Older layouts still load: Documents/romfs and the copy inside the app remain as fallbacks.
  • BC textures on older GPUs. GPUs that do not advertise BC texture compression (A15/A16 and older) now decode those textures on the CPU into RGBA8 instead of failing to create them. Opt-in per game (tex_bc_cpu in the profile), off by default; verified by decoding a known block and comparing bytes against an independent DXT1 decoder, not yet on an A15/A16 device — none was available.
  • 72 games (up from 69): Pokémon Brilliant Diamond, Shin Megami Tensei V: Vengeance, Sea of Stars.
  • The NRO header is no longer scanned as code. A module loaded with nn::ro starts with an 0x80-byte header; the rewrite scan read its build ID as instructions and reported a bogus site. Affected Final Fantasy X/X-2 HD Remaster (issue #14).
  • The nightly sync can no longer fail silently. The workflow's own issue-opening step needed a repository permission that was set to read-only; it is now write, so a failed sync reports itself.

Windows (the Qt front end)

This release's app is macOS. The Windows build is separate and still in testing — it now installs PortableGit itself, downloads LLVM-MinGW and the iPhoneOS SDK, and its dependency panel reports every step in the log. Not shipped here.

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"). v0.4.2 and later update themselves; from the app, Check for updates → Pull updates also brings the script fix that this release depends on.

This is a front end only. It drives the scripts of NX2Apple; the repository group downloads them with one button.

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. 45 are reported playable upstream; the full table with per-game versions is in the README.

Requirements

  • An Apple Silicon Mac, macOS 13+
  • Xcode with the iOS SDK (Xcode 15+ downloads the platform separately; the dependency panel says so and can fetch it)
  • Python 3.9+ with lz4, capstone, fontTools, zstd and nsz — the dependency panel manages a venv with all of it
  • .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.

中文说明

从 App 发起的每一个构建都在失败。 v0.4.3 及之前的版本里，构建脚本有一处顺序错误，让 build_ipa_from_nsp.py 以 UnboundLocalError: cannot access local variable 'work' 中止——每个游戏、每次从 App 构建都会遇到。命令行没受影响（它传了 -o），所以这边一直没发现。如果你在用 v0.4.3，请更新。

修复

work 现在在 out_ipa 读取它之前赋值。这两行在加 --work-dir 时被调换了顺序；同步补丁器现在把它们作为一个整体替换，不会再错位。

v0.4.3 之后的其他改动

  • 每个游戏一个文件夹，外置硬盘可用了。 游戏数据现在放在 Documents/games/<title ID>/ —— romfs/、save/、temp/，可选自己的 msl/。构建直接产出这个结构，所以整个 games 文件夹拷到手机（或文件 App 能访问的外置目录）不用改名。旧布局仍然可用：Documents/romfs 和 App 内的副本都保留为回退。
  • 老 GPU 上的 BC 纹理。 不支持 BC 纹理压缩的 GPU（A15/A16 及更早）现在把这类纹理在 CPU 上解压成 RGBA8，而不是创建失败。按游戏开启（profile 里的 tex_bc_cpu），默认关闭；已用已知数据块与独立 DXT1 解码器逐字节比对验证，但还没在 A15/A16 设备上验证——手头没有。
  • 72 款游戏（原 69）：宝可梦 晶灿钻石、真·女神转生 V Vengeance、星之海。
  • NRO 头不再被当作代码扫描。 通过 nn::ro 加载的模块以 0x80 字节头部开始，重写扫描把里面的 build ID 当指令读了，报出假位置。影响《最终幻想 X/X-2 HD 重制版》（issue #14）。
  • 每日同步不会再静默失败。 workflow 自动开 issue 的步骤需要一个仓库权限，之前是只读；现在是可写，同步失败会自己报告。

Windows（Qt 前端）

本次发布的是 macOS App。Windows 版是独立的，仍在测试中——它现在会自己安装 PortableGit、下载 LLVM-MinGW 和 iPhoneOS SDK，依赖面板会把每一步都写进日志。本次不发布。

这个包是什么

NS-Port-Builder-macOS-arm64.zip 就是 App 本身，ad-hoc 签名，Apple Silicon，macOS 13+。解压后首次启动右键 → 打开（或执行 xattr -dr com.apple.quarantine "NS Port Builder.app"）。v0.4.2 起 App 能自己更新；在 App 里 检查更新 → 拉取更新 也会带上本次依赖的脚本修复。

这只是前端。 它调用 NX2Apple 的脚本；仓库分组里一键下载。

已验证的游戏

游戏 需要的更新包 状态
塞尔达传说：王国之泪 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 均未验证。 45 个上游报告 iPhone 可玩；完整表格（含每个游戏的版本）在 README。

环境要求

  • Apple Silicon Mac，macOS 13+
  • 装了 iOS SDK 的 Xcode（Xcode 15+ 平台需单独下载——依赖面板会提示并可代劳）
  • Python 3.9+，装有 lz4、capstone、fontTools、zstd 和 nsz——依赖面板通过 venv 全部管理
  • .NET SDK 10（Homebrew / .pkg / dotnet-install.sh 三种都支持）
  • 除 NSP 外约 6 GB 空间；shader 编译是最慢的一步
  • 你自己的游戏文件和 prod.keys——不含任何数据

法律

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

Assets 5
Loading