# TheOne Studio Cocos Creator 开发标准 ⚠️ **Cocos Creator 3.x (TypeScript 4.1+):** 所有模式和示例均兼容 Cocos Creator 3.x 可玩广告开发。 ## 技能目的此技能强制执行 TheOne Studio 全面的 Cocos Creator 开发标准，**代码质量第一**： **优先事项 1：代码质量和卫生**（最重要） * TypeScript 严格模式、ESLint 配置、访问修饰符（公共/私有/受保护） * 抛出异常（绝不是静默错误） * console.log 用于开发，在生产版本中删除 * readonly 表示不可变字段，const 表示常量 * 没有内嵌注释（使用描述性名称） * 正确的错误处理和类型安全 **优先级 2：现代 TypeScript 模式** * 循环上的数组方法（map/filter/reduce） * 箭头函数、解构、扩展运算符 * 可选的链接、无效合并 * 类型保护、实用程序类型（部分、必需、只读） * 现代 TypeScript 功能 **优先级3：Cocos Creator架构** * 基于组件的实体组件（EC）系统 * 生命周期方法：onLoad→start→onEnable→update→onDisable→onDestroy * 自定义事件的EventDispatcher模式 * 节点事件系统（EventTouch、键盘事件） * 可玩的资源管理和池化 **优先级 4：可玩广告效果** * DrawCall 批处理（<10 个 DrawCalls 目标） * 精灵图集配置（启用自动图集） * 骨骼动画的 GPU 蒙皮 * update() 循环中的零分配 * 捆绑包大小<5MB（纹理压缩、代码缩小） ## 该技能何时触发 * 编写或重构 Cocos Creator TypeScript 代码 * 实现可玩广告功能 * 使用组件生命周期和事件 * 优化可玩广告的性能 * 审查代码更改或拉取请求 * 设置可玩的项目架构 * 减少捆绑包大小或 DrawCall 数量 ## 快速参考指南 ### 您需要什么帮助？优先|任务|参考 ---|---|--- **🔴优先级 1：代码质量（首先检查）** | | 1 | TypeScript 严格模式、ESLint、访问修饰符 | [质量与卫生]() ⭐ 1 |抛出异常，正确的错误处理 | [质量与卫生]() ⭐ 1 | console.log（仅限开发），在生产中删除 | [质量与卫生]() ⭐ 1 |只读/常量，无内联注释，描述性名称 | [质量与卫生]() ⭐ **🟡优先级 2：现代 TypeScript 模式** | | 2 |数组方法、箭头函数、解构 | [现代 TypeScript]() 2 |可选链接、无效合并 | [现代 TypeScript]() 2 |类型保护，实用类型 | [现代 TypeScript]() **🟢 优先级 3：Cocos 架构** | | 3 |组件系统，@property 装饰器 | [组件系统]() 3 |生命周期方法（onLoad→start→update→onDestroy）| [组件系统]() 3 | EventDispatcher、节点事件、清理 | [事件模式]() 3 |资源加载、池化、内存管理| [可玩优化]() **🔵 优先事项 4：性能和审核** | | 4 | DrawCall 批处理、精灵图集、GPU 蒙皮 | [可玩优化]() 4 |更新循环优化，零分配 | [性能]() 4 |捆绑包大小减小（<5MB 目标）| [尺寸优化]() 4 |架构审查（组件、生命周期、事件）| [架构回顾]() 4 | TypeScript 质量审查 | [质量审核]() 4 |绩效审查（DrawCalls、分配）| [性能回顾]() ## 🔴 关键：代码质量规则（首先检查！） ### ⚠️ 强制性质量标准 **在编写任何代码之前始终强制执行这些：** 1. **启用 TypeScript 严格模式** \- tsconfig.json 中的 "strict": true 2. **使用ESLint配置** \- 启用@typescript-eslint规则 3. **对所有成员使用访问修饰符** \- public/private/protected 4. **抛出错误异常** \- 永远不会出现静默失败或未定义的返回 5. **console.log 仅用于开发** \- 删除生产版本中的所有控制台语句 6. **对不可变字段使用只读** \- 标记未重新分配的字段 7. **对常量使用const** \- 常量应该是const，而不是let 8. **无内嵌注释** \- 使用描述性名称；代码应该是不言自明的 9. **正确的 null/未定义处理** \- 使用可选链接和 nullish 合并 10. **类型安全** \- 避免`any`类型，使用正确的类型和接口 **示例：强制质量第一** // ✅ 优秀：执行所有质量规则从 'cc' 导入 { _decorator, Component, Node, EventTouch }; const { ccclass, 属性 } = _decorator; @ccclass('玩家控制器') 导出类 PlayerController 扩展组件 { // 3. 访问修饰符，6. 不可变的 readonly @属性（节点）私有只读目标节点：节点|空=空； // 7. const 表示常量私有静态只读 MAX_HEALTH：数量 = 100；私人当前健康状况：数量= 100； // 生命周期：onLoad→start→onEnable 受保护的 onLoad(): void { // 4. 错误抛出异常 if (!this.targetNode) { throw new Error('PlayerController: targetNode 未分配'); } // 9. 正确的事件监听器设置 this.node.on(Node.EventType.TOUCH_START, this.onTouchStart, this); } 受保护的 onDestroy(): void { // 9. 始终清理事件监听器 this.node.off(Node.EventType.TOUCH_START, this.onTouchStart, this); } 私人onTouchStart（事件：EventTouch）：无效{ // 5. console.log 仅用于开发（在生产中删除）如果（CC_DEBUG）{ console.log('检测到触摸'); } this.takeDamage(10); } // 8. 描述性方法名称（不需要内联注释）私人takeDamage（金额：数字）：无效{ this.currentHealth -= 金额； if (this.currentHealth <= 0) { this.handlePlayerDeath(); } } 私人handlePlayerDeath（）：无效{ // 死亡逻辑 } } ## ⚠️ Cocos Creator 架构规则（质量后） ### 组件系统基础知识 **实体组件 (EC) 系统：** * 组件扩展`Component`类 * 使用`@ccclass`和`@property`装饰器 * 生命周期：onLoad→start→onEnable→update→lateUpdate→onDisable→onDestroy **执行顺序：** 1. **onLoad()** \- 组件初始化，一次性设置 2. **start()** \- 所有组件加载完毕后，可以引用其他组件 3. **onEnable()** \- 当组件/节点启用时（可以多次调用） 4. **更新(dt)** \- 每帧（对于可播放内容请谨慎使用） 5. **lateUpdate(dt)** \- 在所有 update() 调用之后 6. **onDisable()** \- 当组件/节点禁用时 7. **onDestroy()** \- 清理、移除监听器、释放资源 **通用规则：** * ✅ 在onLoad()中初始化，在start()中引用其他组件 * ✅ 在onEnable()中注册事件，在onDisable()中取消注册 * ✅ 始终在 onDestroy() 中清理监听器 * ✅ 避免 update() 中的繁重逻辑（性能对于可玩性至关重要） * ✅ 对不应重新分配的 @property 字段使用 readonly * ✅ 因缺少所需参考而引发异常 ## 简短示例 ### 🔴代码质量第一 // ✅ 优秀：执行质量规则从 'cc' 导入 { _decorator, Component, Node }; const { ccclass, 属性 } = _decorator; @ccclass('游戏管理器') 导出类 GameManager 扩展组件 { @属性（节点）私有只读playerNode：节点|空=空；私有静态只读 MAX_SCORE：数量 = 1000；私人当前分数：数字= 0；受保护的 onLoad(): void { // 如果缺少必需的引用，则抛出异常 if (!this.playerNode) { throw new Error('GameManager:需要playerNode'); } 如果（CC_DEBUG）{ console.log('GameManager 已初始化'); // 仅开发 } } 公共addScore（点数：数量）：无效{ 如果（点 <= 0）{ throw new Error('GameManager.addScore: 分数必须为正'); } this.currentScore = Math.min( this.currentScore + 积分, GameManager.MAX_SCORE ）； } } ### 🟡 现代 TypeScript 模式 // ✅ 好：数组方法而不是循环 const activeEnemies = allEnemies.filter(e => e.isActive); const heavenlyPositions = activeEnemies.map(e => e.node.position); // ✅ 好：可选链接和无效合并 const 玩家名称 = 玩家?.名称 ?? '未知'; // ✅ 好：解构 const { x, y } = this.node.position; // ✅ 好：箭头函数 this.enemies.forEach（敌人=>敌人.takeDamage（10））; // ✅ 好：类型保护 function isPlayer(node: Node): 节点是 PlayerNode { return node.getComponent(PlayerController) !== null; } ### 🟢 Cocos Creator 组件模式从 'cc' 导入 { _decorator, Component, Node, EventTouch, Vec3 }; const { ccclass, 属性 } = _decorator; @ccclass('触摸处理程序') 导出类 TouchHandler 扩展组件 { @属性（节点）私有只读目标节点：节点|空=空；私有只读 tempVec3: Vec3 = new Vec3(); // 可重复使用的向量 // 1.onLoad：初始化组件受保护的 onLoad(): void { if (!this.targetNode) { throw new Error('TouchHandler: 需要 targetNode'); } } // 2. start：引用其他组件（如果需要）受保护的开始（）：无效{ // 这里可以安全地访问其他组件 } // 3. onEnable：注册事件监听器受保护的 onEnable(): void { this.node.on(Node.EventType.TOUCH_START, this.onTouchStart, this); this.node.on(Node.EventType.TOUCH_MOVE, this.onTouchMove, this); } // 4. onDisable：取消注册事件监听器受保护的 onDisable(): void { this.node.off(Node.EventType.TOUCH_START, this.onTouchStart, this); this.node.off(Node.EventType.TOUCH_MOVE, this.onTouchMove, this); } // 5. onDestroy：最终清理受保护的 onDestroy(): void { // 释放任何额外资源 } 私人onTouchStart（事件：EventTouch）：无效{ // 处理触摸 } 私人onTouchMove（事件：EventTouch）：无效{ // 重用向量以避免分配 this.targetNode!.getPosition(this.tempVec3); this.tempVec3.y += 10; this.targetNode!.setPosition(this.tempVec3); } } ### 🟢 事件调度程序模式从 'cc' 导入 { _decorator, Component, EventTarget }; const { ccclass } = _decorator; // 自定义事件类型导出枚举 GameEvent { SCORE_CHANGED = '分数更改', LEVEL_COMPLETE = '关卡完成', PLAYER_DIED = '玩家死亡', } 导出接口 ScoreChangedEvent { 旧分数：数字；新分数：数字； } @ccclass('事件管理器') 导出类 EventManager 扩展组件 { 私有静态实例：EventManager |空=空；私有只读 eventTarget: EventTarget = new EventTarget(); 受保护的 onLoad(): void { if (EventManager.instance) { throw new Error('EventManager: 实例已存在'); } EventManager.instance = this; } 公共静态发射（事件：GameEvent，数据？：任何）：无效{ if (!EventManager.instance) { throw new Error('EventManager: 实例未初始化'); } EventManager.instance.eventTarget.emit(事件，数据); } 公共静态 on（事件：GameEvent，回调：函数，目标？：任何）：void { if (!EventManager.instance) { throw new Error('EventManager: 实例未初始化'); } EventManager.instance.eventTarget.on(事件、回调、目标); } 公共静态关闭（事件：GameEvent，回调：函数，目标？：任何）：void { if (!EventManager.instance) { throw new Error('EventManager: 实例未初始化'); } EventManager.instance.eventTarget.off(事件、回调、目标); } } // 组件中的使用 @ccclass('分数显示') 导出类 ScoreDisplay 扩展组件 { 受保护的 onEnable(): void { EventManager.on(GameEvent.SCORE_CHANGED, this.onScoreChanged, this); } 受保护的 onDisable(): void { EventManager.off(GameEvent.SCORE_CHANGED, this.onScoreChanged, this); } 私人onScoreChanged（数据：ScoreChangedEvent）：无效{ console.log(`得分：${data.oldScore} → ${data.newScore}`); } } ### 🔵 可玩性能优化从 'cc' 导入 { _decorator, Component, Node, Sprite, SpriteAtlas }; const { ccclass, 属性 } = _decorator; @ccclass('优化的SpriteManager') 导出类 OptimizedSpriteManager 扩展组件 { // 使用 sprite atlas 进行 DrawCall 批处理 @property(SpriteAtlas) 私有只读角色图集：SpriteAtlas |空=空； // 预分配数组以避免在 update() 中分配私有只读临时节点：Node[] = []；私有frameCount：数量= 0；受保护的 onLoad(): void { if (!this.characterAtlas) { throw new Error('OptimizedSpriteManager:需要characterAtlas'); } // 从图集中预热精灵帧 this.prewarmSpriteFrames(); } 私人 prewarmSpriteFrames(): void { // 从图集中加载所有精灵（在单个 DrawCall 中批量处理） const spriteFrame = this.characterAtlas!.getSpriteFrame('character_idle'); 如果（！spriteFrame）{ throw new Error('在图集中找不到精灵帧'); } } // 优化更新：避免分配，使用对象池受保护的更新（dt：数字）：无效{ // 每 N 帧运行一次昂贵的操作，而不是每帧 this.frameCount++; if (this.frameCount % 10 === 0) { this.updateExpenseOperation(); } } 私人更新昂贵操作（）：无效{ // 重用数组而不是创建新数组 this.tempNodes.length = 0; // 批量操作以减少DrawCalls } } ## 代码审查清单 ### 快速验证（提交前） **🔴代码质量（首先检查）：** * 在 tsconfig.json 中启用 TypeScript 严格模式 * ESLint 规则通过（无错误） * 所有访问修饰符均正确（公共/私有/受保护） * 错误抛出异常（没有静默失败） * console.log 被删除或包含在 CC_DEBUG 中 * 只读用于非重新分配的字段 * const 用于常量 * 没有内嵌注释（不言自明的代码） * 正确的空/未定义处理 * 没有“任何”类型（使用正确的类型） **🟡 现代 TypeScript 模式：** * 使用数组方法代替手动循环 * 用于回调的箭头函数 * 用于安全属性访问的可选链接 (?.) * 默认值的空合并 (??) * 解构以获得更清晰的代码 * 用于缩小类型的类型保护装置 **🟢Cocos Creator 架构：** * 组件生命周期方法按正确顺序排列 * onLoad()用于初始化，start()用于引用 * 在onEnable()中注册的事件监听器 * 在 onDisable() 中取消注册事件监听器 * onDestroy()中释放资源 * 正确使用@property装饰器 * 验证所需的引用（如果为空则抛出） **🔵 可玩性能：** * update() 循环中没有分配 * 用于 DrawCall 批处理的 Sprite 图集 * 为骨骼动画启用 GPU 蒙皮 * 昂贵的操作被限制（不是每一帧） * 频繁创建对象的对象池 * 启用纹理压缩 * 捆绑包大小 <5MB 目标 * DrawCall 计数 <10 个目标 ## 要避免的常见错误 ### ❌不要： 1. **忽略 TypeScript 严格模式** → 启用“strict”：true 2. **静默错误处理** → 抛出错误异常 3. **将 console.log 保留在生产中** → 删除或包含在 CC_DEBUG 中 4. **跳过访问修饰符** → 使用 public/private/protected 5. **使用`any`类型** → 定义正确的类型和接口 6. **添加内联注释** → 使用描述性名称代替 7. **跳过事件清理** → 始终在 onDisable/onDestroy 中取消注册 8. **在 update() 中分配** → 预分配和重用对象 9. **忘记精灵图集** → 使用图集进行 DrawCall 批处理 10. ** update() 中的繁重逻辑** → 限制昂贵的操作 11. **跳过 null 检查** → 验证 onLoad 中所需的引用 12. **可变@property字段** → 适当时使用只读 13. **手动循环数组** → 使用map/filter/reduce 14. **忽略捆绑包大小** → 监控和优化（<5MB 目标） ### ✅ 要做： 1. **启用 TypeScript 严格模式** ("strict": true) 2. **抛出错误异常**（绝不是静默失败） 3. **仅将 console.log 用于开发**（在生产中删除） 4. **使用访问修饰符**（公共/私有/受保护） 5. **定义适当的类型**（避免“any”） 6. **使用描述性名称**（无内嵌注释） 7. **始终清理事件** (onDisable/onDestroy) 8. **预分配对象**（在 update() 中重用） 9. **使用精灵图集**（DrawCall批处理） 10. **限制昂贵的操作**（不是每一帧） 11. **验证所需引用**（如果为 null，则抛出 onLoad） 12. **对@property使用只读**（在适当的情况下） 13. **使用数组方法**（map/filter/reduce） 14. **监控捆绑包大小**（可玩的目标<5MB） ## 查看严重级别 ### 🔴 严重（必须修复） * **禁用 TypeScript 严格模式** \- 必须启用“strict”：true * **静默错误处理** \- 必须抛出错误异常 * **生产代码中的console.log** \- 删除或包含在 CC_DEBUG 中 * **缺少访问修饰符** \- 所有成员都必须具有修饰符 * **在没有理由的情况下使用`any`类型** \- 定义正确的类型 * **内联注释而不是描述性名称** \- 重命名和删除注释 * **事件侦听器未清理** \- 内存泄漏，必须取消注册 * **缺少所需的参考验证** \- 如果为 null，则必须抛出 onLoad * **update() 循环中的分配** \- 性能关键，必须预分配 * **多个精灵没有精灵图集** \- DrawCall爆炸，必须使用图集 * **捆绑包大小 >5MB** \- 超出可玩限制，必须优化 ### 🟡 重要（应该修复） * **@property 字段上缺少只读** \- 未重新分配时应为只读 * **常量缺少 const** \- 应该使用 const 而不是 let * **手动循环而不是数组方法** \- 应该使用map/filter/reduce * **缺少可选链接** \- 应该使用 ?.为了安全访问 * **缺少无效合并** \- 应该使用 ??对于默认值 * ** update() 中的繁重逻辑** \- 应该限制昂贵的操作 * **没有用于频繁分配的对象池** \- 应该实现池化 * **纹理压缩未启用** \- 应该为较小的包启用 * **DrawCall 计数 >10** \- 应优化批处理 ### 🟢 很高兴拥有（建议） * 可以使用箭头函数进行回调 * 可以解构以获得更清晰的代码 * 可以使用类型保护来保证类型安全 * 可以改进命名以使其更加清晰 * 可以添加界面以更好地打字 * 可以优化算法以获得更好的性能 ## 详细参考资料 ### TypeScript 语言标准 * [质量与卫生]() \- 严格模式、ESLint、访问修饰符、错误处理 * [Modern TypeScript]() \- 数组方法、可选链、类型保护、实用程序类型 * [性能]() \- 更新循环优化、零分配、缓存 ### Cocos Creator 框架 * [组件系统]() \- EC系统、生命周期方法、@property装饰器 * [事件模式]() \- EventDispatcher、节点事件、订阅清理 * [可玩优化]() \- DrawCall 批处理、精灵图集、GPU 换肤、资源池 * [尺寸优化]() \- 捆绑包尺寸减小、纹理压缩、构建优化 ### 代码审查 * [架构审查]() \- 组件违规、生命周期错误、事件泄漏 * [质量审查]() \- TypeScript 质量问题、访问修饰符、错误处理 * [性能审查]() \- 可玩特定的性能问题、DrawCalls、分配 ## 总结该技能为 TheOne Studio 的可玩广告团队提供了全面的 Cocos Creator 开发标准： * **TypeScript Excellence**：严格模式、现代模式、类型安全 * **Cocos 架构** ：组件生命周期、事件模式、资源管理 * **可玩性能**：DrawCall 批处理、GPU 皮肤、<5MB 捆绑包 * **代码质量**：强制执行的质量、卫生和性能规则使用上面的快速参考指南导航到您需要的特定模式。

Theone Cocos 标准

包含技能