Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.
Swift apple-siliconcustom-formathomebrewiosipaipadipadosiphonemetalnative-portnintendo-switchnxnativeromfsswitch-games
Docs: release notes for v0.3.1 (issues #1 and #2)
LNPANDYb93a38f46ad6
diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.mdindex 7f5ad3a8..5c13fe26 100644--- a/docs/RELEASE_NOTES.md+++ b/docs/RELEASE_NOTES.md@@ -1,145 +1,59 @@-# NS Port Builder v0.3.0 — release notes+# NS Port Builder v0.3.1 — release notes-This is the text of the [v0.3.0 release](https://github.com/LNPANDY/nxnative-romfs-archive/releases/tag/v0.3.0); v0.2.1, v0.2.0 and v0.1.0 are in the git history. 中文说明在英文下方。+This is the text of the [v0.3.1 release](https://github.com/LNPANDY/nxnative-romfs-archive/releases/tag/v0.3.1), which fixes issues [#1](https://github.com/LNPANDY/nxnative-romfs-archive/issues/1) and [#2](https://github.com/LNPANDY/nxnative-romfs-archive/issues/2). 中文说明在英文下方。-**The app now has an icon, and the repository follows upstream through 296 commits — 46 games instead of 19.**+Two reported builds that failed on machines the first release never met: a Homebrew Python 3.15 and a Homebrew .NET. Both are fixed. Thank you @carbonimax for two excellent reports.-<details>-<summary>Screenshot (click to expand)</summary>+## Fixed: Python 3.14+ was rejected, and installs failed silently (#1)-<img src="../frontend/screenshots/main-window-en.png" width="620" alt="NS Port Builder">+- The dependency probe required `backports.zstd`, which declares Python < 3.14. Python 3.14 has `compression.zstd` built in, so a perfectly good Homebrew Python 3.15 was reported as missing packages. The probe now accepts either: `compression.zstd` where it exists, the backport where it does not.+- The 安装 button ran `pip install --user`, which Homebrew's externally-managed Python refuses under PEP 668 — and the output went to a pipe nobody read. Packages now install into a **dedicated virtual environment** (`~/Library/Application Support/NS Port Builder/venv`) created from the best interpreter found. Your system Python is never touched. `backports.zstd` is only installed where it is actually needed (before 3.14).+- Install output streams into the log window and a failure says so.-</details>+## Fixed: Homebrew dotnet built the extractor, then the extractor could not start (#2)-## What's new in v0.3.0+The app detected `/opt/homebrew/bin/dotnet` fine, then launched the build with a hardcoded `DOTNET_ROOT=~/.dotnet`. Homebrew's runtime lives in `…/opt/dotnet/libexec`, so the generated apphost found no runtime and `nx_extract` exited 131.-**An app icon.** A green badge with a controller, in the same green as the app's header. The app is-no longer a blank square in the Dock and the Finder.+`DOTNET_ROOT` (and `DOTNET_ROOT_ARM64`) are now derived from the detected installation via `dotnet --list-runtimes`, which resolves symlinks and layout differences between Homebrew, the `.pkg` installer and `dotnet-install.sh`. The build script had the same bug in its own derivation; fixed there too.-**46 game profiles, up from 19.** The repository was 296 upstream commits behind. Syncing brought-27 new titles, and the host and graphics work they need:+## Verified-Hollow Knight: Silksong, Celeste, DARK SOULS: REMASTERED, Animal Crossing: New Horizons,-Paper Mario: The Thousand-Year Door, Pokémon Legends: Z-A, Luigi's Mansion 3, Super Mario Galaxy 2,-AI: THE SOMNIUM FILES, Cuphead, Catherine: Full Body, DRAGON QUEST XI S, DRAGON QUEST VII Reimagined,-FINAL FANTASY TACTICS, FINAL FANTASY RESONANCE, Monster Train 2, ANIMAL WELL, Raging Loop,-Digimon Story Cyber Sleuth, The Great Ace Attorney Chronicles, STEINS;GATE RE:BOOT,-Captain Toad: Treasure Tracker, Big Brain Academy, Patrick's Parabox, Absolum,-Brain Memory Training Academy, AI: nirvanA Initiative+- The root parser handles Homebrew output, the standard `~/.dotnet` layout and backslash paths; the real `~/.dotnet` derives itself.+- A venv created from the package-less system Python 3.9 installs all four packages and passes the probe (PEP 668 never involved).+- A fake Homebrew tree (symlinked `bin`, runtime in `libexec`) derives `…/opt/dotnet/libexec`; the old code derived `…/bin`.-That is the profile count, not a promise that every title boots. A profile carries a game's build-IDs, memory layout and shader tables; the host changes a game needs are part of the same upstream-work and came along with it. See the games table in the README for what is verified where.+## Requirements (updated)-**The fork's own features still work**, re-applied on top of the rewritten host:--- The RomFS archive layer, re-ported into the rewritten `hle_fs.c`. The host builds and the archive- reader passes its test against a real two-shard archive.-- Slim IPA by default (`DM_FULL_ROMFS=1` for upstream's full package) and the placeholder ad-hoc- signature that carries the Increased Memory Limit entitlement into a sideloader. Upstream now only- sets that entitlement in its `--prepare-xcode` mode, so an IPA built from upstream alone would have- lost it.-- `romfs.idx` recognition, `--work-dir`, and the `DOTNET_ROOT` derivation.--**The Python 3.9 fix from v0.2.1 is still in place**, and the new upstream code had three more of-the same problem (f-strings only Python 3.12 can parse). All fixed; every `.py` in the repository-parses under 3.9.--## What this build is--[`NS-Port-Builder-macOS-arm64.zip`](https://github.com/LNPANDY/nxnative-romfs-archive/releases/download/v0.3.0/NS-Port-Builder-macOS-arm64.zip)-— the app itself, ad-hoc signed, Apple Silicon, macOS 13+. Unzip it anywhere and double-click.-Because the signature is ad-hoc, the first launch needs right-click → Open, or-`xattr -dr com.apple.quarantine "NS Port Builder.app"`.--**This is a front end only.** It drives the scripts of-[nxnative-romfs-archive](https://github.com/LNPANDY/nxnative-romfs-archive), so you also need a-clone of that repository on the same Mac — and this release needs the current `main`, which carries-the 46 profiles. The app finds the checkout automatically when it sits next to it, and otherwise you-pick it once with Choose repository….--## Verified games--| Game | Status |-|---|---|-| **The Legend of Zelda: Tears of the Kingdom** (0100F2C0115B6000) | Verified — builds, installs and runs on an iPhone; 304,243 files into 127 archive shards, every file byte-verified |-| **Hades II** (0100A00019DE0000) | Verified — builds, installs and runs on an iPhone; 33-file archive |--**Every other game is unverified by this fork.** 20 of the 46 are reported playable on an iPhone by-upstream; the rest have a profile only. If you try another title, expect to bring it up yourself,-and please report what you find.--## Requirements--- An Apple Silicon Mac (the app is arm64 only; the build scripts also run on Intel)-- macOS 13 or later-- **Python 3.9 or newer** with `lz4`, `capstone`, `fonttools` and `backports.zstd`-- ~6 GB free beyond the NSPs for the extraction; the shader compile is the long step-- Your own game files and `prod.keys` — nothing is bundled--## Notes--- No game data, keys or firmware are included. Bring your own dumped NSPs.-- The command line remains the reference; every option and limitation documented in the repository- applies here too.-- Sideloading to the phone (AltStore, Sideloadly, Xcode) is outside this app's scope — see- `dm/ios/ENTITLEMENTS.md` for the memory-limit entitlement a large game needs.+- An Apple Silicon Mac, macOS 13++- **Python 3.9+** with `lz4`, `capstone`, `fontTools`, and zstd from `compression.zstd` (3.14+) or `backports.zstd` — the app's dependency panel manages a venv with all of this; you never pip-install by hand+- .NET SDK 10 — Homebrew, the .pkg installer and `dotnet-install.sh` all work now---# 中文说明-**App 有图标了,仓库同步了上游 296 个提交——游戏从 19 个增加到 46 个。**--## v0.3.0 新增--**App 图标。** 绿色圆角底 + 手柄图形,和 App 标题栏同一个绿色。Dock 和访达里不再是空白方块。--**46 个游戏 profile,原来 19 个。** 仓库落后上游 296 个提交,同步后新增 27 个游戏,以及它们需要的宿主和图形层改动:--Hollow Knight: Silksong, Celeste, DARK SOULS: REMASTERED, Animal Crossing: New Horizons,-Paper Mario: The Thousand-Year Door, Pokémon Legends: Z-A, Luigi's Mansion 3, Super Mario Galaxy 2,-AI: THE SOMNIUM FILES, Cuphead, Catherine: Full Body, DRAGON QUEST XI S, DRAGON QUEST VII Reimagined,-FINAL FANTASY TACTICS, FINAL FANTASY RESONANCE, Monster Train 2, ANIMAL WELL, Raging Loop,-Digimon Story Cyber Sleuth, The Great Ace Attorney Chronicles, STEINS;GATE RE:BOOT,-Captain Toad: Treasure Tracker, Big Brain Academy, Patrick's Parabox, Absolum,-Brain Memory Training Academy, AI: nirvanA Initiative--这是 profile 数量,不代表每个游戏都能跑起来。profile 提供 build ID、内存布局和 shader 表;游戏所需的宿主改动属于同一批上游工作,一并同步过来了。哪些验证到哪一步,见 README 的游戏表。--**本 fork 自己的功能都还在**,在重写后的宿主上重新落地:--- RomFS 归档层,重新移植进重写后的 `hle_fs.c`。宿主编译通过,归档读取器用真实的双分片归档跑通了测试。-- 默认瘦身 IPA(`DM_FULL_ROMFS=1` 才是上游的完整包),以及把「增加内存上限」entitlement 带进侧载工具的 ad-hoc 占位签名。上游现在只在 `--prepare-xcode` 模式下设这个 entitlement,直接用上游打出的 IPA 会丢掉它。-- `romfs.idx` 识别、`--work-dir`、`DOTNET_ROOT` 自动推导。--**v0.2.1 的 Python 3.9 修复仍在**,而且新同步的上游代码里又出现了三处同样的问题(只有 Python 3.12 能解析的 f-string),已全部修掉。仓库里每个 `.py` 都能被 3.9 解析。--## 这个包是什么+两个来自真实机器的构建失败:一台是 Homebrew 的 Python 3.15,一台是 Homebrew 的 .NET。都已修复。感谢 @carbonimax 的两份高质量报告。-[`NS-Port-Builder-macOS-arm64.zip`](https://github.com/LNPANDY/nxnative-romfs-archive/releases/download/v0.3.0/NS-Port-Builder-macOS-arm64.zip) 就是 App 本身,ad-hoc 签名,Apple Silicon,macOS 13+。解压到任意位置双击即可。因为用的是 ad-hoc 签名,**首次启动需要右键 → 打开**,或者执行 `xattr -dr com.apple.quarantine "NS Port Builder.app"`。+## 修复:Python 3.14+ 被误判缺包,安装静默失败(#1)-**这只是前端。** 它调用 [nxnative-romfs-archive](https://github.com/LNPANDY/nxnative-romfs-archive) 里的脚本,所以这台 Mac 上还需要 clone 那个仓库——而且必须是带 46 个 profile 的当前 `main`。App 会自己找:放在仓库旁边能自动发现,找不到就用「Choose repository…」指定一次。+- 依赖探针原来写死了 `backports.zstd`(它声明只支持 Python < 3.14),而 3.14 起标准库自带 `compression.zstd`,于是 Homebrew 的 Python 3.15 被误报缺包。现在两者都接受:有内置用内置,没有用 backport。+- 「安装」按钮原来跑 `pip install --user`,Homebrew 的受管 Python 会在 PEP 668 下拒绝——而且输出进了没人读的管道。现在包装进**专用虚拟环境**(`~/Library/Application Support/NS Port Builder/venv`),用检测到的最佳解释器创建,完全不碰系统 Python。`backports.zstd` 只在真正需要时(3.14 之前)安装。+- 安装输出实时进日志窗口,失败会明确提示。-## 已验证的游戏+## 修复:Homebrew 的 dotnet 能编译,但生成的程序起不来(#2)-| 游戏 | 状态 |-|---|---|-| **塞尔达传说:王国之泪**(0100F2C0115B6000) | 已验证 —— 构建、安装、在 iPhone 上运行;304,243 个文件归档成 127 片,逐字节校验通过 |-| **Hades II**(0100A00019DE0000) | 已验证 —— 构建、安装、在 iPhone 上运行;33 个文件的归档 |+App 检测 `/opt/homebrew/bin/dotnet` 正常,构建时却写死 `DOTNET_ROOT=~/.dotnet`。Homebrew 的运行时在 `…/opt/dotnet/libexec`,所以 apphost 找不到运行时,`nx_extract` 退出码 131。-**其他游戏本 fork 均未验证。** 46 个里有 20 个是上游报告 iPhone 可玩的,其余只有 profile。如果你试了别的游戏,请做好自行 bring-up 的准备,也欢迎反馈结果。+现在 `DOTNET_ROOT`(和 `DOTNET_ROOT_ARM64`)通过 `dotnet --list-runtimes` 从检测到的安装推导,符号链接和 Homebrew / .pkg / dotnet-install.sh 三种布局都能解析。构建脚本里同样的推导也有同样的 bug,一并修复。-## 环境要求+## 验证-- Apple Silicon Mac(App 只有 arm64;构建脚本在 Intel 上也能跑)-- macOS 13 或更高-- **Python 3.9 或更新**,并装有 `lz4`、`capstone`、`fonttools`、`backports.zstd`-- 除 NSP 外额外预留约 6 GB 用于解包;shader 编译是最慢的一步-- 你自己的游戏文件和 `prod.keys` —— 包里不含任何游戏数据+- 根目录解析器覆盖 Homebrew 输出、标准 `~/.dotnet` 布局和反斜杠路径;真实 `~/.dotnet` 正确推导。+- 用无包的系统 Python 3.9 真实创建 venv,四个包全部装上且探针通过(全程未触碰 PEP 668)。+- 伪造 Homebrew 目录(bin 符号链接、运行时在 libexec)推导出 `…/opt/dotnet/libexec`;旧代码得到 `…/bin`。-## 注意事项+## 环境要求(更新)-- 不含任何游戏数据、密钥或固件,请使用自己 dump 的 NSP。-- 命令行仍是权威;仓库里记录的所有选项和限制在这里同样适用。-- 往手机侧载(AltStore、Sideloadly、Xcode)不在这个 App 范围内 —— 大体积游戏需要的内存上限 entitlement 见 `dm/ios/ENTITLEMENTS.md`。+- Apple Silicon Mac,macOS 13++- **Python 3.9+**,`lz4`、`capstone`、`fontTools`,以及 zstd(3.14+ 用内置的 `compression.zstd`,更早用 `backports.zstd`)——这些由 App 的依赖面板通过 venv 管理,不需要手动 pip+- .NET SDK 10 —— Homebrew、.pkg 安装器、dotnet-install.sh 三种方式都支持