donburi

README

Donburi

Donburi is just another Entity Component System library for Ebiten inspired by legion.

It aims to be a feature rich and high performance ECS Library.

Contents

• Features
• Examples
• Installation
• Getting Started
  • Worlds
  • Queries
  • Tags
  • Systems
• Internal Architecture
• How to contribute?
• Contributors

Features

• It introduces the concept of Archetype, which allows us to query entities very efficiently based on the components layout.
• It is possible to combine And, Or, and Not conditions to perform complex queries for components.
• It avoids reflection on every frame and uses unsafe.Pointer for performance.
• Ability to dynamically add or remove components from an entity.

There are many features that need to be added in the future (e.g., parent-child relationship, event-notification system etc).

Examples

To check all examples, visit this page.

The bunnymark example was adapted from mizu's code, which is made by sedyh.

Installation

go get github.com/yohamta/donburi

Getting Started

Worlds

import "github.com/yohamta/donburi"

world := donburi.NewWorld()

Entities can be created via either Create (for a single entity) or CreateMany (for a collection of entities with the same component types). The world will create a unique ID for each entity upon insertion that you can use to refer to that entity later.

// Component is any struct that holds some kind of data.
type PositionData struct {
  X, Y float64
}

type VelocityData struct {
  X, Y float64
}

// ComponentType represents kind of component which is used to create or query entities.
var Position = donburi.NewComponentType(PositionData{})
var Velocity = donburi.NewComponentType(VelocityData{})

// Create an entity by specifying components that the entity will have.
// Component data will be initialized by default value of the struct.
entity = world.Create(Position, Velocity);

// You can use entity (it's a wrapper of int64) to get an Entry object from World
// which allows you to access the components that belong to the entity.
entry := world.Entry(entity)

position := (*PositionData)(entry.Component(Position))
velocity := (*VelocityData)(entry.Component(Velocity))
position.X += velocity.X
position.Y += velocity.y

We can define helper functions to get components for better readability. This was advice from eliasdaler.

func GetPosition(entry *donburi.Entry) *PositionData {
  return (*PositionData)(entry.Component(Position))
}

func GetVelocity(entry *donburi.Entry) *VelocityData {
  return (*VelocityData)(entry.Component(Velocity))
}

Components can be added and removed through Entry objects.

// Fetch the first entity with PlayerTag component
query := query.NewQuery(filter.Contains(PlayerTag))
// Query.FirstEntity() returns only the first entity that 
// matches the query.
if entry, ok := query.FirstEntity(world); ok {
  entry.AddComponent(Position)
  entry.RemoveComponent(Velocity)
}

Entities can be removed from World with the World.Remove() as follows:

if SomeLogic.IsDead(world, someEntity) {
  // World.Remove() removes the entity from the world.
  world.Remove(someEntity)
  // Deleted entities become invalid immediately.
  if world.Valid(someEntity) == false {
    println("this entity is invalid")
  }
}

Queries

Queries allow for high performance and expressive iteration through the entities in a world, to get component references, or to add and remove components.

You can search for entities that have all of a set of components.

// You can define a query by declaring what componet you want to find.
query := query.NewQuery(filter.Contains(Position, Velocity))

// You can then iterate through the entity found in the world
query.EachEntity(world, func(entry *donburi.Entry) {
  // An entry is an accessor to entity and its components.
  var position *PositionData = (*PositionData)(entry.Component(Position))
  var velocity *VelocityData = (*VelocityData)(entry.Component(Velocity))
  
  position.X += velocity.X
  position.Y += velocity.Y
})

There are other types of filters such as And, Or, Exact and Not. You can combine them to find the target entities.

For example:

// This query retrieves entities that have an NpcTag and no Position component.
query := query.NewQuery(filter.And(
  filter.Contains(NpcTag),
  filter.Not(filter.Contains(Position))))

Tags

You can attach one or multiple "Tag" components to an entity. "Tag"s are just components with no data.

Here is the utility function to create a tag component.

// This is the utility function to make tag component
func NewTag() *ComponentType {
  return NewComponentType(struct{}{})
}

Since "Tags" are components, they can be used in queries in the same way as components as follows:

var EnemyTag = donburi.NewTag()
world.CreateMany(100, EnemyTag, Position, Velocity)

