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/component"
	"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 components before the systems that use them.
	w.RegisterComponent[component.Position]()
	w.RegisterComponent[component.Health]()

	// 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).

w.RegisterComponent[Position]()

Registration is explicit. Systems, archetypes, and snapshots only see components registered this way, and a query or Create[T] that names an unregistered component panics.

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:

type BuffSystem struct{}

func (s *BuffSystem) Run(w *cardinal.World) {
	now := w.TickHeight()
	for mob := range w.Contains[struct{ Buffs Buffs }]().Iter() {
		buffs := mob.Get[Buffs]()

		// 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.Set(buffs)
	}
}

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.

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

A system is any type with a Run(w *cardinal.World) method. The world is passed in on every run and gives the system access to queries, commands, events, entities, and the current tick. (We’ll cover these in more detail soon.) Fields on the struct hold the system’s own dependencies, such as a runtime or config. This is the simplest possible system:

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

type MySystem struct{}

func (s *MySystem) Run(w *cardinal.World) {
	// Your game logic here.
}

You must register systems with the world to run them:

w.RegisterSystem(&MySystem{})

RegisterSystem accepts a system instance and passes the world it was registered with to every Run call. Registered systems run sequentially within each tick phase, in registration order.

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(&MySystem{}, 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.

Queries

A query selects entities by component type. Call it on the world from inside Run:

w.Contains[T]() matches entities with every component in T, allowing extras.
w.Exact[T]() matches entities with exactly the components in T.

T is an archetype: a struct whose fields are component types. The struct carries no entity data; it names a set of components. Every component in it must be registered with w.RegisterComponent[C]() before StartGame. Nothing registers components implicitly. A query that names an unregistered component panics. Queries return world-bound Entity handles.

type Mob struct {
    Health   Health
    Position Position
}

type MobSystem struct{}

func (s *MobSystem) Run(w *cardinal.World) {
    for mob := range w.Contains[Mob]().Iter() {
        // ...
    }
}

w.RegisterComponent[Health]()
w.RegisterComponent[Position]()
w.RegisterComponent[Poisoned]()
w.RegisterSystem(&MobSystem{})

Register components before StartGame, including across plugins. Every Register* method panics once the world has started, so a system cannot register anything from Run. The first Contains[T]() or Exact[T]() call for an archetype resolves its component set with reflection and caches it on the world. Later calls for the same T are a map lookup, so querying inside Run on every tick costs no reflection. The search keeps selecting current entities as components change.

Creating an Entity

Use the world’s generic Create[T] method:

func SpawnMob(w *cardinal.World) {
    mob := w.Create[Mob]()
    mob.Set(Health{Value: 100})
    mob.Set(Position{X: 0, Y: 0})
}

Creation adds exactly the archetype’s components, initialized to zero. Create[T] panics if any component in T was not registered with w.RegisterComponent. A query’s Create() does the same for the query’s archetype: w.Contains[Mob]().Create().

Entity Handles and Stored IDs

An Entity carries its numeric ID and owning world. Its methods need no extra world argument. Use entity.ID() in components, commands, physics lookups, and persistent data. To access that ID in a system, bind it to the world:

entity := w.Entity(entityID)
if entity.Alive() && entity.Has[Health]() {
    health := entity.Get[Health]()
    entity.Set(Health{Value: health.Value - 10})
}

EntityID remains a numeric value. Store IDs rather than runtime handles. After snapshot restoration, w.Entity(savedID) binds an ID to the restored world. IDs belong to one world and can be reused after destruction or reset, so discard handles when that happens. Access handles from systems on the world’s execution goroutine.

Iterating Over Entities

Iter yields each matching Entity:

func DamageMobs(w *cardinal.World) {
    for mob := range w.Contains[Mob]().Iter() {
        health := mob.Get[Health]()
        mob.Set(Health{Value: health.Value - 10})
    }
}

Handles are independent values. Retaining one during another query does not change which entity it refers to. Get[T] returns a copy. Write changes back with Set, subject to the component ownership rules in What a Component May Hold. Use Filter(func(Entity) bool) and Limit to narrow results. Single() returns (Entity, error) and requires exactly one match.

Getting a Specific Entity

GetByID validates the query’s component requirements before returning a handle:

mob, err := w.Contains[Mob]().GetByID(entityID)
if err != nil {
    // The entity is absent or its components do not match the query.
    return
}
health := mob.Get[Health]()

Use w.Entity(entityID) when no archetype check is needed. Binding does not itself check existence. Alive() and Has[T]() return false for absent entities.

Adding and Removing Components

Set infers the component type from its argument and adds or replaces it:

mob.Set(Poisoned{Duration: 10})
if mob.Has[Poisoned]() {
    mob.Remove[Poisoned]()
}

Optional types must be registered with w.RegisterComponent[T]() like any other component. They do not need to be part of the query that found the entity, and nothing declares them on the system. Get, Set, and Remove panic for invalid operations, including access to a destroyed entity or an unregistered component. Get also panics for an absent component. Removing a registered component that is already absent is a no-op. Adding or removing components changes an entity’s archetype. Collect handles before making structural changes while iterating a query, so moving rows cannot skip other matches.

Destroying an Entity

Destroy removes the entity and all its components. It returns true only if an entity was removed:

mob.Destroy()

A zero Entity is not alive. Its Has and Destroy methods return false, and component reads or writes panic.

Getting Started

Cardinal

Forge

The World

Components

What a Component May Hold

Lists Without a Bound: `immutable.Slice`

Tag Components

Systems

System Hooks

Queries

Creating an Entity

Entity Handles and Stored IDs

Iterating Over Entities

Getting a Specific Entity

Adding and Removing Components

Destroying an Entity

​The World

​Components

​What a Component May Hold

​Lists Without a Bound: immutable.Slice

​Tag Components

​Systems

​System Hooks

​Queries

​Creating an Entity

​Entity Handles and Stored IDs

​Iterating Over Entities

​Getting a Specific Entity

​Adding and Removing Components

​Destroying an Entity

The World

Components

What a Component May Hold

Lists Without a Bound: `immutable.Slice`

Tag Components

Systems

System Hooks

Queries

Creating an Entity

Entity Handles and Stored IDs

Iterating Over Entities

Getting a Specific Entity

Adding and Removing Components

Destroying an Entity