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