# Buff 系统实现总结

## 修改的文件

### 1. `HeroViewComp.ts` (主要实现)

#### 导入部分更新
```typescript
import { ..., BType, BuffConf, DbuffConf } from "../common/config/SkillSet";
```

#### 新增方法（精简版）

| 方法名 | 功能 | 访问修饰符 |
|------|------|---------|
| `initBuffsDebuffs()` | 初始化 buff/debuff 系统 | public |
| `addBuff(buffConf)` | 添加 buff 效果 | public |
| `addDebuff(dbuffConf)` | 添加 debuff 效果 | public |
| `getAttrFieldFromDebuff()` | 获取 debuff 对应属性 | private |
| `recalculateAttrs()` | 重新计算属性 | public |
| `applyValueBuffs()` | 应用数值型 buff | private |
| `applyRatioBuffs()` | 应用百分比型 buff | private |
| `applyValueDebuffs()` | 应用数值型 debuff | private |
| `applyRatioDebuffs()` | 应用百分比型 debuff | private |
| `clampAttrs()` | 限制属性值范围 | private |
| `updateTemporaryBuffsDebuffs()` | 更新临时 buff/debuff | public |

**删除的方法**（持久性不需要移除）:
- ~~removeBuff()~~
- ~~removeDebuff()~~
- ~~getBuffValue()~~
- ~~getDebuffValue()~~
- ~~hasDebuff()~~

#### 关键特性
- 百分比属性限制在 0-85%（CRITICAL, DODGE, HIT）
- 持久型 buff/debuff 永久生效，不支持移除
- 临时型自动过期，自动重新计算

#### update() 方法更新
添加了对 `updateTemporaryBuffsDebuffs(dt)` 的调用，以处理临时 buff/debuff 的过期。

---

### 2. `Hero.ts` (初始化调用)

#### hero_init() 方法更新
在方法末尾添加了 `hv.initBuffsDebuffs()` 调用，在英雄初始化时自动初始化 buff 系统。

---

## 核心设计

### 存储结构

```
buffPerm/buffTemp       Buff 缓存（持久/临时）
  ├─ value             数值型
  └─ ratio             百分比型

debuffPerm/debuffTemp   Debuff 缓存（持久/临时）
  ├─ value             数值型
  └─ ratio             百分比型
```

### 优势

- **更清晰**：按持久/临时和数值/百分比二维组织
- **更简洁**：从 8 个数组变为 4 个对象
- **更易扩展**：新增字段时直接添加到对应对象
- **更易查询**：通过对象结构自文档化

### 设计原则

1. **持久性不可移除**
   - 持久型 buff/debuff 一旦添加就永久生效
   - 无需提供移除接口，简化代码

2. **临时自动过期**
   - 临时型自动在每帧更新时递减
   - 过期自动移除和重新计算属性

3. **百分比上限 85%**
   - 防止百分比属性过高导致游戏失衡
   - 暴击率、闪避、命中等限制在 0-85%

### 计算流程

```
1. 重置为基础值 (base_hp, base_mp, base_def, base_ap, base_map)
   ↓
2. 应用数值型 buff (V_BUFF + V_BUFFS)
   ↓
3. 应用百分比型 buff (R_BUFF + R_BUFFS)
   ↓
4. 应用数值型 debuff (V_DBUFF + V_DBUFFS)
   ↓
5. 应用百分比型 debuff (R_DBUFF + R_DBUFFS)
   ↓
6. 限制属性值范围 (clampAttrs)
   - HP_MAX, MP_MAX 最少 1
   - 百分比属性限制 0-85%
```

---

## 集成要点

### 1. 技能系统集成

在技能释放时调用：
```typescript
// 应用技能的 buff
for (const buffConf of skillConf.buffs) {
    targetHeroView.addBuff(buffConf);
}

// 应用技能的 debuff
for (const dbuffConf of skillConf.debuffs) {
    targetHeroView.addDebuff(dbuffConf);
}
```

### 2. SkillSet 配置

SkillSet 中的每个技能可配置 buff 和 debuff：
```typescript
{
    uuid: 6001,
    // ... 其他配置 ...
    buffs: [
        { buff: Attrs.AP, BType: BType.VALUE, buV: 10, buC: 0, buR: 100 }
    ],
    debuffs: [
        { debuff: DBuff.STUN, BType: BType.VALUE, dev: 0, deC: 3, deR: 50 }
    ]
}
```

### 3. HeroInfo 配置

HeroInfo 中可配置英雄初始 buff/debuff：
```typescript
5001: {
    // ... 其他配置 ...
    buff: [
        { buff: Attrs.CRITICAL, BType: BType.VALUE, buV: 15, buC: 0, buR: 100 }
    ],
    debuff: []
}
```

