Skip to content

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: skill t1k-cocos-base-engine-decouple.

  • MUST NOT import 'cc' outside engine/cocos/ — no form: named, default, * as cc, import type, require, dynamic import(), cc/env, or the global cc.. That includes Vec2, Vec3, Color and types. Logic uses the game’s own value types and talks to the engine through ports; only engine/cocos/ adapters and component shells touch cc.
  • New code complies. No exceptions, no new baseline entries. A file you create or a file not in the baseline that gains a cc import is fixed in code, never pinned.
  • Old code is ratcheted down. cc-import-baseline.json pins 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 --init over an existing baseline.
  • Run the gate before claiming a change done — in a project that has opted in (a cc-import-baseline.json exists 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.