Instruction file imported from BlackFrost-hub/kaminotabibito (.cursor/rules/gameplay/equipment/buff经验/00．Buff经验规则.mdc). Copyright stays with the author.

Buff 经验规则

这条规则是 Buff 相关工作的唯一经验口径。
新增或修改任何 Buff / Debuff / HOT / DOT / 原生魔法效果时，先读这里，再看具体子系统规则。
核心目标只有一个：不要只做 UI，不要只做表，不要只做一半。

执行摘要

1. 先确认 Buff 表、原生物编、TS 运行逻辑和原生魔法效果四层分别需要什么。
2. 明确来源、持续时间、叠层、驱散和外部截断时的真实停止条件。
3. DOT/HOT、属性修改、原生 Buff 清理和 UI 消失必须共享同一生命周期。
4. 新增完成后同时检查分类表、聚合入口、技能侧统一入口和清除路径。

1. 先判断 Buff 属于哪一层

新增 Buff 前，先分清四层：

• Buff 表/UI 层：TS/系统/05．Buff系统/01．Buff表.ts，定义名称、图标、类型、驱散、叠层、提示、表现信息。
• 原生 Buff 物编数据层：TS/系统/05．Buff系统/02．Buff数据表/00．Buff数据表.ts，这是从魔兽物体编辑器导出的原生 Buff 数据，字段如 Bufftip / Buffubertip / Buffart 只代表物编侧数据。
• TS 运行逻辑层：真正的效果、持续、叠层、回调、DOT/HOT、属性变化、攻击效果等。
• 原生魔法效果层：马甲技能自带的状态栏 / 图标 / 原生 Buff，需要时必须同步清理。

禁止只加 Buff 表 就当成完成。

额外说明：

• 01．Buff表.ts 是我们自己定义的 TS Buff/UI/驱散语义表，不是物编导出表。
• 02．Buff数据表/00．Buff数据表.ts 是War3 原生物编 Buff 数据表，不是运行时 Buff 定义表。
• Buff数据表.ts 也不是完整的原生 Buff 全量总表：魔兽内建技能自带的一些默认 Buff 可能不会出现在这里，例如风暴之锤的眩晕。
• 需要判断某个原生技能是否有默认 Buff 时，不能只依赖 Buff数据表.ts，要结合技能物编、原生效果和实测。

2. Buff 表新增时必须写清楚

新增 Buff 优先写入分类表目录 TS/系统/05．Buff系统/03．Buff表/，不要继续把新条目直接堆进大文件 01．Buff表.ts。

• 通用 Buff 放 03．Buff表/01．通用.ts。
• DOT / HOT / 周期效果放 03．Buff表/02．DOT.ts。
• 控制类 Buff 放 03．Buff表/03．控制.ts。
• 属性类 Buff 放 03．Buff表/04．属性.ts。
• 光环类 Buff 放 03．Buff表/05．光环.ts。
• Boss 专属 Buff 放 03．Buff表/01．Boss/ 下的单 Boss 文件，例如 01．瑟兰迪尔.ts。
• 英雄专属 Buff 放 03．Buff表/02．英雄/ 下的单英雄文件，并在该目录 index.ts 聚合。
• 01．Buff表.ts 是对外兼容入口，会合并旧表与 03．Buff表/ 分类表；业务代码仍通过 系统.05．Buff系统.01．Buff表 读取。

Buff 新条目至少要明确这些字段：

• buffID
• buffName
• icon
• effect
• type
• interval
• maxStack
• stackRule
• stackRefresh
• dispelLevel
• canPurge
• tooltip

要求：

• type 必须能表达驱散语义，例如 Buff:、Debuff:、Debuff:control、Debuff:magic、Debuff:dot:soft。
• type 第一段必须是大类，统一使用 Buff: / Debuff: / Aura:，不要写成 deBuff: 这类大小写混用。
• 持续伤害、周期伤害、站圈残留伤害、每秒结算的锁链/中毒/灼烧等，必须在 type 中包含 :dot，例如 Debuff:dot:fire:stack、Debuff:dot:poison、Debuff:magic:dot、Debuff:control:dot。
• Buff 查询按 : 分隔后的字段精确命中，不依赖字段顺序：有 Debuff 字段就是负面，有 control 字段就是控制，有 dot 字段就是持续伤害；例如 Debuff:control:dot 和 Debuff:dot:control 都能同时被控制查询与持续伤害查询命中。
• 减速类 Buff 必须在 type 中包含 :slow，例如 Debuff:control:soft:slow、Debuff:dot:slow:magic；只有确实降低移动/行动速度的条目才标 :slow，不要把所有软控都当减速。
• tooltip 必须和实际代码一致。
• 如果有真实效果，就必须在对应 TS 文件里实现，不允许只放表。
• effectMode / effectAttachPoint / effectModel 这类表现字段如果存在，也必须和实际表现一致。

3. 运行时效果必须绑定真实生命周期

