ecs

README

ecs

This is our implementation of the "Entity Component System" model in Go. It was designed to be used in engo, however it is not dependent on any other packages so is able to be used wherever!

Basics

In the Entity Component System paradigm, you have three elements;

• Entities
• Components
• Systems.

In our implementation, we use the type World to work with those Systems. Each System can have references to any number (including 0) of entities. And each Entity can have as many Components as desired.

An example of creating a World, adding a System to it, and update all systems

// Declare the world - you can also use "var world ecs.World" 
world := ecs.World{}

// You can add as many Systems here as you like. The RenderSystem provided by `engo` is just an example. 
world.AddSystem(&engo.RenderSystem{})

// This will usually be called within the game-loop, in order to update all Systems on every frame.  
world.Update(0.125) // 0.125 would be the time in seconds since the last update

System

We've been talking about Systems, but what are they? Anything that implements the interface, can be used as a System:

type System interface {
	// Update is ran every frame, with `dt` being the time in seconds since the last frame
	Update(dt float32)

	// Delete should remove the entity from the system completely
	Remove(e BasicEntity)
}

What does this say? It needs to have an Update method (which is called from world.Update), and it needs to have a Remove(ecs.BasicEntity) method. Why require a Remove method, but not an Add method? Because there's no 'generic' Add method (the parameters may change), while in order to remove something, all you need it the unique identifier (as provided by the BasicEntity).

Initialization

Optionally, your System may implement the Initializer interface, which allows you to do initialization for the given World. Basically, it allows you to initialize values, without having to call the function manually before adding it to the World. Whenever you add a System (one that implements the Initializer interface) to the world, the New method will be called.

type Initializer interface {
	// New is the initialisation of the System, and may be used to initialize some values beforehand, like storing
	// a reference to the World
	New(*World)
}

Priority

Optionally, your System may implement the Prioritizer interface, which allows the World to sort the Systems based on that priority. If omitted, a value of 0 is assumed.

type Prioritizer interface {
	// Priority indicates the order in which Systems should be executed per iteration, higher meaning sooner. Default is 0
	Priority() int
}

Entities and Components

Where do the entities come in? All game-logic has to be done within Systems (the Update method, to be precise)). Components store data (which is used by those Systems). An Entity is no more than a wrapper which combines multiple Components and adds a unique identifier to the whole. This unique identifier is nothing magic: simply an incrementing integer value - nothing to worry about.

Because the precise definition of those Components can vary, this ecs package provides no Components -- we only provide examples here. The engo.io/engo/common package offers lots of Components and Systems to work with, out of the box.

Let's view an example:

type SpaceComponent struct {
    Width  float32
    Height float32
}

type HealthComponent struct {
    HealthPercentage float32
    ManaPercentage   float32
}

type Player struct {
    ecs.BasicEntity
    SpaceComponent
    HealthComponent
}

Here, the type Player is made out of three elements: the unique identifier (ecs.BasicEntity) and two Components. A System may make use of one or more of those Components. Which are required, is defined by the Add method on that System.

Let's view a few examples:

func (MySystem1) Add(basic *ecs.BasicEntity, space *SpaceComponent) { /* ... */ }

func (MySystem2) Add(basic *ecs.BasicEntity, health *HealthComponent) { /* ... */ }

func (MySystem3) Add(basic *ecs.BasicEntity, space *SpaceComponent, health *HealthComponent) { /* ... */ }

These three different Add methods are all valid, and use different Components. But how can I add my Entity to the System, if I didn't save a reference to that System?

// Initialize our custom Entity
// NOTE: we have to call `ecs.NewBasic` here, to give our Entity a new unique identifier
player := Player{BasicEntity: ecs.NewBasic()}

// Loop over all Systems
for _, system := range world.Systems() {

    // Use a type-switch to figure out which System is which
    switch sys := system.(type) {
    
        // Create a case for each System you want to use
        case *MySystem1:
            sys.Add(&player.BasicEntity, &player.SpaceComponent)
        case *MySystem3:
            sys.Add(&player.BasicEntity, &player.SpaceComponent, &player.Healthcomponent)
    }
}

