API Reference

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

func WithCustomMockRedis(miniRedis *miniredis.Miniredis) WorldOption

func WithDisableSignatureVerification() WorldOption

func WithPort(port string) WorldOption

func WithPrettyLog() WorldOption

func WithReceiptHistorySize(size int) WorldOption

func WithStoreManager(s gamestate.Manager) WorldOption

func WithTickChannel(ch <-chan time.Time) WorldOption

// Example 1: Set tick rate to 500ms (2 ticks per second)
opt := WithTickChannel(time.Tick(500*time.Millisecond))

// Example 2: Set tick rate to 50ms (20 ticks per second) for fast-paced games
opt := WithTickChannel(time.Tick(50*time.Millisecond))

// Example 3: Use a custom channel for manual tick control in tests
tickCh := make(chan time.Time)
opt := WithTickChannel(tickCh)

func WithTickDoneChannel(ch chan<- uint64) WorldOption

// Example usage in tests
func TestGameSystem(t *testing.T) {
    tickCh := make(chan time.Time)
    doneCh := make(chan uint64)

    world, _ := cardinal.NewWorld(
        WithTickChannel(tickCh),
        WithTickDoneChannel(doneCh),
    )

    // Start game in a goroutine
    go world.StartGame()

    // Trigger a tick
    tickCh <- time.Now()

    // Wait for tick to complete
    <-doneCh

    // Now safe to check game state
    // Your test assertions here...
}

func WithMessageExpiration(seconds uint) WorldOption

func WithHashCacheSize(sizeKB uint) WorldOption

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

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)
}

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

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,
    )
}

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

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)
	}
}

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

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)
    }
}

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

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)
	}
}

func (w *World) StartGame() error