cocos-creator-v3

Cocos Creator 3.8 开发指导技能

元信息 (Frontmatter)

• 技能名称: cocos-creator-3x-cn
• 适用引擎: Cocos Creator 3.8 (LTS)
• 语言: TypeScript (ES Module, import { ... } from 'cc')
• 官方文档: https://docs.cocos.com/creator/3.8/manual/zh/
• API 参考: https://docs.cocos.com/creator/3.8/api/zh/

---

快速参考 — 与 2.x 的核心差异

项目	2.x 写法	3.8 写法
导入	const { ccclass } = cc._decorator	import { _decorator } from 'cc'; const { ccclass } = _decorator;
组件基类	cc.Component	Component (从 'cc' 导入)
节点类	cc.Node	Node (从 'cc' 导入)
调试宏	CC_DEBUG	import { DEBUG } from 'cc/env';
全局事件	cc.systemEvent	import { input, Input } from 'cc';
资源加载	cc.resources.load()	import { resources } from 'cc'; resources.load()
缓动	cc.tween()	import { tween } from 'cc'; tween()
实例化	cc.instantiate()	import { instantiate } from 'cc';
场景管理	cc.director	import { director } from 'cc';
属性类型	cc.Integer	import { CCInteger } from 'cc';

---

1. 组件系统 (Component System)

1.1 基础组件模板

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

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

    @property
    private readonly speed: number = 10;

    // 生命周期见 §2
    protected onLoad(): void { }
    protected start(): void { }
    protected update(dt: number): void { }
    protected onDestroy(): void { }
}

1.2 装饰器速查

装饰器	说明	示例
@ccclass('Name')	注册 cc 类（名称全局唯一）	@ccclass('Player')
@property	序列化属性	@property speed = 10;
@property(Type)	指定类型	@property(Node) target: Node = null!;
@property({type: [Node]})	数组类型	children: Node[] = [];
@integer	整数类型简写	@integer count = 0;
@float	浮点类型简写	@float ratio = 1.0;
@type(T)	类型简写	@type(Node) target = null;
@executeInEditMode	编辑器模式执行	@executeInEditMode(true)
@requireComponent(T)	依赖组件	@requireComponent(Sprite)
@executionOrder(n)	执行优先级	@executionOrder(-1)
@disallowMultiple	禁止重复添加	@disallowMultiple(true)
@menu('path')	添加到组件菜单	@menu('Custom/MyComp')

1.3 属性参数

@property({
    type: Node,
    visible: true,
    displayName: '目标节点',
    tooltip: '要跟随的目标',
    serializable: true,
    group: { name: '基础设置' },
})
targetNode: Node | null = null;

常用参数: type, visible, displayName, tooltip, serializable, readonly, min, max, step, range, slide, group, override, formerlySerializedAs, editorOnly

---

2. 生命周期回调

执行顺序：onLoad → onEnable → start → update / lateUpdate → onDisable → onDestroy

 ┌─────────┐   ┌──────────┐   ┌───────┐   ┌────────┐
 │ onLoad  │──▶│ onEnable │──▶│ start │──▶│ update │──┐
 └─────────┘   └──────────┘   └───────┘   └────────┘  │
                                              ▲         │
                                              └─────────┘
                                           ┌────────────┐
                                           │ lateUpdate │
                                           └────────────┘
                                                 │
                                           ┌───────────┐   ┌─────────────┐
                                           │ onDisable │──▶│ onDestroy   │
                                           └───────────┘   └─────────────┘

回调	触发时机	典型用途
onLoad()	节点首次激活时（仅一次）	初始化引用、获取组件
onEnable()	组件启用时	注册事件监听
start()	第一次 update 之前（仅一次）	需要依赖其他组件 onLoad 完成
update(dt)	每帧调用	游戏逻辑、移动
lateUpdate(dt)	所有 update 后	跟随相机、后处理
onDisable()	组件禁用时	取消事件监听
onDestroy()	节点销毁时	资源释放、清理

关键规则:

• onLoad 中可确保节点已挂载到节点树
• 同一节点上组件的 onLoad/onEnable/start 按组件面板顺序执行，可通过 @executionOrder 控制
• onEnable/onDisable 配对使用：注册/注销事件监听
• onDestroy 中应释放所有动态加载资源的引用

---

3. 事件系统

3.1 自定义事件 (EventTarget)

import { EventTarget } from 'cc';

// 创建全局事件总线
const eventTarget = new EventTarget();

