Skip to content

t1k:cocos:base:ipa-port

FieldValue
Modulebase
Version4.51.9
Efforthigh
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

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

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.

IntentPath
Start a port from an IPAapk-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 presscore macho-slice.cjs → ipa-extract (references/ipa-extract.md) § Step 3
A rule that lives in a method bodyipa-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 availableport from the APK with apk-port; use the IPA only where it differs
Data, art, UI, polish, verify, Discordapk-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)”
  1. SCR and tool-preflight.cjs exactly as apk-port Phase 1 steps 0-1.
  2. Run core’s script, from core’s t1k-apk-port folder, 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). Read state, 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.
  3. 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 a capture-decision and 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.
  4. After the extract, evidence-index.cjs build SCR; lookup before any grep of SCR. Unity: core macho-slice.cjs (fat binary), core t1k-apk-port’s il2cpp-setup.cjs on the metadata file, the dumper on the thin binary, AssetRipper on <app>/Data, decode_mb.py + resolve_refs.py, il2cpp_method.py for code-only logic (ipa-extract (references/ipa-extract.md) § Step 3-4).
  5. 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).

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.

Run with bun. Every script prints stable markers, never prompts, and reads bytes only.

ScriptDoesExit
core scripts/ipa-unpack.cjs <file.ipa> <outDir> --target cocos · --extracted <dir> --target cocosfind 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 overwriting0 · 1 not Mach-O / arch absent · 2 usage
apk-port scripts/unity/il2cpp_method.pymethod bodies; reads Mach-O (thin/fat, RVA-addressed) as well as ELF, refuses an encrypted slice0 · 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.

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.

  • references/ipa-extract.md — IPA layout, FairPlay and the three decryption routes, dumpers and method bodies on Mach-O
  • t1k-cocos-base-apk-port — every phase other than extraction; its references are this skill’s references
  • t1k-cocos-base-apk-unbuild — a Cocos 2.x build