跳到主要内容

API参考

GameEvent系统的完整API参考文档。所有事件类型都实现了严格的类型安全接口，具有用于事件驱动架构的全面功能。

命名空间

所有类和接口都位于TinyGiants.GameEventSystem.Runtime命名空间中。

using TinyGiants.GameEventSystem.Runtime;

事件类型概述​

GameEvent系统提供三种事件类型变体

类型描述
GameEvent用于简单通知的无参数事件
GameEvent<T>用于传递类型化数据的单参数事件
GameEvent<TSender, TArgs>用于发送者感知通信的双参数事件

下面的所有方法都适用于这些类型，具有适当的参数变化。

🚀 事件触发与取消​

Raise()

立即触发事件，按执行顺序调用所有注册的监听器。

执行顺序：基础 → 优先级 → 条件 → 持久化 → 触发器 → 链

void Raise();

示例：

myEvent.Raise();
Cancel()

停止此事件资产的任何活动的Inspector配置的调度执行（延迟或重复）。

void Cancel();

示例：

// 停止在Inspector中配置的自动重复
myEvent.Cancel();
范围限制

这仅取消由Inspector的"调度配置"启动的调度。它不会取消通过RaiseDelayed()或RaiseRepeating()创建的手动调度。对于这些，使用CancelDelayed(handle)或CancelRepeating(handle)。

⏱️ 基于时间的调度​

RaiseDelayed()

调度事件在指定延迟后触发一次。

ScheduleHandle RaiseDelayed(float delay);

参数：

名称类型描述
delayfloat触发事件前等待的时间（秒）

返回值： ScheduleHandle - 用于取消的句柄

示例：

// 5秒后触发
ScheduleHandle handle = myEvent.RaiseDelayed(5f);

// 如果需要，取消
myEvent.CancelDelayed(handle);
RaiseRepeating()

调度事件以固定间隔重复触发。

ScheduleHandle RaiseRepeating(float interval, int repeatCount = -1);

参数：

名称类型描述
intervalfloat每次执行之间的秒数
repeatCountint重复次数。使用-1表示无限（默认：-1）

返回值： ScheduleHandle - 用于取消的句柄

示例：

// 重复10次
ScheduleHandle handle = tickEvent.RaiseRepeating(1f, repeatCount: 10);

// 永远重复（无限循环）
ScheduleHandle infinite = pulseEvent.RaiseRepeating(0.5f);

// 停止无限循环
pulseEvent.CancelRepeating(infinite);
CancelDelayed()

取消用RaiseDelayed()创建的特定延迟事件。

bool CancelDelayed(ScheduleHandle handle);

参数：

名称类型描述
handleScheduleHandleRaiseDelayed()返回的句柄

返回值： bool - 如果成功取消则为true，如果已执行或无效则为false

示例：

ScheduleHandle handle = explosionEvent.RaiseDelayed(5f);

// 在爆炸发生前取消
if (explosionEvent.CancelDelayed(handle))
{
    Debug.Log("爆炸已拆除！");
}
CancelRepeating()

取消用RaiseRepeating()创建的特定重复事件。

bool CancelRepeating(ScheduleHandle handle);

参数：

名称类型描述
handleScheduleHandleRaiseRepeating()返回的句柄

返回值： bool - 如果成功取消则为true，如果已完成或无效则为false

示例：

ScheduleHandle handle = tickEvent.RaiseRepeating(1f);

// 停止重复
if (tickEvent.CancelRepeating(handle))
{
    Debug.Log("计时器已停止！");
}

🎧 监听器管理​

AddListener()

注册具有标准执行优先级的基础监听器。

void AddListener(UnityAction call);

参数：

名称类型描述
callUnityAction无参数的回调方法

示例：

myEvent.AddListener(OnEventTriggered);

void OnEventTriggered()
{
    Debug.Log("事件已触发！");
}
防止重复

如果监听器已存在，它将被删除并重新添加以防止重复。

RemoveListener()

从事件中注销基础监听器。

void RemoveListener(UnityAction call);

参数：

名称类型描述
callUnityAction无参数的回调方法

示例：