That is all there is to it.

Custom Systems - How to save Entities?

You more than likely will want to create Systems yourself. We will now go in depth on what you should do when defining your own Add method for your System. As seen above, you can create any number (and type of) parameters you want.

We do ask you to let the first argument be of type *ecs.BasicEntity - as a general rule.

Your System should include an array, slice or map in which to store those entities. Now it is important to note that you're not receiving entities per se -- you are receiving references to the Components you need. The actual Entity (type Player in our example) may contain way more Components. You will most-likely want to create a struct for you to store those pointers in. An example:

type myAWesomeEntity struct {
    *ecs.BasicEntity
    *SpaceComponent
}

type MyAwesomeSystem struct {
    entities []myAwesomeEntity
}

func (m *MyAesomeSystem) Add(basic *ecs.BasicEntity, space *SpaceComponent) {
    m.entities = append(m.entities, myAwesomeEntity{basic, space})
}

NOTE

As a convention, please include "System" in the name of your System -- at the end. When you define a struct (which contains pointers, as opposed to the Player struct we created earlier), please replace that System part with Entity. You should only use this newly-created struct in your similarly-named System. You will usually never want to export that Entity definition, as it is only being used in that System. If your system would be called BallMovementSystem, then your struct would be called ballMovementEntity.

Removing Entities from your System

Your System must implement the Remove method as specified by the System interface. Whenever you start storing entities, you should define this method in such a way, that it removes the custom-created non-exported Entity-struct from the array, slice or map. An ecs.BasicEntity is given for you to figure out which element in the array, slice or map it is.

// Remove removes the Entity from the System. This is what most Remove methods will look like
func (m *MyAwesomeSystem) Remove(basic ecs.BasicEntity) {
  	var delete int = -1
  	for index, entity := range m.entities {
    		if entity.ID() == basic.ID() {
    			delete = index
    			break
  		  } 
  	}
  	if delete >= 0 {
    		m.entities = append(m.entities[:delete], m.entities[delete+1:]...)
  	}
}

// OR, if you were using a `map` instead of a `slice`:

// Remove removes the Entity from the System. As you see, removing becomes easier when using a `map`. 
func (m *MyAwesomeSystem) Remove(basic ecs.BasicEntity) {
  	delete(m.entities, basic.ID())
}
//

NOTE

Even though that a map looks easier, if you want to loop over that map each frame, writing those additional lines to use a slice instead, is definitely worth it in terms of runtime performance. Iterating over a map is a lot slower.

Custom Systems - The Update method

Whatever your System does on the Update method, is up to you. Each System is unique in that sense. If you're storing entities, then you might want to loop over them each frame. Again, this depends on your use-case.

func (m *MyAwesomeSystem) Update(dt float32) {
    for _, entity := range m.entities {
        fmt.Println("I would like to tell you", entity.ID(), "that it has been", dt, "seconds since the last time we spoke. ")
    }
}

Documentation

Overview

Package ecs provides interfaces for the Entity Component System (ECS) paradigm used by engo.io/engo. It is predominately used by games, however will find use in other applications.

The ECS paradigm aims to decouple distinct domains (e.g. rendering, input handling, AI) from one another, through a composition of independent components. The core concepts of ECS are described below.

Entities

An entity is simply a set of components with a unique ID attached to it, nothing more. In particular, an entity has no logic attached to it and stores no data explicitly (except for the ID).

Each entity corresponds to a specific entity within the game, such as a character, an item, or a spell.

Components

A component stores the raw data related to a specific aspect of an entity, nothing more. In particular, a component has no logic attached to it.

Different aspects may include the position, animation graphics, or input actions of an entity.

Systems

A system implements logic for processing entities possessing components of the same aspects as the system.

For instance, an animation system may render entities possessing animation components.

Index

• type BasicEntity
  • func NewBasic() BasicEntity
  • func NewBasics(amount int) []BasicEntity
  • func (e *BasicEntity) GetBasicEntity() *BasicEntity
  • func (e BasicEntity) ID() uint64
