ecs

Documentation

Overview

Package ecs contains Arche's core API.

See the top level module github.com/mlange-42/arche for an overview.

Index

• Constants
• type Component
• type Config
  • func NewConfig() Config
  • func (c Config) WithCapacityIncrement(inc int) Config
• type Entity
  • func (e Entity) IsZero() bool
• type EntityEvent
  • func (e *EntityEvent) EntityAdded() bool
  • func (e *EntityEvent) EntityRemoved() bool
• type Filter
• type ID
  • func ComponentID[T any](w *World) ID
  • func TypeID(w *World, tp reflect.Type) ID
• type Mask
  • func All(ids ...ID) Mask
  • func (b *Mask) Contains(other Mask) bool
  • func (b *Mask) ContainsAny(other Mask) bool
  • func (b *Mask) Get(bit ID) bool
  • func (b *Mask) IsZero() bool
  • func (b Mask) Matches(bits Mask) bool
  • func (b *Mask) Reset()
  • func (b *Mask) Set(bit ID, value bool)
  • func (b *Mask) TotalBitsSet() int
  • func (b Mask) Without(comps ...ID) MaskFilter
• type MaskFilter
  • func (f *MaskFilter) Matches(bits Mask) bool
• type Query
  • func (q *Query) Close()
  • func (q *Query) Entity() Entity
  • func (q *Query) Get(comp ID) unsafe.Pointer
  • func (q *Query) Has(comp ID) bool
  • func (q *Query) Mask() Mask
  • func (q *Query) Next() bool
• type World
  • func NewWorld(config ...Config) World
  • func (w *World) Add(entity Entity, comps ...ID)
  • func (w *World) Alive(entity Entity) bool
  • func (w *World) Assign(entity Entity, comps ...Component)
  • func (w *World) Exchange(entity Entity, add []ID, rem []ID)
  • func (w *World) Get(entity Entity, comp ID) unsafe.Pointer
  • func (w *World) Has(entity Entity, comp ID) bool
  • func (w *World) IsLocked() bool
  • func (w *World) Mask(entity Entity) Mask
  • func (w *World) NewEntity(comps ...ID) Entity
  • func (w *World) NewEntityWith(comps ...Component) Entity
  • func (w *World) Query(filter Filter) Query
  • func (w *World) Remove(entity Entity, comps ...ID)
  • func (w *World) RemoveEntity(entity Entity)
  • func (w *World) Set(entity Entity, id ID, comp interface{}) unsafe.Pointer
  • func (w *World) SetListener(listener func(e EntityEvent))
  • func (w *World) Stats() *stats.WorldStats

Constants

const MaskTotalBits = 128

MaskTotalBits is the size of Mask in bits.

It is the maximum number of component types that may exist in any World.

Types

type Component

type Component struct {
	ID   ID
	Comp interface{}
}

Component is a component ID/pointer pair.

It is a helper for World.Assign and World.NewEntityWith. It is not related to how components are implemented in Arche.

type Config

type Config struct {
	CapacityIncrement int
}

Config provides configuration for an ECS World.

func NewConfig

func NewConfig() Config

NewConfig creates a new default World configuration.

func (Config) WithCapacityIncrement

func (c Config) WithCapacityIncrement(inc int) Config

WithCapacityIncrement return a new Config with CapacityIncrement set. Use with method chaining.

type Entity

type Entity struct {
	// contains filtered or unexported fields
}

Entity identifier. Holds an entity ID and it's generation for recycling.

Entities should only be created via the World, using World.NewEntity or World.NewEntityWith.

func (Entity) IsZero

func (e Entity) IsZero() bool

IsZero returns whether this entity is the reserved zero entity.

type EntityEvent

type EntityEvent struct {
	// The entity that was changed.
	Entity Entity
	// The old and new component masks.
	OldMask, NewMask Mask
	// Components added, removed, and after the change.
	Added, Removed, Current []ID
	// Whether the entity itself was added (> 0), removed (< 0), or only changed (= 0).
	AddedRemoved int
}

EntityEvent contains information about component changes.

To receive change events, register a function func(e EntityEvent) with World.SetListener.

func (*EntityEvent) EntityAdded

func (e *EntityEvent) EntityAdded() bool

EntityAdded reports whether the entity was newly added.

func (*EntityEvent) EntityRemoved

func (e *EntityEvent) EntityRemoved() bool

EntityRemoved reports whether the entity was removed.

type Filter

type Filter interface {
	// Matches the filter against a bitmask, i.e. a component composition.
	Matches(bits Mask) bool
}