持续型效果必须在每次 tick 前检查自己是否还存在。

常见原则：

• DOT / HOT 每跳前都要检查对应 BuffID 是否还在 Buff 池。
• 持续伤害的语义必须是“某个效果持续一段时间，并按 tick/每秒/周期结算伤害”，例如 DOT、燃烧、中毒、持续伤害区域、持续 Debuff；单次伤害、连击多段、持有装备后的常驻周期脉冲/光环伤害不自动算持续伤害。
• DOT 秒跳和其它持续窗口内的 tick 伤害统一走 TS/系统/04．伤害系统/07．持续伤害系统.ts 计算来源玩家属性 持续伤害；旧 DOT 框架仍由 TS/系统/04．伤害系统/02．dot伤害.ts / 01．DOT定义 管理状态和 Buff 同步。装备不要自己另造“持续伤害提升”字段或单件独立乘区。
• registerManualBuff 只是登记，不代表逻辑已经自动支持驱散中断。
• 属性型 Buff 必须通过 onRemove 回滚。
• 如果效果和 effect/effect2 有语义，读写单位必须统一单位。
• 多个同类 Buff 的语义要先定清楚：叠加、取最高、刷新还是独立计时，代码和表必须一致。

4. 外部驱散 / 截断必须真的结束

如果 Buff 会被外部驱散、清除、截断，那么必须满足下面至少一条：

• 运行时每 tick 检查 Buff 是否还存在，没了就停。
• 清除入口会真正调用 移除单位指定Buff / UnitRemoveAbility / 对应回调。
• DOT 状态通过 syncDotBuff(..., null) 或等效路径清掉。

燃烧经验

• D002 燃烧是 DOT Buff。
• 只要 Buff 池里对应项被删掉，燃烧就应提前结束。
• 不允许只删 UI、只删图标、只删局部状态，却让伤害继续跑。
• 如果是可驱散的持续属性 buff，驱散后必须立刻回滚，不允许留下永久属性。

5. registerManualBuff 的使用约束

registerManualBuff(target, buffID, duration, effectValue, extras) 只负责注册 Buff 池记录。

常用补充项：

• sourceName：来源显示
• iconOverride：图标覆盖
• effectModelOverride：特效覆盖
• effectValue2：第二数值
• nativeBuffAbilityIds：需要同步清理的原生魔法效果 rawId
• onRemove：移除时回滚逻辑

如果是可驱散 Buff，必须先想清楚：

• 清除时谁负责停逻辑
• 谁负责回滚属性
• 谁负责删原生效果
• 谁负责删 DOT 状态
• 谁负责处理重复施加和刷新时的累计结果

6. 清除入口优先统一

业务代码优先走统一入口，不要直接散写删除逻辑：

• 移除单位指定Buff
• 移除单位增益Buff
• 移除单位负面Buff
• 按驱散等级移除单位Buff
• 技能侧的中文便捷入口 TS/系统/03．技能系统/00．技能模板+函数/02．通用函数/01．控制与Buff.ts

如果是某个具体 Buff，优先补一个明确的清除入口，而不是让外部猜 buffID。

7. 属性与治疗

• 固定攻击力增加走属性底层加减，清除时 onRemove 反向回滚。
• 伤害百分比增减必须对齐伤害系统读取层级：玩家英雄通常写玩家属性，非英雄写单位属性。
• 生命/魔法恢复走治疗系统 doHeal 或 HOT 封装。
• 持续恢复必须支持 Buff 被驱散后提前停止。
• 如果是移动速度、视野、护甲等底层属性，优先走统一属性应用函数，不要在各个装备里重复写。

8. 新增 Buff 自检清单

新增或修改 Buff 后，至少检查：

• Buff 表字段是否完整
• 是否有真实 TS 逻辑
• 是否需要 onRemove
• 是否要同步原生能力清理
• 是否需要 tick 时检查存活
• 是否会被外部驱散 / 截断
• 是否会因为多个同类 Buff 只触发一个
• 是否会导致永久增减属性
• 是否按 TS 构建验证分流 完成了与本次改动相称的构建

9. 技能侧统一入口必须同步更新

每次新增 Buff、DOT、HOT 或和 Buff 相关的新效果时，都必须同步检查并更新：

• TS/系统/03．技能系统/00．技能模板+函数/02．通用函数/01．控制与Buff.ts

要求：

• 新增的 Buff 读取函数要优先挂到这里，方便技能侧统一调用。
• 新增的 Buff 清除函数也要优先挂到这里，避免业务侧直接散写 buffID。
• 如果是 DOT 相关内容，还要确认 dot伤害.ts / DOT定义 / 对应 Buff 表是否同步。
• 之前已经存在的 DOT / Buff 经验函数，也要顺手检查是否需要补到这个统一入口里。

一句话原则：

新增 Buff 不只改定义文件，必须把“读、加、清”都接进 控制与Buff.ts。