Messages

Messages enable Cardinal to handle state mutating requests in systems.

package msg
 
import "pkg.world.dev/world-engine/cardinal"
 
 
// AttackInput is the input for the Attack message.
type AttackInput struct {
	TargetID uint64
}
 
// AttackResult is the result of the Attack message.
type AttackResult struct {
	Success bool
}
 
// Attack is an attack message.
var Attack = cardinal.NewMessageType[AttackInput, AttackResult]("attack")

NewMessageType

NewMessageType creates a new MessageType. MessageTypes wrap around an Input and Result type. The Input specifies the input for a message and the Result represents the result of the message's execution.

The given name of the message will be used to generate a message endpoint. For example, if NewMessageType is called with "attack", the http endpoint /tx/game/attack will be created. The "/tx" prefix in this context is short for "Transaction". A Transaction is the combination of a cardinal Message along with a cryptographic signature.

func NewMessageType[Input, Result any](name string) *MessageType[Input, Result]

Type Parameters

Parameters

Return Value

NewMessageTypeWithEVMSupport

NewMessageTypeWithEVMSupport creates a new MessageType with EVM support. This adds additional configuration to the message which enables it to handle requests originating from EVM smart contracts.

func NewMessageTypeWithEVMSupport[Msg, Result any](name string) *MessageType[Msg, Result]

Type Parameters

Parameters

Return Value

Methods

AddError

AddError adds an error to a specific message that signifies an issue has occurred with the message's execution.

func (t *MessageType[Msg, Result]) AddError(worldCtx WorldContext, hash TxHash, err error)

Example

Attack.AddError(
	worldCtx,
	txHash,
	errors.New("attack failed"),
)

Parameters

SetResult

SetResult sets the result for a message's execution. SetResult requires the message type's output data structure for the result data.

func (t *MessageType[Input, Result]) SetResult(
	worldCtx WorldContext,
	hash TxHash,
	result Result,
)

Example

Attack.SetResult(worldCtx, txHash, AttackResult{Success: true})

Parameters

GetReceipt

GetReceipt gets the result and errors, if any, associated with a specific message type.

func (t *MessageType[Msg, Result]) GetReceipt(worldCtx WorldContext, hash TxHash) (r Result, errs []error, ok bool)

Example

result, errs, ok := Attack.GetReceipt(worldCtx, txHash)

Parameters

Return Values

In

In is a method primarily used in Systems that retrieves all messages of the MessageType from the World's TransactionQueue.

func (t *MessageType[Msg, Result]) In(worldCtx WorldContext) []TxData[In]

Example

txs := AttackTx.In(worldCtx)
for _, tx := range txs {
	// ... do something with each msg
	msg := tx.Msg()
	hash := tx.Hash()
	txData := tx.Tx()
}

Parameters

Return Value