myEvent.RemoveListener(OnEventTriggered);
RemoveAllListeners()

从事件中清除所有基础、优先级和条件监听器。

void RemoveAllListeners();

示例：

// 清理所有监听器
myEvent.RemoveAllListeners();
范围

出于安全原因，不会删除持久化监听器或触发器/链事件。

AddPriorityListener()

注册具有显式执行优先级的监听器。更高的优先级值先执行。

void AddPriorityListener(UnityAction call, int priority);

参数：

名称类型描述
callUnityAction回调方法
priorityint执行优先级（越高 = 越早，默认：0）

示例：

myEvent.AddPriorityListener(CriticalHandler, 100);
myEvent.AddPriorityListener(NormalHandler, 50);
myEvent.AddPriorityListener(LowPriorityHandler, 10);
// 执行顺序：CriticalHandler → NormalHandler → LowPriorityHandler
RemovePriorityListener()

注销优先级监听器。

void RemovePriorityListener(UnityAction call);

参数：

名称类型描述
callUnityAction无参数的回调方法

示例：

myEvent.RemovePriorityListener(OnEventTriggered);
AddConditionalListener()

注册仅在条件评估为true时执行的监听器。

void AddConditionalListener(UnityAction call, Func<bool> condition, int priority = 0);

参数：

名称类型描述
callUnityAction回调方法
conditionFunc<bool>谓词函数（null = 始终执行）
priorityint执行优先级（默认：0）

示例：

myEvent.AddConditionalListener(
    OnHealthLow,
    () => playerHealth < 20,
    priority: 10
);
RemoveConditionalListener()

注销条件监听器。

void RemoveConditionalListener(UnityAction call);

参数：

名称类型描述
callUnityAction无参数的回调方法

示例：

myEvent.RemoveConditionalListener(OnEventTriggered);
AddPersistentListener()

注册在场景更改后存活的全局监听器（DontDestroyOnLoad）。

void AddPersistentListener(UnityAction call, int priority = 0);

参数：

名称类型描述
callUnityAction回调方法
priorityint执行优先级（默认：0）

示例：

globalEvent.AddPersistentListener(OnGlobalAction, priority: 100);
持久性

持久化监听器在场景加载间保持活动。用于全局系统，如保存管理或分析。

RemovePersistentListener()

注销持久化监听器。

void RemovePersistentListener(UnityAction call);

参数：

名称类型描述
callUnityAction无参数的回调方法

示例：

myEvent.RemovePersistentListener(OnEventTriggered);

⚡ 触发器事件（扇出模式）​

AddTriggerEvent()

注册在触发此事件时自动触发的目标事件。

TriggerHandle AddTriggerEvent(
    GameEventBase targetEvent,
    float delay = 0f,
    Func<bool> condition = null,
    int priority = 0
);

参数：

名称类型描述
targetEventGameEventBase要触发的事件
delayfloat可选延迟（秒）（默认：0）
conditionFunc<bool>可选谓词来控制执行
priorityint相对于其他触发器的执行顺序（默认：0）

返回值： TriggerHandle - 用于安全移除的唯一标识符

示例：

// 简单触发器：门打开 → 灯打开
doorOpenEvent.AddTriggerEvent(lightOnEvent);

// 延迟触发器：2秒后爆炸
fuseEvent.AddTriggerEvent(explosionEvent, delay: 2f);

// 条件触发器
doorOpenEvent.AddTriggerEvent(
    alarmEvent,
    condition: () => isNightTime
);

// 优先级排序的触发器
bossDefeatedEvent.AddTriggerEvent(stopMusicEvent, priority: 100);
bossDefeatedEvent.AddTriggerEvent(victoryMusicEvent, priority: 90);
bossDefeatedEvent.AddTriggerEvent(showRewardsEvent, priority: 50);
扇出模式

触发器并行执行 - 每个触发器都是独立的。如果一个触发器的条件失败或抛出异常，其他触发器仍然执行。

RemoveTriggerEvent()（按句柄）

使用其唯一句柄安全地移除特定触发器。

void RemoveTriggerEvent(TriggerHandle handle);

参数：

名称类型描述
handleTriggerHandleAddTriggerEvent()返回的句柄

