# 增益/减益状态系统

<cite>
**本文档引用的文件**
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts)
- [HeroAttrs.ts](file://assets/script/game/common/config/HeroAttrs.ts)
- [SkillSet.ts](file://assets/script/game/common/config/SkillSet.ts)
- [timedCom.ts](file://assets/script/game/skill/timedCom.ts)
- [Hero.ts](file://assets/script/game/hero/Hero.ts)
</cite>

## 目录
1. [系统概述](#系统概述)
2. [核心组件架构](#核心组件架构)
3. [状态系统设计](#状态系统设计)
4. [状态持续时间管理](#状态持续时间管理)
5. [视觉反馈机制](#视觉反馈机制)
6. [状态叠加与刷新策略](#状态叠加与刷新策略)
7. [状态特效节点管理](#状态特效节点管理)
8. [生命周期管理](#生命周期管理)
9. [性能优化措施](#性能优化措施)
10. [使用示例与最佳实践](#使用示例与最佳实践)

## 系统概述

增益/减益状态系统是一个复杂的状态管理框架，负责管理英雄的各种状态效果，包括攻击提升、防御增强、灼烧、冰冻、眩晕等多种状态。该系统采用ECS架构设计，通过分离的状态管理组件和视觉反馈组件协同工作，实现了高效的状态管理和实时的视觉反馈。

### 主要特性

- **多重叠加支持**：同一属性允许多个增益/减益效果同时存在
- **持久与临时状态**：支持永久buff和限时debuff的统一管理
- **类型化属性系统**：区分数值型和百分比型属性的不同计算方式
- **实时视觉反馈**：状态变化时的即时视觉效果展示
- **性能优化**：通过对象池和定时器复用提升系统效率

## 核心组件架构

系统由三个核心组件构成，每个组件承担不同的职责：

```mermaid
classDiagram
class HeroViewComp {
+Record~number,Array~ BUFFS
+Record~number,Array~ BUFFS_TEMP
+Object NeAttrs
+addBuff(buffConf)
+removeBuff(attrIndex, value, isPermanent)
+clearBuffs(attrIndex, isBuff)
+recalculateSingleAttr(attrIndex)
+updateTemporaryBuffsDebuffs(dt)
}
class BuffComp {
+Node top_node
+Node ap_node
+Node cd_node
+Node def_node
+Node hp_node
+Node crit_node
+number ap_cd
+number cd_cd
+number def_cd
+number hp_cd
+number crit_cd
+Timer timer
+hp_show(hp, hp_max)
+mp_show(mp, mp_max)
+show_shield(shield, shield_max)
+show_do_buff(name)
+in_iced(t, ap)
+in_fired(t, ap)
+in_yun(t, ap)
}
class timedCom {
+number time
+number cd
+number ap
+update(deltaTime)
}
HeroViewComp --> BuffComp : "管理视觉反馈"
HeroViewComp --> timedCom : "创建临时状态"
BuffComp --> timedCom : "管理特效节点"
```

**图表来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L44-L84)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L0-L46)
- [timedCom.ts](file://assets/script/game/skill/timedCom.ts#L0-L24)

**章节来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L44-L84)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L0-L46)

## 状态系统设计

### 数据结构设计

系统采用统一的数组设计模式，支持多种类型的状态管理：

```mermaid
erDiagram
HeroViewComp {
Record BUFFS
Record BUFFS_TEMP
Object NeAttrs
}
BuffConf {
Attrs buff
BType BType
number value
number time
number chance
}
BuffInstance {
number value
BType BType
number remainTime
}
NeAttrInstance {
number value
number time
}
HeroViewComp ||--o{ BuffInstance : "管理"
BuffConf ||--|| BuffInstance : "转换为"
HeroViewComp ||--o{ NeAttrInstance : "管理负面状态"
```

**图表来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L20-L47)
- [SkillSet.ts](file://assets/script/game/common/config/SkillSet.ts#L80-L90)

### 属性类型系统

系统定义了两种属性类型，每种类型采用不同的计算方式：

| 属性类型 | 描述 | 计算公式 | 示例 |
|---------|------|----------|------|
| 数值型 (VALUE) | 直接加减绝对数值 | `(基础值 + 所有数值型buff之和) × (1 + 所有百分比buff之和/100)` | 攻击力、防御力、生命值 |
| 百分比型 (RATIO) | 按百分比计算 | 基础值 + 所有数值型buff之和 + 所有百分比buff之和 | 暴击率、闪避率、伤害加成 |

**章节来源**
- [HeroAttrs.ts](file://assets/script/game/common/config/HeroAttrs.ts#L142-L226)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L251-L320)

## 状态持续时间管理

### cd字段族系统

系统通过专门的cd字段族来管理各种状态的持续时间：

```mermaid
flowchart TD
A[状态触发] --> B{判断状态类型}
B --> |增益状态| C[设置ap_cd字段]
B --> |减益状态| D[设置deap_cd字段]
C --> E[启动计时器]
D --> F[启动计时器]
E --> G[更新视觉反馈]
F --> G
G --> H{计时结束?}
H --> |否| I[继续监控]
H --> |是| J[清除状态]
I --> G
J --> K[更新属性计算]
```

**图表来源**
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L15-L30)

### 定时器更新机制

系统采用帧更新的方式管理状态持续时间：

```mermaid
sequenceDiagram
participant Game as "游戏主循环"
participant Hero as "HeroViewComp"
participant Timer as "updateTemporaryBuffsDebuffs"
participant Buff as "状态容器"
Game->>Hero : update(deltaTime)
Hero->>Timer : 调用定时器更新
Timer->>Buff : 遍历BUFFS_TEMP
loop 每个临时buff
Buff->>Buff : remainTime -= deltaTime
alt remainTime <= 0
Buff->>Buff : 从数组移除
Buff->>Hero : 标记属性受影响
end
end
Timer->>Hero : 重新计算受影响属性
Hero->>Game : 状态更新完成
```

**图表来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L350-L400)

**章节来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L350-L400)

## 视觉反馈机制

### UI同步逻辑

系统通过专门的方法管理UI元素的显示状态：

```mermaid
flowchart LR
A[状态变化] --> B[调用相应显示方法]
B --> C{状态类型}
C --> |生命值| D[hp_show方法]
C --> |魔法值| E[mp_show方法]
C --> |护盾| F[show_shield方法]
C --> |特殊效果| G[show_do_buff方法]
D --> H[更新进度条]
E --> H
F --> H
G --> I[创建特效节点]
H --> J[延迟更新确保同步]
I --> K[设置位置和时间]
J --> L[视觉反馈完成]
K --> L
```

**图表来源**
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L60-L120)

### 特效节点管理

系统支持动态创建和销毁状态特效节点：

| 方法名 | 功能 | 参数 | 创建的节点类型 |
|--------|------|------|---------------|
| `show_do_buff` | 显示通用状态特效 | `name: string` | buff_xxx.prefab |
| `in_iced` | 显示冰冻状态特效 | `t: number, ap: number` | buff_iced.prefab |
| `in_fired` | 显示燃烧状态特效 | `t: number, ap: number` | buff_fired.prefab |
| `in_yun` | 显示眩晕状态特效 | `t: number, ap: number` | buff_yun.prefab |
| `dead` | 显示死亡特效 | 无 | dead.prefab |

**章节来源**
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L120-L200)

## 状态叠加与刷新策略

### 叠加规则

系统支持同属性多实例叠加，每种状态实例保持独立：

```mermaid
flowchart TD
A[添加新状态] --> B{检查属性是否存在}
B --> |不存在| C[创建新数组]
B --> |存在| D[添加到现有数组]
C --> E[设置状态实例]
D --> E
E --> F{状态类型判断}
F --> |持久| G[BUFFS数组]
F --> |临时| H[BUFFS_TEMP数组]
G --> I[直接添加]
H --> J[添加remainTime字段]
I --> K[重新计算属性]
J --> K
K --> L[触发视觉更新]
```

**图表来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L217-L251)

### 刷新与清除策略

系统提供了多种状态清除机制：

```mermaid
flowchart TD
A[状态清除请求] --> B{清除范围}
B --> |单属性| C[clearBuffsForAttr]
B --> |全属性| D[遍历所有属性]
C --> E{过滤条件}
E --> |增益| F[value > 0]
E --> |减益| G[value < 0]
E --> |全部| H[无条件清除]
F --> I[过滤并保留符合条件的buff]
G --> I
H --> I
I --> J{数组是否为空}
J --> |是| K[删除属性条目]
J --> |否| L[保留数组]
K --> M[重新计算属性]
L --> M
M --> N[更新视觉反馈]
```

**图表来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L421-L459)

**章节来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L217-L251)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L421-L459)

## 状态特效节点管理

### 动态创建流程

状态特效节点的创建遵循统一的流程：

```mermaid
sequenceDiagram
participant System as "状态系统"
participant Manager as "BuffComp"
participant Resource as "资源管理器"
participant Scene as "场景节点"
participant Timed as "timedCom组件"
System->>Manager : 请求创建特效
Manager->>Resource : 获取预制体资源
Resource-->>Manager : 返回Prefab对象
Manager->>Manager : instantiate(prefab)
Manager->>Scene : 设置父节点
Manager->>Manager : setPosition(position)
alt 临时状态特效
Manager->>Timed : 设置时间参数
Timed->>Timed : 启动定时器
Timed->>Scene : 自动销毁
end
Manager-->>System : 特效创建完成
```

**图表来源**
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L120-L180)
- [timedCom.ts](file://assets/script/game/skill/timedCom.ts#L0-L24)

### 销毁机制

临时状态特效通过定时器组件自动销毁：

```mermaid
stateDiagram-v2
[*] --> Created : instantiate()
Created --> Active : setPosition()
Active --> Updating : update(deltaTime)
Updating --> Active : remainTime > 0
Updating --> Destroyed : remainTime <= 0
Destroyed --> [*] : node.destroy()
```

**图表来源**
- [timedCom.ts](file://assets/script/game/skill/timedCom.ts#L15-L24)

**章节来源**
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L120-L180)
- [timedCom.ts](file://assets/script/game/skill/timedCom.ts#L0-L24)

## 生命周期管理

### 完整生命周期示例

以冰冻状态为例，展示状态的完整生命周期：

```mermaid
sequenceDiagram
participant Skill as "技能系统"
participant Hero as "HeroViewComp"
participant Buff as "BuffComp"
participant Effect as "特效系统"
participant UI as "UI系统"
Note over Skill,UI : 冰冻状态触发
Skill->>Hero : addBuff(冰冻配置)
Hero->>Hero : 添加到BUFFS_TEMP
Hero->>Hero : recalculateSingleAttr(DEF)
Hero->>Buff : in_iced(duration, ap)
Buff->>Effect : 创建buff_iced特效
Effect->>Effect : 设置remainTime
Buff->>UI : 更新防御显示
UI-->>Buff : 视觉反馈确认
loop 每帧更新
Hero->>Hero : updateTemporaryBuffsDebuffs(dt)
Hero->>Hero : 减少remainTime
alt remainTime <= 0
Hero->>Hero : 从BUFFS_TEMP移除
Hero->>Hero : recalculateSingleAttr(DEF)
Hero->>Buff : 清除特效
Hero->>UI : 更新防御显示
end
end
```

**图表来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L217-L251)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L150-L170)

### 状态移除流程

系统提供了多种状态移除方式：

| 移除方式 | 触发条件 | 影响范围 | 性能影响 |
|----------|----------|----------|----------|
| 自然消失 | remainTime <= 0 | 单个状态 | 低 |
| 主动清除 | clearBuffs() | 指定属性 | 中等 |
| 类型过滤清除 | clearBuffs(attrIndex, isBuff) | 指定属性和类型 | 中等 |
| 全部清除 | clearAllNeAttrs() | 所有负面状态 | 高 |

**章节来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L385-L425)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L457-L500)

