pixelheros/.qoder/repowiki/zh/content/奖励系统/奖励配置/奖励提示类型定义.md

# 奖励提示类型定义

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

## 目录
1. [简介](#简介)
2. [TooltipTypes常量定义](#tooltiptypes常量定义)
3. [类型映射关系](#类型映射关系)
4. [UI奖励提示系统架构](#ui奖励提示系统架构)
5. [具体类型应用场景](#具体类型应用场景)
6. [代码实现分析](#代码实现分析)
7. [新增提示类型的配置步骤](#新增提示类型的配置步骤)
8. [常见集成问题及解决方案](#常见集成问题及解决方案)
9. [性能优化建议](#性能优化建议)
10. [总结](#总结)

## 简介

奖励提示系统是游戏中的重要视觉反馈机制，用于向玩家展示各种奖励效果和状态变化。本文档详细解析了Mission.ts中TooltipTypes常量的定义，说明了各种提示类型对应的数值标识及其在游戏中的实际应用场景，并解释了这些类型如何与UI奖励提示系统（如TooltipCom.ts）协同工作，实现不同奖励效果的视觉反馈。

## TooltipTypes常量定义

### 核心常量结构

TooltipTypes常量定义在Mission.ts文件中，采用简洁的对象字面量形式：

```typescript
export const TooltipTypes = {
    life:1,
    health:2,
    skill:3,
    crit:4,
    uskill:5,
    lvup:6,
    apup:7,
    hpup:8,
}
```

### 类型定义说明

| 类型名称 | 数值标识 | 描述 |
|---------|---------|------|
| life | 1 | 减少生命值提示 |
| health | 2 | 增加生命值提示 |
| skill | 3 | 技能激活提示 |
| crit | 4 | 暴击伤害提示 |
| uskill | 5 | 特殊技能效果提示 |
| lvup | 6 | 等级提升提示 |
| apup | 7 | 攻击力提升提示 |
| hpup | 8 | 生命值上限提升提示 |

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

## 类型映射关系

### 枚举与数值映射

```mermaid
graph TD
A[TooltipTypes常量] --> B[life: 1]
A --> C[health: 2]
A --> D[skill: 3]
A --> E[crit: 4]
A --> F[uskill: 5]
A --> G[lvup: 6]
A --> H[apup: 7]
A --> I[hpup: 8]
B --> J[减少生命值效果]
C --> K[增加生命值效果]
D --> L[技能激活效果]
E --> M[特殊技能效果]
F --> N[等级提升效果]
G --> O[攻击力提升效果]
H --> P[生命值上限提升效果]
```

**图表来源**
- [Mission.ts](file://assets/script/game/common/config/Mission.ts#L44-L52)

### 对应的UI元素结构

每种类型对应不同的UI子节点和显示内容：

```mermaid
flowchart TD
A[TooltipCom.start] --> B{stype判断}
B --> |1 - life| C[loss_life节点]
B --> |2 - health| D[add_life节点]
B --> |3 - skill| E[skill节点]
B --> |4 - crit| F[bloss节点]
B --> |5 - uskill| G[uskill节点]
B --> |6 - lvup| H[lvup节点]
B --> |7 - apup| I[apup节点]
B --> |8 - hpup| J[hpup节点]
C --> K[显示伤害数值]
D --> L[显示恢复数值]
E --> M[显示技能名称]
F --> N[显示暴击数值]
G --> O[显示特殊效果]
H --> P[显示升级效果]
I --> Q[显示攻击力提升]
J --> R[显示生命值提升]
```

**图表来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L26-L101)

## UI奖励提示系统架构

### 系统组件关系

```mermaid
classDiagram
class Tooltip {
+TooltipView : TooltipCom
+load(pos, type, value, s_uuid, parent, cd)
+destroy()
}
class TooltipCom {
+stype : number
+value : string
+s_uuid : number
+alive_time : number
+start()
+do_up()
+to_destroy()
+reset()
}
class BuffComp {
+tooltip(type, value, s_uuid, y)
+hp_tip(type, value, s_uuid, y)
+show_shield(shield, shield_max)
+hp_show(hp, hp_max)
+ap_up()
+lv_up()
}
class HeroViewComp {
+do_atked(remainingDamage, CAttrs, s_uuid)
+check_dodge()
+check_crit(crit)
+playSkillEffect(skill_id)
+showDamage(damage, isCrit, anm)
}
Tooltip --> TooltipCom : "管理"
BuffComp --> Tooltip : "使用"
HeroViewComp --> BuffComp : "调用"
HeroViewComp --> Tooltip : "直接调用"
```

**图表来源**
- [Tooltip.ts](file://assets/script/game/skill/Tooltip.ts#L10-L30)
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L12-L25)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L10-L30)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L540-L580)

### 数据流向

```mermaid
sequenceDiagram
participant Player as 玩家操作
participant Hero as HeroViewComp
participant Buff as BuffComp
participant Tooltip as Tooltip
participant Com as TooltipCom
Player->>Hero : 触发事件(攻击/技能/死亡等)
Hero->>Hero : 计算结果
Hero->>Buff : 调用tooltip()方法
Buff->>Tooltip : 获取Tooltip实体
Tooltip->>Tooltip : 加载预制件
Tooltip->>Com : 创建TooltipCom实例
Com->>Com : 根据stype设置UI
Com->>Com : 启动动画和定时器
Com->>Com : 自动销毁
```

**图表来源**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L540-L580)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L185-L210)
- [Tooltip.ts](file://assets/script/game/skill/Tooltip.ts#L35-L49)

**节来源**
- [Tooltip.ts](file://assets/script/game/skill/Tooltip.ts#L10-L49)
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L12-L101)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L10-L210)

## 具体类型应用场景

### life类型 - 减少生命值提示

**应用场景：**
- 英雄受到伤害时显示
- 怪物攻击玩家时显示
- 各种负面效果造成的伤害

**实现特点：**
- 使用`loss_life`节点显示
- 数值显示在`hp`标签中
- 动画效果：从当前位置向上移动
- 持续时间：0.5秒后自动销毁

**节来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L26-L33)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L774)

### health类型 - 增加生命值提示

**应用场景：**
- 回复技能效果
- 治疗道具使用
- 生命值恢复效果

**实现特点：**
- 使用`add_life`节点显示
- 数值显示在`hp`标签中
- 层级索引：110（高于其他提示）
- 动画效果：从当前位置向上移动

**节来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L35-L42)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L540-L550)

### skill类型 - 技能激活提示

**应用场景：**
- 主要技能激活
- 技能冷却完成
- 特殊技能触发

**实现特点：**
- 使用`skill`节点显示
- 显示技能名称（从SkillSet获取）
- 位置偏移：y坐标+30
- 持续时间：0.5秒

**节来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L52-L60)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L730)

