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.
dotnet add package Archevolt- to move 100,000 entities
- 22 µs
- allocated per update after warm up
- 0 B
- package dependencies
- 0
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.
[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 };
}
}Archevolt stores each component type in a column of its own. Position is one float, so the generated code reads the whole column as floats.
[Each] runs the method for every entity that has both components. The generated code walks those entities in blocks of rows.
ref asks to write and in asks to read. The block gives the loop the Position column as a writable span and the Velocity column as a read only span.
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.
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.
| Case | Median µs |
|---|---|
| 20.50 | |
| 22.0 | |
| 23.70 | |
| 83.06 | |
| 103.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.
Then wire it into a program
Add the package
One package holds the runtime and the source generator. Your project needs .NET 11 and C# 15.
dotnet add package ArchevoltCollect 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.ModuleandSimulation.Createfrom 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;Build a world and run it
Spawn entities from bundles, bind the schedule to the world, and call
Runonce 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.
Archevolt is headless
No window, input, rendering, or audio. You call simulation.Run() from your own loop, in a game, a server, or a test.
Parallel when you ask for it
Systems run one at a time by default. Turn on the worker pool, and systems that do not conflict run together. A partitioned system also splits its rows across the workers.
Execution guideReady for NativeAOT
The same package runs under the JIT, trimmed, or as a NativeAOT image.
InstallationQueries, storage, schedules, and messages
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.
Dense native tables
Components live in aligned, structure of arrays tables, one per archetype, outside the managed heap.
ArchitectureOrdering you declare once
Order systems with Order, Before, After, stages, and sets. The planner adds conservative ordering where access conflicts.
Changes, resources, messages
Track added and changed components, share resources, and send messages that each reader consumes at its own pace.
Messages guideA guide for every feature
Components, modules, queries, schedules, resources, commands, and the rest.
Browse the guidesQuestions 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.
dotnet add package Archevolt