Interface IScyllaEventBus

Defines the contract for the Scylla Event eXchange System (SEX) event bus. The bus provides strongly-typed, priority-ordered publish/subscribe messaging between decoupled game systems.

Namespace: Scylla.Core.Events
Assembly: ScyllaCore.dll
Syntax
public interface IScyllaEventBus
Remarks

The event bus routes events from a single publisher to any number of subscribers without creating direct dependencies between them. Events are defined as classes that inherit from ScyllaEvent; subscribers register interest in a specific event type via Listen<TEvent>(object, Action<TEvent>, ScyllaEventPriority) and publishers dispatch instances via Publish<TEvent>(TEvent).

Dispatch is synchronous and happens on the calling thread. All registered handlers for the published event type are invoked within the same Publish<TEvent>(TEvent) call, in ascending ScyllaEventPriority order. Exception isolation is applied per-handler: if a handler throws, the exception is caught, logged, and the remaining handlers continue to execute.

The default implementation is ScyllaEventBus. Use Bus to access the global instance, or SetBus(IScyllaEventBus) to inject a custom or mock implementation.

Methods

Listen<TEvent>(object, Action<TEvent>, ScyllaEventPriority)

Registers a handler callback to be invoked whenever an event of type TEvent is published on this bus.

Declaration
ScyllaEventSubscription Listen<TEvent>(object subscriber, Action<TEvent> handler, ScyllaEventPriority priority = ScyllaEventPriority.Medium) where TEvent : ScyllaEvent
Parameters
Type Name Description
object subscriber

The object that owns this subscription, used for automatic lifecycle management. When the subscriber is a UnityEngine.Object and Unity destroys it, the subscription is automatically considered stale and pruned on the next dispatch. For plain C# objects, the subscription is pruned if the reference is null. Must not be null.
Action<TEvent> handler

The callback to invoke when a matching event is dispatched. Receives the event instance as its only argument. Must not be null.
ScyllaEventPriority priority

Determines the order in which this handler is called relative to other handlers for the same event type. Lower numeric values run first. Defaults to Medium.
Returns
Type Description
ScyllaEventSubscription

A ScyllaEventSubscription token. Dispose the token to immediately unsubscribe the handler and release internal resources. The token is safe to dispose more than once.
Type Parameters
Name Description
TEvent

The concrete event type to subscribe to. Must derive from ScyllaEvent.
Remarks

The bus logs a warning when the subscriber count for an event type reaches a soft threshold (100 by default) to help detect leaks early.

Subscribing to an event and storing the token for later disposal:

private ScyllaEventSubscription _subscription;

private void OnEnable()
{
_subscription = ScyllaEvents.Bus.Listen<PlayerDiedEvent>(
this,
OnPlayerDied,
ScyllaEventPriority.High
);
}


private void OnDisable()
{
_subscription?.Dispose();
_subscription = null;
}


private void OnPlayerDied(PlayerDiedEvent e)
{
// Handle event.
}
Exceptions
Type Condition
ArgumentNullException

Thrown when subscriber or handler is null.
InvalidOperationException

Thrown when the total number of subscribers for TEvent reaches the hard limit configured in ScyllaEventBus (1000 by default), which typically indicates a subscription leak.
See Also

PruneInvalidSubscribers()

Removes every subscription whose subscriber is a destroyed Unity object (or a plain null reference) across ALL event types.

Declaration
int PruneInvalidSubscribers()
Returns
Type Description
int

The number of invalid subscriptions that were removed.
Remarks

Destroyed subscribers are normally pruned lazily on the next publish of their event type; this method performs the cleanup eagerly across the whole bus. Called by the scene management subsystem during scene transitions so subscriptions from destroyed scene objects do not accumulate.

Publish<TEvent>(TEvent)

Dispatches the given event instance to all active subscribers registered for TEvent, invoking their handlers in ScyllaEventPriority order.

Declaration
void Publish<TEvent>(TEvent @event) where TEvent : ScyllaEvent
Parameters
Type Name Description
TEvent event

The event instance to dispatch. Must not be null; passing null logs a warning and returns without invoking any handler.
Type Parameters
Name Description
TEvent

The concrete event type to dispatch. Must derive from ScyllaEvent.
Remarks

The same event instance is passed to every handler in the dispatch chain. A handler may call StopPropagation() on the event to prevent delivery to subsequent lower-priority handlers. Handlers at Essential and Cleanup are always invoked regardless of cancellation.

Stale subscriptions whose subscriber object has been destroyed are silently pruned during each dispatch pass. 

ScyllaEvents.Bus.Publish(new PlayerDiedEvent("Hero", 4200));
See Also

Extension Methods

See Also