Shiliang/UnityAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs][refactor]: 将旧 01~06 中文教程合并整理为 modules/frameworks 文件夹结构

Browse Source 
- 删除 01~05 旧中文教程目录
- 将 03 核心功能教程拆分为各 framework 模块的子文档
- 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/
- 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md
- 更新所有交叉链接与文档关联表

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
lms
2026-07-07 18:36:15 +08:00
parent 5e5b9f8c80
commit ee1ff7f444
77 changed files with 6263 additions and 1133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
modules/frameworks/事件系统/README.md Normal file
View File

@@ -0,0 +1,122 @@
# 事件系统
## 分类
- 核心框架
## 目的
提供客户端内部事件（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) | 模块登记规则定义分类和状态口径 |

168
modules/frameworks/事件系统/使用指南.md Normal file
View File

@@ -0,0 +1,168 @@
# 事件系统使用指南
## 一、事件系统概述
事件系统分为两类：
- **STCEvent**：Server To Client（服务器到客户端消息）
- **CTCEvent**：Client To Client（客户端内部消息）
---
## 二、定义事件
### 2.1 定义事件枚举和参数
```csharp
// 事件 ID 枚举
public enum GameEventId
{
PlayerLevelUp,
EnemyKilled,
GoldChanged
}
// 事件参数基类
public class GameEventArgs : IHFEventArg<GameEventId>, IHFRecycle
{
public GameEventId eventId { get; set; }
public void Recycle()
{
// 重置状态
eventId = default;
}
}
// 具体事件参数
public class PlayerLevelUpEventArgs : GameEventArgs
{
public int playerId;
public int oldLevel;
public int newLevel;
}
```
---
## 三、UI 窗口事件监听
### 3.1 在窗口中注册 CTCEvent
```csharp
[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/CardDeck/CardDeckWindow.prefab")]
[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Dynamic, isIgnoreCloseByESC = false)]
public class CardDeckWindow : AbsHFUIWindow
{
protected override void OnOpen(Action _onOpenComplete)
{
base.OnOpen(_onOpenComplete);
// 注册客户端内部消息监听（CTCEvent）
HFFunCatalogue.Event.CTCEvent.AddListener<HFEvent_CTC_CardUpdate>(enHFCTCEvent.CardUpdate, OnCardUpdate);
}
protected override void OnClose(Action _onCloseComplete)
{
base.OnClose(_onCloseComplete);
// 取消客户端内部消息监听
HFFunCatalogue.Event.CTCEvent.RemoveListener<HFEvent_CTC_CardUpdate>(enHFCTCEvent.CardUpdate, OnCardUpdate);
}
void OnCardUpdate(HFEventArgBase arg)
{
HFEvent_CTC_CardUpdate cardArg = arg as HFEvent_CTC_CardUpdate;
// 更新卡组 UI 显示
}
}
```
> **注意**：UI 窗口中**不监听服务器事件（STCEvent）**，服务器事件应在 Logic 层的 Manager 中监听。
---
## 四、Manager 事件监听
### 4.1 使用 AbsHFSingleMonoBehaviour（需要 Update）
```csharp
public class PlayerManager : AbsHFSingleMonoBehaviour<PlayerManager>
{
protected override int[] simulateBehaviourEvents => new int[]
{
enHFSimulateBehaviourEvent.Mono_Update,
enHFSimulateBehaviourEvent.Mono_FixedUpdate
};
protected override void OnAfterCreateInstance()
{
base.OnAfterCreateInstance();
RegisterServerEvents();
}
void RegisterServerEvents()
{
HFFunCatalogue.Event.STCEvent.AddListener<HFEvent_STC_PlayerInfo>(enHFSTCEvent.PlayerInfo, OnPlayerInfo);
}
void OnPlayerInfo(HFEventArgBase arg)
{
HFEvent_STC_PlayerInfo info = arg as HFEvent_STC_PlayerInfo;
// 处理服务器返回的玩家信息
// 触发客户端事件通知 UI 更新
HFEvent_CTC_PlayerLevelUp evt = HFFunCatalogue.New<HFEvent_CTC_PlayerLevelUp>();
evt.playerId = info.playerId;
evt.newLevel = info.level;
HFFunCatalogue.Event.CTCEvent.Dispatch(evt);
}
}
```
### 4.2 使用 AbsHFSingleRunTime（纯逻辑）
```csharp
public class ConfigManager : AbsHFSingleRunTime<ConfigManager>
{
protected override void OnAfterCreateInstance()
{
base.OnAfterCreateInstance();
// 加载配置表
LoadConfigTables();
}
void LoadConfigTables()
{
// 加载配置数据
}
}
```
---
## 五、Manager 类型对比
| 类型 | 说明 | 适用场景 |
|-----|------|---------|
| `AbsHFSingleMonoBehaviour` | 生成 GameObject，可注册 MonoBehaviour 事件 | 需要 Update/FixedUpdate 等生命周期 |
| `AbsHFSingleRunTime` | 纯内存单例，无 GameObject | 不需要生命周期事件 |
---
**版本**: v1.0
**生效日期**: 2026年
**适用范围**: GiftGameX 项目业务开发人员
---
## 文档关联
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
| 文档 | 关联原因 |
|---|---|
| [事件系统入口](README.md) | 本文件是事件系统模块的子文档 |
| [网络系统](../网络系统.md) | STC 事件来源与网络系统相关 |
| [UI 窗口系统](../UI窗口系统/README.md) | UI 窗口订阅和释放事件 |
| [实体系统](../实体系统/README.md) | Manager 常与实体系统协作 |
| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 事件订阅/释放与开发规则互相引用 |
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |