Skip to content

ENTITLEMENTS.md

Latest commit

 

History

History
100 lines (73 loc) · 4.67 KB

ENTITLEMENTS.md

File metadata and controls

100 lines (73 loc) · 4.67 KB
Raw

Increased Memory Limit

The app asks for com.apple.developer.kernel.increased-memory-limit. build_ipa.sh writes the entitlements file itself (DM_ENTITLEMENTS=<plist> gives another one, an empty value none): into the unsigned IPA's placeholder signature (below), and for a prepared Xcode project as Gen/DmIOS.entitlements through CODE_SIGN_ENTITLEMENTS in its Gen/dm.xcconfig.

Why it matters

iOS gives an app a per-process physical-memory budget and kills it (jetsam, SIGKILL, no crash report) when it goes over. On current iPhones that budget is about 3.3 GB without the entitlement and 6–8 GB with it, depending on the device.

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, 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.

What the entitlement needs

Two conditions, both required:

  1. The signature carries it. build_ipa.sh builds unsigned (the sideloader re-signs), so what matters is whether the sideloader copies unknown entitlements from the IPA into its own signature instead of dropping them.
  2. The App ID has it enabled. The provisioning profile a sideloader generates only includes entitlements the App ID is registered for. The sideloader has to ask Apple for it.

Which sideloaders keep it

Reported by playport.dev (a different project with the same requirement):

Sideloader Keeps the entitlement
AltStore Classic 2.2 or later Yes
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

SideStore with a free Apple ID

The entitlement attaches to the App ID, so it survives the weekly refresh once set. One-time fix:

  1. Install this app through SideStore, so its App ID has been created with Apple.
  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, 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.

Checking whether it took effect

Launch the game, let it run a few hundred frames, then read the memory line in Documents/log.txt:

memory up to frame 600: resident 3342 MB, ... headroom to the system memory limit 33 MB

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 the entitlement 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:

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

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.