Manual

Manual

Performance

What the engine's own benchmarks measured, and what that means for how you write a game's systems: the cost of a system over many entities, the shape a system is written in, one system on every core, scheduling many systems, entities spread over many archetypes, changing the world, transforms, the development-time borrow checks, and one sharp edge.

How the numbers were measured

Every number on this page comes from the engine's benchmark programs, in the engine's source: dotnet/bench/Abyss.Bench for C#, and rust/crates/abyss-bench for the native baselines. They were measured on one Windows 10 x64 machine with an Intel Core i7-14700K, 20 cores (8 performance and 12 efficiency) behind 28 hardware threads, from release builds, with .NET's JIT unless a row says otherwise. Each benchmark runs its frames for a while before it starts measuring, so the JIT has compiled them, except where a row says it measured the first frames.

They are measurements of one machine and one version of the engine, not promises. With the engine's source you can run them on your own:

dotnet run -c Release --project dotnet/bench/Abyss.Bench            # every C# benchmark
dotnet run -c Release --project dotnet/bench/Abyss.Bench -- swarm   # the swarm alone
cargo run --release -p abyss-bench                                  # the native baselines, from rust/

To see where your own game's frames go, use the Profiler, which times each system by its name.

A system over half a million entities

500,000 entities, each with a position and a velocity, and one system adding the velocity times the frame's time to the position, over 200 measured frames:

ImplementationMean framePer entity
A native Bevy system, Query<(&mut Position, &Velocity)>0.700 ms1.40 ns
Rust, through the engine's chunks0.461 ms0.92 ns
C#, through the engine's chunks (JIT)0.414 ms0.83 ns
C#, through the engine's chunks (NativeAOT, as a built game is compiled)0.398 ms0.80 ns

The C# loop allocated 0 bytes and caused no garbage collections across the measured frames. A C# system reads Bevy's memory as spans, and crosses into the engine once per frame to find its chunks, not once per entity, so it costs about what the same loop costs in Rust.

The shape a system is written in

The same work, in each of the ways a C# system can be written (GeneratedSystemBenchmark):

FormMean frameAgainst the hand-written
Added by hand with schedule.Add, a loop over chunks0.382 ms1.00x
[AbyssSystem], per entity (ref and in)0.432 ms1.13x
[AbyssSystem], per chunk (Span<T>)0.444 ms1.16x
[AbyssSystem], per entity, without [MethodImpl(MethodImplOptions.AggressiveInlining)]1.38 to 1.91 ms3.6x to 5.0x

Without the attribute, the JIT does not inline the per-entity call, and the system runs several times slower with nothing to show why but a profiler. That is why the build warns (ABYSS010) when a per-entity system lacks it.

Rust and vectorization

The same arithmetic again, in the same schedule and process (NativeSystemBenchmark):

BodyMean frameAgainst native
Native, the engine's Rust0.193 ms1.00x
C#, field by field, as gameplay code is written0.381 ms1.98x
C#, the columns read as flat runs of float, the native body's loop shape0.582 ms3.02x
C#, the flat runs vectorized by hand with Vector<T>0.229 ms1.19x

The difference is auto-vectorization, not the language: Rust's compiler turns a simple loop into SIMD instructions on its own, and .NET's does not. A C# loop vectorized by hand comes within a fifth of the native one. Rust in a game says when that is worth a crate of your own.

One system on every core

A game's systems run one after another on the engine thread. A system over many entities can cut its own loop into slices that several threads run, with [AbyssSystem(Parallel = true)] (see One system on every core). The swarm benchmark (SwarmBenchmark) writes the transforms of 100,000 entities from one C# system:

The system's loopOne threadIn slices
Turning each, a quaternion built for each1.38 ms0.18 ms
Circling each, a sine and a cosine for each1.61 ms0.19 ms

Once warm, neither form allocates. Slices pay for a loop over many thousands of entities that does real work on each. Handing out a slice has a cost of its own, which is why a slice is at least 1,024 rows, and a loop over a few hundred entities is better left on one thread.

Scheduling many systems

A Schedule can also run systems that touch different data at the same time, with Schedule.RunParallel; it gives the same result as running them in order, because systems that touch the same data keep the order they were added in. A game's own frame does not use it: the editor and a built game run their schedules one system after another. These numbers measure RunParallel on schedules built for the purpose, and say how ECS work behaves on many cores.

What the numbers say

Four systems over 500,000 entities (ScheduleBenchmark), where one of them writes the velocity another reads, so those two must run one after the other:

One after another1.082 ms
In parallel0.691 ms
Speedup1.57x
The two that must run in order, alone0.561 ms
What parallel reached of that floor81%

The speedup is bounded by the work, not the cores: no scheduler can finish faster than its longest chain of systems that must run in order, so nothing could beat about 1.93x here. Schedule.CriticalPathLength says how long that chain is. And systems of this shape stream memory with little arithmetic for each byte, so they are bound by the memory's bandwidth long before they run out of cores.

At realistic system counts

128 systems, none touching another's data, so none has to wait for another (ScheduleScalingBenchmark):