// 监听
eventTarget.on('game-over', (score: number) => {
    console.log('Game Over, score:', score);
});

// 发射（最多 5 个参数）
eventTarget.emit('game-over', 100);

// 取消监听
eventTarget.off('game-over', callback, target);

⚠️ 注意: 不再推荐通过 Node 对象做自定义事件监听与发射。

3.2 全局输入事件 (input)

import { _decorator, Component, input, Input, EventTouch, EventKeyboard, KeyCode } from 'cc';

@ccclass('InputExample')
export class InputExample extends Component {
    protected onEnable(): void {
        input.on(Input.EventType.TOUCH_START, this.onTouchStart, this);
        input.on(Input.EventType.KEY_DOWN, this.onKeyDown, this);
    }
    protected onDisable(): void {
        input.off(Input.EventType.TOUCH_START, this.onTouchStart, this);
        input.off(Input.EventType.KEY_DOWN, this.onKeyDown, this);
    }
    private onTouchStart(event: EventTouch): void {
        console.log(event.getLocation());     // 屏幕坐标
        console.log(event.getUILocation());   // UI 坐标
    }
    private onKeyDown(event: EventKeyboard): void {
        if (event.keyCode === KeyCode.SPACE) { /* ... */ }
    }
}

全局输入事件类型:

类别	事件类型
触摸	TOUCH_START, TOUCH_MOVE, TOUCH_END, TOUCH_CANCEL
鼠标	MOUSE_DOWN, MOUSE_MOVE, MOUSE_UP, MOUSE_WHEEL
键盘	KEY_DOWN, KEY_PRESSING, KEY_UP
重力	DEVICEMOTION

3.3 节点事件

// UI 节点触摸（需要 UITransform 组件）
this.node.on(Node.EventType.TOUCH_START, (event: EventTouch) => {
    event.propagationStopped = true; // 阻止冒泡
}, this);

// 使用捕获阶段
this.node.on(Node.EventType.TOUCH_START, callback, this, true);

// 事件穿透（v3.4+）
private onTouchStart(event: EventTouch): void {
    event.preventSwallow = true; // 阻止事件被吞噬
}

3.4 自定义节点事件派发

import { Event } from 'cc';

class MyEvent extends Event {
    public readonly detail: unknown;
    constructor(name: string, bubbles?: boolean, detail?: unknown) {
        super(name, bubbles);
        this.detail = detail;
    }
}

// 派发事件（支持冒泡/捕获）
this.node.dispatchEvent(new MyEvent('custom-event', true, { data: 123 }));

---

4. 资源管理 (Asset Manager)

4.1 resources 加载

import { resources, Prefab, SpriteFrame, Texture2D, instantiate, Sprite } from 'cc';

// 加载 Prefab
resources.load('prefabs/enemy', Prefab, (err, prefab) => {
    const node = instantiate(prefab);
    this.node.addChild(node);
});

// 加载 SpriteFrame（注意路径到子资源）
resources.load('images/bg/spriteFrame', SpriteFrame, (err, sf) => {
    this.getComponent(Sprite)!.spriteFrame = sf;
});

// 批量加载
resources.loadDir('textures', Texture2D, (err, assets) => { /* ... */ });

// 预加载
resources.preload('images/bg/spriteFrame', SpriteFrame);

4.2 Asset Bundle

import { assetManager, Prefab } from 'cc';

// 加载 Bundle
assetManager.loadBundle('gameBundle', (err, bundle) => {
    // 加载 Bundle 中的资源
    bundle.load('prefabs/player', Prefab, (err, prefab) => { /* ... */ });
    // 批量加载
    bundle.loadDir('textures', (err, assets) => { /* ... */ });
    // 加载场景
    bundle.loadScene('level1', (err, scene) => {
        director.runScene(scene);
    });
});

// 获取已加载的 Bundle
const bundle = assetManager.getBundle('gameBundle');

4.3 资源释放

import { assetManager, resources, SpriteFrame } from 'cc';

// 方式一：直接释放
assetManager.releaseAsset(asset);

// 方式二：通过 Bundle 释放
bundle.release('image', SpriteFrame);
bundle.releaseAll();

// 方式三：引用计数管理
resources.load('img/spriteFrame', SpriteFrame, (err, sf) => {
    sf.addRef();       // 持有时增加引用
    // ... 使用中
    sf.decRef();       // 不再使用时减少引用
});

// 移除 Bundle
assetManager.removeBundle(bundle);

4.4 远程资源加载

