Skip to main content

API Reference

Complete API reference documentation for the GameEvent system. All event types implement strict type-safe interfaces with comprehensive functionality for event-driven architecture.

Namespace

All classes and interfaces are located in the TinyGiants.GameEventSystem.Runtime namespace.

using TinyGiants.GameEventSystem.Runtime;

Event Types Overview​

The GameEvent system provides three event type variants

TypeDescription
GameEventParameterless events for simple notifications
GameEvent<T>Single-argument events for passing typed data
GameEvent<TSender, TArgs>Dual-argument events for sender-aware communication

All methods below are available across these types with appropriate parameter variations.

🚀 Event Raising & Cancellation​

Raise()

Triggers the event immediately, invoking all registered listeners in execution order.

Execution Order: Basic → Priority → Conditional → Persistent → Triggers → Chains

void Raise();

Example:

myEvent.Raise();
Cancel()

Stops any active Inspector-configured scheduled execution (delay or repeating) for this event asset.

void Cancel();

Example:

// Stop automatic repeating configured in Inspector
myEvent.Cancel();
Scope Limitation

This ONLY cancels schedules initiated by the Inspector's "Schedule Configuration". It does NOT cancel manual schedules created via RaiseDelayed() or RaiseRepeating(). Use CancelDelayed(handle) or CancelRepeating(handle) for those.

⏱️ Time-Based Scheduling​

RaiseDelayed()

Schedules the event to fire once after a specified delay.

ScheduleHandle RaiseDelayed(float delay);

Parameters:

NameTypeDescription
delayfloatTime in seconds to wait before raising the event

Returns: ScheduleHandle - Handle for cancellation

Example:

// Raise after 5 seconds
ScheduleHandle handle = myEvent.RaiseDelayed(5f);

// Cancel if needed
myEvent.CancelDelayed(handle);
RaiseRepeating()

Schedules the event to fire repeatedly at fixed intervals.

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

Parameters:

NameTypeDescription
intervalfloatSeconds between each execution
repeatCountintNumber of repetitions. Use -1 for infinite (default: -1)

Returns: ScheduleHandle - Handle for cancellation

Example:

// Repeat 10 times
ScheduleHandle handle = tickEvent.RaiseRepeating(1f, repeatCount: 10);

// Repeat forever (infinite loop)
ScheduleHandle infinite = pulseEvent.RaiseRepeating(0.5f);

// Stop infinite loop
pulseEvent.CancelRepeating(infinite);
CancelDelayed()

Cancels a specific delayed event created with RaiseDelayed().

bool CancelDelayed(ScheduleHandle handle);

Parameters:

NameTypeDescription
handleScheduleHandleThe handle returned by RaiseDelayed()

Returns: bool - true if successfully cancelled, false if already executed or invalid

Example:

ScheduleHandle handle = explosionEvent.RaiseDelayed(5f);

// Cancel before explosion happens
if (explosionEvent.CancelDelayed(handle))
{
    Debug.Log("Explosion defused!");
}
CancelRepeating()

Cancels a specific repeating event created with RaiseRepeating().

bool CancelRepeating(ScheduleHandle handle);

Parameters:

NameTypeDescription
handleScheduleHandleThe handle returned by RaiseRepeating()

Returns: bool - true if successfully cancelled, false if already finished or invalid

Example:

ScheduleHandle handle = tickEvent.RaiseRepeating(1f);

// Stop repeating
if (tickEvent.CancelRepeating(handle))
{
    Debug.Log("Timer stopped!");
}

🎧 Listener Management​

AddListener()

Registers a basic listener with standard execution priority.

void AddListener(UnityAction call);

Parameters:

NameTypeDescription
callUnityActionCallback method with no parameters

Example:

myEvent.AddListener(OnEventTriggered);

void OnEventTriggered()
{
    Debug.Log("Event fired!");
}
Duplicate Prevention

If the listener already exists, it will be removed and re-added to prevent duplicates.

RemoveListener()

Unregisters a basic listener from the event.

void RemoveListener(UnityAction call);

Parameters:

NameTypeDescription
callUnityActionCallback method with no parameters

Example:

myEvent.RemoveListener(OnEventTriggered);
RemoveAllListeners()

Clears all Basic, Priority, and Conditional listeners from the event.

void RemoveAllListeners();

Example:

// Clean up all listeners
myEvent.RemoveAllListeners();
Scope

Does NOT remove Persistent listeners or Trigger/Chain events for safety reasons.

AddPriorityListener()

Registers a listener with explicit execution priority. Higher priority values execute first.

void AddPriorityListener(UnityAction call, int priority);

