code-conventions-cocos
Code Conventions (Cocos Creator / TypeScript)
Section titled “Code Conventions (Cocos Creator / TypeScript)”Extends core code-conventions.md. The always-loaded prohibition set; rationale and recipes:
docs/code-conventions-cocos.md.
Naming
Section titled “Naming”PascalCase + semantic suffix (Service/Component/Controller) · private fields _camelCase
(mandatory) · enums PascalCase, lowercase string values (BROWN = 'brown') · interfaces
PascalCase, no I prefix · callbacks on*/handle* · constants UPPER_SNAKE_CASE · files
{Feature}{Suffix}.ts. A reusable framework type never bakes in a game/demo name.
Architecture
Section titled “Architecture”Service = business logic, singleton · Component = extends Component, scene-attached UI ·
Controller = orchestration/state · Singleton = private static _instance +
static get instance(), set in onLoad().
SignalBus (Critical)
Section titled “SignalBus (Critical)”signalBus.subscribe/unsubscribe() for inter-component events, never direct calls. MUST use
named methods (arrow-function class fields), never inline lambdas: unsubscribe() uses
indexOf(), so a lambda never matches. Unsubscribe in onDestroy().
Decorators
Section titled “Decorators”@ccclass('ClassName') on every component class · @property(Type) only for editor-exposed
fields · destructure once: const { ccclass, property } = _decorator;.
Patterns
Section titled “Patterns”Guard clauses over nesting · readonly for config values · magic numbers in GameConfig or a
local const · lifecycle order onLoad → onEnable → start → update → onDestroy.
Release build ≠ editor preview
Section titled “Release build ≠ editor preview”[...x] over a non-array (Map, Set, iterator, matchAll, arguments, NodeList) mis-serializes
in release only; no unit test catches it. MUST use Array.from(x) (spread stays fine on arrays
and object literals). MUST NOT iterate a reassigned let array in the release/CLI build. The
required gate is t1k-cocos-base-source-scan-guard (--changed); ESLint
no-restricted-syntax only with an ESLint config. Full mechanism: docs/code-conventions-cocos.md
§ “Release build ≠ editor preview”.
Feature modules & testability
Section titled “Feature modules & testability”A game feature module MUST NOT use the playable-ad by-type layout; use the vertical feature
module from t1k-game-arch, specialized by t1k-cocos-base-clean-architecture. It ships with its
own tests and keeps game logic outside cc.Component. Reasoning: docs/code-conventions-cocos.md
§ “Feature modules & testability”.
Colocated tests must be dot-prefixed
Section titled “Colocated tests must be dot-prefixed”Cocos imports every .ts under assets/, so a colocated tests/ ships and kills preview on
boot. .tests/ is invisible to the asset-db instead. Detail: docs/colocated-tests-cocos.md.
If unsure about a convention not covered here, ask the user and update this rule with the answer.