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

Parameter	Type	Description
`T`	`type parameter`	A registered component struct that implements the Name method
`worldCtx`	`WorldContext`	A WorldContext object passed in to your System or Query definition
`id`	`EntityID`	The ID of the entity from which to retrieve the component data.

Return Values

Type	Description
`T`	The retrieved component data.
`error`	An 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

Parameter	Type	Description
`T`	`type parameter`	A registered component struct that implements the Name method
`worldCtx`	`WorldContext`	A WorldContext object passed in to your System or Query definition
`id`	`EntityID`	Entity ID of the entity to set the component data for.
`component`	`T`	Component value to set for the entity.

Return Value

Type	Description
`error`	An 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

Parameter	Type	Description
`T`	`type parameter`	A registered component struct that implements the Name method
`worldCtx`	`WorldContext`	A WorldContext object passed in to your System or Query definition
`id`	`EntityID`	ID of the entity to perform the component update on.
`fn`	`func(T) T`	Function that modifies the component's value.

Return Value

Type	Description
`error`	An 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

Parameter	Type	Description
`T`	`type parameter`	A registered component struct that implements the Name method
`worldCtx`	`WorldContext`	A WorldContext object passed in to your System or Query definition
`id`	`EntityID`	Entity ID of the entity to remove the component from.

Return Value

Type	Description
`error`	Returns 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

Parameter	Type	Description
`T`	`type parameter`	A registered component struct that implements the Name method
`worldCtx`	`WorldContext`	A WorldContext object passed in to your System or Query definition
`id`	`EntityID`	Entity ID of the entity to add the component to.

Return Value

Type	Description
`error`	Returns an error if the operation encounters an issue.

ECS Systems