• type Identifier
• type IdentifierSlice
  • func (is IdentifierSlice) Len() int
  • func (is IdentifierSlice) Less(i, j int) bool
  • func (is IdentifierSlice) Swap(i, j int)
• type Initializer
• type Prioritizer
• type System
• type World
  • func (w *World) AddSystem(system System)
  • func (w *World) RemoveEntity(e BasicEntity)
  • func (w *World) Systems() []System
  • func (w *World) Update(dt float32)

Types

type BasicEntity

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

A BasicEntity is simply a set of components with a unique ID attached to it, nothing more. It belongs to any amount of Systems, and has a number of Components

func NewBasic

func NewBasic() BasicEntity

NewBasic creates a new Entity with a new unique identifier. It is safe for concurrent use.

func NewBasics

func NewBasics(amount int) []BasicEntity

NewBasics creates an amount of new entities with a new unique identifiers. It is safe for concurrent use, and performs better than NewBasic for large numbers of entities.

func (*BasicEntity) GetBasicEntity

func (e *BasicEntity) GetBasicEntity() *BasicEntity

GetBasicEntity returns a Pointer to the BasicEntity itself By having this method, All Entities containing a BasicEntity now automatically have a GetBasicEntity Method This allows system.Add functions to recieve a single interface EG: s.AddByInterface(a interface{GetBasicEntity()*BasicEntity, GetSpaceComponent()*SpaceComponent){ s.Add(a.GetBasicEntity(),a.GetSpaceComponent()) }

func (BasicEntity) ID

func (e BasicEntity) ID() uint64

ID returns the unique identifier of the entity.

type Identifier

type Identifier interface {
	ID() uint64
}

Identifier is an interface for anything that implements the basic ID() uint64, as the BasicEntity does. It is useful as more specific interface for an entity registry than just the interface{} interface

type IdentifierSlice

type IdentifierSlice []Identifier

IdentifierSlice implements the sort.Interface, so you can use the store entites in slices, and use the P=n*log n lookup for them

func (IdentifierSlice) Len

func (is IdentifierSlice) Len() int

Len returns the length of the underlying slice part of the sort.Interface

func (IdentifierSlice) Less

func (is IdentifierSlice) Less(i, j int) bool

Less will return true if the ID of element at i is less than j; part of the sort.Interface

func (IdentifierSlice) Swap

func (is IdentifierSlice) Swap(i, j int)

Swap the elements at positions i and j part of the sort.Interface

type Initializer

type Initializer interface {
	// New initializes the given System, and may be used to initialize some
	// values beforehand, like storing a reference to the World.
	New(*World)
}

Initializer provides initialization of systems.

type Prioritizer

type Prioritizer interface {
	// Priority indicates the order in which Systems should be executed per
	// iteration, higher meaning sooner. The default priority is 0.
	Priority() int
}

Prioritizer specifies the priority of systems.

type System

type System interface {
	// Update updates the system. It is invoked by the engine once every frame,
	// with dt being the duration since the previous update.
	Update(dt float32)

	// Remove removes the given entity from the system.
	Remove(e BasicEntity)
}

A System implements logic for processing entities possessing components of the same aspects as the system. A System should iterate over its Entities on `Update`, in any way suitable for the current implementation.

By convention, systems provide an Add method for adding entities and their associated components to the system; e.g.

Add(basic *ecs.BasicEntity, collision *CollisionComponent, space *SpaceComponent)

type World

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

World contains a bunch of Entities, and a bunch of Systems. It is the recommended way to run ecs.

func (*World) AddSystem

func (w *World) AddSystem(system System)

AddSystem adds the given System to the World, sorted by priority.

func (*World) RemoveEntity

func (w *World) RemoveEntity(e BasicEntity)

RemoveEntity removes the entity across all systems.

func (*World) Systems

func (w *World) Systems() []System

Systems returns the list of Systems managed by the World.

func (*World) Update

func (w *World) Update(dt float32)

Update updates each System managed by the World. It is invoked by the engine once every frame, with dt being the duration since the previous update.