# 事件系统

## 分类

- 核心框架

## 目的

提供客户端内部事件（CTC）和服务器消息事件（STC）的统一派发、监听和释放机制。

---

## 核心路径

- 框架层：`Assets/Game/GameHFScripte/CopyToHF/Event/`
- 功能层：`Assets/Game/GameHFScripte/GameFunction/Event/`
- STC 事件参数：`Assets/Game/GameHFScripte/GameFunction/Event/STCEventArg/`

---

## 核心类

| 类 | 职责 |
|---|---|
| `HFEventManager` | 事件管理器单例，继承 `AbsHFSingleRunTime<HFEventManager>` |
| `TCEvent` | CTC 事件句柄 |
| `STCEvent` | STC 事件句柄 |
| `CTCHandle` | CTC 事件处理器定义位置 |
| `AbsHFEventArg<K,T>` | 事件参数基类 |

---

## 事件派发链路

### CTC 事件

```text
AbsHFEventArg<enHFCTCEvent>.Dispatch()
  -> HFEventManager.Instance.TCEvent.Dispatch(arg)
```

CTC 事件来源：

- 功能代码手动创建事件参数对象。
- 设置字段后调用 `.Dispatch()`。
- 示例：业务管理器派发初始化事件、背包更新事件。

### STC 事件

```text
AbsHFEventArg<enHFSTCEvent>.Dispatch()
  -> HFEventManager.Instance.STCEvent.Dispatch(arg)
```

STC 事件来源：

```text
WSSession 收到 protobuf S2C
  -> 反射创建 HFEvent_STC_{MessageTypeName}
  -> 写入 Request / ErrorCode
  -> Dispatch 到 STCEvent
```

---

## 监听与派发机制

```text
AddListener<TEventArg>(eventId, callback)
  -> 按 eventId 分组
  -> 按事件参数类型 hash 分组

Dispatch(arg)
  -> 根据 arg.eventId 找事件组
  -> 根据 arg.GetType() 找具体类型监听
  -> Invoke callbacks
  -> arg.Recycle()
```

---

## 使用规则

- UI 窗口在 `OnOpen` 中注册的事件，必须在 `OnClose` 中移除。
- 管理器监听 STC 事件通常在初始化时添加，在 `Recycle` 或销毁时移除。
- 不要直接监听与当前模块无关的事件。
- 事件参数对象由框架自动回收，业务代码不要重复释放。

---

## 错误响应

当服务器返回错误响应时：

```text
messagePage.IsError = true
  -> 解析 ErrorResponse
  -> 派发 HFEvent_ErrorCode
  -> 同时仍创建对应 HFEvent_STC_* 并写入 ErrorCode
```

---

## 相关模块

- [网络系统](../网络系统.md)
- [UI 窗口系统](../UI窗口系统/README.md)
- [实体系统](../实体系统/README.md)

---

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
| [modules/frameworks/网络系统.md](../网络系统.md) | S2C 消息是 STC 事件来源 |
| [modules/frameworks/UI窗口系统/README.md](../UI窗口系统/README.md) | UI 窗口订阅和释放事件 |
| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |