Examples using Friflo.Engine.ECS are part of the unit tests see: Tests/ECS/Examples
When testing the examples use a debugger to check entity state changes while stepping throw the code.
Examples showing typical use cases of the Entity API
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.
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.
publicstaticvoidCreateStore(){var store =newEntityStore();}
Entity
An Entity has an identity - Id - and acts as a container for components, tags, script and child entities.
Entities are related to a single EntityStore and created with CreateEntity().
publicstaticvoidCreateEntity(){var store =newEntityStore();store.CreateEntity();store.CreateEntity();foreach (var entity instore.Entities) {Console.WriteLine($"entity {entity}"); } // > entity id: 1 [] Info: [] entity has no components // > entity id: 2 []}
Entities can be deleted with 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.
Entities can be disabled.
Disabled entities are excluded from query results by default.
To include disabled entities in a query result use query.WithDisabled().
Components are structs 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.
[ComponentKey("my-component")]publicstructMyComponent:IComponent {publicint value;}publicstaticvoidAddComponents(){var store =newEntityStore();var entity =store.CreateEntity(); // add componentsentity.AddComponent(newEntityName("Hello World!"));// EntityName is build-inentity.AddComponent(newMyComponent { value =42 });Console.WriteLine($"entity: {entity}"); // > entity: id: 1 "Hello World!" [EntityName, Position] // get componentConsole.WriteLine($"name: {entity.Name.value}"); // > name: Hello World!var value =entity.GetComponent<MyComponent>().value;Console.WriteLine($"MyComponent: {value}"); // > MyComponent: 42 // Serialize entity to JSONConsole.WriteLine(entity.DebugJSON);}
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.
publicstaticvoidGetUniqueEntity(){var store =newEntityStore();store.CreateEntity(newUniqueEntity("Player")); // UniqueEntity is build-invar player =store.GetUniqueEntity("Player");Console.WriteLine($"entity: {player}"); // > entity: id: 1 [UniqueEntity]}
Tag
Tags are structs 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.
As described in the intro queries are a fundamental feature of an ECS.
Friflo.Engine.ECS support queries by any combination of component types and tags.
See ArchetypeQuery - API for available query filters to reduce the number of entities / components returned by a query.
ArchetypeQuery and all its generic variants returned by store.Query() are designed for reuse.
So their references can be stored and used when needed to avoid unnecessary allocations.
publicstaticvoidEntityQueries(){var store =newEntityStore();store.CreateEntity(newEntityName("entity-1"));store.CreateEntity(newEntityName("entity-2"),Tags.Get<MyTag1>());store.CreateEntity(newEntityName("entity-3"),Tags.Get<MyTag1,MyTag2>()); // --- query componentsvar queryNames =store.Query<EntityName>();queryNames.ForEachEntity((refEntityName name,Entity entity) => { // ... 3 matches }); // --- query components with tagsvar namesWithTags =store.Query<EntityName>().AllTags(Tags.Get<MyTag1,MyTag2>());namesWithTags.ForEachEntity((refEntityName name,Entity entity) => { // ... 1 match }); // --- use query.Entities in case an iteration requires no component accessforeach (var entity inqueryNames.Entities) { // ... 3 matches }}
Some optional filter snippets used to shrink the result set returned by a query.
.WithDisabled(); // query result contains also disabled entities .AllTags(Tags.Get<MyTag1>()); // query result contains only entities having all given tags .WithoutAnyTags(Tags.Get<MyTag1, MyTag2>()); // entities having any of the given tags are excluded from query result
.AllComponents(ComponentTypes.Get<Position>); // query result contains only entities having all given components
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.
The following comparison shows the difference in modeling types in ECS vs OOP.
ECS - Composition
OOP - 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 ECSstructDog:ITag { }structCat:ITag { }var store =newEntityStore();var dogType =store.GetArchetype(Tags.Get<Dog>());var catType =store.GetArchetype(Tags.Get<Cat>());WriteLine(dogType.Name); // [#Dog]dogType.CreateEntity();catType.CreateEntity();var dogs =store.Query().AnyTags(Tags.Get<Dog>());var all =store.Query().AnyTags(Tags.Get<Dog,Cat>());WriteLine($"dogs: {dogs.Count}"); // dogs: 1WriteLine($"all: {all.Count}"); // all: 2
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.
Script
Scripts are similar to components and can be added / removed to / from entities.
Scripts 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 Scripts are fine.
If dealing with a multiple of 10.000 components should be used for efficiency / performance.
A typical use case in Games 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 gest 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.
If changing an entity by adding or removing components, tags, scripts or child entities events are emitted.
An application can subscribe to these events like shown in the example.
Emitting these type of events increase code decoupling.
Without events these modifications need to be notified by direct method calls.
The build-in events can be subscribed on EntityStore and on Entity level like shown in the example below.
Signals are similar to events. They are used to send and receive custom events on entity level in an application.
They have the same characteristics as events described in the section above.
The use of Signal's is intended for scenarios when something happens occasionally.
This avoids the need to check a state every frame.
Note: JSON serialization is currently not support by Native AOT.
Using Friflo.Engine.ECS does not require a source generator - aka Roslyn Analyzer.
A source generator could be used to register component types automatically.
Because of this component types used by an application must be registered on startup as shown below.
var aot =newNativeAOT();aot.RegisterComponent<MyComponent>();aot.RegisterTag <MyTag1>();aot.RegisterScript <MyScript>();var schema =aot.CreateSchema();
In case using an unregistered component a TypeInitializationException will be thrown. E.g.
entity.AddComponent(newUnregisteredComponent());
On console to the exception log looks like
A type initializer threw an exception. To determine which type, inspect the InnerException's StackTrace property.
Stack Trace:
at System.Runtime.CompilerServices.ClassConstructorRunner.EnsureClassConstructorRun(StaticClassConstructionContext*) + 0x14f
at System.Runtime.CompilerServices.ClassConstructorRunner.CheckStaticClassConstructionReturnNonGCStaticBase(StaticClassConstructionContext*, IntPtr) + 0x1c
at Friflo.Engine.ECS.Entity.AddComponent[T](T&) + 0x4e
at MyApplication.UseUnregisteredComponent() + 0x7c
Unity update script
A query can be used within a MonoBehaviour script to update the position of moving objects.
Example for a move system in Unity.
publicclassMoveEntitySystem:MonoBehaviour{privateArchetypeQuery<Position> query;voidStart() {int entityCount =1_000;var store =newEntityStore(); // create entities with a Position componentfor (int n =0; n < entityCount; n++) {store.Batch() .Add(newPosition(n,0,0)) .CreateEntity(); } query =store.Query<Position>(); }voidUpdate() {foreach (var (positions, entities) inquery.Chunks) { // Update entity positions on each frameforeach (refvar position inpositions.Span) {position.y++; } } }}
Last updated
Screenshot: Entity state - enables browsing the entire store hierarchy.