Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

Texts: no semicolons in the launcher's strings and our docs

v0lumehi705d2a59c43e
diff --git a/.github/ISSUE_TEMPLATE/build_problem.yml b/.github/ISSUE_TEMPLATE/build_problem.yml
index 821557fa..8bc36251 100644
--- a/.github/ISSUE_TEMPLATE/build_problem.yml
+++ b/.github/ISSUE_TEMPLATE/build_problem.yml
@@ -4,7 +4,7 @@ body:
- type: markdown
attributes:
value: |
- Thanks for the report. A build fails at one step with one message; the fields below find it.
+ Thanks for the report. A build fails at one step with one message. The fields below find it.
**Never attach game files, keys, title keys or anything extracted from a game.** Logs and screenshots are fine.
If the game builds but then crashes, freezes or looks wrong, use the Game problem form.
- type: dropdown
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index a64185dc..43e61f6f 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -5,7 +5,7 @@ contact_links:
about: Ask how something works in Q&A, or suggest and talk over an idea in Ideas. Bugs stay as issues, with the forms here.
- name: The engine and game compatibility (seedds/nxnative)
url: https://github.com/seedds/nxnative/issues
- about: NX2Apple packs and starts games with the nxnative engine. Go there for how the engine itself works, for porting a new game or for a rendering fault you have traced into it; for a game that fails on your Mac or iPhone, use the Game problem form here first.
+ about: NX2Apple packs and starts games with the nxnative engine. Go there for how the engine itself works, for porting a new game or for a rendering fault you have traced into it. For a game that fails on your Mac or iPhone, use the Game problem form here first.
- name: Install and build instructions (README)
url: https://github.com/LNPANDY/NX2Apple#readme
about: How to install the app, what you need on disk, how to build and install a game, and the games that are known to work.
diff --git a/.github/ISSUE_TEMPLATE/game_problem.yml b/.github/ISSUE_TEMPLATE/game_problem.yml
index b99026b8..9f3b40ac 100644
--- a/.github/ISSUE_TEMPLATE/game_problem.yml
+++ b/.github/ISSUE_TEMPLATE/game_problem.yml
@@ -4,7 +4,7 @@ body:
- type: markdown
attributes:
value: |
- Thanks for the report. The fields below are what a game problem is traced with; without them the first reply is a request for them.
+ Thanks for the report. The fields below are what a game problem is traced with. Without them the first reply is a request for them.
**Never attach game files, keys, title keys or anything extracted from a game** (RomFS, NSOs, shaders). Logs and screenshots are fine.
If the problem is that the build or the install to a device fails, use the Build problem form instead.
- type: input
diff --git a/.github/ISSUE_TEMPLATE/launcher.yml b/.github/ISSUE_TEMPLATE/launcher.yml
index 0dd75c2d..d668529e 100644
--- a/.github/ISSUE_TEMPLATE/launcher.yml
+++ b/.github/ISSUE_TEMPLATE/launcher.yml
@@ -4,7 +4,7 @@ body:
- type: markdown
attributes:
value: |
- For a game that crashes or looks wrong, use the Game problem form; for a failing build, the Build problem form.
+ For a game that crashes or looks wrong, use the Game problem form. For a failing build, use the Build problem form.
Never attach keys, game files or anything extracted from a game.
- type: dropdown
id: kind
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 71daf224..135ff2f2 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,4 +1,4 @@
-<!-- One change per PR. CONTRIBUTING.md says where a change may go; read it before touching dm/, scripts/, docs/, ref/ or AGENTS.md. -->
+<!-- One change per PR. CONTRIBUTING.md says where a change may go. Read it before touching dm/, scripts/, docs/, ref/ or AGENTS.md. -->
## What and why
@@ -7,9 +7,9 @@
## Checked
<!-- Delete what does not apply. Say what was not checked too. -->
-- Tests: <!-- `cd frontend && swift test`; frontend-qt tests if you changed it; `python3 scripts/patches.py check` when `patches/` or a vendored path changed -->
+- Tests: <!-- `cd frontend && swift test`, frontend-qt tests if you changed it, `python3 scripts/patches.py check` when `patches/` or a vendored path changed -->
- Visual QA: <!-- `NX_LAUNCHER_CAPTURE_DIR=<dir> swift test` captures the views, for a UI change -->
-- Run on a device or Mac: <!-- what was built, played or installed, with title ID and version; chip and OS -->
+- Run on a device or Mac: <!-- what was built, played or installed, with title ID and version, chip and OS -->
## Screenshots
@@ -17,5 +17,5 @@
## Scope
-- [ ] No vendored file (`dm/`, `scripts/`, `docs/`, `ref/`, `AGENTS.md`) is edited directly: a change there is a patch in `patches/` (`scripts/patches.py export`; `patches.py check` passes), with its `Upstream-Status`
+- [ ] No vendored file (`dm/`, `scripts/`, `docs/`, `ref/`, `AGENTS.md`) is edited directly: a change there is a patch in `patches/` (`scripts/patches.py export`, and `patches.py check` passes), with its `Upstream-Status`
- [ ] No keys, game files or data extracted from a game in the change or the attachments
diff --git a/BUILDING.md b/BUILDING.md
index ab735a01..83ca05b4 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -4,7 +4,7 @@ The launcher (see the [README](README.md)) runs the same scripts a terminal does
## Get the tools
-This is the command-line route the launcher drives for you; the build is upstream's. Follow upstream's [README](https://github.com/seedds/nxnative) to install Xcode, Homebrew tools and the Python packages, then pack an IPA.
+This is the command-line route the launcher drives for you. The build is upstream's. Follow upstream's [README](https://github.com/seedds/nxnative) to install Xcode, Homebrew tools and the Python packages, then pack an IPA.
```bash
git clone https://github.com/<you>/NX2Apple.git
@@ -31,7 +31,7 @@ homebrew tool reads this format. It is **not** tied to a specific game: one `pro
any of your games. The only requirement is that the file contains keys for the key generation
(firmware era) the game was packaged with — a current dump covers every retail game.
-Where to put it is up to you; you pass the path with `-k`:
+Where to put it is up to you. You pass the path with `-k`:
```bash
# any layout works, e.g.
@@ -45,7 +45,7 @@ python3 scripts/build_ipa_from_nsp.py ~/Games/Hades2 -k ~/keys/prod.keys
```
How keys are dumped is documented across the Switch homebrew community (Lockpick_RCM from a
-hacked console is the usual route); this repository does not cover that step and ships none of
+hacked console is the usual route). This repository does not cover that step and ships none of
it. Two practical notes from real dumps:
- **Malformed lines.** Some dumpers emit lines whose hex value has the wrong length (33 bad
@@ -56,11 +56,11 @@ it. Two practical notes from real dumps:
both decrypt fine as long as `prod.keys` is reasonably current — verified here with a base
game on generation 15 and its update on 16, using a keys file that only reached 15.
-`backports.zstd` is needed for Tears of the Kingdom's zstd dictionaries; other games do not use it.
+`backports.zstd` is needed for Tears of the Kingdom's zstd dictionaries. Other games do not use it.
## Build the IPA
-The main build script packs a **slim IPA by default** (no RomFS inside; the app reads the game's data from its folder on the device, `Documents/games/<id>/`), so the build above already produced it. To re-pack just the package later:
+The main build script packs a **slim IPA by default** (no RomFS inside, as the app reads the game's data from its folder on the device, `Documents/games/<id>/`), so the build above already produced it. To re-pack just the package later:
```bash
GAME=<title id> W=<work dir> PATCHED=<patched dir> \
diff --git a/BUILDING.zh-CN.md b/BUILDING.zh-CN.md
index 4795ea50..d972e93a 100644
--- a/BUILDING.zh-CN.md
+++ b/BUILDING.zh-CN.md
@@ -16,7 +16,7 @@ python3 -m venv .venv # Homebrew 的 Python 不允
source .venv/bin/activate # 之后的 python3 即 venv 的(每个新终端都要执行)
```
-`backports.zstd` 是《王国之泪》的 zstd 字典需要的;其他游戏用不到。
+`backports.zstd` 是《王国之泪》的 zstd 字典需要的,其他游戏用不到。
## 你需要准备的文件
@@ -46,7 +46,7 @@ source .venv/bin/activate # 之后的 python3 即 venv
python3 scripts/build_ipa_from_nsp.py ~/Games/Hades2 -k ~/keys/prod.keys
```
-密钥的导出方式在 Switch 自制软件社区有完整文档(常见做法是在破解机上跑 Lockpick_RCM);
+密钥的导出方式在 Switch 自制软件社区有完整文档(常见做法是在破解机上跑 Lockpick_RCM)。
本仓库不涉及也不携带这一步。两条来自真实导出文件的实用提示:
- **格式错误的行。** 有的导出工具会写出十六进制值长度不对的行(真实案例:33 行长度错误的
@@ -57,7 +57,7 @@ python3 scripts/build_ipa_from_nsp.py ~/Games/Hades2 -k ~/keys/prod.keys
## 构建 IPA
-主构建脚本**默认打瘦身 IPA**(不含 RomFS;App 从设备上的 `Documents/games/<id>/` 读游戏数据),所以上面的构建
+主构建脚本**默认打瘦身 IPA**(不含 RomFS,因为 App 从设备上的 `Documents/games/<id>/` 读游戏数据),所以上面的构建
已经产出。以后只想重新打包时:
```bash
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7fe615d9..1fd9e9bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,21 +1,21 @@
# Changelog
-The release history of NX2Apple, newest first; the text of the latest release is in [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md) and every release is on the [releases page](https://github.com/LNPANDY/NX2Apple/releases). 中文:[CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md).
+The release history of NX2Apple, newest first. The text of the latest release is in [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md) and every release is on the [releases page](https://github.com/LNPANDY/NX2Apple/releases). 中文:[CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md).
Newest first. The fork follows upstream daily, so its game list and host fixes arrive automatically.
| Date | Version | What changed |
|---|---|---|
-| 2026-10-27 | v0.4.9 | **The library follows the folder**: a Mac game's saves and log live beside the .app and migrate from `~/Library` on first run; **the iPhone's game data can live anywhere** (Files-app picker, remembered); **all eight tracker features landed** (#77–#84: key pre-check, drag & drop, build notifications, older-tools flag, free space, saves between Mac and device, copy diagnostics, controller layouts); Windows: Chinese UI fixed, the Metal probe works under a Chinese user name, the failed-install crash is gone, the Vulkan SDK is found by itself |
-| 2026-10-27 | v0.4.8 | **The Mac launcher becomes usable**: install an iPhone build on a paired device (#28), a controller drives the whole launcher (#56), launch options split into basic and advanced (#54) with Display mode and the render scale in real pixels (#55) and a Mods section through `DM_ROMFS_OVERLAY` (#57), keys and controller buttons remappable (#39); **the build tools update when the app opens** (#60) and **a new version says what it changes** before installing; fixes: every rewrite of every game crashed (`patch_nso.py`'s `TEXT_LO` used before assignment, #59), the Mac app refused every build with "requires Python 3.12" (#53), a ROMs folder holding several games could not build any of them (#58), a failed build pointed at a log that was off screen (#52), a Chinese Windows showed an English interface, CI could not open issues |
-| 2026-10-27 | v0.4.7 | **94 game profiles** (+7: Octopath Traveler, Donkey Kong Country Returns HD, Donkey Kong Country: Tropical Freeze, Mario + Rabbids Sparks of Hope, Kirby and the Forgotten Land, Yoshi's Crafted World, Xenoblade Chronicles 3) from the daily sync; **one host binary, any game's memory layout** (runtime profiles — the foundation for the universal launcher, which has not been built yet); **the language toggle translates the whole interface**; **Xcode betas count** (the check asks xcode-select); a loud notice when an upstream update invalidates cached shaders; the output folder documented as the build cache's home; Windows front end: in-app Python 3.12, SDK clone past Windows' path-length limit, LLVM verified by compiling rather than --version, no more black console windows; rebuilding on an external exFAT work folder no longer crashes |
+| 2026-10-27 | v0.4.9 | **The library follows the folder**: a Mac game's saves and log live beside the .app and migrate from `~/Library` on first run. **The iPhone's game data can live anywhere** (Files-app picker, remembered). **All eight tracker features landed** (#77–#84: key pre-check, drag & drop, build notifications, older-tools flag, free space, saves between Mac and device, copy diagnostics, controller layouts). Windows: Chinese UI fixed, the Metal probe works under a Chinese user name, the failed-install crash is gone, the Vulkan SDK is found by itself |
+| 2026-10-27 | v0.4.8 | **The Mac launcher becomes usable**: install an iPhone build on a paired device (#28), a controller drives the whole launcher (#56), launch options split into basic and advanced (#54) with Display mode and the render scale in real pixels (#55) and a Mods section through `DM_ROMFS_OVERLAY` (#57), keys and controller buttons remappable (#39). **The build tools update when the app opens** (#60) and **a new version says what it changes** before installing. Fixes: every rewrite of every game crashed (`patch_nso.py`'s `TEXT_LO` used before assignment, #59), the Mac app refused every build with "requires Python 3.12" (#53), a ROMs folder holding several games could not build any of them (#58), a failed build pointed at a log that was off screen (#52), a Chinese Windows showed an English interface, CI could not open issues |
+| 2026-10-27 | v0.4.7 | **94 game profiles** (+7: Octopath Traveler, Donkey Kong Country Returns HD, Donkey Kong Country: Tropical Freeze, Mario + Rabbids Sparks of Hope, Kirby and the Forgotten Land, Yoshi's Crafted World, Xenoblade Chronicles 3) from the daily sync. **One host binary, any game's memory layout** (runtime profiles — the foundation for the universal launcher, which has not been built yet). **The language toggle translates the whole interface**. **Xcode betas count** (the check asks xcode-select). A loud notice when an upstream update invalidates cached shaders. The output folder documented as the build cache's home. Windows front end: in-app Python 3.12, SDK clone past Windows' path-length limit, LLVM verified by compiling rather than --version, no more black console windows. Rebuilding on an external exFAT work folder no longer crashes |
| 2026-10-26 | v0.4.6 | **Windows app fixed against real hardware reports**: the missing .NET SDK row (it never appeared, so nothing could install it), no more black console windows stealing the foreground, download mirrors chosen by a speed probe (a 974 s LLVM download on a mainland connection), tools installed outside the app folder so updates stop deleting them, and repository checks that say what git is doing |
-| 2026-10-26 | v0.4.5 | **Mac app output** (a double-clickable .app from the same build); **A15/A16 and earlier devices** via CPU BC decode, as an app switch; per-game data folders (`Documents/games/<id>/`) so an external drive works; NRO header no longer scanned as code; the nightly sync can no longer fail silently |
-| 2026-10-26 | v0.4.4 | **Fixes a build failure that hit every app build in v0.4.3** (`work` read before it was assigned); 72 games (+3) |
-| 2026-10-26 | v0.4.3 | NSZ/XCZ dumps work out of the box; a fresh Xcode now reports its missing iOS SDK; three environment traps closed |
-| 2026-10-25 | v0.4.2 | The app downloads and updates the repository itself, and updates itself; 58 games (+10); save-loading deadlock fixed; NuGet failures self-heal |
-| 2026-10-24 | v0.4.1 | Animal Crossing: New Horizons verified on an iPhone (103,645 files → 72 shards); archive packing reuses unchanged work |
-| 2026-10-23 | v0.4.0 | The archive folder is copy-ready with an install guide; dependency list collapses; per-game update versions in the table; renamed to NX2Apple |
+| 2026-10-26 | v0.4.5 | **Mac app output** (a double-clickable .app from the same build). **A15/A16 and earlier devices** via CPU BC decode, as an app switch. Per-game data folders (`Documents/games/<id>/`) so an external drive works. NRO header no longer scanned as code. The nightly sync can no longer fail silently |
+| 2026-10-26 | v0.4.4 | **Fixes a build failure that hit every app build in v0.4.3** (`work` read before it was assigned). 72 games (+3) |
+| 2026-10-26 | v0.4.3 | NSZ/XCZ dumps work out of the box. A fresh Xcode now reports its missing iOS SDK. Three environment traps closed |
+| 2026-10-25 | v0.4.2 | The app downloads and updates the repository itself, and updates itself. 58 games (+10). Save-loading deadlock fixed. NuGet failures self-heal |
+| 2026-10-24 | v0.4.1 | Animal Crossing: New Horizons verified on an iPhone (103,645 files → 72 shards). Archive packing reuses unchanged work |
+| 2026-10-23 | v0.4.0 | The archive folder is copy-ready with an install guide. Dependency list collapses. Per-game update versions in the table. Renamed to NX2Apple |
| 2026-10-23 | v0.3.1 | Fixes for Homebrew Python 3.15 and `DOTNET_ROOT` (#1, #2) |
| 2026-10-22 | v0.3.0 | App icon, 46 games |
| 2026-10-21 | v0.2.1 | Python 3.9 build fix |
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index c0b64c2f..7c07ea70 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -1,21 +1,21 @@
# 更新日志
-NX2Apple 的版本历史,最新在上;最新版本的完整说明见 [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md)(英文),所有版本见[发布页](https://github.com/LNPANDY/NX2Apple/releases)。English: [CHANGELOG.md](CHANGELOG.md).
+NX2Apple 的版本历史,最新在上,最新版本的完整说明见 [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md)(英文),所有版本见[发布页](https://github.com/LNPANDY/NX2Apple/releases)。English: [CHANGELOG.md](CHANGELOG.md).
最新在上。本 fork 每天跟随上游,标「同步上游」的条目是自动来的。
| 日期 | 版本 | 变更 |
|---|---|---|
-| 2026-10-27 | v0.4.9 | **游戏库跟着文件夹走**:Mac 游戏的存档和日志放在 .app 旁边,首次运行自动从 `~/Library` 迁移;**iPhone 的游戏数据可以放任何位置**(Files 应用选择器,自动记住);**追踪器八项需求全部落地**(#77–#84:密钥预检、文件拖拽、构建通知、旧工具标记、空间回收、Mac 与设备存档互拷、复制诊断报告、手柄布局);Windows:中文界面修复、中文用户名下 Metal 探针正常、依赖安装失败闪退修复、Vulkan SDK 自动识别 |
-| 2026-10-27 | v0.4.8 | **Mac 启动器真正可用了**:把 iPhone 版装到配对设备(#28)、手柄导航整个启动器(#56)、启动选项分基础/高级(#54)并加上显示模式与真实像素的 Render scale(#55)、Mods 区走 `DM_ROMFS_OVERLAY`(#57)、键位与手柄按钮可自定义(#39);**启动时自动更新构建工具**(#60),**新版本会先说明改了什么**再让你决定;修复:每一款游戏的每一次重写都会崩(`patch_nso.py` 的 `TEXT_LO` 先用后定义,#59)、Mac 版建什么都报「需要 Python 3.12」(#53)、一个文件夹多款游戏时一款都建不了(#58)、构建失败指向窗口外的日志(#52)、Windows 中文系统显示英文界面、CI 建不了 issue |
-| 2026-10-27 | v0.4.7 | **79 个游戏 profile**(+7:歧路旅人、大金刚国度 归乡 HD、大金刚国度 热带冻结)来自每日同步;**一个宿主二进制适配任意游戏的内存布局**(运行时 profile——为通用启动器打下的地基,启动器本身尚未开始);**语言切换现在翻译整个界面**;**Xcode Beta 也算数**(检测改问 xcode-select);上游更新导致 shader 缓存失效时会醒目提示;「输出目录」同时是构建缓存的位置已写明;Windows 前端:App 内装 Python 3.12、SDK 克隆突破 Windows 路径长度限制、LLVM 用试编译而不是 --version 验证、不再弹黑色命令行窗口;外置 exFAT 工作目录重建不再崩溃 |
+| 2026-10-27 | v0.4.9 | **游戏库跟着文件夹走**:Mac 游戏的存档和日志放在 .app 旁边,首次运行自动从 `~/Library` 迁移。**iPhone 的游戏数据可以放任何位置**(Files 应用选择器,自动记住)。**追踪器八项需求全部落地**(#77–#84:密钥预检、文件拖拽、构建通知、旧工具标记、空间回收、Mac 与设备存档互拷、复制诊断报告、手柄布局)。Windows:中文界面修复、中文用户名下 Metal 探针正常、依赖安装失败闪退修复、Vulkan SDK 自动识别 |
+| 2026-10-27 | v0.4.8 | **Mac 启动器真正可用了**:把 iPhone 版装到配对设备(#28)、手柄导航整个启动器(#56)、启动选项分基础/高级(#54)并加上显示模式与真实像素的 Render scale(#55)、Mods 区走 `DM_ROMFS_OVERLAY`(#57)、键位与手柄按钮可自定义(#39)。**启动时自动更新构建工具**(#60),**新版本会先说明改了什么**再让你决定。修复:每一款游戏的每一次重写都会崩(`patch_nso.py` 的 `TEXT_LO` 先用后定义,#59)、Mac 版建什么都报「需要 Python 3.12」(#53)、一个文件夹多款游戏时一款都建不了(#58)、构建失败指向窗口外的日志(#52)、Windows 中文系统显示英文界面、CI 建不了 issue |
+| 2026-10-27 | v0.4.7 | **79 个游戏 profile**(+7:歧路旅人、大金刚国度 归乡 HD、大金刚国度 热带冻结)来自每日同步。**一个宿主二进制适配任意游戏的内存布局**(运行时 profile——为通用启动器打下的地基,启动器本身尚未开始)。**语言切换现在翻译整个界面**。**Xcode Beta 也算数**(检测改问 xcode-select)。上游更新导致 shader 缓存失效时会醒目提示。「输出目录」同时是构建缓存的位置已写明。Windows 前端:App 内装 Python 3.12、SDK 克隆突破 Windows 路径长度限制、LLVM 用试编译而不是 --version 验证、不再弹黑色命令行窗口。外置 exFAT 工作目录重建不再崩溃 |
| 2026-10-26 | v0.4.6 | **Windows 版按真机反馈修好**:.NET SDK 那一行以前根本不存在(所以永远装不上)、不再弹出黑色命令行窗口抢走焦点、下载走镜像并用测速挑最快的一个(真机上 LLVM 曾下 974 秒)、工具装到 App 目录外所以更新不再把它删掉、检查更新会说明 git 在做什么 |
-| 2026-10-26 | v0.4.5 | **可输出 Mac App**(同一次构建产出可双击运行的 .app);**支持 A15 / A16 及更早设备**(CPU 解压 BC 纹理,App 内开关);每游戏独立数据目录(`Documents/games/<id>/`),外置硬盘可用;NRO 头不再被当作代码扫描;每日同步不会再静默失败 |
-| 2026-10-26 | v0.4.4 | **修复了 v0.4.3 里每个 App 构建都会失败的问题**(`work` 在赋值前被读取);72 款游戏(+3) |
-| 2026-10-26 | v0.4.3 | NSZ/XCZ 压缩格式开箱可用;全新 Xcode 会明说缺 iOS SDK;三个环境陷阱关掉 |
-| 2026-10-25 | v0.4.2 | App 自己下载并更新仓库、也能更新自己;58 款游戏(+10);读档死锁修复;NuGet 报错自动恢复 |
-| 2026-10-24 | v0.4.1 | 集合啦!动物森友会在 iPhone 上验证通过(103,645 文件 → 72 片);归档打包复用未变的成果 |
-| 2026-10-23 | v0.4.0 | 归档文件夹直接可拷贝并附安装引导;依赖列表可折叠;表格列出每个游戏的所需版本;更名为 NX2Apple |
+| 2026-10-26 | v0.4.5 | **可输出 Mac App**(同一次构建产出可双击运行的 .app)。**支持 A15 / A16 及更早设备**(CPU 解压 BC 纹理,App 内开关)。每游戏独立数据目录(`Documents/games/<id>/`),外置硬盘可用。NRO 头不再被当作代码扫描。每日同步不会再静默失败 |
+| 2026-10-26 | v0.4.4 | **修复了 v0.4.3 里每个 App 构建都会失败的问题**(`work` 在赋值前被读取),72 款游戏(+3) |
+| 2026-10-26 | v0.4.3 | NSZ/XCZ 压缩格式开箱可用,全新 Xcode 会明说缺 iOS SDK,三个环境陷阱关掉 |
+| 2026-10-25 | v0.4.2 | App 自己下载并更新仓库、也能更新自己,58 款游戏(+10),读档死锁修复,NuGet 报错自动恢复 |
+| 2026-10-24 | v0.4.1 | 集合啦!动物森友会在 iPhone 上验证通过(103,645 文件 → 72 片),归档打包复用未变的成果 |
+| 2026-10-23 | v0.4.0 | 归档文件夹直接可拷贝并附安装引导,依赖列表可折叠,表格列出每个游戏的所需版本,更名为 NX2Apple |
| 2026-10-23 | v0.3.1 | 修复 Homebrew Python 3.15 与 `DOTNET_ROOT` 问题(#1、#2) |
| 2026-10-22 | v0.3.0 | App 图标,46 款游戏 |
| 2026-10-21 | v0.2.1 | Python 3.9 构建修复 |
diff --git a/CLAUDE.md b/CLAUDE.md
index 0462563d..0d8d5776 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,4 +2,4 @@
- Read [AGENTS.md](AGENTS.md) first.
- For an issue or a pull request, follow [CONTRIBUTING.md](CONTRIBUTING.md), section "For AI agents and other tools", and the templates in `.github/`.
-- `dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are upstream plus the patch queue in `patches/`: a change there is a patch (`scripts/patches.py export`, see [patches/README.md](patches/README.md)), not a direct edit; `scripts/patches.py check` fails otherwise.
+- `dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are upstream plus the patch queue in `patches/`: a change there is a patch (`scripts/patches.py export`, see [patches/README.md](patches/README.md)), not a direct edit, and `scripts/patches.py check` fails otherwise.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 84eddda9..5967cc34 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,17 +4,17 @@ Issues and pull requests are welcome. NX2Apple is the launcher (`frontend/`, `fr
## Reporting a problem
-Game problems, build problems and launcher problems each have an issue form (`.github/ISSUE_TEMPLATE/`); the form asks for what a report needs — versions, device, Copy diagnostics and the game's log. Use it from the Issues page; a report without those is usually unactionable.
+Game problems, build problems and launcher problems each have an issue form (`.github/ISSUE_TEMPLATE/`). The form asks for what a report needs — versions, device, Copy diagnostics and the game's log. Use it from the Issues page. A report without those is usually unactionable.
## Where an issue goes
- **Here:** the app, a build or install that fails, and a game that does not run well on your Mac or iPhone or iPad.
-- **[Discussions](https://github.com/LNPANDY/NX2Apple/discussions):** questions (Q&A) and ideas (Ideas); bugs stay issues.
+- **[Discussions](https://github.com/LNPANDY/NX2Apple/discussions):** questions (Q&A) and ideas (Ideas). Bugs stay issues.
- **[seedds/nxnative](https://github.com/seedds/nxnative/issues):** how the engine works, porting a new game, a rendering fault you have traced into the engine itself.
## What a report needs
-Pick a form: **Game problem**, **Build problem** or **Launcher problem or idea**. Each asks for what the problem is traced with: the game, its title ID and versions, the target, the device and OS, the NX2Apple version, **Settings > Copy diagnostics**, and the log (a game's log, or the Build log on the Builds page). A report without them gets a request for them first. Where a game's log is: a Mac game in a library folder writes `log/<title ID>.log` beside its app, otherwise `~/Library/Logs/nxnative/<title ID>.log`; on an iPhone or iPad it is `log.txt` in the Files app.
+Pick a form: **Game problem**, **Build problem** or **Launcher problem or idea**. Each asks for what the problem is traced with: the game, its title ID and versions, the target, the device and OS, the NX2Apple version, **Settings > Copy diagnostics**, and the log (a game's log, or the Build log on the Builds page). A report without them gets a request for them first. Where a game's log is: a Mac game in a library folder writes `log/<title ID>.log` beside its app, otherwise `~/Library/Logs/nxnative/<title ID>.log`. On an iPhone or iPad it is `log.txt` in the Files app.
**Never attach keys, game files or anything extracted from a game.** Logs, screenshots, title IDs and build IDs are fine.
@@ -28,7 +28,7 @@ useful:**
with the title ID, the update version, and what you did. It becomes a profile others can use.
- **Send the shaders that are missing** — if a game runs but stutters on first use of an effect, its
shader variants are missing from the map. The host can dump what it cannot find
- (`DM_NVN_SHDUMP=<dir>`); attach those and we add them to `shader_map.tsv` for everyone.
+ (`DM_NVN_SHDUMP=<dir>`). Attach those and we add them to `shader_map.tsv` for everyone.
Issues with a full `Documents/log.txt` get looked at first — that log usually names the exact
missing piece.
@@ -37,8 +37,8 @@ missing piece.
- One change per PR, off `main`. Commit messages say what changed and why, in plain English, as `git log` does.
- Fill in the PR template: what and why, what was checked, screenshots for UI changes.
-- **`frontend/` and `frontend-qt/` are the fork's own:** change them freely. Run `cd frontend && swift test`; for a UI change also capture the views for visual QA (`NX_LAUNCHER_CAPTURE_DIR`, see [frontend/README.md](frontend/README.md#verification)).
-- **`dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are upstream plus the patch queue.** They are generated: seedds/nxnative at the commit in `.upstream-ref` with the patches in `patches/` applied, so a direct edit fails `scripts/patches.py check` (the `pr-scope` and `patch-queue` jobs) and would be lost on the next bump. The failure names the command: `python3 scripts/patches.py absorb <files>` folds a direct edit into the patch that already touches the file (a new file may need `--into <patch>`); commit `patches/` with it. For a change that needs a patch of its own, commit the change, turn it into a patch with `scripts/patches.py export <commit>`, fill in its header (`Upstream-Status`, `Reason`, `Issue`), and send the same change to seedds/nxnative so the patch can go: [patches/README.md](patches/README.md) walks through it and states the patch policy (what a patch may and may not change). Files under `.github/` and in the repository root that are not in that list (this file, `CLAUDE.md`, the README) are the fork's.
+- **`frontend/` and `frontend-qt/` are the fork's own:** change them freely. Run `cd frontend && swift test`. For a UI change also capture the views for visual QA (`NX_LAUNCHER_CAPTURE_DIR`, see [frontend/README.md](frontend/README.md#verification)).
+- **`dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are upstream plus the patch queue.** They are generated: seedds/nxnative at the commit in `.upstream-ref` with the patches in `patches/` applied, so a direct edit fails `scripts/patches.py check` (the `pr-scope` and `patch-queue` jobs) and would be lost on the next bump. The failure names the command: `python3 scripts/patches.py absorb <files>` folds a direct edit into the patch that already touches the file (a new file may need `--into <patch>`). Commit `patches/` with it. For a change that needs a patch of its own, commit the change, turn it into a patch with `scripts/patches.py export <commit>`, fill in its header (`Upstream-Status`, `Reason`, `Issue`), and send the same change to seedds/nxnative so the patch can go: [patches/README.md](patches/README.md) walks through it and states the patch policy (what a patch may and may not change). Files under `.github/` and in the repository root that are not in that list (this file, `CLAUDE.md`, the README) are the fork's.
## For AI agents and other tools
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
index 0440e471..b489f0b1 100644
--- a/CONTRIBUTING.zh-CN.md
+++ b/CONTRIBUTING.zh-CN.md
@@ -10,7 +10,7 @@
- **报告一款能跑的游戏** —— 如果你让验证清单之外的游戏跑起来了,开 issue 附上 title ID、更新版本和
你做的步骤,它会变成一个别人也能用的 profile。
- **提交缺失的着色器** —— 如果游戏能跑但首次使用某个效果时卡顿,说明它的 shader 变体不在映射表里。
- 宿主可以导出找不到的部分(`DM_NVN_SHDUMP=<dir>`);附上它们,我们把它加进 `shader_map.tsv`,
+ 宿主可以导出找不到的部分(`DM_NVN_SHDUMP=<dir>`)。附上它们,我们把它加进 `shader_map.tsv`,
所有人都受益。
带完整 `Documents/log.txt` 的 issue 会优先看——那份日志通常能直接指出缺的是什么。
diff --git a/GAMES.md b/GAMES.md
index 20ffb28f..d7f60c48 100644
--- a/GAMES.md
+++ b/GAMES.md
@@ -1,10 +1,10 @@
# Games
-Every game this fork has a profile for, with the update NSP each one needs. The player's page is [README.md](README.md); [dm/games/README.md](dm/games/README.md) lists the same games with the engine's own notes on each. This page is the full list, so the README stays short. 中文:[GAMES.zh-CN.md](GAMES.zh-CN.md).
+Every game this fork has a profile for, with the update NSP each one needs. The player's page is [README.md](README.md), and [dm/games/README.md](dm/games/README.md) lists the same games with the engine's own notes on each. This page is the full list, so the README stays short. 中文:[GAMES.zh-CN.md](GAMES.zh-CN.md).
## Gallery
-Screenshots and IPA sizes. The block between the markers is written by `dm/tools/docs_gallery.py` from `docs/images/gallery.tsv` (add a row there, then run the script); do not edit it by hand.
+Screenshots and IPA sizes. The block between the markers is written by `dm/tools/docs_gallery.py` from `docs/images/gallery.tsv` (add a row there, then run the script). Do not edit it by hand.
<!-- gallery: written by dm/tools/docs_gallery.py from docs/images/gallery.tsv; change the table, then run it -->
<table>
@@ -189,103 +189,103 @@ update layers over it). "无(v0)" = the base game alone is enough.
|---|---|---|---|
| Super Mario Odyssey | `0100000000010000` | 1.4.1 (v393216) | Playable on an iPhone (upstream) |
| Pokémon Brilliant Diamond | `0100000011D90000` | 1.3.0 (v393216) | Playable on an iPhone (upstream) |
-| Ace Attorney Investigations Collection | `010005501E68C000` | 1.0.0.2 (v131072) | Profile present; not verified on a phone |
-| Hollow Knight: Silksong | `010013C00E930000` | 1.0.30000 (v655360) | Profile present; not verified on a phone |
-| Digimon Story Cyber Sleuth: Complete Edition | `010014E00DB56000` | 1.0.3 (v196608) | Profile present; not verified on a phone |
+| Ace Attorney Investigations Collection | `010005501E68C000` | 1.0.0.2 (v131072) | Profile present, not verified on a phone |
+| Hollow Knight: Silksong | `010013C00E930000` | 1.0.30000 (v655360) | Profile present, not verified on a phone |
+| Digimon Story Cyber Sleuth: Complete Edition | `010014E00DB56000` | 1.0.3 (v196608) | Profile present, not verified on a phone |
| Super Mario Bros. Wonder | `010015100B514000` | 1.2.1 (v327680) | Playable on an iPhone (upstream) |
| Mario Kart 8 Deluxe | `0100152000022000` | 4.0.1 (v1507328) | Playable on an iPhone (upstream) |
-| Raging Loop | `010020400E1C2000` | 无(v0) | Profile present; not verified on a phone |
+| Raging Loop | `010020400E1C2000` | 无(v0) | Profile present, not verified on a phone |
| ANIMAL WELL | `010020D01AD24000` | 1.0.10 (v655360) | Playable on an iPhone (upstream) |
| Super Mario 3D World + Bowser's Fury | `010028600EBDA000` | 1.2.2 (v262144) | Playable on an iPhone (upstream) |
| Ghost Trick: Phantom Detective | `010029B018432000` | 无(v0) | Playable on an iPhone (upstream) |
| Hyrule Warriors: Age of Calamity | `01002B00111A2000` | 1.3.0 (v327680) | Playable on an iPhone (upstream) |
-| Celeste | `01002B30028F6000` | 1.4.1.1 (v589824) | Profile present; not verified on a phone |
+| Celeste | `01002B30028F6000` | 1.4.1.1 (v589824) | Profile present, not verified on a phone |
| Advance Wars 1+2: Re-Boot Camp | `0100300012F2A000` | 无(v0) | Playable on an iPhone (upstream) |
-| Mario + Rabbids® Sparks of Hope | `0100317013770000` | 1.6.2225577 (v393216) | Profile present; not verified on a phone |
-| Return of the Obra Dinn | `010032E00E6E2000` | 1.0.1 (v65536) | Profile present; not verified on a phone |
+| Mario + Rabbids® Sparks of Hope | `0100317013770000` | 1.6.2225577 (v393216) | Profile present, not verified on a phone |
+| Return of the Obra Dinn | `010032E00E6E2000` | 1.0.1 (v65536) | Profile present, not verified on a phone |
| Taiko Risshiden V DX | `0100346017304000` | 1.1.1 (v131072) | Playable on an iPhone by touch (upstream) |
| The Great Ace Attorney Chronicles | `010036E00FB20000` | 无(v0) | Playable on an iPhone (upstream) |
-| FINAL FANTASY TACTICS - The Ivalice Chronicles | `010038B015560000` | 1.4.0 (v393216) | Profile present; not verified on a phone |
+| FINAL FANTASY TACTICS - The Ivalice Chronicles | `010038B015560000` | 1.4.0 (v393216) | Profile present, not verified on a phone |
| 13 Sentinels: Aegis Rim | `01003FC01670C000` | 1.10 (v65536) | Playable on an iPhone (upstream) |
-| Blasphemous 2 | `010040801A4C8000` | 1.0.8 (v524288) | Profile present; not verified on a phone |
-| 13 Sentinels: Aegis Rim (Japan) | `010045C014650000` | 无(v0) | Profile present; not verified on a phone |
+| Blasphemous 2 | `010040801A4C8000` | 1.0.8 (v524288) | Profile present, not verified on a phone |
+| 13 Sentinels: Aegis Rim (Japan) | `010045C014650000` | 无(v0) | Profile present, not verified on a phone |
| Bayonetta 3 | `01004A4010FEA000` | 1.2.0 (v131072) | Playable on an iPhone (upstream) |
-| DARK SOULS: REMASTERED | `01004AB00A260000` | 1.0.3 (v196608) | Profile present; not verified on a phone |
-| Kirby and the Forgotten Land | `01004D300C5AE000` | 1.1.0 (v65536) | Profile present; not verified on a phone |
+| DARK SOULS: REMASTERED | `01004AB00A260000` | 1.0.3 (v196608) | Profile present, not verified on a phone |
+| Kirby and the Forgotten Land | `01004D300C5AE000` | 1.1.0 (v65536) | Profile present, not verified on a phone |
| Monster Train 2 | `010051701FB46000` | 1.1.1 (v131072) | Playable on an iPhone (upstream) |
-| OCTOPATH TRAVELER 0 | `01005270232F2000` | 1.0.5 (v327680) | Profile present; not verified on a phone |
+| OCTOPATH TRAVELER 0 | `01005270232F2000` | 1.0.5 (v327680) | Profile present, not verified on a phone |
| Hades | `0100535012974000` | 1.0.38233 (v589824) | Playable on an iPhone (upstream) |
-| Unicorn Overlord (Asia) | `010054B01AD92000` | 1.05 (v262144) | Profile present; not verified on a phone |
+| Unicorn Overlord (Asia) | `010054B01AD92000` | 1.05 (v262144) | Profile present, not verified on a phone |
| Fire Emblem: Three Houses | `010055D009F78000` | 1.2.0 (v327680) | Playable on an iPhone (upstream) |
| NieR:Automata The End of YoRHa Edition | `010056B015FE8000` | 1.0.3 (v131072) | Playable on an iPhone (upstream) |
-| OCTOPATH TRAVELER | `010057D006492000` | 1.0.5 (v327680) | Profile present; not verified on a phone |
+| OCTOPATH TRAVELER | `010057D006492000` | 1.0.5 (v327680) | Profile present, not verified on a phone |
| Persona 5 Royal | `01005CA01580E000` | 1.0.2 (v65536) | Playable on an iPhone (upstream) |
-| Yoshi's Crafted World | `01006000040C2000` | 1.0.1 (v65536) | Profile present; not verified on a phone |
+| Yoshi's Crafted World | `01006000040C2000` | 1.0.1 (v65536) | Profile present, not verified on a phone |
| FINAL FANTASY RESONANCE | `0100606026F12000` | 1.0.1 (v65536) | Playable on an iPhone (upstream) |
-| Big Brain Academy: Brain vs. Brain | `0100620012D6E000` | 1.2.0 (v131072) | Profile present; not verified on a phone |
-| Persona 4 Golden | `010062B01525C000` | 1.0.2 (v131072) | Profile present; not verified on a phone |
-| Mario + Rabbids Kingdom Battle | `010067300059A000` | 1.9.589692 (v589824) | Profile present; not verified on a phone |
-| Unicorn Overlord | `010069401ADB8000` | 1.05 (v262144) | Profile present; not verified on a phone |
-| Blasphemous | `0100698009C6E000` | 1.0.8 (v524288) | Profile present; not verified on a phone |
+| Big Brain Academy: Brain vs. Brain | `0100620012D6E000` | 1.2.0 (v131072) | Profile present, not verified on a phone |
+| Persona 4 Golden | `010062B01525C000` | 1.0.2 (v131072) | Profile present, not verified on a phone |
+| Mario + Rabbids Kingdom Battle | `010067300059A000` | 1.9.589692 (v589824) | Profile present, not verified on a phone |
+| Unicorn Overlord | `010069401ADB8000` | 1.05 (v262144) | Profile present, not verified on a phone |
+| Blasphemous | `0100698009C6E000` | 1.0.8 (v524288) | Profile present, not verified on a phone |
| SHIN MEGAMI TENSEI V: Vengeance | `010069C01AB82000` | 1.0.3 (v196608) | Playable on an iPhone (upstream) |
| Super Smash Bros. Ultimate | `01006A800016E000` | 13.0.5 (v2031616) | Playable on an iPhone (upstream) |
| The Legend of Zelda: Link's Awakening | `01006BB00C6F0000` | 1.1.0 (v131072) | Playable on an iPhone (upstream) |
-| DRAGON QUEST XI S: Echoes of an Elusive Age – Definitive Edition | `01006C300E9F0000` | 1.0.4 (v262144) | Profile present; not verified on a phone |
-| Animal Crossing: New Horizons | `01006F8002326000` | 3.0.3 (v2228224) | **Verified here** — builds, installs and runs smoothly on an iPhone; 103,645 files into 72 archive shards |
+| DRAGON QUEST XI S: Echoes of an Elusive Age – Definitive Edition | `01006C300E9F0000` | 1.0.4 (v262144) | Profile present, not verified on a phone |
+| Animal Crossing: New Horizons | `01006F8002326000` | 3.0.3 (v2228224) | **Verified here** — builds, installs and runs smoothly on an iPhone, 103,645 files into 72 archive shards |
| AI: THE SOMNIUM FILES - nirvanA Initiative | `0100713016CCC000` | 1.0.2 (v131072) | Playable on an iPhone (upstream) |
| ASTRAL CHAIN | `01007300020FA000` | 1.0.1 (v65536) | Playable on an iPhone (upstream) |
-| Xenoblade Chronicles 3 | `010074F013262000` | 2.2.1 (v720896) | Profile present; not verified on a phone |
+| Xenoblade Chronicles 3 | `010074F013262000` | 2.2.1 (v720896) | Profile present, not verified on a phone |
| Bayonetta | `010076F0049A2000` | 1.1 (v65536) | Playable on an iPhone (upstream) |
| Bayonetta 2 | `01007960049A0000` | 1.2 (v131072) | Playable on an iPhone (upstream) |
| Portal | `01007BB017812000` | 1.0.3 (v196608) | Playable on an iPhone (upstream) |
| The Legend of Zelda: Breath of the Wild | `01007EF00011E000` | 1.9.0 (v1114112) | Playable on an iPhone (upstream) |
| BALL x PIT | `010086A022444000` | 1.293 (v393216) | Playable on an iPhone (upstream) |
| AI: THE SOMNIUM FILES | `010089B00D09C000` | 1.0.1 (v65536) | Playable on an iPhone (upstream) |
-| STEINS;GATE RE:BOOT | `01008BC024FDE000` | 1.0.3 (v131072) | Profile present; not verified on a phone |
+| STEINS;GATE RE:BOOT | `01008BC024FDE000` | 1.0.3 (v131072) | Profile present, not verified on a phone |
| Sea of Stars | `01008C0016544000` | 2.0.59001 (v786432) | Playable on an iPhone (upstream) |
| The Legend of Zelda: Echoes of Wisdom | `01008CF01BAAC000` | 1.1.0 (v196608) | Playable on an iPhone (upstream) |
| 13 Sentinels: Aegis Rim (Asia) | `01008D7016438000` | 无(v0) | Playable on an iPhone (upstream) |
| Pokémon Shield | `01008DB008C2C000` | 1.3.2 (v458752) | Playable on an iPhone (upstream) |
| Metroid Dread | `010093801237C000` | 2.1.0 (v327680) | Playable on an iPhone (upstream) |
| Super Mario Galaxy | `010099C022B96000` | 1.3.1 (v327680) | Playable on an iPhone (upstream) |
-| Captain Toad: Treasure Tracker | `01009BF0072D4000` | 1.4.2 (v393216) | Profile present; not verified on a phone |
-| Donkey Kong Country Returns HD | `01009D901BC56000` | 1.1.0 (v65536) | Profile present; not verified on a phone |
-| Hades II | `0100A00019DE0000` | 1.0.137848 (v1) | **Verified here** — builds, installs and runs on an iPhone; 33-file archive |
+| Captain Toad: Treasure Tracker | `01009BF0072D4000` | 1.4.2 (v393216) | Profile present, not verified on a phone |
+| Donkey Kong Country Returns HD | `01009D901BC56000` | 1.1.0 (v65536) | Profile present, not verified on a phone |
+| Hades II | `0100A00019DE0000` | 1.0.137848 (v1) | **Verified here** — builds, installs and runs on an iPhone, 33-file archive |
| OCTOPATH TRAVELER II | `0100A3501946E000` | 1.1.1 (v131072) | Playable on an iPhone (upstream) |
-| Pokémon Scarlet | `0100A3D008C5C000` | 无(v0) | Profile present; not verified on a phone |
-| Cuphead | `0100A5C00D162000` | 1.3.7 (v655360) | Profile present; not verified on a phone |
+| Pokémon Scarlet | `0100A3D008C5C000` | 无(v0) | Profile present, not verified on a phone |
+| Cuphead | `0100A5C00D162000` | 1.3.7 (v655360) | Profile present, not verified on a phone |
| Fire Emblem Engage | `0100A6301214E000` | 2.0.0 (v327680) | Playable on an iPhone (upstream) |
-| Absolum | `0100A83022A22000` | 1.1.2 (v458752) | Profile present; not verified on a phone |
-| DRAGON QUEST VII Reimagined | `0100A9D01C446000` | 1.2.0 (v131072) | Profile present; not verified on a phone |
+| Absolum | `0100A83022A22000` | 1.1.2 (v458752) | Profile present, not verified on a phone |
+| DRAGON QUEST VII Reimagined | `0100A9D01C446000` | 1.2.0 (v131072) | Profile present, not verified on a phone |
| Pokémon Sword | `0100ABF008968000` | 1.3.2 (v458752) | Playable on an iPhone (upstream) |
-| Monster Hunter Rise | `0100B04011742000` | 16.0.2 (v2228224) | Profile present; not verified on a phone |
+| Monster Hunter Rise | `0100B04011742000` | 16.0.2 (v2228224) | Profile present, not verified on a phone |
| Pikmin 4 | `0100B7C00933A000` | 1.1.1 (v262144) | Playable on an iPhone (upstream) |
-| FINAL FANTASY RESONANCE (Asian release) | `0100B8A026F14000` | 1.0.1 (v65536) | Profile present; not verified on a phone |
-| NieR:Automata The End of YoRHa Edition | `0100B8E016F76000` | 1.0.3 (v131072) | Profile present; not verified on a phone |
+| FINAL FANTASY RESONANCE (Asian release) | `0100B8A026F14000` | 1.0.1 (v65536) | Profile present, not verified on a phone |
+| NieR:Automata The End of YoRHa Edition | `0100B8E016F76000` | 1.0.3 (v131072) | Profile present, not verified on a phone |
| Mario vs. Donkey Kong | `0100B99019412000` | 1.0.1 (v65536) | Playable on an iPhone (upstream) |
-| FINAL FANTASY X/X-2 HD Remaster | `0100BC300CB48000` | 无(v0) | Profile present; not verified on a phone |
-| Catherine: Full Body | `0100BF00112C0000` | 1.0.1a (v131072) | Profile present; not verified on a phone |
-| Donkey Kong Country: Tropical Freeze | `0100C1F0051B6000` | 1.0.2 (v131072) | Profile present; not verified on a phone |
+| FINAL FANTASY X/X-2 HD Remaster | `0100BC300CB48000` | 无(v0) | Profile present, not verified on a phone |
+| Catherine: Full Body | `0100BF00112C0000` | 1.0.1a (v131072) | Profile present, not verified on a phone |
+| Donkey Kong Country: Tropical Freeze | `0100C1F0051B6000` | 1.0.2 (v131072) | Profile present, not verified on a phone |
| ROMANCE OF THE THREE KINGDOMS 8 REMAKE | `0100C2A01A730000` | 1.1.3 (v851968) | Playable on an iPhone with a controller (upstream) |
| Balatro | `0100CD801CE5E000` | 1.1.3 (v851968) | Playable on an iPhone (upstream) |
-| FINAL FANTASY CRYSTAL CHRONICLES Remastered Edition | `0100CE4010AAC000` | 1.0.3 (v196608) | Profile present; not verified on a phone |
-| Silver Pines | `0100D5B026844000` | 无(v0) | Profile present; not verified on a phone |
-| Rhythm Heaven Groove | `0100D9F01D474000` | 无(v0) | Profile present; not verified on a phone |
+| FINAL FANTASY CRYSTAL CHRONICLES Remastered Edition | `0100CE4010AAC000` | 1.0.3 (v196608) | Profile present, not verified on a phone |
+| Silver Pines | `0100D5B026844000` | 无(v0) | Profile present, not verified on a phone |
+| Rhythm Heaven Groove | `0100D9F01D474000` | 无(v0) | Profile present, not verified on a phone |
| Luigi's Mansion 3 | `0100DCA0064A6000` | 1.4.0 (v327680) | Playable on an iPhone (upstream) |
-| Patrick's Parabox | `0100E44016C22000` | 1.0.1 (v65536) | Profile present; not verified on a phone |
+| Patrick's Parabox | `0100E44016C22000` | 1.0.1 (v65536) | Profile present, not verified on a phone |
| Stardew Valley | `0100E65002BB8000` | 1.6.15.13 (v1310720) | Playable on an iPhone (upstream) |
-| Xenoblade Chronicles 2 | `0100E95004038000` | 2.1.0 (v983040) | Profile present; not verified on a phone |
-| Paper Mario: The Thousand-Year Door | `0100ECD018EBE000` | 1.0.1 (v65536) | Profile present; not verified on a phone |
-| The Legend of Zelda: Tears of the Kingdom | `0100F2C0115B6000` | 1.4.3 (v720896) | **Verified here** — builds, installs and runs on an iPhone; 304,243 files into 127 archive shards, byte-verified |
-| Pokémon Legends: Z-A | `0100F43008C44000` | 2.0.2 (v393216) | Profile present; not verified on a phone |
-| Brain Memory Training Academy | `0100F5D01DA3A000` | 无(v0) | Profile present; not verified on a phone |
-| Super Mario Galaxy 2 | `0100FD8022DAA000` | 1.4.0 (v393216) | Profile present; not verified on a phone |
-| Xenoblade Chronicles: Definitive Edition | `0100FF500E34A000` | 1.1.2 (v196608) | Profile present; not verified on a phone |
+| Xenoblade Chronicles 2 | `0100E95004038000` | 2.1.0 (v983040) | Profile present, not verified on a phone |
+| Paper Mario: The Thousand-Year Door | `0100ECD018EBE000` | 1.0.1 (v65536) | Profile present, not verified on a phone |
+| The Legend of Zelda: Tears of the Kingdom | `0100F2C0115B6000` | 1.4.3 (v720896) | **Verified here** — builds, installs and runs on an iPhone, 304,243 files into 127 archive shards, byte-verified |
+| Pokémon Legends: Z-A | `0100F43008C44000` | 2.0.2 (v393216) | Profile present, not verified on a phone |
+| Brain Memory Training Academy | `0100F5D01DA3A000` | 无(v0) | Profile present, not verified on a phone |
+| Super Mario Galaxy 2 | `0100FD8022DAA000` | 1.4.0 (v393216) | Profile present, not verified on a phone |
+| Xenoblade Chronicles: Definitive Edition | `0100FF500E34A000` | 1.1.2 (v196608) | Profile present, not verified on a phone |
## Verified on
- **Tears of the Kingdom** (0100F2C0115B6000, v1.0.0 + update 1.4.3): 304,243 files packed into 127
- files; all 304,243 byte-compared against the source (`verify: OK`); the game runs from the archive
+ files, and all 304,243 byte-compared against the source (`verify: OK`). The game runs from the archive
on macOS (1,905 frames at 30 fps).
- **Hades II** (0100A00019DE0000, base + update 1.0.137848): 5,258 files packed into 33 files,
byte-compare OK, and the game runs from the archive on macOS (2,100 frames, 1,772 archive reads).
@@ -298,11 +298,11 @@ update layers over it). "无(v0)" = the base game alone is enough.
**The jetsam budget is the limit on big titles, and it can be raised.** Without
`com.apple.developer.kernel.increased-memory-limit` an iPhone gives this app ~3,375 MB (measured on
a 12 GB device: Tears of the Kingdom was killed entering the world map at 3,342 MB resident with
-33 MB of headroom; lowering the render scale to 0.5 did not change it, so the limit is the guest
+33 MB of headroom. Lowering the render scale to 0.5 did not change it, so the limit is the guest
heap, not the GPU). The app requests the entitlement and `build_ipa.sh` embeds it in a placeholder
ad-hoc signature — an unsigned binary has no signature for a sideloader to read entitlements from,
so without that step the request would be lost. **AltStore Classic 2.2+**, **Impactor** and **Xcode
-with a Personal Team** keep it; **SideStore** with a free Apple ID needs a one-time App ID fix;
-**Sideloadly** does not. See [dm/ios/ENTITLEMENTS.md](dm/ios/ENTITLEMENTS.md) for the steps and how
+with a Personal Team** keep it. **SideStore** with a free Apple ID needs a one-time App ID fix,
+but **Sideloadly** does not. See [dm/ios/ENTITLEMENTS.md](dm/ios/ENTITLEMENTS.md) for the steps and how
to tell from `Documents/log.txt` (resident + headroom: ~3,375 MB = not in effect, 6–8 GB = it is).
diff --git a/GAMES.zh-CN.md b/GAMES.zh-CN.md
index f29192e7..1f6b457a 100644
--- a/GAMES.zh-CN.md
+++ b/GAMES.zh-CN.md
@@ -1,6 +1,6 @@
# 游戏
-本 fork 有 profile 的全部游戏,以及每款需要的更新包。玩家主页是 [README.zh-CN.md](README.zh-CN.md);[dm/games/README.md](dm/games/README.md)(英文)是引擎对每款游戏的笔记。截图和 IPA 大小在英文页的[图库](GAMES.md#gallery)里。English: [GAMES.md](GAMES.md).
+本 fork 有 profile 的全部游戏,以及每款需要的更新包。玩家主页是 [README.zh-CN.md](README.zh-CN.md)。[dm/games/README.md](dm/games/README.md)(英文)是引擎对每款游戏的笔记。截图和 IPA 大小在英文页的[图库](GAMES.md#gallery)里。English: [GAMES.md](GAMES.md).
## 实测游戏
@@ -16,7 +16,7 @@
## Profile 列表
本仓库自带 94 个游戏 profile。profile 决定了一个游戏能不能构建——build ID、内存布局、
-shader 表、每个游戏各自的开关;本 fork 在此基础上加了 RomFS 归档层,让大体积游戏能装得下。
+shader 表、每个游戏各自的开关。本 fork 在此基础上加了 RomFS 归档层,让大体积游戏能装得下。
「需要的更新包」就是构建时严格校验的版本:更新包 NSP 的显示版本必须与 profile 注册的 build 一致
(本体自身的版本无所谓——更新会叠加在本体上)。「无(v0)」= 只需本体。
@@ -67,7 +67,7 @@ shader 表、每个游戏各自的开关;本 fork 在此基础上加了 RomFS
| 任天堂明星大乱斗 特别版 | `01006A800016E000` | 13.0.5 (v2031616) | 上游报告 iPhone 可玩 |
| 塞尔达传说 织梦岛 | `01006BB00C6F0000` | 1.1.0 (v131072) | 上游报告 iPhone 可玩 |
| 勇者斗恶龙 XI S 寻觅逝去的时光 决定版 | `01006C300E9F0000` | 1.0.4 (v262144) | 有 profile,未在手机上验证 |
-| 集合啦!动物森友会 | `01006F8002326000` | 3.0.3 (v2228224) | **本 fork 已验证** —— 构建、安装、在 iPhone 上流畅运行;103,645 个文件归档成 72 片 |
+| 集合啦!动物森友会 | `01006F8002326000` | 3.0.3 (v2228224) | **本 fork 已验证** —— 构建、安装、在 iPhone 上流畅运行,103,645 个文件归档成 72 片 |
| AI 梦境档案 涅槃肇始 | `0100713016CCC000` | 1.0.2 (v131072) | 上游报告 iPhone 可玩 |
| 异界锁链 | `01007300020FA000` | 1.0.1 (v65536) | 上游报告 iPhone 可玩 |
| 异度神剑 3 | `010074F013262000` | 2.2.1 (v720896) | 有 profile,未在手机上验证 |
@@ -86,7 +86,7 @@ shader 表、每个游戏各自的开关;本 fork 在此基础上加了 RomFS
| 超级马力欧 银河 | `010099C022B96000` | 1.3.1 (v327680) | 上游报告 iPhone 可玩 |
| 奇诺比奥队长 宝物追踪 | `01009BF0072D4000` | 1.4.2 (v393216) | 有 profile,未在手机上验证 |
| 大金刚国度 归乡 HD | `01009D901BC56000` | 1.1.0 (v65536) | 有 profile,未在手机上验证 |
-| 哈迪斯 II | `0100A00019DE0000` | 1.0.137848 (v1) | **本 fork 已验证** —— 构建、安装、在 iPhone 上运行;33 个文件的归档 |
+| 哈迪斯 II | `0100A00019DE0000` | 1.0.137848 (v1) | **本 fork 已验证** —— 构建、安装、在 iPhone 上运行,33 个文件的归档 |
| 歧路旅人 II | `0100A3501946E000` | 1.1.1 (v131072) | 上游报告 iPhone 可玩 |
| Pokémon Scarlet | `0100A3D008C5C000` | 无(v0) | 有 profile,未在手机上验证 |
| 茶杯头 | `0100A5C00D162000` | 1.3.7 (v655360) | 有 profile,未在手机上验证 |
@@ -112,7 +112,7 @@ shader 表、每个游戏各自的开关;本 fork 在此基础上加了 RomFS
| 星露谷物语 | `0100E65002BB8000` | 1.6.15.13 (v1310720) | 上游报告 iPhone 可玩 |
| Xenoblade Chronicles 2 | `0100E95004038000` | 2.1.0 (v983040) | 有 profile,未在手机上验证 |
| 纸片马力欧 千年之门 | `0100ECD018EBE000` | 1.0.1 (v65536) | 有 profile,未在手机上验证 |
-| 塞尔达传说 王国之泪 | `0100F2C0115B6000` | 1.4.3 (v720896) | **本 fork 已验证** —— 构建、安装、在 iPhone 上运行;304,243 个文件归档成 127 片,逐字节校验通过 |
+| 塞尔达传说 王国之泪 | `0100F2C0115B6000` | 1.4.3 (v720896) | **本 fork 已验证** —— 构建、安装、在 iPhone 上运行,304,243 个文件归档成 127 片,逐字节校验通过 |
| 宝可梦传说 Z-A | `0100F43008C44000` | 2.0.2 (v393216) | 有 profile,未在手机上验证 |
| 脑力记忆训练学院 | `0100F5D01DA3A000` | 无(v0) | 有 profile,未在手机上验证 |
| 超级马力欧 银河 2 | `0100FD8022DAA000` | 1.4.0 (v393216) | 有 profile,未在手机上验证 |
@@ -124,8 +124,8 @@ shader 表、每个游戏各自的开关;本 fork 在此基础上加了 RomFS
## 验证情况
-- **《王国之泪》**(0100F2C0115B6000,v1.0.0 + 更新 1.4.3):304,243 个文件打成 127 个文件;
- 304,243 个文件全部与源目录逐字节比对通过(`verify: OK`);游戏从归档正常运行于 macOS
+- **《王国之泪》**(0100F2C0115B6000,v1.0.0 + 更新 1.4.3):304,243 个文件打成 127 个文件,
+ 304,243 个文件全部与源目录逐字节比对通过(`verify: OK`)。游戏从归档正常运行于 macOS
(30 fps,1,905 帧)。
- **《哈迪斯 2》**(0100A00019DE0000,本体 + 更新 1.0.137848):5,258 个文件打成 33 个文件,
逐字节比对通过,游戏从归档正常运行于 macOS(2,100 帧,1,772 次归档读取)。更新包无需特殊
@@ -136,10 +136,10 @@ shader 表、每个游戏各自的开关;本 fork 在此基础上加了 RomFS
**jetsam 预算是大体积游戏的限制,而它是可以提高的。** 没有
`com.apple.developer.kernel.increased-memory-limit` 时,iPhone 给这个 App 约 3,375 MB(12 GB
-设备实测:《王国之泪》进大地图时被杀,常驻 3,342 MB、余量 33 MB;渲染缩放降到 0.5 无改善,
+设备实测:《王国之泪》进大地图时被杀,常驻 3,342 MB、余量 33 MB,渲染缩放降到 0.5 无改善,
说明瓶颈在 guest 堆而不是 GPU)。App 请求了这个 entitlement,`build_ipa.sh` 把它嵌进占位用的
ad-hoc 签名——无签名的二进制没有可供侧载工具读取 entitlement 的签名,不做这一步请求就会丢失。
-**AltStore Classic 2.2+**、**Impactor** 和 **Xcode + Personal Team** 会保留它;**SideStore**
-配合免费 Apple ID 需要对 App ID 做一次性修复;**Sideloadly** 不会。步骤和判断方法(log.txt 里
+**AltStore Classic 2.2+**、**Impactor** 和 **Xcode + Personal Team** 会保留它。**SideStore**
+配合免费 Apple ID 需要对 App ID 做一次性修复,**Sideloadly** 不会。步骤和判断方法(log.txt 里
resident + headroom:约 3,375 MB = 未生效,6–8 GB = 已生效)见
[dm/ios/ENTITLEMENTS.md](dm/ios/ENTITLEMENTS.md)。
diff --git a/README.md b/README.md
index cf7d778c..048979fb 100644
--- a/README.md
+++ b/README.md
@@ -43,7 +43,7 @@ keeps your games in a library you start with **Play**, the way a Switch does.
<img src="frontend/screenshots/launcher-library.webp" width="100%" alt="The launcher: a library of built games, one build in progress">
It is a community fork of **[nxnative](https://github.com/seedds/nxnative)**, which does the actual
-work (the code rewriter, the Horizon host, NVN on Metal and every game's profile); this fork adds the
+work (the code rewriter, the Horizon host, NVN on Metal and every game's profile). This fork adds the
launcher and a short list of patches, and follows nxnative every day.
## Requirements
@@ -52,11 +52,11 @@ launcher and a short list of patches, and follows nxnative every day.
the iOS SDK, and NVN games need [Xcode](https://apps.apple.com/app/xcode/id497799835) 27.1 (macOS 26.6
or later) unless built with `--allow-other-metal`.
- **Your own game dumps** (NSP or XCI) and **your own `prod.keys`** from your own console. Nothing is
- bundled, downloaded or looked up for you. The same `prod.keys` opens every one of your games; a
+ bundled, downloaded or looked up for you. The same `prod.keys` opens every one of your games, and a
current dump covers all retail titles.
- For an iPhone: iOS 26 or later and a recent phone. Older devices are untested.
-The app carries its own build tools and Python, so no Homebrew and no Python install; the .NET SDK 10
+The app carries its own build tools and Python, so no Homebrew and no Python install. The .NET SDK 10
is the one tool it still installs for you. The launcher's dependency page checks each requirement and
installs what it can with one click.
@@ -65,9 +65,9 @@ installs what it can with one click.
1. **Download the app**: `NS-Port-Builder-macOS-arm64.zip` from the
[latest release](https://github.com/LNPANDY/NX2Apple/releases/latest). Unzip it.
2. **Open it once with right-click, then Open.** The app is not signed with a paid Apple developer
- certificate, so macOS asks before the first start; after that it opens normally.
+ certificate, so macOS asks before the first start, and after that it opens normally.
3. **Follow the setup.** The launcher fetches the project it builds with (a **Download repository**
- button on the setup page, a shallow clone into `~/NX2Apple`; if GitHub is slow, the page shows the
+ button on the setup page, a shallow clone into `~/NX2Apple`, and if GitHub is slow, the page shows the
manual ZIP route), checks the tools above and updates itself later. You never need git.
4. **Build a game.** Pick the game's folder (or its base game, update, DLC and `prod.keys` one by
one), choose **This Mac** or **iPhone / iPad**, and press build. The page shows the real stages and
@@ -80,10 +80,10 @@ Building by hand from a terminal is in [BUILDING.md](BUILDING.md).
**On the Mac**, a finished game appears in the library with its key art. **Play** starts it.
**Launch options** (per game, kept across rebuilds) set the frame rate, console mode (docked or
-handheld), render scale and upscaling, game language, controls and more; what each does is in
+handheld), render scale and upscaling, game language, controls and more. What each does is in
[docs/settings.md](docs/settings.md). A controller drives the launcher as well as the games.
-**On the iPhone**, the app shows the same settings before the game starts; tap **Play**. Touch
+**On the iPhone**, the app shows the same settings before the game starts. Tap **Play**. Touch
controls come in a 2D and a 3D layout (tap the button at the top centre), and a connected controller
(Xbox, PlayStation, Switch Pro, MFi) replaces them. [docs/playing.md](docs/playing.md) covers touch,
rumble and motion. Short stutters the first time a scene appears are normal: the app compiles
@@ -93,19 +93,19 @@ that the Files app picks.
**Game language.** English is the default. On the Mac, use the **Game language** row of Launch
options. For anything the sheet lacks, write an `env.txt` of `KEY=VALUE` lines (for example
`DM_LANG=zh-Hans`) in one of two places: `~/Library/Application Support/nxnative/<title ID>/env.txt`
-wins and survives rebuilds; `<App>.app/Contents/Resources/dm/env.txt` is the app's own. A Mac app
+wins and survives rebuilds, and `<App>.app/Contents/Resources/dm/env.txt` is the app's own. A Mac app
built before the language row existed needs one rebuild to get it. On the iPhone, the same lines go
in `Documents/env.txt` (`DM_FPS_TARGET=30` caps the frame rate to save battery, `DM_OPMODE=0` picks
handheld mode).
**Saves and logs.** A Mac game in a library folder keeps its saves and its log beside the app
-(`log/<title ID>.log`); otherwise they are in `~/Library/Application Support/nxnative/<title ID>/` and
+(`log/<title ID>.log`). Otherwise they are in `~/Library/Application Support/nxnative/<title ID>/` and
`~/Library/Logs/nxnative/<title ID>.log`. On the iPhone they are in the Files app under the app's
name: `save/` and `log.txt` (the previous run is `log.prev.txt`).
**Reporting a bug.** Use the [issue forms](https://github.com/LNPANDY/NX2Apple/issues/new/choose)
(game problem, build problem, launcher problem). Each asks for the game and its title ID, your
-versions and device, **Settings > Copy diagnostics** and the game's log; [CONTRIBUTING.md](CONTRIBUTING.md)
+versions and device, **Settings > Copy diagnostics** and the game's log. [CONTRIBUTING.md](CONTRIBUTING.md)
says why. A report with the full `log.txt` is looked at first. Never attach keys, game files or
anything extracted from a game.
@@ -117,11 +117,11 @@ been tried on a phone yet. A few of them:
| | Game | Where it runs | Status |
|---|---|---|---|
-| <img src="docs/images/zelda-tears-of-the-kingdom.jpg" width="96" alt=""> | The Legend of Zelda: Tears of the Kingdom | Mac and iPhone | **Verified here**: 304,243 files, byte-checked; ~17 GB |
+| <img src="docs/images/zelda-tears-of-the-kingdom.jpg" width="96" alt=""> | The Legend of Zelda: Tears of the Kingdom | Mac and iPhone | **Verified here**: 304,243 files, byte-checked, ~17 GB |
| <img src="docs/images/hades-ii.jpg" width="96" alt=""> | Hades II | Mac and iPhone | **Verified here** |
| <img src="docs/images/animal-crossing-new-horizons.jpg" width="96" alt=""> | Animal Crossing: New Horizons | iPhone | **Verified here**: runs smoothly |
| <img src="docs/images/super-mario-odyssey.jpg" width="96" alt=""> | Super Mario Odyssey | iPhone | Reported playable upstream |
-| <img src="docs/images/zelda-breath-of-the-wild.jpg" width="96" alt=""> | The Legend of Zelda: Breath of the Wild | iPhone | Reported playable upstream; 60 fps with 1.9.0 |
+| <img src="docs/images/zelda-breath-of-the-wild.jpg" width="96" alt=""> | The Legend of Zelda: Breath of the Wild | iPhone | Reported playable upstream, 60 fps with 1.9.0 |
| <img src="docs/images/mario-kart-8-deluxe.jpg" width="96" alt=""> | Mario Kart 8 Deluxe | iPhone | Reported playable upstream |
**[GAMES.md](GAMES.md)** (中文: [GAMES.zh-CN.md](GAMES.zh-CN.md)) has the screenshot gallery with each
@@ -130,17 +130,17 @@ display version must match the profile's, or the build says so.
## Limitations
-- **Only the games with a profile.** A title outside the list needs bring-up work of its own; the
+- **Only the games with a profile.** A title outside the list needs bring-up work of its own. The
place to start is [docs/agents](docs/agents/README.md), upstream's guide for another Switch title.
- **Big games on an iPhone hit a memory limit.** Without the Increased Memory Limit entitlement iOS
gives the app about 3.4 GB, which is not enough for Tears of the Kingdom. The app requests it, and
- AltStore Classic 2.2+, Impactor and Xcode with a Personal Team keep it; SideStore with a free Apple
+ AltStore Classic 2.2+, Impactor and Xcode with a Personal Team keep it. SideStore with a free Apple
ID needs a one-time App ID fix, and Sideloadly drops it ([the steps](dm/ios/ENTITLEMENTS.md)). The
full measurements are in [GAMES.md](GAMES.md#verified-on).
-- **Unsigned apps.** The launcher and the iPhone builds are not signed for you; you sideload them.
+- **Unsigned apps.** The launcher and the iPhone builds are not signed for you, so you sideload them.
- **Your own files.** No game data, firmware or keys are included or downloaded.
- **Older shard archives still load.** The first iPhone builds packed Tears of the Kingdom into a
- RomFS shard archive (`romfs.idx`); the build writes a single `romfs.img` now, and the reader for
+ RomFS shard archive (`romfs.idx`). The build writes a single `romfs.img` now, and the reader for
the old archives is still shipped ([docs/ROMFS_ARCHIVE.md](docs/ROMFS_ARCHIVE.md)).
## For developers
@@ -161,7 +161,7 @@ display version must match the profile's, or the build says so.
- **[v0lumehi](https://github.com/v0lumehi)** — **the Mac front end's launcher** (PR [#27](https://github.com/LNPANDY/NX2Apple/pull/27), 40 files): a game library with key art, per-game launch options, a real progress stream, and a Stop that ends the whole build's process group. The Mac app went from "a build form" to the first version of a launcher that opens like a Switch.
- **[m1guelpf](https://github.com/m1guelpf)** (Miguel Piedrafita) — two HLE fixes (PRs [#24](https://github.com/LNPANDY/NX2Apple/pull/24) and [#26](https://github.com/LNPANDY/NX2Apple/pull/26)): the missing `EnableAlbumImageTakenNotification` and `CreateWithAdjustableSystemClock` entries plus their snapshot type byte — each would have read a null in games that call them, and each came with a test.
-Want on this list? [Contributing](CONTRIBUTING.md#helping-with-games) says how to start; reports with a full log and fixes with a test move fastest.
+Want on this list? [Contributing](CONTRIBUTING.md#helping-with-games) says how to start. Reports with a full log and fixes with a test move fastest.
All of the engine work is other people's. This repository adds the launcher and the patch queue on top:
@@ -194,18 +194,18 @@ redistribute any protection — LibHac opens the user's own dumps with the user'
operation a console performs on a cartridge.
**Trademarks.** Not affiliated with, sponsored by or endorsed by Nintendo. "Nintendo Switch" and
-game titles are trademarks of Nintendo Co., Ltd.; all other trademarks belong to their respective
+game titles are trademarks of Nintendo Co., Ltd. All other trademarks belong to their respective
owners.
-**Your responsibility.** Laws on making a personal backup copy differ by country; some places do
+**Your responsibility.** Laws on making a personal backup copy differ by country, and some places do
not allow it at all. You are responsible for knowing and following the law where you live, and for
never distributing game files, keys or the packages built from them — the project's outputs are for
personal use on your own hardware only. If you enjoy a game, buy it.
**Takedowns.** If you believe anything in this repository infringes your rights, open an issue or
-contact the maintainer directly; valid claims will be actioned promptly, up to removing content or
+contact the maintainer directly. Valid claims will be actioned promptly, up to removing content or
the repository.
**No warranty.** The software is provided "as is" under the licenses in [LICENSE](LICENSE) (this
-fork adds to upstream's; see the credits) — without warranty of any kind, express or implied. Use
+fork adds to upstream's, as the credits show) — without warranty of any kind, express or implied. Use
it at your own risk.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 3775e87f..df43898d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -42,26 +42,26 @@ NX2Apple 用你自己导出的游戏文件,在你的 Mac 和 iPhone 上运行
<img src="frontend/screenshots/launcher-library.webp" width="100%" alt="启动器:已构建游戏的游戏库,和一个正在进行的构建">
它是 **[nxnative](https://github.com/seedds/nxnative)** 的社区 fork。真正的工作(代码改写器、Horizon
-宿主层、NVN-on-Metal 和每个游戏的 profile)都是 nxnative 的;本 fork 在其上增加启动器和少量补丁,
+宿主层、NVN-on-Metal 和每个游戏的 profile)都是 nxnative 的。本 fork 在其上增加启动器和少量补丁,
并每天跟随 nxnative 更新。
## 环境要求
-- **Apple Silicon Mac。** 启动器支持 **macOS 13 或更新**。构建需要装了 iOS SDK 的 Xcode;NVN 游戏需要
+- **Apple Silicon Mac。** 启动器支持 **macOS 13 或更新**。构建需要装了 iOS SDK 的 Xcode,NVN 游戏需要
[Xcode](https://apps.apple.com/app/xcode/id497799835) 27.1(macOS 26.6 或更新),除非加 `--allow-other-metal`。
- **你自己的游戏文件**(NSP 或 XCI)和**你自己主机里导出的 `prod.keys`**。本项目不自带、不下载、
- 也不替你查找任何东西。一份 `prod.keys` 能解你所有的游戏;新导出的一份覆盖所有零售游戏。
+ 也不替你查找任何东西。一份 `prod.keys` 能解你所有的游戏,新导出的一份覆盖所有零售游戏。
- 要装到 iPhone:iOS 26 或更新,以及较新的手机。更旧的设备未测试。
-App 自带构建工具和 Python,不需要装 Homebrew 和 Python;.NET SDK 10 仍由 App 帮你安装。启动器的依赖页会逐项检查,能装的一键安装。
+App 自带构建工具和 Python,不需要装 Homebrew 和 Python,但 .NET SDK 10 仍由 App 帮你安装。启动器的依赖页会逐项检查,能装的一键安装。
## 安装
1. **下载 App**:从[最新版本](https://github.com/LNPANDY/NX2Apple/releases/latest)下载
`NS-Port-Builder-macOS-arm64.zip`,解压。
2. **首次启动:右键 → 打开。** 这个 App 没有付费的 Apple 开发者证书签名,所以 macOS 在第一次启动时会
- 询问;之后就能正常打开。
-3. **按设置页走。** 启动器会取回构建用的项目(设置页上的「下载仓库」按钮,浅克隆到 `~/NX2Apple`;
+ 询问,之后就能正常打开。
+3. **按设置页走。** 启动器会取回构建用的项目(设置页上的「下载仓库」按钮,浅克隆到 `~/NX2Apple`,
GitHub 不顺手时页面会给出手动 ZIP 的路线),检查上面的工具,之后还会自己更新。全程不需要懂 git。
4. **构建游戏。** 选好游戏文件夹(或者分别选本体、更新包、DLC 和 `prod.keys`),选择「这台 Mac」或
「iPhone / iPad」,按构建。页面显示真实的阶段和剩余时间,中途停止的构建会从上次继续。iPhone 构建
@@ -72,7 +72,7 @@ App 自带构建工具和 Python,不需要装 Homebrew 和 Python;.NET SDK 1
## 游玩
**在 Mac 上**,构建好的游戏带着封面出现在游戏库里,点 **Play** 启动。**启动选项**(按游戏保存,重新
-构建后仍然保留)可设置帧率、主机模式(底座或掌机)、渲染缩放和超分辨率、游戏语言、操控等;每项的
+构建后仍然保留)可设置帧率、主机模式(底座或掌机)、渲染缩放和超分辨率、游戏语言、操控等。每项的
作用见 [docs/settings.md](docs/settings.md)(英文)。手柄既能操作游戏,也能操作启动器。
**在 iPhone 上**,App 在游戏开始前显示同样的设置,点 **Play** 即可。触屏操控有 2D 和 3D 两种布局
@@ -82,17 +82,17 @@ App 会为它编译一次图形并记住。游戏数据(`romfs.img`)可以
**游戏语言。** 默认英文。Mac 上用启动选项里的「游戏语言」一行。面板里没有的设置,可以写一个
`env.txt`,每行 `KEY=VALUE`(例如 `DM_LANG=zh-Hans`),放在两处之一:
-`~/Library/Application Support/nxnative/<title ID>/env.txt` 优先,重新构建后仍在;
+`~/Library/Application Support/nxnative/<title ID>/env.txt` 优先,重新构建后仍在,
`<App>.app/Contents/Resources/dm/env.txt` 是 App 自带的。在加入语言选项之前构建的 Mac App 需要重新构建
一次才有该项。iPhone 上同样的行写在 `Documents/env.txt` 里(`DM_FPS_TARGET=30` 限帧省电,
`DM_OPMODE=0` 选掌机模式)。
-**存档和日志。** 放在游戏库文件夹里的 Mac 游戏,存档和日志在 App 旁边(`log/<title ID>.log`);否则在
+**存档和日志。** 放在游戏库文件夹里的 Mac 游戏,存档和日志在 App 旁边(`log/<title ID>.log`)。否则在
`~/Library/Application Support/nxnative/<title ID>/` 和 `~/Library/Logs/nxnative/<title ID>.log`。
iPhone 上在「文件」App 里该 App 名字下:`save/` 和 `log.txt`(上一次运行的是 `log.prev.txt`)。
**报告问题。** 请用[问题表单](https://github.com/LNPANDY/NX2Apple/issues/new/choose)(游戏问题、构建问题、
-启动器问题)。表单会要你填游戏和 title ID、版本和设备、**设置 > 复制诊断信息**,以及游戏的日志;
+启动器问题)。表单会要你填游戏和 title ID、版本和设备、**设置 > 复制诊断信息**,以及游戏的日志。
为什么需要见 [CONTRIBUTING.md](CONTRIBUTING.md)(英文)。附上完整 `log.txt` 的报告会优先处理。
千万不要附上密钥、游戏文件或任何从游戏中提取的内容。
@@ -103,11 +103,11 @@ iPhone 上在「文件」App 里该 App 名字下:`save/` 和 `log.txt`(上
| | 游戏 | 运行于 | 状态 |
|---|---|---|---|
-| <img src="docs/images/zelda-tears-of-the-kingdom.jpg" width="96" alt=""> | 塞尔达传说:王国之泪 | Mac 和 iPhone | **本 fork 验证**:304,243 个文件,逐字节校验;约 17 GB |
+| <img src="docs/images/zelda-tears-of-the-kingdom.jpg" width="96" alt=""> | 塞尔达传说:王国之泪 | Mac 和 iPhone | **本 fork 验证**:304,243 个文件,逐字节校验,约 17 GB |
| <img src="docs/images/hades-ii.jpg" width="96" alt=""> | Hades II | Mac 和 iPhone | **本 fork 验证** |
| <img src="docs/images/animal-crossing-new-horizons.jpg" width="96" alt=""> | 集合啦!动物森友会 | iPhone | **本 fork 验证**:流畅运行 |
| <img src="docs/images/super-mario-odyssey.jpg" width="96" alt=""> | 超级马力欧 奥德赛 | iPhone | 上游报告可玩 |
-| <img src="docs/images/zelda-breath-of-the-wild.jpg" width="96" alt=""> | 塞尔达传说:旷野之息 | iPhone | 上游报告可玩;1.9.0 可 60 fps |
+| <img src="docs/images/zelda-breath-of-the-wild.jpg" width="96" alt=""> | 塞尔达传说:旷野之息 | iPhone | 上游报告可玩,1.9.0 可 60 fps |
| <img src="docs/images/mario-kart-8-deluxe.jpg" width="96" alt=""> | 马力欧卡丁车 8 豪华版 | iPhone | 上游报告可玩 |
**[GAMES.zh-CN.md](GAMES.zh-CN.md)**(English: [GAMES.md](GAMES.md),带截图图库和每款的安装大小)
@@ -115,22 +115,22 @@ iPhone 上在「文件」App 里该 App 名字下:`save/` 和 `log.txt`(上
## 限制
-- **只支持有 profile 的游戏。** 列表之外的游戏需要单独的 bring-up 工作;起点是
+- **只支持有 profile 的游戏。** 列表之外的游戏需要单独的 bring-up 工作。起点是
[docs/agents](docs/agents/README.md)(上游为其他 Switch 游戏写的指南,英文)。
- **大体积游戏在 iPhone 上会碰到内存上限。** 没有 Increased Memory Limit entitlement 时 iOS 只给 App
约 3.4 GB,不够《王国之泪》用。App 请求了它,AltStore Classic 2.2+、Impactor 和 Xcode + Personal Team
- 会保留;SideStore 配合免费 Apple ID 需要对 App ID 做一次性修复,Sideloadly 会丢掉它
+ 会保留。SideStore 配合免费 Apple ID 需要对 App ID 做一次性修复,Sideloadly 会丢掉它
([步骤](dm/ios/ENTITLEMENTS.md))。完整的测量见 [GAMES.zh-CN.md](GAMES.zh-CN.md#验证情况)。
- **App 未签名。** 启动器和 iPhone 构建不会替你签名,需要你自己侧载。
- **你自己的文件。** 不包含也不下载任何游戏数据、固件或密钥。
-- **旧的分片归档仍能加载。** 最早的 iPhone 构建把《王国之泪》打成 RomFS 分片归档(`romfs.idx`);现在
+- **旧的分片归档仍能加载。** 最早的 iPhone 构建把《王国之泪》打成 RomFS 分片归档(`romfs.idx`)。现在
构建写出单个 `romfs.img`,但旧归档的读取层仍然随附([docs/ROMFS_ARCHIVE.md](docs/ROMFS_ARCHIVE.md))。
## 给开发者
- **从源码构建:** [BUILDING.zh-CN.md](BUILDING.zh-CN.md)。**报告或修复问题:** [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。
- **本 fork 对上游改了什么:** 引擎(`dm/`、`scripts/`、`docs/`、`ref/`、`AGENTS.md`)就是 nxnative 在固定提交上的
- 内容,加一组补丁,每个补丁写明本 fork 为什么带着它。见 [patches/README.md](patches/README.md);
+ 内容,加一组补丁,每个补丁写明本 fork 为什么带着它。见 [patches/README.md](patches/README.md)。
`python3 scripts/patches.py status` 列出带着的全部补丁。每天一次的任务移动固定提交并开 pull request,
某个补丁对不上时开一个点名该补丁的 issue。
- **其他 Switch 游戏:** [docs/agents](docs/agents/README.md)(解包、二进制调查、bring-up)。
@@ -143,7 +143,7 @@ iPhone 上在「文件」App 里该 App 名字下:`save/` 和 `log.txt`(上
- **[v0lumehi](https://github.com/v0lumehi)** —— **Mac 前端的启动器界面**(PR [#27](https://github.com/LNPANDY/NX2Apple/pull/27),40 个文件):游戏库、封面图、每游戏启动选项、真进度流、能真正结束整个构建进程组的 Stop。Mac 端从"一个构建表单"变成了"打开像一台 Switch 的启动器"的第一版。
- **[m1guelpf](https://github.com/m1guelpf)**(Miguel Piedrafita)—— 两个 HLE 修复(PR [#24](https://github.com/LNPANDY/NX2Apple/pull/24)、[#26](https://github.com/LNPANDY/NX2Apple/pull/26)):补上了 `EnableAlbumImageTakenNotification` 和 `CreateWithAdjustableSystemClock` 及其快照类型字节——两个原本会让游戏读到空指针的缺失条目,各带测试。
-想加入这个列表?[参与贡献](CONTRIBUTING.zh-CN.md#帮忙补充游戏)写了怎么开始;issue 里附上完整日志的报告和带测试的修复最快。
+想加入这个列表?[参与贡献](CONTRIBUTING.zh-CN.md#帮忙补充游戏)写了怎么开始。issue 里附上完整日志的报告和带测试的修复最快。
所有底层引擎的工作都是别人的。本仓库在其之上增加了启动器和补丁队列:
@@ -170,13 +170,13 @@ NSP/XCI 导出文件,且不连接任何服务器。它不绕过、不移除、
密钥打开用户自己的导出文件,和主机读取卡带执行的是同一种操作。
**商标。** 与任天堂无关联,也未获得其赞助或认可。"Nintendo Switch" 及各游戏名称是任天堂株式会社的
-商标;其他商标归各自权利人所有。
+商标。其他商标归各自权利人所有。
**你的责任。** 制作个人备份副本的法律因国家而异,有些地方完全不允许。你有责任了解并遵守所在地的
法律,并且绝不分发游戏文件、密钥或由它们构建出的安装包——本项目的产物仅供在你自己的硬件上个人使用。
喜欢哪个游戏,请购买它。
-**下架。** 如果你认为本仓库中的任何内容侵犯了你的权利,请开 issue 或直接联系维护者;有效的权利
+**下架。** 如果你认为本仓库中的任何内容侵犯了你的权利,请开 issue 或直接联系维护者。有效的权利
主张会得到及时处理,包括删除相关内容乃至整个仓库。
**无担保。** 本软件按 [LICENSE](LICENSE) 中的许可证(本 fork 在上游之上有所附加,见致谢)以"现状"
diff --git a/dm/ios/ENTITLEMENTS.md b/dm/ios/ENTITLEMENTS.md
index de284eb2..5808b59e 100644
--- a/dm/ios/ENTITLEMENTS.md
+++ b/dm/ios/ENTITLEMENTS.md
@@ -16,7 +16,7 @@ Measured here, both on a 12 GB iPhone:
| Game | Peak resident | Headroom | Result |
|---|---|---|---|
| Tears of the Kingdom | 3,342 MB | 33 MB | killed entering the world map |
-| Hades II | — | — | asks for a 3.10 GB heap; at the budget limit |
+| Hades II | — | — | asks for a 3.10 GB heap, which is at the budget limit |
Lowering the render scale to 0.5 did not change the Tears of the Kingdom outcome, so the limit is
the guest heap rather than the GPU. The only way past it is a higher budget.
@@ -41,7 +41,7 @@ Reported by [playport.dev](https://playport.dev/) (a different project with the
| Impactor (from a computer) | Yes |
| Xcode with a Personal Team | Yes |
| SideStore 0.7.0, free Apple ID | Not by default — see below |
-| Sideloadly and others | Check the tool; Sideloadly does not enable it |
+| Sideloadly and others | Check the tool. Sideloadly does not enable it |
## SideStore with a free Apple ID
@@ -51,8 +51,8 @@ The entitlement attaches to the App ID, so it survives the weekly refresh once s
2. Sideload **GetMoreRam** and sign in with the same Apple ID SideStore uses.
3. In GetMoreRam open **App IDs**, tap **Refresh**, select this app's App ID, then
**Add Increased Memory Limit**.
-4. Reinstall the app from SideStore (it upgrades in place; `Documents/` — the RomFS archive and the
- saves — is preserved).
+4. Reinstall the app from SideStore (it upgrades in place, and `Documents/`, the RomFS archive and the
+ saves, is preserved).
5. Confirm: `Documents/log.txt` should now show a much larger `headroom to the system memory limit`
in the `memory up to frame N` lines. GetMoreRam uses one of a free Apple ID's three app slots, so
delete it afterwards if you need the slot back.
@@ -87,14 +87,14 @@ codesign -d --entitlements :- Payload/DmIOS.app/DmIOS | grep increased-memory-li
```
Measured here (12 GB iPhone, AltStore Classic 2.3): before the placeholder signature the budget was
-3,375 MB and Hades II died entering a larger scene; after it the game runs. If the budget stays at
+3,375 MB and Hades II died entering a larger scene. After it the game runs. If the budget stays at
3,375 MB with a signed IPA, the remaining step is on the App ID — enable the capability with a tool
like GetMoreRam (same Apple ID as the sideloader, App IDs → Refresh → select the app → Add
Increased Memory Limit), then reinstall so the profile picks it up.
## Xcode route
-A project prepared with `--prepare-xcode` already carries the entitlement (`Gen/DmIOS.entitlements`);
-with a Personal Team and a real device, build from there. That is the one route where the app is
+A project prepared with `--prepare-xcode` already carries the entitlement (`Gen/DmIOS.entitlements`).
+With a Personal Team and a real device, build from there. That is the one route where the app is
signed at build time, so no re-signing step can drop the entitlement. The Mac launcher's
**Install on** uses this route.
diff --git a/docs/MULTIPLAYER.md b/docs/MULTIPLAYER.md
index 39558eb5..f29c8188 100644
--- a/docs/MULTIPLAYER.md
+++ b/docs/MULTIPLAYER.md
@@ -44,7 +44,7 @@ Port **11451** by default, plain UDP, one byte of type followed by the payload.
| `0x01` | IPv4 | both | a whole IP packet |
| `0x02` | ping | client → server | 4 random bytes (echoed back) |
| `0x03` | IPv4 fragment | both | 16-byte header + data (below) |
-| `0x04` | auth | server → client | the server asks for a login; implementations without it log and continue |
+| `0x04` | auth | server → client | the server asks for a login, and implementations without it log and continue |
| `0x10` | info | server → client | a UTF-8 message to show the player |
The high bit (`type & 0x7F`) is masked off on receive, so `0x81` is accepted as IPv4.
@@ -64,7 +64,7 @@ Reassembly keeps a table keyed by `(source, fragment id)`, drops entries older t
mismatched totals or MTUs, and concatenates parts in index order.
**Client behaviour**: keepalive + ping every 10 s, consider the server lost after 30 s of
-silence, reconnect every 5 s on failure. The client picks its virtual address itself; the server
+silence, reconnect every 5 s on failure. The client picks its virtual address itself, and the server
maps it to the connection.
A real Switch can join a lan-play server, which is the whole point: this is how Switch players
@@ -83,7 +83,7 @@ them. Simpler than lan-play, but only works when everyone shares one subnet.
Peer discovery without a router, using the platform's peer-to-peer mechanism (mush8 uses mDNS /
DNS-SD to advertise and browse, `dnssd.rs`: `DNSServiceRegister` / `DNSServiceBrowse` /
`DNSServiceResolve` / `DNSServiceGetAddrInfo`). Each player advertises a service and browses for
-the others; the first contact becomes the transport.
+the others, and the first contact becomes the transport.
## What the game needs above the transport
@@ -108,8 +108,8 @@ Roughly four layers, in order:
|---|---|---|
| 1. BSD sockets | `socket`/`bind`/`sendto`/`recvfrom`/`poll`/`select` over the virtual network, with the errno conventions the SDK expects | new `dm/host/hle_bsd.c` (replaces the offline stubs in `hle_offline.c`) |
| 2. Virtual network | address/MASK/gateway, per-port socket registry, broadcast rules, receive queues, wake-on-packet for `poll` | new `dm/host/dm_vnet.c` |
-| 3. Transports | lan-play framing + reassembly; LAN broadcast; wireless via mDNS | one file per transport |
-| 4. `ldn` / `nifm` | make the game believe a session can exist; per-game payload mapping | `hle_ldn.c`, and per-game code |
+| 3. Transports | lan-play framing and reassembly, LAN broadcast, wireless via mDNS | one file per transport |
+| 4. `ldn` / `nifm` | make the game believe a session can exist, per-game payload mapping | `hle_ldn.c`, and per-game code |
Layers 1–3 are game independent and reusable. Layer 4 is where a new title costs work again.
@@ -122,7 +122,7 @@ documented above and it is the title mush8 proved) ≈ 2–3 weeks. Each further
- **Does our Metal host survive packet injection at frame rate?** Untested. The transport runs
on its own thread, but `poll` must wake a blocked guest thread promptly.
- **iOS local network permission**: iOS 14+ shows a prompt and the entitlement
- `com.apple.developer.networking.multicast` may be needed for broadcast; a sideloaded unsigned
+ `com.apple.developer.networking.multicast` may be needed for broadcast. A sideloaded unsigned
IPA cannot carry it, which could make LAN mode impossible on iOS while lan-play (unicast UDP)
still works.
- **Matching the game update to the Switch's**, per mush8's note — our profiles already pin an
@@ -136,4 +136,4 @@ documented above and it is the title mush8 proved) ≈ 2–3 weeks. Each further
- [c22dev/mush8](https://github.com/c22dev/mush8) — `crates/nxhost/src/services/{vnet,lanplay,lan,wireless}.rs`,
`crates/nxhost/src/dnssd.rs` (read at commit 0.1).
- lan-play itself is a public protocol with several open implementations (switch-lan-play and
- clients for it); the constant table above matches what mush8 implements.
+ clients for it), and the constant table above matches what mush8 implements.
diff --git a/docs/RELEASE-NOTES-GUIDE.md b/docs/RELEASE-NOTES-GUIDE.md
index a8378ef2..116d6e85 100644
--- a/docs/RELEASE-NOTES-GUIDE.md
+++ b/docs/RELEASE-NOTES-GUIDE.md
@@ -53,11 +53,11 @@ same section order, and a reader picks one and reads straight through.
The two halves use the **same headings in the same order** (the Chinese ones are the translations
of the English ones), and the same number of items under each heading. Item 2 in English is item 2
-in Chinese; a reader comparing the two must not have to map lists.
+in Chinese, so a reader comparing the two does not have to map lists.
Rules that matter more than the template:
-1. **English first.** It is the canonical text; the Chinese half is written from it.
+1. **English first.** It is the canonical text, and the Chinese half is written from it.
2. **Both halves say the same thing.** Not "a translation of the headline and a summary of the
rest" — a user reading either half must learn everything the other one learns.
3. **Never split a section across the two halves.** All of Fixes is in one place, then all of
@@ -75,10 +75,10 @@ changing the template means checking that sheet's tests too.
## Where the text comes from
-- `CHANGELOG.md` and `CHANGELOG.zh-CN.md` share an update-history table; a release row goes in both, the
+- `CHANGELOG.md` and `CHANGELOG.zh-CN.md` share an update-history table. A release row goes in both, the
English one first (it is the canonical project history), then translated.
- The release body itself is written once, in both languages, and is what `gh release edit
- --notes-file` takes. Keep the file in `/tmp` while working; the release is the record.
+ --notes-file` takes. Keep the file in `/tmp` while working, since the release is the record.
- If a fact differs per platform (a macOS-only fix), say which platform in the same sentence in both
languages rather than relying on the reader's inference.
diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
index c8adbaab..2f1132cb 100644
--- a/docs/RELEASE_NOTES.md
+++ b/docs/RELEASE_NOTES.md
@@ -11,27 +11,27 @@ This is the text of the [v0.5.0 release](https://github.com/LNPANDY/NX2Apple/rel
- **Launch options live in the game's own store**: one string per setting (`launcher.<VAR>`) in the app's preferences domain, exactly where upstream's launcher reads them — Finder and Dock starts included. Only non-default values are kept, an earlier launcher's choices migrate once, and schema 1 is read properly: sub-settings appear only when their parent has the value (`needs`), sections the launcher has no name for draw after the known ones in list order, and range limits come from the row. A newer schema is read as far as it can be and noted in the log, never refused.
- **The library's Manage menu in the launcher's own style** — and a controller can open and drive it.
- **Build tools update themselves**: a ZIP copy of an old release is connected to git by itself when the app opens (your own edits are preserved on a branch), and a build refuses to start when the tools are older than the app instead of failing at the last step.
-- **Install with just an Apple ID**: signing teams come from Xcode's provisioning preferences (personal teams are labelled), merged with the certificates'. With no certificate at all, Xcode creates one at the first install (`-allowProvisioningUpdates`); the messages say so, and with neither an Apple ID nor a certificate they say exactly where to sign in.
-- **The installer asks before copying game files**: USB from the Mac runs at about 25–70 MB/s, so the dialog offers transfer now or skip — the game installs either way, and the outcome card gains a "Game data (romfs.img)" row with Reveal in Finder for a manual copy (a fast external drive handed to the device is quicker; the launcher's Game data picker loads from it).
-- **Issue forms**: game, build and launcher problems each ask for what a report needs (versions, device, Copy diagnostics, the game's log) and refuse to submit without it; a PR template and CONTRIBUTING.md set the same rules for tools.
+- **Install with just an Apple ID**: signing teams come from Xcode's provisioning preferences (personal teams are labelled), merged with the certificates'. With no certificate at all, Xcode creates one at the first install (`-allowProvisioningUpdates`). The messages say so, and with neither an Apple ID nor a certificate they say exactly where to sign in.
+- **The installer asks before copying game files**: USB from the Mac runs at about 25–70 MB/s, so the dialog offers transfer now or skip — the game installs either way, and the outcome card gains a "Game data (romfs.img)" row with Reveal in Finder for a manual copy (a fast external drive handed to the device is quicker, and the launcher's Game data picker loads from it).
+- **Issue forms**: game, build and launcher problems each ask for what a report needs (versions, device, Copy diagnostics, the game's log) and refuse to submit without it. A PR template and CONTRIBUTING.md set the same rules for tools.
## Fixes
- **iPhone: choosing game data sticks.** The bookmark is written while the Files app's security scope is held (one written without it resolves to nothing from the next launch on — every pick read as "the app was signed differently"), saved only after a round-trip resolves, and a stale-but-readable bookmark rewrites itself instead of making you pick again. The resolved scope stays held for the session, since the game reads the image the whole time.
- **iPhone: no game data is no dead end.** A fresh install with nothing in Documents and no pick ever made boots into the launcher (the old build stopped on a static "Game files not found" page that never mentioned the picker), and Play (re)locates the data first — a pick made this session applies at once, with save/temp following the final location. An app without a launcher falls back to the static hint.
-- **iPhone: the signing retry keeps its stage row.** The team-variant retry appended a second "Sign for …" row with the same id that no update ever reached; it spun for ever after the build moved on. A retried stage now reuses its row.
+- **iPhone: the signing retry keeps its stage row.** The team-variant retry appended a second "Sign for …" row with the same id that no update ever reached, so it spun for ever after the build moved on. A retried stage now reuses its row.
- **Mac: every extracted game version is kept as the build resource it is.** The versions a profile's shader tables were made from are inputs to the shader split on every build, so deleting the packed version's siblings traded a full re-extraction of the base game for disk space — the wrong trade, and it is undone.
-- **Sync: the next upstream sync runs.** Upstream's latest commits stopped the sync and would have silently lost fork code; every patcher is now tested against real upstream in CI, a `--check-protection` run lists any hand-edited file no table covers, and files the fork owns outright are registered so a sync cannot revert them.
+- **Sync: the next upstream sync runs.** Upstream's latest commits stopped the sync and would have silently lost fork code. Every patcher is now tested against real upstream in CI, a `--check-protection` run lists any hand-edited file no table covers, and files the fork owns outright are registered so a sync cannot revert them.
## Known issues
-- **Mods have not been played with a real mod yet**: the layouts and the environment string are verified; the actual overlay is not.
+- **Mods have not been played with a real mod yet**: the layouts and the environment string are verified, but the actual overlay is not.
- **Windows**: not provided on this page — the front end is verified on real hardware, the full build pipeline is not. The Actions artifact `NS-Port-Builder-qt-windows-x64` has the current front end.
## Install
- **macOS**: download `NX2Apple-macOS-arm64.zip`, unzip, then right-click → Open on first launch. In-app updates work from 0.4.9 on under the NX2Apple name (older versions: download this one by hand).
-- **Windows**: not provided on this page; the Actions artifact has the Qt front end.
+- **Windows**: not provided on this page, but the Actions artifact has the Qt front end.
## Credits
@@ -46,20 +46,20 @@ This is the text of the [v0.5.0 release](https://github.com/LNPANDY/NX2Apple/rel
## 新增
-- **启动选项存进游戏自己的存储**:每个设置一条字符串(`launcher.<VAR>`),写在 App 的偏好域里——正是上游启动器读取的位置,Finder 和 Dock 启动同样生效。只保留非默认值,旧启动器的选择一次性迁移;schema 1 完整支持:父项有值才显示子项(`needs`)、启动器不认识的分组按列表顺序排在已知分组之后、范围上下限来自条目本身。更新版的 schema 能读多少读多少并写进日志,绝不拒绝。
+- **启动选项存进游戏自己的存储**:每个设置一条字符串(`launcher.<VAR>`),写在 App 的偏好域里——正是上游启动器读取的位置,Finder 和 Dock 启动同样生效。只保留非默认值,旧启动器的选择一次性迁移。schema 1 完整支持:父项有值才显示子项(`needs`)、启动器不认识的分组按列表顺序排在已知分组之后、范围上下限来自条目本身。更新版的 schema 能读多少读多少并写进日志,绝不拒绝。
- **游戏库的 Manage 菜单换成启动器同款风格**——并且可以用手柄打开和操作。
-- **构建工具自己更新**:旧版 ZIP 拷贝在 App 打开时自动接上 git(你自己的修改保留在分支上);工具比 App 旧时直接拒绝开始构建,而不是到最后一步才失败。
-- **只凭 Apple ID 就能安装**:签名团队从 Xcode 的开发者偏好里读取(个人团队会标注),与证书里的合并。一个证书都没有时,Xcode 在第一次安装时自动创建(`-allowProvisioningUpdates`);提示语会说明这一点,既没有 Apple ID 也没有证书时,会告诉你确切该去哪里登录。
-- **安装器在拷贝游戏文件前先询问**:Mac 经 USB 向 iPhone 只有约 25–70 MB/s,弹窗提供"现在传输"或"暂不传输"——两种选择游戏都会装上;结果卡片新增"游戏数据(romfs.img)"一行,带"在访达中显示",方便手动拷贝(把高速外接盘直接连 iPhone 更快,启动器的"选择游戏数据"可以从那里加载)。
-- **Issue 表单**:游戏/构建/启动器三类问题各自要求报告所需的信息(版本、设备、Copy 诊断、游戏日志),缺了就提交不了;PR 模板和 CONTRIBUTING.md 给工具立了同样的规矩。
+- **构建工具自己更新**:旧版 ZIP 拷贝在 App 打开时自动接上 git(你自己的修改保留在分支上),工具比 App 旧时直接拒绝开始构建,而不是到最后一步才失败。
+- **只凭 Apple ID 就能安装**:签名团队从 Xcode 的开发者偏好里读取(个人团队会标注),与证书里的合并。一个证书都没有时,Xcode 在第一次安装时自动创建(`-allowProvisioningUpdates`),提示语会说明这一点,既没有 Apple ID 也没有证书时,会告诉你确切该去哪里登录。
+- **安装器在拷贝游戏文件前先询问**:Mac 经 USB 向 iPhone 只有约 25–70 MB/s,弹窗提供"现在传输"或"暂不传输"——两种选择游戏都会装上,结果卡片新增"游戏数据(romfs.img)"一行,带"在访达中显示",方便手动拷贝(把高速外接盘直接连 iPhone 更快,启动器的"选择游戏数据"可以从那里加载)。
+- **Issue 表单**:游戏/构建/启动器三类问题各自要求报告所需的信息(版本、设备、Copy 诊断、游戏日志),缺了就提交不了。PR 模板和 CONTRIBUTING.md 给工具立了同样的规矩。
## 修复
- **iPhone:选择游戏数据终于能记住。** 书签在 Files App 的安全作用域被持有期间写入(不持作用域写出的书签从下次启动起就解析不了——于是每次选择都报"签名不同"),保存前先验证能读回,能解析但过期的书签自动重写而不必重选。解析出的作用域在整个会话期间持有,因为游戏全程都在读镜像。
-- **iPhone:没有游戏数据不再是死路。** 全新安装、Documents 里没有数据、也从没选过路径时,App 会正常进启动器(旧版停在一句静态的"Game files not found"上,绝口不提选择器);按 Play 时先重新定位数据——本次会话的选择立即生效,存档/临时目录跟着最终位置走。没有启动器的极简包才回退到静态提示。
+- **iPhone:没有游戏数据不再是死路。** 全新安装、Documents 里没有数据、也从没选过路径时,App 会正常进启动器(旧版停在一句静态的"Game files not found"上,绝口不提选择器),按 Play 时先重新定位数据——本次会话的选择立即生效,存档/临时目录跟着最终位置走。没有启动器的极简包才回退到静态提示。
- **iPhone:签名重试复用同一行。** 团队变体重试会追加一行同 ID 的"为 … 签名",而所有更新都只打到第一行——构建都走完了它还在转圈。重试的步骤现在复用自己的行。
- **Mac:每个解包版本都作为构建资源保留。** 游戏 shader 表登记的来源版本是每次构建 shader split 的输入,删掉打包版本之外的版本,等于拿整份基础版重解去换磁盘空间——这笔账不划算,已撤销。
-- **同步:下一次上游同步能跑通了。** 上游最新提交会让同步中断并悄悄丢掉 fork 代码;现在每个补丁器都在 CI 里对着真实上游测试,`--check-protection` 会列出任何没被登记的手改文件,fork 完全 own 的文件也已登记、同步不会回退它们。
+- **同步:下一次上游同步能跑通了。** 上游最新提交会让同步中断并悄悄丢掉 fork 代码。现在每个补丁器都在 CI 里对着真实上游测试,`--check-protection` 会列出任何没被登记的手改文件,fork 完全 own 的文件也已登记、同步不会回退它们。
## 已知问题
@@ -69,7 +69,7 @@ This is the text of the [v0.5.0 release](https://github.com/LNPANDY/NX2Apple/rel
## 安装
- **macOS**:下载 `NX2Apple-macOS-arm64.zip`,解压后右键 → 打开(首次)。0.4.9 起 App 内更新在 NX2Apple 名下正常工作(更早的版本请这次手动下载)。
-- **Windows**:本页不提供;Actions 产物里有 Qt 前端。
+- **Windows**:本页不提供,Actions 产物里有 Qt 前端。
## 致谢
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 69666591..35472c99 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -16,10 +16,10 @@ the camera, aiming and the weapon wheel all see the same input instead of one us
stick and the other an injected value.
Four details worth copying verbatim, because each is a bug that took them time:
-- **float exact equality** to recognise the frame it wrote, not an epsilon window;
+- **float exact equality** to recognise the frame it wrote, not an epsilon window,
- **thread-local** copies of the original value, because the camera and action threads both
- call the getter and would otherwise cross-pair;
-- normalisation by the frame's VFR ratio, and zero output when the drag stops;
+ call the getter and would otherwise cross-pair,
+- normalisation by the frame's VFR ratio, and zero output when the drag stops, and
- `touchpad_geometry.h`: one C header describing the whole virtual pad, used by both the UIKit
view and a **Mac mouse preview**, so the layout is tuned on a desk instead of on a phone.
@@ -30,7 +30,7 @@ the 3D view fills the screen.
| Piece | Effort | Note |
|---|---|---|
| `touchpad_geometry.h` + Mac `--touch-preview` | 3–5 days | Visible immediately, zero device time |
-| Relative look (`hle_look.c`) | 1–2 weeks | Needs tests; the four details above are the spec |
+| Relative look (`hle_look.c`) | 1–2 weeks | Needs tests, and the four details above are the spec |
| Native aspect (`hle_aspect.c`) | 3–5 days per game | Needs per-game projection offsets |
| BOTW touch HUD (`hle_botw_touchhud.c`) | 3–5 days | Per-game only |
@@ -72,7 +72,7 @@ The two ideas worth taking without the code:
~4 ms/frame). One data row, read once per second.
We already read one table from three places (`dm/games/settings.tsv` → `Launcher.swift` →
-`frontend-qt`); adding two columns keeps that structure.
+`frontend-qt`), and adding two columns keeps that structure.
Also from that fork: `nvn_ambient.h` (227 lines, present stage only) — ambient letterbox that
samples the frame's edges so a 16:9 game on a 4:3 iPad has a coloured surround instead of black.
@@ -87,8 +87,8 @@ Two forks solved it. **Copy the small one:**
| | zenvyzenshiro/NXNativeWindows | xbunax/nxnative |
|---|---|---|
| Size | ~24 files (`win/` shim) | full FastAPI WebUI (720 KB, 98 files) |
-| Approach | `xcrun.py` maps every `xcrun metal/metallib/clang`, `sips`, `plutil` to a Windows equivalent; `Launcher.m` replaces the SwiftUI launcher; `sdk/extract_xip.py` unpacks `iPhoneOS.sdk` | same idea plus its own staging/overlay/patch build system |
-| Verified on | Windows 11, LLVM 23.1.4, Metal Tools 6.2, iPhoneOS 27.1 — **Balatro built, sideloaded, ran on an A16 iPad** | Hades II IPA produced; not verified on a device |
+| Approach | `xcrun.py` maps every `xcrun metal/metallib/clang`, `sips`, `plutil` to a Windows equivalent, `Launcher.m` replaces the SwiftUI launcher, and `sdk/extract_xip.py` unpacks `iPhoneOS.sdk` | same idea plus its own staging/overlay/patch build system |
+| Verified on | Windows 11, LLVM 23.1.4, Metal Tools 6.2, iPhoneOS 27.1 — **Balatro built, sideloaded, ran on an A16 iPad** | Hades II IPA produced, not verified on a device |
| Fit for us | High — we already have two front ends | Low — it would be a third |
Toolchain (pinned in both forks): LLVM-MinGW `20261020`, iPhoneOS SDK from
@@ -123,8 +123,8 @@ What actually bounds a universal launcher is different:
| C. Shell app + per-game signed framework via `dlopen` | unbounded | large, unvalidated |
**A already delivers what external storage needs** (romfs from an external folder, per-game
-saves and logs) and enables the runtime-profile work that was already done. Do A first; B only
-if 4–8 games in one app is worth it; C needs a `dlopen` experiment before any commitment.
+saves and logs) and enables the runtime-profile work that was already done. Do A first, B only
+if 4–8 games in one app is worth it, and C needs a `dlopen` experiment before any commitment.
External storage on iOS: `UIDocumentPickerViewController` for the folder, persist a security-
scoped bookmark in UserDefaults, store the ROMFSARC index and shards there. `romfs_arc.c`
diff --git a/docs/WORK-IN-PROGRESS.md b/docs/WORK-IN-PROGRESS.md
index 5a11bdf8..7364c2c8 100644
--- a/docs/WORK-IN-PROGRESS.md
+++ b/docs/WORK-IN-PROGRESS.md
@@ -54,18 +54,18 @@ Ordered by value per week. See `docs/ROADMAP.md` for the reasoning.
| # | Item | Effort | Why not started |
|---|---|---|---|
-| C1 | **Relative touch look** (`hle_look.c` idea) | 1–2 wks | touch-the-wild's version depends on per-game observation hooks and float-exact provenance; author says unstable. Layer 1 (geometry) is already in |
-| C2 | **Native aspect ratio** (`hle_aspect.c` idea) | 3–5 d per game | Needs per-game projection offsets; layer 1 came first |
-| C3 | **Atmosphère cheats** | 0 if upstream merges PR #268 | Waiting on upstream; falls back to ~1 wk of our own if it stalls |
-| C4 | **Settings capability gating** (`requires` + `defaultAtFps` from AnySwitch) | 1–2 wks | Polish; needs `settings.tsv` schema change |
+| C1 | **Relative touch look** (`hle_look.c` idea) | 1–2 wks | touch-the-wild's version depends on per-game observation hooks and float-exact provenance, and the author says it is unstable. Layer 1 (geometry) is already in |
+| C2 | **Native aspect ratio** (`hle_aspect.c` idea) | 3–5 d per game | Needs per-game projection offsets, and layer 1 came first |
+| C3 | **Atmosphère cheats** | 0 if upstream merges PR #268 | Waiting on upstream, and falls back to ~1 wk of our own if it stalls |
+| C4 | **Settings capability gating** (`requires` + `defaultAtFps` from AnySwitch) | 1–2 wks | Polish, needs `settings.tsv` schema change |
| C5 | **Universal launcher architecture B** (4–8 games per IPA) | 3–4 wks | Blocked on: NRO-style module packing for non-NRO modules (`loader.c map_image`), and on deciding whether 4–8 games is worth it |
-| C6 | **Multiplayer (LAN / lan-play / wireless)** | 2–3 wks for one game | Protocol documented in `docs/MULTIPLAYER.md`; needs BSD socket layer + virtual network + per-game `ldn` mapping. Untested: iOS multicast entitlement on a sideloaded IPA |
-| C7 | **Launcher architecture C** (`dlopen` per-game framework) | large | Feasibility experiment **passed** on a device (iOS 27.0.1, sideloaded: `dlopen` of a nested framework + `dlsym` + call, docs/probe-dlopen.md); next is one real game as a framework in a shell app |
+| C6 | **Multiplayer (LAN / lan-play / wireless)** | 2–3 wks for one game | Protocol documented in `docs/MULTIPLAYER.md`, and needs BSD socket layer + virtual network + per-game `ldn` mapping. Untested: iOS multicast entitlement on a sideloaded IPA |
+| C7 | **Launcher architecture C** (`dlopen` per-game framework) | large | Feasibility experiment **passed** on a device (iOS 27.0.1, sideloaded, `dlopen` of a nested framework + `dlsym` + call, see docs/probe-dlopen.md). Next is one real game as a framework in a shell app |
| C8 | **Pikmin 4 / Yoshi / other fork profiles** | days each | Cherriable from forks once their PRs land upstream |
## D. Blocked on upstream
-- [ ] PR #268 Atmosphère cheats — watch for merge; our daily sync will bring it in.
+- [ ] PR #268 Atmosphère cheats — watch for merge, since our daily sync will bring it in.
- [ ] seedds/nxnative#205 (we filed): ARM64 branch range on a 185 MB text. Without it,
EA Sports FC 27 and similar large titles cannot be rewritten.
- [ ] Upstream PRs from forks worth cherry-picking: #218/#216 (Yoshi sparse textures, texraw),
@@ -75,14 +75,14 @@ Ordered by value per week. See `docs/ROADMAP.md` for the reasoning.
- [ ] The Qt front end has no reproducible "check for app updates" (the SwiftUI one has it).
- [ ] Qt front end: per-stage percentage display (currently an indeterminate bar for the
- running stage; the SwiftUI app shows real percentages from the script's own output).
+ running stage, while the SwiftUI app shows real percentages from the script's own output).
- [ ] `frontend-qt/README.md` says the Windows path is untested — update once section A passes.
-- [ ] The games table in both READMEs is hand-inserted; `refresh_badges()` already counts the
+- [ ] The games table in both READMEs is hand-inserted, and `refresh_badges()` already counts the
folders, so the table could be generated too.
-- [ ] `docs/ROADMAP.md` predates the BC/multiplayer findings; fold them in.
+- [ ] `docs/ROADMAP.md` predates the BC/multiplayer findings, so fold them in.
## How to use this file
-- Pick from A first if you are the one with the hardware; otherwise B.
+- Pick from A first if you are the one with the hardware, otherwise B.
- C is a menu, not a queue: each entry names its own blocker.
- Anything finished goes to the top table with its commit, so the list stays short.
diff --git a/docs/launcher-c-design.md b/docs/launcher-c-design.md
index 515d3eae..bc814c7d 100644
--- a/docs/launcher-c-design.md
+++ b/docs/launcher-c-design.md
@@ -4,12 +4,12 @@
`dm/host/hle_profile.{c,h}`(运行时 profile,已在 main,`3b36083`)。
目标(用户原话):**"打开启动器就像打开了一台 Switch"**——一个壳 App,里面看到多个已构建的游戏,
-点一个进入那个游戏。架构 A(进行中,WIP:41-47)交付按游戏隔离的数据布局;本文设计 C——壳 +
+点一个进入那个游戏。架构 A(进行中,WIP:41-47)交付按游戏隔离的数据布局。本文设计 C——壳 +
每游戏 framework——把"多个游戏装进一个 App"的**代码**维度做对。
本文回答六个问题:framework 边界、与架构 B 的真实差异(含 codesign 的诚实结论)、构建系统改造、
运行时选择器、风险清单、工作量分解。每个结论都给证据(文件与行号,或外部来源)。
-**一句话结论先放在这里:C 不能"不重签就加游戏"——iOS 只允许 dlopen 安装时已在签名 bundle 内的代码;
+**一句话结论先放在这里:C 不能"不重签就加游戏"——iOS 只允许 dlopen 安装时已在签名 bundle 内的代码,
C 的真实价值是"每个游戏一个独立 Mach-O(各自的 255 section 预算、增量链接、坏一个不坏全局)",
不是 unbounded。第 2 节有完整论证。**
@@ -27,7 +27,7 @@ C 的真实价值是"每个游戏一个独立 Mach-O(各自的 255 section 预
| `<game>` dylib:`__TEXT,__dm<mod>x0` / `__DM<mod>W,__img` / `__TEXT,__dm<mod>x1` 三段式聚合段 | `dm/ios/tools/gen_embed.py`(不改,同样的 embed.S 进一个 dylib target 而不是可执行文件) | 今天这些 section 在主可执行文件里(`loader.c:473-476`) |
| `__DATA,__dm_nro_tab` + 三个共享 NRO 段(有 NRO 的游戏,如任天堂明星大乱斗 98 个) | `gen_embed.py`(不改) | `loader.c:485-492` |
| `Info.plist`、`Resources/dm/`(`*.fixups.tsv`、`*.gates.tsv`、`nro.tsv`、shader 表) | `build_ipa.sh:75-81` 的复制清单原样搬进 framework | 今天在 App 的 `dm/` 资源目录(`project.yml` `Gen/dm` resources) |
-| `Resources/profile.tsv`(运行时 game profile,可选;优先用 Documents 里的) | `dm/games/game.py profile <id> <out>`(`game.py:192-232`) | 今天靠 DM_PROFILE 环境变量指向 |
+| `Resources/profile.tsv`(运行时 game profile,可选,优先用 Documents 里的) | `dm/games/game.py profile <id> <out>`(`game.py:192-232`) | 今天靠 DM_PROFILE 环境变量指向 |
framework 里**没有**宿主代码、没有 ObjC 类、没有入口函数——它对 dyld 是一个"加载后不被调用"的镜像,
唯一用途是让它的段被签名映射进进程,然后 `vm_remap` 到 guest 布局。romfs / msl / save / pso 一概不进
@@ -35,11 +35,11 @@ framework(数据不是代码,走 Documents,见 1.3)。
**方案 FH(备选):framework = 整个 dmhost + 该游戏的聚合段。** 入口
`int dmgame_main(int argc, char **argv, const char *profile_path)`(= 现在的 `dm_main`,`main.m:11` 用
-`-Dmain=dm_main` 编进宿主;framework 内同名导出),壳 dlopen 后 `dlsym(handle, "dmgame_main")` 调用。
+`-Dmain=dm_main` 编进宿主,framework 内同名导出),壳 dlopen 后 `dlsym(handle, "dmgame_main")` 调用。
仅当 FR 的探针(第 5 节 R1)失败时退到 FH。FH 的代价:宿主对象码每个游戏重复一份(dm/host 的
-.c/.m 源码合计约 11,265 行,头文件另计——重复是浪费但量级可接受);**更严重的是壳与 framework
+.c/.m 源码合计约 11,265 行,头文件另计——重复是浪费但量级可接受)。**更严重的是壳与 framework
各持一份 ObjC 类**(`front_ios.m` 的 App/SceneDelegate、Metal NVN 层的类),同名类跨镜像重复注册
-是 ObjC 运行时的已知雷区;除非"壳里不放宿主",但这又把窗口/Metal 生命周期切成两半。
+是 ObjC 运行时的已知雷区,除非"壳里不放宿主",但这又把窗口/Metal 生命周期切成两半。
### 1.2 入口符号设计(两种方案统一写法)
@@ -81,11 +81,11 @@ DM_PROF_* 环境变量",壳把 DM_PROFILE 设为
| 环境变量 | 现状(main.m 行号) | C 中的值 |
|---|---|---|
| `DM_ROMFS` | 87-90:`Documents/games/<DM_GAME_ID>/romfs` → `Documents/romfs` → `<App>/romfs` | `Documents/games/<选中 id>/romfs`,判定函数 `romfs_dir_ok`(19-28 行)原样复用 |
-| `DM_SAVE` / `DM_TEMP` | 95-104:`game_dir_for`(36-39 行)的 per-game 布局,`romfs` 落在游戏目录内才启用 | 同上;**按游戏隔离已经存在**,壳只换 id |
-| `DM_MSL_DIR` | 107-111:**已优先 per-game `<gdir>/msl`**,退到 bundle `<App>/msl` | 不改逻辑;shader 库放 `Documents/games/<id>/msl/`(数据,不进 framework,见 1.1) |
+| `DM_SAVE` / `DM_TEMP` | 95-104:`game_dir_for`(36-39 行)的 per-game 布局,`romfs` 落在游戏目录内才启用 | 同上,**按游戏隔离已经存在**,壳只换 id |
+| `DM_MSL_DIR` | 107-111:**已优先 per-game `<gdir>/msl`**,退到 bundle `<App>/msl` | 不改逻辑,shader 库放 `Documents/games/<id>/msl/`(数据,不进 framework,见 1.1) |
| `DM_PSO_BUNDLE` | 115-116:只查 bundle `<App>/pso` | 壳扩展为先查 `Documents/games/<id>/pso`(pso 离线管线档案是数据,BotW 一档约 650 MB/架构,`build_ipa.sh:82-86`) |
| `DM_NVN_SHMAP` | 105-106:bundle `<App>/dm/shader_map.tsv` | `<framework>/Resources/dm/shader_map.tsv` |
-| `DM_PROFILE` | hle_profile.c:213-214 读取;iOS 侧今天没人设它 | `Documents/games/<id>/profile.tsv` 优先,退 framework 资源 |
+| `DM_PROFILE` | hle_profile.c:213-214 读取,iOS 侧今天没人设它 | `Documents/games/<id>/profile.tsv` 优先,退 framework 资源 |
| `DM_LANG` / `DM_SHOW_FPS` | 84-86(Info.plist `DMLanguage`) | 壳 Info.plist 或 Documents/env.txt(69-80 行的 env 文件机制不动) |
| 其余 `DM_*` 调试开关 | `main.c:42-46 flags_init` | Documents/env.txt,不变 |
@@ -108,7 +108,7 @@ main.m:119 的 UIKit 并行加载)挪到"点选游戏之后、建窗口之前"
放 Data 容器不行。
2. **实测复现**(johnno1962/InjectionNext issue #81,2025-08 起):同 TeamIdentifier 签名、合法
load commands、甚至 get-task-allow + Developer Mode 的 dylib,只要在 bundle 外(Data 容器),
- `dlopen` 报 `code signature invalid (errno=1)`;拷进 bundle 后立即成功。结论:AMFI 拒绝的是
+ `dlopen` 报 `code signature invalid (errno=1)`,拷进 bundle 后立即成功。结论:AMFI 拒绝的是
**代码所在的路径**,不是签名的对错。该 issue 还确认 dylib **不能携带自己的 entitlements**。
3. **嵌入位置的官方要求**:TN2435(Embedding Frameworks In An App)与
developer.apple.com/documentation/bundleresources/placing-content-in-a-bundle——第三方 app 的动态
@@ -117,7 +117,7 @@ main.m:119 的 UIKit 并行加载)挪到"点选游戏之后、建窗口之前"
**反例为什么不算数**:LiveContainer(github.com/LiveContainer/LiveContainer)确实做到了"装一次壳、
之后随便加 app"。它的做法(读源码确认):guest 可执行文件放在数据容器里,靠
-`dlopen` 直接加载(`LCBootstrap.m:570-583`);能这样做的条件是
+`dlopen` 直接加载(`LCBootstrap.m:570-583`),能这样做的条件是
`"If JIT is enabled, bypass library validation so we can load arbitrary binaries"`(`LCBootstrap.m:367-371`)——
即持有 JIT/动态代码签名资格时,在**自己进程内** hook dyld:`mmap` 被换成"把文件读进匿名内存再
mprotect 成 exec"、`fcntl(F_ADDFILESIGS_RETURN)` 被改成谎报签名覆盖全文件
@@ -128,7 +128,7 @@ signed with the same certificate used by LiveContainer"*——没有 JIT 就退
guest"。我们的项目**不采用这条路**:JIT 资格(get-task-allow / 动态代码签名)在侧载调试场景技术上
拿得到(DolphiniOS 等靠 JIT-enabler 应用按会话附加),但那要求用户每次会话先跑一个 enabler、且整个
加载器建立在进程内 hook dyld 之上——LiveContainer 自己的代码就是"每次系统更新都可能断"的证词
-(README 注明 "(Below iOS 26)",即 iOS 26 起该路径有变;`LCBootstrap.m:577-583` 为 iOS 27 另加
+(README 注明 "(Below iOS 26)",即 iOS 26 起该路径有变,`LCBootstrap.m:577-583` 为 iOS 27 另加
`bypass_seg_count_check`)。我们只需要"映射已签名页",从来不需要"执行未签名代码",
loader.c:473-476 的 vm_remap 路线不依赖任何特殊资格。**所以 LiveContainer 证明的恰恰是规则的坚硬,
不是豁口:绕过它需要 JIT 资格 + dyld hook,二者我们都不具备也不想要。**
@@ -143,7 +143,7 @@ loader.c:473-476 的 vm_remap 路线不依赖任何特殊资格。**所以 LiveC
因此 ROADMAP 第 123 行的 **"C: unbounded" 是错的,本文推翻它**。正确表述:
- **代码维度**:games per IPA 仍由体积上界(第 5 节 R3 的同一套算术:每游戏 modules 约 104 MB,
- ROADMAP:116;系统对超大包拒绝安装,`build_ipa.sh:170-172` 记录了 PackageExtractionFailed),
+ ROADMAP:116,系统对超大包拒绝安装,`build_ipa.sh:170-172` 记录了 PackageExtractionFailed),
ROADMAP:117 "4–8 games" 的估计对 B 和 C 同样成立。
- **数据维度**:romfs / msl / save / pso / profile.tsv 全是数据,放 `Documents/games/<id>/`,
用户手动放文件即可、永不触发重签——这一维才是 unbounded,而且**架构 A 已经拿到了它**
@@ -156,14 +156,14 @@ loader.c:473-476 的 vm_remap 路线不依赖任何特殊资格。**所以 LiveC
B(4–8 游戏聚合进一个二进制,WIP C5 估 3–4 周):所有游戏的模块 section 挤进同一个 Mach-O,
共享 255 section 预算与命名空间。ROADMAP:112-115 记录了实测事故:*两个游戏同名模块静默合并进同一
-section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3 共享段 + (game, module) 键表"是修补,
+section,无任何报错(第二个游戏的代码消失了)*,NRO 式"3 共享段 + (game, module) 键表"是修补,
验证到 2 游戏 × 2 模块。C 把每个游戏放进自己的 Mach-O:
| 维度 | B(聚合二进制) | C(壳 + 每 game framework) |
|---|---|---|
-| section 预算 | 全体游戏共享 255(`loader.c:485`:"a Mach-O file has at most 255 sections";SSBU 98 NRO ×3 段 = 294 已单游戏爆表) | **每 framework 各自 255**;同名 section 物理上不可能跨游戏合并——B 的静默合并 bug 在 C 里结构性不存在 |
-| 增量构建 | 加/换一个游戏 → 整个巨型可执行重链接 | 只有该游戏的 dylib 重链接;壳二进制不变;`pack_ipa.py` 按文件指纹复用旧 IPA 条目(pack_ipa.py:12-15),换一个游戏的重打包接近增量 |
-| 故障半径 | 任一游戏的段/链接问题让整个 IPA 构建失败 | 坏的 framework 让 `dlopen` 返回 NULL(壳弹一条错误继续);其余游戏不受影响 |
+| section 预算 | 全体游戏共享 255(`loader.c:485`:"a Mach-O file has at most 255 sections",SSBU 98 NRO ×3 段 = 294 已单游戏爆表) | **每 framework 各自 255**,同名 section 物理上不可能跨游戏合并——B 的静默合并 bug 在 C 里结构性不存在 |
+| 增量构建 | 加/换一个游戏 → 整个巨型可执行重链接 | 只有该游戏的 dylib 重链接,壳二进制不变,`pack_ipa.py` 按文件指纹复用旧 IPA 条目(pack_ipa.py:12-15),换一个游戏的重打包接近增量 |
+| 故障半径 | 任一游戏的段/链接问题让整个 IPA 构建失败 | 坏的 framework 让 `dlopen` 返回 NULL(壳弹一条错误继续),其余游戏不受影响 |
| 宿主份数 | 1 | 1(FR 方案) |
| 每游戏元数据 | 聚合表 | framework 自带(Resources + 段),分发单个游戏 = 拷一个目录 |
| 按需组合 | 每次都要全量决定装哪几个游戏 | 聚合脚本按用户拥有的 NSP 挑 framework 组装 IPA(仍是装时定死) |
@@ -190,8 +190,8 @@ section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3
### 3.2 `--framework` 模式(build_ipa.sh / build_ipa_from_nsp.py)
- 工程模板加一个 `framework` target(xcodegen `type: framework`,platform iOS),sources 只含
- `Gen/embed.S` + 一个 3 行的占位 `.m`(给镜像一个符号,供 `dladdr` 取 `dli_fbase`)+ `Info.plist`;
- `Gen/dm` 表格进 `Resources`。`gen_build.py` 不动(宿主源码归壳的 target);`gen_embed.py` 不动。
+ `Gen/embed.S` + 一个 3 行的占位 `.m`(给镜像一个符号,供 `dladdr` 取 `dli_fbase`)+ `Info.plist`。
+ `Gen/dm` 表格进 `Resources`。`gen_build.py` 不动(宿主源码归壳的 target),`gen_embed.py` 不动。
- 链接 flags:沿用 embed 的 `-Wl,-segprot,__DM<mod>W,rw,rw`(gen_embed.py 末尾输出),dylib 同样接受。
- 产物:`<game>.framework/`(dylib + Info.plist + Resources/{dm 表格, profile.tsv, launcher.json, icon}),
外加一个 `game.manifest.json`(title id、名称、版本、modules 列表、chain 版本 `b-$V`、romfs marker——
@@ -201,7 +201,7 @@ section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3
同类检查(stage_resources.sh:21-28)。
- 签名:`codesign --force --sign -` 占位 ad-hoc 签 framework(与 build_ipa.sh:158 现在签 App 的理由
相同:侧载器要从占位签名里读 entitlements 并全部重签)。**framework 不带 entitlements 文件**
- (dylib 无法持有 entitlements,见 2.1 证据 2;内存权限等 entitlement 全在壳上,build_ipa.sh:119-124)。
+ (dylib 无法持有 entitlements,见 2.1 证据 2,内存权限等 entitlement 全在壳上,build_ipa.sh:119-124)。
### 3.3 壳 App 与聚合 IPA
@@ -212,9 +212,9 @@ section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3
`Payload/Shell.app/Frameworks/<game>.framework`,壳资源映射照旧,调 `pack_ipa.py` 产出一份 IPA
(`--skip $P/_CodeSignature` 的既有跳过逻辑沿用,build_ipa.sh:188)。
- **签名顺序**(对照 pack_app.py:100-106 的"先内后外"):
- 1. 每个 framework 内 dylib;
- 2. 每个 framework bundle(封存其 Resources 与 Info.plist);
- 3. 壳可执行文件(带 entitlements,ad-hoc 占位);
+ 1. 每个 framework 内 dylib,
+ 2. 每个 framework bundle(封存其 Resources 与 Info.plist),
+ 3. 壳可执行文件(带 entitlements,ad-hoc 占位),
4. 壳 bundle(封存 Frameworks/ 下全部嵌套代码)。
壳 bundle 的签名会把所有 framework 的 CD hash 写进 CodeResources——这正是"加游戏必须重签"的
机械原因(2.2)。侧载器(SideStore/AltStore)安装时对每个嵌套二进制重签并重建外层封存:
@@ -230,24 +230,24 @@ section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3
- **游戏列表** = 扫描两个来源后按 title id 连接:
1. **代码**:`Bundle.main/Frameworks/*.framework`,读每个 framework `Resources/game.manifest.json`
- (构建时生成,第 3.2 节);运行期用 `getsectiondata`/段存在性做交叉校验(防 manifest 与段不一致)。
+ (构建时生成,第 3.2 节),运行期用 `getsectiondata`/段存在性做交叉校验(防 manifest 与段不一致)。
不建议扫 `romfs.idx` 当列表依据——romfs 是用户可移动的数据(外置盘是计划能力:romfs_arc.c 按分片
pread,天然支持外部路径,但今天 `main.m romfs_locate` 只查 per-game/Documents/bundle 三处,
文件夹选择器是待办,ROADMAP:129-132),代码在不在 bundle 里才是"装没装"。
2. **数据**:`Documents/games/*/`,"这个目录是不是一个游戏的文件"的判定已经存在:
`main.m:19-28 romfs_dir_ok`(有 `romfs.idx` 或 profile 的 `romfs_marker` 路径即算)。
- - 列表状态:代码+数据 = 可玩;只有代码 = 提示"把 romfs 放进 Files";只有数据 = 灰显"IPA 里没有这个游戏
+ - 列表状态:代码+数据 = 可玩,只有代码 = 提示"把 romfs 放进 Files",只有数据 = 灰显"IPA 里没有这个游戏
的 framework(需要重签安装)"——这条提示就是 2.2 结论的用户可见面。
- **存档隔离**:已经有了。`Documents/games/<id>/{save,temp}`,`main.m:95-104`:
romfs 落在游戏目录内才用 per-game save(`per_game = [romfs hasPrefix:gdir]`,98 行),
壳不改这个规则,只把选中的 id 传给 `game_dir_for`(36-39 行)。WIP:41-44 与 ROADMAP:125 的
"A 已交付 per-game 布局" 即此。
- **profile 与设置**:`DM_PROFILE` 指向 `Documents/games/<id>/profile.tsv`(用户可改,不重签),
- 无则退 framework 资源;`DM_PROF_*` 与 `DM_FPS_TARGET` 等开关的优先级链不变
+ 无则退 framework 资源,`DM_PROF_*` 与 `DM_FPS_TARGET` 等开关的优先级链不变
(hle_profile.h:3-5、hle_profile.c:211-219)。设置 UI 用壳自己的 launcher.json(每 framework 自带一份,
`build_ipa.sh:96-97` 的 settings.py 产物搬进 Resources)。
- **切换游戏**:一次进程只跑一个游戏(理由见 R4)。游戏退出回壳 = 若宿主能干净收尾
- (hle_lifecycle 的 SIGTERM 路径)就回 shell 场景重建选择器;收不干净就 `exit(0)` 由用户再点图标
+ (hle_lifecycle 的 SIGTERM 路径)就回 shell 场景重建选择器,收不干净就 `exit(0)` 由用户再点图标
(与 Switch 回 home 的手感一致)。两种都先写进壳,探针阶段一并验证。
---
@@ -256,20 +256,20 @@ section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3
- **R1 `dlopen`/`vm_remap` 在 dylib 上是否成立——C 的存在性风险,探针先行。**
规则层面 2.1 已定(bundle 内可 dlopen),但我们的用法有两个未验证细节:dyld 是否接受带多个
- `__DM*W` rw,rw 自定义段 + 上百 section 的 dylib;`vm_remap` copy=FALSE 把 **dylib**(而非主可执行文件)
+ `__DM*W` rw,rw 自定义段 + 上百 section 的 dylib,`vm_remap` copy=FALSE 把 **dylib**(而非主可执行文件)
的已签名 __TEXT 页重映射到匿名地址再执行是否被 AMFI 放行。现行机制对"主可执行文件自己的段"成立
(loader.c:473-476,注释并援引 libffi trampoline table 先例),dylib 与它在内核路径上是同一类
(同进程内已映射的签名页),但**没有实验前不下结论**。探针必须先跑。
说明:任务输入里提到 `dm/ios/probe/` 正在另一分支验证——**本工作树核对过 launcher-b、pr17、pr18、
mg-profile-runtime 四个分支,`dm/ios/probe/` 尚不存在**(只有 `dm/gfx/metal/probe/` 与 `dm/host/probe.c`),
全仓库也没有任何 dlopen 引用。本文第 6 节把它列为第一步交付物,实验清单:
- P1 设备上 dlopen 一个 100 MB 级自定义段 dylib;P2 对其 __TEXT 段 vm_remap copy=FALSE + 执行 +
- 与现行 executable 路径逐字节对比;P3 `getsectiondata(dylib_mh, ...)`;P4 dlopen 失败的错误面
- (能否继续跑);P5 iOS 26 实机 + 侧载签名链(SideStore)各跑一遍。
-- **R2 255 section 限制**:C 的每 framework 独立预算消掉 B 的跨游戏合并事故(2.3);单游戏内
- NRO 过多仍沿用共享段方案(`gen_embed.py` 注释:最多 255 sections、SSBU 98 NRO×3 段必须打包;
+ P1 设备上 dlopen 一个 100 MB 级自定义段 dylib,P2 对其 __TEXT 段 vm_remap copy=FALSE + 执行 +
+ 与现行 executable 路径逐字节对比,P3 `getsectiondata(dylib_mh, ...)`,P4 dlopen 失败的错误面
+ (能否继续跑),P5 iOS 26 实机 + 侧载签名链(SideStore)各跑一遍。
+- **R2 255 section 限制**:C 的每 framework 独立预算消掉 B 的跨游戏合并事故(2.3)。单游戏内
+ NRO 过多仍沿用共享段方案(`gen_embed.py` 注释:最多 255 sections、SSBU 98 NRO×3 段必须打包,
`loader.c:485-492`)。残余风险:壳自身 + framework 数量不影响各镜像预算(预算是 per-Mach-O 的)。
-- **R3 体积**:每游戏 framework ≈ modules(约 104 MB 原始,ROADMAP:116)+ 表格;IPA 总体积 = 壳
+- **R3 体积**:每游戏 framework ≈ modules(约 104 MB 原始,ROADMAP:116)+ 表格,IPA 总体积 = 壳
(~11 K 行宿主 + SwiftUI,数 MB 级)+ N × framework。压缩后估每游戏几十 MB(deflate 对 NSO 镜像
的实际收益待测,无历史数据,标待验证)。shader 库(BotW 阴影库 344 MB,ROADMAP:116)、pso 档案
(~650 MB/架构,build_ipa.sh:86)全部走 `Documents/games/<id>/`,不占 IPA。系统对过大的包拒绝安装
@@ -279,33 +279,33 @@ section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3
(hle_profile.h:22-23 的 mem_reserve/alias/stack/pool 等),不同游戏不需要不同签名资格。
**同一时刻只加载一个 framework**:规避跨镜像 ObjC 类重复与 C 符号串扰,也把"多游戏同时运行"明确
划出范围(那是 LiveContainer 的多容器问题,不追)。内存上多装几个游戏不吃亏:未 dlopen 的
- framework 不映射任何页;dlopen 后的代码页经 vm_remap copy=FALSE 与原映射共享物理页
- (loader.c:475 "sharing the same signed pages"),不因加载翻倍;切游戏先终止当前进程(第 4 节),
+ framework 不映射任何页,dlopen 后的代码页经 vm_remap copy=FALSE 与原映射共享物理页
+ (loader.c:475 "sharing the same signed pages"),不因加载翻倍,切游戏先终止当前进程(第 4 节),
不存在两份 guest 内存布局并存。
- **R5 dyld 行为随 iOS 版本漂移**:LiveContainer 在 iOS 26 有豁免分支、iOS 27 加段数补丁(其源码
- 2.1 节引用处);我们目标就是 iOS 26+(project.yml `deploymentTarget: iOS 26.0`)。探针必须在
+ 2.1 节引用处),我们目标就是 iOS 26+(project.yml `deploymentTarget: iOS 26.0`)。探针必须在
实际目标 OS 上做,并把这个探针纳入每次大版本升级的回归清单。
-- **R6 打包与增量**:`pack_ipa.py` 复用按指纹(pack_ipa.py:12-15、193-195);framework 拆映射后
+- **R6 打包与增量**:`pack_ipa.py` 复用按指纹(pack_ipa.py:12-15、193-195),framework 拆映射后
增量成立,但 ad-hoc 重签会改变 dylib 字节 → 每次聚合后所有 framework 的指纹都会变(签名写入
Mach-O)。缓解:聚合脚本对"构建产物 → 占位签名 → 打包"全程用固定副本,只有真正重建的 framework
- 走签名;重签发生在设备侧(侧载器),不影响构建机增量。此项需要在 W4 实测确认。
+ 走签名,重签发生在设备侧(侧载器),不影响构建机增量。此项需要在 W4 实测确认。
---
-## 6. 工作量分解(按周;◇ = 依赖探针结果,∥ = 可并行)
+## 6. 工作量分解(按周,◇ = 依赖探针结果,∥ = 可并行)
| 周 | 内容 | 依赖 |
|---|---|---|
-| W1 | `dm/ios/probe/`:P1–P5 实验(新目录;本工作树四分支均无现成探针)| 无。3–5 天 |
-| W1 ∥ | `--framework` 构建模式(build_ipa.sh 分支、xcodegen framework target、manifest 生成);Mac 上可先用普通 dylib 验证段布局与单测 | 不依赖探针(纯构建侧) |
+| W1 | `dm/ios/probe/`:P1–P5 实验(新目录,本工作树四分支均无现成探针)| 无。3–5 天 |
+| W1 ∥ | `--framework` 构建模式(build_ipa.sh 分支、xcodegen framework target、manifest 生成),Mac 上可先用普通 dylib 验证段布局与单测 | 不依赖探针(纯构建侧) |
| W1 ∥ | `loader.c` IMAGE_MH 参数化 + 宿主单测(Mac 可跑:map_image 的非 NRO 路径换成"给定 mach header")| 不依赖探针 |
-| W2 ◇ | 壳 App:选择器 UI(扫描 Frameworks + Documents/games)、env 装配(第 1.3 节表)、dlopen→dm_main 接线;探针若失败则切 FR→FH(第 1.1 节)或终止 C | W1 探针 P1–P3 |
-| W3 | `pack_launcher_ipa.py` 聚合 + 签名顺序 + `test_pack_ipa.py` 扩展;双游戏 IPA 在模拟器/设备装机链验证 | W2 |
+| W2 ◇ | 壳 App:选择器 UI(扫描 Frameworks + Documents/games)、env 装配(第 1.3 节表)、dlopen→dm_main 接线,探针若失败则切 FR→FH(第 1.1 节)或终止 C | W1 探针 P1–P3 |
+| W3 | `pack_launcher_ipa.py` 聚合 + 签名顺序 + `test_pack_ipa.py` 扩展,双游戏 IPA 在模拟器/设备装机链验证 | W2 |
| W4 ◇ | 实机端到端:两个真实游戏(探针用的 NSP 复用)、切游戏、存档隔离、坏 framework 容错、R6 增量实测、文档收尾 | W3 + 用户的 NSP |
| 缓冲 | R5 的 iOS 26.1/27 差异回归、FH 备选路径(若 P2 失败,+1 周实现 FH 的 dmgame_main 与壳移交)| — |
总计:**约 4 周到"双游戏可玩",探针失败再 +1 周(FH)或止损回 B**。与 B 的 3–4 周相比没有省,
-买到的是 2.3 表里的结构性收益;决定点仍建议放在 W1 探针之后。
+买到的是 2.3 表里的结构性收益,决定点仍建议放在 W1 探针之后。
---
@@ -317,23 +317,23 @@ section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3
- `dm/ios/tools/gen_embed.py:1-13`(三段式段、ITMS-90999 单可执行段、NRO 共享段 + 表)
- `dm/host/main.c:42-46,87-97,115-124`(DM_* 开关、模块清单来源、preload 约定)
- `dm/ios/Sources/main.m:19-28,36-39,41-52,69-80,87-116`(per-game 布局、romfs 判定、env 装配全表)
-- `dm/host/hle_profile.{h:1-6, c:211-219}`(运行时 profile 加载顺序);`dm/games/game.py:192-232`(profile TSV 生成)
+- `dm/host/hle_profile.{h:1-6, c:211-219}`(运行时 profile 加载顺序),`dm/games/game.py:192-232`(profile TSV 生成)
- `dm/ios/tools/build_ipa.sh:53,70-76,96-97,100-101,117-124,138-161,166-188`(chain 版本、Gen 生成、
entitlements、不签名构建、占位签名、pack 映射)
-- `dm/ios/tools/pack_ipa.py:12-15,193-195`(指纹复用);`dm/ios/tools/stage_resources.sh:21-28`(chain 校验先例)
+- `dm/ios/tools/pack_ipa.py:12-15,193-195`(指纹复用),`dm/ios/tools/stage_resources.sh:21-28`(chain 校验先例)
- `dm/ios/project.yml`(iOS 26.0 target、Gen/dm resources、`-Dmain=dm_main`)
- `dm/mac/pack_app.py:100-106`(先内后外签名先例)
- `dm/host/dm.h:11`(MAX_MOD 128:profile 模块 + NRO 上限)
-- `docs/ROADMAP.md:109-127`(调查结论、255 合并事故、104 MB/游戏、A/B/C 表);`docs/WORK-IN-PROGRESS.md:41-47,61,63`(A 现状、C5/C7)
+- `docs/ROADMAP.md:109-127`(调查结论、255 合并事故、104 MB/游戏、A/B/C 表),`docs/WORK-IN-PROGRESS.md:41-47,61,63`(A 现状、C5/C7)
仓库外:
- Apple DTS(Quinn "The Eskimo!"),dlopen 规则:developer.apple.com/forums/thread/773210
- InjectionNext 实测(bundle 外同 TeamID dylib 被拒、dylib 无 entitlements):github.com/johnno1962/InjectionNext/issues/81
-- TN2435 嵌入 framework:developer.apple.com/library/archive/technotes/tn2435/_index.html;
+- TN2435 嵌入 framework:developer.apple.com/library/archive/technotes/tn2435/_index.html,
Placing content in a bundle:developer.apple.com/documentation/bundleresources/placing-content-in-a-bundle
- LiveContainer(JIT 条件下的 dyld 验证绕过、无 JIT 则重签 guest、iOS 26/27 适配):
- github.com/LiveContainer/LiveContainer(README;`LiveContainer/LCBootstrap.m`、`LiveContainer/dyld_bypass_validation.m`)
-- SideStore FAQ(重装同 bundle id 数据保留、重签模型):docs.sidestore.io/docs/faq;
+ github.com/LiveContainer/LiveContainer(README,`LiveContainer/LCBootstrap.m`、`LiveContainer/dyld_bypass_validation.m`)
+- SideStore FAQ(重装同 bundle id 数据保留、重签模型):docs.sidestore.io/docs/faq,
免费 Apple ID 3 app / 10 App ID 限制:faq.altstore.io(这也是"所有游戏进一个壳"的动机之一)
-> **Update (merged):** the dlopen probe now exists — `dm/ios/probe/` with `build_probe.sh`, committed alongside this document, and `probe-out/DmProbe.ipa` is built. W1 step 1 is done; what remains is running it on an iOS 26 device and reading `Documents/probe-log.txt`.
+> **Update (merged):** the dlopen probe now exists — `dm/ios/probe/` with `build_probe.sh`, committed alongside this document, and `probe-out/DmProbe.ipa` is built. W1 step 1 is done. What remains is running it on an iOS 26 device and reading `Documents/probe-log.txt`.
diff --git a/docs/launcher-c-plan.md b/docs/launcher-c-plan.md
index 9dc0ad3a..ab13b78d 100644
--- a/docs/launcher-c-plan.md
+++ b/docs/launcher-c-plan.md
@@ -3,7 +3,7 @@
Status: **the dlopen gate is open** (device run on iOS 27.0.1, [probe-dlopen.md](probe-dlopen.md)),
design in [launcher-c-design.md](launcher-c-design.md). This plan turns the design into
milestones with a testable artifact each. The probe proved a one-function framework loads and
-runs; **the real payload is still unproven** (a framework with the game's ~100 MB of `__DM*W`
+runs, but **the real payload is still unproven** (a framework with the game's ~100 MB of `__DM*W`
sections / up to 255 sections, `vm_remap` of its signed `__TEXT` with copy=FALSE,
`getsectiondata` on a dylib header). M1 exists to prove exactly that.
@@ -19,20 +19,20 @@ sections / up to 255 sections, `vm_remap` of its signed `__TEXT` with copy=FALSE
## M1 — the first testable artifact
-Keep "one game, one IPA"; move the game's modules out of the main executable into
+Keep "one game, one IPA" and move the game's modules out of the main executable into
`DmIOS.app/Frameworks/DmGame.framework`, `dlopen` it at launch, take its mach header via
`dlsym` + `dladdr`, and read its sections.
**New files**
- `dm/ios/project-framework.yml`: same app target as `project.yml` but without `Gen/embed.S`, with
- a `DmGame` framework target (`Gen/embed.S` + a marker `.m`; resources `Gen/framework/dm`,
+ a `DmGame` framework target (`Gen/embed.S` + a marker `.m`, with resources `Gen/framework/dm`,
`profile.tsv`, `game.manifest.json`), `embed: true`, `link: false`, app RPATH
`@executable_path/Frameworks`.
- `dm/ios/framework/DmGameMarker.m`: `dmgame_image_marker` — only for `dlsym`/`dladdr`.
- `dm/host/loader_image.h`: `void dm_set_game_image_header(const void *mh);`
- `dm/ios/Sources/FrameworkBootstrap.m/.h`: `dlopen` → `dlsym(marker)` → `dladdr` →
- `dm_set_game_image_header(info.dli_fbase)`; logs `[RED]` on failure.
+ `dm_set_game_image_header(info.dli_fbase)`, and it logs `[RED]` on failure.
- `dm/ios/tools/gen_manifest.py`: builds `game.manifest.json` (schema below).
- `dm/ios/tests/test_framework_build.py`, `test_framework_link.py`.
@@ -43,69 +43,69 @@ Keep "one game, one IPA"; move the game's modules out of the main executable int
`map_image()` (:536) use it. **Do not** touch `force_init()` (:154) — `__DATA,swforce` is the
host's own table.
- `dm/ios/Sources/main.m`: under `DM_FRAMEWORK_BUILD`, set `DM_PROFILE` to the framework's
- `profile.tsv` **before** the first `dm_profile()` call; call `dm_open_game_framework()` before
- `dm_host_preload_start()` (:237); `argv[1]` and `DM_NVN_SHMAP` point at `<framework>/dm`.
-- `dm/ios/tools/build_ipa.sh`: `FRAMEWORK=${DM_FRAMEWORK:-0}`; framework mode generates
+ `profile.tsv` **before** the first `dm_profile()` call, call `dm_open_game_framework()` before
+ `dm_host_preload_start()` (:237), and point `argv[1]` and `DM_NVN_SHMAP` at `<framework>/dm`.
+- `dm/ios/tools/build_ipa.sh`: `FRAMEWORK=${DM_FRAMEWORK:-0}`. Framework mode generates
`Gen/framework/{dm,profile.tsv,game.manifest.json,Info.plist}`, `xcodegen --spec
project-framework.yml` (:134), signs the framework first and the app executable second
(:164–174).
- `scripts/build_ipa_from_nsp.py` (~:2075): `--framework` → `DM_FRAMEWORK=1` in `ipa_env`.
- `dm/ios/tools/compile_check.py`: a second pass with `DM_FRAMEWORK_BUILD=1`.
- `dm/ios/tests/test_ipa_unsigned.py`, `test_xcode_workflow.py`: framework packaging/signing
- assertions; `--prepare-xcode` uses `project-framework.yml`.
+ assertions, and `--prepare-xcode` uses `project-framework.yml`.
**Done when**
-- Off-device: `compile_check.py` passes both ways; `test_framework_link.py` builds a synthetic
+- Off-device: `compile_check.py` passes both ways, `test_framework_link.py` builds a synthetic
framework with `xcodebuild -target DmGame CODE_SIGNING_ALLOWED=NO` and `otool -l` shows
- `__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, `__DATA,__dm_nro_tab`;
- `test_framework_build.py` packs/signs a stand-in (framework has no entitlements); the default
+ `__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, `__DATA,__dm_nro_tab`,
+ `test_framework_build.py` packs/signs a stand-in (framework has no entitlements), and the default
path (no `DM_FRAMEWORK`) is unchanged and the IPA has no `Frameworks/`.
-- On device: sideload the `DM_FRAMEWORK=1` IPA; the log shows the framework path, handle, image
- base and each module's base/size; `DM_LOADHASH=1` per-module sha256 lines match the default
- build exactly (proof the framework path loads byte-identical code); a second run with an NRO
- game (SSBU) shows `__DATA,__dm_nro_tab` and `nro.tsv` working; iOS 26 and 27 if available.
+- On device: sideload the `DM_FRAMEWORK=1` IPA. The log shows the framework path, handle, image
+ base and each module's base/size, `DM_LOADHASH=1` per-module sha256 lines match the default
+ build exactly (proof the framework path loads byte-identical code), a second run with an NRO
+ game (SSBU) shows `__DATA,__dm_nro_tab` and `nro.tsv` working, and iOS 26 and 27 pass if available.
## M2 — shell + one framework
-`DmShell.app` lists one game; Play sets the environment, `dlopen`s the framework, calls
+`DmShell.app` lists one game. Play sets the environment, `dlopen`s the framework, calls
`dm_set_game_image_header` + `dm_host_preload_start`, then shows the existing game view.
- New: `dm/ios/project-shell.yml`, `dm/ios/Shell/{ShellMain.m,ShellView.swift,GameManifest.swift,
GameLibrary.swift,GameData.m,GameLauncher.m,BootState.m}`, `dm/ios/tools/build_shell.sh`,
`dm/ios/tests/{test_shell_library.py,test_framework_bootstrap.py}`.
- Changed: `main.m`'s `game_dir_for`/`romfs_dir_ok`/`romfs_locate`/`set_data_env` move to
- `GameData.m` (explicit title id/marker, no `dm_profile()`); `g_boot_ok` moves to `BootState`;
- `front_ios.m` presents the shell root only after preload; `Launcher.swift` reads
- `DM_LAUNCHER_JSON` (bundle fallback); `LauncherSettings.swift` gains a per-game key/suite.
+ `GameData.m` (explicit title id/marker, no `dm_profile()`), `g_boot_ok` moves to `BootState`,
+ `front_ios.m` presents the shell root only after preload, `Launcher.swift` reads
+ `DM_LAUNCHER_JSON` (bundle fallback), and `LauncherSettings.swift` gains a per-game key/suite.
- `dm/host/main.c:95` falls back to the compiled `DM_GAME_MODULES`: the shell passes the manifest
modules in argv explicitly (no code change), or the fallback changes to
`dm_profile()->modules` — pick one in M2 and keep the default path identical.
-- Done when: `xcodebuild -scheme DmShell` builds; `test_shell_library.py` covers the three states
- (playable / needsData / needsFramework / broken); device: shell + 1 framework lists and plays,
+- Done when: `xcodebuild -scheme DmShell` builds, `test_shell_library.py` covers the three states
+ (playable / needsData / needsFramework / broken), and on a device the shell + 1 framework lists and plays and the
log shows per-game `DM_PROFILE`/`DM_ROMFS`/`DM_SAVE`.
## M3 — N games in one IPA
- New: `dm/ios/tools/pack_launcher_ipa.py` (reads each manifest, validates chain vs
- `dm/gfx/nvn/dmsh_chain.h`, unique title ids, `CFBundleExecutable` vs manifest; signs in order:
- framework → shell executable (entitlements) → shell bundle; calls `pack_ipa.py`),
+ `dm/gfx/nvn/dmsh_chain.h`, unique title ids, `CFBundleExecutable` vs manifest, signs in order:
+ framework → shell executable (entitlements) → shell bundle, and calls `pack_ipa.py`),
`tests/test_pack_launcher_ipa.py`, optional `framework_cache.py`.
-- Changed: `build_ipa.sh` gains `DM_FRAMEWORK_ONLY=1` (framework + manifest, no app, no pack);
- `build_ipa_from_nsp.py` gains `--framework-only`; `GameLibrary.swift` scans
+- Changed: `build_ipa.sh` gains `DM_FRAMEWORK_ONLY=1` (framework + manifest, no app, no pack),
+ `build_ipa_from_nsp.py` gains `--framework-only`, and `GameLibrary.swift` scans
`Frameworks/*.framework/game.manifest.json` + `Documents/games/*/`.
-- Done when: two synthetic frameworks pack, chain mismatch and duplicate title ids are rejected;
- device: one IPA, two games, both play; a broken framework only breaks its own row.
+- Done when: two synthetic frameworks pack, chain mismatch and duplicate title ids are rejected,
+ and on a device one IPA holds two games that both play and a broken framework only breaks its own row.
## M4 — per-game data, settings, external drive, DLC
-- `GameDataPicker.swift`, `test_shell_data.py`; `DataBookmark` keys become
- `pickedDataBookmark.<titleID>` with migration; `GameData.m` resolves like `main.m:69–117` with
- explicit title id/marker; `GameLauncher.m` sets `DM_AOC_DIR`, `DM_MSL_DIR`, `DM_PSO_BUNDLE`
- per game first, then app-wide; `LauncherSettings` per game; `GameLibrary` never treats
+- `GameDataPicker.swift`, `test_shell_data.py`. `DataBookmark` keys become
+ `pickedDataBookmark.<titleID>` with migration, `GameData.m` resolves like `main.m:69–117` with
+ explicit title id/marker, `GameLauncher.m` sets `DM_AOC_DIR`, `DM_MSL_DIR`, `DM_PSO_BUNDLE`
+ per game first and then app-wide, `LauncherSettings` is per game, and `GameLibrary` never treats
`romfs.idx` as "code installed" (design §233–240).
- Done when: two titles' `Documents/games/<id>/{romfs.img,romfs,save,temp,msl,pso,aoc}` are
- isolated; stale bookmark falls back; identity mismatch falls back; DLC `aoc/<index>.img`
+ isolated, a stale bookmark falls back, an identity mismatch falls back, and DLC `aoc/<index>.img`
mounts (`hle_fs.c:516-518`).
## Manifest (`game.manifest.json`, in the framework root)
@@ -114,15 +114,15 @@ Required keys: `schema` (1), `title_id` (16 hex), `name`, `display_version`, `pa
`modules` (≥1), `nro_count`, `chain` (`b-<hex>`), `loader` (`FR`|`FH`), `framework`
(`<name>.framework`), `framework_executable`, `image_marker` (`dmgame_image_marker`), `profile`
(`profile.tsv`), `shader_map` (`dm/shader_map.tsv`), `launcher` (`dm/launcher.json`),
-`romfs_marker`, `romfs_identity` (`DMROMFSID1 …`), `min_os`; optional `icon`, `built_by`,
+`romfs_marker`, `romfs_identity` (`DMROMFSID1 …`), `min_os`. Optional keys are `icon`, `built_by`,
`built_at`, `bytes`. Validation: schema, `CFBundleExecutable`, framework name, chain equal to the
-shell's `DMSH_CHAIN`, unique title ids; at launch cross-check sections per module
+shell's `DMSH_CHAIN`, unique title ids, and at launch the loader cross-checks sections per module
(`__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, and `__DATA,__dm_nro_tab` when
`nro_count > 0`) — a mismatch marks the game `broken` without affecting others.
-Discovery: frameworks from `Bundle.main.privateFrameworksURL/*.framework`; data from
+Discovery: frameworks come from `Bundle.main.privateFrameworksURL/*.framework` and data from
`Documents/games/<title_id>/` (`romfs.img` complete, or `romfs/romfs.idx`, or
-`romfs/<manifest.romfs_marker>`); per-title bookmark for external drives; merge into
+`romfs/<manifest.romfs_marker>`), with a per-title bookmark for external drives, and the results merge into
playable / needsData / needsFramework / broken.
## Environment at game start
@@ -150,49 +150,49 @@ Order: set `DM_PROFILE` → resolve data (explicit title id) → set the rest
1. Build each `<Game>.framework` unsigned.
2. Sign the framework bundle first (no entitlements).
-3. Build `DmShell.app`; place frameworks in `DmShell.app/Frameworks/`.
+3. Build `DmShell.app` and place frameworks in `DmShell.app/Frameworks/`.
4. Sign the shell executable with `com.apple.developer.kernel.increased-memory-limit`.
5. Sign the shell bundle last so `CodeResources` covers every nested CDHash (same order as
`build_probe.sh:79–86`).
-6. `pack_ipa.py` unchanged (mapping pairs, `--skip`, fingerprint reuse); `pack_launcher_ipa.py`
+6. `pack_ipa.py` unchanged (mapping pairs, `--skip`, fingerprint reuse), and `pack_launcher_ipa.py`
orchestrates, skips the shell's `Frameworks/` in the generic map and maps each framework
explicitly.
-7. Self-check: `codesign -vvv --verify --strict` on framework and app; `otool -l` for
- `LC_ID_DYLIB=@rpath/<game>.framework/<game>` and app `LC_RPATH`; `plutil` both Info.plists.
+7. Self-check: `codesign -vvv --verify --strict` on framework and app, `otool -l` for
+ `LC_ID_DYLIB=@rpath/<game>.framework/<game>` and app `LC_RPATH`, and `plutil` on both Info.plists.
Incremental: `pack_ipa.py` keys on size/mtime/ctime/inode, and ad-hoc re-signing rewrites bytes —
cache each signed framework per game (`$W/build/ios/frameworks/<id>/`) and never re-sign an
-unchanged one; a shell change then rewrites only the shell entries.
+unchanged one, so a shell change then rewrites only the shell entries.
## Tests
-Off-device: the tool-test loop; `compile_check.py` both modes; `xcodegen` + `xcodebuild` of the
-framework from a synthetic `Gen`; macOS `dlopen`/`dlsym`/`dladdr` of a small dylib
-(`getsectiondata`/`vm_remap` are covered by M1 on device); synthetic aggregate IPA checks
-(`unzip -l`, `codesign -vvv`, negative chain/duplicate cases); `test_shell_library.py` three-state
-cases; `test_shell_data.py` environment/isolation.
+Off-device: the tool-test loop, `compile_check.py` in both modes, `xcodegen` + `xcodebuild` of the
+framework from a synthetic `Gen`, macOS `dlopen`/`dlsym`/`dladdr` of a small dylib
+(`getsectiondata`/`vm_remap` are covered by M1 on device), synthetic aggregate IPA checks
+(`unzip -l`, `codesign -vvv`, negative chain/duplicate cases), `test_shell_library.py` three-state
+cases, and `test_shell_data.py` environment/isolation.
On-device (minimum): M1 one real NVN game + one NRO game with `DM_LOADHASH` matching the default
-build; M2 shell + 1; M3 shell + 2 with a broken framework; M4 two games with data/settings/DLC/
-external drive; M5 upgrade/reinstall (bookmarks), incremental timing, iOS 26.1/27.
+build, M2 shell + 1, M3 shell + 2 with a broken framework, M4 two games with data/settings/DLC/
+external drive, and M5 upgrade/reinstall (bookmarks), incremental timing, iOS 26.1/27.
## Top risks
-1. **Real payload unproven (M1)** — run a real game, not the probe; compare `DM_LOADHASH` with the
- default build; a `dlopen` success does not imply `vm_remap` works.
-2. **Nested re-signing / entitlements** — framework first, shell last; framework carries no
- entitlements; test with AltStore, Sideloadly and i4Tools once, record which one.
-3. **Size / re-sign / install limit** — code dimension stays 4–8 games/IPA (not unbounded); data
- stays in Documents; every added game means a new IPA, re-signed.
-4. **Shell lifecycle / globals / ObjC** — one game per process; one preload; `DM_PROFILE` before the
- first `dm_profile()`; FH must handle duplicated ObjC classes (design §36–42, 277–284).
-5. **Complexity regressing the default path** — default `project.yml` untouched; framework mode is
- opt-in; existing tests must stay green; cache prevents re-signing.
+1. **Real payload unproven (M1)** — run a real game, not the probe, and compare `DM_LOADHASH` with the
+ default build. A `dlopen` success does not imply `vm_remap` works.
+2. **Nested re-signing / entitlements** — framework first, shell last, and the framework carries no
+ entitlements. Test with AltStore, Sideloadly and i4Tools once, record which one.
+3. **Size / re-sign / install limit** — code dimension stays 4–8 games/IPA (not unbounded), data
+ stays in Documents, and every added game means a new IPA, re-signed.
+4. **Shell lifecycle / globals / ObjC** — one game per process, one preload, `DM_PROFILE` before the
+ first `dm_profile()`, and FH must handle duplicated ObjC classes (design §36–42, 277–284).
+5. **Complexity regressing the default path** — default `project.yml` untouched, framework mode is
+ opt-in, existing tests must stay green, and a cache prevents re-signing.
## FH fallback trigger (decidable)
Switch to FH only when **all** hold: `dlopen` and `dlsym(marker)` succeed and `dladdr` gives the
-framework base; a plain control dylib/framework in the bundle loads and runs; but
+framework base, and a plain control dylib/framework in the bundle loads and runs, but
`getsectiondata(framework_mh, "__TEXT", "__dm<mod>x0")` returns NULL for real modules, or dyld
rejects a pure-module dylib carrying several `__DM<mod>W` sections. If `dlopen` fails for any
bundle framework (contradicting the probe), or `vm_remap` of signed pages cannot execute, FH does
@@ -200,14 +200,14 @@ not help (it also maps an image) — fall back to architecture A/B instead of sp
## Documentation to update as this lands
-- `docs/ROADMAP.md`: C is **not** unbounded (code dimension 4–8 games/IPA; every added game needs a
- re-signed IPA; the data dimension is the unbounded one — see design §136–153); the `romfs_locate`
+- `docs/ROADMAP.md`: C is **not** unbounded (code dimension 4–8 games/IPA, and every added game needs a
+ re-signed IPA, while the data dimension is the unbounded one — see design §136–153). The `romfs_locate`
row is stale (`main.m` already does per-game + picker + identity).
-- `docs/WORK-IN-PROGRESS.md`: C7 "experiment passed, M1–M5 in progress"; architecture A's per-game
- layout is done; runtime profile is on main since `3b36083f`.
+- `docs/WORK-IN-PROGRESS.md`: C7 "experiment passed, M1–M5 in progress", architecture A's per-game
+ layout is done, and the runtime profile is on main since `3b36083f`.
- `README.md` / `README.zh-CN.md`: v0.4.7's "launcher not started" note is stale.
-- `docs/probe-dlopen.md`: device result recorded (done in #139); keep "what it does not prove".
-- `docs/launcher-c-design.md`: status line; §52–53 says omitting argv lets the profile's modules
+- `docs/probe-dlopen.md`: device result recorded (done in #139), and keep "what it does not prove".
+- `docs/launcher-c-design.md`: status line. The text at §52–53 says omitting argv lets the profile's modules
apply, but `dm/host/main.c:95` falls back to the compiled macro — fix the doc or the code in M2.
- `docs/development.md`, `docs/reference/packing.md`, `docs/frontends.md`: `--framework`,
`build_shell.sh`, `pack_launcher_ipa.py`, signing order, incremental cache, and what the shell is.
diff --git a/docs/probe-dlopen.md b/docs/probe-dlopen.md
index 42ef8aba..f50079dd 100644
--- a/docs/probe-dlopen.md
+++ b/docs/probe-dlopen.md
@@ -7,10 +7,10 @@ iPhone, can a sideloaded IPA — installed outside the App Store review with Alt
i4Tools (爱思助手) — `dlopen` a dynamic framework inside its own bundle and call functions in it?**
Every app with dynamic frameworks loads nested code from its own bundle at launch, so the
-mechanism exists; what this probe proves is that it survives the sideloaded conditions, where a
+mechanism exists, and what this probe proves is that it survives the sideloaded conditions, where a
free-provisioning signature replaces the ad-hoc one at install time and re-signs the app and every
nested framework. If `dlopen` refuses such code, route C is dead on stock devices and the dlerror
-texts are the evidence for upstream; if it works, route C stands.
+texts are the evidence for upstream. If it works, route C stands.
## What ships
@@ -26,13 +26,13 @@ Payload/DmProbe.app/
At launch the shell appends one line per step to `Documents/probe-log.txt` and shows the verdict on
its screen:
-1. the bundle and executable paths, the iOS version, and whether the framework file is present;
+1. the bundle and executable paths, the iOS version, and whether the framework file is present,
2. `dlopen` attempts in order, each with its handle or its `dlerror()` text verbatim:
`@executable_path/Frameworks/Probe.framework/Probe`, then `@rpath/Probe.framework/Probe`, the
absolute sandbox path of the same file, the relative `Probe.framework/Probe`, and the bare
- `Probe` (the last two are expected to fail; their texts tell us how far dyld got);
+ `Probe` (the last two are expected to fail, and their texts tell us how far dyld got),
3. on the first success: `dlsym` of `probe_answer`, a call (42 expected), and `dladdr` naming the
- image the symbol came from;
+ image the symbol came from,
4. the last line is the verdict: `RESULT: FEASIBLE ...` or `RESULT: BLOCKED ...` plus the reason.
## Installing and reading the result
@@ -43,10 +43,10 @@ its screen:
IPA). The IPA is unsigned-but-ad-hoc on purpose: the sideloader re-signs it with the user's
Apple ID, exactly like every game IPA this repository ships.
2. The first install from a given Apple ID needs Settings → General → VPN & Device Management →
- trust the certificate. A free Apple ID re-signs every 7 days; a one-shot probe does not mind.
+ trust the certificate. A free Apple ID re-signs every 7 days, but a one-shot probe does not mind.
3. Open DmProbe and wait two seconds. The result is on the screen and in the file:
**Files app → On My iPhone → DmProbe → probe-log.txt** (`UIFileSharingEnabled` in the app's
- Info.plist makes Documents visible there; runs append, so nothing is lost).
+ Info.plist makes Documents visible there, and runs append, so nothing is lost).
4. Send the log back by sharing it from the Files app (long-press → Share → AirDrop / Mail /
WeChat), or from i4Tools' app-file browser (DmProbe → Documents → probe-log.txt). If no new
lines appeared, the app died before logging: send the crash report instead (Settings → Privacy
@@ -54,7 +54,7 @@ its screen:
## Result: FEASIBLE (device run, 2026-10-26)
-Run on an iPhone (iOS **27.0.1**, sideloaded IPA; probe built 2026-10-27). The full log:
+Run on an iPhone (iOS **27.0.1**, sideloaded IPA, probe built 2026-10-27). The full log:
```text
---- DmProbe run 2026-10-26 19:51:50 +0000 (probe built Oct 27 2026 03:48:01) ----
@@ -76,10 +76,10 @@ resolves a symbol in it and executes it. Route C is viable in principle.
**What this still does not prove** (design doc §R1, and the reasons are different):
- a framework carrying the game's working set — the many `__DM*W` sections (up to 255 per image),
- tens of MB of `__TEXT` — loads and executes like this one-function probe;
+ tens of MB of `__TEXT` — loads and executes like this one-function probe,
- the launcher's `vm_remap` of the game image's signed `__TEXT` into an anonymous address
- (copy = FALSE) is accepted for a sideloaded, re-signed framework;
-- `getsectiondata` on a *dylib* header (the probe only used `dlsym`/`dladdr`);
+ (copy = FALSE) is accepted for a sideloaded, re-signed framework,
+- `getsectiondata` on a *dylib* header (the probe only used `dlsym`/`dladdr`),
- loading a framework that was re-signed by a free Apple ID and installed through a different
sideloader than the probe's.
@@ -91,27 +91,27 @@ one real game as a framework, in a shell app, on a device.
| Last line of probe-log.txt | Meaning |
|---|---|
| `RESULT: FEASIBLE - dlopen("@executable_path/Frameworks/Probe.framework/Probe") succeeded and probe_answer() = 42` | Route C is viable: a sideloaded app loads and calls code in a framework inside its own bundle. Proceed with the launcher shell + per-game frameworks. |
-| `RESULT: BLOCKED - ... no suitable image found ... (no such file)` | The framework is not in the installed bundle: the sideloader stripped it or the layout broke. Record the sideloader and version; fix the packaging before concluding anything about `dlopen`. |
-| `RESULT: BLOCKED - ... code signature ... not valid` / `not signed` / `no Team ID` | The nested framework's signature was rejected: the sideloader failed to re-sign it, or iOS refuses its signature. Record the exact text and sideloader; retry with another sideloader (or an `ldid`-signed IPA) before treating it as a platform refusal. |
-| `RESULT: BLOCKED - ...` with any other `dlerror` text | Record the text verbatim with the device model, iOS version and sideloader; the attempt lines above it show which forms were tried. |
+| `RESULT: BLOCKED - ... no suitable image found ... (no such file)` | The framework is not in the installed bundle: the sideloader stripped it or the layout broke. Record the sideloader and version, and fix the packaging before concluding anything about `dlopen`. |
+| `RESULT: BLOCKED - ... code signature ... not valid` / `not signed` / `no Team ID` | The nested framework's signature was rejected: the sideloader failed to re-sign it, or iOS refuses its signature. Record the exact text and sideloader, and retry with another sideloader (or an `ldid`-signed IPA) before treating it as a platform refusal. |
+| `RESULT: BLOCKED - ...` with any other `dlerror` text | Record the text verbatim with the device model, iOS version and sideloader. The attempt lines above it show which forms were tried. |
The failing fallbacks (relative and bare-name forms) always log `no suitable image found` texts —
-that is their expected outcome, not a verdict; the verdict uses only whether some form loaded.
+that is their expected outcome, not a verdict. The verdict uses only whether some form loaded.
## What it does not prove
- **App Store review rules** (a policy question, not a technique one): irrelevant to sideloaded
distribution, which is how this project ships.
- **Loading code that is not in the signed bundle** (streaming game payloads from disk — the
- original ROADMAP blocker): still expected to be blocked; route C compiles each game's modules
+ original ROADMAP blocker): still expected to be blocked, since route C compiles each game's modules
into its framework at packaging time, inside the signed bundle.
- **JIT, or anything about the game modules themselves**: the rewriter's output needs much more
- than one C function; this probe only opens the door the launcher would walk through.
+ than one C function, and this probe only opens the door the launcher would walk through.
The build was self-checked on the Mac only (`codesign -vvv --verify --strict` on the framework,
-the app, and the app extracted from the packed IPA again; `otool` load commands: the app's
+the app, and the app extracted from the packed IPA again. `otool` load commands: the app's
`LC_RPATH @executable_path/Frameworks`, the framework's install name `@rpath/Probe.framework/Probe`,
-`minos 26.0`; `lipo` arm64; `plutil` on both Info.plists; `ldid` is not installed on this machine,
+`minos 26.0`, `lipo` arm64, `plutil` on both Info.plists, and `ldid` is not installed on this machine,
so codesign only). The device run is the user's step.
## Building it again
diff --git a/frontend-qt/README.md b/frontend-qt/README.md
index 8c72012e..c20c0dcb 100644
--- a/frontend-qt/README.md
+++ b/frontend-qt/README.md
@@ -35,13 +35,13 @@ wherever `NSPB_REPO` points, and the repository group lets you pick it by hand.
- Dependency detection per platform: Python + packages, .NET SDK, and either **Xcode + iOS SDK +
Metal toolchain** (macOS) or the **Windows cross toolchain** (see [Windows build](#windows-build)),
plus xcodegen / zstd / spirv-cross. Each row has an install button when a command can fix it.
-- Pick a game folder (or its four inputs separately); base / update / DLC / `prod.keys` are
+- Pick a game folder (or its four inputs separately). Base / update / DLC / `prod.keys` are
recognised from the dump names.
- Build: runs the same script the SwiftUI app runs, streams its stage lines and log, then packs
the RomFS archive and reports where the IPA and archive landed.
- `--work-dir` is passed only when the checkout's script declares it (an upstream checkout has
no such option — issue #5).
-- Bilingual: Chinese on Chinese devices, English elsewhere; the header button switches.
+- Bilingual: Chinese on Chinese devices, English elsewhere, and the header button switches.
## What is not there yet
@@ -95,7 +95,7 @@ The upstream file is never edited, so the daily sync cannot conflict with this w
| `dmsh_xlate` apphost (a Mach-O) | `dotnet dmsh_xlate.dll`, the same locked build |
| `which`, `python3`, `ctypes.CDLL(None)` | `sitecustomize.py` rewrites them at the subprocess boundary |
| app icon via `actool` | Pillow, five sizes |
-| `codesign` ad-hoc + entitlements | skipped; the sideloader re-signs the IPA anyway |
+| `codesign` ad-hoc + entitlements | skipped, since the sideloader re-signs the IPA anyway |
| the IPA's Unix `x` bit | `win/fix_ipa_modes.py` rewrites the zip's central directory in place |
## What you need to install
@@ -108,7 +108,7 @@ optional Vulkan/GL tools.
Everything it downloads goes to `%LOCALAPPDATA%\NS Port Builder\tools`, outside the app folder, so
updating the app (re-extracting its zip) does not throw the 182 MB LLVM archive away.
-Run this first if you prefer the command line; it lists what is missing and where to get it:
+Run this first if you prefer the command line. It lists what is missing and where to get it:
```bat
python -m nspb_qt.win.doctor
@@ -118,7 +118,7 @@ python -m nspb_qt.win.doctor
(and `backports.zstd` before Python 3.14).
2. **.NET SDK 10** — the app downloads it (the zip, not the installer: no administrator rights,
about 287 MB), or get it from <https://dotnet.microsoft.com/download/dotnet/10.0> (SDK, x64).
- `nx_extract` targets `net10.0`, so SDK 8 or 9 alone is not enough; the dependency row says so
+ `nx_extract` targets `net10.0`, so SDK 8 or 9 alone is not enough, and the dependency row says so
rather than failing halfway through a build.
3. **LLVM-MinGW 20261020** — the app's Dependencies panel downloads and verifies it, or:
@@ -132,7 +132,7 @@ python -m nspb_qt.win.doctor
|---|---|
| `llvm-mingw-20261020-ucrt-x86_64.zip` | `fd5462b7f5d93b2ff981fcd3f9c7e427e47f3203c64ea91c27bcc444eebd74cd` |
- Only the x86-64 archive is published by this app; a Windows-on-ARM machine runs it under
+ Only the x86-64 archive is published by this app, so a Windows-on-ARM machine runs it under
emulation (the dependency panel says so in a `host architecture` row).
The official `LLVM-*-win64.msi` from llvm.org works too (same clang, same LLD).
@@ -153,7 +153,7 @@ python -m nspb_qt.win.doctor
The app cannot download this for you: Apple gates it behind a login.
6. **spirv-cross** and **zstd** — Windows builds. The Vulkan SDK has `spirv-cross` (and
- `glslangValidator`); zstd has releases on GitHub.
+ `glslangValidator`), and zstd has releases on GitHub.
If auto-detection picks the wrong folder, set it in
`%LOCALAPPDATA%\NS Port Builder\toolchain.json`:
@@ -182,7 +182,7 @@ two mirrors (`ghfast.top`, `gh-proxy.com`), and picks between them by timing a 2
request — the report that prompted this was a 974-second download that *succeeded*, so failing
over on errors alone would never have helped. The pinned SHA-256 is the only thing that decides
what gets unpacked: a mirror serving different bytes is rejected exactly like a corrupted
-download. Microsoft's CDN (the .NET SDK) is not mirrored; it is fast enough on its own.
+download. Microsoft's CDN (the .NET SDK) is not mirrored, because it is fast enough on its own.
**Where tools land.** `%LOCALAPPDATA%\NS Port Builder\tools`. Not inside the app folder: the app
ships as a zip that gets re-extracted for every update, which would take 182 MB of LLVM with it.
@@ -214,7 +214,7 @@ Exit code 0 means every required row passed its probe.
### The one thing llvm-mingw gets wrong
-llvm-mingw's release script (`strip-llvm.sh`) **deletes `ld64.lld.exe`**; the zip only has
+llvm-mingw's release script (`strip-llvm.sh`) **deletes `ld64.lld.exe`**, so the zip only has
`ld.lld.exe`. That is not a dead end: LLD is one binary containing every driver and picks one
from `argv[0]`. Copying `ld.lld.exe` to `ld64.lld.exe` gives the Mach-O linker, and the app does
that automatically (`toolchain.ensure_ld64_lld`). A build of LLD that was stripped down to ELF
@@ -234,7 +234,7 @@ broken IPA:
(Pokémon Legends: Z-A, PlatinumGames titles, DRAGON QUEST XI S, …). Upstream decodes them by
running the game's own decoder.
- **The heap check** for a provisional profile. Replaced by an estimate (a 2 GB pool for a game
- with virtual address memory); see `driver.heap_check`.
+ with virtual address memory). See `driver.heap_check`.
- **The pipeline archive** (`pso_offline.py` / `metal-tt`). Apple's Windows Metal tools do not
ship `metal-tt`, so `DM_PSO_GPUS` is forced to `none`: the device builds those pipeline bases
on its first start instead (slower first launch, same result).
@@ -264,12 +264,12 @@ build on Windows plus a device run can settle:
different compiler version, so the build will not fail — only a device run proves it.
2. **The real rewritten modules.** Sections hundreds of MB, linked by `ld64.lld`, then signed by
the sideloader.
-3. **The UIKit launcher.** `win/ios/Launcher.m` is a hand port of `Launcher.swift`; it honours
+3. **The UIKit launcher.** `win/ios/Launcher.m` is a hand port of `Launcher.swift`. It honours
`section` grouping, a toggle's `on`/`off` values, env-file locking and Reset, but no one has
tapped through it on a device.
4. **Icons without an asset catalog** on iOS 26.
5. **Line endings.** The checkout must keep LF. The shader chain hashes source bytes, so a CRLF
- checkout breaks `dmsh_xlate --source-sha`. `.gitattributes` enforces this; a ZIP download
+ checkout breaks `dmsh_xlate --source-sha`. `.gitattributes` enforces this, but a ZIP download
with autocrlf on can still break it.
`nspb_qt/win/doctor.py` is the fastest way to narrow a failure: it separates "a tool is missing"
diff --git a/frontend-qt/nspb_qt/localization.py b/frontend-qt/nspb_qt/localization.py
index 6f7266e1..f61a1586 100644
--- a/frontend-qt/nspb_qt/localization.py
+++ b/frontend-qt/nspb_qt/localization.py
@@ -33,7 +33,7 @@ TABLE: dict[str, tuple[str, str]] = {
'dev.refresh': ('刷新', 'Refresh'),
'dev.team': ('签名团队', 'Signing team'),
'dev.noTeam': ('没有开发证书。在 Xcode 中登录 Apple ID(设置 → 账户)即可获得。', 'No development certificate. Sign in to Xcode with your Apple ID (Settings → Accounts) to get one.'),
- 'dev.note': ('Xcode 会为这台设备签名并直接安装,游戏数据(romfs.img)复制到 App 的“文稿”中,与侧载相同;第一次复制大型游戏需要几分钟。第一次需要在设备上开启开发者模式,并信任开发者(设置 → 通用 → VPN 与设备管理)。', 'Xcode signs the game for this device and installs it there, then copies the game data (romfs.img) into the app’s Documents, as for sideloading; the first copy of a large game takes a few minutes. The first time, turn on Developer Mode on the device and trust the developer (Settings → General → VPN & Device Management).'),
+ 'dev.note': ('Xcode 会为这台设备签名并直接安装,游戏数据(romfs.img)复制到 App 的“文稿”中,与侧载相同。第一次复制大型游戏需要几分钟。第一次需要在设备上开启开发者模式,并信任开发者(设置 → 通用 → VPN 与设备管理)。', 'Xcode signs the game for this device and installs it there, then copies the game data (romfs.img) into the app’s Documents, as for sideloading. The first copy of a large game takes a few minutes. The first time, turn on Developer Mode on the device and trust the developer (Settings → General → VPN & Device Management).'),
'saves.menu': ('存档…', 'Saves…'),
'saves.title': ('存档', 'Saves'),
'saves.mac': ('这台 Mac', 'This Mac'),
@@ -199,7 +199,7 @@ TABLE: dict[str, tuple[str, str]] = {
'repo.downloadFail': ('下载失败——网络不顺?用下面的手动方法', 'Download failed — flaky network? Use the manual route below'),
'repo.manualHint': ('网络不顺也可以手动:打开', 'Flaky network? Do it by hand: open'),
'repo.manualHint2': ('→ 点绿色 Code 按钮 → Download ZIP,解压后点「选择仓库…」选中解压出的文件夹', '→ the green Code button → Download ZIP, unzip, then pick the unzipped folder with Choose repository…'),
- 'repo.noGit': ('这是 ZIP 下载的副本(无 git 历史),构建不受影响;点「接入 git」转为可更新', 'This is a ZIP copy (no git history); builds work fine — Make updatable connects it to git'),
+ 'repo.noGit': ('这是 ZIP 下载的副本(无 git 历史),构建不受影响,点「接入 git」转为可更新', 'This is a ZIP copy (no git history), and builds work fine. Make updatable connects it to git'),
'repo.adopt': ('接入 git(可更新)', 'Make updatable (git)'),
'repo.adopting': ('正在接入 git…', 'Connecting git…'),
'repo.adopted': ('已接入 git,可以检查更新了', 'Connected — updates work now'),
@@ -222,19 +222,19 @@ TABLE: dict[str, tuple[str, str]] = {
'app.devBuild': ('%@ 已发布。这个启动器是从仓库构建的,不会替换自己', '%@ is out. This launcher was built from the repository and does not replace itself'),
'app.readOnly': ('%@ 已发布,但 App 无法在当前位置替换自己——请把它移到「应用程序」文件夹', '%@ is out, but the app cannot replace itself where it is — move it to Applications'),
'app.auto': ('自动安装更新', 'Install updates automatically'),
- 'app.autoNote': ('在后台下载并校验,退出 App 时安装;构建进行中绝不安装', 'Downloaded and verified in the background, installed when you quit; never during a build'),
+ 'app.autoNote': ('在后台下载并校验,退出 App 时安装,构建进行中绝不安装', 'Downloaded and verified in the background, installed when you quit and never during a build'),
'app.autoDev': ('从仓库构建的启动器不会自动更新', 'Not for a launcher built from the repository'),
'app.autoReadOnly': ('App 所在的文件夹不可写,无法自动更新', "The app's folder is not writable, so it cannot update itself"),
'library.appReady': ('NX2Apple %@ 已就绪', 'NX2Apple %@ is ready'),
'update.title': ('有新版本可用', 'A new version is out'),
'update.fromTo': ('当前 %@ → 新版本 %@', 'You have %@ — the new version is %@'),
- 'update.noNotes': ('这一版没有写更新说明,可以打开发布页查看。', 'This release has no notes; open the release page to see it.'),
+ 'update.noNotes': ('这一版没有写更新说明,可以打开发布页查看。', 'This release has no notes. Open the release page to see them.'),
'update.now': ('现在更新', 'Update now'),
'update.later': ('稍后', 'Later'),
'update.openPage': ('打开发布页', 'Open the release page'),
'app.installing': ('正在安装…(旧版本会进废纸篓)', 'Installing… (the old version goes to the Trash)'),
'app.relaunching': ('已更新到 %@,正在重启 App…', 'Updated to %@ — restarting…'),
- 'app.installFail': ('安装失败:%@——新版本已下载,可手动替换', 'Install failed: %@ — the new version was downloaded; replace by hand'),
+ 'app.installFail': ('安装失败:%@——新版本已下载,可手动替换', 'Install failed: %@ — the new version was downloaded, so replace it by hand'),
'app.netFail': ('网络失败(GitHub 不通?稍后再试)', 'Network failed (GitHub unreachable? try again later)'),
'repo.destBusy': ('%@ 已存在且不是本项目——换个位置,或点「选择仓库…」', '%@ already exists and is not this project — use another place, or Choose repository…'),
'repo.firstHint': ('第一次用?点「下载仓库」自动获取项目(约一分钟,需要网络)', 'First time here? Download repository fetches the project for you (about a minute, needs network)'),
@@ -289,7 +289,7 @@ TABLE: dict[str, tuple[str, str]] = {
'opt.note': ('按输出类型', 'per output'),
'opt.bc': ('兼容老设备(A15 / A16 及更早)', 'Older devices (A15 / A16 and earlier)'),
'opt.bc.note': ('在不支持 BC 纹理压缩的 GPU 上于 CPU 解压:iPhone 13 及更早、A16 的 iPad。新设备请保持关闭——GPU 路径更快', 'Decode BC textures on the CPU for GPUs without BC support: iPhone 13 and earlier, A16 iPads. Leave off on newer devices — the GPU path is faster'),
- 'opt.macNoBc': ('Mac App 用这台 Mac 的 GPU,不需要兼容选项', "A Mac app uses this Mac's GPU; no compatibility option needed"),
+ 'opt.macNoBc': ('Mac App 用这台 Mac 的 GPU,不需要兼容选项', "A Mac app uses this Mac's GPU, so no compatibility option is needed"),
'msg.bcOn': ('兼容老设备:BC 纹理将在 CPU 上解压', 'Older-device mode: BC textures will be decoded on the CPU'),
'msg.bcEnvFailed': ('无法写入环境文件:%@——继续构建,但兼容模式未启用', 'Could not write the environment file: %@ — building without the compatibility mode'),
'target.ios': ('输出:iPhone IPA', 'Output: iPhone IPA'),
@@ -353,7 +353,7 @@ TABLE: dict[str, tuple[str, str]] = {
'dep.xcodegen.hint': ('Xcode 工程生成', 'generates the Xcode project'),
'dep.zstd': ('brew: zstd', 'brew: zstd'),
'dep.spirv.win': ('spirv-cross', 'spirv-cross'),
- 'dep.spirv.hint.win': ('仅 OpenGL 游戏(如 Balatro、Digimon)需要,Metal 游戏用不到。装 <a href="https://vulkan.lunarg.com/sdk/home">Vulkan SDK</a> 即可,本程序会自动在 %VULKAN_SDK%\\\\Bin 和 C:\\\\VulkanSDK\\\\<版本>\\\\Bin 里找到它,不用改任何配置', 'only OpenGL games (Balatro, Digimon) need it; Metal games never do. Install the <a href="https://vulkan.lunarg.com/sdk/home">Vulkan SDK</a> and this app finds it in %VULKAN_SDK%\\\\Bin or C:\\\\VulkanSDK\\\\<version>\\\\Bin by itself — no configuration'),
+ 'dep.spirv.hint.win': ('仅 OpenGL 游戏(如 Balatro、Digimon)需要,Metal 游戏用不到。装 <a href="https://vulkan.lunarg.com/sdk/home">Vulkan SDK</a> 即可,本程序会自动在 %VULKAN_SDK%\\\\Bin 和 C:\\\\VulkanSDK\\\\<版本>\\\\Bin 里找到它,不用改任何配置', 'only OpenGL games (Balatro, Digimon) need it, and Metal games never do. Install the <a href="https://vulkan.lunarg.com/sdk/home">Vulkan SDK</a> and this app finds it in %VULKAN_SDK%\\\\Bin or C:\\\\VulkanSDK\\\\<version>\\\\Bin by itself — no configuration'),
'dep.zstd.win': ('zstd', 'zstd'),
'dep.zstd.hint.win': ('解压——点「安装」由 App 下载(facebook/zstd 官方 Windows 版)', "decompression — press Install and the app fetches it (facebook/zstd's official Windows build)"),
'dep.metal.hint.win': ('需要 <a href="https://developer.apple.com/download/all/">Apple 开发者下载页</a> 的「Metal Developer Tools for Windows」(需 Apple ID)', 'needs <a href="https://developer.apple.com/download/all/">Apple developer downloads</a>: "Metal Developer Tools for Windows" (Apple ID required)'),
@@ -372,11 +372,11 @@ TABLE: dict[str, tuple[str, str]] = {
'dep.python.missing': ('%@ 缺包', '%@ is missing packages'),
'dep.install.begin': ('开始安装 %@…', 'Installing %@…'),
'dep.install.fail': ('安装失败:%@(详情见日志)', 'Install failed: %@ (see the log)'),
- 'dep.python.old': ('Python %@ 太旧(需要 %@ 或更新);这个解释器没有构建需要的包', 'Python %@ is too old (need %@ or newer); it lacks the packages the build needs'),
- 'dep.python.notFound': ('没找到 Python %@ 或更新版本;先装一个(brew install python@%@),再点「重新检测」', 'No Python %@ or newer found; install one (brew install python@%@), then press Check again'),
+ 'dep.python.old': ('Python %@ 太旧(需要 %@ 或更新),这个解释器没有构建需要的包', 'Python %@ is too old (need %@ or newer), and it lacks the packages the build needs'),
+ 'dep.python.notFound': ('没找到 Python %@ 或更新版本,先装一个(brew install python@%@),再点「重新检测」', 'No Python %@ or newer found. Install one (brew install python@%@), then press Check again'),
'dep.python.none': ('没找到可用的 Python(%@ 不行)——点右侧「安装」,App 会下载 3.12 并静默装到自己的目录', 'No usable Python found (%@ will not run) — press Install and the app fetches 3.12 into its own folder'),
- 'msg.workdirHint': ('提示:「输出目录」同时是构建缓存的位置(输出目录/<ID>_build)。已有构建资源时,把它选回上次的同一位置即可复用(解包、shader 不重跑);换新位置会从头再来。', 'Tip: the output folder is also where the build cache lives (<output>/<ID>_build). To reuse an existing build, point it back at the same folder; a new folder starts over.'),
- 'msg.chainChanged': ('上游代码更新了 shader 翻译链,之前构建的 shader 库无法复用——本次构建用新翻译器重建(每个版本一次,之后的构建恢复复用)。', 'An upstream update changed the shader translator, so previously built shader libraries cannot be reused — this build rebuilds them with the new one (once per update; later builds reuse as before).'),
+ 'msg.workdirHint': ('提示:「输出目录」同时是构建缓存的位置(输出目录/<ID>_build)。已有构建资源时,把它选回上次的同一位置即可复用(解包、shader 不重跑),换新位置会从头再来。', 'Tip: the output folder is also where the build cache lives (<output>/<ID>_build). To reuse an existing build, point it back at the same folder, since a new folder starts over.'),
+ 'msg.chainChanged': ('上游代码更新了 shader 翻译链,之前构建的 shader 库无法复用——本次构建用新翻译器重建(每个版本一次,之后的构建恢复复用)。', 'An upstream update changed the shader translator, so previously built shader libraries cannot be reused, so this build rebuilds them with the new one (once per update, and later builds reuse as before).'),
'dep.python.downloading': ('正在下载并安装 Python 3.12…(约 26 MB,装到 App 自己的目录)', "Downloading and installing Python 3.12… (about 26 MB, into the app's own folder)"),
'dep.python.done': ('Python 已安装:%@', 'Python installed: %@'),
'prog.title': ('构建进度', 'Build progress'),
diff --git a/frontend/Onboarding.md b/frontend/Onboarding.md
index 1048e583..6219c74d 100644
--- a/frontend/Onboarding.md
+++ b/frontend/Onboarding.md
@@ -14,12 +14,12 @@ NSPB_ONBOARDING_DEMO=noGames swift run
```
- `fresh`: Start, select a platform, Continue, Get Xcode, wait, Finish setup, confirm the found keys, review the games, Continue, Open library.
-- `xcodeReady`: the same path, with Xcode already present; its checks tick through automatically.
+- `xcodeReady`: the same path, with Xcode already present, and its checks tick through automatically.
- `keysInvalid`: confirming the found file fails validation. Choose or drop another file to exercise recovery. The mock does not read it.
- `xcodeFailed`: setup fails with a plain explanation and expandable diagnostics. Retry, then Finish setup to recover.
- `noGames`: the mock folder scan finds no NSPs and shows a hint. Use Back or Set up later.
-Set up later preserves an in-memory snapshot; Resume setup restores it. The mock persists nothing; the real driver does (below).
+Set up later preserves an in-memory snapshot, and Resume setup restores it. The mock persists nothing, and the real driver does (below).
`NSPB_ONBOARDING_FORCE=1 swift run` shows the real flow (the live driver, real detection) on launch even when setup is complete or marked done. It writes nothing until the player finishes or picks "Set up later": no `onboarding.completed`, step, platform or build target, and nothing is installed until an install action (Get Xcode, Finish setup, Retry) is pressed. Quitting in between leaves no trace.
@@ -42,21 +42,21 @@ skipForLater()
openLibrary()
```
-The driver owns detection, installation, privileges, security-scoped access to selected URLs, validation, decoded cover images, persistence, and navigation. The view owns only presentation, the system chooser, drop URL decoding, disclosure expansion and input handling. No key file contents belong in `OnboardingState`, failure text or diagnostics. Failure messages must already be localized; `details` is diagnostic text supplied by the driver.
+The driver owns detection, installation, privileges, security-scoped access to selected URLs, validation, decoded cover images, persistence, and navigation. The view owns only presentation, the system chooser, drop URL decoding, disclosure expansion and input handling. No key file contents belong in `OnboardingState`, failure text or diagnostics. Failure messages must already be localized, and `details` is diagnostic text supplied by the driver.
Use `OnboardingState.next()` and `.back()` for gated navigation. `canAdvance` requires disk space on Welcome, a platform selection, Xcode plus all background tasks, valid keys, or a nonempty games list respectively. `primary` distinguishes a step action (Get Xcode, Finish setup, confirm keys, Retry) from advancing. `primaryEnabled` also gates completion and dismissed flows. `setupTasks` derives the iOS row from the selected platform.
Automatic advancement belongs in the driver. The mock gives completed Xcode and keys a brief checkmark hold, then advances. Returning to an already completed step stays there so Back remains useful. Games wait for explicit Continue so the player can review what was found. On a return visit, selecting iPhone after completed Mac setup adds the iOS preparation step.
-Persist the current step and selections before handling `skipForLater`; inject the restored state on the next launch and revalidate external prerequisites in the real driver. `MockOnboardingDriver(state:)` demonstrates restoration without preferences or file I/O. Its `animated: false` initializer disables scheduled changes for deterministic tests.
+Persist the current step and selections before handling `skipForLater`, then inject the restored state on the next launch and revalidate external prerequisites in the real driver. `MockOnboardingDriver(state:)` demonstrates restoration without preferences or file I/O. Its `animated: false` initializer disables scheduled changes for deterministic tests.
## The real driver
`LiveOnboardingDriver` (`LiveOnboardingDriver.swift`) implements the contract over the launcher's own `BuildModel` and `GameLibrary`, which `RootView` shares with `ContentView`. Everything it does to the machine goes through `OnboardingEnvironment`, so the tests use fakes.
-- When it shows: on launch, unless `onboarding.completed` is set or setup is already complete (all tools present, a keys file known, a games folder set; a complete one is marked done without being shown). Settings has "Run setup again". Set up later stores the step, platform and an in-progress flag in `UserDefaults`; the next launch resumes there and revalidates (a stored step past Xcode returns to Xcode when Xcode no longer holds).
+- When it shows: on launch, unless `onboarding.completed` is set or setup is already complete (all tools present, a keys file known, a games folder set, and a complete one is marked done without being shown). Settings has "Run setup again". Set up later stores the step, platform and an in-progress flag in `UserDefaults`, and the next launch resumes there and revalidates (a stored step past Xcode returns to Xcode when Xcode no longer holds).
- Detection and installs are `BuildModel.checkDeps` / `deps` / `installDep`, one install at a time (Python, .NET, then Homebrew and the formulas). Homebrew waits for Xcode to be ready. The xcode row asks for the iOS SDK only when the stored platform is not Mac-only or builds target an iPhone (`BuildModel.needsIOSPlatform`).
-- Xcode: missing opens the App Store and polls /Applications for it; setup is one administrator prompt (`OnboardingAdmin.source`: `xcode-select -s`, `xcodebuild -license accept`, `-runFirstLaunch`), then the Metal Toolchain and, for iPhone or both, the iOS platform without it. A cancelled prompt returns to `needsSetup`.
+- Xcode: missing opens the App Store and polls /Applications for it, and setup is one administrator prompt (`OnboardingAdmin.source`: `xcode-select -s`, `xcodebuild -license accept`, `-runFirstLaunch`), then the Metal Toolchain and, for iPhone or both, the iOS platform without it. A cancelled prompt returns to `needsSetup`.
- Keys are found in `~/.switch`, `~/Downloads` and the games folder, checked by `KeyCheck`, and only the path goes into the keys slot. Games use `GameLibrary.sourceGames`, `BuildModel.scan` and `GameLibrary.setFolder`.
## Presentation choices
diff --git a/frontend/README.md b/frontend/README.md
index e5f95fa8..de48c966 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -33,15 +33,15 @@ Setup lives under **Settings**: the games folder, the repository and its updates
the dependency checks and installers, and app updates. Missing setup is linked
from the build screen. The progress shows each of the script's steps with its
count, the time it has been running and, while the script's estimate lasts, the
-time left; the build log opens under it. **Stop** ends the script and every tool
+time left. The build log opens under it. **Stop** ends the script and every tool
it started (the build runs in a process group of its own), and so does quitting
the app.
**Settings → Copy diagnostics** puts a short Markdown report on the clipboard, for a
-bug report: the app and macOS versions and the chip; the repository, its commit and
-branch and how far it is behind `upstream/main` and `origin/main` as of the last fetch
-(nothing is fetched); the Python and .NET the builds run with and the dependency
-check; this session's last build command and the last 50 lines of its log. The home
+bug report. It holds the app and macOS versions and the chip, the repository (its commit and
+branch and how far it is behind `upstream/main` and `origin/main` as of the last fetch, since
+nothing is fetched), the Python and .NET the builds run with and the dependency
+check, and this session's last build command and the last 50 lines of its log. The home
folder is shown as `~`, a log line holding key material (`name = <hex>`, as in
`prod.keys`) keeps only its name, and no environment variables are included.
@@ -50,7 +50,7 @@ with **Play**. An iPhone build, by default, offers its unsigned IPA and the
sideloading and RomFS-copy instructions.
When a build finishes or fails while the app is in the background, a notification
-names the game and the target; clicking it shows the game in the library, or the
+names the game and the target. Clicking it shows the game in the library, or the
Builds page with the log for a failed build. macOS asks for permission when the
first build starts, and **Settings → App** turns it off. Notifications need the
app bundle: started with `swift run` the launcher has no bundle identifier, and
@@ -77,14 +77,14 @@ The first time, turn on Developer Mode on the device and trust the developer
under Settings → General → VPN & Device Management. With a free Apple ID the
profile expires after seven days. **Don't install, export the IPA** keeps the
unsigned IPA as before. The devices and teams are read with `devicectl list
-devices` and `security find-identity`; the team is the certificate's
+devices` and `security find-identity`. The team is the certificate's
organizational unit, not the code in its name.
## Saves
**Manage > Saves…** (a controller's Y) shows a game's save on this Mac
(where `dm/mac/launcher.c` puts it: `<library folder>/save/<title ID>` beside the app when
-its folder holds `games/`, else `~/Library/Application Support/nxnative/<title ID>/save`;
+its folder holds `games/`, else `~/Library/Application Support/nxnative/<title ID>/save`, and
until the app has copied an older `~/Library` save across, that one is shown) and
on the device the launcher installed it on (`Documents/games/<title ID>/save` in the app's
data container, from `dm/ios/Sources/main.m`), each with the date of its newest file, and
@@ -93,7 +93,7 @@ asking. The save being replaced is backed up first, beside the Mac save in
`<save>-backups/<date> mac` or `<date> device` (the device's is copied to the Mac before
anything is replaced). A game that also keeps device save data has a `<save>_device`
folder beside it (`dm/host/hle_fs.c`), which goes along. The copy is refused while
-the game runs on the Mac; close it on the device too, or it writes its own save over the
+the game runs on the Mac. Close it on the device too, or it writes its own save over the
copy later. The device side uses the install's route: `devicectl device info files` for
the date and `devicectl device copy from` / `copy to` with the app's data container. Only
a game installed from here has a known bundle ID, so a sideloaded IPA has no device side.
@@ -104,8 +104,8 @@ Set **Your games folder** in Settings once. The launcher remembers it, checks it
on startup, and uses it as the default output location for new builds. **Refresh**
looks for existing nxnative Mac game apps, including apps in subfolders up to four
levels deep. It skips game contents, extraction folders and build caches. It does
-not copy or move the games. Several builds of the same title occupy one entry;
-an already linked, valid build keeps its location.
+not copy or move the games. Several builds of the same title occupy one entry,
+and an already linked, valid build keeps its location.
Readiness is checked against each app's title ID and executables. Ready games are
green, building games are yellow, and games without a finished output are gray.
@@ -118,11 +118,11 @@ library manifest is stored at
The button beside **Play** opens the game's launch options: the settings the iPhone
launcher shows before a game starts ([docs/settings.md](../docs/settings.md)), read
from the list the engine packs into the Mac app (`Contents/Resources/dm/launcher.json`,
-written by `dm/games/settings.py` from `dm/games/settings.tsv`; the engine change that
+written by `dm/games/settings.py` from `dm/games/settings.tsv`, and the engine change that
packs it is [seedds/nxnative#352](https://github.com/seedds/nxnative/pull/352), so a
sync from upstream brings it). **Play** starts the app with every setting in its
environment. Only a choice that differs from the game's tested default is kept, in the
-library manifest; **Reset to tested defaults** forgets them. An app without the list
+library manifest. **Reset to tested defaults** forgets them. An app without the list
shows none. Starting the app from Finder uses its defaults.
## Controls
@@ -147,20 +147,20 @@ buttons by their letters (an Xbox controller's letters are Apple's button diamon
a Pro Controller's A, on the right, arrives as `buttonA`, as
[seedds/nxnative#382](https://github.com/seedds/nxnative/pull/382) found), which the
host's positional reading turns into the other letter, so one swap serves both.
-**Custom** is the per-button choice; changing a button switches to it. **Auto** picks
+**Custom** is the per-button choice. Changing a button switches to it. **Auto** picks
By label or Standard from `GCController.productCategory` of the controller connected
when **Play** is pressed (Nintendo, Switch Pro, Joy-Con or Xbox in its name: By label).
-One map goes to every controller, so two different kinds at once cannot both be right;
-a per-controller choice belongs in the host (#382 does it for Nintendo controllers).
+One map goes to every controller, so two different kinds at once cannot both be right.
+A per-controller choice belongs in the host (#382 does it for Nintendo controllers).
The page shows the connected controller and what Auto picks for it.
## Artwork
The launcher shows, in this order: a custom image chosen under **Manage > Change
-artwork**; the game's eShop key art (1920×1080 from Nintendo's image CDN, found by
+artwork**, then the game's eShop key art (1920×1080 from Nintendo's image CDN, found by
title ID in the community title database
-[blawar/titledb](https://github.com/blawar/titledb)); a matching gameplay screenshot
-from the repository; the built app's icon. The title list (about 90 MB) is
+[blawar/titledb](https://github.com/blawar/titledb)), then a matching gameplay screenshot
+from the repository, and last the built app's icon. The title list (about 90 MB) is
downloaded only while a game in the collection has no key art yet, reduced to title
ID → image and kept with the images in
`~/Library/Application Support/NS Port Builder/artwork/`. Custom images stay at
@@ -168,13 +168,13 @@ their chosen path.
## Type
-The interface is set in Manrope (SIL Open Font License; `fonts/`, with its license):
+The interface is set in Manrope (SIL Open Font License, with its license in `fonts/`):
headings, text and a game's status line, whose capitals are the same face, tracked.
Paths and the build log use the system's monospaced face. `python3 fonts/embed_fonts.py`
writes the font into the binary as `Sources/NSPortBuilder/EmbeddedFonts.swift`, so the app needs no font
installed and no resource bundle beside the executable.
-The app icon is drawn by `make_icon.swift`; `./make_icon.sh` writes `icon.iconset/`
+The app icon is drawn by `make_icon.swift`, and `./make_icon.sh` writes `icon.iconset/`
and `AppIcon.icns` from it.
## App updates
@@ -185,12 +185,12 @@ the background and staged: the zip's SHA-256 must match the `digest` GitHub give
for the asset (a release without one is not installed automatically), and the app
inside must carry this app's bundle identifier, an executable and the release's
version. The staged copy replaces the app when you quit it, so the next launch is
-the new version; **Restart now** in Settings and in the library's bottom line
+the new version. **Restart now** in Settings and in the library's bottom line
installs it at once. Neither runs while a build does: the swap ends with a relaunch,
which would end the build's process group. If you quit during a build, the build is
stopped as before and the update waits for a later quit. With the switch off,
**Update to vX** in Settings downloads, verifies and relaunches as before (a
-release without a digest is still accepted there; a wrong digest never is).
+release without a digest is still accepted there, but a wrong digest never is).
A launcher built from this repository never replaces itself: `swift run` (no
bundle), a bundle under `.build/` or `DerivedData/`, a bundle beside
@@ -204,7 +204,7 @@ cd frontend
swift run
```
-or double-click `nxnative.app` in this folder (ad-hoc signed; rebuild it with `swift build -c release`
+or double-click `nxnative.app` in this folder (ad-hoc signed, and rebuild it with `swift build -c release`
and copy the binary into `Contents/MacOS/`). The app's settings and library stay under the folder name it
had before the rename, `~/Library/Application Support/NS Port Builder/`.
@@ -227,10 +227,10 @@ The release app (`NX2Apple.app`) carries `zstd`, `glslangValidator`, `spirv-cros
`Contents/Resources/tools/bin`) and a relocatable CPython 3.13 with `lz4 capstone fonttools
backports.zstd nsz` (`Contents/Resources/python`), so a player needs no Homebrew and no Python.
`tools/bundle_tools.sh` fills them in during the release workflow (pinned versions and sha256 of the
-sources, built for macOS 13 with static libraries; the Python packages come from
+sources, built for macOS 13 with static libraries, and the Python packages come from
`tools/bundled-python-requirements.txt`) and `tools/check_bundle.sh` runs each tool from the bundle
with a clean PATH. The dependency check (`BundledTools.swift`) prefers them to Homebrew's and shows
-"bundled"; the build's PATH starts with them. Under `swift run`, or in a build without the bundle,
+"bundled", and the build's PATH starts with them. Under `swift run`, or in a build without the bundle,
nothing changes: Homebrew's tools, a system Python or the launcher's venv. To try the bundle by hand:
`tools/bundle_tools.sh <folder> <work folder>`, then `tools/check_bundle.sh <folder>`.
@@ -238,8 +238,8 @@ nothing changes: Homebrew's tools, a system Python or the launcher's venv. To tr
The interface follows the system language at every launch: any Chinese variant
(Simplified, Traditional, Hong Kong, Taiwan) gets Chinese, every other language gets
-English; the app has no language switch. Strings live in
-`Sources/NSPortBuilder/Localization.swift`; regenerate the Qt table after editing
+English, and the app has no language switch. Strings live in
+`Sources/NSPortBuilder/Localization.swift`. Regenerate the Qt table after editing
it with `python3 frontend-qt/gen_localization.py` from the repository root.
## Verification
diff --git a/frontend/Sources/NSPortBuilder/Diagnostics.swift b/frontend/Sources/NSPortBuilder/Diagnostics.swift
index 0f701037..40d44cc6 100644
--- a/frontend/Sources/NSPortBuilder/Diagnostics.swift
+++ b/frontend/Sources/NSPortBuilder/Diagnostics.swift
@@ -43,7 +43,7 @@ struct Diagnostics {
if let commit = i.commit {
var line = "- Commit: \(commit)" + (i.branch.map { " (branch \($0))" } ?? "")
if !i.behind.isEmpty {
- line += "; " + i.behind.map { "\($0.count) behind \($0.ref)" }.joined(separator: ", ")
+ line += ", " + i.behind.map { "\($0.count) behind \($0.ref)" }.joined(separator: ", ")
if let fetched = i.lastFetch { line += " as of the last fetch, " + stamp(fetched) }
}
out.append(line)
diff --git a/frontend/Sources/NSPortBuilder/Localization.swift b/frontend/Sources/NSPortBuilder/Localization.swift
index c7fe38f4..1f1f7954 100644
--- a/frontend/Sources/NSPortBuilder/Localization.swift
+++ b/frontend/Sources/NSPortBuilder/Localization.swift
@@ -160,7 +160,7 @@ enum L10n {
"dev.teamNoCert": ("这个团队还没有开发证书:第一次安装时 Xcode 会自动创建(Mac 需要联网)。",
"This team has no development certificate yet: Xcode creates it at the first install (the Mac needs to be online)."),
"dev.personalTeam": ("个人团队", "Personal team"),
- "dev.note": ("Xcode 会为这台设备签名并直接安装,游戏数据(romfs.img)复制到 App 的“文稿”中,与侧载相同;第一次复制大型游戏需要几分钟。第一次需要在设备上开启开发者模式,并信任开发者(设置 → 通用 → VPN 与设备管理)。", "Xcode signs the game for this device and installs it there, then copies the game data (romfs.img) into the app’s Documents, as for sideloading; the first copy of a large game takes a few minutes. The first time, turn on Developer Mode on the device and trust the developer (Settings → General → VPN & Device Management)."),
+ "dev.note": ("Xcode 会为这台设备签名并直接安装,游戏数据(romfs.img)复制到 App 的“文稿”中,与侧载相同。第一次复制大型游戏需要几分钟。第一次需要在设备上开启开发者模式,并信任开发者(设置 → 通用 → VPN 与设备管理)。", "Xcode signs the game for this device and installs it there, then copies the game data (romfs.img) into the app’s Documents, as for sideloading. The first copy of a large game takes a few minutes. The first time, turn on Developer Mode on the device and trust the developer (Settings → General → VPN & Device Management)."),
// ---- Saves: a game's save copied between this Mac and the device it is installed on (SaveTransfer.swift) ----
"saves.menu": ("存档…", "Saves…"),
"saves.title": ("存档", "Saves"),
@@ -196,7 +196,7 @@ enum L10n {
"dev.askTransferText": ("Mac 通过 USB 线向 iPhone 传输的速度有限(约 25–70 MB/s,视线缆和设备而定),大游戏需要较长时间。如果游戏文件在高速存储设备上(USB3 移动硬盘、读卡器),把它直接连到 iPhone,在游戏启动器的“选择游戏数据”里选取会更快。", "USB transfer from the Mac is limited (about 25–70 MB/s, depending on cable and device), so a large game takes a while. If the game files are on fast external storage (a USB 3 drive or card reader), connecting it to the iPhone and picking it under “Choose game data” in the launcher is faster."),
"dev.transferNow": ("传输", "Transfer"),
"dev.transferSkip": ("暂不传输", "Not now"),
- "dev.copySkipped": ("已安装到 %@;游戏文件未传输", "Installed on %@; the game files were not transferred"),
+ "dev.copySkipped": ("已安装到 %@,游戏文件未传输", "Installed on %@, but the game files were not transferred"),
"dev.gameData": ("游戏数据(romfs.img)", "Game data (romfs.img)"),
"dev.installed": ("\u{5df2}\u{5b89}\u{88c5}\u{5230} %@", "Installed on %@"),
"dev.installedNote": ("\u{6e38}\u{620f}\u{5df2}\u{5728}\u{8bbe}\u{5907}\u{4e0a}\u{ff0c}\u{53ef}\u{4ee5}\u{76f4}\u{63a5}\u{6253}\u{5f00}\u{3002}", "The game is on the device, ready to open."),
@@ -343,13 +343,13 @@ enum L10n {
"repo.manualHint": ("网络不顺也可以手动:打开", "Flaky network? Do it by hand: open"),
"repo.manualHint2": ("→ 点绿色 Code 按钮 → Download ZIP,解压后点「选择仓库…」选中解压出的文件夹",
"→ the green Code button → Download ZIP, unzip, then pick the unzipped folder with Choose repository…"),
- "repo.noGit": ("这是 ZIP 下载的副本(无 git 历史),构建不受影响;点「接入 git」转为可更新",
- "This is a ZIP copy (no git history); builds work fine — Make updatable connects it to git"),
+ "repo.noGit": ("这是 ZIP 下载的副本(无 git 历史),构建不受影响,点「接入 git」转为可更新",
+ "This is a ZIP copy (no git history), and builds work fine. Make updatable connects it to git"),
"repo.adopt": ("接入 git(可更新)", "Make updatable (git)"),
"repo.adopting": ("正在接入 git…", "Connecting git…"),
- "repo.adopted": ("已接入 git,可以更新了;原来的文件保存在分支 %@", "Connected — updates work now. Your previous files are kept on branch %@"),
+ "repo.adopted": ("已接入 git,可以更新了,原来的文件保存在分支 %@", "Connected — updates work now. Your previous files are kept on branch %@"),
"repo.adoptFail": ("接入失败——详情见日志", "Connect failed — see the log"),
- "repo.adoptedAuto": ("打开时已接入 git 并更新到最新版本;原来的文件保存在分支 %@", "Connected to git and updated when the app opened. Your previous files are kept on branch %@"),
+ "repo.adoptedAuto": ("打开时已接入 git 并更新到最新版本,原来的文件保存在分支 %@", "Connected to git and updated when the app opened. Your previous files are kept on branch %@"),
"repo.adoptFailAuto": ("打开时未能接入 git(网络不通?详情见日志)——点「接入 git」重试",
"Could not connect to git when the app opened (offline? see the log) — try Make updatable"),
"repo.zipWaits": ("构建运行中,暂不接入 git——构建结束后重启 App 或点「接入 git」",
@@ -378,23 +378,23 @@ enum L10n {
"app.digestMismatch": ("%@ 的下载与校验值不符,已丢弃", "The download of %@ did not match its checksum and was discarded"),
"app.unpackFail": ("%@ 的下载无法解压,已丢弃", "The download of %@ could not be unpacked and was discarded"),
"app.notOurApp": ("%@ 的下载不是 NX2Apple,已丢弃", "The download of %@ is not an NX2Apple app and was discarded"),
- "app.needsNewerMacOS": ("NX2Apple %@ 需要 macOS %@,这台 Mac 是 %@。没有安装,继续使用当前版本", "NX2Apple %@ needs macOS %@ and this Mac has %@. It was not installed; you keep the current version"),
+ "app.needsNewerMacOS": ("NX2Apple %@ 需要 macOS %@,这台 Mac 是 %@。没有安装,继续使用当前版本", "NX2Apple %@ needs macOS %@ and this Mac has %@. It was not installed, so you keep the current version"),
"app.devBuild": ("%@ 已发布。这个启动器是从仓库构建的,不会替换自己", "%@ is out. This launcher was built from the repository and does not replace itself"),
"app.readOnly": ("%@ 已发布,但 App 无法在当前位置替换自己——请把它移到「应用程序」文件夹", "%@ is out, but the app cannot replace itself where it is — move it to Applications"),
"app.auto": ("自动安装更新", "Install updates automatically"),
- "app.autoNote": ("在后台下载并校验,退出 App 时安装;构建进行中绝不安装", "Downloaded and verified in the background, installed when you quit; never during a build"),
+ "app.autoNote": ("在后台下载并校验,退出 App 时安装,构建进行中绝不安装", "Downloaded and verified in the background, installed when you quit and never during a build"),
"app.autoDev": ("从仓库构建的启动器不会自动更新", "Not for a launcher built from the repository"),
"app.autoReadOnly": ("App 所在的文件夹不可写,无法自动更新", "The app's folder is not writable, so it cannot update itself"),
"library.appReady": ("NX2Apple %@ 已就绪", "NX2Apple %@ is ready"),
"update.title": ("有新版本可用", "A new version is out"),
"update.fromTo": ("当前 %@ → 新版本 %@", "You have %@ — the new version is %@"),
- "update.noNotes": ("这一版没有写更新说明,可以打开发布页查看。", "This release has no notes; open the release page to see it."),
+ "update.noNotes": ("这一版没有写更新说明,可以打开发布页查看。", "This release has no notes. Open the release page to see them."),
"update.now": ("现在更新", "Update now"),
"update.later": ("稍后", "Later"),
"update.openPage": ("打开发布页", "Open the release page"),
"app.installing": ("正在安装…(旧版本会进废纸篓)", "Installing… (the old version goes to the Trash)"),
"app.relaunching": ("已更新到 %@,正在重启 App…", "Updated to %@ — restarting…"),
- "app.installFail": ("安装失败:%@——新版本已下载,可手动替换", "Install failed: %@ — the new version was downloaded; replace by hand"),
+ "app.installFail": ("安装失败:%@——新版本已下载,可手动替换", "Install failed: %@ — the new version was downloaded, so replace it by hand"),
"app.netFail": ("网络失败(GitHub 不通?稍后再试)", "Network failed (GitHub unreachable? try again later)"),
"repo.destBusy": ("%@ 已存在且不是本项目——换个位置,或点「选择仓库…」",
"%@ already exists and is not this project — use another place, or Choose repository…"),
@@ -472,7 +472,7 @@ enum L10n {
"opt.bc": ("兼容老设备(A15 / A16 及更早)", "Older devices (A15 / A16 and earlier)"),
"opt.bc.note": ("在不支持 BC 纹理压缩的 GPU 上于 CPU 解压:iPhone 13 及更早、A16 的 iPad。新设备请保持关闭——GPU 路径更快",
"Decode BC textures on the CPU for GPUs without BC support: iPhone 13 and earlier, A16 iPads. Leave off on newer devices — the GPU path is faster"),
- "opt.macNoBc": ("Mac App 用这台 Mac 的 GPU,不需要兼容选项", "A Mac app uses this Mac's GPU; no compatibility option needed"),
+ "opt.macNoBc": ("Mac App 用这台 Mac 的 GPU,不需要兼容选项", "A Mac app uses this Mac's GPU, so no compatibility option is needed"),
"msg.bcOn": ("兼容老设备:BC 纹理将在 CPU 上解压", "Older-device mode: BC textures will be decoded on the CPU"),
"msg.bcEnvFailed": ("无法写入环境文件:%@——继续构建,但兼容模式未启用",
"Could not write the environment file: %@ — building without the compatibility mode"),
@@ -529,7 +529,7 @@ enum L10n {
"dep.tool.spirv-cross": ("spirv-cross", "spirv-cross"),
"dep.tool.glslangValidator": ("glslangValidator", "glslangValidator"),
"dep.glslang": ("brew: glslang", "brew: glslang"),
- "dep.glslang.hint": ("编译 OpenGL 游戏的着色器;打包脚本的环境检查要求它", "compiles OpenGL games' shaders; the NSP script's environment check requires it"),
+ "dep.glslang.hint": ("编译 OpenGL 游戏的着色器,打包脚本的环境检查要求它", "compiles OpenGL games' shaders, and the NSP script's environment check requires it"),
"dep.installTimeout": ("安装超时(30 分钟)——网络太慢或卡住了",
"Install timed out (30 minutes) — the network is slow or stuck"),
"dep.installAll": ("一键安装全部缺失项", "Install all missing"),
@@ -561,7 +561,7 @@ enum L10n {
"dep.zstd": ("brew: zstd", "brew: zstd"),
"dep.spirv.win": ("spirv-cross", "spirv-cross"),
"dep.spirv.hint.win": ("仅 OpenGL 游戏(如 Balatro、Digimon)需要,Metal 游戏用不到。装 <a href=\"https://vulkan.lunarg.com/sdk/home\">Vulkan SDK</a> 即可,本程序会自动在 %VULKAN_SDK%\\Bin 和 C:\\VulkanSDK\\<版本>\\Bin 里找到它,不用改任何配置",
- "only OpenGL games (Balatro, Digimon) need it; Metal games never do. Install the <a href=\"https://vulkan.lunarg.com/sdk/home\">Vulkan SDK</a> and this app finds it in %VULKAN_SDK%\\Bin or C:\\VulkanSDK\\<version>\\Bin by itself — no configuration"),
+ "only OpenGL games (Balatro, Digimon) need it, and Metal games never do. Install the <a href=\"https://vulkan.lunarg.com/sdk/home\">Vulkan SDK</a> and this app finds it in %VULKAN_SDK%\\Bin or C:\\VulkanSDK\\<version>\\Bin by itself — no configuration"),
"dep.zstd.win": ("zstd", "zstd"),
"dep.zstd.hint.win": ("解压——点「安装」由 App 下载(facebook/zstd 官方 Windows 版)", "decompression — press Install and the app fetches it (facebook/zstd's official Windows build)"),
"dep.metal.hint.win": ("需要 <a href=\"https://developer.apple.com/download/all/\">Apple 开发者下载页</a> 的「Metal Developer Tools for Windows」(需 Apple ID)",
@@ -591,16 +591,16 @@ enum L10n {
"dep.python.missing": ("%@ 缺包", "%@ is missing packages"),
"dep.install.begin": ("开始安装 %@…", "Installing %@…"),
"dep.install.fail": ("安装失败:%@(详情见日志)", "Install failed: %@ (see the log)"),
- "dep.python.old": ("Python %@ 太旧(需要 %@ 或更新);这个解释器没有构建需要的包",
- "Python %@ is too old (need %@ or newer); it lacks the packages the build needs"),
- "dep.python.notFound": ("没找到 Python %@ 或更新版本;先装一个(brew install python@%@),再点「重新检测」",
- "No Python %@ or newer found; install one (brew install python@%@), then press Check again"),
+ "dep.python.old": ("Python %@ 太旧(需要 %@ 或更新),这个解释器没有构建需要的包",
+ "Python %@ is too old (need %@ or newer), and it lacks the packages the build needs"),
+ "dep.python.notFound": ("没找到 Python %@ 或更新版本,先装一个(brew install python@%@),再点「重新检测」",
+ "No Python %@ or newer found. Install one (brew install python@%@), then press Check again"),
"dep.python.none": ("没找到可用的 Python(%@ 不行)——点右侧「安装」,App 会下载 3.12 并静默装到自己的目录",
"No usable Python found (%@ will not run) — press Install and the app fetches 3.12 into its own folder"),
- "msg.workdirHint": ("提示:「输出目录」同时是构建缓存的位置(输出目录/<ID>_build)。已有构建资源时,把它选回上次的同一位置即可复用(解包、shader 不重跑);换新位置会从头再来。",
- "Tip: the output folder is also where the build cache lives (<output>/<ID>_build). To reuse an existing build, point it back at the same folder; a new folder starts over."),
+ "msg.workdirHint": ("提示:「输出目录」同时是构建缓存的位置(输出目录/<ID>_build)。已有构建资源时,把它选回上次的同一位置即可复用(解包、shader 不重跑),换新位置会从头再来。",
+ "Tip: the output folder is also where the build cache lives (<output>/<ID>_build). To reuse an existing build, point it back at the same folder, since a new folder starts over."),
"msg.chainChanged": ("上游代码更新了 shader 翻译链,之前构建的 shader 库无法复用——本次构建用新翻译器重建(每个版本一次,之后的构建恢复复用)。",
- "An upstream update changed the shader translator, so previously built shader libraries cannot be reused — this build rebuilds them with the new one (once per update; later builds reuse as before)."),
+ "An upstream update changed the shader translator, so previously built shader libraries cannot be reused, so this build rebuilds them with the new one (once per update, and later builds reuse as before)."),
"dep.python.downloading": ("正在下载并安装 Python 3.12…(约 26 MB,装到 App 自己的目录)",
"Downloading and installing Python 3.12… (about 26 MB, into the app's own folder)"),
"dep.python.done": ("Python 已安装:%@", "Python installed: %@"),
diff --git a/frontend/Tests/NSPortBuilderTests/DiagnosticsTests.swift b/frontend/Tests/NSPortBuilderTests/DiagnosticsTests.swift
index 787bd3ed..782fae3c 100644
--- a/frontend/Tests/NSPortBuilderTests/DiagnosticsTests.swift
+++ b/frontend/Tests/NSPortBuilderTests/DiagnosticsTests.swift
@@ -32,7 +32,7 @@ final class DiagnosticsTests: XCTestCase {
"- macOS: Version 26.1 (Build 25B78)",
"- Chip: Apple M3 Pro",
"- Repository: ~/repos/NX2Apple",
- "- Commit: d66e4ddd CI: the legacy zip names are hyphenated (branch main); 3 behind upstream/main, 0 behind origin/main as of the last fetch, 2026-10-27 09:05",
+ "- Commit: d66e4ddd CI: the legacy zip names are hyphenated (branch main), 3 behind upstream/main, 0 behind origin/main as of the last fetch, 2026-10-27 09:05",
"- Python: ~/Library/Application Support/NS Port Builder/venv/bin/python3 (3.13.1, the launcher's venv)",
"- .NET: ~/.dotnet/dotnet (10.0.100)",
"- Dependencies: 1 missing",
diff --git a/patches/0015-fork-docs.patch b/patches/0015-fork-docs.patch
index dd806ffd..df2370a2 100644
--- a/patches/0015-fork-docs.patch
+++ b/patches/0015-fork-docs.patch
@@ -19,8 +19,8 @@ Issue: LNPANDY/NX2Apple#123
docs/badges/verified.json | 6 +
docs/launcher-c-design.md | 339 ++++++++++++++++++++++++++++++++++++
docs/launcher-c-plan.md | 213 ++++++++++++++++++++++
- docs/probe-dlopen.md | 34 ++++
- 11 files changed, 1247 insertions(+)
+ docs/probe-dlopen.md | 64 +++++--
+ 11 files changed, 1262 insertions(+), 15 deletions(-)
create mode 100644 dm/ios/ENTITLEMENTS.md
create mode 100644 docs/MULTIPLAYER.md
create mode 100644 docs/RELEASE-NOTES-GUIDE.md
@@ -34,7 +34,7 @@ Issue: LNPANDY/NX2Apple#123
diff --git a/dm/ios/ENTITLEMENTS.md b/dm/ios/ENTITLEMENTS.md
new file mode 100644
-index 00000000..de284eb2
+index 00000000..5808b59e
--- /dev/null
+++ b/dm/ios/ENTITLEMENTS.md
@@ -0,0 +1,100 @@
@@ -56,7 +56,7 @@ index 00000000..de284eb2
+| Game | Peak resident | Headroom | Result |
+|---|---|---|---|
+| Tears of the Kingdom | 3,342 MB | 33 MB | killed entering the world map |
-+| Hades II | — | — | asks for a 3.10 GB heap; at the budget limit |
++| Hades II | — | — | asks for a 3.10 GB heap, which is at the budget limit |
+
+Lowering the render scale to 0.5 did not change the Tears of the Kingdom outcome, so the limit is
+the guest heap rather than the GPU. The only way past it is a higher budget.
@@ -81,7 +81,7 @@ index 00000000..de284eb2
+| Impactor (from a computer) | Yes |
+| Xcode with a Personal Team | Yes |
+| SideStore 0.7.0, free Apple ID | Not by default — see below |
-+| Sideloadly and others | Check the tool; Sideloadly does not enable it |
++| Sideloadly and others | Check the tool. Sideloadly does not enable it |
+
+## SideStore with a free Apple ID
+
@@ -91,8 +91,8 @@ index 00000000..de284eb2
+2. Sideload **GetMoreRam** and sign in with the same Apple ID SideStore uses.
+3. In GetMoreRam open **App IDs**, tap **Refresh**, select this app's App ID, then
+ **Add Increased Memory Limit**.
-+4. Reinstall the app from SideStore (it upgrades in place; `Documents/` — the RomFS archive and the
-+ saves — is preserved).
++4. Reinstall the app from SideStore (it upgrades in place, and `Documents/`, the RomFS archive and the
++ saves, is preserved).
+5. Confirm: `Documents/log.txt` should now show a much larger `headroom to the system memory limit`
+ in the `memory up to frame N` lines. GetMoreRam uses one of a free Apple ID's three app slots, so
+ delete it afterwards if you need the slot back.
@@ -127,20 +127,20 @@ index 00000000..de284eb2
+```
+
+Measured here (12 GB iPhone, AltStore Classic 2.3): before the placeholder signature the budget was
-+3,375 MB and Hades II died entering a larger scene; after it the game runs. If the budget stays at
++3,375 MB and Hades II died entering a larger scene. After it the game runs. If the budget stays at
+3,375 MB with a signed IPA, the remaining step is on the App ID — enable the capability with a tool
+like GetMoreRam (same Apple ID as the sideloader, App IDs → Refresh → select the app → Add
+Increased Memory Limit), then reinstall so the profile picks it up.
+
+## Xcode route
+
-+A project prepared with `--prepare-xcode` already carries the entitlement (`Gen/DmIOS.entitlements`);
-+with a Personal Team and a real device, build from there. That is the one route where the app is
++A project prepared with `--prepare-xcode` already carries the entitlement (`Gen/DmIOS.entitlements`).
++With a Personal Team and a real device, build from there. That is the one route where the app is
+signed at build time, so no re-signing step can drop the entitlement. The Mac launcher's
+**Install on** uses this route.
diff --git a/docs/MULTIPLAYER.md b/docs/MULTIPLAYER.md
new file mode 100644
-index 00000000..39558eb5
+index 00000000..f29c8188
--- /dev/null
+++ b/docs/MULTIPLAYER.md
@@ -0,0 +1,139 @@
@@ -190,7 +190,7 @@ index 00000000..39558eb5
+| `0x01` | IPv4 | both | a whole IP packet |
+| `0x02` | ping | client → server | 4 random bytes (echoed back) |
+| `0x03` | IPv4 fragment | both | 16-byte header + data (below) |
-+| `0x04` | auth | server → client | the server asks for a login; implementations without it log and continue |
++| `0x04` | auth | server → client | the server asks for a login, and implementations without it log and continue |
+| `0x10` | info | server → client | a UTF-8 message to show the player |
+
+The high bit (`type & 0x7F`) is masked off on receive, so `0x81` is accepted as IPv4.
@@ -210,7 +210,7 @@ index 00000000..39558eb5
+mismatched totals or MTUs, and concatenates parts in index order.
+
+**Client behaviour**: keepalive + ping every 10 s, consider the server lost after 30 s of
-+silence, reconnect every 5 s on failure. The client picks its virtual address itself; the server
++silence, reconnect every 5 s on failure. The client picks its virtual address itself, and the server
+maps it to the connection.
+
+A real Switch can join a lan-play server, which is the whole point: this is how Switch players
@@ -229,7 +229,7 @@ index 00000000..39558eb5
+Peer discovery without a router, using the platform's peer-to-peer mechanism (mush8 uses mDNS /
+DNS-SD to advertise and browse, `dnssd.rs`: `DNSServiceRegister` / `DNSServiceBrowse` /
+`DNSServiceResolve` / `DNSServiceGetAddrInfo`). Each player advertises a service and browses for
-+the others; the first contact becomes the transport.
++the others, and the first contact becomes the transport.
+
+## What the game needs above the transport
+
@@ -254,8 +254,8 @@ index 00000000..39558eb5
+|---|---|---|
+| 1. BSD sockets | `socket`/`bind`/`sendto`/`recvfrom`/`poll`/`select` over the virtual network, with the errno conventions the SDK expects | new `dm/host/hle_bsd.c` (replaces the offline stubs in `hle_offline.c`) |
+| 2. Virtual network | address/MASK/gateway, per-port socket registry, broadcast rules, receive queues, wake-on-packet for `poll` | new `dm/host/dm_vnet.c` |
-+| 3. Transports | lan-play framing + reassembly; LAN broadcast; wireless via mDNS | one file per transport |
-+| 4. `ldn` / `nifm` | make the game believe a session can exist; per-game payload mapping | `hle_ldn.c`, and per-game code |
++| 3. Transports | lan-play framing and reassembly, LAN broadcast, wireless via mDNS | one file per transport |
++| 4. `ldn` / `nifm` | make the game believe a session can exist, per-game payload mapping | `hle_ldn.c`, and per-game code |
+
+Layers 1–3 are game independent and reusable. Layer 4 is where a new title costs work again.
+
@@ -268,7 +268,7 @@ index 00000000..39558eb5
+- **Does our Metal host survive packet injection at frame rate?** Untested. The transport runs
+ on its own thread, but `poll` must wake a blocked guest thread promptly.
+- **iOS local network permission**: iOS 14+ shows a prompt and the entitlement
-+ `com.apple.developer.networking.multicast` may be needed for broadcast; a sideloaded unsigned
++ `com.apple.developer.networking.multicast` may be needed for broadcast. A sideloaded unsigned
+ IPA cannot carry it, which could make LAN mode impossible on iOS while lan-play (unicast UDP)
+ still works.
+- **Matching the game update to the Switch's**, per mush8's note — our profiles already pin an
@@ -282,7 +282,7 @@ index 00000000..39558eb5
+- [c22dev/mush8](https://github.com/c22dev/mush8) — `crates/nxhost/src/services/{vnet,lanplay,lan,wireless}.rs`,
+ `crates/nxhost/src/dnssd.rs` (read at commit 0.1).
+- lan-play itself is a public protocol with several open implementations (switch-lan-play and
-+ clients for it); the constant table above matches what mush8 implements.
++ clients for it), and the constant table above matches what mush8 implements.
diff --git a/docs/RELEASE-NOTES-GUIDE.md b/docs/RELEASE-NOTES-GUIDE.md
new file mode 100644
index 00000000..ba1f3323
@@ -396,7 +396,7 @@ index 00000000..ba1f3323
+into two lists.
diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
new file mode 100644
-index 00000000..c8adbaab
+index 00000000..2f1132cb
--- /dev/null
+++ b/docs/RELEASE_NOTES.md
@@ -0,0 +1,77 @@
@@ -413,27 +413,27 @@ index 00000000..c8adbaab
+- **Launch options live in the game's own store**: one string per setting (`launcher.<VAR>`) in the app's preferences domain, exactly where upstream's launcher reads them — Finder and Dock starts included. Only non-default values are kept, an earlier launcher's choices migrate once, and schema 1 is read properly: sub-settings appear only when their parent has the value (`needs`), sections the launcher has no name for draw after the known ones in list order, and range limits come from the row. A newer schema is read as far as it can be and noted in the log, never refused.
+- **The library's Manage menu in the launcher's own style** — and a controller can open and drive it.
+- **Build tools update themselves**: a ZIP copy of an old release is connected to git by itself when the app opens (your own edits are preserved on a branch), and a build refuses to start when the tools are older than the app instead of failing at the last step.
-+- **Install with just an Apple ID**: signing teams come from Xcode's provisioning preferences (personal teams are labelled), merged with the certificates'. With no certificate at all, Xcode creates one at the first install (`-allowProvisioningUpdates`); the messages say so, and with neither an Apple ID nor a certificate they say exactly where to sign in.
-+- **The installer asks before copying game files**: USB from the Mac runs at about 25–70 MB/s, so the dialog offers transfer now or skip — the game installs either way, and the outcome card gains a "Game data (romfs.img)" row with Reveal in Finder for a manual copy (a fast external drive handed to the device is quicker; the launcher's Game data picker loads from it).
-+- **Issue forms**: game, build and launcher problems each ask for what a report needs (versions, device, Copy diagnostics, the game's log) and refuse to submit without it; a PR template and CONTRIBUTING.md set the same rules for tools.
++- **Install with just an Apple ID**: signing teams come from Xcode's provisioning preferences (personal teams are labelled), merged with the certificates'. With no certificate at all, Xcode creates one at the first install (`-allowProvisioningUpdates`). The messages say so, and with neither an Apple ID nor a certificate they say exactly where to sign in.
++- **The installer asks before copying game files**: USB from the Mac runs at about 25–70 MB/s, so the dialog offers transfer now or skip — the game installs either way, and the outcome card gains a "Game data (romfs.img)" row with Reveal in Finder for a manual copy (a fast external drive handed to the device is quicker, and the launcher's Game data picker loads from it).
++- **Issue forms**: game, build and launcher problems each ask for what a report needs (versions, device, Copy diagnostics, the game's log) and refuse to submit without it. A PR template and CONTRIBUTING.md set the same rules for tools.
+
+## Fixes
+
+- **iPhone: choosing game data sticks.** The bookmark is written while the Files app's security scope is held (one written without it resolves to nothing from the next launch on — every pick read as "the app was signed differently"), saved only after a round-trip resolves, and a stale-but-readable bookmark rewrites itself instead of making you pick again. The resolved scope stays held for the session, since the game reads the image the whole time.
+- **iPhone: no game data is no dead end.** A fresh install with nothing in Documents and no pick ever made boots into the launcher (the old build stopped on a static "Game files not found" page that never mentioned the picker), and Play (re)locates the data first — a pick made this session applies at once, with save/temp following the final location. An app without a launcher falls back to the static hint.
-+- **iPhone: the signing retry keeps its stage row.** The team-variant retry appended a second "Sign for …" row with the same id that no update ever reached; it spun for ever after the build moved on. A retried stage now reuses its row.
++- **iPhone: the signing retry keeps its stage row.** The team-variant retry appended a second "Sign for …" row with the same id that no update ever reached, so it spun for ever after the build moved on. A retried stage now reuses its row.
+- **Mac: every extracted game version is kept as the build resource it is.** The versions a profile's shader tables were made from are inputs to the shader split on every build, so deleting the packed version's siblings traded a full re-extraction of the base game for disk space — the wrong trade, and it is undone.
-+- **Sync: the next upstream sync runs.** Upstream's latest commits stopped the sync and would have silently lost fork code; every patcher is now tested against real upstream in CI, a `--check-protection` run lists any hand-edited file no table covers, and files the fork owns outright are registered so a sync cannot revert them.
++- **Sync: the next upstream sync runs.** Upstream's latest commits stopped the sync and would have silently lost fork code. Every patcher is now tested against real upstream in CI, a `--check-protection` run lists any hand-edited file no table covers, and files the fork owns outright are registered so a sync cannot revert them.
+
+## Known issues
+
-+- **Mods have not been played with a real mod yet**: the layouts and the environment string are verified; the actual overlay is not.
++- **Mods have not been played with a real mod yet**: the layouts and the environment string are verified, but the actual overlay is not.
+- **Windows**: not provided on this page — the front end is verified on real hardware, the full build pipeline is not. The Actions artifact `NS-Port-Builder-qt-windows-x64` has the current front end.
+
+## Install
+
+- **macOS**: download `NX2Apple-macOS-arm64.zip`, unzip, then right-click → Open on first launch. In-app updates work from 0.4.9 on under the NX2Apple name (older versions: download this one by hand).
-+- **Windows**: not provided on this page; the Actions artifact has the Qt front end.
++- **Windows**: not provided on this page, but the Actions artifact has the Qt front end.
+
+## Credits
+
@@ -448,20 +448,20 @@ index 00000000..c8adbaab
+
+## 新增
+
-+- **启动选项存进游戏自己的存储**:每个设置一条字符串(`launcher.<VAR>`),写在 App 的偏好域里——正是上游启动器读取的位置,Finder 和 Dock 启动同样生效。只保留非默认值,旧启动器的选择一次性迁移;schema 1 完整支持:父项有值才显示子项(`needs`)、启动器不认识的分组按列表顺序排在已知分组之后、范围上下限来自条目本身。更新版的 schema 能读多少读多少并写进日志,绝不拒绝。
++- **启动选项存进游戏自己的存储**:每个设置一条字符串(`launcher.<VAR>`),写在 App 的偏好域里——正是上游启动器读取的位置,Finder 和 Dock 启动同样生效。只保留非默认值,旧启动器的选择一次性迁移。schema 1 完整支持:父项有值才显示子项(`needs`)、启动器不认识的分组按列表顺序排在已知分组之后、范围上下限来自条目本身。更新版的 schema 能读多少读多少并写进日志,绝不拒绝。
+- **游戏库的 Manage 菜单换成启动器同款风格**——并且可以用手柄打开和操作。
-+- **构建工具自己更新**:旧版 ZIP 拷贝在 App 打开时自动接上 git(你自己的修改保留在分支上);工具比 App 旧时直接拒绝开始构建,而不是到最后一步才失败。
-+- **只凭 Apple ID 就能安装**:签名团队从 Xcode 的开发者偏好里读取(个人团队会标注),与证书里的合并。一个证书都没有时,Xcode 在第一次安装时自动创建(`-allowProvisioningUpdates`);提示语会说明这一点,既没有 Apple ID 也没有证书时,会告诉你确切该去哪里登录。
-+- **安装器在拷贝游戏文件前先询问**:Mac 经 USB 向 iPhone 只有约 25–70 MB/s,弹窗提供"现在传输"或"暂不传输"——两种选择游戏都会装上;结果卡片新增"游戏数据(romfs.img)"一行,带"在访达中显示",方便手动拷贝(把高速外接盘直接连 iPhone 更快,启动器的"选择游戏数据"可以从那里加载)。
-+- **Issue 表单**:游戏/构建/启动器三类问题各自要求报告所需的信息(版本、设备、Copy 诊断、游戏日志),缺了就提交不了;PR 模板和 CONTRIBUTING.md 给工具立了同样的规矩。
++- **构建工具自己更新**:旧版 ZIP 拷贝在 App 打开时自动接上 git(你自己的修改保留在分支上),工具比 App 旧时直接拒绝开始构建,而不是到最后一步才失败。
++- **只凭 Apple ID 就能安装**:签名团队从 Xcode 的开发者偏好里读取(个人团队会标注),与证书里的合并。一个证书都没有时,Xcode 在第一次安装时自动创建(`-allowProvisioningUpdates`),提示语会说明这一点,既没有 Apple ID 也没有证书时,会告诉你确切该去哪里登录。
++- **安装器在拷贝游戏文件前先询问**:Mac 经 USB 向 iPhone 只有约 25–70 MB/s,弹窗提供"现在传输"或"暂不传输"——两种选择游戏都会装上,结果卡片新增"游戏数据(romfs.img)"一行,带"在访达中显示",方便手动拷贝(把高速外接盘直接连 iPhone 更快,启动器的"选择游戏数据"可以从那里加载)。
++- **Issue 表单**:游戏/构建/启动器三类问题各自要求报告所需的信息(版本、设备、Copy 诊断、游戏日志),缺了就提交不了。PR 模板和 CONTRIBUTING.md 给工具立了同样的规矩。
+
+## 修复
+
+- **iPhone:选择游戏数据终于能记住。** 书签在 Files App 的安全作用域被持有期间写入(不持作用域写出的书签从下次启动起就解析不了——于是每次选择都报"签名不同"),保存前先验证能读回,能解析但过期的书签自动重写而不必重选。解析出的作用域在整个会话期间持有,因为游戏全程都在读镜像。
-+- **iPhone:没有游戏数据不再是死路。** 全新安装、Documents 里没有数据、也从没选过路径时,App 会正常进启动器(旧版停在一句静态的"Game files not found"上,绝口不提选择器);按 Play 时先重新定位数据——本次会话的选择立即生效,存档/临时目录跟着最终位置走。没有启动器的极简包才回退到静态提示。
++- **iPhone:没有游戏数据不再是死路。** 全新安装、Documents 里没有数据、也从没选过路径时,App 会正常进启动器(旧版停在一句静态的"Game files not found"上,绝口不提选择器),按 Play 时先重新定位数据——本次会话的选择立即生效,存档/临时目录跟着最终位置走。没有启动器的极简包才回退到静态提示。
+- **iPhone:签名重试复用同一行。** 团队变体重试会追加一行同 ID 的"为 … 签名",而所有更新都只打到第一行——构建都走完了它还在转圈。重试的步骤现在复用自己的行。
+- **Mac:每个解包版本都作为构建资源保留。** 游戏 shader 表登记的来源版本是每次构建 shader split 的输入,删掉打包版本之外的版本,等于拿整份基础版重解去换磁盘空间——这笔账不划算,已撤销。
-+- **同步:下一次上游同步能跑通了。** 上游最新提交会让同步中断并悄悄丢掉 fork 代码;现在每个补丁器都在 CI 里对着真实上游测试,`--check-protection` 会列出任何没被登记的手改文件,fork 完全 own 的文件也已登记、同步不会回退它们。
++- **同步:下一次上游同步能跑通了。** 上游最新提交会让同步中断并悄悄丢掉 fork 代码。现在每个补丁器都在 CI 里对着真实上游测试,`--check-protection` 会列出任何没被登记的手改文件,fork 完全 own 的文件也已登记、同步不会回退它们。
+
+## 已知问题
+
@@ -471,7 +471,7 @@ index 00000000..c8adbaab
+## 安装
+
+- **macOS**:下载 `NX2Apple-macOS-arm64.zip`,解压后右键 → 打开(首次)。0.4.9 起 App 内更新在 NX2Apple 名下正常工作(更早的版本请这次手动下载)。
-+- **Windows**:本页不提供;Actions 产物里有 Qt 前端。
++- **Windows**:本页不提供,Actions 产物里有 Qt 前端。
+
+## 致谢
+
@@ -479,7 +479,7 @@ index 00000000..c8adbaab
+- **GabeThe21stGamer**:暴露了旧工具与无证书两条路径的报告(#87),以及免证书安装的免费 Apple ID 实测。
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
-index 00000000..69666591
+index 00000000..35472c99
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,140 @@
@@ -501,10 +501,10 @@ index 00000000..69666591
+stick and the other an injected value.
+
+Four details worth copying verbatim, because each is a bug that took them time:
-+- **float exact equality** to recognise the frame it wrote, not an epsilon window;
++- **float exact equality** to recognise the frame it wrote, not an epsilon window,
+- **thread-local** copies of the original value, because the camera and action threads both
-+ call the getter and would otherwise cross-pair;
-+- normalisation by the frame's VFR ratio, and zero output when the drag stops;
++ call the getter and would otherwise cross-pair,
++- normalisation by the frame's VFR ratio, and zero output when the drag stops, and
+- `touchpad_geometry.h`: one C header describing the whole virtual pad, used by both the UIKit
+ view and a **Mac mouse preview**, so the layout is tuned on a desk instead of on a phone.
+
@@ -515,7 +515,7 @@ index 00000000..69666591
+| Piece | Effort | Note |
+|---|---|---|
+| `touchpad_geometry.h` + Mac `--touch-preview` | 3–5 days | Visible immediately, zero device time |
-+| Relative look (`hle_look.c`) | 1–2 weeks | Needs tests; the four details above are the spec |
++| Relative look (`hle_look.c`) | 1–2 weeks | Needs tests, and the four details above are the spec |
+| Native aspect (`hle_aspect.c`) | 3–5 days per game | Needs per-game projection offsets |
+| BOTW touch HUD (`hle_botw_touchhud.c`) | 3–5 days | Per-game only |
+
@@ -557,7 +557,7 @@ index 00000000..69666591
+ ~4 ms/frame). One data row, read once per second.
+
+We already read one table from three places (`dm/games/settings.tsv` → `Launcher.swift` →
-+`frontend-qt`); adding two columns keeps that structure.
++`frontend-qt`), and adding two columns keeps that structure.
+
+Also from that fork: `nvn_ambient.h` (227 lines, present stage only) — ambient letterbox that
+samples the frame's edges so a 16:9 game on a 4:3 iPad has a coloured surround instead of black.
@@ -572,8 +572,8 @@ index 00000000..69666591
+| | zenvyzenshiro/NXNativeWindows | xbunax/nxnative |
+|---|---|---|
+| Size | ~24 files (`win/` shim) | full FastAPI WebUI (720 KB, 98 files) |
-+| Approach | `xcrun.py` maps every `xcrun metal/metallib/clang`, `sips`, `plutil` to a Windows equivalent; `Launcher.m` replaces the SwiftUI launcher; `sdk/extract_xip.py` unpacks `iPhoneOS.sdk` | same idea plus its own staging/overlay/patch build system |
-+| Verified on | Windows 11, LLVM 23.1.4, Metal Tools 6.2, iPhoneOS 27.1 — **Balatro built, sideloaded, ran on an A16 iPad** | Hades II IPA produced; not verified on a device |
++| Approach | `xcrun.py` maps every `xcrun metal/metallib/clang`, `sips`, `plutil` to a Windows equivalent, `Launcher.m` replaces the SwiftUI launcher, and `sdk/extract_xip.py` unpacks `iPhoneOS.sdk` | same idea plus its own staging/overlay/patch build system |
++| Verified on | Windows 11, LLVM 23.1.4, Metal Tools 6.2, iPhoneOS 27.1 — **Balatro built, sideloaded, ran on an A16 iPad** | Hades II IPA produced, not verified on a device |
+| Fit for us | High — we already have two front ends | Low — it would be a third |
+
+Toolchain (pinned in both forks): LLVM-MinGW `20261020`, iPhoneOS SDK from
@@ -608,8 +608,8 @@ index 00000000..69666591
+| C. Shell app + per-game signed framework via `dlopen` | unbounded | large, unvalidated |
+
+**A already delivers what external storage needs** (romfs from an external folder, per-game
-+saves and logs) and enables the runtime-profile work that was already done. Do A first; B only
-+if 4–8 games in one app is worth it; C needs a `dlopen` experiment before any commitment.
++saves and logs) and enables the runtime-profile work that was already done. Do A first, B only
++if 4–8 games in one app is worth it, and C needs a `dlopen` experiment before any commitment.
+
+External storage on iOS: `UIDocumentPickerViewController` for the folder, persist a security-
+scoped bookmark in UserDefaults, store the ROMFSARC index and shards there. `romfs_arc.c`
@@ -625,7 +625,7 @@ index 00000000..69666591
+carrier).
diff --git a/docs/WORK-IN-PROGRESS.md b/docs/WORK-IN-PROGRESS.md
new file mode 100644
-index 00000000..5a11bdf8
+index 00000000..7364c2c8
--- /dev/null
+++ b/docs/WORK-IN-PROGRESS.md
@@ -0,0 +1,88 @@
@@ -685,18 +685,18 @@ index 00000000..5a11bdf8
+
+| # | Item | Effort | Why not started |
+|---|---|---|---|
-+| C1 | **Relative touch look** (`hle_look.c` idea) | 1–2 wks | touch-the-wild's version depends on per-game observation hooks and float-exact provenance; author says unstable. Layer 1 (geometry) is already in |
-+| C2 | **Native aspect ratio** (`hle_aspect.c` idea) | 3–5 d per game | Needs per-game projection offsets; layer 1 came first |
-+| C3 | **Atmosphère cheats** | 0 if upstream merges PR #268 | Waiting on upstream; falls back to ~1 wk of our own if it stalls |
-+| C4 | **Settings capability gating** (`requires` + `defaultAtFps` from AnySwitch) | 1–2 wks | Polish; needs `settings.tsv` schema change |
++| C1 | **Relative touch look** (`hle_look.c` idea) | 1–2 wks | touch-the-wild's version depends on per-game observation hooks and float-exact provenance, and the author says it is unstable. Layer 1 (geometry) is already in |
++| C2 | **Native aspect ratio** (`hle_aspect.c` idea) | 3–5 d per game | Needs per-game projection offsets, and layer 1 came first |
++| C3 | **Atmosphère cheats** | 0 if upstream merges PR #268 | Waiting on upstream, and falls back to ~1 wk of our own if it stalls |
++| C4 | **Settings capability gating** (`requires` + `defaultAtFps` from AnySwitch) | 1–2 wks | Polish, needs `settings.tsv` schema change |
+| C5 | **Universal launcher architecture B** (4–8 games per IPA) | 3–4 wks | Blocked on: NRO-style module packing for non-NRO modules (`loader.c map_image`), and on deciding whether 4–8 games is worth it |
-+| C6 | **Multiplayer (LAN / lan-play / wireless)** | 2–3 wks for one game | Protocol documented in `docs/MULTIPLAYER.md`; needs BSD socket layer + virtual network + per-game `ldn` mapping. Untested: iOS multicast entitlement on a sideloaded IPA |
-+| C7 | **Launcher architecture C** (`dlopen` per-game framework) | large | Feasibility experiment **passed** on a device (iOS 27.0.1, sideloaded: `dlopen` of a nested framework + `dlsym` + call, docs/probe-dlopen.md); next is one real game as a framework in a shell app |
++| C6 | **Multiplayer (LAN / lan-play / wireless)** | 2–3 wks for one game | Protocol documented in `docs/MULTIPLAYER.md`, and needs BSD socket layer + virtual network + per-game `ldn` mapping. Untested: iOS multicast entitlement on a sideloaded IPA |
++| C7 | **Launcher architecture C** (`dlopen` per-game framework) | large | Feasibility experiment **passed** on a device (iOS 27.0.1, sideloaded, `dlopen` of a nested framework + `dlsym` + call, see docs/probe-dlopen.md). Next is one real game as a framework in a shell app |
+| C8 | **Pikmin 4 / Yoshi / other fork profiles** | days each | Cherriable from forks once their PRs land upstream |
+
+## D. Blocked on upstream
+
-+- [ ] PR #268 Atmosphère cheats — watch for merge; our daily sync will bring it in.
++- [ ] PR #268 Atmosphère cheats — watch for merge, since our daily sync will bring it in.
+- [ ] seedds/nxnative#205 (we filed): ARM64 branch range on a 185 MB text. Without it,
+ EA Sports FC 27 and similar large titles cannot be rewritten.
+- [ ] Upstream PRs from forks worth cherry-picking: #218/#216 (Yoshi sparse textures, texraw),
@@ -706,15 +706,15 @@ index 00000000..5a11bdf8
+
+- [ ] The Qt front end has no reproducible "check for app updates" (the SwiftUI one has it).
+- [ ] Qt front end: per-stage percentage display (currently an indeterminate bar for the
-+ running stage; the SwiftUI app shows real percentages from the script's own output).
++ running stage, while the SwiftUI app shows real percentages from the script's own output).
+- [ ] `frontend-qt/README.md` says the Windows path is untested — update once section A passes.
-+- [ ] The games table in both READMEs is hand-inserted; `refresh_badges()` already counts the
++- [ ] The games table in both READMEs is hand-inserted, and `refresh_badges()` already counts the
+ folders, so the table could be generated too.
-+- [ ] `docs/ROADMAP.md` predates the BC/multiplayer findings; fold them in.
++- [ ] `docs/ROADMAP.md` predates the BC/multiplayer findings, so fold them in.
+
+## How to use this file
+
-+- Pick from A first if you are the one with the hardware; otherwise B.
++- Pick from A first if you are the one with the hardware, otherwise B.
+- C is a menu, not a queue: each entry names its own blocker.
+- Anything finished goes to the top table with its commit, so the list stays short.
diff --git a/docs/badges/games.json b/docs/badges/games.json
@@ -743,7 +743,7 @@ index 00000000..92b31479
+}
diff --git a/docs/launcher-c-design.md b/docs/launcher-c-design.md
new file mode 100644
-index 00000000..515d3eae
+index 00000000..bc814c7d
--- /dev/null
+++ b/docs/launcher-c-design.md
@@ -0,0 +1,339 @@
@@ -753,12 +753,12 @@ index 00000000..515d3eae
+`dm/host/hle_profile.{c,h}`(运行时 profile,已在 main,`3b36083`)。
+
+目标(用户原话):**"打开启动器就像打开了一台 Switch"**——一个壳 App,里面看到多个已构建的游戏,
-+点一个进入那个游戏。架构 A(进行中,WIP:41-47)交付按游戏隔离的数据布局;本文设计 C——壳 +
++点一个进入那个游戏。架构 A(进行中,WIP:41-47)交付按游戏隔离的数据布局。本文设计 C——壳 +
+每游戏 framework——把"多个游戏装进一个 App"的**代码**维度做对。
+
+本文回答六个问题:framework 边界、与架构 B 的真实差异(含 codesign 的诚实结论)、构建系统改造、
+运行时选择器、风险清单、工作量分解。每个结论都给证据(文件与行号,或外部来源)。
-+**一句话结论先放在这里:C 不能"不重签就加游戏"——iOS 只允许 dlopen 安装时已在签名 bundle 内的代码;
++**一句话结论先放在这里:C 不能"不重签就加游戏"——iOS 只允许 dlopen 安装时已在签名 bundle 内的代码,
+C 的真实价值是"每个游戏一个独立 Mach-O(各自的 255 section 预算、增量链接、坏一个不坏全局)",
+不是 unbounded。第 2 节有完整论证。**
+
@@ -776,7 +776,7 @@ index 00000000..515d3eae
+| `<game>` dylib:`__TEXT,__dm<mod>x0` / `__DM<mod>W,__img` / `__TEXT,__dm<mod>x1` 三段式聚合段 | `dm/ios/tools/gen_embed.py`(不改,同样的 embed.S 进一个 dylib target 而不是可执行文件) | 今天这些 section 在主可执行文件里(`loader.c:473-476`) |
+| `__DATA,__dm_nro_tab` + 三个共享 NRO 段(有 NRO 的游戏,如任天堂明星大乱斗 98 个) | `gen_embed.py`(不改) | `loader.c:485-492` |
+| `Info.plist`、`Resources/dm/`(`*.fixups.tsv`、`*.gates.tsv`、`nro.tsv`、shader 表) | `build_ipa.sh:75-81` 的复制清单原样搬进 framework | 今天在 App 的 `dm/` 资源目录(`project.yml` `Gen/dm` resources) |
-+| `Resources/profile.tsv`(运行时 game profile,可选;优先用 Documents 里的) | `dm/games/game.py profile <id> <out>`(`game.py:192-232`) | 今天靠 DM_PROFILE 环境变量指向 |
++| `Resources/profile.tsv`(运行时 game profile,可选,优先用 Documents 里的) | `dm/games/game.py profile <id> <out>`(`game.py:192-232`) | 今天靠 DM_PROFILE 环境变量指向 |
+
+framework 里**没有**宿主代码、没有 ObjC 类、没有入口函数——它对 dyld 是一个"加载后不被调用"的镜像,
+唯一用途是让它的段被签名映射进进程,然后 `vm_remap` 到 guest 布局。romfs / msl / save / pso 一概不进
@@ -784,11 +784,11 @@ index 00000000..515d3eae
+
+**方案 FH(备选):framework = 整个 dmhost + 该游戏的聚合段。** 入口
+`int dmgame_main(int argc, char **argv, const char *profile_path)`(= 现在的 `dm_main`,`main.m:11` 用
-+`-Dmain=dm_main` 编进宿主;framework 内同名导出),壳 dlopen 后 `dlsym(handle, "dmgame_main")` 调用。
++`-Dmain=dm_main` 编进宿主,framework 内同名导出),壳 dlopen 后 `dlsym(handle, "dmgame_main")` 调用。
+仅当 FR 的探针(第 5 节 R1)失败时退到 FH。FH 的代价:宿主对象码每个游戏重复一份(dm/host 的
-+.c/.m 源码合计约 11,265 行,头文件另计——重复是浪费但量级可接受);**更严重的是壳与 framework
++.c/.m 源码合计约 11,265 行,头文件另计——重复是浪费但量级可接受)。**更严重的是壳与 framework
+各持一份 ObjC 类**(`front_ios.m` 的 App/SceneDelegate、Metal NVN 层的类),同名类跨镜像重复注册
-+是 ObjC 运行时的已知雷区;除非"壳里不放宿主",但这又把窗口/Metal 生命周期切成两半。
++是 ObjC 运行时的已知雷区,除非"壳里不放宿主",但这又把窗口/Metal 生命周期切成两半。
+
+### 1.2 入口符号设计(两种方案统一写法)
+
@@ -830,11 +830,11 @@ index 00000000..515d3eae
+| 环境变量 | 现状(main.m 行号) | C 中的值 |
+|---|---|---|
+| `DM_ROMFS` | 87-90:`Documents/games/<DM_GAME_ID>/romfs` → `Documents/romfs` → `<App>/romfs` | `Documents/games/<选中 id>/romfs`,判定函数 `romfs_dir_ok`(19-28 行)原样复用 |
-+| `DM_SAVE` / `DM_TEMP` | 95-104:`game_dir_for`(36-39 行)的 per-game 布局,`romfs` 落在游戏目录内才启用 | 同上;**按游戏隔离已经存在**,壳只换 id |
-+| `DM_MSL_DIR` | 107-111:**已优先 per-game `<gdir>/msl`**,退到 bundle `<App>/msl` | 不改逻辑;shader 库放 `Documents/games/<id>/msl/`(数据,不进 framework,见 1.1) |
++| `DM_SAVE` / `DM_TEMP` | 95-104:`game_dir_for`(36-39 行)的 per-game 布局,`romfs` 落在游戏目录内才启用 | 同上,**按游戏隔离已经存在**,壳只换 id |
++| `DM_MSL_DIR` | 107-111:**已优先 per-game `<gdir>/msl`**,退到 bundle `<App>/msl` | 不改逻辑,shader 库放 `Documents/games/<id>/msl/`(数据,不进 framework,见 1.1) |
+| `DM_PSO_BUNDLE` | 115-116:只查 bundle `<App>/pso` | 壳扩展为先查 `Documents/games/<id>/pso`(pso 离线管线档案是数据,BotW 一档约 650 MB/架构,`build_ipa.sh:82-86`) |
+| `DM_NVN_SHMAP` | 105-106:bundle `<App>/dm/shader_map.tsv` | `<framework>/Resources/dm/shader_map.tsv` |
-+| `DM_PROFILE` | hle_profile.c:213-214 读取;iOS 侧今天没人设它 | `Documents/games/<id>/profile.tsv` 优先,退 framework 资源 |
++| `DM_PROFILE` | hle_profile.c:213-214 读取,iOS 侧今天没人设它 | `Documents/games/<id>/profile.tsv` 优先,退 framework 资源 |
+| `DM_LANG` / `DM_SHOW_FPS` | 84-86(Info.plist `DMLanguage`) | 壳 Info.plist 或 Documents/env.txt(69-80 行的 env 文件机制不动) |
+| 其余 `DM_*` 调试开关 | `main.c:42-46 flags_init` | Documents/env.txt,不变 |
+
@@ -857,7 +857,7 @@ index 00000000..515d3eae
+ 放 Data 容器不行。
+2. **实测复现**(johnno1962/InjectionNext issue #81,2025-08 起):同 TeamIdentifier 签名、合法
+ load commands、甚至 get-task-allow + Developer Mode 的 dylib,只要在 bundle 外(Data 容器),
-+ `dlopen` 报 `code signature invalid (errno=1)`;拷进 bundle 后立即成功。结论:AMFI 拒绝的是
++ `dlopen` 报 `code signature invalid (errno=1)`,拷进 bundle 后立即成功。结论:AMFI 拒绝的是
+ **代码所在的路径**,不是签名的对错。该 issue 还确认 dylib **不能携带自己的 entitlements**。
+3. **嵌入位置的官方要求**:TN2435(Embedding Frameworks In An App)与
+ developer.apple.com/documentation/bundleresources/placing-content-in-a-bundle——第三方 app 的动态
@@ -866,7 +866,7 @@ index 00000000..515d3eae
+
+**反例为什么不算数**:LiveContainer(github.com/LiveContainer/LiveContainer)确实做到了"装一次壳、
+之后随便加 app"。它的做法(读源码确认):guest 可执行文件放在数据容器里,靠
-+`dlopen` 直接加载(`LCBootstrap.m:570-583`);能这样做的条件是
++`dlopen` 直接加载(`LCBootstrap.m:570-583`),能这样做的条件是
+`"If JIT is enabled, bypass library validation so we can load arbitrary binaries"`(`LCBootstrap.m:367-371`)——
+即持有 JIT/动态代码签名资格时,在**自己进程内** hook dyld:`mmap` 被换成"把文件读进匿名内存再
+mprotect 成 exec"、`fcntl(F_ADDFILESIGS_RETURN)` 被改成谎报签名覆盖全文件
@@ -877,7 +877,7 @@ index 00000000..515d3eae
+guest"。我们的项目**不采用这条路**:JIT 资格(get-task-allow / 动态代码签名)在侧载调试场景技术上
+拿得到(DolphiniOS 等靠 JIT-enabler 应用按会话附加),但那要求用户每次会话先跑一个 enabler、且整个
+加载器建立在进程内 hook dyld 之上——LiveContainer 自己的代码就是"每次系统更新都可能断"的证词
-+(README 注明 "(Below iOS 26)",即 iOS 26 起该路径有变;`LCBootstrap.m:577-583` 为 iOS 27 另加
++(README 注明 "(Below iOS 26)",即 iOS 26 起该路径有变,`LCBootstrap.m:577-583` 为 iOS 27 另加
+`bypass_seg_count_check`)。我们只需要"映射已签名页",从来不需要"执行未签名代码",
+loader.c:473-476 的 vm_remap 路线不依赖任何特殊资格。**所以 LiveContainer 证明的恰恰是规则的坚硬,
+不是豁口:绕过它需要 JIT 资格 + dyld hook,二者我们都不具备也不想要。**
@@ -892,7 +892,7 @@ index 00000000..515d3eae
+因此 ROADMAP 第 123 行的 **"C: unbounded" 是错的,本文推翻它**。正确表述:
+
+- **代码维度**:games per IPA 仍由体积上界(第 5 节 R3 的同一套算术:每游戏 modules 约 104 MB,
-+ ROADMAP:116;系统对超大包拒绝安装,`build_ipa.sh:170-172` 记录了 PackageExtractionFailed),
++ ROADMAP:116,系统对超大包拒绝安装,`build_ipa.sh:170-172` 记录了 PackageExtractionFailed),
+ ROADMAP:117 "4–8 games" 的估计对 B 和 C 同样成立。
+- **数据维度**:romfs / msl / save / pso / profile.tsv 全是数据,放 `Documents/games/<id>/`,
+ 用户手动放文件即可、永不触发重签——这一维才是 unbounded,而且**架构 A 已经拿到了它**
@@ -905,14 +905,14 @@ index 00000000..515d3eae
+
+B(4–8 游戏聚合进一个二进制,WIP C5 估 3–4 周):所有游戏的模块 section 挤进同一个 Mach-O,
+共享 255 section 预算与命名空间。ROADMAP:112-115 记录了实测事故:*两个游戏同名模块静默合并进同一
-+section,无任何报错(第二个游戏的代码消失了)*;NRO 式"3 共享段 + (game, module) 键表"是修补,
++section,无任何报错(第二个游戏的代码消失了)*,NRO 式"3 共享段 + (game, module) 键表"是修补,
+验证到 2 游戏 × 2 模块。C 把每个游戏放进自己的 Mach-O:
+
+| 维度 | B(聚合二进制) | C(壳 + 每 game framework) |
+|---|---|---|
-+| section 预算 | 全体游戏共享 255(`loader.c:485`:"a Mach-O file has at most 255 sections";SSBU 98 NRO ×3 段 = 294 已单游戏爆表) | **每 framework 各自 255**;同名 section 物理上不可能跨游戏合并——B 的静默合并 bug 在 C 里结构性不存在 |
-+| 增量构建 | 加/换一个游戏 → 整个巨型可执行重链接 | 只有该游戏的 dylib 重链接;壳二进制不变;`pack_ipa.py` 按文件指纹复用旧 IPA 条目(pack_ipa.py:12-15),换一个游戏的重打包接近增量 |
-+| 故障半径 | 任一游戏的段/链接问题让整个 IPA 构建失败 | 坏的 framework 让 `dlopen` 返回 NULL(壳弹一条错误继续);其余游戏不受影响 |
++| section 预算 | 全体游戏共享 255(`loader.c:485`:"a Mach-O file has at most 255 sections",SSBU 98 NRO ×3 段 = 294 已单游戏爆表) | **每 framework 各自 255**,同名 section 物理上不可能跨游戏合并——B 的静默合并 bug 在 C 里结构性不存在 |
++| 增量构建 | 加/换一个游戏 → 整个巨型可执行重链接 | 只有该游戏的 dylib 重链接,壳二进制不变,`pack_ipa.py` 按文件指纹复用旧 IPA 条目(pack_ipa.py:12-15),换一个游戏的重打包接近增量 |
++| 故障半径 | 任一游戏的段/链接问题让整个 IPA 构建失败 | 坏的 framework 让 `dlopen` 返回 NULL(壳弹一条错误继续),其余游戏不受影响 |
+| 宿主份数 | 1 | 1(FR 方案) |
+| 每游戏元数据 | 聚合表 | framework 自带(Resources + 段),分发单个游戏 = 拷一个目录 |
+| 按需组合 | 每次都要全量决定装哪几个游戏 | 聚合脚本按用户拥有的 NSP 挑 framework 组装 IPA(仍是装时定死) |
@@ -939,8 +939,8 @@ index 00000000..515d3eae
+### 3.2 `--framework` 模式(build_ipa.sh / build_ipa_from_nsp.py)
+
+- 工程模板加一个 `framework` target(xcodegen `type: framework`,platform iOS),sources 只含
-+ `Gen/embed.S` + 一个 3 行的占位 `.m`(给镜像一个符号,供 `dladdr` 取 `dli_fbase`)+ `Info.plist`;
-+ `Gen/dm` 表格进 `Resources`。`gen_build.py` 不动(宿主源码归壳的 target);`gen_embed.py` 不动。
++ `Gen/embed.S` + 一个 3 行的占位 `.m`(给镜像一个符号,供 `dladdr` 取 `dli_fbase`)+ `Info.plist`。
++ `Gen/dm` 表格进 `Resources`。`gen_build.py` 不动(宿主源码归壳的 target),`gen_embed.py` 不动。
+- 链接 flags:沿用 embed 的 `-Wl,-segprot,__DM<mod>W,rw,rw`(gen_embed.py 末尾输出),dylib 同样接受。
+- 产物:`<game>.framework/`(dylib + Info.plist + Resources/{dm 表格, profile.tsv, launcher.json, icon}),
+ 外加一个 `game.manifest.json`(title id、名称、版本、modules 列表、chain 版本 `b-$V`、romfs marker——
@@ -950,7 +950,7 @@ index 00000000..515d3eae
+ 同类检查(stage_resources.sh:21-28)。
+- 签名:`codesign --force --sign -` 占位 ad-hoc 签 framework(与 build_ipa.sh:158 现在签 App 的理由
+ 相同:侧载器要从占位签名里读 entitlements 并全部重签)。**framework 不带 entitlements 文件**
-+ (dylib 无法持有 entitlements,见 2.1 证据 2;内存权限等 entitlement 全在壳上,build_ipa.sh:119-124)。
++ (dylib 无法持有 entitlements,见 2.1 证据 2,内存权限等 entitlement 全在壳上,build_ipa.sh:119-124)。
+
+### 3.3 壳 App 与聚合 IPA
+
@@ -961,9 +961,9 @@ index 00000000..515d3eae
+ `Payload/Shell.app/Frameworks/<game>.framework`,壳资源映射照旧,调 `pack_ipa.py` 产出一份 IPA
+ (`--skip $P/_CodeSignature` 的既有跳过逻辑沿用,build_ipa.sh:188)。
+- **签名顺序**(对照 pack_app.py:100-106 的"先内后外"):
-+ 1. 每个 framework 内 dylib;
-+ 2. 每个 framework bundle(封存其 Resources 与 Info.plist);
-+ 3. 壳可执行文件(带 entitlements,ad-hoc 占位);
++ 1. 每个 framework 内 dylib,
++ 2. 每个 framework bundle(封存其 Resources 与 Info.plist),
++ 3. 壳可执行文件(带 entitlements,ad-hoc 占位),
+ 4. 壳 bundle(封存 Frameworks/ 下全部嵌套代码)。
+ 壳 bundle 的签名会把所有 framework 的 CD hash 写进 CodeResources——这正是"加游戏必须重签"的
+ 机械原因(2.2)。侧载器(SideStore/AltStore)安装时对每个嵌套二进制重签并重建外层封存:
@@ -979,24 +979,24 @@ index 00000000..515d3eae
+
+- **游戏列表** = 扫描两个来源后按 title id 连接:
+ 1. **代码**:`Bundle.main/Frameworks/*.framework`,读每个 framework `Resources/game.manifest.json`
-+ (构建时生成,第 3.2 节);运行期用 `getsectiondata`/段存在性做交叉校验(防 manifest 与段不一致)。
++ (构建时生成,第 3.2 节),运行期用 `getsectiondata`/段存在性做交叉校验(防 manifest 与段不一致)。
+ 不建议扫 `romfs.idx` 当列表依据——romfs 是用户可移动的数据(外置盘是计划能力:romfs_arc.c 按分片
+ pread,天然支持外部路径,但今天 `main.m romfs_locate` 只查 per-game/Documents/bundle 三处,
+ 文件夹选择器是待办,ROADMAP:129-132),代码在不在 bundle 里才是"装没装"。
+ 2. **数据**:`Documents/games/*/`,"这个目录是不是一个游戏的文件"的判定已经存在:
+ `main.m:19-28 romfs_dir_ok`(有 `romfs.idx` 或 profile 的 `romfs_marker` 路径即算)。
-+ - 列表状态:代码+数据 = 可玩;只有代码 = 提示"把 romfs 放进 Files";只有数据 = 灰显"IPA 里没有这个游戏
++ - 列表状态:代码+数据 = 可玩,只有代码 = 提示"把 romfs 放进 Files",只有数据 = 灰显"IPA 里没有这个游戏
+ 的 framework(需要重签安装)"——这条提示就是 2.2 结论的用户可见面。
+- **存档隔离**:已经有了。`Documents/games/<id>/{save,temp}`,`main.m:95-104`:
+ romfs 落在游戏目录内才用 per-game save(`per_game = [romfs hasPrefix:gdir]`,98 行),
+ 壳不改这个规则,只把选中的 id 传给 `game_dir_for`(36-39 行)。WIP:41-44 与 ROADMAP:125 的
+ "A 已交付 per-game 布局" 即此。
+- **profile 与设置**:`DM_PROFILE` 指向 `Documents/games/<id>/profile.tsv`(用户可改,不重签),
-+ 无则退 framework 资源;`DM_PROF_*` 与 `DM_FPS_TARGET` 等开关的优先级链不变
++ 无则退 framework 资源,`DM_PROF_*` 与 `DM_FPS_TARGET` 等开关的优先级链不变
+ (hle_profile.h:3-5、hle_profile.c:211-219)。设置 UI 用壳自己的 launcher.json(每 framework 自带一份,
+ `build_ipa.sh:96-97` 的 settings.py 产物搬进 Resources)。
+- **切换游戏**:一次进程只跑一个游戏(理由见 R4)。游戏退出回壳 = 若宿主能干净收尾
-+ (hle_lifecycle 的 SIGTERM 路径)就回 shell 场景重建选择器;收不干净就 `exit(0)` 由用户再点图标
++ (hle_lifecycle 的 SIGTERM 路径)就回 shell 场景重建选择器,收不干净就 `exit(0)` 由用户再点图标
+ (与 Switch 回 home 的手感一致)。两种都先写进壳,探针阶段一并验证。
+
+---
@@ -1005,20 +1005,20 @@ index 00000000..515d3eae
+
+- **R1 `dlopen`/`vm_remap` 在 dylib 上是否成立——C 的存在性风险,探针先行。**
+ 规则层面 2.1 已定(bundle 内可 dlopen),但我们的用法有两个未验证细节:dyld 是否接受带多个
-+ `__DM*W` rw,rw 自定义段 + 上百 section 的 dylib;`vm_remap` copy=FALSE 把 **dylib**(而非主可执行文件)
++ `__DM*W` rw,rw 自定义段 + 上百 section 的 dylib,`vm_remap` copy=FALSE 把 **dylib**(而非主可执行文件)
+ 的已签名 __TEXT 页重映射到匿名地址再执行是否被 AMFI 放行。现行机制对"主可执行文件自己的段"成立
+ (loader.c:473-476,注释并援引 libffi trampoline table 先例),dylib 与它在内核路径上是同一类
+ (同进程内已映射的签名页),但**没有实验前不下结论**。探针必须先跑。
+ 说明:任务输入里提到 `dm/ios/probe/` 正在另一分支验证——**本工作树核对过 launcher-b、pr17、pr18、
+ mg-profile-runtime 四个分支,`dm/ios/probe/` 尚不存在**(只有 `dm/gfx/metal/probe/` 与 `dm/host/probe.c`),
+ 全仓库也没有任何 dlopen 引用。本文第 6 节把它列为第一步交付物,实验清单:
-+ P1 设备上 dlopen 一个 100 MB 级自定义段 dylib;P2 对其 __TEXT 段 vm_remap copy=FALSE + 执行 +
-+ 与现行 executable 路径逐字节对比;P3 `getsectiondata(dylib_mh, ...)`;P4 dlopen 失败的错误面
-+ (能否继续跑);P5 iOS 26 实机 + 侧载签名链(SideStore)各跑一遍。
-+- **R2 255 section 限制**:C 的每 framework 独立预算消掉 B 的跨游戏合并事故(2.3);单游戏内
-+ NRO 过多仍沿用共享段方案(`gen_embed.py` 注释:最多 255 sections、SSBU 98 NRO×3 段必须打包;
++ P1 设备上 dlopen 一个 100 MB 级自定义段 dylib,P2 对其 __TEXT 段 vm_remap copy=FALSE + 执行 +
++ 与现行 executable 路径逐字节对比,P3 `getsectiondata(dylib_mh, ...)`,P4 dlopen 失败的错误面
++ (能否继续跑),P5 iOS 26 实机 + 侧载签名链(SideStore)各跑一遍。
++- **R2 255 section 限制**:C 的每 framework 独立预算消掉 B 的跨游戏合并事故(2.3)。单游戏内
++ NRO 过多仍沿用共享段方案(`gen_embed.py` 注释:最多 255 sections、SSBU 98 NRO×3 段必须打包,
+ `loader.c:485-492`)。残余风险:壳自身 + framework 数量不影响各镜像预算(预算是 per-Mach-O 的)。
-+- **R3 体积**:每游戏 framework ≈ modules(约 104 MB 原始,ROADMAP:116)+ 表格;IPA 总体积 = 壳
++- **R3 体积**:每游戏 framework ≈ modules(约 104 MB 原始,ROADMAP:116)+ 表格,IPA 总体积 = 壳
+ (~11 K 行宿主 + SwiftUI,数 MB 级)+ N × framework。压缩后估每游戏几十 MB(deflate 对 NSO 镜像
+ 的实际收益待测,无历史数据,标待验证)。shader 库(BotW 阴影库 344 MB,ROADMAP:116)、pso 档案
+ (~650 MB/架构,build_ipa.sh:86)全部走 `Documents/games/<id>/`,不占 IPA。系统对过大的包拒绝安装
@@ -1028,33 +1028,33 @@ index 00000000..515d3eae
+ (hle_profile.h:22-23 的 mem_reserve/alias/stack/pool 等),不同游戏不需要不同签名资格。
+ **同一时刻只加载一个 framework**:规避跨镜像 ObjC 类重复与 C 符号串扰,也把"多游戏同时运行"明确
+ 划出范围(那是 LiveContainer 的多容器问题,不追)。内存上多装几个游戏不吃亏:未 dlopen 的
-+ framework 不映射任何页;dlopen 后的代码页经 vm_remap copy=FALSE 与原映射共享物理页
-+ (loader.c:475 "sharing the same signed pages"),不因加载翻倍;切游戏先终止当前进程(第 4 节),
++ framework 不映射任何页,dlopen 后的代码页经 vm_remap copy=FALSE 与原映射共享物理页
++ (loader.c:475 "sharing the same signed pages"),不因加载翻倍,切游戏先终止当前进程(第 4 节),
+ 不存在两份 guest 内存布局并存。
+- **R5 dyld 行为随 iOS 版本漂移**:LiveContainer 在 iOS 26 有豁免分支、iOS 27 加段数补丁(其源码
-+ 2.1 节引用处);我们目标就是 iOS 26+(project.yml `deploymentTarget: iOS 26.0`)。探针必须在
++ 2.1 节引用处),我们目标就是 iOS 26+(project.yml `deploymentTarget: iOS 26.0`)。探针必须在
+ 实际目标 OS 上做,并把这个探针纳入每次大版本升级的回归清单。
-+- **R6 打包与增量**:`pack_ipa.py` 复用按指纹(pack_ipa.py:12-15、193-195);framework 拆映射后
++- **R6 打包与增量**:`pack_ipa.py` 复用按指纹(pack_ipa.py:12-15、193-195),framework 拆映射后
+ 增量成立,但 ad-hoc 重签会改变 dylib 字节 → 每次聚合后所有 framework 的指纹都会变(签名写入
+ Mach-O)。缓解:聚合脚本对"构建产物 → 占位签名 → 打包"全程用固定副本,只有真正重建的 framework
-+ 走签名;重签发生在设备侧(侧载器),不影响构建机增量。此项需要在 W4 实测确认。
++ 走签名,重签发生在设备侧(侧载器),不影响构建机增量。此项需要在 W4 实测确认。
+
+---
+
-+## 6. 工作量分解(按周;◇ = 依赖探针结果,∥ = 可并行)
++## 6. 工作量分解(按周,◇ = 依赖探针结果,∥ = 可并行)
+
+| 周 | 内容 | 依赖 |
+|---|---|---|
-+| W1 | `dm/ios/probe/`:P1–P5 实验(新目录;本工作树四分支均无现成探针)| 无。3–5 天 |
-+| W1 ∥ | `--framework` 构建模式(build_ipa.sh 分支、xcodegen framework target、manifest 生成);Mac 上可先用普通 dylib 验证段布局与单测 | 不依赖探针(纯构建侧) |
++| W1 | `dm/ios/probe/`:P1–P5 实验(新目录,本工作树四分支均无现成探针)| 无。3–5 天 |
++| W1 ∥ | `--framework` 构建模式(build_ipa.sh 分支、xcodegen framework target、manifest 生成),Mac 上可先用普通 dylib 验证段布局与单测 | 不依赖探针(纯构建侧) |
+| W1 ∥ | `loader.c` IMAGE_MH 参数化 + 宿主单测(Mac 可跑:map_image 的非 NRO 路径换成"给定 mach header")| 不依赖探针 |
-+| W2 ◇ | 壳 App:选择器 UI(扫描 Frameworks + Documents/games)、env 装配(第 1.3 节表)、dlopen→dm_main 接线;探针若失败则切 FR→FH(第 1.1 节)或终止 C | W1 探针 P1–P3 |
-+| W3 | `pack_launcher_ipa.py` 聚合 + 签名顺序 + `test_pack_ipa.py` 扩展;双游戏 IPA 在模拟器/设备装机链验证 | W2 |
++| W2 ◇ | 壳 App:选择器 UI(扫描 Frameworks + Documents/games)、env 装配(第 1.3 节表)、dlopen→dm_main 接线,探针若失败则切 FR→FH(第 1.1 节)或终止 C | W1 探针 P1–P3 |
++| W3 | `pack_launcher_ipa.py` 聚合 + 签名顺序 + `test_pack_ipa.py` 扩展,双游戏 IPA 在模拟器/设备装机链验证 | W2 |
+| W4 ◇ | 实机端到端:两个真实游戏(探针用的 NSP 复用)、切游戏、存档隔离、坏 framework 容错、R6 增量实测、文档收尾 | W3 + 用户的 NSP |
+| 缓冲 | R5 的 iOS 26.1/27 差异回归、FH 备选路径(若 P2 失败,+1 周实现 FH 的 dmgame_main 与壳移交)| — |
+
+总计:**约 4 周到"双游戏可玩",探针失败再 +1 周(FH)或止损回 B**。与 B 的 3–4 周相比没有省,
-+买到的是 2.3 表里的结构性收益;决定点仍建议放在 W1 探针之后。
++买到的是 2.3 表里的结构性收益,决定点仍建议放在 W1 探针之后。
+
+---
+
@@ -1066,29 +1066,29 @@ index 00000000..515d3eae
+- `dm/ios/tools/gen_embed.py:1-13`(三段式段、ITMS-90999 单可执行段、NRO 共享段 + 表)
+- `dm/host/main.c:42-46,87-97,115-124`(DM_* 开关、模块清单来源、preload 约定)
+- `dm/ios/Sources/main.m:19-28,36-39,41-52,69-80,87-116`(per-game 布局、romfs 判定、env 装配全表)
-+- `dm/host/hle_profile.{h:1-6, c:211-219}`(运行时 profile 加载顺序);`dm/games/game.py:192-232`(profile TSV 生成)
++- `dm/host/hle_profile.{h:1-6, c:211-219}`(运行时 profile 加载顺序),`dm/games/game.py:192-232`(profile TSV 生成)
+- `dm/ios/tools/build_ipa.sh:53,70-76,96-97,100-101,117-124,138-161,166-188`(chain 版本、Gen 生成、
+ entitlements、不签名构建、占位签名、pack 映射)
-+- `dm/ios/tools/pack_ipa.py:12-15,193-195`(指纹复用);`dm/ios/tools/stage_resources.sh:21-28`(chain 校验先例)
++- `dm/ios/tools/pack_ipa.py:12-15,193-195`(指纹复用),`dm/ios/tools/stage_resources.sh:21-28`(chain 校验先例)
+- `dm/ios/project.yml`(iOS 26.0 target、Gen/dm resources、`-Dmain=dm_main`)
+- `dm/mac/pack_app.py:100-106`(先内后外签名先例)
+- `dm/host/dm.h:11`(MAX_MOD 128:profile 模块 + NRO 上限)
-+- `docs/ROADMAP.md:109-127`(调查结论、255 合并事故、104 MB/游戏、A/B/C 表);`docs/WORK-IN-PROGRESS.md:41-47,61,63`(A 现状、C5/C7)
++- `docs/ROADMAP.md:109-127`(调查结论、255 合并事故、104 MB/游戏、A/B/C 表),`docs/WORK-IN-PROGRESS.md:41-47,61,63`(A 现状、C5/C7)
+
+仓库外:
+- Apple DTS(Quinn "The Eskimo!"),dlopen 规则:developer.apple.com/forums/thread/773210
+- InjectionNext 实测(bundle 外同 TeamID dylib 被拒、dylib 无 entitlements):github.com/johnno1962/InjectionNext/issues/81
-+- TN2435 嵌入 framework:developer.apple.com/library/archive/technotes/tn2435/_index.html;
++- TN2435 嵌入 framework:developer.apple.com/library/archive/technotes/tn2435/_index.html,
+ Placing content in a bundle:developer.apple.com/documentation/bundleresources/placing-content-in-a-bundle
+- LiveContainer(JIT 条件下的 dyld 验证绕过、无 JIT 则重签 guest、iOS 26/27 适配):
-+ github.com/LiveContainer/LiveContainer(README;`LiveContainer/LCBootstrap.m`、`LiveContainer/dyld_bypass_validation.m`)
-+- SideStore FAQ(重装同 bundle id 数据保留、重签模型):docs.sidestore.io/docs/faq;
++ github.com/LiveContainer/LiveContainer(README,`LiveContainer/LCBootstrap.m`、`LiveContainer/dyld_bypass_validation.m`)
++- SideStore FAQ(重装同 bundle id 数据保留、重签模型):docs.sidestore.io/docs/faq,
+ 免费 Apple ID 3 app / 10 App ID 限制:faq.altstore.io(这也是"所有游戏进一个壳"的动机之一)
+
-+> **Update (merged):** the dlopen probe now exists — `dm/ios/probe/` with `build_probe.sh`, committed alongside this document, and `probe-out/DmProbe.ipa` is built. W1 step 1 is done; what remains is running it on an iOS 26 device and reading `Documents/probe-log.txt`.
++> **Update (merged):** the dlopen probe now exists — `dm/ios/probe/` with `build_probe.sh`, committed alongside this document, and `probe-out/DmProbe.ipa` is built. W1 step 1 is done. What remains is running it on an iOS 26 device and reading `Documents/probe-log.txt`.
diff --git a/docs/launcher-c-plan.md b/docs/launcher-c-plan.md
new file mode 100644
-index 00000000..9dc0ad3a
+index 00000000..ab13b78d
--- /dev/null
+++ b/docs/launcher-c-plan.md
@@ -0,0 +1,213 @@
@@ -1097,7 +1097,7 @@ index 00000000..9dc0ad3a
+Status: **the dlopen gate is open** (device run on iOS 27.0.1, [probe-dlopen.md](probe-dlopen.md)),
+design in [launcher-c-design.md](launcher-c-design.md). This plan turns the design into
+milestones with a testable artifact each. The probe proved a one-function framework loads and
-+runs; **the real payload is still unproven** (a framework with the game's ~100 MB of `__DM*W`
++runs, but **the real payload is still unproven** (a framework with the game's ~100 MB of `__DM*W`
+sections / up to 255 sections, `vm_remap` of its signed `__TEXT` with copy=FALSE,
+`getsectiondata` on a dylib header). M1 exists to prove exactly that.
+
@@ -1113,20 +1113,20 @@ index 00000000..9dc0ad3a
+
+## M1 — the first testable artifact
+
-+Keep "one game, one IPA"; move the game's modules out of the main executable into
++Keep "one game, one IPA" and move the game's modules out of the main executable into
+`DmIOS.app/Frameworks/DmGame.framework`, `dlopen` it at launch, take its mach header via
+`dlsym` + `dladdr`, and read its sections.
+
+**New files**
+
+- `dm/ios/project-framework.yml`: same app target as `project.yml` but without `Gen/embed.S`, with
-+ a `DmGame` framework target (`Gen/embed.S` + a marker `.m`; resources `Gen/framework/dm`,
++ a `DmGame` framework target (`Gen/embed.S` + a marker `.m`, with resources `Gen/framework/dm`,
+ `profile.tsv`, `game.manifest.json`), `embed: true`, `link: false`, app RPATH
+ `@executable_path/Frameworks`.
+- `dm/ios/framework/DmGameMarker.m`: `dmgame_image_marker` — only for `dlsym`/`dladdr`.
+- `dm/host/loader_image.h`: `void dm_set_game_image_header(const void *mh);`
+- `dm/ios/Sources/FrameworkBootstrap.m/.h`: `dlopen` → `dlsym(marker)` → `dladdr` →
-+ `dm_set_game_image_header(info.dli_fbase)`; logs `[RED]` on failure.
++ `dm_set_game_image_header(info.dli_fbase)`, and it logs `[RED]` on failure.
+- `dm/ios/tools/gen_manifest.py`: builds `game.manifest.json` (schema below).
+- `dm/ios/tests/test_framework_build.py`, `test_framework_link.py`.
+
@@ -1137,69 +1137,69 @@ index 00000000..9dc0ad3a
+ `map_image()` (:536) use it. **Do not** touch `force_init()` (:154) — `__DATA,swforce` is the
+ host's own table.
+- `dm/ios/Sources/main.m`: under `DM_FRAMEWORK_BUILD`, set `DM_PROFILE` to the framework's
-+ `profile.tsv` **before** the first `dm_profile()` call; call `dm_open_game_framework()` before
-+ `dm_host_preload_start()` (:237); `argv[1]` and `DM_NVN_SHMAP` point at `<framework>/dm`.
-+- `dm/ios/tools/build_ipa.sh`: `FRAMEWORK=${DM_FRAMEWORK:-0}`; framework mode generates
++ `profile.tsv` **before** the first `dm_profile()` call, call `dm_open_game_framework()` before
++ `dm_host_preload_start()` (:237), and point `argv[1]` and `DM_NVN_SHMAP` at `<framework>/dm`.
++- `dm/ios/tools/build_ipa.sh`: `FRAMEWORK=${DM_FRAMEWORK:-0}`. Framework mode generates
+ `Gen/framework/{dm,profile.tsv,game.manifest.json,Info.plist}`, `xcodegen --spec
+ project-framework.yml` (:134), signs the framework first and the app executable second
+ (:164–174).
+- `scripts/build_ipa_from_nsp.py` (~:2075): `--framework` → `DM_FRAMEWORK=1` in `ipa_env`.
+- `dm/ios/tools/compile_check.py`: a second pass with `DM_FRAMEWORK_BUILD=1`.
+- `dm/ios/tests/test_ipa_unsigned.py`, `test_xcode_workflow.py`: framework packaging/signing
-+ assertions; `--prepare-xcode` uses `project-framework.yml`.
++ assertions, and `--prepare-xcode` uses `project-framework.yml`.
+
+**Done when**
+
-+- Off-device: `compile_check.py` passes both ways; `test_framework_link.py` builds a synthetic
++- Off-device: `compile_check.py` passes both ways, `test_framework_link.py` builds a synthetic
+ framework with `xcodebuild -target DmGame CODE_SIGNING_ALLOWED=NO` and `otool -l` shows
-+ `__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, `__DATA,__dm_nro_tab`;
-+ `test_framework_build.py` packs/signs a stand-in (framework has no entitlements); the default
++ `__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, `__DATA,__dm_nro_tab`,
++ `test_framework_build.py` packs/signs a stand-in (framework has no entitlements), and the default
+ path (no `DM_FRAMEWORK`) is unchanged and the IPA has no `Frameworks/`.
-+- On device: sideload the `DM_FRAMEWORK=1` IPA; the log shows the framework path, handle, image
-+ base and each module's base/size; `DM_LOADHASH=1` per-module sha256 lines match the default
-+ build exactly (proof the framework path loads byte-identical code); a second run with an NRO
-+ game (SSBU) shows `__DATA,__dm_nro_tab` and `nro.tsv` working; iOS 26 and 27 if available.
++- On device: sideload the `DM_FRAMEWORK=1` IPA. The log shows the framework path, handle, image
++ base and each module's base/size, `DM_LOADHASH=1` per-module sha256 lines match the default
++ build exactly (proof the framework path loads byte-identical code), a second run with an NRO
++ game (SSBU) shows `__DATA,__dm_nro_tab` and `nro.tsv` working, and iOS 26 and 27 pass if available.
+
+## M2 — shell + one framework
+
-+`DmShell.app` lists one game; Play sets the environment, `dlopen`s the framework, calls
++`DmShell.app` lists one game. Play sets the environment, `dlopen`s the framework, calls
+`dm_set_game_image_header` + `dm_host_preload_start`, then shows the existing game view.
+
+- New: `dm/ios/project-shell.yml`, `dm/ios/Shell/{ShellMain.m,ShellView.swift,GameManifest.swift,
+ GameLibrary.swift,GameData.m,GameLauncher.m,BootState.m}`, `dm/ios/tools/build_shell.sh`,
+ `dm/ios/tests/{test_shell_library.py,test_framework_bootstrap.py}`.
+- Changed: `main.m`'s `game_dir_for`/`romfs_dir_ok`/`romfs_locate`/`set_data_env` move to
-+ `GameData.m` (explicit title id/marker, no `dm_profile()`); `g_boot_ok` moves to `BootState`;
-+ `front_ios.m` presents the shell root only after preload; `Launcher.swift` reads
-+ `DM_LAUNCHER_JSON` (bundle fallback); `LauncherSettings.swift` gains a per-game key/suite.
++ `GameData.m` (explicit title id/marker, no `dm_profile()`), `g_boot_ok` moves to `BootState`,
++ `front_ios.m` presents the shell root only after preload, `Launcher.swift` reads
++ `DM_LAUNCHER_JSON` (bundle fallback), and `LauncherSettings.swift` gains a per-game key/suite.
+- `dm/host/main.c:95` falls back to the compiled `DM_GAME_MODULES`: the shell passes the manifest
+ modules in argv explicitly (no code change), or the fallback changes to
+ `dm_profile()->modules` — pick one in M2 and keep the default path identical.
-+- Done when: `xcodebuild -scheme DmShell` builds; `test_shell_library.py` covers the three states
-+ (playable / needsData / needsFramework / broken); device: shell + 1 framework lists and plays,
++- Done when: `xcodebuild -scheme DmShell` builds, `test_shell_library.py` covers the three states
++ (playable / needsData / needsFramework / broken), and on a device the shell + 1 framework lists and plays and the
+ log shows per-game `DM_PROFILE`/`DM_ROMFS`/`DM_SAVE`.
+
+## M3 — N games in one IPA
+
+- New: `dm/ios/tools/pack_launcher_ipa.py` (reads each manifest, validates chain vs
-+ `dm/gfx/nvn/dmsh_chain.h`, unique title ids, `CFBundleExecutable` vs manifest; signs in order:
-+ framework → shell executable (entitlements) → shell bundle; calls `pack_ipa.py`),
++ `dm/gfx/nvn/dmsh_chain.h`, unique title ids, `CFBundleExecutable` vs manifest, signs in order:
++ framework → shell executable (entitlements) → shell bundle, and calls `pack_ipa.py`),
+ `tests/test_pack_launcher_ipa.py`, optional `framework_cache.py`.
-+- Changed: `build_ipa.sh` gains `DM_FRAMEWORK_ONLY=1` (framework + manifest, no app, no pack);
-+ `build_ipa_from_nsp.py` gains `--framework-only`; `GameLibrary.swift` scans
++- Changed: `build_ipa.sh` gains `DM_FRAMEWORK_ONLY=1` (framework + manifest, no app, no pack),
++ `build_ipa_from_nsp.py` gains `--framework-only`, and `GameLibrary.swift` scans
+ `Frameworks/*.framework/game.manifest.json` + `Documents/games/*/`.
-+- Done when: two synthetic frameworks pack, chain mismatch and duplicate title ids are rejected;
-+ device: one IPA, two games, both play; a broken framework only breaks its own row.
++- Done when: two synthetic frameworks pack, chain mismatch and duplicate title ids are rejected,
++ and on a device one IPA holds two games that both play and a broken framework only breaks its own row.
+
+## M4 — per-game data, settings, external drive, DLC
+
-+- `GameDataPicker.swift`, `test_shell_data.py`; `DataBookmark` keys become
-+ `pickedDataBookmark.<titleID>` with migration; `GameData.m` resolves like `main.m:69–117` with
-+ explicit title id/marker; `GameLauncher.m` sets `DM_AOC_DIR`, `DM_MSL_DIR`, `DM_PSO_BUNDLE`
-+ per game first, then app-wide; `LauncherSettings` per game; `GameLibrary` never treats
++- `GameDataPicker.swift`, `test_shell_data.py`. `DataBookmark` keys become
++ `pickedDataBookmark.<titleID>` with migration, `GameData.m` resolves like `main.m:69–117` with
++ explicit title id/marker, `GameLauncher.m` sets `DM_AOC_DIR`, `DM_MSL_DIR`, `DM_PSO_BUNDLE`
++ per game first and then app-wide, `LauncherSettings` is per game, and `GameLibrary` never treats
+ `romfs.idx` as "code installed" (design §233–240).
+- Done when: two titles' `Documents/games/<id>/{romfs.img,romfs,save,temp,msl,pso,aoc}` are
-+ isolated; stale bookmark falls back; identity mismatch falls back; DLC `aoc/<index>.img`
++ isolated, a stale bookmark falls back, an identity mismatch falls back, and DLC `aoc/<index>.img`
+ mounts (`hle_fs.c:516-518`).
+
+## Manifest (`game.manifest.json`, in the framework root)
@@ -1208,15 +1208,15 @@ index 00000000..9dc0ad3a
+`modules` (≥1), `nro_count`, `chain` (`b-<hex>`), `loader` (`FR`|`FH`), `framework`
+(`<name>.framework`), `framework_executable`, `image_marker` (`dmgame_image_marker`), `profile`
+(`profile.tsv`), `shader_map` (`dm/shader_map.tsv`), `launcher` (`dm/launcher.json`),
-+`romfs_marker`, `romfs_identity` (`DMROMFSID1 …`), `min_os`; optional `icon`, `built_by`,
++`romfs_marker`, `romfs_identity` (`DMROMFSID1 …`), `min_os`. Optional keys are `icon`, `built_by`,
+`built_at`, `bytes`. Validation: schema, `CFBundleExecutable`, framework name, chain equal to the
-+shell's `DMSH_CHAIN`, unique title ids; at launch cross-check sections per module
++shell's `DMSH_CHAIN`, unique title ids, and at launch the loader cross-checks sections per module
+(`__TEXT,__dm<mod>x0`, `__DM<mod>W,__img`, `__TEXT,__dm<mod>x1`, and `__DATA,__dm_nro_tab` when
+`nro_count > 0`) — a mismatch marks the game `broken` without affecting others.
+
-+Discovery: frameworks from `Bundle.main.privateFrameworksURL/*.framework`; data from
++Discovery: frameworks come from `Bundle.main.privateFrameworksURL/*.framework` and data from
+`Documents/games/<title_id>/` (`romfs.img` complete, or `romfs/romfs.idx`, or
-+`romfs/<manifest.romfs_marker>`); per-title bookmark for external drives; merge into
++`romfs/<manifest.romfs_marker>`), with a per-title bookmark for external drives, and the results merge into
+playable / needsData / needsFramework / broken.
+
+## Environment at game start
@@ -1244,49 +1244,49 @@ index 00000000..9dc0ad3a
+
+1. Build each `<Game>.framework` unsigned.
+2. Sign the framework bundle first (no entitlements).
-+3. Build `DmShell.app`; place frameworks in `DmShell.app/Frameworks/`.
++3. Build `DmShell.app` and place frameworks in `DmShell.app/Frameworks/`.
+4. Sign the shell executable with `com.apple.developer.kernel.increased-memory-limit`.
+5. Sign the shell bundle last so `CodeResources` covers every nested CDHash (same order as
+ `build_probe.sh:79–86`).
-+6. `pack_ipa.py` unchanged (mapping pairs, `--skip`, fingerprint reuse); `pack_launcher_ipa.py`
++6. `pack_ipa.py` unchanged (mapping pairs, `--skip`, fingerprint reuse), and `pack_launcher_ipa.py`
+ orchestrates, skips the shell's `Frameworks/` in the generic map and maps each framework
+ explicitly.
-+7. Self-check: `codesign -vvv --verify --strict` on framework and app; `otool -l` for
-+ `LC_ID_DYLIB=@rpath/<game>.framework/<game>` and app `LC_RPATH`; `plutil` both Info.plists.
++7. Self-check: `codesign -vvv --verify --strict` on framework and app, `otool -l` for
++ `LC_ID_DYLIB=@rpath/<game>.framework/<game>` and app `LC_RPATH`, and `plutil` on both Info.plists.
+
+Incremental: `pack_ipa.py` keys on size/mtime/ctime/inode, and ad-hoc re-signing rewrites bytes —
+cache each signed framework per game (`$W/build/ios/frameworks/<id>/`) and never re-sign an
-+unchanged one; a shell change then rewrites only the shell entries.
++unchanged one, so a shell change then rewrites only the shell entries.
+
+## Tests
+
-+Off-device: the tool-test loop; `compile_check.py` both modes; `xcodegen` + `xcodebuild` of the
-+framework from a synthetic `Gen`; macOS `dlopen`/`dlsym`/`dladdr` of a small dylib
-+(`getsectiondata`/`vm_remap` are covered by M1 on device); synthetic aggregate IPA checks
-+(`unzip -l`, `codesign -vvv`, negative chain/duplicate cases); `test_shell_library.py` three-state
-+cases; `test_shell_data.py` environment/isolation.
++Off-device: the tool-test loop, `compile_check.py` in both modes, `xcodegen` + `xcodebuild` of the
++framework from a synthetic `Gen`, macOS `dlopen`/`dlsym`/`dladdr` of a small dylib
++(`getsectiondata`/`vm_remap` are covered by M1 on device), synthetic aggregate IPA checks
++(`unzip -l`, `codesign -vvv`, negative chain/duplicate cases), `test_shell_library.py` three-state
++cases, and `test_shell_data.py` environment/isolation.
+
+On-device (minimum): M1 one real NVN game + one NRO game with `DM_LOADHASH` matching the default
-+build; M2 shell + 1; M3 shell + 2 with a broken framework; M4 two games with data/settings/DLC/
-+external drive; M5 upgrade/reinstall (bookmarks), incremental timing, iOS 26.1/27.
++build, M2 shell + 1, M3 shell + 2 with a broken framework, M4 two games with data/settings/DLC/
++external drive, and M5 upgrade/reinstall (bookmarks), incremental timing, iOS 26.1/27.
+
+## Top risks
+
-+1. **Real payload unproven (M1)** — run a real game, not the probe; compare `DM_LOADHASH` with the
-+ default build; a `dlopen` success does not imply `vm_remap` works.
-+2. **Nested re-signing / entitlements** — framework first, shell last; framework carries no
-+ entitlements; test with AltStore, Sideloadly and i4Tools once, record which one.
-+3. **Size / re-sign / install limit** — code dimension stays 4–8 games/IPA (not unbounded); data
-+ stays in Documents; every added game means a new IPA, re-signed.
-+4. **Shell lifecycle / globals / ObjC** — one game per process; one preload; `DM_PROFILE` before the
-+ first `dm_profile()`; FH must handle duplicated ObjC classes (design §36–42, 277–284).
-+5. **Complexity regressing the default path** — default `project.yml` untouched; framework mode is
-+ opt-in; existing tests must stay green; cache prevents re-signing.
++1. **Real payload unproven (M1)** — run a real game, not the probe, and compare `DM_LOADHASH` with the
++ default build. A `dlopen` success does not imply `vm_remap` works.
++2. **Nested re-signing / entitlements** — framework first, shell last, and the framework carries no
++ entitlements. Test with AltStore, Sideloadly and i4Tools once, record which one.
++3. **Size / re-sign / install limit** — code dimension stays 4–8 games/IPA (not unbounded), data
++ stays in Documents, and every added game means a new IPA, re-signed.
++4. **Shell lifecycle / globals / ObjC** — one game per process, one preload, `DM_PROFILE` before the
++ first `dm_profile()`, and FH must handle duplicated ObjC classes (design §36–42, 277–284).
++5. **Complexity regressing the default path** — default `project.yml` untouched, framework mode is
++ opt-in, existing tests must stay green, and a cache prevents re-signing.
+
+## FH fallback trigger (decidable)
+
+Switch to FH only when **all** hold: `dlopen` and `dlsym(marker)` succeed and `dladdr` gives the
-+framework base; a plain control dylib/framework in the bundle loads and runs; but
++framework base, and a plain control dylib/framework in the bundle loads and runs, but
+`getsectiondata(framework_mh, "__TEXT", "__dm<mod>x0")` returns NULL for real modules, or dyld
+rejects a pure-module dylib carrying several `__DM<mod>W` sections. If `dlopen` fails for any
+bundle framework (contradicting the probe), or `vm_remap` of signed pages cannot execute, FH does
@@ -1294,28 +1294,69 @@ index 00000000..9dc0ad3a
+
+## Documentation to update as this lands
+
-+- `docs/ROADMAP.md`: C is **not** unbounded (code dimension 4–8 games/IPA; every added game needs a
-+ re-signed IPA; the data dimension is the unbounded one — see design §136–153); the `romfs_locate`
++- `docs/ROADMAP.md`: C is **not** unbounded (code dimension 4–8 games/IPA, and every added game needs a
++ re-signed IPA, while the data dimension is the unbounded one — see design §136–153). The `romfs_locate`
+ row is stale (`main.m` already does per-game + picker + identity).
-+- `docs/WORK-IN-PROGRESS.md`: C7 "experiment passed, M1–M5 in progress"; architecture A's per-game
-+ layout is done; runtime profile is on main since `3b36083f`.
++- `docs/WORK-IN-PROGRESS.md`: C7 "experiment passed, M1–M5 in progress", architecture A's per-game
++ layout is done, and the runtime profile is on main since `3b36083f`.
+- `README.md` / `README.zh-CN.md`: v0.4.7's "launcher not started" note is stale.
-+- `docs/probe-dlopen.md`: device result recorded (done in #139); keep "what it does not prove".
-+- `docs/launcher-c-design.md`: status line; §52–53 says omitting argv lets the profile's modules
++- `docs/probe-dlopen.md`: device result recorded (done in #139), and keep "what it does not prove".
++- `docs/launcher-c-design.md`: status line. The text at §52–53 says omitting argv lets the profile's modules
+ apply, but `dm/host/main.c:95` falls back to the compiled macro — fix the doc or the code in M2.
+- `docs/development.md`, `docs/reference/packing.md`, `docs/frontends.md`: `--framework`,
+ `build_shell.sh`, `pack_launcher_ipa.py`, signing order, incremental cache, and what the shell is.
diff --git a/docs/probe-dlopen.md b/docs/probe-dlopen.md
-index 625759c0..42ef8aba 100644
+index 625759c0..f50079dd 100644
--- a/docs/probe-dlopen.md
+++ b/docs/probe-dlopen.md
-@@ -52,6 +52,40 @@ its screen:
+@@ -7,10 +7,10 @@ iPhone, can a sideloaded IPA — installed outside the App Store review with Alt
+ i4Tools (爱思助手) — `dlopen` a dynamic framework inside its own bundle and call functions in it?**
+
+ Every app with dynamic frameworks loads nested code from its own bundle at launch, so the
+-mechanism exists; what this probe proves is that it survives the sideloaded conditions, where a
++mechanism exists, and what this probe proves is that it survives the sideloaded conditions, where a
+ free-provisioning signature replaces the ad-hoc one at install time and re-signs the app and every
+ nested framework. If `dlopen` refuses such code, route C is dead on stock devices and the dlerror
+-texts are the evidence for upstream; if it works, route C stands.
++texts are the evidence for upstream. If it works, route C stands.
+
+ ## What ships
+
+@@ -26,13 +26,13 @@ Payload/DmProbe.app/
+ At launch the shell appends one line per step to `Documents/probe-log.txt` and shows the verdict on
+ its screen:
+
+-1. the bundle and executable paths, the iOS version, and whether the framework file is present;
++1. the bundle and executable paths, the iOS version, and whether the framework file is present,
+ 2. `dlopen` attempts in order, each with its handle or its `dlerror()` text verbatim:
+ `@executable_path/Frameworks/Probe.framework/Probe`, then `@rpath/Probe.framework/Probe`, the
+ absolute sandbox path of the same file, the relative `Probe.framework/Probe`, and the bare
+- `Probe` (the last two are expected to fail; their texts tell us how far dyld got);
++ `Probe` (the last two are expected to fail, and their texts tell us how far dyld got),
+ 3. on the first success: `dlsym` of `probe_answer`, a call (42 expected), and `dladdr` naming the
+- image the symbol came from;
++ image the symbol came from,
+ 4. the last line is the verdict: `RESULT: FEASIBLE ...` or `RESULT: BLOCKED ...` plus the reason.
+
+ ## Installing and reading the result
+@@ -43,41 +43,75 @@ its screen:
+ IPA). The IPA is unsigned-but-ad-hoc on purpose: the sideloader re-signs it with the user's
+ Apple ID, exactly like every game IPA this repository ships.
+ 2. The first install from a given Apple ID needs Settings → General → VPN & Device Management →
+- trust the certificate. A free Apple ID re-signs every 7 days; a one-shot probe does not mind.
++ trust the certificate. A free Apple ID re-signs every 7 days, but a one-shot probe does not mind.
+ 3. Open DmProbe and wait two seconds. The result is on the screen and in the file:
+ **Files app → On My iPhone → DmProbe → probe-log.txt** (`UIFileSharingEnabled` in the app's
+- Info.plist makes Documents visible there; runs append, so nothing is lost).
++ Info.plist makes Documents visible there, and runs append, so nothing is lost).
+ 4. Send the log back by sharing it from the Files app (long-press → Share → AirDrop / Mail /
+ WeChat), or from i4Tools' app-file browser (DmProbe → Documents → probe-log.txt). If no new
lines appeared, the app died before logging: send the crash report instead (Settings → Privacy
& Security → Analytics Data → `DmProbe-*.ips`).
+## Result: FEASIBLE (device run, 2026-10-26)
+
-+Run on an iPhone (iOS **27.0.1**, sideloaded IPA; probe built 2026-10-27). The full log:
++Run on an iPhone (iOS **27.0.1**, sideloaded IPA, probe built 2026-10-27). The full log:
+
+```text
+---- DmProbe run 2026-10-26 19:51:50 +0000 (probe built Oct 27 2026 03:48:01) ----
@@ -1337,10 +1378,10 @@ index 625759c0..42ef8aba 100644
+
+**What this still does not prove** (design doc §R1, and the reasons are different):
+- a framework carrying the game's working set — the many `__DM*W` sections (up to 255 per image),
-+ tens of MB of `__TEXT` — loads and executes like this one-function probe;
++ tens of MB of `__TEXT` — loads and executes like this one-function probe,
+- the launcher's `vm_remap` of the game image's signed `__TEXT` into an anonymous address
-+ (copy = FALSE) is accepted for a sideloaded, re-signed framework;
-+- `getsectiondata` on a *dylib* header (the probe only used `dlsym`/`dladdr`);
++ (copy = FALSE) is accepted for a sideloaded, re-signed framework,
++- `getsectiondata` on a *dylib* header (the probe only used `dlsym`/`dladdr`),
+- loading a framework that was re-signed by a free Apple ID and installed through a different
+ sideloader than the probe's.
+
@@ -1350,3 +1391,37 @@ index 625759c0..42ef8aba 100644
## Reading the result
| Last line of probe-log.txt | Meaning |
+ |---|---|
+ | `RESULT: FEASIBLE - dlopen("@executable_path/Frameworks/Probe.framework/Probe") succeeded and probe_answer() = 42` | Route C is viable: a sideloaded app loads and calls code in a framework inside its own bundle. Proceed with the launcher shell + per-game frameworks. |
+-| `RESULT: BLOCKED - ... no suitable image found ... (no such file)` | The framework is not in the installed bundle: the sideloader stripped it or the layout broke. Record the sideloader and version; fix the packaging before concluding anything about `dlopen`. |
+-| `RESULT: BLOCKED - ... code signature ... not valid` / `not signed` / `no Team ID` | The nested framework's signature was rejected: the sideloader failed to re-sign it, or iOS refuses its signature. Record the exact text and sideloader; retry with another sideloader (or an `ldid`-signed IPA) before treating it as a platform refusal. |
+-| `RESULT: BLOCKED - ...` with any other `dlerror` text | Record the text verbatim with the device model, iOS version and sideloader; the attempt lines above it show which forms were tried. |
++| `RESULT: BLOCKED - ... no suitable image found ... (no such file)` | The framework is not in the installed bundle: the sideloader stripped it or the layout broke. Record the sideloader and version, and fix the packaging before concluding anything about `dlopen`. |
++| `RESULT: BLOCKED - ... code signature ... not valid` / `not signed` / `no Team ID` | The nested framework's signature was rejected: the sideloader failed to re-sign it, or iOS refuses its signature. Record the exact text and sideloader, and retry with another sideloader (or an `ldid`-signed IPA) before treating it as a platform refusal. |
++| `RESULT: BLOCKED - ...` with any other `dlerror` text | Record the text verbatim with the device model, iOS version and sideloader. The attempt lines above it show which forms were tried. |
+
+ The failing fallbacks (relative and bare-name forms) always log `no suitable image found` texts —
+-that is their expected outcome, not a verdict; the verdict uses only whether some form loaded.
++that is their expected outcome, not a verdict. The verdict uses only whether some form loaded.
+
+ ## What it does not prove
+
+ - **App Store review rules** (a policy question, not a technique one): irrelevant to sideloaded
+ distribution, which is how this project ships.
+ - **Loading code that is not in the signed bundle** (streaming game payloads from disk — the
+- original ROADMAP blocker): still expected to be blocked; route C compiles each game's modules
++ original ROADMAP blocker): still expected to be blocked, since route C compiles each game's modules
+ into its framework at packaging time, inside the signed bundle.
+ - **JIT, or anything about the game modules themselves**: the rewriter's output needs much more
+- than one C function; this probe only opens the door the launcher would walk through.
++ than one C function, and this probe only opens the door the launcher would walk through.
+
+ The build was self-checked on the Mac only (`codesign -vvv --verify --strict` on the framework,
+-the app, and the app extracted from the packed IPA again; `otool` load commands: the app's
++the app, and the app extracted from the packed IPA again. `otool` load commands: the app's
+ `LC_RPATH @executable_path/Frameworks`, the framework's install name `@rpath/Probe.framework/Probe`,
+-`minos 26.0`; `lipo` arm64; `plutil` on both Info.plists; `ldid` is not installed on this machine,
++`minos 26.0`, `lipo` arm64, `plutil` on both Info.plists, and `ldid` is not installed on this machine,
+ so codesign only). The device run is the user's step.
+
+ ## Building it again
diff --git a/patches/0024-games-md-gallery.patch b/patches/0024-games-md-gallery.patch
index f3e813db..2d7e8ba3 100644
--- a/patches/0024-games-md-gallery.patch
+++ b/patches/0024-games-md-gallery.patch
@@ -9,12 +9,11 @@ README.md is the player's page and stays short: docs_gallery.py writes the galle
Upstream-Status: fork-only
Reason: README is the fork's short player page: the games gallery is written to GAMES.md (it would be most of the README) and the update history is CHANGELOG.md
Issue: LNPANDY/NX2Apple#123
-
---
dm/tools/docs_gallery.py | 16 ++++++++--------
dm/tools/tests/test_docs.py | 4 ++--
- docs/RELEASE-NOTES-GUIDE.md | 2 +-
- 3 files changed, 11 insertions(+), 11 deletions(-)
+ docs/RELEASE-NOTES-GUIDE.md | 8 ++++----
+ 3 files changed, 14 insertions(+), 14 deletions(-)
diff --git a/dm/tools/docs_gallery.py b/dm/tools/docs_gallery.py
index 38280413..5d5c78da 100644
@@ -97,15 +96,33 @@ index 350f7be9..ce6f40ed 100644
def test_plain_text_captions_and_unknown_size(self):
image = docs_gallery.rows()[0][0]
diff --git a/docs/RELEASE-NOTES-GUIDE.md b/docs/RELEASE-NOTES-GUIDE.md
-index ba1f3323..a8378ef2 100644
+index ba1f3323..116d6e85 100644
--- a/docs/RELEASE-NOTES-GUIDE.md
+++ b/docs/RELEASE-NOTES-GUIDE.md
-@@ -75,7 +75,7 @@ changing the template means checking that sheet's tests too.
+@@ -53,11 +53,11 @@ same section order, and a reader picks one and reads straight through.
+
+ The two halves use the **same headings in the same order** (the Chinese ones are the translations
+ of the English ones), and the same number of items under each heading. Item 2 in English is item 2
+-in Chinese; a reader comparing the two must not have to map lists.
++in Chinese, so a reader comparing the two does not have to map lists.
+
+ Rules that matter more than the template:
+
+-1. **English first.** It is the canonical text; the Chinese half is written from it.
++1. **English first.** It is the canonical text, and the Chinese half is written from it.
+ 2. **Both halves say the same thing.** Not "a translation of the headline and a summary of the
+ rest" — a user reading either half must learn everything the other one learns.
+ 3. **Never split a section across the two halves.** All of Fixes is in one place, then all of
+@@ -75,10 +75,10 @@ changing the template means checking that sheet's tests too.
## Where the text comes from
-- `README.md` and `README.zh-CN.md` share an update-history table; a release row goes in both, the
-+- `CHANGELOG.md` and `CHANGELOG.zh-CN.md` share an update-history table; a release row goes in both, the
++- `CHANGELOG.md` and `CHANGELOG.zh-CN.md` share an update-history table. A release row goes in both, the
English one first (it is the canonical project history), then translated.
- The release body itself is written once, in both languages, and is what `gh release edit
- --notes-file` takes. Keep the file in `/tmp` while working; the release is the record.
+- --notes-file` takes. Keep the file in `/tmp` while working; the release is the record.
++ --notes-file` takes. Keep the file in `/tmp` while working, since the release is the record.
+ - If a fact differs per platform (a macOS-only fix), say which platform in the same sentence in both
+ languages rather than relying on the reader's inference.
+
diff --git a/patches/README.md b/patches/README.md
index c3e1720e..44afd85b 100644
--- a/patches/README.md
+++ b/patches/README.md
@@ -15,10 +15,10 @@ Issue: LNPANDY/NX2Apple#<n>
| Upstream-Status | Meaning |
|---|---|
-| `forwarded seedds/nxnative#N` | the same change is a pull request upstream; the patch goes when it merges |
+| `forwarded seedds/nxnative#N` | the same change is a pull request upstream, and the patch goes when it merges |
| `pending` | meant for upstream, no pull request yet |
| `fork-only` | stays here: a fork product choice, or upstream declined it (`fork-only (declined seedds/nxnative#N)`) |
-| `backport <sha>` | upstream has it (that commit); the patch goes on the next bump |
+| `backport <sha>` | upstream has it (that commit), and the patch goes on the next bump |
A status may carry a note in brackets. `scripts/patches.py status` lists every patch with its status, reason and age, so the
list of what the fork carries and why is one command, and it should keep shrinking.
@@ -37,7 +37,7 @@ python3 scripts/patches.py absorb [paths] # direct edits of vendored files f
`apply` and `bump` need the upstream commit in the local repository (`git fetch seedds`, the remote
`https://github.com/seedds/nxnative.git`). Scratch worktrees go to `$PATCHES_TMP` (or `--tmp`), else the system's temporary folder.
-`dm/fork_patches.txt` is generated by `apply` and `bump` (one patch name per line); do not edit it.
+`dm/fork_patches.txt` is generated by `apply` and `bump` (one patch name per line). Do not edit it.
## You edited a vendored file directly (check fails)
@@ -48,7 +48,7 @@ already touches it (the last one, when several do), keeping that patch's header.
- A new file goes to a patch only when that is unambiguous: the one patch that touches files in the file's nearest folder.
Otherwise `absorb` stops, writes nothing, and asks for `--into <patch>` (a name from `status`, or its number).
-- `paths` limit what is folded in (files or folders); without them every difference is.
+- `paths` limit what is folded in (files or folders). Without them every difference is.
- It refuses the shader chain and the tool pins (Patch policy), and leaves the generated indexes to `apply`.
- For a change that needs its own `Upstream-Status`, use `export` below instead.
@@ -56,15 +56,15 @@ already touches it (the last one, when several do), keeping that patch's header.
1. Branch off `main`. Make the fix as an ordinary commit in the vendored files, with a message that says what and why.
2. `python3 scripts/patches.py export HEAD` writes `patches/NNNN-<subject>.patch`, adds it to `series`, and puts the header
- template into the message (`Upstream-Status: pending`, `Reason: TODO`, `Issue: TODO`; `--status`, `--reason` and `--issue` set them). Fill the three lines in. A range
- (`export main..HEAD`) makes one patch per commit. Rename the file if you want a shorter name; the name is what
+ template into the message (`Upstream-Status: pending`, `Reason: TODO`, `Issue: TODO`, which `--status`, `--reason` and `--issue` set). Fill the three lines in. A range
+ (`export main..HEAD`) makes one patch per commit. Rename the file if you want a shorter name, because the name is what
`fork_patches.txt` and `status` show.
3. `python3 scripts/patches.py check` must pass: the series applied to the pin gives exactly the tree you committed. Commit the
patch file with the change in the same pull request. The files you edited are already in your commit, so they are part of the PR.
4. Send the same change to seedds/nxnative as a pull request from a branch off *their* main (`git fetch seedds`,
`git switch -c fix-x seedds/main`, `git cherry-pick <commit>`), and set the patch to `forwarded seedds/nxnative#<N>`.
5. When upstream merges it, the next bump finds the patch empty and drops it (`landed upstream` in the sync PR). If upstream took it
- in a different form (as `Co-authored-by`, reworked), the patch conflicts instead; delete it then, and set nothing else.
+ in a different form (as `Co-authored-by`, reworked), the patch conflicts instead. Delete it then, and set nothing else.
## Bumping, and what a conflict is
@@ -93,8 +93,8 @@ Upstream's compatibility is the baseline. A patch does not change it silently.
patch acts only where it is needed (no change on supported hardware), has its own tests, and is ours to maintain: if it
conflicts on a bump, we refresh it or drop it.
3. **Off limits:** the shader chain (`DMSH_CHAIN`, `dm/gfx/nvn/dmsh_chain.h`, the chain tools `dm/gfx/tools/dmsh_*`, `Program.cs`,
- `ios_metal.py`, `dmsh_chain.lock`, the translator `dmsh_xlate_bin`; AGENTS.md has the exact list, and `patches.py` reads it
- from there), upstream's tool pins, and lowering a minimum version. Shader caches and game profiles depend on them; diverging there
+ `ios_metal.py`, `dmsh_chain.lock`, the translator `dmsh_xlate_bin`, with the exact list in AGENTS.md, which `patches.py` reads
+ from there), upstream's tool pins, and lowering a minimum version. Shader caches and game profiles depend on them, and diverging there
makes our builds incompatible with upstream's caches and bug reports. `patches.py check` and `export` reject a patch that touches
these paths.
4. **Bug reports go where they belong.** Every build records the patches it carries: `DMForkPatches` in the app's `Info.plist` and
@@ -115,5 +115,5 @@ belong to the fork and are edited directly. Inside the vendored paths, the tool'
the tree differs from upstream's (a profile key, a patched host table), so upstream's copy would fail the test, and a patch that
carried the file would conflict on every bump. `apply`, `bump` and `check` therefore run both tools on the patched tree and
compare the result, and a patch that touches either file is rejected by `check` (`export` leaves them out). Nothing to do by hand:
-`apply` writes them. Not covered: `docs/badges/*.json`, which are carried as static files in `fork-docs`; the README's game table and
+`apply` writes them. Not covered: `docs/badges/*.json`, which are carried as static files in `fork-docs`. The README's game table and
banners are outside the vendored paths and no longer refreshed by a script.