t1k:cocos:base:ipa-port
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | high |
| Tools | — |
Keywords: fairplay, ios port, ios to cocos, ipa port, mach-o, port ios game, port ipa, port this ipa, unity ios to cocos, unityframework
How to invoke
Section titled “How to invoke”/t1k:cocos:base:ipa-port<file.ipa> [--video <url>] [--phase setup|extract|video|plan|data|art|lanes|polish|verify]IPA Port: a shipped iOS game into a Cocos 3.8.7 template game
Section titled “IPA Port: a shipped iOS game into a Cocos 3.8.7 template game”The iOS twin of t1k-cocos-base-apk-port, itself the Cocos rebuild half of the core skill t1k-apk-port. Only
extraction differs, and core owns it (ipa-unpack.cjs --target cocos): an IPA is one Payload/<Name>.app bundle, the IL2CPP code lives in a Mach-O
(UnityFramework), and an App Store build is FairPlay-encrypted. Everything after extraction (video, plan, data,
art, UI, polish, verify, Discord) is core’s workflow plus apk-port’s Cocos delta, unchanged: follow core
t1k-apk-port SKILL.md and workflow, then t1k-cocos-base-apk-port, with this skill’s Phase 1.
Rights
Section titled “Rights”The same standing as apk-port (its § Rights), and the same two exclusions: third-party SDK ids and keys stay
__SET_PER_GAME__ placeholders (extracted values go to the ONE gitignored ids file only), and the original
publisher’s splash and logo are dropped by default. On iOS the ids sit in Info.plist and
GoogleService-Info.plist; core’s ipa-unpack.cjs never prints them.
Decision tree
Section titled “Decision tree”| Intent | Path |
|---|---|
| Start a port from an IPA | apk-port phase 0 (the preflight), then § Phase 1 below |
encrypted: true, core exit 4 (an App Store download) | a STOP for decoding, never a question: ipa-extract (references/ipa-extract.md) § Step 2 lists the routes; without a decrypted build or a same-version APK, continue from captures and video (all INFERRED or VIDEO-OBSERVED) |
| A fat binary, or Il2CppDumper waits for a key press | core macho-slice.cjs → ipa-extract (references/ipa-extract.md) § Step 3 |
| A rule that lives in a method body | ipa-extract (references/ipa-extract.md) § Step 4, then core t1k-apk-port’s il2cpp-method-bodies reference |
The IPA is Cocos 2.x (route names t1k-cocos-base-apk-unbuild) | stop here, use t1k-cocos-base-apk-unbuild |
| The Android build of the same game is also available | port from the APK with apk-port; use the IPA only where it differs |
| Data, art, UI, polish, verify, Discord | apk-port’s decision tree, unchanged |
Phase 1 (replaces apk-port’s Phase 1 steps 2-3)
Section titled “Phase 1 (replaces apk-port’s Phase 1 steps 2-3)”SCRandtool-preflight.cjsexactly as apk-port Phase 1 steps 0-1.- Run core’s script, from core’s
t1k-apk-portfolder, always with--target cocos(without it the route is a hint that names no skill):bun scripts/ipa-unpack.cjs <file.ipa> SCR/unpacked --target cocos(new, empty dir). Readstate,engine,binary,metadata,arches,encrypted,route. Exit 4 is a FairPlay-encrypted binary: the summary is still written, but there is nothing to decode (step 3). Exit 3 is ZIP64: ipa-extract (references/ipa-extract.md) § Step 1. encrypted: true(exit 4) → surface it as a stop for decoding with one clear message in the report (“code binary is FairPlay-encrypted, nothing to decode; art and audio continue, data and method bodies need a decrypted build or the Android build”) and take ipa-extract (references/ipa-extract.md) § Step 2: art and audio can start, game data and method bodies cannot. Record it as acapture-decisionand the route taken in the plan’s decision register; the run continues on what can be decoded (core “Non-stop run”), it does not wait on a question.- After the extract,
evidence-index.cjs build SCR;lookupbefore any grep ofSCR. Unity: coremacho-slice.cjs(fat binary), coret1k-apk-port’sil2cpp-setup.cjson the metadata file, the dumper on the thin binary, AssetRipper on<app>/Data,decode_mb.py+resolve_refs.py,il2cpp_method.pyfor code-only logic (ipa-extract (references/ipa-extract.md) § Step 3-4). - Reports as apk-port Phase 1 step 4, plus the decryption route in
data-port.md.
Accept: apk-port’s Phase 1 acceptance, plus encrypted: false on the binary every dumper and body citation
read (or a written route-2 proof that the APK decodes this IPA’s data).
Untrusted input: hard rules
Section titled “Untrusted input: hard rules”apk-port’s rules hold in full: the IPA gets its own new, empty dir outside assets/; never run, import, load
or open anything from it in an interpreter (that covers the .app, its frameworks and dylibs, and any script
in it); every Python run is python -I; nothing raw is committed. A decrypted IPA from a device dump is
untrusted input too.
Scripts
Section titled “Scripts”Run with bun. Every script prints stable markers, never prompts, and reads bytes only.
| Script | Does | Exit |
|---|---|---|
core scripts/ipa-unpack.cjs <file.ipa> <outDir> --target cocos · --extracted <dir> --target cocos | find the one Payload/*.app, extract (zip-slip refused), detect the engine, pick the code binary (UnityFramework, else the main executable), read its arches and FairPlay cryptid, five safe Info.plist keys, one JSON line + IPA-PORT-UNPACK: OK engine=<e> route=<skill>[ WARN ...] | 0 · 1 corrupt / no single app · 2 usage · 3 ZIP64/encrypted zip · 4 FairPlay-encrypted binary |
core scripts/macho-slice.cjs <binary> <out> [--arch arm64] | write one slice of a fat Mach-O (or copy a thin one), never overwriting | 0 · 1 not Mach-O / arch absent · 2 usage |
apk-port scripts/unity/il2cpp_method.py | method bodies; reads Mach-O (thin/fat, RVA-addressed) as well as ELF, refuses an encrypted slice | 0 · 1 · 2 · 3 not ARM ELF/Mach-O or encrypted |
Every other script (tool-preflight, il2cpp-setup, decode_mb, resolve_refs, video-ref-fetch,
compare-image, Ghidra) is core t1k-apk-port’s, run from its folder. This skill ships no scripts/ of its own
(test/no-core-script-copies.test.cjs refuses a copy of a core script). Core t1k-apk-port must be installed.
Executed by
Section titled “Executed by”The scripts are mechanical: t1k-cocos-base-asset-porter runs core’s ipa-unpack.cjs, macho-slice.cjs, the
dumpers and the art import; every later lane is staffed as in apk-port’s § Executed by. The decryption route,
the route-2 proof, INFERRED calls and the parity judgment stay with the orchestrating session.
Related
Section titled “Related”references/ipa-extract.md— IPA layout, FairPlay and the three decryption routes, dumpers and method bodies on Mach-Ot1k-cocos-base-apk-port— every phase other than extraction; its references are this skill’s referencest1k-cocos-base-apk-unbuild— a Cocos 2.x build