@mclawnet/agent 0.6.20 → 0.6.22

package/skills/cocos-creator-3x-cn/SKILL.md

@@ -0,0 +1,475 @@
+---
+name: cocos-creator-3x-cn
+description: 提供 Cocos Creator 3.8 游戏引擎的全面开发指导，包括组件系统（_decorator、Component）、生命周期回调、事件系统（EventTarget、input）、resources 资源管理、tween 缓动系统、对象池、UI 系统、物理碰撞以及可试玩广告优化。在用户编写或重构 Cocos Creator 3.x TypeScript 代码、实现游戏功能、处理资源加载与释放、优化性能/包体大小、审查代码变更、搭建可试玩广告项目架构时触发。也适用于用户提到 import from 'cc'、Component、Node、resources、tween、director 等 3.x API 时使用。
+version: 1.0.0
+---
+
+# 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 基础组件模板
+
+```typescript
+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 属性参数
+
+```typescript
+@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)
+
+```typescript
+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)
+
+```typescript
+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 节点事件
+
+```typescript
+// 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 自定义节点事件派发
+
+```typescript
+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 加载
+
+```typescript
+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
+
+```typescript
+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 资源释放
+
+```typescript
+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 远程资源加载
+
+```typescript
+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)
+
+```typescript
+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 节点访问
+
+```typescript
+// 子节点
+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 节点变换
+
+```typescript
+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 场景管理
+
+```typescript
+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. 平台宏与条件编译
+
+```typescript
+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. 模块导入规范
+
+```typescript
+// ✅ 正确：从 '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](references/framework/component-system.md) | 组件系统、装饰器、生命周期详解 |
+| [event-patterns.md](references/framework/event-patterns.md) | 事件系统、输入/节点/自定义事件模式 |
+| [asset-management.md](references/framework/asset-management.md) | 资源管理、加载/释放/Bundle |
+| [playable-optimization.md](references/framework/playable-optimization.md) | 可试玩广告优化、包体/性能策略 |
+
+### 语言参考 (references/language/)
+| 文件 | 说明 |
+|------|------|
+| [quality-hygiene.md](references/language/quality-hygiene.md) | TypeScript 代码质量与卫生规范 |
+| [performance.md](references/language/performance.md) | 性能优化指南、内存/渲染/逻辑 |
+
+### 审查参考 (references/review/)
+| 文件 | 说明 |
+|------|------|
+| [architecture-review.md](references/review/architecture-review.md) | 架构审查清单 |
+| [quality-review.md](references/review/quality-review.md) | 代码质量审查清单 |