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 的核心差异

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 装饰器速查

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 中可确保节点已挂载到节点树
• 同一节点上组件的 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) { /* ... */ }
    }
}

全局输入事件类型:

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/)

语言参考 (references/language/)

审查参考 (references/review/)