Overview

Entitas is fast, light and gets rid of unnecessary complexity. There are less than a handful classes you have to know to rocket start your game or application:

Entity
Pool
Group
Entity Collector

+------------------+
|       Pool       |
|------------------|
|    e       e     |      +-----------+
|        e     e---|----> |  Entity   |
|  e        e      |      |-----------|
|     e  e       e |      | Component |
| e            e   |      |           |      +-----------+
|    e     e       |      | Component-|----> | Component |
|  e    e     e    |      |           |      |-----------|
|    e      e    e |      | Component |      |   Data    |
+------------------+      +-----------+      +-----------+
  |
  |
  |     +-------------+  Groups:
  |     |      e      |  Subsets of entities in the pool
  |     |   e     e   |  for blazing fast querying
  +---> |        +------------+
        |     e  |    |       |
        |  e     | e  |  e    |
        +--------|----+    e  |
                 |     e      |
                 |  e     e   |
                 +------------+

Entity

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;

Pool

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 generator
var 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
}

Group

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 groups 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 Entity Collector.

Entity Collector

The Entity Collector 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 collector = group.CreateCollector(GroupEventType.OnEntityAdded);

Later

foreach (var e in collector.collectedEntities) {
    // do something with all the entities
    // that have been collected to this point of time
}
collector.ClearCollectedEntities();