Filter is the interface for logic filters. Filters are required to query entities using World.Query.

See Mask and MaskFilter for basic filters. For type-safe generics queries, see package github.com/mlange-42/arche/generic. For advanced filtering, see package github.com/mlange-42/arche/filter.

type ID

type ID = uint8

ID is the component identifier type.

func ComponentID

func ComponentID[T any](w *World) ID

ComponentID returns the ID for a component type via generics. Registers the type if it is not already registered.

func TypeID

func TypeID(w *World, tp reflect.Type) ID

TypeID returns the ID for a component type. Registers the type if it is not already registered.

type Mask

type Mask struct {
	Lo uint64
	Hi uint64
}

Mask is a 128 bit bitmask. It is also a Filter for including certain components (see All and Mask.Without).

func All

func All(ids ...ID) Mask

All creates a new Mask from a list of IDs.

If any ID is bigger or equal MaskTotalBits, it'll not be added to the mask.

func (*Mask) Contains

func (b *Mask) Contains(other Mask) bool

Contains reports if other mask is a subset of this mask.

func (*Mask) ContainsAny

func (b *Mask) ContainsAny(other Mask) bool

ContainsAny reports if any bit of other mask is in this mask.

func (*Mask) Get

func (b *Mask) Get(bit ID) bool

Get reports if bit index defined by ID is true or false.

The return will be always false for bit >= MaskTotalBits.

func (*Mask) IsZero

func (b *Mask) IsZero() bool

IsZero returns whether no bits are set in the bitmask.

func (Mask) Matches

func (b Mask) Matches(bits Mask) bool

Matches matches a filter against a bitmask.

func (*Mask) Reset

func (b *Mask) Reset()

Reset changes the state of all bits to false.

func (*Mask) Set

func (b *Mask) Set(bit ID, value bool)

Set sets the state of bit index to true or false.

This function has no effect for bit >= MaskTotalBits.

func (*Mask) TotalBitsSet

func (b *Mask) TotalBitsSet() int

TotalBitsSet returns how many bits are set in this mask.

func (Mask) Without

func (b Mask) Without(comps ...ID) MaskFilter

Without creates a MaskFilter which filters for including the mask's components, and excludes the components given as arguments.

type MaskFilter

type MaskFilter struct {
	Include Mask
	Exclude Mask
}

MaskFilter is a Filter for including and excluding certain components. See All and Mask.Without.

func (*MaskFilter) Matches

func (f *MaskFilter) Matches(bits Mask) bool

Matches matches a filter against a mask.

type Query

type Query struct {
	// contains filtered or unexported fields
}

Query is an iterator to iterate entities, filtered by a Filter.

Create queries through the World using World.Query.

See also the generic alternatives github.com/mlange-42/arche/generic.Query1, github.com/mlange-42/arche/generic.Query2, etc. For advanced filtering, see package github.com/mlange-42/arche/filter

func (*Query) Close

func (q *Query) Close()

Close closes the Query and unlocks the world.

Automatically called when iteration finishes. Needs to be called only if breaking out of the query iteration.

func (*Query) Entity

func (q *Query) Entity() Entity

Entity returns the Entity at the iterator's position

func (*Query) Get

func (q *Query) Get(comp ID) unsafe.Pointer

Get returns the pointer to the given component at the iterator's current Entity.

func (*Query) Has

func (q *Query) Has(comp ID) bool

Has returns whether the current Entity has the given component.

func (*Query) Mask

func (q *Query) Mask() Mask

Mask returns the archetype [BitMask] for the Entity at the iterator's current position.

Can be used for fast checks of the entity composition, e.g. using a Filter.

func (*Query) Next

func (q *Query) Next() bool

Next proceeds to the next Entity in the Query.

type World

type World struct {
	// contains filtered or unexported fields
}

World is the central type holding Entity and component data.

func NewWorld

func NewWorld(config ...Config) World

NewWorld creates a new World from an optional Config.

Uses the default Config if called without an argument. Accepts zero or one arguments.

func (*World) Add

func (w *World) Add(entity Entity, comps ...ID)

Add adds components to an Entity.

Panics when called with component that can't be added because they are already present. Panics when called on a locked world or for an already removed entity. Do not use during Query iteration!

See also the generic variants under github.com/mlange-42/arche/generic.Map1, etc.

func (*World) Alive

func (w *World) Alive(entity Entity) bool

Alive reports whether an entity is still alive.

func (*World) Assign

