Commands

Commands are how players interact with your game world. They represent actions that players want to perform, such as moving, attacking, or chatting. To handle commands in your game, you must first define them and create systems to handle them. Commands can come from either game clients or other shards.

Defining Commands

Commands are plain Go structs that embed BaseCommand and implement the Command interface. This interface requires a single Name() method that returns a unique string identifier.

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

type AttackCommand struct {
    cardinal.BaseCommand // Required
    TargetID string `json:"target_id"`
    Damage   int    `json:"damage"`
}

func (AttackCommand) Name() string {
    return "attack"
}

Handling Commands

Just like with components, you must register a command type with the world before StartGame. The service only accepts commands that are registered:

w.RegisterCommand[AttackCommand]()

Different systems can handle the same command type. This is useful for when you want a single command to trigger multiple game logic and/or side effects.

Iterating Over Commands

Use w.Commands[T]() to loop through all commands of type T received this tick. Each iteration yields a CommandContext whose fields hold the command data and metadata. To access the command’s payload, read the Payload field:

type AttackSystem struct{}

func (s *AttackSystem) Run(w *cardinal.World) {
    for cmd := range w.Commands[AttackCommand]() {
        attack := cmd.Payload
        // Use attack.TargetID, attack.Damage, etc.
    }
}

Senders

Every command knows who sent it, which you can use for authorization checks like verifying entity ownership. A sender is either a player or another shard:

cmd.Player() returns the player ID and true when a client sent the command. Cardinal takes the ID from the client’s auth token, so a client cannot claim to be another player. Player IDs are the same on every shard of a project.
cmd.Shard() returns the sending shard’s address (<project>.<shard_id>, such as my-game.matchmaking) and true when another shard sent the command with w.SendToShard.
cmd.Sender() returns either one, for code that doesn’t care which, such as logs.

func (s *AttackSystem) Run(w *cardinal.World) {
    players := w.Contains[struct{ Owner Owner }]()
    for cmd := range w.Commands[AttackCommand]() {
        attack := cmd.Payload
        sender, ok := cmd.Player()
        if !ok {
            continue // Sent by another shard, not a player.
        }

        // Get the player's entity and verify ownership.
        player, err := players.GetByID(attack.PlayerID)
        if err != nil {
            continue
        }
        if player.Get[Owner]().PlayerID != sender {
            continue // Skip unauthorized commands.
        }

        // Process the command...
    }
}

Sending Commands

Use the client SDK to send commands to the server:

Unity C#
TypeScript

await shard.SendCommandAsync("attack", new Dictionary<string, object>
{
    ["target_id"] = "enemy-123",
    ["damage"] = 50
});

TODO: update

Command-Reply Pattern

Commands are asynchronous by design. When you send a command, you receive an acknowledgment, but not the result of the command’s execution. If you need a result, you typically emit an event from the system that processes the command and subscribe to it from the client. Some command types are more synchronous in nature, like updating game config, where every command has a corresponding result event. For these cases, use the synchronous command method, which handles the temporary event subscription for you and returns the result event directly:

Unity C#
TypeScript

var result = await shard.SendCommandWithReplyAsync<PurchaseResult>("buy-item", new Dictionary<string, object>
{
    ["item_id"] = "sword-01",
    ["quantity"] = 1
});

TODO: update

In the system that handles the command, send the reply with w.SendTo(playerID, event), using the player ID from cmd.Player(). A targeted reply answers only that player’s pending requests for that event name, while w.Broadcast answers every player’s.

Inter-Shard Commands

In a multi-shard setup, you can send commands from within a system to another shard. This allows you to trigger systems in other shards or coordinate game state.

Defining Shard Targets

To send an inter-shard command, construct an OtherWorld value for each destination and pass it into the system:

The convention is to place this in pkg/other_worlds/other_world.go.

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

matchmakingShard := cardinal.OtherWorld{
    Project: "my-game",
    ShardID: "matchmaking",
}
w.RegisterSystem(&GameEndSystem{MatchmakingShard: matchmakingShard})

An OtherWorld represents a specific remote shard and is used to route commands to the correct destination.

Sending Inter-Shard Commands

Use the world’s SendToShard to dispatch a command to another shard. Pass the destination OtherWorld and the command you want to send:

import matchcmd "my-game/shards/matchmaking/command"

type GameEndSystem struct {
    MatchmakingShard cardinal.OtherWorld
}

func (s *GameEndSystem) Run(w *cardinal.World) {
    for cmd := range w.Commands[EndGameCommand]() {
        game := cmd.Payload

        // Queue the winner for another match on the matchmaking shard.
        w.SendToShard(s.MatchmakingShard, matchcmd.QueuePlayer{
            PlayerID: game.WinnerID,
            Rating:   game.NewRating,
        })
    }
}

The receiving shard processes inter-shard commands like any other command: it registers the type with RegisterCommand and reads it with w.Commands[T]().

The target shard must register the command type you’re sending. If the type is not registered there, the target rejects the command and it is not delivered.

Getting Started

Cardinal

Forge

Defining Commands

Handling Commands

Iterating Over Commands

Senders

Sending Commands

Command-Reply Pattern

Inter-Shard Commands

Defining Shard Targets

Sending Inter-Shard Commands

​Defining Commands

​Handling Commands

​Iterating Over Commands

​Senders

​Sending Commands

​Command-Reply Pattern

​Inter-Shard Commands

​Defining Shard Targets

​Sending Inter-Shard Commands

Defining Commands

Handling Commands

Iterating Over Commands

Senders

Sending Commands

Command-Reply Pattern

Inter-Shard Commands

Defining Shard Targets

Sending Inter-Shard Commands