engine-decouple-cocos
Engine Decouple: Game Logic Never Imports cc
Section titled “Engine Decouple: Game Logic Never Imports cc”Scope: the game’s own TypeScript under
assets/in any Cocos project — playable ads (PLA) are the primary example, but the boundary is the same for every Cocos game. How to do it — ports, own math, adapters, the refactor playbook: skillt1k-cocos-base-engine-decouple.
- MUST NOT import
'cc'outsideengine/cocos/— no form: named, default,* as cc,import type,require, dynamicimport(),cc/env, or the globalcc.. That includesVec2,Vec3,Colorand types. Logic uses the game’s own value types and talks to the engine through ports; onlyengine/cocos/adapters and component shells touchcc. - New code complies. No exceptions, no new baseline entries. A file you create or a file not in
the baseline that gains a
ccimport is fixed in code, never pinned. - Old code is ratcheted down.
cc-import-baseline.jsonpins each legacy violator by path and may only shrink. When you touch a baselined file, leave it no more coupled; when you fix one, remove its entry (--prune). Never re-pin, never--initover an existing baseline. - Run the gate before claiming a change done — in a project that has opted in (a
cc-import-baseline.jsonexists in the cocos root):bun ~/.claude/skills/t1k-cocos-base-engine-decouple/scripts/check-cc-imports.cjs <cocos-root>— exit 0 only. Exit 2 (nothing scanned, malformed baseline) is not a pass.
Enforcement is opt-in per project. The kit ships no hook, checkpoint or CI step that runs the
gate; this rule loads for every Cocos project but never fails one. A project that has no
cc-import-baseline.json has not adopted the gate: do not run it, do not create the baseline
unasked (--init pins every current violator and is a deliberate adoption step), and do not report
the missing baseline as a failure. Still write new code to the boundary above. Once the baseline is
committed, every rule here binds.
Carve-outs: vendored submodules (PLAGameFoundation, PlayableParamterTool, …) and installed
assets/packages/ are reported, not gated — fix them upstream. Editor extensions outside assets/.
Does not relax prefab-only-construction-cocos.md: adapters bind editor-assigned @property
refs and instantiate(prefab); they never build nodes in code.