Arch 1.2.8

There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Arch --version 1.2.8                
NuGet\Install-Package Arch -Version 1.2.8                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Arch" Version="1.2.8" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Arch --version 1.2.8                
#r "nuget: Arch, 1.2.8"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Arch as a Cake Addin
#addin nuget:?package=Arch&version=1.2.8

// Install Arch as a Cake Tool
#tool nuget:?package=Arch&version=1.2.8                

Arch

Maintenance Nuget License C#

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 comes along several Extensions!
  • 🚢 SUPPORT > Supports .NetStandard 2.1, .Net Core 6 and 7, and therefore you may use it with Unity or Godot!

Download the package, get started today and join the Discord!

dotnet add PROJECT package Arch --version 1.2.8

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 sealed 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

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(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, (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 Creation
  • Batch Operations
  • High-performance Queries
  • Archetypes
  • Chunks
  • Parallel / Multithreaded Queries
  • Enumerators
  • CommandBuffers
  • Pure ECS
  • Events
  • Monogame, Unity, Godot Integration guides
  • More API

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!
  • 🔎 Godot Entity Debugger > An Arch Entity debugger for the Godot engine!
  • 🔎 Stride Entity Debugger > An example of Arch in the Stride engine, with additional entity and system inspector!
  • 🔎 Arch.Unity > A library that makes the integration of Arch in Unity much easier, with many cool new features!
  • Your Tool-Library? > If you develop more tools and features for Arch, let us know and we'll list them here!

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.

Method Amount Mean Error StdDev CacheMisses/Op Allocated
WorldEntityQuery 10000 111.003 us 13.2838 us 0.7281 us 409 -
Query 10000 20.159 us 1.4188 us 0.0778 us 103 -
EntityQuery 10000 17.711 us 1.1311 us 0.0620 us 49 -
StructQuery 10000 7.767 us 0.1572 us 0.0086 us 7 -
StructEntityQuery 10000 7.338 us 1.7188 us 0.0942 us 12 -
WorldEntityQuery 100000 1,326.959 us 3,058.5935 us 167.6518 us 5,753 -
Query 100000 203.555 us 4.6038 us 0.2523 us 2,977 -
EntityQuery 100000 228.222 us 17.4030 us 0.9539 us 2,708 -
StructQuery 100000 115.466 us 8.8355 us 0.4843 us 2,726 -
StructEntityQuery 100000 76.823 us 2.1875 us 0.1199 us 2,544 -
WorldEntityQuery 1000000 12,519.798 us 4,491.2760 us 246.1820 us 45,604 -
Query 1000000 2,679.153 us 35.1696 us 1.9278 us 28,579 -
EntityQuery 1000000 2,462.296 us 322.4767 us 17.6760 us 28,113 -
StructQuery 1000000 1,514.479 us 296.5311 us 16.2539 us 29,723 -
StructEntityQuery 1000000 1,483.142 us 329.9446 us 18.0854 us 31,272 -

Projects using Arch

Arch is already used in some projects, for a more detailed look, take a look at the wiki!

https://github.com/genaray/Arch/wiki/Projects-using-Arch

Space Station 14

Space Station 14 is inspired by the cult classic Space Station 13 and tells the extraordinary story of everything that can go wrong on a shift at a space station. You take on a role and complete your tasks so that the space station doesn't go to the dogs... or do the exact opposite. Prepare yourself for chaos and the finest roleplay. Best of all, SS14 is open-source and anyone can play!

Roguelite-Survivor

An action-packed c# clone of the hit "vampire survivor" based on monogame and arch! Fight your way through hordes of different enemies, level up your character, collect permanent items and explore various maps! Try it out!

EquilibriumEngine-CSharp

Equilibrium Engine is a data-oriented C# game engine that takes advantage of ECS pattern followed by Hot-Reloading of your libraries which allows you to quickly iterate on different aspects of your projects.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on Arch:

Package Downloads
Arch.Persistence

A Persistence-Framework for Arch.

Arch.Relationships

Simple Entity-Relationships for Arch.

Undine.Arch

Package Description

Doprez.Stride.Arch

A package of helper classes for using Arch ECS in Stride3D

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on Arch:

Repository Stars
genaray/Arch.Extended
Extensions for Arch with some useful features like Systems, Source Generator and Utils.
Doraku/Ecs.CSharp.Benchmark
Benchmarks of some C# ECS frameworks.
Version Downloads Last updated
1.2.8.1-alpha 1,248 4/19/2024
1.2.8 4,993 3/13/2024
1.2.7.1-alpha 530 11/20/2023
1.2.7 2,961 10/15/2023
1.2.6.8-alpha 345 9/17/2023
1.2.6.7-alpha 161 8/27/2023
1.2.6.6-alpha 3,094 8/25/2023
1.2.6.5-alpha 217 8/19/2023
1.2.6.4-alpha 127 8/14/2023
1.2.6.3-alpha 72 8/14/2023
1.2.6 669 8/13/2023
1.2.5.3-alpha 494 5/21/2023
1.2.5.2-alpha 126 5/16/2023
1.2.5.1-alpha 221 5/11/2023
1.2.5 780 4/26/2023
1.2.4.2-beta 93 4/16/2023
1.2.4 396 4/15/2023
1.2.3 211 3/19/2023
1.2.0 177 3/5/2023
1.1.9 191 1/29/2023
1.1.8 114 1/29/2023
1.1.7 117 1/29/2023
1.1.6 146 1/19/2023
1.1.5 117 1/18/2023
1.1.4 123 1/16/2023
1.1.3 117 1/16/2023
1.1.2 113 1/16/2023
1.1.1 464 12/30/2022
1.1.0 130 12/20/2022
1.0.17 108 12/9/2022
1.0.16 228 12/4/2022
1.0.15 107 11/27/2022
1.0.14 102 11/23/2022
1.0.13 104 11/22/2022
1.0.12 100 11/20/2022
1.0.11 103 11/15/2022
1.0.10 98 11/15/2022
1.0.9 107 11/13/2022
1.0.8 131 11/6/2022
1.0.7 106 11/4/2022
1.0.6 98 11/4/2022
1.0.5 104 11/2/2022
1.0.4 89 11/1/2022
1.0.3 98 11/1/2022
1.0.2 93 11/1/2022
1.0.1 114 11/1/2022
1.0.0 140 11/1/2022

Updated LowLevel which fixes bugs.
Fixed issue where Unsafe.As did not work on .Net 2.1 for the Dangerous-Utils.
Dangerous API now allows setting/getting of recycled ids.
Fixed archetype duplication after loading a save.
Fixed .Add when a newly non registered component was added.
Now makes use of the updated and improved JobScheduler 1.1.2.
ScheduleParallelInlineQuery added.
Added World.IsAlive(EntityReference);
Fixed bug where `World.TrimExcess` does not trim Recycled-Entities which results in an out of bounds exception sooner or later.
Fixed bug in JobScheduler which prevents a deadlock.
Moved CommandBuffer to Buffer namespace, might break references.
CommandBuffer now accepts a world during playback, world in ctor was removed.
CommandBuffer now triggers OnComponentRemoved events.