# 奖励系统

<cite>
**本文档引用的文件**
- [Mission.ts](file://assets/script/game/common/config/Mission.ts)
- [Tasks.ts](file://assets/script/game/common/config/Tasks.ts)
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts) - *最近提交中已更新*
- [MissionHeroComp.ts](file://assets/script/game/map/MissionHeroComp.ts)
- [MissionMonComp.ts](file://assets/script/game/map/MissionMonComp.ts)
- [MissionHomeComp.ts](file://assets/script/game/map/MissionHomeComp.ts)
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts)
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts)
- [HeroAttrs.ts](file://assets/script/game/common/config/HeroAttrs.ts)
- [TalSet.ts](file://assets/script/game/common/config/TalSet.ts)
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts)
</cite>

## 更新摘要
**已做更改**
- 更新了“核心组件分析”中关于MissionComp的实体销毁逻辑说明
- 修正了“性能优化考虑”中关于组件清理的描述
- 移除了过时的故障排除建议，增加了针对空引用问题的解决方案
- 所有文件引用和标题均已转换为中文

## 目录
1. [简介](#简介)
2. [系统架构概览](#系统架构概览)
3. [核心组件分析](#核心组件分析)
4. [奖励类型与配置](#奖励类型与配置)
5. [三选一奖励机制](#三选一奖励机制)
6. [战斗胜利与奖励选择](#战斗胜利与奖励选择)
7. [奖励触发条件](#奖励触发条件)
8. [数据绑定与UI展示](#数据绑定与UI展示)
9. [扩展新奖励类型](#扩展新奖励类型)
10. [性能优化考虑](#性能优化考虑)
11. [故障排除指南](#故障排除指南)
12. [总结](#总结)

## 简介

奖励系统是本游戏的核心机制之一，采用三选一奖励选择模式，在每波怪物清理后为玩家提供三种不同类型的奖励选项。系统基于肉鸽（Roguelike）游戏设计理念，通过策略性的奖励选择来影响英雄的成长路径，为玩家提供多样化的游戏体验和重玩价值。

奖励系统的主要特点包括：
- **三选一选择机制**：每轮战斗结束后提供三个奖励选项
- **多样化奖励类型**：属性提升、技能升级、装备获取、新技能解锁等
- **策略性决策**：玩家需要根据当前阵容和游戏进度做出最优选择
- **动态权重系统**：奖励权重根据游戏进度和玩家状态动态调整
- **可视化反馈**：清晰的奖励预览和效果展示

## 系统架构概览

奖励系统采用模块化架构设计，各组件职责明确，通过事件驱动的方式协同工作。

```mermaid
graph TB
subgraph "战斗系统"
MC[MissionComp<br/>任务控制器]
MMC[MissionMonComp<br/>怪物控制器]
MHMC[MissionHeroComp<br/>英雄控制器]
end
subgraph "奖励系统"
VC[VictoryComp<br/>胜利界面]
SM[SingletonModule<br/>单例模块]
end
subgraph "配置系统"
MS[Mission.ts<br/>战斗配置]
TS[Tasks.ts<br/>任务配置]
RS[RogueConfig.ts<br/>肉鸽配置]
end
subgraph "数据层"
GD[GameData<br/>游戏数据]
MD[MissionData<br/>关卡数据]
end
MC --> VC
MC --> SM
MMC --> MC
MHMC --> MC
VC --> SM
SM --> GD
SM --> MD
MS --> MC
RS --> MMC
TS --> MC
```

**图表来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L1-L151)
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L1-L75)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L41)

## 核心组件分析

### MissionComp - 任务控制器

MissionComp是奖励系统的核心控制器，负责整个战斗流程的管理和奖励发放。

```mermaid
classDiagram
class MissionComp {
+rewards : any[]
+game_data : any
+onLoad() void
+update(dt : number) void
+do_reward() void
+do_drop(drop_item : any[], game_data : any) void
+do_mon_dead(event : any, data : any) void
+do_hero_dead(event : any, data : any) void
+mission_start() Promise~void~
+to_fight() void
+fight_end() void
+mission_end() void
+data_init() void
+cleanComponents() void
}
class SingletonModuleComp {
+mission : any
+vmdata : any
+data : any
}
class GameEvent {
+MissionStart
+MonDead
+HeroDead
+FightEnd
+MissionEnd
}
MissionComp --> SingletonModuleComp : "使用"
MissionComp --> GameEvent : "监听"
```

**图表来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L15-L151)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L20-L41)

**节来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L1-L151)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L41)

### VictoryComp - 胜利界面控制器

VictoryComp负责战斗胜利后的奖励选择界面，处理玩家的选择和奖励发放。

```mermaid
sequenceDiagram
participant Player as 玩家
participant VC as VictoryComp
participant SM as SingletonModule
participant UI as 用户界面
Player->>VC : 战斗胜利
VC->>SM : 获取奖励数据
SM-->>VC : 返回奖励列表
VC->>UI : 显示奖励选项
Player->>UI : 选择奖励
UI->>VC : 发送选择事件
VC->>SM : 处理奖励发放
SM-->>VC : 确认奖励生效
VC->>Player : 显示奖励效果
```

**图表来源**
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L25-L75)

**节来源**
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L1-L75)

### MissionHeroComp & MissionMonComp - 奖励触发器

这两个组件分别负责英雄和怪物的奖励触发条件监控。

```mermaid
flowchart TD
A[战斗开始] --> B{检查英雄状态}
B --> |英雄存活| C[继续战斗]
B --> |英雄死亡| D[战斗失败]
C --> E{检查怪物状态}
E --> |怪物存活| F[继续战斗]
E --> |怪物死亡| G[战斗胜利]
F --> H[更新战斗数据]
H --> B
G --> I[触发奖励生成]
I --> J[打开胜利界面]
J --> K[等待玩家选择]
D --> L[打开失败界面]
```

**图表来源**
- [MissionHeroComp.ts](file://assets/script/game/map/MissionHeroComp.ts#L1-L81)
- [MissionMonComp.ts](file://assets/script/game/map/MissionMonComp.ts#L1-L240)

**节来源**
- [MissionHeroComp.ts](file://assets/script/game/map/MissionHeroComp.ts#L1-L81)
- [MissionMonComp.ts](file://assets/script/game/map/MissionMonComp.ts#L1-L240)

## 奖励类型与配置

### 基础奖励配置

奖励系统基于Mission.ts中的FightSet枚举定义了各种奖励类型的基础配置：

| 奖励类型 | 配置值 | 描述 |
|---------|--------|------|
| ATK_ADD_COUNT | 4 | 伙伴攻击力增加数量 |
| ATK_ADD_GLOD | 1 | 金币增加数量 |
| CRIT_DAMAGE | 50 | 暴击伤害百分比 |
| DOUBLE_ATK_RATE | 100 | 额外攻击默认概率 |
| GREEN_GOLD | 1 | 绿色金币数量 |
| BLUE_GOLD | 2 | 蓝色金币数量 |
| PURPLE_GOLD | 3 | 紫色金币数量 |
| ORANGE_GOLD | 4 | 橙色金币数量 |

**节来源**
- [Mission.ts](file://assets/script/game/common/config/Mission.ts#L1-L60)

### 英雄属性系统

英雄属性系统通过HeroAttrs.ts定义了完整的属性体系：

```mermaid
graph LR
subgraph "基础属性"
HP[生命值 HP_MAX]
MP[魔法值 MP_MAX]
AP[攻击力 AP]
MAP[魔法攻击力 MAP]
end
subgraph "防御属性"
DEF[物理防御 DEF]
MDEF[魔法防御 MDEF]
SHIELD[护盾值 SHIELD_MAX]
end
subgraph "特殊属性"
SPEED[移动速度 SPEED]
DIS[攻击距离 DIS]
CRIT[暴击率 CRITICAL]
DODGE[闪避率 DODGE]
end
HP --> DEF
MP --> MDEF
AP --> CRIT
MAP --> CRIT
```

**图表来源**
- [HeroAttrs.ts](file://assets/script/game/common/config/HeroAttrs.ts#L25-L47)

**节来源**
- [HeroAttrs.ts](file://assets/script/game/common/config/HeroAttrs.ts#L1-L544)

### 天赋系统配置

天赋系统通过TalSet.ts定义了丰富的天赋效果：

| 天赋类型 | 示例 | 效果描述 |
|---------|------|----------|
| 等级类天赋 | 剑意提升 | 每升5级，攻击力增加10% |
| 攻击触发类 | 胡服骑射 | 每3次攻击，攻击速度增加5% |
| 受伤触发类 | 坚韧意志 | 每受伤3次，防御力增加2点 |
| 特定等级触发 | 兵圣之道 | 20级获得额外技能 |

**节来源**
- [TalSet.ts](file://assets/script/game/common/config/TalSet.ts#L68-L114)

## 三选一奖励机制

### 奖励生成算法

奖励系统采用基于权重的概率算法生成奖励选项：

```mermaid
flowchart TD
A[战斗胜利] --> B[计算基础权重]
B --> C[应用难度系数]
C --> D[生成奖励池]
D --> E{随机选择奖励}
E --> |奖励1| F[验证奖励有效性]
E --> |奖励2| F
E --> |奖励3| F
F --> G{奖励有效?}
G --> |是| H[添加到选项列表]
G --> |否| I[重新生成]
H --> J[返回三个奖励选项]
I --> E
```

**图表来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L40-L50)

### 奖励权重调整

奖励权重系统根据以下因素动态调整：

1. **游戏进度**：随着关卡推进，奖励权重逐渐向高级奖励倾斜
2. **英雄状态**：根据当前英雄阵容和等级调整奖励偏好
3. **玩家行为**：记录玩家的选择历史，优化奖励推荐
4. **随机事件**：特殊事件可能临时改变奖励权重

**节来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L40-L50)

## 战斗胜利与奖励选择

### 战斗胜利流程

战斗胜利后，系统按照以下流程处理奖励选择：

```mermaid
sequenceDiagram
participant Game as 游戏引擎
participant MC as MissionComp
participant VC as VictoryComp
participant SM as SingletonModule
participant UI as 用户界面
Game->>MC : 战斗结束事件
MC->>MC : 检查战斗结果
alt 战斗胜利
MC->>SM : 获取奖励数据
SM-->>MC : 返回奖励列表
MC->>VC : 打开胜利界面
VC->>UI : 显示奖励选项
UI->>VC : 玩家选择奖励
VC->>SM : 处理奖励发放
SM-->>VC : 确认奖励生效
VC->>Game : 关闭胜利界面
else 战斗失败
MC->>Game : 显示失败界面
end
```

**图表来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L80-L95)
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L25-L40)

**节来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L80-L95)
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L25-L40)

### 奖励选择界面

胜利界面提供直观的奖励选择功能：

1. **奖励预览**：每个奖励选项都有详细的属性说明
2. **视觉反馈**：通过图标和颜色区分不同类型的奖励
3. **选择确认**：提供明确的选择按钮和取消选项
4. **即时反馈**：选择后立即显示奖励效果

**节来源**
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L1-L75)

## 奖励触发条件

### 英雄奖励触发

英雄奖励通过MissionHeroComp监控英雄状态变化：

```mermaid
stateDiagram-v2
[*] --> 战斗准备
战斗准备 --> 英雄召唤 : Zhaohuan事件
英雄召唤 --> 战斗中 : FightReady事件
战斗中 --> 英雄存活 : 英雄未死亡
战斗中 --> 英雄死亡 : HeroDead事件
英雄存活 --> 战斗中 : 继续战斗
英雄死亡 --> 战斗失败 : 英雄全灭
战斗失败 --> [*]
```

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

**节来源**
- [MissionHeroComp.ts](file://assets/script/game/map/MissionHeroComp.ts#L1-L81)

### 怪物奖励触发

怪物奖励通过MissionMonComp监控怪物击杀情况：

```mermaid
flowchart TD
A[怪物生成] --> B[怪物存活]
B --> C{怪物死亡?}
C --> |否| D[继续战斗]
C --> |是| E[更新怪物计数]
E --> F{还有怪物?}
F --> |是| B
F --> |否| G[战斗胜利]
D --> C
G --> H[触发奖励生成]
```

**图表来源**
- [MissionMonComp.ts](file://assets/script/game/map/MissionMonComp.ts#L40-L60)

**节来源**
- [MissionMonComp.ts](file://assets/script/game/map/MissionMonComp.ts#L1-L240)

### 事件奖励触发

特殊事件通过RogueConfig.ts定义的事件系统触发：

| 事件类型 | 概率 | 效果 |
|---------|------|------|
| TREASURE | 40% | 增加50金币奖励 |
| TRAP | 20% | 对玩家造成伤害 |
| BUFF | 25% | 增加临时增益效果 |
| DEBUFF | 15% | 增加临时减益效果 |

**节来源**
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts#L279-L310)

## 数据绑定与UI展示

### 单例模块数据管理

SingletonModuleComp作为全局数据管理中心，维护奖励系统所需的所有数据：

```mermaid
classDiagram
class SingletonModuleComp {
+mission : MissionData
+vmdata : ViewData
+data : GameData
+guides : number[]
+current_guide : number
+openid : string
}
class MissionData {
+status : number
+play : boolean
+pause : boolean
+in_select : boolean
+in_fight : boolean
}
class ViewData {
+mission_data : MissionData
}
class GameData {
+gold : number
+diamond : number
+score : number
+mission : number
}
SingletonModuleComp --> MissionData
SingletonModuleComp --> ViewData
SingletonModuleComp --> GameData
```

**图表来源**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L20-L41)

**节来源**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L41)

### UI配置与界面管理

GameUIConfig.ts定义了奖励系统相关的界面配置：

| UI标识 | 预制件路径 | 层级 |
|--------|-----------|------|
| Victory | gui/element/victory | UI层 |
| Loading | loading/prefab/loading | UI层 |

**节来源**
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L36)

## 扩展新奖励类型

### 添加新奖励类型

要扩展新的奖励类型，需要修改以下文件：

1. **Mission.ts** - 添加新的奖励配置常量
2. **HeroAttrs.ts** - 定义新属性类型
3. **TalSet.ts** - 添加新天赋效果
4. **RogueConfig.ts** - 更新事件配置

### 奖励权重调整

通过修改FightSet枚举可以调整各类奖励的权重：

```typescript
// 示例：增加高级奖励的权重
export enum FightSet {
    // 高级奖励权重提升
    PURPLE_GOLD = 5,    // 紫色金币权重从3提升到5
    ORANGE_GOLD = 8,    // 橙色金币权重从4提升到8
    // 中级奖励保持不变
    BLUE_GOLD = 2,
    GREEN_GOLD = 1,
}
```

### 自定义奖励算法

可以通过重写MissionComp中的do_reward方法来实现自定义奖励算法：

```typescript
// 示例：基于英雄阵容的奖励算法
do_reward() {
    // 获取当前英雄阵容
    const heroes = this.getCurrentHeroes();
    
    // 根据阵容特点调整奖励权重
    const weightMap = this.calculateRewardWeights(heroes);
    
    // 生成奖励选项
    this.rewards = this.generateRewards(weightMap);
}
```

## 性能优化考虑

### 内存管理

奖励系统采用以下内存优化策略：

1. **组件生命周期管理**：及时销毁不需要的组件
2. **数据缓存策略**：缓存常用的奖励配置数据
3. **事件监听优化**：避免不必要的事件监听器

### 渲染优化

1. **延迟加载**：奖励界面按需加载资源
2. **对象池**：复用奖励预览对象
3. **批量更新**：合并UI更新操作

### 算法优化

1. **权重计算缓存**：缓存复杂的权重计算结果
2. **随机数优化**：使用高效的随机数生成算法
3. **数据结构优化**：使用合适的数据结构提高查找效率

### 实体销毁优化

根据最近的代码提交，MissionComp中的实体销毁逻辑已优化：

```typescript
private cleanComponents() {
    // 优化销毁顺序：直接销毁实体，让ECS系统自动处理组件清理
    // 这样可以避免在组件reset方法中访问已经被销毁的实体引用
    ecs.query(ecs.allOf(HeroViewComp)).forEach(entity => {
        entity.destroy();
    });
    ecs.query(ecs.allOf(AtkConCom)).forEach(entity => {
        entity.destroy();
    });
    ecs.query(ecs.allOf(SkillViewCom)).forEach(entity => {
        entity.destroy();
    });
}
```

此更改修复了实体销毁时可能出现的空引用问题，确保在清理过程中不会访问已被销毁的实体。

**节来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L137-L149) - *最近提交中已更新*

## 故障排除指南

### 常见问题及解决方案

#### 奖励不显示问题

**症状**：战斗胜利后没有显示奖励选项

**原因分析**：
1. 奖励数据为空
2. UI界面未正确打开
3. 事件监听器未正确注册

**解决方案**：
```typescript
// 检查奖励数据
if (!this.rewards || this.rewards.length === 0) {
    console.error("奖励数据为空");
    // 重新生成奖励
    this.rewards = this.generateDefaultRewards();
}

// 确保UI正确打开
oops.gui.open(UIID.Victory, {
    victory: true,
    rewards: this.rewards,
    game_data: this.game_data
});
```

#### 奖励权重异常

**症状**：奖励权重分布不合理

**原因分析**：
1. 权重配置错误
2. 动态权重计算逻辑问题
3. 随机数种子问题

**解决方案**：
```typescript
// 验证权重配置
validateRewardWeights() {
    const weights = Object.values(FightSet).filter(v => typeof v === 'number');
    const sum = weights.reduce((a, b) => a + b, 0);
    
    if (sum === 0) {
        console.error("奖励权重总和为0");
        // 使用默认权重
        return this.getDefaultWeights();
    }
    
    return weights;
}
```

#### 实体销毁空引用问题

**症状**：在组件清理过程中出现空引用错误

**原因分析**：
1. 组件清理顺序不当
2. 在reset方法中访问已被销毁的实体

**解决方案**：
```typescript
// 优化后的实体销毁方法
private cleanComponents() {
    // 直接销毁实体，让ECS系统自动处理组件清理
    ecs.query(ecs.allOf(HeroViewComp)).forEach(entity => {
        entity.destroy();
    });
    ecs.query(ecs.allOf(AtkConCom)).forEach(entity => {
        entity.destroy();
    });
    ecs.query(ecs.allOf(SkillViewCom)).forEach(entity => {
        entity.destroy();
    });
}
```

此解决方案通过直接销毁实体而非逐个清理组件，避免了在组件reset方法中访问已被销毁实体的问题。

**节来源**
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L137-L149) - *最近提交中已更新*

## 总结

奖励系统是本游戏的核心机制，通过精心设计的三选一奖励选择模式，为玩家提供了丰富的策略选择空间。系统采用模块化架构，各组件职责明确，通过事件驱动的方式实现松耦合设计。

### 主要特性

1. **多样化奖励类型**：涵盖属性提升、技能升级、装备获取等多个方面
2. **策略性决策**：玩家需要根据当前阵容和游戏进度做出最优选择
3. **动态权重系统**：奖励权重根据游戏进度和玩家状态动态调整
4. **可视化反馈**：清晰的奖励预览和效果展示
5. **扩展性强**：易于添加新的奖励类型和调整奖励权重

### 设计优势

- **平衡性**：通过权重系统确保奖励的平衡性
- **可玩性**：多样的奖励选项提供重玩价值
- **可维护性**：模块化设计便于维护和扩展
- **性能优化**：采用多种优化策略确保流畅运行

### 未来发展方向

1. **智能推荐系统**：基于玩家行为的奖励推荐
2. **社交元素**：好友间的奖励分享和比较
3. **成就系统**：与奖励系统结合的成就解锁
4. **动态难度**：根据玩家表现调整奖励难度

奖励系统的设计体现了游戏设计理念的核心思想：通过简单的机制创造复杂的策略深度，为玩家提供持续的游戏动力和成就感。