Arch 1.0.15

Arch

A C# based Archetype Entity Component System (ECS).

Each Archetype stores their entities within 16KB sized chunks perfectly fitting into L1 Caches for maximum iteration performance.
This technique has two main advantages, first of all it provides an great entity allocation speed and second it lowers the cache misses to the best possible minimum. Its incredible fast, especially for well architectured component structures and supports multithreading.

Supports .NetStandard 2.1, .Net Core 6 and 7.
Since .NetStandard is supported, you may also use it with Unity or Godot.

Download the package and get started today !

dotnet add PROJECT package Arch --version 1.0.15

Code Sample

Enough spoken, lets take a look at some code. Arch is bare minimum, easy to use and efficient. Lets say we want to create some game entities and make them move based on their velocity, sounds complicated ?

Its not ! Arch does everything for you, you only need to define the entities and the logic.

public class Game {

    public struct Position { public float x, y; }
    public struct Velocity { public float dx, dy; }
    
    // The entity structure and or filter/query
    public static Type[] archetype = { typeof(Position), typeof(Velocity) };
    
    public static void Main(string[] args) {
        
        var world = World.Create();
        var query = new QueryDescription{ All = archetype };  // Query all entities with Position AND Velocity components

        // Create entities
        for (var index = 0; index < 1000; index++) 
            var entity = world.Create(new Position{ x = 0, y = 0}, new Velocity{ dx = 1, dy = 1});
        
        // Query and modify entities 
        world.Query(in query, (ref Position pos, ref Velocity vel) => {
            pos.x += vel.dx;
            pos.y += vel.dy;
        });
    }
}

Contents

• Quickstart
  • ECS
  • World
  • Entity
  • Component
  • System aka. Query
  • Outlook
• Performance
  • Benchmark
• Contributing

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 to get something done.

For more detailed API and features, check out the wiki !

ECS

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.

World

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.

Entity

A entity represents your game entity.
It is a simple struct with some metadata acting as a key to acess and manage its components.

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 otherEntity = world.Create<Transform, Collider, PowerUp>(... optional);

or

var archetype = new []{ typeof(Position), typeof(Velocity), ... };
var entity = world.Create(archetype);

world.Destroy(in entity);

Component

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.
A small example could look like this...

var entity = world.Create<Position, 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. 

System aka. Query

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.

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 !

Outlook

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's features and performance techniques, check out the Wiki ! Theres more to explore, for example...

• Bulk Entity Adding
• Highperformance Queries
• Archetypes
• Chunks
• Parallel / Multithreaded Queries
• Enumerators
• More api

Performance

Well... its fast, like REALLY fast.
However the iteration speed depends, the less you query, the faster it is.
This rule targets the amount of queried components aswell as their size.

Based on https://github.com/Doraku/Ecs.CSharp.Benchmark - Benchmark, it is among the fastest ecs frameworks in terms of allocation and iteration.

Benchmark

The current Benchmark tested a bunch of different iterations and acess techniques. However the most interesting one is the QueryBenchmark. It tests world.Query against world.HPQuery and a world.Query(in desc, (in Entity) => { entity.Get<T>... } variant.

public struct Transform{ float x; float y; float z; }
public struct Velocity { float x; float y; }

The used structs are actually quite big, the smaller the components, the faster the query. However i wanted to create a realistic approach and therefore used a combination of Transform and Velocity.

Contributing

I will accept contributions, especially bugfixes, performance improvements and new features. New features however should not harm its performance, if they do they should be wrapped within predecessor variables for enabling/disabling them.