Parameters:

NameTypeDescription
callUnityActionCallback method
priorityintExecution priority (higher = earlier, default: 0)

Example:

myEvent.AddPriorityListener(CriticalHandler, 100);
myEvent.AddPriorityListener(NormalHandler, 50);
myEvent.AddPriorityListener(LowPriorityHandler, 10);
// Execution order: CriticalHandler → NormalHandler → LowPriorityHandler
RemovePriorityListener()

Unregisters a priority listener.

void RemovePriorityListener(UnityAction call);

Parameters:

NameTypeDescription
callUnityActionCallback method with no parameters

Example:

myEvent.RemovePriorityListener(OnEventTriggered);
AddConditionalListener()

Registers a listener that only executes when a condition evaluates to true.

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

Parameters:

NameTypeDescription
callUnityActionCallback method
conditionFunc<bool>Predicate function (null = always execute)
priorityintExecution priority (default: 0)

Example:

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

Unregisters a conditional listener.

void RemoveConditionalListener(UnityAction call);

Parameters:

NameTypeDescription
callUnityActionCallback method with no parameters

Example:

myEvent.RemoveConditionalListener(OnEventTriggered);
AddPersistentListener()

Registers a global listener that survives scene changes (DontDestroyOnLoad).

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

Parameters:

NameTypeDescription
callUnityActionCallback method
priorityintExecution priority (default: 0)

Example:

globalEvent.AddPersistentListener(OnGlobalAction, priority: 100);
Persistence

Persistent listeners remain active across scene loads. Use for global systems like save management or analytics.

RemovePersistentListener()

Unregisters a persistent listener.

void RemovePersistentListener(UnityAction call);

Parameters:

NameTypeDescription
callUnityActionCallback method with no parameters

Example:

myEvent.RemovePersistentListener(OnEventTriggered);

⚡ Trigger Events (Fan-Out Pattern)​

AddTriggerEvent()

Registers a target event to be triggered automatically when this event is raised.

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

Parameters:

NameTypeDescription
targetEventGameEventBaseThe event to trigger
delayfloatOptional delay in seconds (default: 0)
conditionFunc<bool>Optional predicate to gate execution
priorityintExecution order relative to other triggers (default: 0)

Returns: TriggerHandle - Unique identifier for safe removal

Example:

// Simple trigger: door opens → light turns on
doorOpenEvent.AddTriggerEvent(lightOnEvent);

// Delayed trigger: explosion after 2 seconds
fuseEvent.AddTriggerEvent(explosionEvent, delay: 2f);

// Conditional trigger
doorOpenEvent.AddTriggerEvent(
    alarmEvent,
    condition: () => isNightTime
);

// Priority-ordered triggers
bossDefeatedEvent.AddTriggerEvent(stopMusicEvent, priority: 100);
bossDefeatedEvent.AddTriggerEvent(victoryMusicEvent, priority: 90);
bossDefeatedEvent.AddTriggerEvent(showRewardsEvent, priority: 50);
Fan-Out Pattern

Triggers execute in parallel - each trigger is independent. If one trigger's condition fails or throws an exception, other triggers still execute.

RemoveTriggerEvent() (by Handle)

Safely removes a specific trigger using its unique handle.

void RemoveTriggerEvent(TriggerHandle handle);

Parameters:

NameTypeDescription
handleTriggerHandleThe handle returned by AddTriggerEvent()

Example:

TriggerHandle handle = doorEvent.AddTriggerEvent(lightEvent);

// Remove specific trigger
doorEvent.RemoveTriggerEvent(handle);
Recommended

This is the safest removal method as it only removes your specific trigger instance.

RemoveTriggerEvent() (by Target)

Removes all triggers pointing to a specific target event.

void RemoveTriggerEvent(GameEventBase targetEvent);

Parameters:

NameTypeDescription
targetEventGameEventBaseThe target event to disconnect

Example:

doorEvent.RemoveTriggerEvent(lightEvent);
Broad Impact

This removes ALL triggers targeting this event, including those registered by other systems. Use RemoveTriggerEvent(handle) for precision.

RemoveAllTriggerEvents()

Removes all trigger events from this event.

void RemoveAllTriggerEvents();

Example:

myEvent.RemoveAllTriggerEvents();

🔗 Chain Events (Sequential Pattern)​

AddChainEvent()

Registers a target event to execute sequentially in a chain.

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

Parameters:

NameTypeDescription
targetEventGameEventBaseThe event to execute in the chain
delayfloatDelay before executing this node (default: 0)
durationfloatDelay after executing this node (default: 0)
conditionFunc<bool>Optional predicate - chain breaks if false
waitForCompletionboolWait one frame after execution (default: false)