示例：

TriggerHandle handle = doorEvent.AddTriggerEvent(lightEvent);

// 移除特定触发器
doorEvent.RemoveTriggerEvent(handle);
推荐

这是最安全的移除方法，因为它只移除您的特定触发器实例。

RemoveTriggerEvent()（按目标）

移除指向特定目标事件的所有触发器。

void RemoveTriggerEvent(GameEventBase targetEvent);

参数：

名称类型描述
targetEventGameEventBase要断开连接的目标事件

示例：

doorEvent.RemoveTriggerEvent(lightEvent);
广泛影响

这会移除指向此事件的所有触发器，包括其他系统注册的触发器。使用RemoveTriggerEvent(handle)以获得精确性。

RemoveAllTriggerEvents()

从此事件中移除所有触发器事件。

void RemoveAllTriggerEvents();

示例：

myEvent.RemoveAllTriggerEvents();

🔗 链事件（顺序模式）​

AddChainEvent()

注册在链中顺序执行的目标事件。

ChainHandle AddChainEvent(
    GameEventBase targetEvent,
    float delay = 0f,
    float duration = 0f,
    Func<bool> condition = null,
    bool waitForCompletion = false
);

参数：

名称类型描述
targetEventGameEventBase要在链中执行的事件
delayfloat执行此节点前的延迟（默认：0）
durationfloat执行此节点后的延迟（默认：0）
conditionFunc<bool>可选谓词 - 如果为false则链中断
waitForCompletionbool执行后等待一帧（默认：false）

返回值： ChainHandle - 用于安全移除的唯一标识符

示例：

// 简单序列：A → B → C
eventA.AddChainEvent(eventB);
eventB.AddChainEvent(eventC);

// 带延迟的过场动画
fadeOutEvent.AddChainEvent(loadSceneEvent, delay: 1f);
loadSceneEvent.AddChainEvent(fadeInEvent, delay: 0.5f);

// 条件链：仅在满足条件时继续
combatEndEvent.AddChainEvent(
    victoryEvent,
    condition: () => playerHealth > 0
);

// 带异步操作帧等待的链
showDialogEvent.AddChainEvent(
    typeTextEvent,
    waitForCompletion: true
);
顺序执行

链是顺序的（A → B → C）。如果任何节点的条件返回false或抛出异常，整个链在该点停止。

触发器 vs 链
  • 触发器 = 并行（A → [B, C, D]）- 所有独立执行
  • 链 = 顺序（A → B → C）- 严格顺序，失败时停止
RemoveChainEvent()（按句柄）

使用其唯一句柄安全地移除特定链节点。

void RemoveChainEvent(ChainHandle handle);

参数：

名称类型描述
handleChainHandleAddChainEvent()返回的句柄

示例：

ChainHandle handle = eventA.AddChainEvent(eventB);

// 移除特定链节点
eventA.RemoveChainEvent(handle);
RemoveChainEvent()（按目标）

移除指向特定目标事件的所有链节点。

void RemoveChainEvent(GameEventBase targetEvent);

参数：

名称类型描述
targetEventGameEventBase要断开连接的目标事件

示例：

eventA.RemoveChainEvent(eventB);
广泛影响

这会移除指向此事件的所有链节点。使用RemoveChainEvent(handle)以获得精确性。

RemoveAllChainEvents()

从此事件中移除所有链事件。

void RemoveAllChainEvents();

示例：

myEvent.RemoveAllChainEvents();

🔧 配置与实用工具​

SetInspectorListenersActive()

控制触发事件时是否应执行Inspector配置的监听器。

void SetInspectorListenersActive(bool isActive);

参数：

名称类型描述
isActivebooltrue启用Inspector监听器，false静音它们

示例：

// 静音Inspector配置的UI/音频效果
damageEvent.SetInspectorListenersActive(false);

// 事件将仅触发代码注册的监听器
damageEvent.Raise(10);

// 重新启用Inspector监听器
damageEvent.SetInspectorListenersActive(true);

使用场景：

  • 在过场动画期间临时静音视觉/音频效果
  • 运行后端计算而不触发UI更新
  • 在加载屏幕期间禁用特定于场景的行为
  • 在测试/调试模式下模拟游戏逻辑
