Skip to content

playablelabs-decouple-game-code

PlayableLabs: Game Code Is Decoupled From the Shared Libs

Section titled “PlayableLabs: Game Code Is Decoupled From the Shared Libs”

Advisory (a kit ships no hooks; each lib’s own CI gates the lib, and a game repo with a Cocos playableSync can call the server check The1Studio/cocos-stdlib/.github/workflows/reuse-check.yml, report mode first: it checks playableSync completeness, staleness against stdlib main, and that baselines only shrink. It has no duplicate detector (dropped after measurement) and does not apply to repos without playableSync). Standard for BOTH Cocos 3.8 and web (three.js, --engine-host web) playables. This rule only makes two core skills mandatory here; it restates neither: t1k-game-arch (game code, 4 layers, its references/module-contracts.md template) and t1k-library-decoupling (lib cores never import third-party code; interface + provider seams in opt-in bridge packages). Read them before touching game or lib code.

  1. Public API only. Game code reaches a shared lib ONLY through its public package API: no deep imports into a lib’s internals, no relative paths into a vendored copy.
  2. CPM packages, not submodules. New work consumes libs as versioned @playablelabs/* packages from cpm.playablelabs.ai. Never add a git submodule for a lib. Existing submodule games migrate per PlaybleEngine plans/decouple-game-code-from-libs.md; do not convert them ad hoc.
  3. Neutral core. A lib’s core has no cc and no three import (type-only imports included). Cocos and web adapters are separate, opt-in packages behind the lib’s interface.
  4. Automated gate. Every lib repo carries an import-graph / neutral-core CI test that computes reach from the real imports (no hand-classified list). Worked example: The1Studio/PlayableParamterTool .tests/neutral-core.test.mjs (#99). A new lib without it is not done.
  5. Cocos zero-change still applies: a Cocos customer sees no behaviour change from any of this; see rule playablelabs-cocos-zero-change.md.
  6. Adding a lib to a web/none playable (wasm base64, init gate, size budget): follow skill t1k-playablelabs-optimize-shared-libs; it is the checklist, not this rule.