Skip to content
T1KTheOneKit

code-conventions-cocos

Code Conventions — Cocos Creator / TypeScript

Section titled “Code Conventions — Cocos Creator / TypeScript”

Extends core code-conventions.md. The1Studio-specific patterns.

Naming

Section titled “Naming”
  • Classes: PascalCase with semantic suffix — Service, Component, Controller
  • Private fields: _camelCase (underscore prefix — standard TS convention)
  • Enums: PascalCase names, lowercase string values (BROWN = 'brown') for serialization
  • Interfaces: PascalCase, NO I prefix (modern TS style, not Java/C#)
  • Callbacks: on* or handle* prefix — onWeaponPlaced, handleTimerEnd
  • Constants: UPPER_SNAKE_CASE in config objects
  • Files: {Feature}{Suffix}.ts — ColorService.ts, TimerComponent.ts

Architecture

Section titled “Architecture”
  • Service: business logic, singleton — reusable utilities
  • Component: UI, extends Component — scene-attached
  • Controller: orchestration, state management
  • Singleton: private static _instance + static get instance(), set in onLoad()

SignalBus (Critical)

Section titled “SignalBus (Critical)”
  • Use signalBus.subscribe/unsubscribe() for inter-component events — NOT direct calls
  • MUST use named methods (arrow function class fields), NOT inline lambdas
  • Reason: unsubscribe() uses indexOf() — lambdas create new refs each call
  • Unsubscribe in onDestroy() — always clean up

Decorators

Section titled “Decorators”
  • @ccclass('ClassName') on every component class
  • @property(Type) for editor-exposed fields only
  • Destructure at top: const { ccclass, property } = _decorator;

Patterns

Section titled “Patterns”
  • Guard clauses for null safety — early return, not nested conditions
  • readonly for config values — prevents runtime mutation
  • Extract magic numbers to GameConfig or local const
  • Lifecycle order: onLoad → onEnable → start → update → onDestroy

File Organization

Section titled “File Organization”
assets/scripts/{ProjectName}/
├── services/    # Business logic singletons
├── parameter/   # Config management
├── UI/          # UI components and controllers
├── utils/       # Static utility classes
├── constant/    # Named constants
├── Data/        # Models, enums, configs
└── Signal/      # Signal class definitions + shared signalBus export

Living Document

Section titled “Living Document”

If unsure about a convention not covered here, ask the user for their preference and update this file with the answer. Conventions grow from real decisions.