范围

此设置仅影响通过GameEventManager在Unity Inspector中配置的监听器。通过代码中的AddListener()注册的监听器不受影响，将始终执行。

🗄️ 数据库管理​

GameEventManager.Instance 上用于动态数据库生命周期管理的 API —— 在运行时加载/卸载 GameEventDatabase 资产，用于基于场景的内容、DLC 或 Addressables 集成。

RegisterDatabase()

运行时注册 GameEventDatabase，使其所有事件可用于绑定和调用。自动为尚未有绑定的事件创建 EventBinding 条目。重复注册的数据库会被安全忽略。

void RegisterDatabase(GameEventDatabase database);

参数：

名称类型说明
databaseGameEventDatabase要注册的数据库资产

示例：

var combatDB = Resources.Load<GameEventDatabase>("CombatEvents");
GameEventManager.Instance.RegisterDatabase(combatDB);
UnregisterDatabase()

运行时注销 GameEventDatabase，从活跃系统中移除其所有事件。清理关联的绑定和运行时回调。对 null 或未注册的数据库调用是安全的。

void UnregisterDatabase(GameEventDatabase database);

参数：

名称类型说明
databaseGameEventDatabase要移除的数据库资产

示例：

GameEventManager.Instance.UnregisterDatabase(combatDB);
SetDatabaseActive()

在不注销数据库的前提下切换其激活状态。未激活的数据库保留注册条目，但其事件不会接收调用。

void SetDatabaseActive(GameEventDatabase database, bool active);

参数：

名称类型说明
databaseGameEventDatabase目标数据库（必须已注册）
activebooltrue 激活，false 静音

示例：

// 过场动画期间暂停战斗事件
GameEventManager.Instance.SetDatabaseActive(combatDB, false);

// 过场动画结束后恢复
GameEventManager.Instance.SetDatabaseActive(combatDB, true);
Register 与 SetActive 的区别
  • RegisterDatabase / UnregisterDatabase 管理列表成员（添加 / 移除）。
  • SetDatabaseActive 只切换事件调用开关 —— 数据库保持注册状态。

🔍 运行时查询 API​

GameEventManager.Instance 上用于在运行时按 GUID、名称、分类 或 类型定位事件的 API —— 无需 [SerializeField] 引用。适用于非 MonoBehaviour 使用方、存档/读档系统、插件桥接以及动态加载的内容。

每个 Get* / Has* / TryGet* 方法都有三种泛型重载用于严格类型过滤：

  • 非泛型 → 返回 GameEventBase；匹配任意事件类型
  • <T> → 仅匹配 GameEvent<T>
  • <TSender, TArgs> → 仅匹配 GameEvent<TSender, TArgs>

类型过滤使用 is GameEvent<T> / is GameEvent<TSender, TArgs> 模式匹配。例如，即使 "OnJump" 存在为 void 事件，GetGameEvents<int>("OnJump") 也会返回 0 —— 杜绝跨类型误中。

所有查询范围限于活跃的已注册数据库。

HasGameEvent() / HasGameEvents()

存在性检查 —— 单数对应唯一 GUID，复数对应基于名称的查询（可能匹配多个事件）。

// 按 GUID（唯一）
bool HasGameEvent(string guid);

// 按名称（+ 可选分类过滤）
bool HasGameEvents(string name, string category = null);
bool HasGameEvents<T>(string name, string category = null);
bool HasGameEvents<TSender, TArgs>(string name, string category = null);

示例：

var mgr = GameEventManager.Instance;

if (mgr.HasGameEvent(savedGuid))
    Debug.Log("已保存的事件仍然存在");

if (mgr.HasGameEvents("OnDamage", "Combat"))
    Debug.Log("战斗伤害事件可用");

if (mgr.HasGameEvents<int>("OnScoreChanged"))
    Debug.Log("找到类型为 int 的分数事件");
GetGameEvent() / TryGetGameEvent()

基于 GUID 的获取。如果 GUID 未找到或类型不匹配，返回 null / false。

