# 事件系统

<cite>
**本文档引用文件**  
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
- [event.md](file://doc/core/common/event.md)
- [MessageManager.ts](file://extensions/oops-plugin-framework/assets/core/common/event/MessageManager.ts)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
- [TopComp.ts](file://assets/script/game/map/TopComp.ts)
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts)
- [move.ts](file://assets/script/game/map/move.ts)
- [TalComp.ts](file://assets/script/game/hero/TalComp.ts)
</cite>

## 目录
1. [事件常量分类与业务含义](#事件常量分类与业务含义)
2. [事件监听机制与内存管理](#事件监听机制与内存管理)
3. [事件系统解耦设计与应用示例](#事件系统解耦设计与应用示例)
4. [事件命名规范与作用域管理](#事件命名规范与作用域管理)
5. [事件调试与常见问题解决方案](#事件调试与常见问题解决方案)

## 事件常量分类与业务含义

基于 `GameEvent.ts` 枚举文件，游戏全局事件按功能模块可分为以下几类：

### 战斗流程事件
- `MissionStart`：关卡开始时触发，初始化战斗环境
- `MissionWin`：玩家胜利时触发，进入结算流程
- `MissionLoss`：玩家失败时触发，显示失败界面
- `FightStart`：战斗正式开始，激活战斗逻辑
- `FightEnd`：战斗结束，无论胜负均触发
- `NewWave`：新一波敌人出现，用于刷新怪物生成

### 英雄相关事件
- `HeroLvUp`：英雄升级时触发，用于属性更新和UI反馈
- `HeroUnlock`：新英雄解锁时触发，通知UI展示获取动画
- `HeroDead`：英雄死亡时触发，处理死亡逻辑和成就判断
- `HeroSelect`：选择出战英雄时触发，更新队伍配置
- `HeroSkillSelect`：技能选择阶段触发，激活技能选择界面

### 资源更新事件
- `GOLD_UPDATE`：金币数量变化时触发，用于UI金币显示更新
- `DIAMOND_UPDATE`：钻石数量变化时触发
- `MEAT_UPDATE`：游戏内特定资源"肉"的数量更新
- `MISSION_UPDATE`：关卡进度更新，用于顶部UI显示当前关卡

### 界面与交互事件
- `ShopOpen`：商店界面打开时触发
- `HerosOpen`：英雄列表界面打开
- `RestOpen`：休息界面打开
- `HeroInfoOpen`：英雄详情界面打开
- `GuideStart`、`GuideEnd`：新手引导流程控制

### 地图移动事件
- `MAP_MOVE_END_LEFT`：地图向左移动到达边界
- `MAP_MOVE_END_RIGHT`：地图向右移动到达边界
- `CardsClose`：卡牌选择界面关闭

### 卡牌与技能事件
- `CardRefresh`：卡牌刷新时触发
- `UseHeroCard`：使用英雄卡牌
- `UseSkillCard`：使用技能卡牌
- `UseTalentCard`：使用天赋卡牌
- `CastSkill`：技能施放

**Section sources**
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)

## 事件监听机制与内存管理

### 持续监听与单次监听的差异

`oops.message.on()` 用于注册持续监听的事件，监听器会一直存在直到显式移除。适用于需要长期响应的事件，如资源更新、状态变化等。

```typescript
oops.message.on(GameEvent.GOLD_UPDATE, this.onGoldUpdate, this);
```

`oops.message.once()` 用于注册只触发一次的事件监听，事件响应后监听器自动移除。适用于一次性流程，如初始化完成、首次加载等场景。

```typescript
oops.message.once(GameEvent.GameServerConnected, this.onHandler, this);
```

从 `MessageManager.ts` 的实现可以看出，`once()` 方法通过创建一个包装函数 `_listener`，在事件触发后立即调用 `off()` 移除自身，确保只执行一次。

### 内存泄漏防范措施

为防止内存泄漏，必须在对象销毁时移除所有事件监听。通常在 `onDestroy()` 或 `reset()` 生命周期方法中执行：

```typescript
protected onDestroy() {
    oops.message.off(GameEvent.GOLD_UPDATE, this.onGoldUpdate, this);
}
```

`MessageManager` 在注册事件时会检查重复注册，并发出警告，避免同一对象对同一事件的重复监听。

**Section sources**
- [event.md](file://doc/core/common/event.md)
- [MessageManager.ts](file://extensions/oops-plugin-framework/assets/core/common/event/MessageManager.ts)

## 事件系统解耦设计与应用示例

### 解耦模块间通信

事件系统通过发布-订阅模式实现模块间的松耦合通信。发送方无需知道接收方的存在，接收方也无需主动轮询状态变化。

#### 英雄升级事件（HeroLvUp）的完整流程

1. **事件触发**：当英雄经验值满足升级条件时，触发 `HeroLvUp` 事件
2. **UI更新**：UI组件监听 `HeroLvUp` 事件，更新英雄等级显示和属性面板
3. **成就判断**：成就系统监听该事件，判断是否达成"快速升级"等成就条件
4. **天赋系统响应**：某些天赋（如"每升5级攻击力+10%"）在等级变化时触发效果

#### 金币更新事件的实际应用

在 `SingletonModuleComp.ts` 中，当金币数量变化时触发 `GOLD_UPDATE` 事件：

```typescript
updateGold(gold: number) {
    this.vmdata.gold += gold;
    // ... 更新云端数据
    oops.message.dispatchEvent(GameEvent.GOLD_UPDATE);
}
```

在 `TopComp.ts` 中，顶部UI组件监听该事件并执行视觉反馈：

```typescript
onGoldUpdate(event: string, data: any) {
    tween(this.node.getChildByName("bar").getChildByName("gold").getChildByName("num").getComponent(Label).node)
        .to(0.1, { scale: v3(1.2, 1.2, 1) })
        .to(0.1, { scale: v3(1, 1, 1) })
        .start();
}
```

这种设计使得金币逻辑与UI展示完全分离，任何模块都可以独立修改而不影响其他部分。

### 地图移动事件的循环机制

`move.ts` 文件展示了 `MAP_MOVE_END_LEFT` 和 `MAP_MOVE_END_RIGHT` 事件的闭环设计：

1. 地图移动组件监听边界到达事件
2. 当到达边界时，重置位置并派发对应的边界事件
3. 其他组件可以监听这些事件执行相应逻辑

```mermaid
flowchart TD
A[地图移动] --> B{到达右边界?}
B --> |是| C[重置到左边界]
C --> D[派发MAP_MOVE_END_LEFT]
D --> E[其他组件响应]
B --> |否| F{到达左边界?}
F --> |是| G[重置到右边界]
G --> H[派发MAP_MOVE_END_RIGHT]
H --> I[其他组件响应]
```

**Diagram sources**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
- [TopComp.ts](file://assets/script/game/map/TopComp.ts)
- [move.ts](file://assets/script/game/map/move.ts)

**Section sources**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
- [TopComp.ts](file://assets/script/game/map/TopComp.ts)
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts)
- [move.ts](file://assets/script/game/map/move.ts)

## 事件命名规范与作用域管理

### 命名规范

事件名称采用大写常量格式，使用有意义的描述性名称。遵循以下原则：

- 使用名词或名词短语，如 `GOLD_UPDATE`、`HeroLvUp`
- 模块相关事件添加前缀，如 `MAP_MOVE_END_LEFT`
- 业务流程事件使用动词，如 `MissionWin`、`FightStart`
- 避免缩写，确保名称清晰可读

### 作用域管理

事件系统通过第三个参数 `this` 管理作用域，确保回调函数在正确的上下文中执行。这解决了 JavaScript/TypeScript 中常见的 `this` 上下文丢失问题。

在注册事件时，必须传入正确的对象引用，以便在移除监听时能够精确匹配。

```typescript
oops.message.on(GameEvent.GOLD_UPDATE, this.onGoldUpdate, this);
```

这里的 `this` 确保了：
1. 回调函数在正确的对象实例上下文中执行
2. 移除监听时能够准确找到对应的监听器
3. 避免不同实例间的监听器混淆

**Section sources**
- [MessageManager.ts](file://extensions/oops-plugin-framework/assets/core/common/event/MessageManager.ts)

## 事件调试与常见问题解决方案

### 调试技巧

#### 事件监听器dump

可以通过访问 `MessageManager` 的内部 `events` 对象来查看当前所有注册的事件监听器，便于调试和性能分析。

#### 事件触发跟踪

在开发环境中，可以临时修改 `dispatchEvent` 方法，添加日志输出，跟踪所有事件的触发情况。

```mermaid
flowchart LR
A[事件注册] --> B[事件派发]
B --> C{是否有监听器?}
C --> |是| D[执行所有监听器]
D --> E[回调函数执行]
C --> |否| F[无操作]
```

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

#### 事件重复注册

**问题**：同一对象对同一事件多次注册，导致回调执行多次。

**解决方案**：
1. 在 `onLoad()` 中注册事件，在 `onDestroy()` 中移除
2. 使用 `MessageManager` 的重复注册警告功能及时发现
3. 在复杂场景下，使用标志位确保只注册一次

#### this上下文丢失

**问题**：回调函数中的 `this` 指向错误的对象。

**解决方案**：
1. 严格按照 `oops.message.on(event, handler, this)` 格式注册
2. 避免使用箭头函数作为回调，除非明确不需要绑定作用域
3. 在 TypeScript 中利用类型检查确保第三个参数正确

#### 内存泄漏

**问题**：对象销毁后事件监听器未移除，导致对象无法被垃圾回收。

**解决方案**：
1. 严格遵守生命周期，在 `onDestroy()` 中调用 `off()`
2. 对于临时组件，使用 `once()` 替代 `on()`
3. 使用事件管理器批量管理事件的注册和移除

#### 事件命名冲突

**问题**：不同模块使用相同名称的事件导致意外行为。

**解决方案**：
1. 使用模块前缀，如 `MAP_`、`HERO_`
2. 在 `GameEvent` 枚举中统一管理所有事件名称
3. 避免使用过于通用的名称

**Section sources**
- [MessageManager.ts](file://extensions/oops-plugin-framework/assets/core/common/event/MessageManager.ts)
- [TalComp.ts](file://assets/script/game/hero/TalComp.ts)