EasyEcs 4.7.0
dotnet add package EasyEcs --version 4.7.0
NuGet\Install-Package EasyEcs -Version 4.7.0
<PackageReference Include="EasyEcs" Version="4.7.0" />
<PackageVersion Include="EasyEcs" Version="4.7.0" />
<PackageReference Include="EasyEcs" />
paket add EasyEcs --version 4.7.0
#r "nuget: EasyEcs, 4.7.0"
#:package EasyEcs@4.7.0
#addin nuget:?package=EasyEcs&version=4.7.0
#tool nuget:?package=EasyEcs&version=4.7.0
EasyEcs
EasyEcs is a high-performance archetype Entity Component System (ECS) for C# and .NET 10 game servers,
simulations and other long-running real-time backends. A warmed-up world of 100,000 entities runs nine simulation
systems in 1.72 ms with 0 B allocated. Across 37 head-to-head benchmarks against Friflo.Engine.ECS, Arch and
DefaultEcs, EasyEcs leads in 24, is within measurement error in 11 and trails in 2
(full comparison). Write plain structs and
[ForEach] methods; a source generator builds the iteration jobs and an analyzer catches mistakes at compile time.
Documentation: ecs.xgamedev.net (English · 中文)
Try it in your browser: set the live particle demo to 100k, then
move your pointer across the particles. The demo's C# runs through Mono AOT to WebAssembly; its batched drag and
movement systems took about 0.1 ms on an M4 during this capture. The rest of the systems and rendering are separate
from that reading. The batch system source shows the
[ForEach] + Span + SIMD path.
<a href="https://ecs.xgamedev.net/en/docs/demo"><img src="docs/public/demo-vortex-100k.png" alt="EasyEcs browser demo with 100k particles forming a vortex and live ECS timings" width="560"></a>
One server tick of 9 systems (movement, AOI, combat, status effects, death, respawn, projectiles):
| Tick | Entities | Time | Allocated |
|---|---|---|---|
| One world | 100,000 | 1.72 ms | 0 B |
| Four worlds, one per thread | 100,000 | 0.92 ms | 0 B |
| Battle server, every feature | 100,000 | 2.97 ms | 0 B |
<sub>BenchmarkDotNet 0.15.2 (EasyEcs.Benchmark), 4-core Intel Xeon VM at 2.1 GHz (Ubuntu 24.04), .NET 10.0.13; entities spawn, die, gain and lose components every tick.
The battle server turns every feature on: parallel steering and systems, replication, indexes, relations, timings.
A [ForEach] system adding Velocity to Position costs 0.9 ns per entity (one archetype), faster than two
plain arrays.
Details.</sub>
dotnet add package EasyEcs # net10.0 · source generator, analyzer and Nino included
Why EasyEcs
- Fast and garbage-free. Archetype tables with 64-byte-aligned columns that iteration and SIMD walk front to back, 16-byte entity records (4 per cache line), JIT-inlined struct jobs instead of delegates, lock-free queries. After warm-up nothing allocates: a unit test guards the 0 B budget of updates, queries and structural changes on every run.
- Structural changes are immediate and cheap. Add and remove components, spawn and destroy, even in the middle of a pass; no command buffer to flush. Removing a status effect and adding it back flips a presence bit, the entity never moves. State can be tags, not flags.
- Write the logic, not the plumbing. A
[ForEach]method is the whole system; filters are attributes ([With<T>],[Without<T>],[WithAny<T>]), singletons are parameters. - Built-in change tracking, removal detection, indexes and relations.
[Changed<T>]visits only the rows written since a system last ran, including writes throughref(or only the rows whose value changed, throughMut<T>),[ChangedAny<A, B>]those where any of several changed,[Removed<T>]the entities that lost a component, and a destroy log the entities destroyed since each client's tick;IIndexed<TKey>components are found by value, and anIIndexed<EntityId>component or anIRelationbuffer (Link) makes a relation, kept current by everySet. No events and nothing to keep in sync by hand. - Prefabs that stay out of your queries. A
Prefabis a recipe of component values that belongs to no world:world.Instantiate(prefab)spawns from it (a whole wave in one pass), and no system ever has to filter templates out.entity.Clone()copies a living entity. - Mistakes fail the build. The bundled analyzer (EECS002-EECS052, with code fixes) reports invalid
[ForEach]methods and systems, class components, stateful systems, systems that reference each other, batch methods mixing spans with per-entity parameters, parallel methods that would race, writes through read-only parameters, copied dynamic buffers, structural changes off the owner thread, indexed components written behind their index's back, removal filters no entity can pass and ordering cycles; it warns aboutEntityhandles stored in components. - Decoupled by construction. Systems cooperate only through data, in registration order unless
[UpdateBefore<T>]/[UpdateAfter<T>]say otherwise; system groups give you separate cadences (input on every wake, simulation on a fixed tick). - Built for servers that run for months. Ids are recycled behind version-checked handles, memory is bounded by the peak entity count, a structural change off the owner thread throws or is reported at compile time instead of tearing the tables; the supported model is one owner thread per world (see Threading), and one world per thread scales across cores.
Features
Everything EasyEcs gives you; each row links to its guide page with examples (all features: what each costs and when to use it).
| Feature | API | What it does |
|---|---|---|
| Worlds and entities | new World(options), CreateEntity, TryGetEntity, IsAlive, Destroy |
Isolated worlds of version-checked, recycled entity handles; lookup by id. |
| Components and tags | struct : IComponent, Set, Get, Read, TryGet, TryGetRef, GetOrAdd, Has, Remove; generated e.Position, SetX, IsDead |
Plain structs in archetype tables; an empty struct is a tag; up to 9 components per call. |
| Prefabs and cloning | Prefab, generated prefab.SetX(…), world.Instantiate(prefab), Instantiate(prefab, span), Instantiate(prefab, new ChildOf(p), …), entity.Clone() |
Kinds of entities defined once as data that belongs to no world, spawned with components of their own in one row copy; copies of a living entity. |
| Immediate structural changes | any Set / Remove / create / Instantiate / destroy |
Applied at once, even in the middle of a pass; no command buffer to flush. |
Systems and [ForEach] |
EcsSystem, [ForEach], [UpdateBefore<T>] / [UpdateAfter<T>], OnCreate / OnUpdate / OnDestroy, AddSystem / RemoveSystem / TryGetSystem |
A method is the whole loop, compiled to an inlined struct job; in reads, ref writes, Entity and singletons as parameters. |
| Filters | [With<T>], [Without<T>], [WithAny<T>], [Changed<T>], [Removed<T>], [ChangedAny<A, B>], [RemovedAny<A, B>], QueryFilter |
Narrow a system or query by presence, absence, any-of, recent writes or recent removals. |
| Group filters | [With<T>] / [Without<T>] / [WithAny<T>] on an ISystemGroup, ISystemGroupWith<T>, ISystemGroupWithout<T> |
One filter for every system of a group; through an interface, a generic group gives each actor type its own. |
| Optional components | Maybe<T> parameter, HasValue, Value |
One method for entities with and without a small optional part. |
| Ad-hoc queries | world.Query, Count, Any |
Iterate from any code (tools, tests, request handlers), allocation-free. |
| Struct jobs | IForEach, IForEachEntity, IForEachBatch, world.ForEach / ForEachEntity / ForEachBatch, INoStructuralChanges |
Ad-hoc loops with no delegate, inlined like a system; a job declares WriteMask. |
| One entity | entity.Run(ref job), Run(ref job, filter) |
A struct job on one entity (a request, a message to an actor) with the refs and guarantees of a pass; false when it does not match. |
| Batch methods | ForEachBatch, span parameters |
Contiguous runs of rows as spans, for SIMD. |
| System groups and intervals | ISystemGroup, [UpdateInGroup<T>], Update<TGroup>(), UpdateInterval, Enabled |
Separate cadences (input on every wake, simulation on a fixed tick), throttled and switchable systems. |
| Slices | [ForEach(Slices = N)], QueryFilter.Slice, system.RunCount |
Spread a method's rows over N runs: every row once per N runs, about 1 / N of the work per update. |
| Generic systems | class CountOf<T> : EcsSystem |
Each closed type is a system of its own, scheduled on its own. |
| Singletons | ISingletonComponent, AddSingleton, GetSingleton, SingletonRef<T> |
One value per world, passed to systems as ref / in parameters. |
| Parallel systems | WorldOptions.ParallelSystems |
Systems with no order and no conflict between them run at once, with the sequential result. |
Parallel [ForEach] |
[ForEach(Parallel = true)], ForEachParallel, ForEachEntityParallel, ParallelChunkRows |
One heavy method's rows split across cores. |
| Change tracking | ITracked, [Changed<T>], [ChangedAny<A, B>], QueryFilter.Changed<T>(since), ChangedAny<A, B>(since), Since(tick) |
Visit only the rows written since a system last ran, or since each client's tick; ref access counts as a write. |
| Writes only when changed | Mut<T> parameter, SetIfChanged, generated SetXIfChanged(…) |
Stamp only the rows whose value really changed, so readers skip the rest. |
| Removal detection | [Removed<T>], [RemovedAny<A, B>], QueryFilter.Removed<T>(since) |
Visit only the entities that lost a tracked component since a system last ran (replicate what went away). |
| Destroy log | WorldOptions.DestroyLogCapacity, world.DestroyedSince(since, into, out count) |
The entities destroyed since each reader's tick, for despawns to many clients; a reader older than the log resynchronizes. |
| Cleanup components | ICleanupComponent, Retired |
An entity outlives Destroy until a system releases its external resource (a socket, a seat). |
| Disable and enable | entity.Disable<T>(), Enable<T>(), Disabled<T>, DisableAll / EnableAll |
Hide a component from queries and keep its value. |
| Dynamic buffers | DynamicBuffer<T>, Add, RemoveAt, AsSpan, [Changed<DynamicBuffer<T>>] |
A list per entity as a component: written only through ref, so every change is tracked; copied by snapshots. |
| Value indexes | IIndexed<TKey>, world.Index<T, TKey>(), Find, TryFind, Count |
Find entities by a component's value, kept in sync with every write. |
| Unique keys | IUniqueIndexed<TKey>, index.Get(key), TryGet |
One entity per key (an account, a session); a write that would duplicate a key throws before it changes anything. |
| Ordered ranges | index.Range(min, max), RangeDescending, Ascending(), Descending() |
Walk a comparable key in order: leaderboards, rating brackets. |
| Relations | an IIndexed<EntityId> component; IRelation elements with Link / Unlink, world.Relations<T>(); WhenTargetDestroyed |
One or many entity-to-entity links with reverse lookup; what a link does when its target dies (keep, remove, destroy). |
| Hierarchy | ChildOf, world.Children(parent), world.Descendants(root) |
Parents and children; destroying a parent destroys its subtree; a whole subtree in one walk. |
| Table groups | IGroup, world.GroupBy<T>(), QueryFilter.InGroup<T>(group) |
Split tables by a value (zone, map, match), so a query walks one group's rows only. |
| Snapshots | world.Capture(), world.Restore(snapshot) |
Copy a world in memory and roll it back (replays, tests, rollback). |
| Saves | world.Save(writer), world.Load(bytes); SaveWithout(writer, exclude), LoadKeeping(bytes, keep, markWritten: false) |
A whole world as bytes through Nino, for restarts and other processes; a restart leaves runtime state out and keeps the new configuration. |
| Migration and records | SaveEntities, SaveEntitiesWith (a ComponentSet), LoadEntities, LoadEntitiesInto (markWritten: false), MoveEntities |
A group of entities to another world or server, links rewritten; a record of what persists, restored onto existing entities. |
| Unloading plugin types | world.RemoveTypes(assembly or context) |
Remove a plugin's types so its AssemblyLoadContext unloads: hot reload on a live server. |
| Bulk create and destroy | CreateEntities, Instantiate(prefab, span), DestroyAll, DestroyEntities(ids), Reserve |
Spawn and clear waves in one pass through the structural gate. |
| Per-system timing | WorldOptions.MeasureSystems, system.Stats |
Run counts, times, allocated bytes and visited entities of every system. |
| Schedule | world.DescribeSchedule(), ToString(), ToMermaid() |
The stages, each system's reads and writes, why it waits, and the pairs only registration orders. |
| Errors | WorldOptions.SystemErrors, system.Error |
A failing system throws out of the update, or is switched off with its exception kept while the tick goes on. |
| Introspection | world.DescribeTables(), entity.Describe() |
Tables, columns, rows and bytes; an entity's component values, for tools and debuggers. |
| Giving memory back | world.TrimExcess() |
After a peak: drop empty tables, shrink the others, release save and load buffers. |
| Analyzer | EECS002-EECS052 | ECS design mistakes (class components, stateful systems, systems referencing systems, …) fail the build. |
| Threading and Native AOT | one owner thread per world; no reflection on hot paths | Many worlds per process, one per thread; AOT works with nothing to configure. |
Example
Data is plain structs, each system is one [ForEach] method, and systems cooperate only through the data they write:
using EasyEcs;
public record struct Position(float X, float Y) : IComponent;
public record struct Velocity(float X, float Y) : IComponent;
public record struct Health(int Value) : IComponent, ITracked; // tracked: rows record their last write
public struct Dead : IComponent; // a tag
public record struct Clock(float Dt) : ISingletonComponent; // one value per world
public class MovementSystem : EcsSystem
{
[ForEach, Without<Dead>] // in reads, ref writes
static void Move(ref Position p, in Velocity v, in Clock clock)
{
p.X += v.X * clock.Dt;
p.Y += v.Y * clock.Dt;
}
}
[UpdateAfter<MovementSystem>] // registration order otherwise
public class DeathSystem : EcsSystem
{
[ForEach, Without<Dead>, Changed<Health>] // only healths written since its last run
static void Die(Entity unit, in Health hp)
{
if (hp.Value <= 0) unit.SetDead(); // immediate: later systems see it this tick
}
}
The host owns the world and ticks it:
using var world = new World();
world.SetClock(1 / 30f); // singletons before the first update
world.AddSystem<MovementSystem>();
world.AddSystem<DeathSystem>();
var hero = world.CreateEntity(new Position(0, 0), new Velocity(1, 0), new Health(100));
world.Update(); // 0 B per update once warmed up
hero.SetHealth(0); // a tracked write: DeathSystem sees it
world.Update();
System.Console.WriteLine(hero.IsDead); // True
A full battle server uses every feature (parallel steering, replication by change tracking and removal detection, NPC kinds as prefabs, bags of loot in dynamic buffers, indexes, relations, snapshots, system groups, struct jobs) in one world; it is the battle server benchmark below and the world of the scenario tests. The step-by-step tutorial is Getting started.
The model in one picture
flowchart LR
subgraph Data
E[Entity<br/>id + version]
C[Components<br/>struct : IComponent]
S[Singletons<br/>struct : ISingletonComponent]
end
Y[Systems<br/>EcsSystem: OnUpdate + ForEach]
E -.->|has| C
Y -->|read / write, in order| C
Y -->|read / write| S
| Concept | API | In one line |
|---|---|---|
| World | World |
Owns entities, component storage, singletons and systems. Worlds share nothing. |
| Entity | Entity |
A 16-byte, version-checked handle. Stale handles throw instead of touching a recycled id. |
| Component | struct : IComponent |
Plain per-entity data. An empty struct is a tag. |
| Singleton | struct : ISingletonComponent |
One value per world: clock, configuration, counters, a spatial grid. |
| System | EcsSystem |
One responsibility: OnUpdate plus [ForEach] methods, run in registration order or as [UpdateBefore<T>] / [UpdateAfter<T>] say. |
| Query | [ForEach], ForEach, Query, Count, Any |
Entities that have a set of components, filtered with With / Without / WithAny / Changed / Removed. |
| Prefab | Prefab, world.Instantiate |
A recipe of component values outside every world, copied into entities. |
| Index | IIndexed<TKey>, world.Index<T, TKey>() |
Entities by a component's value, or by the entity a relation component points at. |
When to use it
| Good fit | Probably not |
|---|---|
| Game servers and simulations on .NET 10: MMO maps and zones, AOI, combat | Unity or other runtimes below .NET 10 (net10.0 only) |
| Worlds where state flips constantly (buffs, deaths, spawns): structural changes are immediate and cheap | Code that needs structural changes recorded from many threads at once (use one owner thread and a queue) |
| Long-running processes where GC pauses and unbounded growth matter | Code that wants objects with behavior, or systems calling each other |
One world per thread, many worlds per process; ParallelSystems for heavy independent systems |
Many threads mutating one world's component values without coordination |
Performance
BenchmarkDotNet 0.15.2 with the repository's job (BenchmarkConfig.cs), 4-core Intel Xeon VM at 2.1 GHz (Ubuntu 24.04), .NET 10.0.13, project EasyEcs.Benchmark. The headline benchmark is a realistic server tick,
not a toy loop (what it simulates). "Allocated" is per tick.
| Benchmark | Entities | Mean | Allocated |
|---|---|---|---|
| WorldSimulationBenchmark.Tick | 10,000 | 158 μs | 0 B |
| WorldSimulationBenchmark.Tick | 100,000 | 1.72 ms | 0 B |
| MultiWorldBenchmark.TickAllWorlds (4 worlds × 25k) | 100,000 | 0.92 ms | 0 B |
| BattleServerBenchmark.Tick (the battle server example, every feature) | 100,000 | 2.97 ms | 0 B |
Against v4.0.1 (4.33 ms, measured in an earlier run on the same VM; v4.0.1 is not part of this run) the tick is 2.5x faster.
A [ForEach] system adding Velocity to Position over 10,000 entities (one archetype) takes 9.1 μs, against
12.8 μs for two plain arrays with no ECS at all (its columns are 64-byte aligned). Micro benchmarks and the
per-operation comparison are in
Performance; their ForEach and
Query rows run on a world with two archetypes, so they are not directly comparable to the [ForEach] row.
dotnet run -c Release --project benchmarks/EasyEcs.Benchmark -- --filter '*'
Compared with other ECS libraries
37 head-to-head benchmarks (project EasyEcs.Comparison, same VM) port the same work to Friflo.Engine.ECS 3.6, Arch
2.1 and DefaultEcs 0.17, each library its own idiomatic way, and check in setup that every library computes the same
result. EasyEcs is faster in 24, within the measurement error in 11 and slower in 2. "Its time vs EasyEcs" is the
time of the fastest other library over the time of EasyEcs (2× = it takes twice as long); the site sorts the same
data live (feature by feature).
Clear leads, where the next-fastest library takes at least 1.25 times as long:
Close, EasyEcs ahead by less than that. The full server tick is one of these: most of a tick is iteration over dense columns, bound by memory more than by the library, and Arch and DefaultEcs take 3.42× and 3.71× as long there and allocate 535 KB and 61 KB per tick (EasyEcs and Friflo: 0 B):
Where another library is faster, with the reason from the benchmark's source:
| What is measured | EasyEcs | Faster library | Its time vs EasyEcs | Why |
|---|---|---|---|---|
| Iterate three components over 100,000 entities | 71.0 μs | Friflo.Engine.ECS 70.7 μs | 0.99× (within error) | The same span loop over the same dense columns in both libraries: the loop is bound by memory, not by the library. |
| Add and remove a tag in the passes that find them (10 of 100,000) | 78.2 μs | Friflo.Engine.ECS 75.4 μs | 0.96× (within error) | Friflo defers the changes to its command buffer, so both of its passes are plain span loops. A [ForEach] that may change structure checks after every row that its table did not move, and over 100,000 rows that costs more than 10 deferred changes; from about 1,000 changes on, applying them at once is faster. |
| Iterate in batches, reading entity ids only where needed | 38.5 μs | Friflo.Engine.ECS 37.0 μs | 0.96× (within error) | The same loop over the same rows: Friflo's is written inline in the benchmark, EasyEcs' is generated from a batch [ForEach] method and runs as a system group. |
| Steer 100,000 agents on all cores (parallel query) | 766 μs | Arch 685 μs | 0.89× (within error) | Arch's and Friflo's runners keep worker threads of their own, which win when passes run back to back, as BenchmarkDotNet runs them. EasyEcs wakes thread-pool helpers only while they pay: in a real server tick a dedicated crew measured worse tail latency and more CPU per tick (D22). |
| Scan 100,000 entities for the 1,000 written, without a change filter | 61.4 μs | Friflo.Engine.ECS 53.7 μs | 0.88× | Not the way to do it in EasyEcs: the component is ITracked, so each of the 1,000 writes also stamps its row's change tick, which [Changed<T>] needs and the scan ignores; Friflo's component is not tracked. [Changed<T>] does the same job faster than every library's scan. |
| Find the 10 of 100,000 entities that lost a component | 830 ns | Friflo.Engine.ECS 697 ns | 0.84× (within error) | Friflo's OnComponentRemoved event pushes each id into a list you keep as the removal happens, a cost per removal; [Removed<T>] finds the removals through per-block summaries, a fixed cost per pass that 10 removals do not cover. From 1,000 removals on, EasyEcs leads, with no subscription to write. |
| Create 100,000 three-component entities one by one in a fresh world, nothing reserved | 7.13 ms | Arch 4.77 ms | 0.67× | A fresh EasyEcs world grows its table and entity storage by doubling, and the arrays past 85,000 bytes land on the large object heap; together they pass the budget that sets off a full collection, once per new world (D28). Arch keeps entities in 16 KB chunks, which never reach that heap. Reserve the table with Reserve<T1..Tn>(count) or create the entities with CreateEntities, and EasyEcs is the fastest of the four. |
What each library has built in:
| EasyEcs | Friflo.Engine.ECS | Arch | DefaultEcs | |
|---|---|---|---|---|
| Structural changes inside a query loop, applied at once | ✅ | ❌ command buffer | ⚠️ unguarded | ⚠️ unsafe |
| Change tracking ("rows written since") | ✅ | ❌ | ❌ | ✅ explicit notify |
| Removal detection ("entities that lost a component since") | ✅ | ⚠️ events | ⚠️ events or a marker tag | ✅ WhenRemoved sets |
| Prefabs and cloning | ✅ prefabs outside the world, Clone |
⚠️ clone an entity of the store | ❌ | ⚠️ CopyTo an entity |
| Value index | ✅ | ✅ | ❌ | ✅ |
| Relations with reverse lookup | ✅ | ✅ | ❌ | ❌ |
| In-memory world snapshot | ✅ | ❌ | ❌ | ❌ |
| Systems, groups, parallel systems | ✅ | ✅ (no parallel systems) | ❌ core | ✅ |
| Source-generated systems + analyzer | ✅ | ❌ | ❌ | ❌ |
| 0 B per tick | ✅ | ✅ | ❌ | ❌ |
| Events | ❌ (state is data) | ✅ | ✅ | ✅ |
| Serialization | ✅ Save / Load (Nino) |
✅ JSON | ❌ | ✅ text, binary |
| Unity / netstandard | ❌ net10.0 | ✅ | ✅ | ✅ |
The full matrix, the per-operation numbers and when to pick which library are in Comparison; every feature with what it does, when to use it and what it costs is in Features.
Documentation
The documentation lives at ecs.xgamedev.net; its sources are the markdown files in
docs/content.
| Getting started | Step-by-step tutorial: entities, components, tags, queries, systems, singletons, groups, the update loop. |
| Features | Every feature: what it does, when to use it, when not, what it costs, which scenarios it serves. |
| Comparison | Features and benchmarks against Friflo.Engine.ECS, Arch and DefaultEcs. |
| Guide | One page per concept: entities and components, prefabs and cloning, queries, systems, singletons, structural changes, change tracking and removal detection, dynamic buffers, indexes and relations, hierarchy, groups, cleanup and disable, bulk changes, snapshots, saves, migration and unloading, ref and await, threading, hosting, testing, troubleshooting, analyzer rules. |
| ECS principles | How to design features with entities, components, singletons and systems. |
| Design questions | Why there are no events, what is thread-safe, how to change a component. |
| Samples | Runnable programs in learning order: hello world, a game loop, saving and loading, one world per thread, hot reload, actors. |
| API reference | Every public API with its complexity. |
| Performance guide | Which API to use when, do's and don'ts, benchmarks. |
| Architecture | Storage, memory layout, archetypes, id recycling, iteration safety, generators. |
| Migration guide | What to change when upgrading: between 4.x releases, from v3 to v4 and from v2 to v3. |
The documentation index suggests a reading order.
What's new in 4.7
- Writes that count only when the value changed. A
Mut<T>parameter stamps only the rows a method writes, andSetIfChanged/ the generatedSetHealthIfChanged(…)skip an equal value, so a value recomputed every tick no longer sends every row to[Changed<T>]readers (change tracking). - Replication per client.
[ChangedAny<A, B>]/QueryFilter.ChangedAny<A, B>(since)select rows where any of several components changed, one filter serving every client withSince(ack);WorldOptions.DestroyLogCapacityandworld.DestroyedSincereport the entities destroyed since each client's tick. - Unique keys.
IUniqueIndexed<TKey>names one entity per key (index.Get(key)); a write that would duplicate a key throws before it changes anything (indexes and relations). - Counts without a walk, subtrees without a loop.
index.Find(key).Countsizes a buffer in O(1),KeyCount/TargetCountcount distinct keys and targets, andworld.Descendants(root).AddTo(ids, includeRoot: true)collects the idsMoveEntitiesandSaveEntitiestake (hierarchy). - Spawns with their own components.
world.Instantiate(prefab, new ChildOf(parent), …)in one row copy, and a prefab with members can be instantiated by a system too, during its pass (prefabs). - Work spread over updates.
[ForEach(Slices = N)]visits about 1 / N of the rows per run (systems). - Operating a long-running server.
world.TrimExcess()gives a peak's memory back;SystemStatsadds allocated bytes and visited entities;world.DescribeSchedule()shows the stages and why each system waits (diagnostics). - Restarts that leave runtime state behind.
SaveWithout(writer, exclude)andLoadKeeping(bytes, keep, markWritten: false)(restart). - Generated members for
ChildOf(entity.SetChildOf(parent),world.ChildOfIndex, …) andentity.IsRetired; a[ForEach]method that uses itsEntityonly as an identity no longer runs alone. - Reads that stamp nothing.
world.Read<T1..Tn>()walks a query withref readonlyitems, so a loop that only reads no longer sends rows to[Changed<T>]readers; EECS046 points at suchQueryloops (queries). - Names that say what a call does:
Reserve,DestroyAll,SaveEntitiesWith,LoadKeeping,UnlinkX(target), andDestroyEntities(ids)for a list of ids;entity.Link/Unlink/Linksand the generatedLinkX(target)for relations,ITracked,TryGetSystem,DescribeTables,DestroyLogCapacity, theRetiredtag and more (renames). - Retired entities stay retired. An entity kept alive for its cleanup components (tagged
Retired) is not moved, cloned or brought back bySetAll, reports no removals, and a moved entity leaves its cleanup components behind (cleanup components). AddSingletonon an existing singleton throws instead of resetting it; reset withworld.SetX(…).- Analyzer rules up to EECS052 (calls that compile but throw, lose writes or keep a ref across a structural
change; filters that never match; a
Setright after a creation), and a fix: parallel[ForEach]methods that write tracked components no longer lose change stamps. Upgrading: the migration guide.
What's new in 4.6
- Restarts that resume a world.
world.Load(bytes, markWritten: false)loads a save without change ticks, so[Changed<T>]savers and replicators do not send the whole world again (restart);world.AddSystem<T>(changesFromNow: true)starts a system at the current tick. - Native AOT without warnings, also with tracked and disabled components: CI publishes the battle server natively with warnings as errors and runs it.
What's new in 4.5
- One entity, one job.
entity.Run(ref job)(andRun(ref job, filter)) runs anIForEachEntityjob on a single entity with the guarantees of a pass: change ticks, refs that survive structural changes, in O(1) plus O(1) per component the filter names (one entity). - Group filters through interfaces.
IGroupWith<T>/IGroupWithout<T>give generic groups their filters (IActorGroup<TActor> : IGroupWith<Inbox<TActor>>) (group filters). world.Descendants(root)walks a whole subtree, andLoadEntitiesInto(input, entities, markWritten: false)restores a record without counting it as a change.- No Nino package to add. The EasyEcs package brings Nino with its generator:
[NinoType]components get their formatters from the EasyEcs reference alone (saves). - The analyzer knows the new calls.
entity.RunandLoadEntitiesIntoare structural: rejected in parallel[ForEach]methods (EECS010), in methods that promise no structural change (EECS013) and on other threads (EECS014). - An actors sample.
samples/Actors: one type per kind of actor that is its key component, its system group and the group's filter, with requests run on their entity byentity.Run.
What's new in 4.4
- Records of what persists.
SaveEntitiesWith(output, ids, set)saves only the components of aComponentSet(runtime components need no formatter), andLoadEntitiesIntoloads them onto entities that exist already, each moving table once (a record of what persists). - Saved components can evolve. Saves record types by Nino type id, so
[NinoFormerName]keeps a renamed component's saves, and an unmanaged[NinoType]component is written by its formatter, so aVersionTolerantone may gain members (when the code changed). - Buffers that come and go allocate nothing: a dead
DynamicBuffer<T>'s list goes to the next buffer of its element type. - The save format changed (saves of 4.3 do not load) and EasyEcs builds on Nino 4.0.0-rc.6: see the migration guide.
What's new in 4.3
- Performance rules in the analyzer (EECS025 to EECS034): a
refthat only reads, an unused[ForEach]parameter, a lookup through the visitedEntityon every row, an allocation in code that runs every update, an instance[ForEach]method, a structural change entity by entity over a query, creation one by one in a counted loop,Count() > 0instead ofAny()(warnings: the code costs); the generic call that has a generated member (a suggestion: the same cost, shorter);World.Update()inside a system (an error). Most come with a code fix. Builds that treat warnings as errors may need changes: see the migration guide.
What's new in 4.2
- Reading a missing singleton throws everywhere. A
[ForEach]method's singleton parameter (andworld.SingletonRef<T>()) used to add the default value; it now throwsInvalidOperationExceptionon the system's first run, likeworld.XandGetSingleton<T>(), and the message names the call to add it. A forgottenworld.SetClock(…)fails at once instead of running on a clock with no step;world.GetOrAddClock()is the explicit default. See the migration guide. - A
[ForEach]method with a parameter namedownerbuilds again (the generated code no longer fails with CS0100).
What's new in 4.1
- Archetype tables. Each archetype stores its components as columns of rows (structure of arrays); unmanaged columns are pinned and start on a 64-byte boundary. Iteration walks columns front to back, and tables stay dense: a removed row is filled by the last one at once, or when the pass that removed it ends.
- Removing a component keeps the row. It only clears a presence bit, so states that come and go (stunned, burning, dead) never move data; queries skip, walk or test 64 rows per bit word per table.
- Stricter iteration with immediate changes. A pass visits each entity at most once, and
[ForEach]writes throughrefparameters survive the body's own structural changes. No command buffer, no idempotency filters. - Batch
[ForEach]methods takeSpan<T>/ReadOnlySpan<T>and receive whole runs of rows for SIMD (world.ForEachBatchfor ad-hoc jobs), with anEntitySpanof the run's entities built only where indexed;world.ForEachEntitypasses the handle to struct jobs. - Jobs that cannot change structure (detected by the generator, or
INoStructuralChanges) iterate with no per-entity bookkeeping and freeze the world's structure (a broken promise throws); structural changes check a plain owner flag instead of a lock or an atomic. - Parallel
[ForEach]:[ForEach(Parallel = true)]splits one method's rows across threads, allocation-free (world.ForEachParallel/ForEachEntityParallelfor ad-hoc jobs,World.ParallelChunkRowsrows per chunk); the analyzer rejects methods that could race (EECS010). - Snapshots:
world.Capture()/world.Restore(snapshot)roll a world back in memory (undo, prediction, tests). - Change tracking: components marked
ITrackChangesrecord each row's last write;[Changed<T>]methods visit only the rows written since their system last ran (replication, persistence), andQueryFilter.Changed<T>(since)does the same for queries (Since(tick)moves a kept filter's tick). - Removal detection: removing a tracked component stamps its row, which the entity keeps;
[Removed<T>]methods visit the entities that lostTsince their system last ran, once per removal and with their other components (replicate a fire that went out), andQueryFilter.Removed<T>(since)does the same for queries. Destroyed entities are not reported; EECS016 rejects a method that also requiresT. - Prefabs and cloning:
new Prefab().SetHealth(60, 60).SetNpc()(generated writers, orSet(a, b)) is a recipe of component values that belongs to no world, so no query sees it;world.Instantiate(prefab)(orInstantiate(prefab, span)for a wave, one gate pass) creates entities from it with one row copy each, andentity.Clone()copies a living entity. Copies get their own dynamic buffers, are indexed at once and count as written for change tracking. - Indexes and relations: components implementing
IIndexed<TKey>are found by value (world.Index<T, TKey>().Find(key)); anEntityIdkey makes a relation (ChildOf(EntityId Parent)) whose index lists the children of an entity.SetandCreateEntityre-index at once; writes through arefare rejected (EECS015). - Generated members: every component gets named C# 14 extension members, in the spirit of Entitas but for
structs, tags, singletons and indexes:
hero.Position.X += 1,hero.HasVelocity,hero.SetVelocity(1, 0),hero.IsDead/hero.SetDead(),world.Battle.Tick++,world.ZoneIndex.Find(3),item.Positionon the items of eachQuery<Position, …>the code calls, and on prefabsprefab.SetHealth(60, 60).SetNpc(). Tracked and indexed components get a read-only property, so reading them never counts as a write; the analyzer treatsSetX/RemoveXas the structural changes they are. - New APIs:
WithAny<T>filters ([WithAny<T>]on[ForEach]), bulkCreateEntities/DestroyEntities, per-system timing (WorldOptions.MeasureSystems,system.Stats),entity.Read<T>()(read-only, never a write) andentity.TryGetRef<T>(out found)(optional access byref); Native AOT compatible. DynamicBuffer<T>: a list per entity, held as a component. Its writes take the buffer byref, so each one is a tracked change ([Changed<DynamicBuffer<T>>]sends only the lists that changed) and a write throughindoes not compile; snapshots copy the elements; writes within the capacity allocate nothing.- Disable, cleanup, hierarchy:
entity.Disable<T>()keeps a component's value while queries see it as gone; cleanup components keep a destroyed entity until its resources are released;ChildOfparents destroy their children. BulkSetAll/RemoveAll/DisableAll/EnableAllchange every match 64 rows at a time. - Relations, ordered indexes, groups:
IRelationbuffers link an entity to many targets, found back by target; value indexes walk keys in order (Range,Ascending) for leaderboards and timers;GroupBy<T>()splits tables by a value, so a query for one zone or team walks only its own tables. - Saves and moves:
world.Save/Load(through Nino), andSaveEntities/LoadEntities/MoveEntitieshand a group of entities to another world or process with theirEntityIds rewritten. - Hot-reloaded game logic:
world.RemoveTypes(assembly)takes a plugin's systems and components out of a world so its collectibleAssemblyLoadContextcan unload. - Systems: ordering by dependency (
[UpdateBefore<T>]/[UpdateAfter<T>]),UpdatePhase, errors as data (SystemErrorPolicy.Disable,system.Error),Maybe<T>parameters, static[ForEach]methods outside systems, generic systems, filters on system groups, and nopartialneeded. - Tools:
world.Describe(), a debugger view of entities, and code fixes for the analyzer's diagnostics. - Analyzer rules up to EECS024, errors except three warnings (EECS017
Entityhandles in components, EECS018 schedules that are not constants, EECS020 orderings across groups); among the new errors: EECS011 rejects a[ForEach]method that changes a collection or class held by aninparameter, EECS012 aDynamicBuffer<T>copied by value, EECS013 a structural change in a[ForEach]method that takes noEntityorWorld, EECS014 a structural change in a delegate handed to another thread that races with other changes of the same world, EECS015 a write of an indexed component through aref, EECS016 a[Removed<T>]method that requiresT. - Structural changes belong to the owner thread. They check a plain owner flag instead of a compare-and-swap (a
create/destroy pair is about a quarter faster); one made inside a parallel stage of systems or a parallel
[ForEach], or reentered, throwsInvalidOperationExceptioninstead of tearing the tables. Entity.GetHashCode()is deterministic (Index ^ (Version << 20)) and cheaper (relation lookups hash handles).- Renamed:
WorldOptions.ParallelisWorldOptions.ParallelSystems(apart from[ForEach(Parallel = true)]);Entity.Idis anEntityId(Id.Index,Id.Version), the id to store in components. - Removed:
EcsSystem.Priority(order by dependency instead), theWorld.SystemErrorevent (errors are data),world.DestroyEntity(entity), a second spelling ofentity.Destroy();entity.Add<T>(), which reset a component the entity already had (writeSet(new T(…))/ the generatedSetX(…)to add or replace,GetOrAdd<T>()to add a default only when missing);world.CompactArchetypes()andworld.GetFragmentationStats()(tables stay dense on their own). - Behavior changes:
Queryresults are ref structs (noawaitin the loop, items cannot be stored); refs can be invalidated by structural changes of other entities; iteration order follows table rows; withParallelSystems, a subclass the generator did not see runs alone; structural changes from several threads at once are no longer serialized (owner thread only);AddSingletonresets an existing singleton in place;IForEachjobs receive only the components; stale handles answerHas/TryGetwith false. See the migration guide. - A realistic 100k-entity server tick takes 1.72 ms instead of 4.33 ms; toggling a status component on 10,000 entities 158 μs instead of 338 μs; reading a component through 1,000 random handles 3.33 μs instead of 3.56 μs (the v4.0.1 numbers are from an earlier run on the same VM).
What's new in 4.0
v4 is a rewrite for .NET 10 with standard ECS vocabulary in a single EasyEcs namespace:
Context→World,GroupOf→Query, and a single version-checkedEntityhandle whose accessors returnref T.- Systems are synchronous
EcsSystems with source-generated[ForEach]methods (no UniTask dependency). - Entity ids are recycled; singletons are per world; system groups with
[UpdateInGroup<T>]. - The analyzer enforces the ECS principles (EECS006-EECS008); events were replaced by state-as-data.
WorldOptions.Parallel(ParallelSystemssince 4.1) runs consecutive systems of a group that no[UpdateBefore<T>]/[UpdateAfter<T>]ordering separates together, only when their generated read/write access does not conflict: parallel with the same result as sequential, allocation-free.- A
[ForEach]method may take no component when a[With<T>]names what to query ([ForEach, With<Dead>] static void Remove(Entity e)).
See the migration guide for every rename and behavioral change.
License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Nino (>= 4.0.0-rc.6)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 4.7.0 | 114 | 10/21/2026 |
| 4.6.0 | 86 | 10/20/2026 |
| 4.5.0 | 75 | 10/20/2026 |
| 4.4.0 | 74 | 10/19/2026 |
| 4.3.0 | 421 | 10/19/2026 |
| 4.2.0 | 78 | 10/19/2026 |
| 4.1.0 | 70 | 10/19/2026 |
| 4.0.1 | 404 | 10/15/2026 |
| 4.0.0 | 110 | 10/15/2026 |
| 3.1.1 | 222 | 3/22/2026 |
| 3.0.5 | 464 | 11/21/2025 |
| 3.0.4 | 477 | 11/21/2025 |
| 3.0.3 | 502 | 11/20/2025 |
| 3.0.2 | 319 | 11/6/2025 |
| 3.0.1 | 296 | 11/6/2025 |
| 3.0.0 | 297 | 11/6/2025 |
| 2.1.6 | 742 | 6/5/2025 |
| 2.1.5 | 296 | 6/5/2025 |
| 2.1.4 | 289 | 6/5/2025 |
| 2.1.3 | 277 | 6/5/2025 |