Each system's workOne after anotherIn parallelSpeedup
10,000 entities, 8 operations an element2.100 ms0.301 ms6.98x
10,000 entities, 64 operations an element45.621 ms3.201 ms14.25x
200 entities, 8 operations an element0.056 ms0.189 ms0.30x

The first row's limit is memory, not the scheduler: the same schedule reaches 14.25x once each element takes enough arithmetic. On this machine's 8 performance and 12 slower efficiency cores, that is close to what it can deliver. The first row is the realistic shape for ECS work.

The third row is the one to remember. Handing a system to another thread costs about 1.5 µs, so a schedule of many systems that each do almost nothing runs three to five times slower in parallel than in order.

Many archetypes

Entities with different sets of components are kept in different tables, and a game soon has many: every component added or removed makes a new combination. 500,000 entities spread evenly over more and more archetypes, one query matching all of them (ArchetypeBenchmark):

ArchetypesRows in eachFinding the chunksFirst frames, per entityOnce warm, per entity
1500,0000.0000 ms0.83 ns0.83 ns
862,5000.0001 ms0.89 ns0.87 ns
647,8120.0002 ms1.49 ns0.82 ns
5129760.0018 ms4.71 ns0.84 ns

Once warm, spreading entities thin costs nothing per entity, and finding the chunks stays negligible; a query matching one archetype of 512 took 0.0008 ms. The first frames are another matter. A chunk of half a million rows runs long enough for the JIT to swap in optimized code part way through the loop, where a chunk of a thousand never does and waits for its method to be called often enough instead. Same work and same memory, 5.7x apart in a game's first second. A native body over the same spreads stays at 0.38 to 0.40 ns per entity, which shows the cause is compilation, not memory.

Changing the world

Creating 10,000 entities of two components each, every frame (SpawnBenchmark):

Per framePer entity
Recording them into a command buffer0.013 ms1.3 ns
Applying the buffer0.761 ms76.1 ns

Recording is writing into memory .NET owns, and the whole buffer crosses into the engine once. The cost is Bevy inserting each entity.

Giving 10,000 entities one component, then taking it away, every frame (RetagBenchmark):

Per framePer entity
Adding one component0.354 ms35.4 ns
Removing it again0.468 ms46.8 ns

Moving an entity from one table to another is cheaper than spawning one, but its cost grows with what the entity carries, since all of its components are copied into the new table.

Transforms

100,000 entities, 20,000 parents with four children each (TransformBenchmark):

World positions worked outPer frame
By Bevy's propagation, after the frame's systems, with nothing moved0.144 ms
By Bevy's propagation, with every transform written2.078 ms
Of which, the C# system writing them0.101 ms
By ResolveTransforms in the schedule, nothing moved1.87 ms
By ResolveTransforms in the schedule, every transform written2.00 ms

Propagation skips what nothing moved, and whole branches of the hierarchy below nothing that moved, so a scene that mostly stands still, as most do, costs almost nothing. ResolveTransforms, the way to see world positions part way through a frame (see The same frame's positions), works out every entity from scratch, so it costs the whole hierarchy every time it runs, moved or not. Add it only where a system needs it.

What the borrow checks cost

world.BorrowChecking turns on a development-time check that refuses two pieces of code holding overlapping spans over the same column at once. It is off unless your code turns it on. It counts a borrow for each column a query reaches, once a system run, not for each entity. Thirty-two systems with empty bodies over 1,000 entities, so the frame is nearly all the work of running a system, the entities spread over a number of tables (BorrowCheckBenchmark):

TablesFrame, checks offFrame, checks onAdded to each system run
10.0022 ms0.0029 ms21 ns
80.0030 ms0.0059 ms90 ns
640.0086 ms0.0171 ms266 ns
5120.0679 ms0.1277 ms1,870 ns

The checks roughly double the cost of finding a system's chunks, which is microseconds. In a frame of real work, four systems over 500,000 entities, the difference was smaller than the frame's own variation from run to run.

One sharp edge

This is for code that resolves a query itself, outside a schedule, such as a tool or a flow that uses world.CreateQuery. Keep the loop over each entity out of the block that holds the borrow:

using Query query = world.CreateQuery(position.Write(), velocity.Read());
void Frame(){    using ChunkCollection chunks = query.Resolve();   // gives the borrow back at the end of the block    foreach (Chunk chunk in chunks)    {        Integrate(chunk);                              // the loop, in a method of its own    }}
[MethodImpl(MethodImplOptions.NoInlining)]static void Integrate(Chunk chunk){    Span<Position> positions = chunk.GetSpan<Position>(0);    ReadOnlySpan<Velocity> velocities = chunk.GetReadOnlySpan<Velocity>(1);    for (int i = 0; i < positions.Length; i++)    {        positions[i].X += velocities[i].X * (1f / 60f);    }}

A using becomes a try/finally, and the JIT optimizes code inside one less aggressively: with the loop written inside the using block, the benchmark's integration loop measured about 7% slower. A loop in a method of its own is outside it. A system added to a schedule needs none of this: the schedule holds the borrow around its body and calls the body as a method of its own.

In the Scripting API