UnityAI/modules/frameworks/事件系统/使用指南.md

事件系统使用指南

一、事件系统概述

事件系统分为两类：

• STCEvent：Server To Client（服务器到客户端消息）
• CTCEvent：Client To Client（客户端内部消息）

---

二、定义事件

2.1 定义事件枚举和参数

// 事件 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

[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）

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（纯逻辑）

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年
适用范围: 使用 StrayFog 框架的项目开发人员

---

文档关联

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

文档	关联原因
事件系统入口	本文件是事件系统模块的子文档
网络系统	STC 事件来源与网络系统相关
UI 窗口系统	UI 窗口订阅和释放事件
实体系统	Manager 常与实体系统协作
modules/模块索引.md	模块索引是项目知识总入口
rules/10-架构说明.md	架构说明定义总体分层和依赖方向
rules/20-开发规则.md	事件订阅/释放与开发规则互相引用
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径