# Cocos Creator Dev

> Cocos Creator 3.x Development Guide

- Skill: `wanghaisheng/cocos-creator-dev` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add wanghaisheng/cocos-creator-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wanghaisheng/cocos-creator-dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wanghaisheng (https://skillmd.com/u/wanghaisheng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wanghaisheng/cocos-creator-dev

---


# Cocos Creator 3.x Development Guide

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

## Quick Start

### Basic Component Template

```typescript
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:**
```typescript
this.node.addComponent(MyComponent);
```

**Get component:**
```typescript
const comp = this.node.getComponent(MyComponent);
```

**Load scene:**
```typescript
director.loadScene('SceneName');
```

**Load resource:**
```typescript
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](references/script-basics.md) - TypeScript setup, decorators, class definitions, property declarations
- **Component System**: [references/component-system.md](references/component-system.md) - Lifecycle methods, component management, execution order
- **Node & Hierarchy**: [references/node-hierarchy.md](references/node-hierarchy.md) - Node creation, traversal, transformations, coordinate systems
- **Scene Management**: [references/scene-management.md](references/scene-management.md) - Scene loading, persist nodes, preloading
- **Resource Management**: [references/resource-management.md](references/resource-management.md) - Asset loading, releasing, Asset Bundles, memory management
- **Event System**: [references/event-system.md](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.