Class ScyllaEvents

Static facade that provides convenient access to the global Scylla Event eXchange System (SEX) event bus.

Inheritance
object
ScyllaEvents
Inherited Members
Namespace: Scylla.Core.Events
Assembly: ScyllaCore.dll
Syntax
public static class ScyllaEvents
Remarks

ScyllaEvents is the primary entry point for publishing and subscribing to events in the SEX system. It exposes the shared IScyllaEventBus singleton via the Bus property and provides shorthand wrappers - Publish<TEvent>(TEvent) and Listen<TEvent>(object, Action<TEvent>, ScyllaEventPriority) - that delegate directly to the bus.

The bus is created on first access using a double-checked locking pattern, ensuring a single ScyllaEventBus instance is constructed even under concurrent access. The default instance is replaced by ScyllaBootstrap at framework startup, but callers that access Bus before the framework initialises will receive an automatically constructed default instance.

To inject a custom or mock implementation - for example in unit tests - call SetBus(IScyllaEventBus) before any events are published or subscribed.

Typical usage from a MonoBehaviour:

private ScyllaEventSubscription _subscription;

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


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


private void OnPlayerDied(PlayerDiedEvent e)
{
Debug.Log($"Player {e.PlayerName} died with score {e.FinalScore}.");
}

Publishing from any system:

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

Properties

Bus

Gets the global IScyllaEventBus singleton used by all SEX operations.

Declaration
public static IScyllaEventBus Bus { get; }
Property Value
Type Description
IScyllaEventBus

The currently active event bus instance. A default ScyllaEventBus is created on first access if no bus has been assigned via SetBus(IScyllaEventBus).
Remarks

Access is thread-safe. A double-checked lock ensures only one default instance is ever created. If SetBus(IScyllaEventBus) is called after the default instance has been created, the new bus replaces it entirely; previously registered subscriptions on the old bus are not migrated.

See Also

Methods

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

Registers handler on the global event bus to be called whenever an event of type TEvent is published.

Declaration
public static 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 a Unity object is destroyed, its subscriptions are silently pruned on the next dispatch. Must not be null.
Action<TEvent> handler

The callback to invoke when a matching event is dispatched. Must not be null.
ScyllaEventPriority priority

The ScyllaEventPriority level that controls when this handler fires relative to other handlers for the same event type. Defaults to Medium.
Returns
Type Description
ScyllaEventSubscription

A ScyllaEventSubscription token. Dispose the token to immediately unsubscribe and release internal resources. Safe to dispose multiple times.
Type Parameters
Name Description
TEvent

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

This is a convenience wrapper that calls Listen<TEvent>(object, Action<TEvent>, ScyllaEventPriority) on Bus. Refer to Listen<TEvent>(object, Action<TEvent>, ScyllaEventPriority) for full subscription semantics, including lifecycle management and leak detection.

Exceptions
Type Condition
ArgumentNullException

Thrown when subscriber or handler is null.
InvalidOperationException

Thrown when the subscriber count for TEvent has reached the hard limit on the underlying bus.
See Also

Publish<TEvent>(TEvent)

Dispatches event to all subscribers registered on the global event bus for TEvent.

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

The event instance to dispatch. If null, a warning is logged and no handlers are invoked.
Type Parameters
Name Description
TEvent

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

This is a convenience wrapper that calls Publish<TEvent>(TEvent) on Bus. Refer to Publish<TEvent>(TEvent) for full dispatch semantics, including priority ordering, cancellation behaviour, and exception isolation.

See Also
Publish<TEvent>(TEvent)

SetBus(IScyllaEventBus)

Replaces the global event bus with a custom IScyllaEventBus implementation.

Declaration
public static void SetBus(IScyllaEventBus bus)
Parameters
Type Name Description
IScyllaEventBus bus

The replacement event bus instance. Must not be null.
Remarks

Call this method before any subscriptions or publications occur to ensure all SEX activity flows through the custom implementation. Common use cases include injecting a mock bus in unit tests or providing a specialised bus with additional instrumentation.

Subscriptions registered on a previously active bus are not transferred to the new bus. If the previous bus held active subscriptions, those handlers will no longer receive events after the swap.

Exceptions
Type Condition
ArgumentNullException

Thrown when bus is null.
See Also

See Also