---

## 属性初始值保护

**有初始值的属性**（基础属性）：
- `base_hp`: 基础血量
- `base_mp`: 基础魔法值
- `base_def`: 基础防御
- `base_ap`: 基础攻击力
- `base_map`: 基础魔法攻击力

**百分比 buff/debuff 基于这些初始值计算**，确保多次计算不会产生偏差。

**无初始值属性**（默认为 0，限制 0-85%）：
- CRITICAL, DODGE, HIT, WFUNY, AS, REFLICT, LIFESTEAL, KNOCKBACK, CON_RES, ICE_RES, FIRE_RES, WIND_RES, ICE_POWER, FIRE_POWER, WIND_POWER, SHIELD_UP, BUFF_UP, DBUFF_UP, DIS

---

## DBuff 到 Attrs 的映射

```typescript
const debuffAttrMap = {
    [DBuff.STUN]: Attrs.CON_RES,           // 眩晕 -> 控制抗性
    [DBuff.SLOW]: Attrs.AS,                // 减速 -> 攻击速度
    [DBuff.FROST]: Attrs.ICE_RES,          // 冰冻 -> 冰冻抗性
    [DBuff.BURN]: Attrs.DEF,               // 易伤 -> 防御
    [DBuff.DEAS]: Attrs.AS,                // 减cd -> 攻击速度
    [DBuff.DEHP]: Attrs.HP_MAX,            // 减hp -> 最大生命值
    [DBuff.DEAP]: Attrs.AP,                // 减atk -> 攻击力
    [DBuff.DEMGP]: Attrs.MAP,              // 减魔法 -> 魔法攻击力
    [DBuff.BACK]: Attrs.KNOCKBACK,         // 击退 -> 击退概率
    [DBuff.CRITICAL]: Attrs.CRITICAL,      // -暴击率 -> 暴击率
    [DBuff.CRIT_DAMAGE]: Attrs.CRITICAL_DMG, // -暴击伤害 -> 暴击伤害
    [DBuff.DODGE]: Attrs.DODGE,            // -闪避 -> 闪避
};
```

---

## 性能考虑

### 优化点
1. **按需重新计算**：只在 buff 变动时计算，不是每帧
2. **缓存分离**：分离存储持久和临时，便于处理
3. **类型分组**：数值型和百分比型分离，计算方式不同

### 缓存行为
- 临时 buff/debuff 每帧检查一次（在 update 中）
- 过期移除时批量重新计算一次

---

## 使用模板

### 模板 1：技能中应用 Buff

```typescript
// 在 SkillEnt.ts 或 SkillConCom.ts 中
applySkillEffect(targetHero: Hero, skillId: number) {
    const skillConf = SkillSet[skillId];
    const heroView = targetHero.get(HeroViewComp);
    
    // 应用所有 buff
    for (const buff of skillConf.buffs) {
        heroView.addBuff(buff);
    }
    
    // 应用所有 debuff
    for (const debuff of skillConf.debuffs) {
        heroView.addDebuff(debuff);
    }
}
```

### 模板 2：查询属性值

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

---

## 兼容性说明

✅ **完全兼容**
- 所有新增方法都是 public，不改变现有接口
- 自动初始化，无需修改现有代码
- 可逐步集成，不需一次性改造全部

⚠️ **注意事项**
- 临时 buff/debuff 需在配置中指定持续时间
- 百分比计算基于基础值，不会重复计算
- 属性值有范围限制，防止异常
- 持久型 buff/debuff 无法移除

---

## 验证清单

- [x] 导入 BType, BuffConf, DbuffConf
- [x] 添加 buff/debuff 缓存字段
- [x] 实现初始化方法
- [x] 实现添加 buff 方法
- [x] 实现添加 debuff 方法
- [x] 实现属性计算方法
- [x] 实现临时效果更新
- [x] 在 update 中调用更新
- [x] 在 Hero.hero_init 中调用初始化
- [x] 编译通过，无错误
- [x] 精简不必要的方法
- [x] 百分比属性限制 0-85%

---

## 相关文件

- 📄 HeroViewComp.ts - 主实现文件
- 📄 Hero.ts - 初始化调用
- 📄 SkillSet.ts - BuffConf/DbuffConf 定义
- 📄 heroSet.ts - HeroInfo 定义
- 📄 BuffSystem_Guide.md - 详细使用指南
- 📄 BuffSystem_QuickRef.md - 快速参考
- 📄 BuffSystem_Implementation.md - 本文件