Entitas

m

Example

Usage

Unity

Examples

2dPlatformer

Generated

ComponentIds.cs

...bunch of other files...don't care

Overview

Entitas

// Contains the complete ECS, basically everything you need to get started

Pool

r

The Pool is the factory where you create and destroy entities. Use it to filter entities of interest.// Pools.pool is kindly generated for you by the code generatorvar pool = Pools.pool;var entity = pool.CreateEntity();entity.isMovable = true;// Returns all entities having MovableComponent and PositionComponent.// Matchers are also generated for you.var entities = pool.GetEntities(Matcher.AllOf(Matcher.Movable, Matcher.Position));foreach (var e in entities) { // do something}

//The Pool is the factory where you create and destroy entities. Use it to filter entities of interest.

(diagram)

(text)

(pic)

Entity

r

An entity is a container holding data to represent certain objects in your application. You can add, replace or remove data from entities in form of IComponent. Entities have corresponding events to let you know if components were added, replaced or removed.Here's how you can interact with an entity. To enjoy a more natural and more readable API, simply use the code generator that comes with Entitas. In this example you can see some generated methods for PositionComponent, HealthComponent, MovableComponent.entity.AddPosition(3, 7);entity.AddHealth(100);entity.isMovable = true;entity.ReplacePosition(10, 100);entity.ReplaceHealth(entity.health.value - 1);entity.isMovable = false;entity.RemovePosition();var hasPos = entity.hasPosition;var movable = entity.isMovable;

//Entities have corresponding events to let you know if components were added, replaced or removed

(composition)

Component (transtform)

Component (id)

Groups

r

Groups enable super quick filtering on entities in the pool. They are continuously updated when entities change and can return groups of entities instantly. Imagine you have thousands of entities and you only want those who have a PositionComponent - just ask the pool for this group, it already has the result waiting for you in no time.pool.GetGroup(Matcher.Position).GetEntities();Both the group and getting the entities is cached, so even calling this method multiple times is super fast. Always try to use goups when possible. pool.GetEntities(Matcher.Movable) internally uses groups, too.Groups have events for OnEntityAdded, OnEntityRemoved and OnEntityUpdated to directly react to changes in the group.pool.GetGroup(Matcher.Position).OnEntityAdded += (group, entity, index, component) => { // Do something};If you want to aggregate and process changes, consider using a Group Observer.

//Subsets of entities in the pool blazing fast querying

//They are continuously updated when entities change and can return groups of entities instantly

(react to changes in the group)

OnEntityAdded

pool.GetGroup(Matcher.Position).OnEntityAdded += (group, entity, index, component) => {
// Do something
};

OnEntityRemoved

OnEntityUpdated

Group Observer

r

The Group Observer provides an easy way to react to changes in a group over time. Let's say you want to collect and process all the entities where a PositionComponent was added or replaced.var group = pool.GetGroup(Matcher.Position);var observer = group.CreateObserver(GroupEventType.OnEntityAdded);foreach (var e in observer.collectedEntities) { // do something}observer.ClearCollectedEntities();To stop observing, simply deactivate the observer.observer.Deactivate();

//The Group Observer provides an easy way to react to changes in a group over time

(Collect and process all the entities where a PositionComponent was added or replaced)

var group = pool.GetGroup(Matcher.Position);

var observer = group.CreateObserver(GroupEventType.OnEntityAdded);

foreach (var e in observer.collectedEntities) { ... }

// do something

observer.ClearCollectedEntities();

// why do I need to do this

??? release memory ???

// To stop observing

observer.Deactivate();

(events)

public

event

GroupChanged

OnEntityAdded

/// Occurs when an entity gets added.

OnEntityRemoved

/// Occurs when an entity gets removed.

OnEntityUpdated

/// Occurs when a component of an entity in the group gets replaced.

// need example

delegate

void

GroupChanged(Group group, Entity entity, int index, IComponent component);

GroupUpdated(Group group, Entity entity, int index, IComponent previousComponent, IComponent newComponent);

Systems

//Create systems for each single task or behaviour in your application and execute them in a defined order

//This helps to keep your app deterministic.

(execute from set pool)

public class MoveSystem : IExecuteSystem, ISetPool { ... }

(var)

Group

_group;

(func)

public

void

SetPool(Pool pool) { ... }

_group = pool.GetGroup(Matcher.AllOf(Matcher.Move, Matcher.Position));

Execute() { ... }

foreach (var e in _group.GetEntities()) { ... }

var move = e.move;

var pos = e.position;

e.ReplacePosition(pos.x, pos.y + move.speed, pos.z);

(reactive to pool change)

public class RenderPositionSystem : IReactiveSystem { ... }

(var)

public

TriggerOnEvent

trigger { ... }

get { ... }

return Matcher.AllOf(Matcher.Position, Matcher.View).OnEntityAdded();

(func)

public

void

Execute(List<Entity> entities) { ... }

foreach (var e in entities) { ... }

var pos = e.position;

e.view.gameObject.transform.DOMove(new Vector3(pos.x, pos.y, 0f), 0.3f);

namespace Entitas { ... }

(type)

public

(example)

public class ProcessInputSystem : IReactiveSystem, ISetPool { ... }

(IReactiveSystem)

(ISetPool)

Matcher

IMatcher

AbstractMatcher.cs

AllOfMatcher.cs

TriggerOnEvent.cs

public

struct

TriggerOnEvent { ... }

(var)

public

IMatcher

trigger;

GroupEventType

eventType;

(func)

(constructor)

TriggerOnEvent(IMatcher trigger, GroupEventType eventType) { ... }

this.trigger = trigger;

this.eventType = eventType;

Module

(Unity)

Entitas.Unity

// Contains the plugin based Entitas preferences panel for Unity

Entitas.Unity.CodeGenerator

// Plugs into the Entitas preferences panel and adds convenient menu items

Entitas.Unity.VisualDebugging

// Integrates Entitas into Unity. Inspect pools, entities, components and systems

(Optional)

Entitas.CodeGenerator

App

Unity

Sources