Returns: ChainHandle - Unique identifier for safe removal

Example:

// Simple sequence: A → B → C
eventA.AddChainEvent(eventB);
eventB.AddChainEvent(eventC);

// Cutscene with delays
fadeOutEvent.AddChainEvent(loadSceneEvent, delay: 1f);
loadSceneEvent.AddChainEvent(fadeInEvent, delay: 0.5f);

// Conditional chain: only continue if condition met
combatEndEvent.AddChainEvent(
    victoryEvent,
    condition: () => playerHealth > 0
);

// Chain with frame wait for async operations
showDialogEvent.AddChainEvent(
    typeTextEvent,
    waitForCompletion: true
);
Sequential Execution

Chains are sequential (A → B → C). If any node's condition returns false or throws an exception, the entire chain stops at that point.

Triggers vs Chains
  • Triggers = Parallel (A → [B, C, D]) - all execute independently
  • Chains = Sequential (A → B → C) - strict order, stops on failure
RemoveChainEvent() (by Handle)

Safely removes a specific chain node using its unique handle.

void RemoveChainEvent(ChainHandle handle);

Parameters:

NameTypeDescription
handleChainHandleThe handle returned by AddChainEvent()

Example:

ChainHandle handle = eventA.AddChainEvent(eventB);

// Remove specific chain node
eventA.RemoveChainEvent(handle);
RemoveChainEvent() (by Target)

Removes all chain nodes pointing to a specific target event.

void RemoveChainEvent(GameEventBase targetEvent);

Parameters:

NameTypeDescription
targetEventGameEventBaseThe target event to disconnect

Example:

eventA.RemoveChainEvent(eventB);
Broad Impact

This removes ALL chain nodes targeting this event. Use RemoveChainEvent(handle) for precision.

RemoveAllChainEvents()

Removes all chain events from this event.

void RemoveAllChainEvents();

Example:

myEvent.RemoveAllChainEvents();

🔧 Configuration & Utility​

SetInspectorListenersActive()

Controls whether Inspector-configured listeners should execute when the event is raised.

void SetInspectorListenersActive(bool isActive);

Parameters:

NameTypeDescription
isActivebooltrue to enable Inspector listeners, false to mute them

Example:

// Mute Inspector-configured UI/Audio effects
damageEvent.SetInspectorListenersActive(false);

// Event will only trigger code-registered listeners
damageEvent.Raise(10);

// Re-enable Inspector listeners
damageEvent.SetInspectorListenersActive(true);

Use Cases:

  • Temporarily silence visual/audio effects during cutscenes
  • Run backend calculations without triggering UI updates
  • Disable scene-specific behavior during loading screens
  • Simulate game logic in test/debug mode
Scope

This setting only affects listeners configured in the Unity Inspector via GameEventManager. Listeners registered via AddListener() in code are not affected and will always execute.

🗄️ Database Management​

APIs on GameEventManager.Instance for dynamic database lifecycle — load/unload GameEventDatabase assets at runtime for scene-based content, DLC, or Addressables integration.

RegisterDatabase()

Registers a GameEventDatabase at runtime, making all its events available for binding and invocation. Automatically creates EventBinding entries for events that don't already have one. Duplicate databases are safely ignored.

void RegisterDatabase(GameEventDatabase database);

Parameters:

NameTypeDescription
databaseGameEventDatabaseDatabase asset to register

Example:

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

Unregisters a GameEventDatabase at runtime, removing all its events from the active system. Cleans up associated bindings and runtime callbacks. Safe to call with null or already-unregistered databases.

void UnregisterDatabase(GameEventDatabase database);

Parameters:

NameTypeDescription
databaseGameEventDatabaseDatabase asset to remove

Example:

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

Toggles the active state of a registered database without removing it. Inactive databases retain their registration but their events won't receive invocations.

void SetDatabaseActive(GameEventDatabase database, bool active);

Parameters:

NameTypeDescription
databaseGameEventDatabaseTarget database (must be registered)
activebooltrue to activate, false to mute

Example:

// Pause combat events during cutscene
GameEventManager.Instance.SetDatabaseActive(combatDB, false);

// Resume after cutscene ends
GameEventManager.Instance.SetDatabaseActive(combatDB, true);
Register vs SetActive
  • RegisterDatabase / UnregisterDatabase manages list membership (add / remove).
  • SetDatabaseActive toggles event invocation only — the database stays registered.

🔍 Runtime Query API​

