Messages are predefined user actions that can be submitted to Cardinal and handled within a system. A message is the primary way of representing possible user actions in the game. After a message is processed within a tick, it returns a Reply payload that can be read by the game client.

In Cardinal, messages are defined using a pair of Go structs representing a Message and a Reply.

Example:

• An AttackPlayerMsg message may contain the TargetNickname of the player you want to attack.
• A MoveMsg message may contain the Direction and Distance of the move.

​

Defining Messages

By convention, messages are defined in the msg directory, with each message definition in its own separate file.

You can easily create a new message and register it to the world by following these steps:

package msg

type AttackPlayerMsg struct {
    TargetNickname string
}

type AttackPlayerMsgReply struct {
    Damage int
}

package main

import (
    "pkg.world.dev/world-engine/cardinal"
    "github.com/argus-labs/starter-game-template/cardinal/msg"
)

func main() {
    w, err := cardinal.NewWorld()
    if err != nil {
        log.Fatal().Err(err).Msg("failed to create world")
    }

    // Register messages (user action)
    // NOTE: You must register your message here for it to be executed.
    err := cardinal.RegisterMessage[msg.AttackPlayerMsg, msg.AttackPlayerMsgReply](w, "attack-player")
    if err != nil {
        log.Fatal().Err(err).Msg("failed to register message")
    }

    // ...
}

​

Message Options

​

EVM Support

Messages can be submitted by EVM smart contracts by using the WithMsgEVMSupport option when you register your messages. This will generate the ABI types necessary for interactions with smart contracts.

import (
    "pkg.world.dev/world-engine/cardinal"
    "pkg.world.dev/world-engine/cardinal/message"
    "github.com/argus-labs/starter-game-template/cardinal/msg"
)

cardinal.RegisterMessage[msg.AttackPlayerMsg, msg.AttackPlayerMsgReply](w, "attack-player", 
    message.WithMsgEVMSupport[msg.AttackPlayerMsg, msg.AttackPlayerMsgReply]())

​

Common Message Patterns

​

Iterating over messages

package system

// If AttackSystem is registered with the cardinal World, it will be executed each tick.
func AttackSystem(worldCtx cardinal.WorldContext) error {
    // Iterate over the messages that came in during the previous tick
    return cardinal.EachMessage[msg.AttackPlayerMsg, msg.AttackPlayerMsgReply](
        worldCtx,
        func(attack cardinal.TxData[msg.AttackPlayerMsg]) (msg.AttackPlayerMsgReply, error) {
            // Handle attack logic here...
        })
}