NewWorld

NewWorld creates a new World object.

func NewWorld(opts ...WorldOption) (*World, error)

Parameters

ParameterTypeDescription
opts…WorldOptionOptions for configuring the world.

Return Values

TypeDescription
*WorldA pointer to the newly created World instance.
errorAn error indicating any issues during creation.

Options

WithCustomMockRedis

The WithCustomMockRedis option uses the given miniredis instance as the storage layer for the game state. Game state saved to these instances of miniredis are not persistent across world restarts, so this should only be used for local development and testing.

func WithCustomMockRedis(miniRedis *miniredis.Miniredis) WorldOption
Parameters
ParameterTypeDescription
miniRedis*miniredis.MiniredisA miniredis instance.

WithDisableSignatureVerification

The WithDisableSignatureVerification option disables signature verification on the World’s server. This should only be used for testing.

func WithDisableSignatureVerification() WorldOption
Parameters

This method has no parameters.

WithPort

The WithPort option allows for a custom port to be set for the World’s server. If this option is unset it uses a default port of “4040”.

func WithPort(port string) WorldOption
Parameters
ParameterTypeDescription
portstringThe port number for the world’s server.

WithPrettyLog

The WithPrettyLog option enables JSON parsing and colorized, human-friendly formatted logs using zerolog.

func WithPrettyLog() WorldOption
Parameters

This method has no parameters.

WithReceiptHistorySize

The WithReceiptHistorySize option specifies the number of ticks for which the World object retains receipts. For instance, at tick 40 with a receipt history size of 5, the World stores receipts from ticks 35 to 39. Upon reaching tick 41, it will hold receipts for ticks 36 to 40. If this option remains unset, it defaults to a history size of 10. Game clients can get receipts via the /query/receipts/list endpoint. Nakama also uses this endpoint to transmit receipts to listening clients.

func WithReceiptHistorySize(size int) Option
Parameters
ParameterTypeDescription
sizeintThe size of the receipt history to be set for World.

WithStoreManager

The WithStoreManager option overrides the default gamestate manager. The gamestate manager is responsible for storing entity and component information, and recovering those values after a world restart. A default manager will be created if this option is unset.

func WithStoreManager(s gamestate.Manager) WorldOption
Parameters
ParameterTypeDescription
sgamestate.ManagerThe replacement game-state manager.

WithTickChannel

The WithTickChannel option sets a channel that will be used to start each tick. A game tick will be started each time a message appears on the given channel. A custom tick rate can be set using time.Tick. This is also useful in tests to manually start ticks. If unset, a default tick rate of 1 per second is used.

func WithTickChannel(ch <-chan time.Time) WorldOption
Parameters
ParameterTypeDescription
ch<-chan time.TimeThe channel that will start each tick.
Example
// option to make ticks happen every 500 milliseconds.
opt := WithTickChannel(time.Tick(500*time.Millisecond))

WithTickDoneChannel

The WithTickDone option sets a channel that will receive the just-completed tick number each time a tick completes execution. All systems are guaranteed to have been called when a message appears on this channel. This is useful in tests (in conjunction with the WithTickChannel) to make sure your user-defined Systems have fully executed before checking expectations.

func WithTickDoneChannel(ch chan<- uint64) WorldOption
Parameters
ParameterTypeDescription
chchan<- uint64The channel that will be notified at the end of each tick.

RegisterSystems

RegisterSystems registers one or more systems to the World. Systems are executed in the order of which they were added to the world.

func RegisterSystems(w *World, s ...system.System)

Example

package main

import (
	"github.com/my-username/my-world-engine-project/systems"
	"pkg.world.dev/world-engine/cardinal"
)

func main() {
	// ... world setup ...

	// Systems will run in order in which they are added:
	// 1. MoveSystem
	// 2. HealthRegenSystem
	// 3. AttackSystem
	cardinal.RegisterSystems(world,
		systems.MoveSystem,
		systems.HealthRegenSystem,
		systems.AttackSystem)
}

RegisterInitSystems

RegisterInitSystems registers one or more init systems to the World. Init systems are executed exactly one time on tick 0. Init systems will not be run when loading a pre-existing world from permanent storage (e.g. on a server restart).

func RegisterInitSystems(world *World, s ...system.System)

Example

package main

import (
	"github.com/my-username/my-world-engine-project/systems"
	"pkg.world.dev/world-engine/cardinal"
)

func main() {
	// ... world setup ...

	// Systems will be run one time on tick 0
	// 1. CreateEntities
	// 2. InitializeHealth
	cardinal.RegisterSystems(world,
		systems.CreateEntities,
		systems.InitializeHealth,
    )
}

Parameters

ParameterTypeDescription
world*WorldA pointer to a World instance.
s…SystemVariadic parameter for init systems to be added to the World.

