Skip to content

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.

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.

Service = business logic, singleton · Component = extends Component, scene-attached UI · Controller = orchestration/state · Singleton = private static _instance + static get instance(), set in onLoad().

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().

@ccclass('ClassName') on every component class · @property(Type) only for editor-exposed fields · destructure once: const { ccclass, property } = _decorator;.

Guard clauses over nesting · readonly for config values · magic numbers in GameConfig or a local const · lifecycle order onLoad → onEnable → start → update → onDestroy.

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

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

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.