System Events

System events are how systems communicate with each other inside a single shard. They are internal messages that one system emits and other systems receive during the same tick. Unlike events, which are broadcast to game clients, system events never leave the server. They’re useful for decoupling systems that need to react to each other’s logic. System events are scoped to a single tick: they’re produced and consumed within the tick, then cleared.

Defining System Events

System events are plain Go structs that implement the SystemEvent interface. This interface requires a single Name() method that returns a unique string identifier:

type PlayerDeathSystemEvent struct {
    PlayerID string `json:"player_id"`
    Reason   string `json:"reason"`
}

func (PlayerDeathSystemEvent) Name() string {
    return "player-death"
}

Using System Events

Just like with components and commands, you must register a system event type with the world before StartGame:

w.RegisterSystemEvent[PlayerDeathSystemEvent]()

Emitting System Events

Use w.EmitSystemEvent to send a system event:

type CombatSystem struct{}

func (s *CombatSystem) Run(w *cardinal.World) {
    // Emit a player death event to be handled by other systems.
    w.EmitSystemEvent(PlayerDeathSystemEvent{
        PlayerID: playerID,
        Reason:   "health_zero",
    })
}

Emitting or receiving a system event type that was not registered panics.

Receiving System Events

Use w.SystemEvents[T]() to loop through all system events of type T emitted so far this tick:

type GraveyardSystem struct{}

func (s *GraveyardSystem) Run(w *cardinal.World) {
    for death := range w.SystemEvents[PlayerDeathSystemEvent]() {
        // Handle death.PlayerID, death.Reason, etc.
    }
}

Different systems can receive the same system event type.

Scheduling and Ordering

Systems run in the order they are registered. To ensure emitters run before receivers, register emitting systems first:

CombatSystem (emits) → GraveyardSystem (receives)
                     → AnalyticsSystem (receives)

If a receiver runs before its emitter, it will not receive any system events for that tick, as they haven’t been emitted yet. Multiple systems can receive the same system event type, and they will each get all events emitted that tick.

Getting Started

Cardinal

Forge

Defining System Events

Using System Events

Emitting System Events

Receiving System Events

Scheduling and Ordering

​Defining System Events

​Using System Events

​Emitting System Events

​Receiving System Events

​Scheduling and Ordering

Defining System Events

Using System Events

Emitting System Events

Receiving System Events

Scheduling and Ordering