pixelheros/.trae/rules/project_rules.md

alwaysApply

alwaysApply
true

oops-framework & Cocos Creator 3.x 开发规范

• 引用其他文件函数时严格审核引用路径的正确性。

技术栈

• Cocos Creator 3.x + TypeScript 严格模式（优先 Interface/Type，杜绝 any）
• 全局对象 oops 访问框架功能，通过 import { oops } from 'xxxx' 获取

架构约束

• Model / View / System(Controller) 分层，禁止将所有逻辑塞入单个组件
• 禁止造轮子：UI、资源、音频、事件、调度等基础功能必须使用 oops.xxx 内置模块

框架模块速查

模块	用途	关键 API
oops.gui	UI 生命周期	open(name, data) / remove(name)；频繁更新用 MVVM
oops.res	资源加载/释放	load / loadAsync / release
oops.message	跨模块事件总线	on / off / dispatchEvent
oops.timer	定时任务	register（禁止 setInterval）
ECS	大量同类实体（弹幕、群怪）	框架内置 ECS 库
行为树	复杂 NPC AI	behavior-tree 模块
AsyncQueue	按序异步初始化	规避回调地狱

严格禁止

• 用 instantiate + addChild 手动管理全屏 UI / 弹窗 → 必须走 oops.gui
• 组件间 @property 拖拽 / find 查找强引用 → 必须走 oops.message 事件解耦
• 所有 oops.message.on / oops.timer.register 必须在 onDestroy / onDisable 中注销

---

代码注释规范

核心原则

1. Clean Code 优先：命名糟糕则重构命名，而非堆注释
2. Why > What：注释解释"为什么"，禁止废话注释（如 // 遍历数组）
3. JSDoc / TSDoc 标准格式，注释使用中文，专业术语保留英文
4. 拒绝幽灵注释：代码变更时必须同步更新注释，删除废弃注释；输出前自校注释与代码一致性

注释标准

• 文件头：复杂/核心模块顶部用 /** ... */ 简述职责
• 类/接口：描述领域模型职责，标注关键生命周期或状态流转
• 公共方法：必须 JSDoc，含功能简述、@param（含边界/可空说明）、@returns、可选 @throws / @deprecated
• 行内注释：仅用于复杂正则、位运算、业务 Workaround；// 后留空格，放在代码正上方
• 标记标签（大写）：// TODO: 未实现、// FIXME: 已知 Bug、// HACK: 妥协方案

输出要求

• 代码前指明使用了 oops-framework 哪个模块
• oops API 调用附带简明中文注释
• 检查所有监听是否在生命周期结束时注销

---

RichText 描边规范

背景

Cocos Creator 3.x 的 cc.RichText 原生支持 <outline> 标签，无需新增组件即可为富文本提供描边能力。

使用方式

import { outlineRich } from "../common/RichOutline";

// 默认黑色 2px 描边
this.info_rich.string = outlineRich(desc);

// 自定义颜色与宽度
this.info_rich.string = outlineRich(desc, "#000", 1);

注意事项

• <outline> 为包裹型标签，需成对出现；内部可嵌套 <color>/<size> 等标签
• width 为像素宽度（int），color 支持 #RGB/#RRGGBB
• 空字符串直接返回，不包裹空标签

---