GameEventBase GetGameEvent(string guid);
bool TryGetGameEvent(string guid, out GameEventBase evt);

示例：

if (GameEventManager.Instance.TryGetGameEvent(savedGuid, out var evt))
    evt.Raise();
GetGameEvents()

获取所有名称匹配的事件（可选分类过滤）。无匹配时返回空 List —— 永不为 null。

List<GameEventBase> GetGameEvents(string name, string category = null);
List<GameEvent<T>> GetGameEvents<T>(string name, string category = null);
List<GameEvent<TSender, TArgs>> GetGameEvents<TSender, TArgs>(string name, string category = null);

参数：

名称类型说明
namestring精确匹配的事件名
categorystring可选分类过滤（null 表示不过滤）

示例：

// 批量触发所有名为 "OnJump" 的事件
foreach (var e in GameEventManager.Instance.GetGameEvents("OnJump"))
    e.Raise();

// 名称 + 分类过滤
var combatEvents = GameEventManager.Instance.GetGameEvents("OnDamage", "Combat");

// 类型过滤：仅匹配 GameEvent<int>
var scoreEvents = GameEventManager.Instance.GetGameEvents<int>("OnScoreChanged");
GetFirstGameEventByName() / TryGetFirstGameEventByName()

当按名称查找只需单个结果时的便捷方法。返回遍历时遇到的首个事件（若有重名则任选其一）。无匹配时返回 null / false。

// 非泛型
GameEventBase GetFirstGameEventByName(string name, string category = null);
bool TryGetFirstGameEventByName(string name, out GameEventBase evt, string category = null);

// GameEvent<T>
GameEvent<T> GetFirstGameEventByName<T>(string name, string category = null);
bool TryGetFirstGameEventByName<T>(string name, out GameEvent<T> evt, string category = null);

// GameEvent<TSender, TArgs>
GameEvent<TSender, TArgs> GetFirstGameEventByName<TSender, TArgs>(string name, string category = null);
bool TryGetFirstGameEventByName<TSender, TArgs>(string name, out GameEvent<TSender, TArgs> evt, string category = null);

示例：

var mgr = GameEventManager.Instance;

// 带分类过滤的 void 事件
mgr.GetFirstGameEventByName("OnJump", "Movement")?.Raise();

// 类型化的 int 查找
if (mgr.TryGetFirstGameEventByName<int>("OnScoreChanged", out var scoreEvt))
    scoreEvt.Raise(100);

// 带 Sender 的查找
if (mgr.TryGetFirstGameEventByName<GameObject, string>("OnEntityAction", out var evt))
    evt.Raise(gameObject, "performed action");
GUID 还是名称？
  • GUID 在项目内全局唯一 —— 适合存档/读档、网络同步、Mod 配置。
  • 名称 可能重复（跨分类或跨数据库）—— 批量操作用 GetGameEvents（复数），接受任意匹配时用 GetFirstGameEventByName。

📊 快速参考表​

方法类别​

类别方法目的
执行Raise(), Cancel()触发事件并停止调度执行
调度RaiseDelayed(), RaiseRepeating(), CancelDelayed(), CancelRepeating()基于时间的事件执行
基础监听器AddListener(), RemoveListener(), RemoveAllListeners()标准回调注册
优先级监听器AddPriorityListener(), RemovePriorityListener()有序回调执行
条件监听器AddConditionalListener(), RemoveConditionalListener()门控回调执行
持久化监听器AddPersistentListener(), RemovePersistentListener()场景独立回调
触发器事件AddTriggerEvent(), RemoveTriggerEvent(), RemoveAllTriggerEvents()并行事件链
链事件AddChainEvent(), RemoveChainEvent(), RemoveAllChainEvents()顺序事件链
配置SetInspectorListenersActive()运行时行为控制
数据库管理RegisterDatabase(), UnregisterDatabase(), SetDatabaseActive()运行时数据库生命周期
运行时查询HasGameEvent(), GetGameEvent(), TryGetGameEvent(), HasGameEvents(), GetGameEvents(), GetFirstGameEventByName(), TryGetFirstGameEventByName()按 GUID / 名称 / 分类 / 类型定位事件