Skip to content

t1k:cocos:base:engine-decouple

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

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

  • A game file (PLA first) outside engine/cocos/ imports cc (the gate says RISE), 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.

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 logic

logic/ may be spelled game/; the gate only knows engine/cocos/. Full layout, the composition root, and the new-game scaffold: references/target-layout.md.

PortLogic seesCocos adapter wraps
render / nodegame-shaped view (SnakeView.moveTo(cells))Node, MeshRenderer, instantiate(prefab)
inputcalls INTO logic (onTap(cell))input.on(Input.EventType…), EventTouch
audioplay(sfx: SfxId)AudioSource
tweenanimate(handle, spec): Promise<void>tween()
physicsraycastGround(screen): Vec3 | nullPhysicsSystem, geometry.Ray
timernow(), after(sec, fn); prefer update(dt) from the shellschedule, director
assetloadLevel(id): Promise<LevelRaw>resources.load, JsonAsset
CTA / SDKopenStore(), gameEnd()PLAGameFoundation SDK, CTAService
parameter toola plain GameConfig object, read oncePlayableParamterTool (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.

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.

  1. Adopt the gate. bun <skill>/scripts/check-cc-imports.cjs <cocos-root> --init, commit the baseline alone. From now on nothing new may couple.
  2. Pick the next file — the leaf with the fewest cc symbols first (a Vec2-only model beats a Component). --json lists every file with its import forms and lines.
  3. Characterize its behaviour before touching it: a Node unit test for already-pure code, or a golden via t1k-cocos-playable-characterization for a module.
  4. Extract: value types → logic/math/; engine calls → a port the logic declares; the pure rules → logic/. A cc.Component shell keeps its uuid: git mv the .ts AND its .ts.meta together into engine/cocos/, keep every @property on it, and make it forward to logic.
  5. Adapter per port in engine/cocos/, wired by the composition root.
  6. Verify: the characterization replays identically, the project compiles (t1k-cocos-playable-mechanic-split/scripts/tsc-gate.sh when the playable module is installed, otherwise the project’s own tsc --noEmit), then --prune removes 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 the PARAM_CANARY build 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.

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 --json output IS the work queue: violations[].file and forms[] 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.json by hand except to rename a git 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.
Terminal window
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.

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

StepAgent
Run the gate / --init / --prune, report rise/fallt1k-tester (cheap)
Characterize, extract, write ports and adapterst1k-cocos-base-developer (reasoning tier, stays non-cheap)
Review a decoupling PR (shell thinness, port shape)t1k-cocos-base-reviewer (reasoning tier)

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.

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)