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