---
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 调用附带简明中文注释
- 检查所有监听是否在生命周期结束时注销

---

# SkillSet / heroSet 配置规则

## 核心原则

1. **技能底座纯净化**：SkillSet 中的技能只定义基础行为（伤害、弹道、命中），**禁止**在基础配置中写死 `timed_buff_id` / `buff_type` 等效果字段
2. **效果由引用处注入**：英雄/怪物引用技能时，通过 `HSkillInfo.overrides` 按需附加 debuff/buff，实现"同一技能、不同效果"
3. **数值覆盖优先**：`ap`（伤害百分比）、`hit_count`、`crt` 等数值差异，统一由 `overrides` 覆写，而非新建相似技能

## SkillSet 配置规范

### 技能 uuid 段位分配

| 段位 | 用途 | 示例 |
|------|------|------|
| 6001-6099 | 基础单体攻击（近战/远程通用底座） | 6001 飞剑、6004 攻击 |
| 6100-6199 | 中阶攻击技能（高阶特效/多命中） | 6101 火球、6102 飓风 |
| 6200-6299 | 高阶范围技能（AOE/必杀） | 6201 陨石术 |
| 6300-6399 | 辅助/治疗/护盾技能 | 6301 护盾、6302 治疗 |
| 6400-6499 | 永久属性强化（buff_type） | 6401 攻击强化 |
| 6500-6599 | 计时爆发技能（timed_buff_id） | 6501 复活 |

### 新增技能检查清单

- [ ] uuid 在对应段位内，且未与现有技能冲突
- [ ] `sp_name` / `icon` 与现有技能不重复（避免视觉混淆）
- [ ] `IType`（近战/远程/辅助）与 `RType`（弹道类型）匹配合理
- [ ] 基础配置**不含** `timed_buff_id` / `buff_type`（效果由引用处注入）
- [ ] `info` 描述只写基础效果，不写具体 debuff（如"造成攻击力100%的伤害"）

## heroSet 配置规范

### 英雄 uuid 段位分配

| 段位 | 品质 | 说明 |
|------|------|------|
| 5001-5099 | card_lv=1 | 基础单体/默认范围 |
| 5101-5199 | card_lv=2 | 数值强化 |
| 5201-5299 | card_lv=3 | 范围扩大 |
| 5301-5399 | card_lv=4 | 数值+范围 |
| 5401-5499 | card_lv=5 | 双技能（+revive/field） |

### 怪物 uuid 段位分配

| 段位 | 类型 |
|------|------|
| 6001-6099 | 基础怪物（近战/远程/特殊位） |
| 6100-6199 | Boss 怪物 |

### 新增英雄/怪物检查清单

- [ ] `skills` 引用的技能 uuid 在 SkillSet 中存在
- [ ] 技能效果通过 `overrides` 按需注入，**禁止**直接修改 SkillSet 基础配置
- [ ] `overrides.ap` 明确写出（如 80/100/150），避免依赖基础配置的默认值
- [ ] `timed_buff_id` 指向 BuffList 中存在的 buff 配置
- [ ] 怪物技能引用优先使用 6001-6012 基础技能，Boss 可用 6101+ 中阶技能

### 触发技能配置规则

| 触发类型 | 字段 | 说明 |
|----------|------|------|
| 普通攻击 | `skills` | 携带技能，`overrides` 注入效果 |
| 受击触发 | `atked` | 按 s_uuid 分组，按 lv 升序 |
| 攻击后触发 | `atking` | 按 s_uuid 分组，按 lv 升序 |
| 死亡触发 | `dead` | 按 s_uuid 分组，按 lv 升序 |
| 战斗开始 | `fstart` | 按 s_uuid 分组，按 lv 升序 |
| 驻场光环 | `field` | `FieldEntry[]`，按 lv 升序 |
| 复活 | `revive` | `LvReviveEntry[]`，按 lv 升序 |

### 示例：同一技能不同效果

```typescript
// SkillSet 6101 火球 — 纯伤害底座，无 debuff
6101: {
    uuid: 6101, name: "火球", sp_name: "fb-1", ...,
    // 禁止写 timed_buff_id / buff_type
}

// heroSet 5004 破晓先知 — 冰冻版火球
skills: { 6101: { uuid: 6101, overrides: { ap: 80, timed_buff_id: 7003 } } }

// heroSet 5304 战吼术士 — 中毒版火球
skills: { 6101: { uuid: 6101, overrides: { ap: 80, timed_buff_id: 7005 } } }

// heroSet 6008 兽人火法 — 原版火球（ap=100，无 debuff）
skills: { 6101: { uuid: 6101 } }
```