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

Buff 系统 - 快速参考卡

🎯 核心概念

概念	说明
Buff	增益效果（增加属性）
Debuff	减益效果（降低属性/能力）
持久	永不过期（buC=0 或 deC=0）
临时	按秒递减（buC>0 或 deC>0）
数值型	固定数值增减（BType.VALUE=0）
百分比型	基于基础属性的百分比（BType.RATIO=1）

---

🚀 快速开始

1️⃣ 添加数值型 Buff

heroView.addBuff({
    buff: Attrs.AP,           // 增加攻击力
    BType: BType.VALUE,       // 数值型
    buV: 10,                  // +10
    buC: 0,                   // 永久
    buR: 100                  // 100% 触发
});

2️⃣ 添加临时 Buff

heroView.addBuff({
    buff: Attrs.DEF,          // 增加防御
    BType: BType.RATIO,       // 百分比型
    buV: 20,                  // +20%
    buC: 5,                   // 持续 5 秒
    buR: 100
});

3️⃣ 添加 Debuff

heroView.addDebuff({
    debuff: DBuff.STUN,       // 眩晕
    BType: BType.VALUE,
    dev: 0,
    deC: 3,                   // 持续 3 秒
    deR: 100
});

---

📋 属性类型 (Attrs)

基础属性（有初始值）

HP_MAX      // 最大生命
MP_MAX      // 最大魔法
DEF         // 防御
AP          // 攻击力
MAP         // 魔法攻击力
SHIELD_MAX  // 护盾值

专项属性（无初始值，限制值 0-85%）

CRITICAL    // 暴击率
CRITICAL_DMG // 暴击伤害
DODGE       // 闪避
HIT         // 命中
AS          // 攻击速度
KNOCKBACK   // 击退概率
CON_RES     // 控制抗性
ICE_RES     // 冰冻抗性
FIRE_RES    // 火抗性
// ... 等等

---

⚡ Debuff 类型 (DBuff)

STUN        → Attrs.CON_RES      // 眩晕
SLOW        → Attrs.AS           // 减速
FROST       → Attrs.ICE_RES      // 冰冻
BURN        → Attrs.DEF          // 易伤
DEAS        → Attrs.AS           // 减CD
DEHP        → Attrs.HP_MAX       // 减血量
DEAP        → Attrs.AP           // 减攻击
DEMGP       → Attrs.MAP          // 减魔法
BACK        → Attrs.KNOCKBACK    // 击退
CRITICAL    → Attrs.CRITICAL     // 降暴击
CRIT_DAMAGE → Attrs.CRITICAL_DMG // 降爆伤
DODGE       → Attrs.DODGE        // 降闪避

---

📊 计算示例

数值型 Buff

基础 AP: 100
+Buff: +10
结果: 110

百分比型 Buff

基础 AP: 100
+20% Buff: 100 * 1.2 = 120

混合计算

基础 AP: 100
+20% Buff: 100 * 1.2 = 120
+10 Buff:  120 + 10 = 130
-30% Debuff: 130 * 0.7 = 91

---

🔧 API 一览表

方法	功能
addBuff(conf)	添加 buff
addDebuff(conf)	添加 debuff（自动区分属性型/状态型）
hasState(type)	检查状态型 debuff（最简洁） ⭐
getDebuff(type)	获取属性型 debuff 对象
hasDebuff(type)	检查属性型 debuff 存在
getBuff(type)	获取 buff 对象
hasBuff(type)	检查 buff 存在

---

💾 缓存结构 & 访问方式

状态型 Debuff（最简洁）⭐

// 使用 Set 存储，O(1) 快速判断
heroView.hasState(DBuff.STUN)        // ✅ 最推荐
heroView.stateDebuffTemp.has(DBuff.STUN)  // 直接访问

属性型 Buff & Debuff

// 使用 Map 存储，支持对象访问
heroView.hasBuff(Attrs.AP)           // 检查 buff
heroView.getBuff(Attrs.AP)           // 获取 buff
heroView.hasDebuff(DBuff.SLOW)       // 检查 debuff
heroView.getDebuff(DBuff.SLOW)       // 获取 debuff

缓存结构一览

buffPerm/buffTemp
  ├─ value: Map<Attrs, buff>
  └─ ratio: Map<Attrs, buff>

debuffPerm/debuffTemp（属性型）
  ├─ value: Map<DBuff, debuff>
  └─ ratio: Map<DBuff, debuff>

stateDebuffPerm/stateDebuffTemp（状态型）
  └─ Set<DBuff>  ← 最简洁的访问

---

✅ 使用检查清单

• 导入 BType, BuffConf, DbuffConf
• 在 SkillSet 中配置 buff/debuff
• 技能释放时调用 addBuff/addDebuff
• 临时 buff/debuff 自动过期
• 查询属性用 Attrs[type]

---

🐛 常见错误

❌ 错误 1: 混淆 buC 和 deC 的含义

buC: 0      // ✅ 正确：持久
buC: 5      // ✅ 正确：5 秒临时

❌ 错误 2: DBuff 类型用错了

// ❌ 错误
addDebuff({ debuff: Attrs.AP, ... });

// ✅ 正确
addDebuff({ debuff: DBuff.DEAP, ... });

---

🎮 实战示例

技能释放流程

// 1. 获取技能配置
const skill = SkillSet[skillId];

// 2. 应用 buff
for (const buff of skill.buffs) {
    heroView.addBuff(buff);
}

// 3. 应用 debuff
for (const debuff of skill.debuffs) {
    heroView.addDebuff(debuff);
}

// 4. 属性自动重新计算！

---

📚 完整文档

• 📖 BuffSystem_Guide.md - 详细使用指南
• 📋 BuffSystem_Implementation.md - 实现细节
• 🎯 BuffSystem_QuickRef.md - 本快速参考
• 🚀 BuffSystem_Extension.md - 扩展指南（如何添加新 buff/debuff）

---

🎓 学习路径

1. 快速开始 ➜ 先看这个文件
2. 详细学习 ➜ 阅读 BuffSystem_Guide.md
3. 深入理解 ➜ 查看 BuffSystem_Implementation.md
4. 需要扩展 ➜ 阅读 BuffSystem_Extension.md
5. 查看源码 ➜ 阅读 HeroViewComp.ts

---

💡 记住：系统会自动计算属性，临时效果自动过期！