APIs on GameEventManager.Instance for locating events at runtime by GUID, Name, Category, or Type — without [SerializeField] references. Enables non-MonoBehaviour consumers, save/load systems, plugin bridges, and dynamically loaded content.

Every Get* / Has* / TryGet* method has three arities for strict type filtering:

  • Non-generic → returns GameEventBase; matches any event type
  • <T> → matches GameEvent<T> only
  • <TSender, TArgs> → matches GameEvent<TSender, TArgs> only

Type filtering uses is GameEvent<T> / is GameEvent<TSender, TArgs> pattern matching. For example, GetGameEvents<int>("OnJump") returns 0 even if "OnJump" exists as a void event — no cross-type accidents.

All lookups are scoped to active registered databases only.

HasGameEvent() / HasGameEvents()

Existence checks — singular for unique GUIDs, plural for name-based lookups (which may match multiple events).

// By GUID (unique)
bool HasGameEvent(string guid);

// By Name (+ optional category filter)
bool HasGameEvents(string name, string category = null);
bool HasGameEvents<T>(string name, string category = null);
bool HasGameEvents<TSender, TArgs>(string name, string category = null);

Example:

var mgr = GameEventManager.Instance;

if (mgr.HasGameEvent(savedGuid))
    Debug.Log("Saved event still exists");

if (mgr.HasGameEvents("OnDamage", "Combat"))
    Debug.Log("Combat damage event is available");

if (mgr.HasGameEvents<int>("OnScoreChanged"))
    Debug.Log("Typed int score event found");
GetGameEvent() / TryGetGameEvent()

GUID-based retrieval. Returns null / false if GUID not found or type mismatch.

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

Example:

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

Retrieves all events matching a name (with optional category filter). Returns an empty List if none found — never 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);

Parameters:

NameTypeDescription
namestringEvent name to match exactly
categorystringOptional category filter (null = no filtering)

Example:

// Batch raise every event sharing the name "OnJump"
foreach (var e in GameEventManager.Instance.GetGameEvents("OnJump"))
    e.Raise();

// Name + category filter
var combatEvents = GameEventManager.Instance.GetGameEvents("OnDamage", "Combat");

// Type-filtered: only GameEvent<int> matches
var scoreEvents = GameEventManager.Instance.GetGameEvents<int>("OnScoreChanged");
GetFirstGameEventByName() / TryGetFirstGameEventByName()

Convenience helpers when a name lookup should yield a single event. Returns the first event encountered during iteration (arbitrary if duplicates exist). Returns null / false if none match.

// Non-generic
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);

Example:

var mgr = GameEventManager.Instance;

// Void event with category filter
mgr.GetFirstGameEventByName("OnJump", "Movement")?.Raise();

// Typed int lookup
if (mgr.TryGetFirstGameEventByName<int>("OnScoreChanged", out var scoreEvt))
    scoreEvt.Raise(100);

// Sender-aware lookup
if (mgr.TryGetFirstGameEventByName<GameObject, string>("OnEntityAction", out var evt))
    evt.Raise(gameObject, "performed action");
When to use GUID vs Name
  • GUID is unique project-wide — best for save/load, network sync, mod configuration.
  • Name can collide (same name across categories or databases) — use GetGameEvents (plural) for batch operations, or GetFirstGameEventByName when you accept any match.

📊 Quick Reference Table​

Method Categories​

CategoryMethodsPurpose
ExecutionRaise(), Cancel()Trigger events and stop scheduled execution
SchedulingRaiseDelayed(), RaiseRepeating(), CancelDelayed(), CancelRepeating()Time-based event execution
Basic ListenersAddListener(), RemoveListener(), RemoveAllListeners()Standard callback registration
Priority ListenersAddPriorityListener(), RemovePriorityListener()Ordered callback execution
Conditional ListenersAddConditionalListener(), RemoveConditionalListener()Gated callback execution
Persistent ListenersAddPersistentListener(), RemovePersistentListener()Scene-independent callbacks
Trigger EventsAddTriggerEvent(), RemoveTriggerEvent(), RemoveAllTriggerEvents()Parallel event chains
Chain EventsAddChainEvent(), RemoveChainEvent(), RemoveAllChainEvents()Sequential event chains
ConfigurationSetInspectorListenersActive()Runtime behavior control
Database ManagementRegisterDatabase(), UnregisterDatabase(), SetDatabaseActive()Runtime database lifecycle
Runtime QueryHasGameEvent(), GetGameEvent(), TryGetGameEvent(), HasGameEvents(), GetGameEvents(), GetFirstGameEventByName(), TryGetFirstGameEventByName()Locate events by GUID / Name / Category / Type