> For the complete documentation index, see [llms.txt](https://friflo.gitbook.io/friflo.engine.ecs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://friflo.gitbook.io/friflo.engine.ecs/documentation/entity.md). # Entity The `Entity` is the main data structure when working with an ECS. An `Entity` has a unique identity - `Id` - and acts as a container for components, tags, script and child entities.\ An `EntityStore` is a container of entities and used to create entities with `store.CreateEntity()`. ```csharp public static void CreateEntity() { var store = new EntityStore(); store.CreateEntity(); store.CreateEntity(); foreach (var entity in store.Entities) { Console.WriteLine($"entity {entity}"); } // > entity id: 1 [] Info: [] entity has no components // > entity id: 2 [] } ``` Entities can be deleted with `entity.DeleteEntity()`.\ Variables of type `Entity` mimic the behavior of reference types.\ Using an entity method on a deleted entity throws a `NullReferenceException`.\ To handled this case use `entity.IsNull`. ```csharp public static void DeleteEntity() { var store = new EntityStore(); var entity = store.CreateEntity(); entity.DeleteEntity(); var isDeleted = entity.IsNull; Console.WriteLine($"deleted: {isDeleted}"); // > deleted: True } ``` Entities can be disabled.\ Disabled entities are excluded from query results by default.\ To include disabled entities in a query result use `query.WithDisabled()`. ```csharp public static void DisableEntity() { var store = new EntityStore(); var entity = store.CreateEntity(); entity.Enabled = false; Console.WriteLine(entity); // > id: 1 [#Disabled] var query = store.Query(); Console.WriteLine($"default - {query}"); // > default - Query: [] Count: 0 var disabled = store.Query().WithDisabled(); Console.WriteLine($"disabled - {disabled}"); // > disabled - Query: [] Count: 1 } ``` Entity example code is part of the unit tests see: [Tests/ECS/Examples](https://github.com/friflo/Friflo.Engine.ECS/tree/main/src/Tests/ECS/Examples). When trying out the examples use a debugger to check entity state changes while stepping throw the code. \ *Screenshot:* Entity state - enables browsing the entire store hierarchy. Examples showing typical use cases of the [Entity API](https://github.com/friflo/Friflo.Engine-docs/blob/main/api/Entity.md) ### EntityStore An `EntityStore` is a container for entities running as an in-memory database.\ It is highly optimized for efficient storage fast queries and event handling.\ In other ECS implementations this type is typically called *World*. The store enables to * create entities * modify entities - add / remove components, tags, scripts and child entities * query entities with a specific set of components or tags * subscribe events like adding / removing components, tags, scripts and child entities Multiple stores can be used in parallel and act completely independent from each other.\ The example shows how to create a store. Mainly every example will start with this line. ```csharp public static void CreateStore() { var store = new EntityStore(); } ```
### Component `Components` are `struct`s used to store data on entities.\ Multiple components with different types can be added / removed to / from an entity.\ If adding a component using a type already stored in the entity its value gets updated. > **Limitation**\ > The number of component types is currently limited to 256. ```csharp [ComponentKey("my-component")] public struct MyComponent : IComponent { public int value; } public static void AddComponents() { var store = new EntityStore(); var entity = store.CreateEntity(); // add components entity.AddComponent(new EntityName("Hello World!"));// EntityName is build-in entity.AddComponent(new MyComponent { value = 42 }); Console.WriteLine($"entity: {entity}"); // > entity: id: 1 "Hello World!" [EntityName, Position] // get component Console.WriteLine($"name: {entity.Name.value}"); // > name: Hello World! var value = entity.GetComponent().value; Console.WriteLine($"MyComponent: {value}"); // > MyComponent: 42 // Serialize entity to JSON Console.WriteLine(entity.DebugJSON); } ``` Result of `entity.DebugJSON`: ```json { "id": 1, "components": { "name": {"value":"Hello World!"}, "my-component": {"value":42} } } ```
### Unique entity Add a `UniqueEntity` component to an entity to mark it as a *"singleton"* with a unique `string` id.\ The entity can than be retrieved with `EntityStore.GetUniqueEntity()` to reduce code coupling.\ It enables access to a unique entity without the need to pass an entity by external code. ```csharp public static void GetUniqueEntity() { var store = new EntityStore(); store.CreateEntity(new UniqueEntity("Player")); // UniqueEntity is build-in var player = store.GetUniqueEntity("Player"); Console.WriteLine($"entity: {player}"); // > entity: id: 1 [UniqueEntity] } ``` A more performant and type-safe approach to implement singletons in the ECS. ```cs enum SingletonType { Player }; // one enum value per singleton type struct SingletonComponent : IIndexedComponent { public SingletonType type; public SingletonType GetIndexedValue() => type; } public static void UseSingletonComponent() { var store = new EntityStore(); store.CreateEntity(new SingletonComponent{ type = SingletonType.Player} ); var index = store.ComponentIndex(); Entity entity = index[SingletonType.Player][0]; // get first entity var playerComponent = entity.GetComponent(); Console.WriteLine($"type: {playerComponent.type}"); // type: Player } ```
> **Info**\ > Since version 3.0.0 there is more flexible and performant alternative available by using a [Component Index](/friflo.engine.ecs/documentation/component-index.md).\ > It supports defining a custom `IIndexedComponent<>` type and have several advantages: > > * The unique key can be of any type - e.g. `int`, `Guid`, `enum`, `string`, ... . The key of unique entities is always a `string`. > * The storage of a **Component Index** is optimized for low memory footprint and fast lookup. > * Additional fields can be added to an `IIndexedComponent<>` type. ### Tag `Tags` are `struct`s similar to components - except they store no data.\ They can be utilized in queries similar as components to restrict the amount of entities returned by a query.\ If adding a tag using a type already attached to the entity the entity remains unchanged. > **Limitation**\ > The number of tag types is currently limited to 256. ```csharp public struct MyTag1 : ITag { } public struct MyTag2 : ITag { } public static void AddTags() { var store = new EntityStore(); var entity = store.CreateEntity(); // add tags entity.AddTag(); entity.AddTag(); Console.WriteLine($"entity: {entity}"); // > entity: id: 1 [#MyTag1, #MyTag2] // get tag var tag1 = entity.Tags.Has(); Console.WriteLine($"tag1: {tag1}"); // > tag1: True } ```
### Clone / Copy entity The methods `Entity.CloneEntity()` and `Entity.CopyEntity(Entity target)` are used to copy all components and tags from one entity to another. * `CloneEntity()` creates a new entity having the same components and tags as the original entity. * `CopyEntity(Entity target)` copy all components and tags to the given `target` entity.\ The target entity can be in the same or in a different store. The example creates a new entity with the same components and tags as the original entity. ```cs public static void CloneEntity() { var store = new EntityStore(); var entity = store.CreateEntity(new Position(1,2,3), Tags.Get()); var clone = entity.CloneEntity(); // the cloned entity have the same components and tags as the original entity. } ``` `CopyEntity(Entity target)` can be used to copy a subset or all entities of one store to another store.\ The entities in the target store will have the same entities ids as in the original store. ```cs public struct NetTag : ITag { } public static void CopyEntities() { var store = new EntityStore(); var targetStore = new EntityStore(); store.CreateEntity(new Position(1,1,1)); // 1 store.CreateEntity(new Position(2,2,2), Tags.Get()); // 2 store.CreateEntity(new Position(3,3,3)); // 3 store.CreateEntity(new Position(4,4,4), Tags.Get()); // 4 store.CreateEntity(new Position(5,5,5)); // 5 // Query will copy only entities [2, 4] having a NetTag var query = store.Query().AnyTags(Tags.Get()); foreach (var entity in query.Entities) { // preserve same entity ids in target store if (!targetStore.TryGetEntityById(entity.Id, out Entity targetEntity)) { targetEntity = targetStore.CreateEntity(entity.Id); } entity.CopyEntity(targetEntity); } // target store contains two entities [2, 4] with same components and tags as in the original store } ``` ### Script `Script`s are similar to components and can be added / removed to / from entities.\ `Script`s are classes and can also be used to store data.\ Additional to components they enable adding behavior in the common OOP style. In case dealing only with a few thousands of entities `Script`s are fine.\ If dealing with a multiple of 10.000 components should be used for efficiency / performance. ```csharp public class MyScript : Script { public int data; } public static void AddScript() { var store = new EntityStore(); var entity = store.CreateEntity(); // add script entity.AddScript(new MyScript{ data = 123 }); Console.WriteLine($"entity: {entity}"); // > entity: id: 1 [*MyScript] // get script var myScript = entity.GetScript(); Console.WriteLine($"data: {myScript.data}"); // > data: 123 } ``` `Script`s enable to `override` their `Start()` and `Update()`. ```cs public class MyScript : Script { public override void Start() { } public override void Update() { } } ``` These methods need to be called manually. The ECS has no build mechanism to execute these methods.\ The ECS provide only access to all scripts added to entities of an `EntityStore`.\ E.g. Executing `Update()` of all scripts in a store use: ```cs foreach (var scripts in store.EntityScripts) { foreach (var script in scripts) { script.Update(); } } ```
### Hierarchy A typical use case in an Game or Editor is to build up a hierarchy of entities.\ To add an entity as a child to another entity use `Entity.AddChild()`.\ In case the added child already has a parent it gets removed from the old parent.\ The children of the added (moved) entity remain being its children.\ If removing a child from its parent all its children are removed from the hierarchy. ```csharp public static void AddChildEntities() { var store = new EntityStore(); var root = store.CreateEntity(); var child1 = store.CreateEntity(); var child2 = store.CreateEntity(); // add child entities root.AddChild(child1); root.AddChild(child2); Console.WriteLine($"entities: {root.ChildEntities}"); // > entities: Count: 2 } ```
### Archetype An `Archetype` defines a specific set of components and tags for its entities.\ At the same time it is also a container of entities with exactly this combination of components and tags. > **Explanation**\ > An `Archetype` instance corresponds to an SQL `TABLE` where its components are the counterpart of the table rows.\ > In contrast to tables archetypes are created automatically on demand. A relational database requires to create tables upfront. The following comparison shows the difference in modeling types in **ECS** vs **OOP**.
ECS - CompositionOOP - Polymorphism
Inheritance
ECS does not utilize inheritance.
It prefers composition over inheritance.
Common OPP is based on inheritance.
Likely result: A god base class responsible for everything. 😊
Code coupling
Data lives in components - behavior in systems.
New behaviors does not affect existing code.
Data and behavior are both in classes.
New behaviors may add dependencies or side effects.
Storage
An Archetype is also a container of entities.
Organizing containers is part of application code.
Changing a type
Supported by adding/removing tags or components.
Type is fixed an cannot be changed.
Component access / visibility
Having a reference to an EntityStore enables
unrestricted reading and changing of components.
Is controlled by access modifiers:
public, protected, internal and private.
Example
// No base class Animal in ECS
struct Dog : ITag { }
struct Cat : ITag { }

var store = new EntityStore();

var dogType = store.GetArchetype(Tags.Get\());
var catType = store.GetArchetype(Tags.Get\());
WriteLine(dogType.Name);            // \[#Dog]

dogType.CreateEntity();
catType.CreateEntity();

var dogs = store.Query().AnyTags(Tags.Get\());
var all  = store.Query().AnyTags(Tags.Get\());

WriteLine($"dogs: {dogs.Count}");   // dogs: 1
WriteLine($"all: {all.Count}");     // all: 2 
class Animal { }
class Dog : Animal { }
class Cat : Animal { }

var animals = new List\();

var dogType = typeof(Dog);
var catType = typeof(Cat);
WriteLine(dogType.Name);            // Dog

animals.Add(new Dog());
animals.Add(new Cat());

var dogs = animals.Where(a => a is Dog);
var all  = animals.Where(a => a is Dog or Cat);

WriteLine($"dogs: {dogs.Count()}"); // dogs: 1
WriteLine($"all: {all.Count()}");   // all: 2
Performance
Runtime complexity O() of queries for specific types
O(size of result set)
O(size of all objects)
Memory layout
Continuous memory in heap - high hit rate of L1 cache.
Randomly placed in heap - high rate of L1 cache misses.
Instruction pipelining
Minimize conditional branches in update loops.
Process multiple components at once using SIMD.

Virtual method calls prevent branch prediction.

### JSON Serialization The entities stored in an EntityStore can be serialized as JSON using an [EntitySerializer](https://github.com/friflo/Friflo.Engine-docs/blob/main/api/EntitySerializer.md). > **Note**\ > Currently serialization / deserialization only support struct fields - properties not. See [Issue #28](https://github.com/friflo/Friflo.Engine.ECS/issues/28).\ > Component and relation types are required to be struct's. Writing the entities of a store to a JSON file is done with `WriteStore()`.\ Reading the entities of a JSON file into a store with `ReadIntoStore()`. Following attributes can be used to customize JSON serialization * `[ComponentKey("data")]` - the attributed component `struct` uses `"data"` as component key * `[Ignore]` - the attributed component field is ignored * `[Serialize("n")]` - the attributed component field uses `"n"` as JSON key ```csharp [ComponentKey("data")] // use "data" as component key in JSON struct DataComponent : IComponent { [Ignore] // field is ignored in JSON public int temp; [Serialize("n")] // use "n" as field key in JSON public string name; } public static void JsonSerialization() { var store = new EntityStore(); store.CreateEntity(new EntityName("hello JSON")); store.CreateEntity(new Position(1, 2, 3)); store.CreateEntity(new DataComponent{ temp = 42, name = "foo" }); // --- Write store entities as JSON array var serializer = new EntitySerializer(); var writeStream = new FileStream("entity-store.json", FileMode.Create); serializer.WriteStore(store, writeStream); writeStream.Close(); // --- Read JSON array into new store var targetStore = new EntityStore(); serializer.ReadIntoStore(targetStore, new FileStream("entity-store.json", FileMode.Open)); Console.WriteLine($"entities: {targetStore.Count}"); // > entities: 3 } ``` The JSON content of the file `"entity-store.json"` created with `serializer.WriteStore()` ```json [{ "id": 1, "components": { "name": {"value":"hello JSON"} } },{ "id": 2, "components": { "pos": {"x":1,"y":2,"z":3} } },{ "id": 3, "components": { "data": {"n":"foo"} } }] ```