Commands - World Engine

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 declare the commands a system can access in its state struct. Add a WithCommand[T] field to your system state type, where T is your command type:

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

type AttackSystemState struct {
    cardinal.BaseSystemState
    AttackCommands cardinal.WithCommand[AttackCommand]
}

A system cannot have multiple WithCommand[T] fields with the same command type. However, 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 Iter to loop through all commands received this tick. Each iteration yields a CommandContext that provides access to the command data and metadata. To access the command’s payload, use Payload:

func AttackSystem(state *AttackSystemState) error {
    for cmd := range state.AttackCommands.Iter() {
        attack := cmd.Payload()
        // Use attack.TargetID, attack.Damage, etc.
    }
    return nil
}

Personas

A persona is the unique identity associated with a player’s account. All commands include metadata containing the sender’s persona, which you can use for authorization checks like verifying entity ownership. If your client is authenticated, commands sent from it will automatically include your account’s persona. In multi-shard setups, personas remain consistent across shards, allowing any shard to verify and act on the same player identity. You can get a command’s persona using Persona:

func AttackSystem(state *AttackSystemState) error {
    for cmd := range state.AttackCommands.Iter() {
        attack := cmd.Payload()
        sender := cmd.Persona()

        // Get the player's entity and verify ownership.
        player, ok := state.Players.GetByID(attack.PlayerID)
        if !ok {
            continue
        }
        if player.Owner.Get() != sender {
            continue // Skip unauthorized commands.
        }

        // Process the command...
    }
    return nil
}

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

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, you must first define an OtherWorld variable for each shard you want to communicate with:

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

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

var MatchmakingShard = cardinal.OtherWorld{
    Region:       "us-west-2",
    Organization: "my-org",
    Project:      "my-game",
    ShardID:      "matchmaking",
}

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

Sending Inter-Shard Commands

Use SendCommand to dispatch a command to another shard. Pass the system’s BaseSystemState and the command you want to send:

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

func GameEndSystem(state *GameEndSystemState) error {
    for cmd := range state.EndGameCommands.Iter() {
        game := cmd.Payload()

        // Queue the winner for another match on the matchmaking shard.
        MatchmakingShard.SendCommand(&state.BaseSystemState, matchcmd.QueuePlayer{
            PlayerID: game.WinnerID,
            Rating:   game.NewRating,
        })
    }
    return nil
}

The receiving shard processes inter-shard commands like any other command, using WithCommand in its system state.

The target shard must have a system that handles the command type you’re sending. If no system handles the command, it will be discarded.

​Defining Commands

​Handling Commands

​Iterating Over Commands

​Personas

​Sending Commands

​Command-Reply Pattern

​Inter-Shard Commands

​Defining Shard Targets

​Sending Inter-Shard Commands

Defining Commands

Handling Commands

Iterating Over Commands

Personas

Sending Commands

Command-Reply Pattern

Inter-Shard Commands

Defining Shard Targets

Sending Inter-Shard Commands