# BUFF 系统完整使用指南

## 系统概述

HeroViewComp 中的 buff 系统是一套完整的属性增强/减弱管理体系，支持：
- **数值型 buff/debuff**：固定数值增减
- **百分比型 buff/debuff**：基于基础属性的百分比增减
- **持久型**：永久生效，直到主动移除
- **临时型**：按时间递减，自动过期

## 架构设计

### 存储结构

```typescript
// 数值型 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 配置）

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

### DbuffConf（debuff 配置）

```typescript
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() 中自动调用）

**示例**：
```typescript
// 自动调用，无需手动调用
heroView.initBuffsDebuffs();
```

---

### 2. 添加 Buff

#### `addBuff(buffConf: BuffConf): void`

**作用**：添加 buff 效果

**参数**：
- `buffConf`: BuffConf 对象

**自动行为**：
- 根据 BType 和 buC 自动分类存储
- 立即重新计算 Attrs

**示例**：

```typescript
// 添加数值型持久 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 | 降低闪避 |

**示例**：

```typescript
// 眩晕：持久型，无数值影响
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

**示例**：

```typescript
// 移除持久 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`: 是否移除临时型

**返回值**：是否成功移除

**示例**：

```typescript
// 移除持久眩晕
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 总值

**示例**：
```typescript
const apBuff = heroView.getBuffValue(Attrs.AP);
console.log("攻击力 buff 总和:", apBuff);
```

---

### 9. 查询 Debuff 状态

#### `getDebuffValue(debuffType: DBuff): number`

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

**返回值**：debuff 总值

**示例**：
```typescript
const stunDebuff = heroView.getDebuffValue(DBuff.STUN);
console.log("眩晕等级:", stunDebuff);
```

---

### 10. 检查 Debuff 存在

#### `hasDebuff(debuffType: DBuff): boolean`

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

**返回值**：是否存在

**示例**：
```typescript
if (heroView.hasDebuff(DBuff.STUN)) {
    console.log("角色已眩晕");
}
```

---

## 完整使用示例

### 场景 1：技能施加 Buff

```typescript
// 在 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：英雄初始化

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

### 场景 3：属性查询

```typescript
// 获取最终计算后的属性值
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：

```typescript
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 类型
✅ 自动处理持久/临时管理
✅ 自动处理属性计算
✅ 编译检查确保类型安全