RegisterComponents

RegisterComponents registers one or more components to the World. Upon registration, components are assigned an ID. IDs are assigned incrementally, starting from 0, in the order in which they were passed to the method.

func RegisterComponent[T metadata.Component](world *World) error

Example

package main

import (
	"log"
	"github.com/my-username/my-world-engine-project/component"
	"pkg.world.dev/world-engine/cardinal"
)

func main() {
	// ... world setup ...

	err := cardinal.RegisterComponent[LocationComponet](world)
	if err != nil {
		log.Fatal(err)
	}
	err = cardinal.RegisterComponent[AttackPowerComponent](world)
	if err != nil {
		log.Fatal(err)
	}
	err = cardinal.RegisterComponent[HealthComponent](world)
	if err != nil {
		log.Fatal(err)
	}

	// Alternative RegisterComponent pattern with less error checking:
	err = errors.Join(
		cardinal.RegisterComponent[LocationComponet](world),
		cardinal.RegisterComponent[AttackPowerComponent](world),
		cardinal.RegisterComponent[HealthComponent](world),
	)
	if err != nil {
		log.Fatal(err)
	}
}

Parameters

ParameterTypeDescription
Ttype parameterA component struct that implements the Name method.
world*WorldA pointer to a World instance.

Return Value

TypeDescription
errorAn error indicating any issues that occurred during the component registration.

RegisterQuery

RegisterQuery registers the queries in the World. This allows the Query endpoints to be automatically generated.

func RegisterQuery[Request, Reply any](
    world *World,
    name string,
    handler func(engine.Context, req *Request) (*Reply, error),
    opts ...QueryOption[Request, Reply]) error

Example

package main

import (
	"log"

	"github.com/my-username/my-world-engine-project/query"
	"pkg.world.dev/world-engine/cardinal"
)

func main() {
	// ... world setup ...

    err := cardinal.RegisterQuery[query.HealthRequest, query.HealthResponse](
		world,
        "query_health",
        func(worldCtx cardinal.WorldContext, req *query.HealthRequest) (reply *query.HealthReply, err error) {
			// ...fetch relevant health from worldCtx...
			return &HealthReply{}, nil
        })
    if err != nil {
		log.Fatal(err)
    }
}

Parameters

ParameterTypeDescription
Requesttype parameterThe input type of this query
Replytype parameterThe output type of this query
world*WorldA pointer to a World instance.
namestringThe name of the server endpoint to use this query
handlerfunc(engine.Context, *Request) (Reply, error)The handler to execute the logic of this query
opts…QueryOption[Request, Reply]Variadic options to augment the behavior of this query

Return Value

TypeDescription
errorAn error indicating any issues that occurred during the query registration.

RegisterMessages

RegisterMessages registers messages in the World. This allows message endpoints to be automatically generated.

func RegisterMessages(world *World, msgs ...AnyMessage) error

Example

package main

import (
	"log"

	"github.com/my-username/my-world-engine-project/msg"
	"pkg.world.dev/world-engine/cardinal"
)

func main() {
	// ... world setup ...

	err := cardinal.RegisterMessages(world,
		msg.Move,
		msg.Attack,
	)
	if err != nil {
		log.Fatal(err)
	}
}

Parameters

ParameterTypeDescription
world*WorldA pointer to a World instance.
msgs…AnyMessageVariadic parameter for Message instances to be registered.

Return Value

TypeDescription
errorAn error indicating any issues that occurred during the message registration.

StartGame

StartGame starts the game by loading any previously saved game state, spinning up the message/query handler, and starting the game ticks. This method blocks the main Go routine. If for whatever reason execution needs to continue after calling this method, it should be called in a separate go routine.

func (w *World) StartGame() error

Return Value

TypeDescription
errorAn error indicating any issues when starting the game.

Environment Variables

Env VariableDefaultDescription
CARDINAL_MODE“development”One of “production” or “development”. Dev mode, ideal for local development, has relaxed security. Production mode is required for router and EVM functionality
CARDINAL_NAMESPACE“world-1”The cardinal namespace; must not be the default value in “production” mode.
CARDINAL_LOG_LEVEL“info”The zerolog log level to emit. Values include “debug”, “info”, “warn”, and “error”.
BASE_SHARD_SEQUENCER_ADDRESS""The address of the base shard’s router service that handles sequencing game shard txs.
REDIS_ADDRESS“localhost:6379”The URL of a redis instance to use for persistent storage.
REDIS_PASSWORD""The password for the redis instance.
STATSD_ADDRESS“localhost:8125”The address of a statsd metric agent that will collect stats from cardinal.
TRACE_ADDRESS""The address of an agent that supports the collection of traces (e.g. a DataDog agent)