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.