Cardinal
API Reference
Components

Components

Any simple struct that provides a Name method can be used as a component. The name you give to a component must be unique within your game.

package components
 
type Health struct {
    Amount      uint64
    Capacity    uint64
}
 
func (Health) Name() string {
	return "health"
}

Registering Components

Before Components can be used to create or modify entities, they must be registered with the world object. See Register Components for more details

import "pkg.world.dev/world-engine/cardinal"
 
err := cardinal.RegisterComponent[Health](world)
if err != nil {
    log.Fatal(err)
}

Checking each returned error can be verbose; multiple components can be registered in a single statement with this pattern:

import "pkg.world.dev/world-engine/cardinal"
 
err := errors.Join(
	cardinal.RegisterComponent[Health](world),
	cardinal.RegisterComponent[Power](world),
	cardinal.RegisterComponent[Strength](world),
	cardinal.RegisterComponent[Agility](world),
	...
	)
if err != nil {
    log.Fatal(err)
}

Methods

GetComponent

GetComponent retrieves the underlying component data for a given entity.

func GetComponent[T metadata.Component](worldContext WorldContext, id entity.ID) (*T, error)

Example

import "pkg.world.dev/world-engine/cardinal"
 
health, err := cardinal.GetComponent[Health](worldCtx, id)

Parameters

ParameterTypeDescription
Ttype parameterA registered component struct that implements the Name method
worldCtxWorldContextA WorldContext object passed in to your System or Query definition
idEntityIDThe ID of the entity from which to retrieve the component data.

Return Values

TypeDescription
TThe retrieved component data.
errorAn error indicating any issues during retrieval.

SetComponent

SetComponent sets the component data for a given entity.

func SetComponent[T metadata.Component](worldCtx WorldContext, id entity.ID, component *T) error

Example

import "pkg.world.dev/world-engine/cardinal"
 
newHealth := Health{Amount: 45, Capacity: 100}
err := cardinal.SetComponent[Health](worldCtx, id, newHealth)

Parameters

ParameterTypeDescription
Ttype parameterA registered component struct that implements the Name method
worldCtxWorldContextA WorldContext object passed in to your System or Query definition
idEntityIDEntity ID of the entity to set the component data for.
componentTComponent value to set for the entity.

Return Value

TypeDescription
errorAn error indicating any issues during the operation.

Update

Update enables modification of the underlying component data in a single function call. Update uses Get and Set under the hood.

func UpdateComponent[T metadata.Component](worldCtx WorldContext, id entity.ID, fn func(*T) *T) error

Example

import "pkg.world.dev/world-engine/cardinal"
 
err := cardinal.UpdateComponent[Health](worldCtx, id, func(h *Health) *Health {
	h.Amount -= 10 // take away 10 health
	return r
})

Parameters

ParameterTypeDescription
Ttype parameterA registered component struct that implements the Name method
worldCtxWorldContextA WorldContext object passed in to your System or Query definition
idEntityIDID of the entity to perform the component update on.
fnfunc(*T) *TFunction that modifies the component's value.

Return Value

TypeDescription
errorAn error indicating any issues during the operation.

RemoveFrom

RemoveFrom removes the component from the given entity. An error will be returned if the entity does not have the component.

func RemoveComponentFrom[T metadata.Component](wCtx WorldContext, id entity.ID) error

Example

import "pkg.world.dev/world-engine/cardinal"
 
target := EntityID(10)
err := cardinal.RemoveComponentFrom[Health](worldCtx, target)

Parameters

ParameterTypeDescription
Ttype parameterA registered component struct that implements the Name method
worldCtxWorldContextA WorldContext object passed in to your System or Query definition
idEntityIDEntity ID of the entity to remove the component from.

Return Value

TypeDescription
errorReturns an error if the operation encounters an issue.

AddTo

AddComponentTo adds the component to a given entity. An error will be returned if the entity already has the component.

func AddComponentTo[T metadata.Component](wCtx WorldContext, id entity.ID) error

Example

import "pkg.world.dev/world-engine/cardinal"
 
target := EntityID(40)
err := cardinal.AddComponentTo[Health](worldCtx, target)

Parameters

ParameterTypeDescription
Ttype parameterA registered component struct that implements the Name method
worldCtxWorldContextA WorldContext object passed in to your System or Query definition
idEntityIDEntity ID of the entity to add the component to.

Return Value

TypeDescription
errorReturns an error if the operation encounters an issue.