Cocos Creator 3.x Development Guide

Guide for Cocos Creator 3.x game development using TypeScript.

Quick Start

Basic Component Template

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('MyComponent')
export class MyComponent extends Component {
    @property(Node)
    targetNode: Node = null;

    @property
    speed: number = 10;

    onLoad() {
        // Initialization
    }

    start() {
        // First frame update
    }

    update(deltaTime: number) {
        // Per-frame update
    }
}

Common Operations

Add component dynamically:

this.node.addComponent(MyComponent);

Get component:

const comp = this.node.getComponent(MyComponent);

Load scene:

director.loadScene('SceneName');

Load resource:

resources.load('textures/sprite', SpriteFrame, (err, asset) => {
    this.node.getComponent(Sprite).spriteFrame = asset;
});

Reference Documentation

For detailed information on specific topics, consult these reference files:

• •Script Basics: references/script-basics.md - TypeScript setup, decorators, class definitions, property declarations
• •Component System: references/component-system.md - Lifecycle methods, component management, execution order
• •Node & Hierarchy: references/node-hierarchy.md - Node creation, traversal, transformations, coordinate systems
• •Scene Management: references/scene-management.md - Scene loading, persist nodes, preloading
• •Resource Management: references/resource-management.md - Asset loading, releasing, Asset Bundles, memory management
• •Event System: references/event-system.md - Input handling, custom events, node events

Development Guidelines

Version Check

Always confirm the user is working with Cocos Creator 3.x, not 2.x. APIs and workflows differ significantly.

Code Style

• •Use TypeScript exclusively (JavaScript not supported in 3.x)
• •Follow decorator pattern: @ccclass, @property
• •Use type annotations for all properties
• •Prefer this.node for current node access

Performance Best Practices

• •Release unused resources with assetManager.releaseAsset()
• •Use object pooling for frequently created/destroyed nodes
• •Cache component references instead of repeated getComponent() calls
• •Use scheduleOnce instead of timers for one-time delays

Common Pitfalls

• •Lifecycle order: onLoad → start → update. Don't access other components in onLoad if they might not be ready.
• •Resource leaks: Always release dynamically loaded assets
• •Node activation: Check node.active before accessing components
• •Scene switching: Use persist nodes for data that needs to survive scene changes

Key APIs Reference

Node Operations

• •this.node - Current node
• •this.node.parent - Parent node
• •this.node.children - Child nodes array
• •this.node.addChild(child) - Add child node
• •this.node.removeFromParent() - Remove from parent
• •this.node.destroy() - Destroy node
• •this.node.setPosition(x, y, z) - Set position
• •this.node.setRotation(x, y, z) - Set rotation
• •this.node.setScale(x, y, z) - Set scale

Component Operations

• •this.node.addComponent(T) - Add component
• •this.node.getComponent(T) - Get component
• •this.getComponentInChildren(T) - Get component in children
• •this.getComponentsInChildren(T) - Get all components in children

Scene Operations

• •director.loadScene(name) - Load scene
• •director.preloadScene(name) - Preload scene
• •director.getScene() - Get current scene
• •game.addPersistRoot(node) - Add persist node
• •game.removePersistRoot(node) - Remove persist node

Resource Operations

• •resources.load(path, type, callback) - Load resource
• •assetManager.loadRemote(url, type, callback) - Load remote resource
• •assetManager.releaseAsset(asset) - Release resource
• •resources.loadDir(path, type, callback) - Load directory

Event Operations

• •this.node.on(type, callback, target) - Register event
• •this.node.off(type, callback, target) - Unregister event
• •this.node.emit(type, detail) - Emit event
• •input.on(type, callback, target) - Register input event

External Resources

• •Official Manual: https://docs.cocos.com/creator/3.8/manual/zh/
• •API Reference: https://docs.cocos.com/creator/3.8/api/zh/
• •Example Projects: https://github.com/cocos/cocos-example-projects

Troubleshooting

Component Not Found

• •Verify component is attached in editor
• •Check node is active: if (this.node.active)
• •Use getComponentInChildren() for nested components

Scene Not Loading

• •Check scene name in Build Settings
• •Verify scene is added to build
• •Use preloadScene() for large scenes

Memory Leaks

• •Release assets after use
• •Destroy unused nodes
• •Remove event listeners in onDestroy
• •Use Asset Bundles for modular loading

Performance Issues

• •Profile with Chrome DevTools
• •Reduce draw calls with batching
• •Use object pooling
• •Optimize sprite atlases
• •Check script execution time in updates

When to Read References

Read specific reference files when:

• •script-basics.md: Creating new components, defining properties, configuring TypeScript
• •component-system.md: Implementing lifecycle callbacks, managing component dependencies
• •node-hierarchy.md: Creating/destroying nodes, building scene hierarchy, coordinate transformations
• •scene-management.md: Loading scenes, passing data between scenes, managing game flow
• •resource-management.md: Loading assets, managing memory, using Asset Bundles
• •event-system.md: Handling user input, implementing custom events, component communication

Decision Guide

Multiple valid approaches? Use high freedom - provide options and let context guide choice.

Standard pattern exists? Use medium freedom - provide template code with parameters.

Error-prone operation? Use low freedom - provide specific, validated code pattern.