// Search entities with EnemyTag
query := query.NewQuery(filter.Contains(EnemyTag))
query.EachEntity(world, func(entry *donburi.Entry) {
  // Perform some operation on the Entities with the EnemyTag component.
}

Systems

As of today, there is no function for the concept of "Systems" in ECS. It is assumed that operations are performed on entities using queries.

Internal Architecture

The internal architecture is a bit complex, so please refer to the following diagram to understand it.

How to contribute?

Feel free to contribute in any way you want. Share ideas, questions, submit issues, and create pull requests. Thanks!

Contributors

Made with contrib.rocks.

Documentation

Index

• Variables
• type ComponentType
  • func NewTag() *ComponentType
• type Entity
• type Entry
  • func (e *Entry) AddComponent(ctype *component.ComponentType, components ...unsafe.Pointer)
  • func (e *Entry) Archetype() *storage.Archetype
  • func (e *Entry) Component(ctype *component.ComponentType) unsafe.Pointer
  • func (e *Entry) Entity() Entity
  • func (e *Entry) Id() entity.EntityId
  • func (e *Entry) RemoveComponent(ctype *component.ComponentType)
  • func (e *Entry) SetComponent(ctype *component.ComponentType, component unsafe.Pointer)
• type StorageAccessor
• type World
  • func NewWorld() World
• type WorldId

Variables

var NewComponentType = component.NewComponentType

NewComponentType creates a new component type. The function is used to create a new component of the type. It receives a function that returns a pointer to a new component.

var Null = entity.Null

Null represents a invalid entity which is zero.

Types

type ComponentType

type ComponentType = component.ComponentType

ComponentType represents a component type. It is used to add components to entities, and to filter entities based on their components. It contains a function that returns a pointer to a new component.

func NewTag

func NewTag() *ComponentType

NewTag is an utility to create a tag component. Which is just an component that contains no data.

type Entity

type Entity = entity.Entity

Entity is identifier of an entity. Entity is just a wrapper of uint64.

type Entry

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

Entry is a struct that contains an entity and a location in an archetype.

func (*Entry) AddComponent

func (e *Entry) AddComponent(ctype *component.ComponentType, components ...unsafe.Pointer)

AddComponent adds the component to the entity.

func (*Entry) Archetype

func (e *Entry) Archetype() *storage.Archetype

Archetype returns the archetype.

func (*Entry) Component

func (e *Entry) Component(ctype *component.ComponentType) unsafe.Pointer

Component returns the component.

func (*Entry) Entity

func (e *Entry) Entity() Entity

Entity returns the entity.

func (*Entry) Id

func (e *Entry) Id() entity.EntityId

Id returns the entity id.

func (*Entry) RemoveComponent

func (e *Entry) RemoveComponent(ctype *component.ComponentType)

RemoveComponent removes the component from the entity.

func (*Entry) SetComponent

func (e *Entry) SetComponent(ctype *component.ComponentType, component unsafe.Pointer)

SetComponent sets the component.

type StorageAccessor

type StorageAccessor struct {
	// Index is the search index for the world.
	Index *storage.SearchIndex
	// Components is the component storage for the world.
	Components *storage.Components
	// Archetypes is the archetype storage for the world.
	Archetypes []*storage.Archetype
}

StorageAccessor is an accessor for the world's storage.

type World

type World interface {
	// Id returns the unique identifier for the world.
	Id() WorldId
	// Create creates a new entity with the specified components.
	Create(components ...*component.ComponentType) Entity
	// CreateMany creates a new entity with the specified components.
	CreateMany(n int, components ...*component.ComponentType) []Entity
	// Entry returns an entry for the specified entity.
	Entry(entity Entity) *Entry
	// Remove removes the specified entity.
	Remove(entity Entity)
	// Valid returns true if the specified entity is valid.
	Valid(e Entity) bool
	// Len returns the number of entities in the world.
	Len() int
	// StorageAccessor returns an accessor for the world's storage.
	// It is used to access components and archetypes by queries.
	StorageAccessor() StorageAccessor
}

World is a collection of entities and components.

func NewWorld

func NewWorld() World

NewWorld creates a new world.

type WorldId

type WorldId int

WorldId is a unique identifier for a world.