# Buff 系统 - 快速参考卡

## 🎯 核心概念

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

---

## 🚀 快速开始

### 1️⃣ 添加数值型 Buff

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

### 2️⃣ 添加临时 Buff

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

### 3️⃣ 添加 Debuff

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

---

## 📋 属性类型 (Attrs)

### 基础属性（有初始值）
```typescript
HP_MAX      // 最大生命
MP_MAX      // 最大魔法
DEF         // 防御
AP          // 攻击力
MAP         // 魔法攻击力
SHIELD_MAX  // 护盾值
```

### 专项属性（无初始值，限制值 0-85%）
```typescript
CRITICAL    // 暴击率
CRITICAL_DMG // 暴击伤害
DODGE       // 闪避
HIT         // 命中
AS          // 攻击速度
KNOCKBACK   // 击退概率
CON_RES     // 控制抗性
ICE_RES     // 冰冻抗性
FIRE_RES    // 火抗性
// ... 等等
```

---

## ⚡ Debuff 类型 (DBuff)

```typescript
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（最简洁）⭐

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

### 属性型 Buff & Debuff

```typescript
// 使用 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 的含义
```typescript
buC: 0      // ✅ 正确：持久
buC: 5      // ✅ 正确：5 秒临时
```

❌ **错误 2**: DBuff 类型用错了
```typescript
// ❌ 错误
addDebuff({ debuff: Attrs.AP, ... });

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

---

## 🎮 实战示例

### 技能释放流程
```typescript
// 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

---

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