t1k:cocos:base:engine-decouple
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | high |
| Tools | — |
Keywords: cc import gate, cc-import baseline, decouple from cc, engine decouple, engine/cocos adapter, logic imports cc, move off cocos, pla composition root, ports and own math
How to invoke
Section titled “How to invoke”/t1k:cocos:base:engine-decouple[<cocos-root>] [--init | --prune] [--file <path>]Cocos Engine Decouple — Ports + Own Math
Section titled “Cocos Engine Decouple — Ports + Own Math”The boundary (decided, not a preference): game logic imports NOTHING from 'cc' — not Vec3,
not Color, not a type. It uses the game’s own tiny value types and math, and talks to the engine
only through ports (interfaces) for render/node, input, audio, tween, physics, timer, asset,
CTA/SDK and the parameter tool. Only engine/cocos/ may import 'cc'. That is what makes the logic
unit-testable in Node, reusable across PLAs, and movable off Cocos later.
The enforcement: the always-loaded rule engine-decouple-cocos.md (this module; loads for every Cocos project, enforcement opt-in via cc-import-baseline.json) plus the
ratchet gate scripts/check-cc-imports.cjs. Each game pins its legacy cc-importing files by
path in cc-import-baseline.json; the list may only shrink. New violations fail; fixed ones fail
until removed; old ones are refactored game by game with this skill.
When to use
Section titled “When to use”- A game file (PLA first) outside
engine/cocos/importscc(the gate saysRISE), or you are shrinking a game’s baseline. - Scaffolding a NEW game (PLA or otherwise) or a new mechanic inside one — start in the target layout, baseline
[]. - Adopting the gate on a Cocos repo for the first time (
--init).
Not for: a packages/* library in a pnpm workspace (→ t1k-cocos-base-engine-free-package,
the same doctrine one level down) · moving a mechanic into its own folder without touching cc
(→ t1k-cocos-playable-mechanic-split) · long-lived, non-PLA features that want the full 4-layer
model (→ t1k-cocos-base-clean-architecture, core t1k-game-arch) · a third-party SDK seam inside a
library (→ core t1k-library-decoupling). This skill REUSES those: narrow local interfaces and
constructor-arg composition from engine-free-package, the uuid-safe shell split from mechanic-split,
the golden gate from t1k-cocos-playable-characterization.
Target layout
Section titled “Target layout”assets/scripts/<Game>/├── logic/ pure TS: rules, state, models. No 'cc'. Unit-tested in Node.│ └── math/ the game's own value types (Vec2, Vec3, Color…) — see references/value-types.md├── ports/ interfaces the logic needs, named in the GAME's words (SnakeView, not Node)├── engine/cocos/ the ONLY place 'cc' is imported: adapters implementing ports, and the│ cc.Component shells scenes/prefabs reference (thin: forward, never decide)└── <Game>Root.ts composition root — lives in engine/cocos/, builds adapters, injects into logiclogic/ may be spelled game/; the gate only knows engine/cocos/. Full layout, the composition
root, and the new-game scaffold: references/target-layout.md.
The ports
Section titled “The ports”| Port | Logic sees | Cocos adapter wraps |
|---|---|---|
| render / node | game-shaped view (SnakeView.moveTo(cells)) | Node, MeshRenderer, instantiate(prefab) |
| input | calls INTO logic (onTap(cell)) | input.on(Input.EventType…), EventTouch |
| audio | play(sfx: SfxId) | AudioSource |
| tween | animate(handle, spec): Promise<void> | tween() |
| physics | raycastGround(screen): Vec3 | null | PhysicsSystem, geometry.Ray |
| timer | now(), after(sec, fn); prefer update(dt) from the shell | schedule, director |
| asset | loadLevel(id): Promise<LevelRaw> | resources.load, JsonAsset |
| CTA / SDK | openStore(), gameEnd() | PLAGameFoundation SDK, CTAService |
| parameter tool | a plain GameConfig object, read once | PlayableParamterTool (ParameterManager) |
Ports are narrow and game-shaped, declared by the logic that calls them. A port that mirrors the
cc.Node API has re-imported cc by another name. Signatures and adapter sketches:
references/port-catalogue.md.
Own math and value types
Section titled “Own math and value types”Scalar math (clamp, lerp, remap, approx-equal) comes from @playablelabs/core-utils
(cocos-stdlib, installed via playableSync). Vector/colour value types have no canonical stdlib
package yet — four structural copies exist (Vec2Like, Vec3Like, Point2, Rgba). Until the
proposed @playablelabs/core-math lands, the game keeps them in logic/math/, structurally identical
so the later swap is an import-path change. Details and the contribution follow-up:
references/value-types.md.
This skill runs in the caller’s session (no context: fork)
Section titled “This skill runs in the caller’s session (no context: fork)”effort: high with no context:, deliberately (#1582). The playbook below is an apply — it
moves files, writes ports and adapters, and edits the baseline commit by commit — and the agent that
loads it, t1k-cocos-playable-feel-developer, is itself the implementer of the same tree. A forked
body runs in a fresh subagent with its own tool pool, so the caller and the fork would both be writing
engine/cocos/. The gate run (--init / --prune) is cheap and mechanical, but it is the same
skill’s step 1, so it cannot be split off into a fork either.
Invoked with Skill, the body loads into the caller’s session and the caller stays the single
writer — which is also how this skill’s own Executed by table already assumes work runs: aggregate
on the cheap tier, decide and edit on the reasoning tier that is already in the room.
Refactor an existing game — the playbook
Section titled “Refactor an existing game — the playbook”Characterize, then move logic out, then shrink the baseline. One file (or one tight cluster) per
commit. Full steps, commands and stop conditions: references/refactor-playbook.md.
- Adopt the gate.
bun <skill>/scripts/check-cc-imports.cjs <cocos-root> --init, commit the baseline alone. From now on nothing new may couple. - Pick the next file — the leaf with the fewest
ccsymbols first (aVec2-only model beats aComponent).--jsonlists every file with its import forms and lines. - Characterize its behaviour before touching it: a Node unit test for already-pure code, or a
golden via
t1k-cocos-playable-characterizationfor a module. - Extract: value types →
logic/math/; engine calls → a port the logic declares; the pure rules →logic/. Acc.Componentshell keeps its uuid:git mvthe.tsAND its.ts.metatogether intoengine/cocos/, keep every@propertyon it, and make it forward to logic. - Adapter per port in
engine/cocos/, wired by the composition root. - Verify: the characterization replays identically, the project compiles
(
t1k-cocos-playable-mechanic-split/scripts/tsc-gate.shwhen the playable module is installed, otherwise the project’s owntsc --noEmit), then--pruneremoves the fixed entries and the gate is green. Before merge, the Jenkins test build smokes every emitted network row green (34/34 on a full matrix) and thePARAM_CANARYbuild passes.
An adapter holds no game rules. Moving a thick component into engine/cocos/ unchanged shrinks
the baseline and decouples nothing. Measure the shell with t1k-cocos-playable-reuse-coverage --cc-thickness; a shell that still decides anything is not done.
Scaffolding a new game
Section titled “Scaffolding a new game”Start in the target layout with an empty baseline (--init on a tree with no cc outside
engine/cocos/ writes "files": []). Every mechanic starts as logic/ + the ports it needs + one
adapter each. Prefabs and scenes are still authored in the editor (prefab-only-construction-cocos.md):
adapters bind to editor-assigned @property refs and instantiate(prefab); they never build nodes.
AI-first operation (running this on any of the 87 PLA repos)
Section titled “AI-first operation (running this on any of the 87 PLA repos)”- One file or one tight cluster per sub-agent brief, ≤3 findings per brief; the brief names the worktree, the file, the ports to add, and the verify commands.
- The gate’s
--jsonoutput IS the work queue:violations[].fileandforms[]with line numbers. Never re-derive it by grep. - Stop and hand back when a file needs a design decision (a port shape the game has not seen before,
a mechanic spanning 4+ files). Record the decision in the game’s
docs/, then continue. - Never edit
cc-import-baseline.jsonby hand except to rename agit mv’d path. Never add a path. - Vendored code (submodules such as PLAGameFoundation / PlayableParamterTool, installed
assets/packages/) is reported, not gated — fix it upstream, never in the game.
The gate
Section titled “The gate”bun ~/.claude/skills/t1k-cocos-base-engine-decouple/scripts/check-cc-imports.cjs <cocos-root> [--json]Exit 0 pass · 1 rise or fall · 2 unverifiable (no baseline, zero .ts, malformed baseline) —
never a pass. Baseline: <cocos-root>/cc-import-baseline.json, git-tracked, outside assets/.
Flags, forms detected, exemptions, and how it is wired into Jenkins and PR CI:
references/gate-and-wiring.md.
Executed by
Section titled “Executed by”Running the gate and replaying goldens are mechanical and need no judgment; choosing port shapes and
splitting a component are design work and stay with the implementer. Routing SSOT:
theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run the gate / --init / --prune, report rise/fall | t1k-tester (cheap) |
| Characterize, extract, write ports and adapters | t1k-cocos-base-developer (reasoning tier, stays non-cheap) |
| Review a decoupling PR (shell thinness, port shape) | t1k-cocos-base-reviewer (reasoning tier) |
Worked example
Section titled “Worked example”SnakeGoPLA GridModel.ts — a “pure-logic model” that still imports Vec2/Vec3 from cc — taken
to zero cc imports, plus the InputController raycast behind a physics port:
references/worked-example-snakego.md.
Related
Section titled “Related”t1k-cocos-base-engine-free-package · t1k-cocos-playable-mechanic-split ·
t1k-cocos-playable-characterization · t1k-cocos-playable-reuse-coverage (--cc-thickness) ·
t1k-cocos-base-clean-architecture · core t1k-game-arch, t1k-library-decoupling ·
theonekit-core/.claude/modules/t1k-verification/rules/pinned-baseline-test-companion.md (why the gate fails in both directions)