Skip to content

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

Carry increased-memory-limit in a placeholder signature; docs

LNPANDYc3bccb55e1f0
diff --git a/README.md b/README.md
index 6c2c5982..97a4b414 100644
--- a/README.md
+++ b/README.md
@@ -116,6 +116,29 @@ The index may sit at any of these places; the reader tries them in order:
<DM_ROMFS>/romfs/romfs.idx
```
+## Playing
+
+**Touch controls.** Two layouts (tap the button at the top centre to switch): 2D (left stick,
+A/B/X/Y, shoulders, − / +) and 3D (adds a D-pad, a right stick and L3 / R3). With no controller
+connected, touches outside the controls go to the game's touch screen.
+
+**Physical controllers** (GameController framework: Xbox, PlayStation, Switch Pro and MFi pads all
+work) hide the touch controls entirely while connected and bring them back when disconnected;
+meanwhile every touch goes to the game's touch screen. Buttons map by position, as on a Switch
+controller: bottom = B, right = A, left = Y, top = X, and the D-pad and right stick are kept.
+
+**Settings without rebuilding:** `Documents/env.txt`, one `KEY=VALUE` per line. Common ones:
+
+```
+DM_LANG=zh-Hans # Chinese (en-US by default)
+DM_FPS_TARGET=30 # cap the frame rate (saves battery; the profile's fps_target by default)
+DM_OPMODE=0 # handheld mode: 720p render instead of the docked 1080p
+```
+
+**Saves and logs** are in the Files app under the app's name: `save/` and `log.txt`. When something
+goes wrong, send `log.txt` (the previous run is `log.prev.txt`). Short stutters the first time a new
+scene appears are normal: the app compiles graphics for it once and remembers them.
+
## Using it for another game
The archive format has nothing game-specific in it: the packer walks whatever directory you give it
@@ -175,19 +198,20 @@ The mount is recognised by its **directory**, not its name: titles differ (`rom`
byte-compare OK, and the game runs from the archive on macOS (2,100 frames, 1,772 archive reads).
The update needs no special handling: `nx_extract` already layers the update NCA over the base
with `OpenFileSystemWithPatch`, so the extracted RomFS — and therefore the archive — is the merge.
+ **Playable on an iPhone** (12 GB device, AltStore Classic 2.3) once the memory entitlement is in
+ effect — see below.
- The C reader walks all 304,243 Tears of the Kingdom files and 2,667 directories in 7.6 s.
-**On an iPhone, Tears of the Kingdom currently stops at the world map.** Its resident memory reaches
-~3.34 GB, which is the per-app jetsam budget on a 12 GB device (measured headroom: 33 MB), and the
-open world needs more. Lowering the render scale to 0.5 does not change it, so the limit is the
-guest heap, not the GPU. Games from upstream's tested list (4–6 GB) are far below that budget.
-
-The app requests `com.apple.developer.kernel.increased-memory-limit`, which raises that budget to
-6–8 GB. Whether it takes effect depends on the sideloader: it has to keep unknown entitlements and
-enable the capability on the App ID with Apple. **AltStore Classic 2.2+**, **Impactor** and **Xcode
-with a Personal Team** do; **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 for
-how to tell from `Documents/log.txt` whether it took effect.
+**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
+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
+to tell from `Documents/log.txt` (resident + headroom: ~3,375 MB = not in effect, 6–8 GB = it is).
## Limitations
diff --git a/README.zh-CN.md b/README.zh-CN.md
index effa24b3..83139241 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -110,6 +110,27 @@ App 会先找 `romfs.idx`(`dm/ios/Sources/main.m` 的 `romfs_locate`)。没
<DM_ROMFS>/romfs/romfs.idx
```
+## 游玩
+
+**触屏操控。** 两种布局(点顶部中央的按钮切换):2D(左摇杆、A/B/X/Y、肩键、−/+)和 3D
+(增加十字键、右摇杆和 L3/R3)。未连接手柄时,触到控件以外的区域会送到游戏的触屏。
+
+**实体手柄**(GameController 框架:Xbox、PlayStation、Switch Pro 和 MFi 手柄都支持)连接后
+会完全隐藏触屏控件,断开时恢复;期间所有触摸都送到游戏的触屏。按键按位置映射,与 Switch
+手柄一致:下=B、右=A、左=Y、上=X,十字键和右摇杆同样保留。
+
+**不改包调设置:** `Documents/env.txt`,每行一个 `KEY=VALUE`。常用的:
+
+```
+DM_LANG=zh-Hans # 中文(默认 en-US)
+DM_FPS_TARGET=30 # 限帧(省电;默认用 profile 的 fps_target)
+DM_OPMODE=0 # 掌机模式:720p 渲染而不是底座的 1080p
+```
+
+**存档和日志**在「文件」App 里该 App 名字下:`save/` 和 `log.txt`。出问题时把 `log.txt`
+发出来(上一次运行的是 `log.prev.txt`)。新场景第一次出现时短促卡顿是正常的:App 会为它
+编译一次图形并记住。
+
## 换其他游戏
归档格式里没有任何与具体游戏绑定的东西:打包工具遍历你给的目录,读取层在那棵树里查路径。换游戏只需要:
@@ -159,11 +180,22 @@ App 会先找 `romfs.idx`(`dm/ios/Sources/main.m` 的 `romfs_locate`)。没
- **《王国之泪》**(0100F2C0115B6000,v1.0.0 + 更新 1.4.3):304,243 个文件打成 127 个文件;
304,243 个文件全部与源目录逐字节比对通过(`verify: OK`);游戏从归档正常运行于 macOS
(30 fps,1,905 帧)。
-- C 读取层遍历全部 304,243 个文件、2,667 个目录,耗时 7.6 秒。
-
-**在 iPhone 上,《王国之泪》目前会停在进入大地图时。** 常驻内存达到约 3.34 GB,而 12 GB 设备给单个
-App 的 jetsam 预算就是这么多(实测剩余余量 33 MB),开放世界需要更多。把渲染缩放降到 0.5 没有改变
-结果,说明瓶颈在 guest 堆而不是 GPU。上游测试列表里的游戏(4–6 GB)离这个预算还远。
+- **《哈迪斯 2》**(0100A00019DE0000,本体 + 更新 1.0.137848):5,258 个文件打成 33 个文件,
+ 逐字节比对通过,游戏从归档正常运行于 macOS(2,100 帧,1,772 次归档读取)。更新包无需特殊
+ 处理:`nx_extract` 本来就用 `OpenFileSystemWithPatch` 把更新层叠在本体上,解出的 RomFS
+ ——也就是归档——就是合并结果。**在 iPhone 上可玩**(12 GB 设备,AltStore Classic 2.3),
+ 前提是内存 entitlement 生效——见下。
+- C 读取层遍历全部 304,243 个《王国之泪》文件、2,667 个目录,耗时 7.6 秒。
+
+**jetsam 预算是大体积游戏的限制,而它是可以提高的。** 没有
+`com.apple.developer.kernel.increased-memory-limit` 时,iPhone 给这个 App 约 3,375 MB(12 GB
+设备实测:《王国之泪》进大地图时被杀,常驻 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 里
+resident + headroom:约 3,375 MB = 未生效,6–8 GB = 已生效)见
+[dm/ios/ENTITLEMENTS.md](dm/ios/ENTITLEMENTS.md)。
## 限制
diff --git a/dm/ios/ENTITLEMENTS.md b/dm/ios/ENTITLEMENTS.md
index 1049e333..5dcb69dd 100644
--- a/dm/ios/ENTITLEMENTS.md
+++ b/dm/ios/ENTITLEMENTS.md
@@ -63,12 +63,33 @@ Launch the game, let it run a few hundred frames, then read the memory line in `
memory up to frame 600: resident 3342 MB, ... headroom to the system memory limit 33 MB
```
-- `headroom` in the low tens of MB, then the log stops with no `CRASH sig=` line → no entitlement.
-- `headroom` in the hundreds of MB or more at the same frame count → the entitlement is active.
+`resident + headroom` is the budget the kernel enforces:
+
+- ≈ 3,375 MB → the entitlement is not in effect.
+- ≈ 6,000–8,000 MB → it is.
`os_proc_available_memory()` is what produces that number (`dm/gfx/nvn/nvn_mtl.m`), and it reports
the distance to the budget the kernel enforces.
+## Why the placeholder signature matters
+
+`build_ipa.sh` builds unsigned. A sideloader decides which entitlements to carry by reading them
+from the signature it is replacing — an unsigned binary has none, so the request would be lost no
+matter what sits in the bundle. The script therefore embeds `Sources/DmIOS.entitlements` with an
+ad-hoc signature (`codesign --force --sign - --entitlements …`, no certificate needed): the
+sideloader strips that signature and swaps in the user's own, but it now sees the entitlement and
+carries it over. Check any built IPA with:
+
+```bash
+codesign -d --entitlements :- Payload/DmIOS.app/DmIOS | grep increased-memory-limit
+```
+
+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 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
With a Personal Team and a real device, add the capability in Xcode
diff --git a/dm/ios/tools/build_ipa.sh b/dm/ios/tools/build_ipa.sh
index 62884b70..349f1256 100755
--- a/dm/ios/tools/build_ipa.sh
+++ b/dm/ios/tools/build_ipa.sh
@@ -77,11 +77,18 @@ APP=$DD/Build/Products/Release-iphoneos/DmIOS.app; [ -d "$APP" ] || APP=$(grep -
# the app sets DM_AOC_DIR at launch, the host reports them as owned and mounts them from it) and the RomFS
rm -rf "$APP/msl" "$O/Payload" "$O/out.ipa" # (the last two: what the copy-and-zip packing left behind)
P=Payload/DmIOS.app; MAPS=("$P=$APP" "$P/msl/$MSLDIR=$MSL_IOS/$MSLDIR")
-# Increased Memory Limit: the build is unsigned, so Xcode never merges Sources/DmIOS.entitlements into
-# a signature. Ship the file inside the app bundle anyway so a sideloader that looks for it there can
-# pick it up. See dm/ios/ENTITLEMENTS.md.
+# Increased Memory Limit: the build is unsigned, so Xcode never merges Sources/DmIOS.entitlements
+# into a signature. A sideloader reads the entitlements it should keep from the signature it is
+# replacing — an unsigned binary has none, so the request would be lost. Embed them with an ad-hoc
+# ("-" identity, no certificate needed) placeholder signature: the sideloader strips this signature
+# anyway and swaps in the user's own, but it now sees the entitlement and carries it over. The file
+# also stays in the bundle for tools that look there. See dm/ios/ENTITLEMENTS.md.
cp Sources/DmIOS.entitlements "$APP/DmIOS.entitlements" || die "copy entitlements into the app bundle"
-t "entitlements: com.apple.developer.kernel.increased-memory-limit requested (see dm/ios/ENTITLEMENTS.md)"
+codesign --force --sign - --entitlements Sources/DmIOS.entitlements "$APP" \
+ || die "ad-hoc sign with entitlements (the sideloader re-signs; this only carries the request)"
+codesign -d --entitlements :- "$APP" | grep -q increased-memory-limit \
+ || die "entitlements did not make it into the placeholder signature"
+t "entitlements: increased-memory-limit embedded in the placeholder signature"
if [ -n "$AOC" ] && [ -d "$AOC" ]; then MAPS+=("$P/aoc=$AOC"); t "add-on content: $(ls "$AOC" | tr '\n' ' ')"; fi
# DM_NO_ROMFS=1: leave the RomFS out of the package. The app then reads it from Documents/romfs
# (a directory tree, or a ROMFSARC archive: romfs.idx + romfs.NN shards, see dm/host/romfs_arc.h).