pan/pixelheros
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
93e02fa292e2f447fbd3c7a6c8af75366e95833b
pixelheros/.trae/rules/project_rules.md
panFD 93e02fa292 refactor(config): 按照技能配置规范重构技能配置 
1. 移除SkillSet中硬编码的buff效果，将6104技能替换为通用6101底座
2. 所有英雄/怪物技能通过overrides注入buff和数值修改
3. 新增项目技能配置规范文档
2026-08-15 20:40:56 +08:00

6.0 KiB
Raw Blame History

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

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 升序

示例：同一技能不同效果

// 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 } }
Reference in New Issue View Git Blame Copy Permalink