Events

Events are notifications sent to game clients about things happening in your game, such as a player dying, an item dropping, or a match ending. While commands are input from players, events are output from systems. Events are useful for triggering real-time UI updates, playing sound effects, or synchronizing game state across clients. Note that events are distinct from system events, which are internal messages for communication between systems within a single tick.

Defining Events

Events are plain Go structs that embed BaseEvent and implement the Event interface. This interface requires a single Name() method that returns a unique string identifier.

import "github.com/argus-labs/world-engine/pkg/cardinal"

type PlayerDeathEvent struct {
    cardinal.BaseEvent
    PlayerID string `json:"player_id"`
    KillerID string `json:"killer_id"`
}

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

Emitting Events

Just like with commands, you must register an event type with the world before StartGame:

w.RegisterEvent[PlayerDeathEvent]()

In your system, use w.Broadcast to emit the event to every subscribed client:

type CombatSystem struct{}

func (s *CombatSystem) Run(w *cardinal.World) {
    // Game logic that results in a player death...

    w.Broadcast(PlayerDeathEvent{
        PlayerID: "player-123",
        KillerID: "player-456",
    })
}

Use w.SendTo(persona, event) instead to deliver the event only to one persona. If that persona has no open event stream, the event is dropped.

Just like with commands, an event type must be registered before it is sent. Broadcast and SendTo panic for an unregistered event type.

Subscribing to Events

Events emitted during a tick are collected and broadcast to subscribers at the end of that tick. While events are broadcast, clients must explicitly subscribe to receive them. Subscribe to an event by passing the event name and a handler function:

Unity C#
TypeScript

var handler = evt =>
{
    Debug.Log($"New player event: {evt.Payload}");
};
await shard.SubscribeEventAsync("new-player", handler);

TODO: update

Unsubscribe from an event when you no longer need to receive updates:

Unity C#
TypeScript

await shard.UnsubscribeEventAsync("new-player", handler);

TODO: update

Getting Started

Cardinal

Forge

Defining Events

Emitting Events

Subscribing to Events

​Defining Events

​Emitting Events

​Subscribing to Events

Defining Events

Emitting Events

Subscribing to Events