Skip to content
Archevolt
Esc
↑↓navigate↵open⌘Jpreview

Headless ECS for .NET · MIT

Blazing fast simulations
in plain C#

Archevolt is an entity component system, or ECS, for .NET games and simulations. You write components as structs and systems as static methods. A source generator compiles them into direct calls at build time, and your program keeps its own host, loop, and threads.

Read the quickstart
dotnet add package Archevolt
to move 100,000 entities
22 µs
allocated per update after warm up
0 B
package dependencies
0
01Generated code

The readable version is the fast version

You do not rewrite Motion.Move for speed. Select a part of it to see what the generator wrote.

Motion.csyou write
[Component]
public readonly record struct Position(float X);

[Component]
public readonly record struct Velocity(float X);

public static partial class Motion
{
    [Each]
    public static void Move(scoped ref Position position, scoped in Velocity velocity)
    {
        position = position with { X = position.X + velocity.X };
    }
}
Motion.Move.Each.g.csgenerated

A Release build compiles the formula into a SIMD loop: eight floats per step with 256 bit vectors, four with 128 bit ones. It does the same operations in the same order as your method, so the results match.

// <auto-generated/>
#nullable enable
#pragma warning disable
using Archevolt;
#pragma warning restore
public static partial class Motion
{
    public const string __Archevolt_Move_Access = "condition|False\ncommands|False\nquery|0|Write|global::Position\nquery|0|Read|global::Velocity";
#pragma warning disable
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    private static void __Archevolt_Move_Inlined(scoped ref Position position, scoped in Velocity velocity)
    {
        position = position with { X = position.X + velocity.X };
    }
#pragma warning restore
    private sealed class __Archevolt_MoveBody : SystemBody
    {
        readonly QueryState _query0;
        static readonly bool __kernel = Vector128.IsHardwareAccelerated && __Probe();
        static bool __Probe()
        {
            {
                if (Unsafe.SizeOf<Position>() != 4) return false;
                Position __probe = default;
                var __lanes = MemoryMarshal.CreateSpan(ref Unsafe.As<Position, float>(ref __probe), 1);
                for (int __lane = 0; __lane < __lanes.Length; __lane++) __lanes[__lane] = __lane + 1;
                if (__probe.X != 1) return false;
            }
            {
                if (Unsafe.SizeOf<Velocity>() != 4) return false;
                Velocity __probe = default;
                var __lanes = MemoryMarshal.CreateSpan(ref Unsafe.As<Velocity, float>(ref __probe), 1);
                for (int __lane = 0; __lane < __lanes.Length; __lane++) __lanes[__lane] = __lane + 1;
                if (__probe.X != 1) return false;
            }
            return true;
        }
        static void __Kernel(Span<float> __column0, ReadOnlySpan<float> __column1)
        {
            int __count = __column0.Length;
            __column1 = __column1.Slice(0, __count);
            ref float __base0 = ref MemoryMarshal.GetReference(__column0);
            ref float __base1 = ref MemoryMarshal.GetReference(__column1);
            int __index = 0;
            if (Vector256.IsHardwareAccelerated)
            {
                for (; __index <= __count - 8; __index += 8)
                {
                    var __load0 = Vector256.LoadUnsafe(ref __base0, (nuint)__index);
                    var __load1 = Vector256.LoadUnsafe(ref __base1, (nuint)__index);
                    var __t0 = (__load0 + __load1);
                    Vector256.StoreUnsafe(__t0, ref __base0, (nuint)__index);
                }
            }
            else if (Vector128.IsHardwareAccelerated)
            {
                for (; __index <= __count - 4; __index += 4)
                {
                    var __load0 = Vector128.LoadUnsafe(ref __base0, (nuint)__index);
                    var __load1 = Vector128.LoadUnsafe(ref __base1, (nuint)__index);
                    var __t0 = (__load0 + __load1);
                    Vector128.StoreUnsafe(__t0, ref __base0, (nuint)__index);
                }
            }
            for (; __index < __count; __index++)
                __column0[__index] = (__column0[__index] + __column1[__index]);
        }
        internal __Archevolt_MoveBody(SystemBinder binder)
        {
            _query0 = binder.Query(0);
        }
        protected override void Run(SystemRun run)
        {
            var cursor = _query0.Begin(run);
            while (cursor.Next(out var block))
            {
                Span<Position> _column0;
                _column0 = block.Write<Position>(0);
                ReadOnlySpan<Velocity> _column1;
                _column1 = block.Read<Velocity>(1);
                int count = block.Count;
                if (__kernel && count <= 2147483647)
                {
                    __Kernel(MemoryMarshal.Cast<Position, float>(_column0), MemoryMarshal.Cast<Velocity, float>(_column1));
                    continue;
                }
                __Rows(_column0, _column1, count);
            }
        }
        [MethodImpl(MethodImplOptions.NoInlining)]
        static void __Rows(Span<Position> __input0, ReadOnlySpan<Velocity> __input1, int __input2)
        {
            var _column0 = __input0;
            var _column1 = __input1;
            var count = __input2;
            for (int row = 0; row < count; row++)
            {
                Motion.__Archevolt_Move_Inlined(ref _column0[row], in _column1[row]);
            }
        }
    }
    public static SystemDescriptor Move_Descriptor { get; } = SystemDescriptor.Create("Motion.Move", static binder => new __Archevolt_MoveBody(binder))
        .EachQuery(QueryShape.Create("Motion.Move(scoped ref Position, scoped in Velocity).0").Write<Position>(0).Read<Velocity>(1).Build(), partitionable: false)
        .Build();
}

