ECS

Cardinal uses the Entity Component System (ECS) architecture to structure game code. ECS separates data from logic and encourages a data-driven design that scales well with complexity and performance demands. In ECS:

Entities are plain identifiers that represent “objects” in your game, e.g. players, projectiles, mobs, etc.
Components contain the data of the properties of your entities, for example: a projectile entity contains the position and velocity components.
Systems are the game logic that operates on your entities, for example: a physics system acts on all entities that have mass and position components, or a regeneration system acts on all entities that have a health component.

The World

Before getting into how to use ECS, we’ll briefly cover the World type. This is your game world. It holds all your entities, components, and systems together. Here’s what a typical main.go looks like:

main.go

package main

import (
	"my-game/shards/game/system"

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

func main() {
	w, err := cardinal.NewWorld(cardinal.WorldOptions{
		TickRate:       1,
		EpochFrequency: 10,
	})
	if err != nil {
		panic(err.Error())
	}

	// Register systems.
	w.RegisterSystem(system.MovementSystem)
	w.RegisterSystem(system.CombatSystem)

	// Start the game loop.
	w.StartGame()
}

Above, we also pass several options to configure the behavior of Cardinal:

TickRate sets how many times per second the game loop runs. A tick represents a single state change in Cardinal.
EpochFrequency sets how many ticks to include in an epoch. An epoch is a group of ticks that will be persisted to a blockchain.

There are other options, but these are all you need to run your world.

Components

Components are plain Go structs that implement the Component interface. This interface requires a single Name() method that returns a unique string identifier.

type Position struct {
	X int `json:"x"`
	Y int `json:"y"`
}

func (Position) Name() string {
	return "position"
}

Component names must start with a letter or underscore, and contain only letters, digits, and underscores (e.g. Health, player_health).

What a Component May Hold

Components are copied. Get hands you a copy and Set stores one, and every snapshot is built from what went through Set. That only works if a copy is independent of the original, so a component may hold values only:

Numbers, booleans, and strings
Structs of those
Fixed-size arrays such as [8]Vec2, at any depth
immutable.Slice[T] for a list with no fixed bound (see below)
time.Time, the one sanctioned exception. It carries a location pointer, but it travels as a protobuf Timestamp, so a restored value comes back in UTC with no monotonic reading. Compare times with Equal, never ==.

A component may not hold pointers, maps, plain slices ([]T), interfaces, channels, or funcs. A plain slice inside a copy still shares its backing array with the stored component, so writing through it changes the world without a Set. world sdk generate refuses such fields and prints the fix for each one. The same rule applies to commands and events, which cross the same generator. A list with a known upper bound is a fixed array plus a count:

const MaxItems = 16

type Inventory struct {
	Items [MaxItems]Item `json:"items"`
	Count int            `json:"count"`
}

Lists Without a Bound: `immutable.Slice`

When the length has no bound you can defend, hold the list in immutable.Slice[T] from github.com/argus-labs/world-engine/pkg/immutable. On the wire it is the same repeated field a []T would be. The difference is that the backing array is hidden: no other package can index into it, reslice it, or hold on to it, and every reader hands back a copy of the element.

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

type Buff struct {
	Kind      string `json:"kind"`
	ExpiresAt uint64 `json:"expires_at"` // tick
}

type Buffs struct {
	Active immutable.Slice[Buff] `json:"active"`
}

func (Buffs) Name() string {
	return "buffs"
}

The API follows Go’s slices package closely. Operations are named for their result rather than for an action on the receiver — Reverse becomes Reversed, and Sort and SortFunc become Sorted and SortedFunc. Reads such as At, All, IndexFunc, and MinFunc are methods, and so are derivations such as Append, Insert, With, Without, Sub, Filter, Delete, Reversed, and SortedFunc. Anything that needs a type constraint is a package function, for example Equal, Contains, Sorted, Min, Map, and Concat. Derive, then Set the component that holds it:

func BuffSystem(state *BuffSystemState) error {
	now := state.Tick()
	for _, mob := range state.Mobs.Iter() {
		buffs := mob.Buffs.Get()

		// Drop expired buffs and add a new one.
		buffs.Active = buffs.Active.
			Filter(func(b Buff) bool { return b.ExpiresAt > now }).
			Append(Buff{Kind: "haste", ExpiresAt: now + 60})

		mob.Buffs.Set(buffs)
	}
	return nil
}

immutable.SliceOf(items...) builds a Slice from a plain slice and copies it, so later changes to that slice never reach the component. To go the other way — a plain []T for an API that needs one — range over Values, or use immutable.Collect to build a fresh Slice from the result: there is no Clone method, since a copy taken that way could look like it protects the original while derivations write through it regardless.

Derivations do not copy, so the Set is not optional. Most of them edit the hidden array in place and return a Slice over that same array, which means the component has already changed by the time the derivation returns. Deriving and then dropping the result does not leave the world alone — it leaves the world holding an edit that no snapshot recorded.Append, Repeat, and Sub leave the receiver alone; Insert and Replace leave it alone only when they have to grow. The rest — With, Without, Filter, Delete, Reversed, SortedFunc, CompactFunc, Sorted, and Compact — always write through. Ones that shrink leave the receiver at its old length over a zero-filled tail, so the receiver is not just reordered but wrong.Two rules follow. Call Set after every derivation, even one you think is read-only: s.SortedFunc(cmp).At(0) reorders the stored list. And when the original has to survive, derive from a copy instead: immutable.SliceOf(slices.Collect(s.Values())...).Each method’s Go doc says whether it writes through.

immutable.Slice needs a World CLI new enough to generate it. An older one reports the field as an unsupported type when you run world sdk generate.A Slice has no JSON form of its own — the wire format is protobuf. Keep a json tag on the field if you like, but do not expect a Slice to survive encoding/json.

The element type follows the same rule as any field: values only. A Slice directly inside another Slice has no protobuf form, so wrap the inner one in a named struct, for example immutable.Slice[Row] where Row holds immutable.Slice[Cell].

Tag Components

Components don’t need to contain data. You can use empty structs as “tags” to mark entities:

type Player struct{}

func (Player) Name() string {
	return "player"
}

This is useful for filtering entities without storing additional data, e.g. finding all player entities vs. NPC entities.

Systems

Systems are plain functions that take a single parameter and return an error. The parameter is a pointer to a user-defined struct type that embeds BaseSystemState. This struct defines a system’s dependencies and what it can access, e.g. components, commands, events, etc. (We’ll cover these in more detail soon.) This is the simplest possible system:

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

type MySystemState struct {
	cardinal.BaseSystemState // Required
}

func MySystem(state *MySystemState) error {
	// Your game logic here.
	return nil
}

You must register systems with the world to run them:

w.RegisterSystem(MySystem)

Registered systems run once every tick, in registration order. Cardinal’s scheduler automatically runs systems without shared dependencies in parallel. A system’s dependencies include the components and system events it accesses.

System Hooks

You can control when a system executes during a tick by specifying a hook when you register the system, for example:

// This system now runs in the pre-update phase of the tick.
w.RegisterSystem(SetupSystem, cardinal.WithHook(cardinal.PreUpdate))

By default, systems run on the update phase. Here are the different hooks you can use:

Hook	When it runs
`Init`	Once during world initialization (only once at tick 0), before any game loop starts
`PreUpdate`	Every tick, before the main update phase
`Update`	Every tick, during the main update phase (this is the default if no hook is specified)
`PostUpdate`	Every tick, after the main update phase

Each of these corresponds to a tick phase, except Init, which runs only once in the first tick.

Searches

To work with entities and their components in your systems, you need to define a search. A search lets you find and manipulate entities with specific components. Add a search field to your system state struct using one of these types:

Exact[T]: finds entities that have exactly the specified components, nothing more.
Contains[T]: finds entities that have at least the specified components, but may have others.

For example, say you have player and enemy entities that both have a Health component, but only enemies have an AIBehavior component. Using Contains with just Health would match both players and enemies. Using Exact with Health and AIBehavior would match only enemies. The type parameter T is a struct that lists the components you want to search for. Each field must use Ref[C], where C is a component type:

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

type MobSystemState struct {
	cardinal.BaseSystemState
	Mobs cardinal.Contains[struct {
		Health   cardinal.Ref[Health]
		Position cardinal.Ref[Position]
	}]
}

This defines a search called Mobs that matches all entities with at least Health and Position components. We’ll use it to demonstrate entity operations below.

Creating an Entity

Use Create to spawn a new entity with the components defined in your search. It returns the entity ID and a handle to access its components. All components are initialized to their zero values.

func MobSystem(state *MobSystemState) error {
	// Create a new entity.
	entityID, mob := state.Mobs.Create()

	// Set the entity's component values. Any fields unset remain at their zero values.
	mob.Health.Set(Health{Value: 100})
	mob.Position.Set(Position{X: 0, Y: 0})

	return nil
}

Create always creates an entity with exactly the components in your search, even if you’re using Contains. The difference between Contains and Exact only affects which entities are matched when iterating or querying.

Destroying an Entity

Use Destroy to remove an entity and all its components from the world. Returns true if the entity existed and was destroyed:

func MobSystem(state *MobSystemState) error {
	ok := state.Mobs.Destroy(entityID)
	if !ok {
		// Entity doesn't exist or was already destroyed.
	}
	return nil
}

Iterating Over Entities

Use Iter to loop through all entities matching the search. It yields both the entity ID and a handle to access components:

func MobSystem(state *MobSystemState) error {
	for entityID, mob := range state.Mobs.Iter() {
	  // Use entity...
	}
	return nil
}

Getting a Specific Entity

Use GetByID to retrieve a specific entity’s handle. Returns false if the entity doesn’t exist or doesn’t have the matching components in the search:

func MobSystem(state *MobSystemState) error {
	mob, ok := state.Mobs.GetByID(entityID)
	if !ok {
		// Entity not found.
		return nil
	}
	health := mob.Health.Get()
	// ...
	return nil
}

Reading and Writing Components

Use Get and Set on component references to read and write component data. Get returns a copy, so nothing you do to it reaches the world until you Set it back (see What a Component May Hold):

func MobSystem(state *MobSystemState) error {
	for _, mob := range state.Mobs.Iter() {
		// Read current health.
		health := mob.Health.Get()

		// Write new health.
		mob.Health.Set(Health{Value: health.Value - 10})
	}
	return nil
}

Adding a Component

Because systems must declare all components they access upfront, adding a component requires including it in your search definition. Define a Contains[T] search with both the entity’s existing components and the component you want to add, then use Set to add the new component:

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

type MobSystemState struct {
	cardinal.BaseSystemState
	Mobs cardinal.Contains[struct {
		Health   cardinal.Ref[Health]
		Position cardinal.Ref[Position]
		Poisoned cardinal.Ref[Poisoned] // Add the component
	}]
}

func MobSystem(state *MobSystemState) error {
	for _, mob := range state.Mobs.Iter() {
		// Set will add the component to the entity if it doesn't exist.
		mob.Poisoned.Set(Poisoned{Duration: 10})
	}
	return nil
}

Because you’re using a Contains search, it may match entities you don’t intend to modify. To avoid this, add a tag component so you can distinguish your target entities from the rest.

Removing a Component

Use Remove to detach a component from an entity:

func MobSystem(state *MobSystemState) error {
	for _, mob := range state.Mobs.Iter() {
		// Remove the health component from this entity.
		mob.Health.Remove()
	}
	return nil
}

Getting Started

Cardinal

Forge

The World

Components

What a Component May Hold

Lists Without a Bound: `immutable.Slice`

Tag Components

Systems

System Hooks

Searches

Creating an Entity

Destroying an Entity

Iterating Over Entities

Getting a Specific Entity

Reading and Writing Components

Adding a Component

Removing a Component

​The World

​Components

​What a Component May Hold

​Lists Without a Bound: immutable.Slice

​Tag Components

​Systems

​System Hooks

​Searches

​Creating an Entity

​Destroying an Entity

​Iterating Over Entities

​Getting a Specific Entity

​Reading and Writing Components

​Adding a Component

​Removing a Component

The World

Components

What a Component May Hold

Lists Without a Bound: `immutable.Slice`

Tag Components

Systems

System Hooks

Searches

Creating an Entity

Destroying an Entity

Iterating Over Entities

Getting a Specific Entity

Reading and Writing Components

Adding a Component

Removing a Component