Arch 1.2.3

Arch

A high-performance C# based Archetype & Chunks Entity Component System (ECS) for game development and data-oriented programming.

• 🚀 FAST > Best cache efficiency, iteration, and allocation speed. Plays in the same league as C++/Rust ECS Libs!
• 🚀🚀 FASTER > Arch is on average quite faster than other ECS implemented in C#. Check out this Benchmark!
• 🤏 BARE MINIMUM > Not bloated, it's small and only provides the essentials for you!
• ☕️ SIMPLE > Promotes a clean, minimal, and self-explanatory API that is simple by design. Check out the Wiki!
• 💪 MAINTAINED > It's actively being worked on, maintained, and supported!
• 🚢 SUPPORT > Supports .NetStandard 2.1, .Net Core 6 and 7 and therefore you may use it with Unity or Godot!

Download the package and get started today!

dotnet add PROJECT package Arch --version 1.2.0

Code Sample

Arch is bare minimum, easy to use, and efficient. Let's say you want to create some game entities and make them move based on their velocity... sounds complicated? It's not! Arch does everything for you, you only need to define the entities and the logic.

// Components ( ignore the formatting, this saves space )
public struct Position{ float X, Y };
public struct Velocity{ float Dx, Dy };

public class Game 
{
    public static void Main(string[] args) 
    {     
        // Create a world and entities with position and velocity.
        var world = World.Create();
        for (var index = 0; index < 1000; index++) 
            world.Create(new Position{ X = 0, Y = 0}, new Velocity{ Dx = 1, Dy = 1});
        
        // Query and modify entities ( There are also alternatives without lambdas ;) ) 
        var query = new QueryDescription().WithAll<Position,Velocity>(); // Targets entities with Position AND Velocity.
        world.Query(in query, (ref Position pos, ref Velocity vel) => {
            pos.X += vel.Dx;
            pos.Y += vel.Dy;
        });
    }
}

Contents

• Quick start
  • ECS
  • World
  • Entity
  • Component
  • System aka. Query
  • More Features and Outlook
• Performance
  • Benchmark
• Extensions
• Contributing

Quick start

I bet you don't want to read tons of documentation, theory, and other boring stuff right?
Let's 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 of 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 completely 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 2,147,483,647 possible worlds with up to 2,147,483,647 entities each.

Entity

An entity represents your game entity.
It is a simple struct with some metadata acting as a key to access 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 created, you need to specify the components it will have. Components are 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 ComponentType[]{ 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 define the game logic with pure data.
It's recommended to use struct components since they offer better speed.

To ease writing code, you can access 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 a velocity component and moves it to a new archetype.
entity.Add<Velocity>(new Velocity{ X = 1, Y = 1);  // Adds a 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 behavior 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().    
            WithAll<Position,Velocity>().      // Should have all specified components
            WithAny<Player,Projectile>().      // Should have any of those
            WithNone<AI>();                    // Should have none of those

// Execute the query
world.Query(in query, (in Entity 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 that are controlled by an AI (None).

The world.Query method then 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 an exclusive set of components via Exclusive. If that's set, it will ignore All, Any, and None and only target entities with an exactly defined set of components. It's 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!

More features and 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! There's more to explore, for example...

• Bulk Entity Adding
• High-performance Queries
• Archetypes
• Chunks
• Parallel / Multithreaded Queries
• Enumerators
• CommandBuffers
• Pure ECS
• More API

Performance

Well... it's 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 as well 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 access techniques. However, the most interesting one is the QueryBenchmark. In the benchmark, a set of entities was iterated over using the framework to access their transform and velocity and calculate a new position each iteration.

Their components looked like this:

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

The following performance was achieved with Arch for the scenario under heavy load and different amount of entities.

Extensions

Arch has some extensions that add more features and tools. Among them for example :

• 🛠️ Arch.Extended > Adds a set of tools and features to save boilerplate code!
• ❓ Your Tool-Library? > If you develop more tools and features for Arch, let us know and we'll list them here!

Contributing

I will accept contributions, especially bug fixes, 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.