heros/assets/script/game/hero/BuffSystem_Guide.md

BUFF 系统完整使用指南

系统概述

HeroViewComp 中的 buff 系统是一套完整的属性增强/减弱管理体系，支持：

• 数值型 buff/debuff：固定数值增减
• 百分比型 buff/debuff：基于基础属性的百分比增减
• 持久型：永久生效，直到主动移除
• 临时型：按时间递减，自动过期

架构设计

存储结构

// 数值型 buff
V_BUFF: BuffConf[]   // 持久型
V_BUFFS: BuffConf[]  // 临时型（含 remainTime）

// 百分比型 buff  
R_BUFF: BuffConf[]   // 持久型
R_BUFFS: BuffConf[]  // 临时型（含 remainTime）

// 数值型 debuff
V_DBUFF: DbuffConf[] // 持久型
V_DBUFFS: DbuffConf[]// 临时型（含 remainTime）

// 百分比型 debuff
R_DBUFF: DbuffConf[] // 持久型
R_DBUFFS: DbuffConf[]// 临时型（含 remainTime）

初始值属性

以下属性拥有初始值，百分比 buff 基于这些值计算：

• base_hp: 基础血量
• base_mp: 基础魔法值
• base_def: 基础防御
• base_ap: 基础攻击力
• base_map: 基础魔法攻击

其他属性（CRITICAL, DODGE, AS 等）默认值为 0。

接口定义

BuffConf（buff 配置）

export interface BuffConf {
    buff: Attrs;      // 影响的属性
    BType: BType;     // VALUE(0)数值型 或 RATIO(1)百分比型
    buV: number;      // 增益值
    buC: number;      // 持续时间（0=持久，>0=临时）
    buR: number;      // 触发概率(1-100)
}

DbuffConf（debuff 配置）

export interface DbuffConf {
    debuff: DBuff;    // debuff 类型
    BType: BType;     // VALUE(0)数值型 或 RATIO(1)百分比型
    dev: number;      // 减益值
    deC: number;      // 持续时间（0=持久，>0=临时）
    deR: number;      // 触发概率(1-100)
}

API 文档

1. 初始化系统

initBuffsDebuffs(): void

作用：从 HeroInfo 读取英雄初始配置，初始化 buff/debuff 系统

调用时机：英雄加载时（在 Hero.hero_init() 中自动调用）

示例：

// 自动调用，无需手动调用
heroView.initBuffsDebuffs();

---

2. 添加 Buff

addBuff(buffConf: BuffConf): void

作用：添加 buff 效果

参数：

• buffConf: BuffConf 对象

自动行为：

• 根据 BType 和 buC 自动分类存储
• 立即重新计算 Attrs

示例：

// 添加数值型持久 buff：+10 攻击力
heroView.addBuff({
    buff: Attrs.AP,
    BType: BType.VALUE,
    buV: 10,
    buC: 0,      // 0 表示持久
    buR: 100
});

// 添加百分比型临时 buff：+20% 防御，持续 5 秒
heroView.addBuff({
    buff: Attrs.DEF,
    BType: BType.RATIO,
    buV: 20,
    buC: 5,      // 5 秒后过期
    buR: 100
});

// 从技能配置添加（来自 SkillSet）
const skillBuff: BuffConf = {
    buff: Attrs.CRITICAL,
    BType: BType.VALUE,
    buV: 25,     // +25% 暴击率
    buC: 3,      // 持续 3 秒
    buR: 100
};
heroView.addBuff(skillBuff);

---

3. 添加 Debuff

addDebuff(dbuffConf: DbuffConf): void

作用：添加 debuff 效果

参数：

• dbuffConf: DbuffConf 对象

自动行为：

• DBuff 类型自动映射到对应 Attrs
• 根据 BType 和 deC 自动分类存储
• 立即重新计算 Attrs

DBuff 映射表：

DBuff 类型	对应 Attrs	说明
STUN	CON_RES	眩晕
SLOW	AS	减速（攻击速度）
FROST	ICE_RES	冰冻抗性
BURN	DEF	易伤（降低防御）
DEAS	AS	减少 CD（攻击速度）
DEHP	HP_MAX	降低最大血量
DEAP	AP	降低攻击力
DEMGP	MAP	降低魔法攻击力
BACK	KNOCKBACK	击退概率
CRITICAL	CRITICAL	降低暴击率
CRIT_DAMAGE	CRITICAL_DMG	降低暴击伤害
DODGE	DODGE	降低闪避

示例：

// 眩晕：持久型，无数值影响
heroView.addDebuff({
    debuff: DBuff.STUN,
    BType: BType.VALUE,
    dev: 0,
    deC: 0,      // 持久
    deR: 100
});

// 减速：临时型，-30% 攻击速度，持续 3 秒
heroView.addDebuff({
    debuff: DBuff.SLOW,
    BType: BType.RATIO,
    dev: 30,     // 减少 30%
    deC: 3,      // 3 秒后过期
    deR: 100
});

// 易伤：数值型，-5 防御，持久
heroView.addDebuff({
    debuff: DBuff.BURN,
    BType: BType.VALUE,
    dev: 5,
    deC: 0,
    deR: 100
});

---

4. 移除 Buff

removeBuff(buffType: Attrs, isTemporary?: boolean): boolean

作用：移除指定属性的 buff

参数：

• buffType: 属性类型
• isTemporary: 是否移除临时型（默认 false=持久型）

返回值：是否成功移除

自动行为：

• 移除成功后自动重新计算 Attrs

示例：

// 移除持久 AP buff
heroView.removeBuff(Attrs.AP, false);

// 移除临时 DEF buff
heroView.removeBuff(Attrs.DEF, true);

---

5. 移除 Debuff