func (w *World) Assign(entity Entity, comps ...Component)

Assign assigns multiple components to an Entity, using pointers for the content.

The components in the `Comp` field of Component must be pointers. The passed pointers are no valid references to the assigned memory!

Panics when called with components that can't be added because they are already present. Panics when called on a locked world or for an already removed entity. Do not use during Query iteration!

See also the generic variants under github.com/mlange-42/arche/generic.Map1, etc.

func (*World) Exchange

func (w *World) Exchange(entity Entity, add []ID, rem []ID)

Exchange adds and removes components in one pass.

Panics when called with components that can't be added or removed because they are already present/not present, respectively. Panics when called on a locked world or for an already removed entity. Do not use during Query iteration!

See also the generic variants under github.com/mlange-42/arche/generic.Exchange.

func (*World) Get

func (w *World) Get(entity Entity, comp ID) unsafe.Pointer

Get returns a pointer th the given component of an Entity.

Returns `nil` if the entity has no such component. Panics when called for an already removed entity.

See also github.com/mlange-42/arche/generic.Map.Get for a generic variant.

func (*World) Has

func (w *World) Has(entity Entity, comp ID) bool

Has returns whether an Entity has a given component.

Panics when called for an already removed entity.

See also github.com/mlange-42/arche/generic.Map.Has for a generic variant.

func (*World) IsLocked

func (w *World) IsLocked() bool

IsLocked returns whether the world is locked by any queries.

func (*World) Mask

func (w *World) Mask(entity Entity) Mask

Mask returns the archetype [BitMask] for the given Entity.

Can be used for fast checks of the entity composition, e.g. using a Filter.

func (*World) NewEntity

func (w *World) NewEntity(comps ...ID) Entity

NewEntity returns a new or recycled Entity. The given component types are added to the entity.

Panics when called on a locked world. Do not use during Query iteration!

See also the generic variants under github.com/mlange-42/arche/generic.Map1, etc.

func (*World) NewEntityWith

func (w *World) NewEntityWith(comps ...Component) Entity

NewEntityWith returns a new or recycled Entity. The given component values are assigned to the entity.

The components in the `Comp` field of Component must be pointers. The passed pointers are no valid references to the assigned memory!

Panics when called on a locked world. Do not use during Query iteration!

See also the generic variants under github.com/mlange-42/arche/generic.Map1, etc.

func (*World) Query

func (w *World) Query(filter Filter) Query

Query creates a Query iterator.

The ecs core package provides only the filter All for querying the given components. Further, it can be chained with Mask.Without (see the examples) to exclude components.

Example:

query := world.Query(All(idA, idB).Without(idC))
for query.Next() {
    pos := (*position)(query.Get(posID))
    pos.X += 1.0
}

For type-safe generics queries, see package github.com/mlange-42/arche/generic. For advanced filtering, see package github.com/mlange-42/arche/filter.

Locks the world to prevent changes to component compositions.

func (*World) Remove

func (w *World) Remove(entity Entity, comps ...ID)

Remove removes components from an entity.

Panics when called with components that can't be removed because they are not present. Panics when called on a locked world or for an already removed entity. Do not use during Query iteration!

See also the generic variants under github.com/mlange-42/arche/generic.Map1, etc.

func (*World) RemoveEntity

func (w *World) RemoveEntity(entity Entity)

RemoveEntity removes and recycles an Entity.

Panics when called on a locked world or for an already removed entity. Do not use during Query iteration!

func (*World) Set

func (w *World) Set(entity Entity, id ID, comp interface{}) unsafe.Pointer

Set overwrites a component for an Entity, using a given pointer for the content.

The passed component must be a pointer. Returns a pointer to the assigned memory. The passed in pointer is not a valid reference to that memory!

Panics when called on a locked world or for an already removed entity. Do not use during Query iteration!

Panics if the entity does not have a component of that type.

See also github.com/mlange-42/arche/generic.Map.Set for a generic variant.

func (*World) SetListener

func (w *World) SetListener(listener func(e EntityEvent))

SetListener sets a listener callback func(e EntityEvent) for the world. The listener is immediately called on every ecs.Entity change. Replaces the current listener. Call with `nil` to remove a listener.

Events notified are entity creation, removal and changes to the component composition. Events are emitted immediately after the change is applied. Except for removal of an entity, where the event is emitted before removal. This allows for inspection of the to-be-removed Entity.

func (*World) Stats

func (w *World) Stats() *stats.WorldStats

Stats reports statistics for inspecting the World.