Methods with if branches, MathF.Min and MathF.Max, and calls to your own static methods can compile this way too. The systems guide lists what qualifies.

02Performance

Speed is a requirement

22µs

to move 100,000 entities on one thread. That is 0.22 ns per entity, and it matches Bevy 0.20, which takes 23.7 µs on the same machine.

allocated per update after warm up, with one worker or four
0 B
to run one [Each] system, before it visits an entity
24 ns
for a Changed<T> scan when nothing changed, at 1,000 or 100,000 entities. Bevy 0.20 takes 29 µs at 100,000.
0.16 µs

Moving 100,000 entities on one thread, median µs per updateEach entity adds its velocity, scaled by a time step, to a position of three floats. Archevolt and Bevy each run that as one system in a schedule.

CaseMedian µs
Rust, handwritten loopno ECS20.50
Archevolt [Each]22.0
Bevy 0.20 for_each23.70
C#, handwritten loopno ECS83.06
Arch 2.1.0, inline queryno scheduler103.5

The chart shows medians of three process runs on an AMD Ryzen 9 5950X, in Release builds, from the round two report and the benchmark results. The system cost comes from a second machine. The performance page lists what costs.

03Setup

Then wire it into a program

  1. Add the package

    One package holds the runtime and the source generator. Your project needs .NET 11 and C# 15.

    dotnet add package Archevolt
  2. Collect systems into a module

    A bundle lists the components an entity starts with. A module gathers systems and bundles, and a schedule declares which systems run, in what order. The generator writes GameEcs.Module and Simulation.Create from them.

    [Bundle]
    public readonly partial record struct Particle(Position Position, Velocity Velocity);
    
    [EcsModule, IncludeSystems(typeof(Motion)), IncludeBundle<Particle>]
    public static partial class GameEcs;
    
    [Schedule, Run(typeof(Motion), nameof(Motion.Move), Order = 0)]
    public sealed partial class Simulation;
  3. Build a world and run it

    Spawn entities from bundles, bind the schedule to the world, and call Run once per update.

    using var world = new WorldBuilder().AddModule(GameEcs.Module).Build();
    var entity = world.Spawn(new Particle(new Position(0), new Velocity(1)));
    
    using var simulation = Simulation.Create(world);
    simulation.Run();
    
    Console.WriteLine(world.Get<Position>(entity).X); // 1

The quickstart walks through the complete program.

05What you get

Queries, storage, schedules, and messages

Queries

Typed rows, no lookups

Named queries produce concrete rows with ref and ref readonly access. Nothing is boxed or looked up by type at run time.

Queries guide
Storage

Dense native tables

Components live in aligned, structure of arrays tables, one per archetype, outside the managed heap.

Architecture
Schedules

Ordering you declare once

Order systems with Order, Before, After, stages, and sets. The planner adds conservative ordering where access conflicts.

Schedules guide
Data flow

Changes, resources, messages

Track added and changed components, share resources, and send messages that each reader consumes at its own pace.

Messages guide
Guides

A guide for every feature

Components, modules, queries, schedules, resources, commands, and the rest.

Browse the guides
06FAQ

Questions before you start

01Is Archevolt a game engine?

No. It is a library that runs your simulation inside your own program, on .NET 11. You bring the window, input, and rendering, for example with Silk.NET, or run with no graphics at all. It has no integration for a specific engine.

02Which methods do not become SIMD loops?

For example, a method that contains a loop, uses %, returns early, or takes an Entity or Commands parameter. Such a method still runs, as a plain loop that handles one entity at a time. Read the rules in the systems guide

03Can I step through a system in the debugger?

Yes. A Debug build calls your method once per entity, so a breakpoint in it is hit. An optimized build copies the body of the method into the generated loop.

04Does it allocate during an update?

Not after the first updates, as long as storage does not grow. Spawning and other structural changes can grow storage, and that allocates.

05What does the generator change in my code?

It adds members to your declarations, so the types it touches must be partial. Generated code stays in your namespace, inside the partial type it extends.

06What happens when a declaration is wrong?

The generator reports it when you build, with a numbered diagnostic such as AV006 for a change filter on a component that is not tracked. All but one of the diagnostics fail the build. See the diagnostics

07How do systems add or remove components?

Inside a system, record the change with Commands. The schedule applies it before the systems that depend on it run. Outside a schedule, change the world directly on its owner thread.

08How does it compare to other ECS libraries?

On a test that moves 100,000 entities, Archevolt matches Bevy 0.20, and Arch 2.1.0 takes 103.5 µs against Archevolt's 22. In other tests Archevolt skips unchanged components faster than Bevy does, and is slower at Get<T> lookups and when it writes and then scans every tracked component. All of these ran on one machine. See the benchmark results

09Is it free to use?

Yes. Archevolt is open source under the MIT license, and the source is on GitHub.

Get started

Build your first simulation

Getting started is easy. Add the package and follow the quickstart.

Read the quickstart
dotnet add package Archevolt