removeDebuff(debuffType: DBuff, isTemporary?: boolean): boolean

作用：移除指定类型的 debuff

参数：

• debuffType: DBuff 类型
• isTemporary: 是否移除临时型

返回值：是否成功移除

示例：

// 移除持久眩晕
heroView.removeDebuff(DBuff.STUN, false);

// 移除临时减速
heroView.removeDebuff(DBuff.SLOW, true);

---

6. 属性重新计算

recalculateAttrs(): void

作用：重新计算所有角色属性

调用时机：

• 自动在 addBuff/addDebuff/removeBuff/removeDebuff 时调用
• 自动在临时 buff/debuff 过期时调用
• 无需手动调用

计算流程：

1. 重置为基础值
2. 应用数值型 buff（持久 + 临时）
3. 应用百分比型 buff（持久 + 临时）
4. 应用数值型 debuff（持久 + 临时）
5. 应用百分比型 debuff（持久 + 临时）
6. Clamp 关键属性（防止负数）

百分比计算示例：

基础攻击力: 100
+20% buff: 100 * 1.2 = 120
-10% debuff: 120 * 0.9 = 108

---

7. 更新临时效果

updateTemporaryBuffsDebuffs(dt: number): void

作用：更新临时 buff/debuff 的剩余时间

参数：

• dt: 时间增量（秒）

调用时机：

• 自动在 update() 中每帧调用
• 无需手动调用

自动行为：

• 减少所有临时 buff/debuff 的 remainTime
• 移除 remainTime <= 0 的效果
• 移除后自动重新计算 Attrs

---

8. 查询 Buff 状态

getBuffValue(attrType: Attrs): number

作用：获取指定属性的所有 buff 总值

返回值：buff 总值

示例：

const apBuff = heroView.getBuffValue(Attrs.AP);
console.log("攻击力 buff 总和:", apBuff);

---

9. 查询 Debuff 状态

getDebuffValue(debuffType: DBuff): number

作用：获取指定 debuff 类型的所有 debuff 总值

返回值：debuff 总值

示例：

const stunDebuff = heroView.getDebuffValue(DBuff.STUN);
console.log("眩晕等级:", stunDebuff);

---

10. 检查 Debuff 存在

hasDebuff(debuffType: DBuff): boolean

作用：检查是否存在指定的 debuff

返回值：是否存在

示例：

if (heroView.hasDebuff(DBuff.STUN)) {
    console.log("角色已眩晕");
}

---

完整使用示例

场景 1：技能施加 Buff

// 在 SkillEnt.ts 或相关技能脚本中
const skillConf = SkillSet[skillId];

// 遍历技能的 buff 配置
for (const buffConf of skillConf.buffs) {
    targetHero.HeroView.addBuff(buffConf);
}

// 遍历技能的 debuff 配置
for (const dbuffConf of skillConf.debuffs) {
    targetHero.HeroView.addDebuff(dbuffConf);
}

场景 2：英雄初始化

// 在 Hero.ts 中（已自动调用）
hero_init(uuid: number, node: Node) {
    var hv = node.getComponent(HeroViewComp)!;
    let hero = HeroInfo[uuid];
    
    // ... 其他初始化 ...
    
    // 自动调用初始化 buff
    hv.initBuffsDebuffs();
    return hv;
}

场景 3：属性查询

// 获取最终计算后的属性值
const finalAP = heroView.Attrs[Attrs.AP];
const finalDEF = heroView.Attrs[Attrs.DEF];

// 获取 buff 总值
const apBuff = heroView.getBuffValue(Attrs.AP);
const defBuff = heroView.getBuffValue(Attrs.DEF);

// 检查 debuff 状态
if (heroView.hasDebuff(DBuff.STUN)) {
    // 眩晕状态下无法行动
}

---

关键设计原则

1. 兼容式修改

• 所有方法名保持不变，易于集成
• 无痛替换原有的 buff 系统

2. 自动化计算

• 每次 buff 变动自动重新计算
• 无需手动更新属性

3. 灵活的时间管理

• 持久型（buC=0）永久生效
• 临时型（buC>0）自动按秒递减
• 过期自动移除和重新计算

4. 基础值保护

• 基础属性独立存储
• 百分比计算基于原始基础值
• 不会出现多次计算的偏差

5. 属性限制

• HP_MAX, MP_MAX 最少为 1
• 百分比属性（CRITICAL, DODGE）限制在 0-100
• 防止异常数值

---

常见问题

Q: 如何区分持久和临时？ A: buC=0 是持久，buC>0 是临时（表示秒数）。

Q: 百分比如何计算？ A: 基于基础属性乘以百分比。例：base_ap=100，+20% → 100*1.2=120

Q: 多个相同 buff 是否叠加？ A: 会叠加。每个 addBuff 调用都会添加新条目。

Q: 如何清除所有 buff？ A: 调用 initBuffsDebuffs() 重新初始化，或手动清空缓存数组。

---

扩展与维护

添加新 Buff

只需在 SkillSet.ts 的技能配置中添加即可，无需修改 HeroViewComp.ts：

buffs: [
    { buff: Attrs.AP, BType: BType.VALUE, buV: 10, buC: 0, buR: 100 }
]

添加新 Debuff

1. 在 SkillSet.ts 的 DBuff enum 中添加新类型
2. 在 HeroViewComp.ts 的 getAttrFieldFromDebuff() 中添加映射
3. 在技能配置中使用

详见 BuffSystem_Extension.md 完整扩展指南。

系统的扩展特性

✅ 支持无限数量的 buff/debuff ✅ 支持新增 Attrs 属性 ✅ 支持新增 DBuff 类型 ✅ 自动处理持久/临时管理 ✅ 自动处理属性计算 ✅ 编译检查确保类型安全