-
-
Notifications
You must be signed in to change notification settings - Fork 100
Quickstart
I bet you dont wanna read tons of documentations, theory and other boring stuff right ?
Lets just ignore all that deep knowledge and jump in directly.
Entity Component System (ECS) is a software architectural pattern mostly used for the representation of game world objects or data oriented design in general. An ECS comprises entities composed from components of data, with systems or queries which operate on entities' components.
ECS follows the principle of composition over inheritance, meaning that every entity is defined not by a type hierarchy, but by the components that are associated with it.
The world acts as a management class for all its entities, it contains methods to create, destroy and query them and handles all the internal mechanics.
Therefore it is the most important class, you will use the world heavily.
Multiple worlds can be used in parallel, each instance and its entities are completly encapsulated from other worlds. Currently worlds and their content can not interact with each other, however this feature is already planned.
Worlds are created and destroyed like this...
var world = World.Create();
World.Destroy(world);There can be up to 255 worlds in total.
A entity represents your game entity.
It is a simple struct with some metadata acting as a key to acess and manage its components.
public readonly struct Entity : IEquatable<Entity> {
public readonly int EntityId; // Its id/key in the world
public readonly byte WorldId; // The world the entity lives in
public readonly ushort Version; // Its version, how often the entity or its id was recycled
....
}Entities are being created by a world and will "live" in the world in which they were created.
When an entity is being created, you need to specify the components it will have. Components are basically the additional data or structure the entity will have. This is called "Archetype".
var entity = world.Create(new Position(), new Velocity(),...);
or
var archetype = new []{ typeof(Position), typeof(Velocity), ... };
var entity = world.Create(archetype);
world.Destroy(in entity);Creating/Destroying entities should not happen during a Query or Iteration ! #17 will introduce this soon.
Components are data assigned to your entity. With them you define how an entity looks and behaves, they basically define the gamelogic with pure data.
Its recommended to use struct components since they offer better speed.
To ease writing code, you can acess the entity directly to modify its components or to check its metadata.
Lets take a look at the most important methods.
entity.IsAlive(); // True if the entity is still existing in its world
entity.Has<Position>(); // True if the entity has a position component
entity.Set(new Position( x = 10 )); // Replaces the position component and updates it data
entity.Get<Position>(); // Returns a reference to the entity position, can directly acess and update position attributes
entity.Add<Velocity>(new Velocity()); // Adds a velocity component to it and moves it to a different archetype.
entity.Remove<Velocity>(); // Removes the velocity component and moves it to a different archetype.
entity.GetComponentTypes(); // Returns an array of its component types. Should be treated as readonly
entity.GetComponents(); // Returns an array of all its components, allocates memory. With those utility methods you are able to implement your game logic.
A small example could look like this...
var entity = world.Create(new Position(), new Velocity());
ref var position = ref entity.Get<Position>(); // Get reference to the position
position.x++; // Update x
position.y++; // Update y
if(entity.Has<Position>()) // Make sure that entity has a position ( Optional )
entity.Set(new Position{ x = 10, y = 10 }; // Replaces the old position
entity.Remove<Velocity>(); // Removes an velocity component and moves it to a new archetype.
entity.Add<Velocity>(new Velocity{ x = 1, y = 1); // Adds an velocity component and moves the entity back to the previous archetype. Structural entity changes should not happen during a Query or Iteration ! #17 will introduce this soon.
Its important to mention that there generic overloads for each of the calls above, they are way more performant since they batch the operations.
entity.Add<T0...T9>();
entity.Remove<T0...T9>();
entity.Get<T0...T9>();
entity.Set<T0...T9>();
entity.Has<T0...T9>();Queries aka. Systems are used to iterate over a set of entities to apply logic and behaviour based on their components.
This is performed by using the world ( remember, it manages your created entities ) and by defining a description of which entities we want to iterate over.
// Define a description of which entities you want to query
var query = new QueryDescription {
All = new []{ typeof(Position), typeof(Velocity) }, // Should have all specified components
Any = new []{ typeof(Player), typeof(Projectile) }, // Should have any of those
None = new []{ typeof(AI) } // Should have none of those
};
// Execute the query
world.Query(in query, entity => { /* Do something */ });
// Execute the query and modify components in the same step, up to 10 generic components at the same time.
world.Query(in query, (ref Position pos, ref Velocity vel) => {
pos.x += vel.dx;
pos.y += vel.dy;
});In the example above we want to move our entities based on their Position and Velocity components.
To perform this operation we need to iterate over all entities having both a Position and Velocity component (All). We also want that our entity either is a Player or a Projectile (Any). However, we do not want to iterate and perform that calculation on entities which are controlled by an AI (None).
The world.Query method than smartly searches for entities having both a Position and Velocity, either a Player or Projectile and no AI component and executes the defined logic for all of those fitting entities.
Besides All, Any and None, QueryDescription can also target a exclusive set of components via Exclusive. If thats set, it will ignore All, Any and None and only target entities with a exactly defined set of components. Its also important to know that there are multiple different overloads to perform such a query.
The less you query in terms of components and the size of components... the faster the query is !
world.Query(in query); // Returns a query which can be iterated over manually
world.Query(in query, entity => {}); // Passes the fitting entity
world.Query(in query, (ref T1 t1, T2 t2, ...) => {}) // Passes the defined components of the fitting entity, up to 10 components
world.Query(in query, (in Entity en, ref T1 t1, ref T2 t2, ...) => {}) // Passed the fitting entity and its defined components, up to 10 components
var filteredEntities = new List<Entity>();
var filteredArchetypes = new List<Archetype>();
var filteredChunks = new List<Chunk>();
world.GetEntities(query, filteredEntities); // Fills all fitting entities into the passed list
world.GetArchetypes(query, filteredArchetypes); // Fills all fitting archetypes into the list
world.GetChunks(query, filteredChunks); // Fills all fitting chunks into the list Archetype's and Chunk's are internal structures of the world and store entities with the same component types. You will mostly never use them directly, therefore more on them later.
There several high performance enumerators which can be used to enumerate over various classes.
They might save you time and code.
foreach(ref var archetype in world){ /** LOGIC **/ }
foreach(ref var chunk in archetype){ /** LOGIC **/ }
foreach(ref var archetype in myQuery.GetArchetypeIterator()){ /** LOGIC **/ } // Automatically loops over all archetypes fitting the query.
foreach(ref var chunk in myQuery.GetChunkIterator()){ /** LOGIC **/ } // Automatically loops over all chunks fitting the query. If you do not want to use the high level queries you can make use of those enumerators. They are great to implement more lowlevel like iteration techniques over your entities and components.
var myQuery = world.Query(in desc);
foreach(ref var chunk in myQuery.GetChunkIterator()){
var chunkSize = chunk.Size; // How many entities are in the chunk, used for iteration
var transforms = chunk.GetArray<Transform>();
var velocity = chunk.GetArray<Velocity>();
...
}Entity creation, deletion and structural changes can not happen during a query or entity iteration. Otherwhise it would ruin the good performance, however theres still a way to do this, let me introduce you to "buffers".
There 4 buffers, each one specialised for a certain operation :
-
CreationBuffer- A buffer which records creation commands -
ModificationBuffer- A Buffer which records set operations -
StructuralBuffer- A buffer which records structural operations -
DestructionBuffer- A buffer which records destroy operations
Each one of them features several methods to record operations and must be playbacked to transfer the changes to the world. The best is... they are thread safe !
Lets take a look at a small example for entity creation via a buffer...
var group = new Type[]{ typeof(Explosion), typeof(Position) };
var creationBuffer = new CreationBuffer(world, 1024); <- Initial capacity, not total capacity
world.ParallelQuery(in desc, (in Entity en) => {
var entity = creationBuffer.Create(group); <- Record entity create operation
entity.Set<Explosion>(...); <- Set data...
entity.Set<Position>(...);
});
creationBuffer.Playback(); // Must happen after a queries on the mainthread. Lets say you wanna record entity destroy commands instead...
var buffer = DestructionBuffer(world);
world.Query(in _queryDescription, buffer.Destroy); // Short variant for (in Entity en) => { buffer.Destroy(en); }
buffer.Playback();You can also record structural operations like this...
var buffer = new StructuralBuffer(world);
world.ParallelQuery(in _queryDescription, (in Entity entity) => {
var addToEntity = buffer.BatchAdd(in entity); // BatchRemove() is for removing components...
buffer.Add<Ai>(in addToEntity);
buffer.Add<int>(in addToEntity);
});
buffer.Playback();And lastly you can also record normal .Set operations :)
var buffer = new ModificationBuffer(world);
world.ParallelQuery(in _queryDescription, (in Entity entity) => {
var bufferedEntity = buffer.Modify(in entity);
buffer.Set(in bufferedEntity, new Transform{ X = 20 });
buffer.Set(in bufferedEntity, new Rotation{ X = 20 });
});
buffer.Playback();Buffers are threadsafe and very fast, perfect for such scenarios. They can and should always be reused ! :)
This is all you need to know, with this little knowledge you are already able to bring your worlds to life.
However, if you want to take a closer look at Arch and performance techniques :