### crit类型 - 暴击伤害提示

**应用场景：**
- 暴击攻击造成伤害
- 暴击回复效果
- 暴击触发的特殊效果

**实现特点：**
- 使用`bloss`节点显示
- 数值显示在`hp`标签中
- 层级索引：200（最高层级）
- 动画效果：从当前位置向上移动

**节来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L43-L50)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L771)

### uskill类型 - 特殊技能效果提示

**应用场景：**
- 闪避成功
- 护盾吸收伤害
- 其他特殊技能效果

**实现特点：**
- 使用`uskill`节点显示
- 直接显示预设文本（如"*吸收*"、"*闪避*"）
- 位置偏移：y坐标+30
- 持续时间：0.5秒

**节来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L60-L68)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L667)

### lvup类型 - 等级提升提示

**应用场景：**
- 英雄等级提升
- 经验值达到新等级
- 系统通知等级变化

**实现特点：**
- 使用`lvup`节点显示
- 位置偏移：y坐标-30
- 持续时间：0.5秒
- （注：当前实现中未显示具体数值）

**节来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L68-L76)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L110-L115)

### apup类型 - 攻击力提升提示

**应用场景：**
- 攻击力属性提升
- 攻击力增益效果
- 装备强化效果

**实现特点：**
- 使用`apup`节点显示
- 数值显示在`num`标签中，带"+"前缀
- 位置偏移：y坐标-60
- 持续时间：0.5秒

**节来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L76-L84)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L115-L120)

### hpup类型 - 生命值上限提升提示

**应用场景：**
- 生命值上限增加
- 生命值成长效果
- 生命值相关增益

**实现特点：**
- 使用`hpup`节点显示
- 数值显示在`num`标签中，带"+"前缀
- 位置偏移：y坐标-60
- 持续时间：0.5秒

