Skip to content

t1k:cocos:base:apk-port

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

/t1k:cocos:base:apk-port
<file.xapk|file.apk> [--video <url>] [--phase setup|extract|video|plan|data|art|lanes|polish|verify]

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

IntentPath
Start a new portcore 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.xt1k-cocos-base-apk-unbuild
The build is an iOS IPAcore 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 stylescore 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 stubunity-odin-and-il2cpp-v39 (references/unity-odin-and-il2cpp-v39.md)
Generate the data tables + TS typesdata-build (references/data-build.md)
Port 3D/2D art, fonts, audio; the map looks grey or washed; particles and trailsart-and-colour (references/art-and-colour.md)
Decode Unity ParticleSystems, gradients, rigs, Animator controllers or AnimationClips with UnityPyunity-particle-encoding (references/unity-particle-encoding.md), scripts/unity/
Play a swapped GLB’s clipsanimation-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 gatecapture-phase (references/capture-phase.md)
Prove a screen matches the APK: the one capped parity pass, reference set, gate, receipt, divergence registervisual-verification (references/visual-verification.md)
Interrupted, stalled or misrouted lane; a blank device capturelane-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 reachablesource-guards (references/source-guards.md)
A sliced sprite fails to build next to an edge widgetsliced-sprite-fit (references/sliced-sprite-fit.md)
How far along is the port, when will it be done, the status postprogress-reporting (references/progress-reporting.md)
Run the whole port unattended: loop, what the agent decides, what may stop itunattended-loop (references/unattended-loop.md)
Compare a screen with the decode; audit scripts; tolerancesfidelity-rules (references/fidelity-rules.md)
Fan out lanes, pod window, build chain, size levers, pod gotchasspeed-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)

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

  • 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-port phase 1c, video-reference-research): a video-reference.md ledger of VIDEO-OBSERVED rows and a video-decision line 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-refs receipt, a closed divergence register and a reviewed batch, or an explicit unverified / 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.

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:

  1. Update plans/<port>/port-scoreboard.json (stages, states, nextLanes).
  2. Run bun .claude/skills/t1k-cocos-base-apk-port/scripts/port-progress.cjs --snapshot (add --discord for the post). It prints the percent, per-area bars, what changed, blockers with owners and the ETA range, then appends the snapshot.
  3. Post the --discord output to the project’s status thread (core’s discord-progress, the project-status-thread rule).
  4. 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.
  • 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 --prune into head (SIGPIPE skipped the prune and shipped 127 stale files); PowerShell 5.1 ConvertFrom-Json passes an array as one object; after deleting assets purge the build copy, wipe its library and check the built resources/config.json (speed-and-pod (references/speed-and-pod.md)).
  • Live checks run on a native agent; a cheap-routed tester is very slow.

This skill ships no copy of these; each is core t1k-apk-port’s, run from its folder, and its reference holds the how.

StepCore tool
Phase 0 human preflightport-preflight.cjs (--init the form, then check; exit 0 before phase 1)
Extract an IPAipa-unpack.cjs <ipa> SCR/unpacked --target cocos (the target is mandatory; exit 4 = encrypted)
Find anything in the extracted evidenceevidence-index.cjs build SCR after extract, lookup BEFORE any grep of SCR
Capture the originalscripts/capture/crawl.cjs, gold-manifest.cjs; emulator and app failure modes: device-capture (references/device-capture.md)
Redact capture textpython -I unity/redact_text.py before anything leaves SCR
Polishparity-pass.cjs once, capped by parity-config.json; visual-verification (references/visual-verification.md) section 0
Timingport-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.

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)):

ScriptDoes
decode_particles.pyParticleSystem + renderer + material of effect prefabs to byte-stable JSON
decode_rigs_and_clips.pyrig prefabs, Animator and override controllers, every AnimationClip (unity-clip/1)
particle_lib.py, clip_lib.py, unity_apk.pythe 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.cjsstart, 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.

NeedSkill
Source side of the portt1k-apk-port (core)
Cocos 2.x APKt1k-cocos-base-apk-unbuild
What the video shows; finding public gameplay videost1k-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 Cocost1k-art-cocos-gltf-export (theonekit-art)
A Unity .shader to a Cocos .effectt1k-cocos-base-unity-shader-port, then t1k-cocos-base-effect-authoring
Prefab/scene writes over MCP, and the calls that liet1k-cocos-base-editor-mcp-truth, t1k-cocos-playable-tooling-gotchas
Prior art before any new classt1k-cocos-base-knowledge-sweep
Game feature module layoutt1k-game-arch, t1k-cocos-base-clean-architecture

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.