import { assetManager, ImageAsset, Texture2D, SpriteFrame } from 'cc';

assetManager.loadRemote<ImageAsset>('https://example.com/avatar.png', (err, imageAsset) => {
    const texture = new Texture2D();
    texture.image = imageAsset;
    const sf = new SpriteFrame();
    sf.texture = texture;
});

---

5. 缓动系统 (Tween)

import { tween, Vec3, Node, UIOpacity } from 'cc';

// 基础缓动
tween(this.node)
    .to(1, { position: new Vec3(100, 200, 0) })
    .start();

// 链式动画
tween(this.node)
    .to(0.5, { scale: new Vec3(1.2, 1.2, 1) })
    .to(0.5, { scale: new Vec3(1, 1, 1) })
    .union()          // 合并为一个动作
    .repeatForever()  // 无限循环
    .start();

// 回调
tween(this.node)
    .to(1, { position: new Vec3(0, 100, 0) })
    .call(() => { console.log('done'); })
    .start();

// 并行 & 延迟
tween(this.node)
    .parallel(
        tween().to(1, { position: new Vec3(100, 0, 0) }),
        tween().to(1, { scale: new Vec3(2, 2, 1) }),
    )
    .delay(0.5)
    .start();

// 透明度缓动（需要 UIOpacity 组件）
const opacity = this.node.getComponent(UIOpacity)!;
tween(opacity).to(0.5, { opacity: 0 }).start();

// 停止缓动
Tween.stopAllByTarget(this.node);

---

6. 节点与场景操作

6.1 节点访问

// 子节点
const child = this.node.getChildByName('child');
const children = this.node.children;
const childByPath = find('Canvas/UI/Button', this.node); // 路径查找

// 父节点
const parent = this.node.parent;

// 全局查找
import { find } from 'cc';
const canvas = find('Canvas');

// 组件获取
const sprite = this.node.getComponent(Sprite);
const sprites = this.node.getComponentsInChildren(Sprite);

6.2 节点变换

import { Vec3, Quat } from 'cc';

// 位置
this.node.setPosition(new Vec3(100, 200, 0));
this.node.position = new Vec3(100, 200, 0);

// 旋转 (3D 使用 Quat)
this.node.setRotationFromEuler(0, 0, 45);
this.node.angle = 45; // 2D 简写

// 缩放
this.node.setScale(new Vec3(2, 2, 1));

// 世界坐标
const worldPos = this.node.worldPosition;
this.node.setWorldPosition(worldPos);

6.3 场景管理

import { director } from 'cc';

// 加载并切换场景
director.loadScene('GameScene');

// 带回调
director.loadScene('GameScene', (err, scene) => {
    console.log('scene loaded');
});

// 预加载场景
director.preloadScene('GameScene', (err) => {
    // 预加载完成
});

// 常驻节点
director.addPersistRootNode(this.node);
director.removePersistRootNode(this.node);

---

7. 平台宏与条件编译

import { sys } from 'cc';
import { DEBUG, EDITOR, PREVIEW, BUILD } from 'cc/env';

// 环境宏
if (DEBUG) { /* 调试模式 */ }
if (EDITOR) { /* 编辑器模式 */ }
if (BUILD) { /* 构建后 */ }

// 平台判断
if (sys.isBrowser) { /* 浏览器 */ }
if (sys.isNative) { /* 原生平台 */ }
if (sys.platform === sys.Platform.WECHAT_GAME) { /* 微信小游戏 */ }

---

8. 模块导入规范

// ✅ 正确：从 'cc' 模块导入
import { _decorator, Component, Node, Vec3, Color, Sprite, resources } from 'cc';

// ✅ 正确：从 'cc/env' 导入环境宏
import { DEBUG, EDITOR } from 'cc/env';

// ❌ 错误：不要使用 cc. 全局前缀
// cc.Component, cc.Node, cc.find // 3.x 中不存在

---

参考文件索引

框架参考 (references/framework/)

文件	说明
component-system.md	组件系统、装饰器、生命周期详解
event-patterns.md	事件系统、输入/节点/自定义事件模式
asset-management.md	资源管理、加载/释放/Bundle
playable-optimization.md	可试玩广告优化、包体/性能策略

语言参考 (references/language/)

文件	说明
quality-hygiene.md	TypeScript 代码质量与卫生规范
performance.md	性能优化指南、内存/渲染/逻辑

审查参考 (references/review/)

文件	说明
architecture-review.md	架构审查清单
quality-review.md	代码质量审查清单