t1k:cocos:base:apk-port
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | high |
| Tools | — |
Keywords: apk port, assetripper, cpp2il, ghidra headless, il2cpp, il2cppdumper, il2cppinspector, literal pool, port apk, port game from apk, port this apk, unity apk to cocos, unitypy, xapk
How to invoke
Section titled “How to invoke”/t1k:cocos:base:apk-port<file.xapk|file.apk> [--video <url>] [--phase setup|extract|video|plan|data|art|lanes|polish|verify]APK port, Cocos target: the rebuild half
Section titled “APK port, Cocos target: the rebuild half”t1k-apk-port (core, t1k:apk-port) holds everything on the source side: APK/XAPK unpack, IL2CPP setup and
method bodies, UnityPy decode, UI tree and TMP style export, region image diff, video reference, the parity
audit method, the evidence dir and the Discord progress post. Run it first. It produces evidence; this skill
rebuilds that evidence as a Cocos Creator 3.8.7 game on the studio template (The1Studio/CocosTemplate:
ScreenManager, PopupService, ViewRegistry, GameFlow, platform SDK, Localization), through the editor MCP.
Rights, untrusted-input rules and the standing rules (video wins copy and brand, APK wins layout, colour and
numbers) are core’s and bind here unchanged. Worked examples: worked-examples (references/worked-examples.md).
Decision tree
Section titled “Decision tree”| Intent | Path |
|---|---|
| Start a new port | core t1k-apk-port workflow phase 0 (port-preflight.cjs --target cocos must exit 0) then phases 1 to 3 (xapk-unpack.cjs <file> SCR/unpacked --target cocos), then engine-workflow (references/engine-workflow.md); the run is non-stop from there (see “Core tools this skill calls”) |
| The APK is Cocos 2.x | t1k-cocos-base-apk-unbuild |
| The build is an iOS IPA | core ipa-unpack.cjs <file.ipa> SCR/unpacked --target cocos (exit 4 = encrypted), then t1k-cocos-base-ipa-port, then this skill |
| Decode Unity data, refs, method bodies, UI tree, TMP styles | core t1k-apk-port (unity-extract, il2cpp-method-bodies, ui-spec) |
An Odin Serialized* object’s bytes do not parse; the dumper rejects metadata v39; a method body is empty in the stub | unity-odin-and-il2cpp-v39 (references/unity-odin-and-il2cpp-v39.md) |
| Generate the data tables + TS types | data-build (references/data-build.md) |
| Port 3D/2D art, fonts, audio; the map looks grey or washed; particles and trails | art-and-colour (references/art-and-colour.md) |
| Decode Unity ParticleSystems, gradients, rigs, Animator controllers or AnimationClips with UnityPy | unity-particle-encoding (references/unity-particle-encoding.md), scripts/unity/ |
| Play a swapped GLB’s clips | animation-import (references/animation-import.md) |
| Rebuild a screen or popup (x3.2 units, 9-slice, text variants) | ui-rule (references/ui-rule.md) |
| Lanes, setup, polish, verify (Cocos delta) | engine-workflow (references/engine-workflow.md) |
| Capture phase: the original’s frames, clips, audio and motion timings; the early gate | capture-phase (references/capture-phase.md) |
| Prove a screen matches the APK: the one capped parity pass, reference set, gate, receipt, divergence register | visual-verification (references/visual-verification.md) |
| Interrupted, stalled or misrouted lane; a blank device capture | lane-recovery (references/lane-recovery.md), device-capture (references/device-capture.md) |
| A source-text guard or mutation test misses a change; audit that every shipped clip or asset is reachable | source-guards (references/source-guards.md) |
| A sliced sprite fails to build next to an edge widget | sliced-sprite-fit (references/sliced-sprite-fit.md) |
| How far along is the port, when will it be done, the status post | progress-reporting (references/progress-reporting.md) |
| Run the whole port unattended: loop, what the agent decides, what may stop it | unattended-loop (references/unattended-loop.md) |
| Compare a screen with the decode; audit scripts; tolerances | fidelity-rules (references/fidelity-rules.md) |
| Fan out lanes, pod window, build chain, size levers, pod gotchas | speed-and-pod (references/speed-and-pod.md) |
| A faithful conversion renders or behaves differently (invisible children, clipped list, native-only reset) | unity-semantics-that-differ (references/unity-semantics-that-differ.md) |
| A ported uGUI prefab does not match the original (CanvasGroup, preserveAspect, LayoutGroup, sizeMode, press scale, RectMask2D, spec suite) | ugui-to-cocos-fidelity (references/ugui-to-cocos-fidelity.md) |
Cocos target writes
Section titled “Cocos target writes”Every prefab, scene and component change goes through the editor MCP, never through code-built nodes
(prefab-only construction). Protocol: save, then reimport, then read the result back from disk, because several
MCP calls report success while doing nothing: t1k-cocos-base-editor-mcp-truth. A feature’s TS and its editor
writes stay with one agent. Editor work is one lane at a time (one Creator, one MCP port).
Cocos standing rules
Section titled “Cocos standing rules”- UI: drop every template view, rebuild every view in the template’s format and open it through the
template’s flow; the home and loading screens must look exactly like the APK (ui-rule (
references/ui-rule.md)). - Decode first, capture what decode cannot give. A hard early gate, right after unpack and decode and before
the art and UI lanes: motion decode pass, INFERRED ledger, capture plan, then frames or a recorded
capture-decision(capture-phase (references/capture-phase.md)). Values are DECODED, CAPTURED, VIDEO-OBSERVED or INFERRED; an INFERRED value with a capturable original is a finding. - Research public gameplay video for the INFERRED remainder (core
t1k-apk-portphase 1c,video-reference-research): avideo-reference.mdledger of VIDEO-OBSERVED rows and avideo-decisionline in the plan, the Cocos delta in capture-phase (references/capture-phase.md) section 5b. - Fonts come from the original APK; animation follows the APK; polish is its own phase after layout lands.
- Done means seen: a screen or milestone is done only with a
preview-verify --ref-dir --require-refsreceipt, a closed divergence register and a reviewed batch, or an explicitunverified/unreviewed (vision down)mark (visual-verification (references/visual-verification.md)). - Playable first: the user judges by playing
develop, so the core loop is playable before breadth. - Report every finished step to Discord with images (core’s discord-progress); self-review and self-merge to
develop; the project’s own MCP port may be bumped when the MCP extension is old.
Report progress
Section titled “Report progress”A port keeps a scoreboard (progress-reporting (references/progress-reporting.md)): every feature, screen, table,
asset family, audio set, locale, platform target and verification as an item on the ladder decoded, built, wired,
live-verified, faithful, with OFF, BLOCKED and OUT-OF-SCOPE carrying a reason. After EVERY round or build:
- Update
plans/<port>/port-scoreboard.json(stages, states,nextLanes). - Run
bun .claude/skills/t1k-cocos-base-apk-port/scripts/port-progress.cjs --snapshot(add--discordfor the post). It prints the percent, per-area bars, what changed, blockers with owners and the ETA range, then appends the snapshot. - Post the
--discordoutput to the project’s status thread (core’s discord-progress, the project-status-thread rule). - Lead every status reply with the headline percent, the ETA range and the top blockers; a number the scoreboard cannot support is written UNKNOWN. Owner-gated and server-data-absent items are never counted as finishable work.
Gotchas
Section titled “Gotchas”- Never ask for a choice the plan, a decision register entry or a standing owner decision settles: pick the default
(unattended-loop (
references/unattended-loop.md)); only credentials, destructive blast radius and legal stop the loop. - Original assets first, every one wired and referenced; “unwired” is a failing gate, reskin is a later step.
- Never pipe
pod_sync --pruneintohead(SIGPIPE skipped the prune and shipped 127 stale files); PowerShell 5.1ConvertFrom-Jsonpasses an array as one object; after deleting assets purge the build copy, wipe its library and check the builtresources/config.json(speed-and-pod (references/speed-and-pod.md)). - Live checks run on a native agent; a cheap-routed tester is very slow.
Core tools this skill calls
Section titled “Core tools this skill calls”This skill ships no copy of these; each is core t1k-apk-port’s, run from its folder, and its reference holds the how.
| Step | Core tool |
|---|---|
| Phase 0 human preflight | port-preflight.cjs (--init the form, then check; exit 0 before phase 1) |
| Extract an IPA | ipa-unpack.cjs <ipa> SCR/unpacked --target cocos (the target is mandatory; exit 4 = encrypted) |
| Find anything in the extracted evidence | evidence-index.cjs build SCR after extract, lookup BEFORE any grep of SCR |
| Capture the original | scripts/capture/crawl.cjs, gold-manifest.cjs; emulator and app failure modes: device-capture (references/device-capture.md) |
| Redact capture text | python -I unity/redact_text.py before anything leaves SCR |
| Polish | parity-pass.cjs once, capped by parity-config.json; visual-verification (references/visual-verification.md) section 0 |
| Timing | port-clock.cjs mark SCR/clock.json <phase 0-8> "<note>" at the end of each phase |
Non-stop run (core workflow “Non-stop run”). After the preflight passes this skill adds no mid-run, non-destructive question: record a default as INFERRED in the plan’s “Open questions” table and keep going; park a capped screen as a known gap; ask a destructive or credential step only through the preflight’s approvals (an unapproved step is skipped and listed). The deferred questions, parked screens and skipped steps are reported once, at the end. Where a reference below says “ask” or “blocker”, read it through this rule.
Scripts
Section titled “Scripts”The source-side tools (tool-preflight, xapk-unpack, ipa-unpack, il2cpp-setup, decode_mb, resolve_refs, ui_tree_export,
tmp_style_export, il2cpp_method (ELF and iOS Mach-O method bodies, used by t1k-cocos-base-ipa-port),
video-ref-fetch, compare-image, Ghidra) are core’s t1k-apk-port. This skill ships only the UnityPy readers that
feed the Cocos effect and animation rebuild, in scripts/unity/, each taking the game-specific joins as arguments
(unity-particle-encoding (references/unity-particle-encoding.md)):
| Script | Does |
|---|---|
decode_particles.py | ParticleSystem + renderer + material of effect prefabs to byte-stable JSON |
decode_rigs_and_clips.py | rig prefabs, Animator and override controllers, every AnimationClip (unity-clip/1) |
particle_lib.py, clip_lib.py, unity_apk.py | the readers they share (pure, testable without UnityPy) |
port-progress.cjs (+ -model, -render) | scoreboard report: percent, per-area bars, blockers, ETA (progress-reporting (references/progress-reporting.md)) |
motion-segments.cjs | start, end and duration of a motion in a screen recording (capture-phase (references/capture-phase.md)) |
Run Python with python -I. The APK is untrusted data: read it, never execute it.
Reuse: link, never re-implement
Section titled “Reuse: link, never re-implement”| Need | Skill |
|---|---|
| Source side of the port | t1k-apk-port (core) |
| Cocos 2.x APK | t1k-cocos-base-apk-unbuild |
| What the video shows; finding public gameplay videos | t1k-gamedev-playable-ref-capture, t1k-gamedev-playable-ref-tools; core t1k-apk-port video-reference-research |
Promote imported art/audio into assets/ | t1k-cocos-base-asset-import |
| GLB export settings for Cocos | t1k-art-cocos-gltf-export (theonekit-art) |
A Unity .shader to a Cocos .effect | t1k-cocos-base-unity-shader-port, then t1k-cocos-base-effect-authoring |
| Prefab/scene writes over MCP, and the calls that lie | t1k-cocos-base-editor-mcp-truth, t1k-cocos-playable-tooling-gotchas |
| Prior art before any new class | t1k-cocos-base-knowledge-sweep |
| Game feature module layout | t1k-game-arch, t1k-cocos-base-clean-architecture |
Executed by
Section titled “Executed by”t1k-cocos-base-asset-porter runs art import, t1k-cocos-base-data-author the data build,
t1k-cocos-base-developer each feature’s TS plus its editor writes, t1k-cocos-base-test-writer the vitest
guards. Phase order, decisions, INFERRED calls and the parity judgment stay with the orchestrating session.