## 性能优化措施

### 对象池应用

虽然当前实现中没有显式的对象池，但系统设计考虑了以下优化点：

1. **定时器复用**：使用统一的Timer实例管理多个状态的计时
2. **数组操作优化**：采用splice而非filter进行状态移除
3. **批量属性计算**：通过Set记录受影响属性，避免重复计算

### 内存管理策略

```mermaid
flowchart TD
A[状态添加] --> B[检查内存使用]
B --> C{超出阈值?}
C --> |否| D[正常添加]
C --> |是| E[触发垃圾回收]
E --> F[清理无效状态]
F --> G[压缩数组结构]
G --> D
D --> H[更新统计信息]
H --> I[监控内存使用]
```

### 更新频率优化

系统采用智能更新策略：

- **暂停检测**：在游戏暂停时跳过状态更新
- **属性变更追踪**：只重新计算受影响的属性
- **延迟更新**：使用scheduleOnce确保UI同步

**章节来源**
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L40-L50)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L470-L490)

## 使用示例与最佳实践

### 基本使用模式

```typescript
// 添加攻击提升buff
const attackBuff: BuffConf = {
    buff: Attrs.AP,
    BType: BType.VALUE,
    value: 50,
    time: 10,
    chance: 100
};
hero.addBuff(attackBuff);

// 添加百分比伤害加成
const damageBuff: BuffConf = {
    buff: Attrs.AP,
    BType: BType.RATIO,
    value: 20,
    time: 5,
    chance: 80
};
hero.addBuff(damageBuff);

// 清除特定属性的所有增益
hero.clearBuffs(Attrs.AP, true);

// 清除所有负面状态
hero.clearAllNeAttrs();
```

### 最佳实践建议

1. **状态优先级管理**：合理安排状态的添加顺序
2. **性能监控**：定期检查状态数量，避免过多叠加
3. **视觉反馈同步**：确保状态变化时UI及时更新
4. **内存泄漏预防**：及时清理不再需要的状态
5. **状态冲突处理**：避免相同属性的相互抵消

### 常见问题解决

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 状态不消失 | remainTime未正确更新 | 检查updateTemporaryBuffsDebuffs调用 |
| UI显示异常 | 视觉反馈未触发 | 确认BuffComp相关方法被调用 |
| 性能下降 | 状态数量过多 | 实施状态数量限制和定期清理 |
| 内存泄漏 | 特效节点未销毁 | 检查timedCom组件的自动销毁机制 |

**章节来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L44-L84)
- [SkillSet.ts](file://assets/script/game/common/config/SkillSet.ts#L80-L90)