**节来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L84-L92)
- [BuffComp.ts](file://assets/script/game/hero/BuffComp.ts#L120-L125)

## 代码实现分析

### TooltipCom核心逻辑

TooltipCom组件负责具体的UI显示逻辑，其核心switch语句处理不同类型：

```mermaid
flowchart TD
A[TooltipCom.start] --> B[接收stype参数]
B --> C{switch(stype)}
C --> |1| D[life类型处理]
C --> |2| E[health类型处理]
C --> |3| F[skill类型处理]
C --> |4| G[crit类型处理]
C --> |5| H[uskill类型处理]
C --> |6| I[lvup类型处理]
C --> |7| J[apup类型处理]
C --> |8| K[hpup类型处理]
D --> L[设置位置和层级]
D --> M[显示loss_life节点]
D --> N[设置数值文本]
D --> O[启动定时器销毁]
E --> P[设置层级110]
E --> Q[显示add_life节点]
E --> R[设置数值文本]
E --> S[启动定时器销毁]
F --> T[显示skill节点]
F --> U[设置技能名称]
F --> V[调整位置]
F --> W[启动定时器销毁]
G --> X[设置层级200]
G --> Y[显示bloss节点]
G --> Z[设置数值文本]
G --> AA[启动定时器销毁]
H --> BB[显示uskill节点]
H --> CC[设置预设文本]
H --> DD[调整位置]
H --> EE[启动定时器销毁]
I --> FF[显示lvup节点]
I --> GG[调整位置]
I --> HH[启动定时器销毁]
J --> II[显示apup节点]
J --> JJ[设置带+的数值]
J --> KK[调整位置]
J --> LL[启动定时器销毁]
K --> MM[显示hpup节点]
K --> NN[设置带+的数值]
K --> OO[调整位置]
K --> PP[启动定时器销毁]
```

**图表来源**
- [TooltipCom.ts](file://assets/script/game/skill/TooltipCom.ts#L26-L101)

### Tooltip加载流程

```mermaid
sequenceDiagram
participant Client as 调用方
participant Tooltip as Tooltip实体
participant ResMgr as 资源管理器
participant Prefab as 提示预制件
participant Com as TooltipCom组件
Client->>Tooltip : load(pos, type, value, s_uuid, parent)
Tooltip->>ResMgr : 获取"game/skill/buff/tooltip"预制件
ResMgr-->>Tooltip : 返回Prefab实例
Tooltip->>Prefab : instantiate(prefab)
Prefab-->>Tooltip : 返回Node实例
Tooltip->>Tooltip : 设置父节点和位置
Tooltip->>Tooltip : 检查父节点缩放
Tooltip->>Com : 获取TooltipCom组件
Tooltip->>Com : 设置stype、value、s_uuid、alive_time
Tooltip->>Tooltip : 添加到实体
Tooltip-->>Client : 完成加载
```

**图表来源**
- [Tooltip.ts](file://assets/script/game/skill/Tooltip.ts#L35-L49)

### BuffComp工具方法

BuffComp提供了两个主要的工具方法来简化Tooltip的使用：

#### tooltip()方法
- 通用提示方法
- 参数：type（类型）、value（数值）、s_uuid（技能UUID）、y（垂直偏移）
- 位置计算：基于节点的相对位置

#### hp_tip()方法  
- 生命值相关提示专用方法
- 参数：type（类型）、value（数值）、s_uuid（技能UUID）、y（垂直偏移）
- 位置计算：基于节点高度的绝对位置

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

## 新增提示类型的配置步骤

### 步骤1：修改TooltipTypes常量

在Mission.ts中添加新的类型定义：

```typescript
export const TooltipTypes = {
    // ... 现有类型
    newType: 9,  // 新增类型，使用下一个可用数值
}
```

### 步骤2：更新TooltipCom处理逻辑

在TooltipCom.ts的switch语句中添加新的case分支：

```typescript
case TooltipTypes.newType:
    this.node.getChildByName("newType").getChildByName("value").getComponent(Label).string = this.value;
    this.node.getChildByName("newType").active = true;
    this.node.setPosition(v3(this.node.position.x, this.node.position.y + offset));
    this.scheduleOnce(() => {
        this.ent.destroy()
    }, this.alive_time);
    break
```

### 步骤3：创建对应的UI节点

在提示预制件中添加新的UI节点：
- 在Canvas下创建名为`newType`的子节点
- 添加必要的子节点（如数值显示标签）
- 设置适当的层级和初始状态

### 步骤4：测试和验证

1. **功能测试**：确保新类型能够正确显示
2. **层级测试**：验证显示层级是否符合预期
3. **动画测试**：确认动画效果正常
4. **性能测试**：检查是否存在性能问题

### 注意事项

1. **数值唯一性**：确保每个类型的数值都是唯一的
2. **层级管理**：合理设置显示层级，避免遮挡
3. **资源管理**：及时销毁不需要的提示对象
4. **兼容性**：确保新类型与现有系统兼容
5. **国际化**：如果支持多语言，考虑文本本地化

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

### 问题1：提示显示位置不正确

**症状**：提示出现在错误的位置

**原因**：
- 父节点变换影响
- 缩放比例问题
- 坐标系转换错误

**解决方案**：
```typescript
// 在Tooltip.ts中已处理
if(parent.scale.x < 0){
    node.setScale(-node.scale.x, node.scale.y, 0);
}
```

### 问题2：提示层级混乱

**症状**：某些提示被其他UI元素遮挡

**原因**：
- 层级索引设置不当
- 动态层级管理缺失

**解决方案**：
```typescript
// 在TooltipCom.ts中已处理
case TooltipTypes.health:
    this.node.setSiblingIndex(110);  // 明确设置层级
    break
```

### 问题3：提示消失过快或过慢

**症状**：提示持续时间不符合预期

**原因**：
- alive_time设置不当
- 销毁时机错误

**解决方案**：
```typescript
// 在Tooltip.ts中统一设置
sv.alive_time = 0.5;  // 统一的持续时间
```

### 问题4：内存泄漏

**症状**：长时间运行后出现内存占用过高

**原因**：
- 提示对象未正确销毁
- 事件监听器未清理

**解决方案**：
```typescript
// 在TooltipCom.ts中确保正确销毁
scheduleOnce(() => {
    this.ent.destroy()
}, this.alive_time);
```

### 问题5：动画效果异常

**症状**：提示动画不流畅或不正确

**原因**：
- Tween动画配置错误
- 更新频率不匹配

**解决方案**：
```typescript
// 在TooltipCom.ts中使用正确的动画配置
tween(this.node).to(
    this.alive_time,
    { position: v3(this.node.position.x, this.node.position.y + 60) },
    {
        onComplete: () => { this.ent.destroy() },
        easing: "linear"
    }
).start()
```

## 性能优化建议

### 1. 对象池化

对于频繁使用的提示类型，可以考虑使用对象池：

```typescript
class TooltipPool {
    private pool: TooltipCom[] = [];
    
    public acquire(): TooltipCom {
        if (this.pool.length > 0) {
            return this.pool.pop()!;
        }
        return new TooltipCom();
    }
    
    public release(tooltip: TooltipCom): void {
        // 重置状态
        tooltip.reset();
        this.pool.push(tooltip);
    }
}
```

### 2. 批量处理

对于连续的相同类型提示，可以考虑批量处理：

```typescript
private damageQueue: DamageInfo[] = [];

public showDamage(damage: number, isCrit: boolean, anm: string = "atked") {
    this.damageQueue.push({
        damage,
        isCrit,
        delay: this.damageInterval,
        anm
    });
}

private processDamageQueue() {
    if (this.isProcessingDamage || this.damageQueue.length === 0) return;
    
    this.isProcessingDamage = true;
    const damageInfo = this.damageQueue.shift()!;
    
    this.showDamageImmediate(damageInfo.damage, damageInfo.isCrit, damageInfo.anm);
    
    this.scheduleOnce(() => {
        this.isProcessingDamage = false;
    }, this.damageInterval);
}
```

### 3. 条件渲染

对于某些不常用的提示类型，可以考虑延迟加载：

```typescript
private cachedNodes: Map<number, Node> = new Map();

private getCachedNode(type: number): Node {
    if (!this.cachedNodes.has(type)) {
        // 延迟加载UI节点
        const node = this.createNodeForType(type);
        this.cachedNodes.set(type, node);
    }
    return this.cachedNodes.get(type)!;
}
```

### 4. 异步加载

对于大型UI资源，可以考虑异步加载：

```typescript
async loadTooltipAsync(type: number, pos: Vec3, value: string, s_uuid: number, parent: any) {
    // 异步加载UI资源
    const prefab = await oops.res.getAsync("game/skill/buff/tooltip", Prefab);
    // 继续后续逻辑...
}
```

## 总结

奖励提示系统是游戏体验的重要组成部分，通过TooltipTypes常量定义的八种提示类型，系统能够有效地向玩家传达各种游戏状态和奖励信息。

### 关键特性

1. **类型化设计**：通过数值化的类型系统，实现了清晰的功能分类
2. **灵活的UI适配**：每种类型都有专门的UI节点和显示逻辑
3. **良好的扩展性**：新增类型只需遵循既定的配置步骤
4. **完善的生命周期管理**：自动化的创建和销毁机制
5. **丰富的应用场景**：覆盖了游戏中的各种奖励和状态变化

### 最佳实践

1. **合理使用类型**：根据具体场景选择合适的提示类型
2. **注意层级管理**：确保提示不会被其他UI元素遮挡
3. **控制显示时机**：避免过多的提示同时显示
4. **关注性能表现**：对于高频使用的提示类型进行优化
5. **保持一致性**：确保相似效果使用相同的提示类型

通过深入理解和正确使用这个奖励提示系统，开发者可以为玩家创造更加丰富和直观的游戏体验。