blackbone / fennecs

...the tiny, tiny, high-energy Entity Component System!

... the tiny, tiny, high-energy Entity Component System!

	Okay, what the fox! Another ECS?! We know... oh, we know. 😩 But in a nutshell, fennecs is... 🐾 zero codegen 🐾 minimal boilerplate 🐾 archetype-based 🐾 intuitively relational 🐾 lithe and fast
fennecs is a re-imagining of RelEcs/HypEcs which feels just right* for high performance game development in any modern C# engine. Including, of course, the fantastic Godot.

fennecs.tech (official website)

Grab a cup of coffee to get started, try the Cookbook, view the Demos , and more!

Quickstart: Let's go!

📦> dotnet add package fennecs

At the basic level, all you need is a 🧩component type, a number of small foxes 🦊entities, and a query to ⚙️iterate and modify components, occasionally passing in some uniform 💾data.

// Declare your own component types. (you can also use most existing value or reference types)
using Velocity = System.Numerics.Vector3;

// Create a world. (fyi, World implements IDisposable)
var world = new fennecs.World();

// Spawn an entity into the world with a choice of components. (or add/remove them later)
var entity = world.Spawn().Add<Velocity>();

// Queries are cached, just build them right where you want to use them.
var query = world.Query<Velocity>().Build();

// Run code on all entities in the query. (omit chunksize to parallelize only by archetype)
query.Job(static (ref Velocity velocity, float dt) => {
    velocity.Y -= 9.81f * dt;
}, uniform: Time.Delta, chunkSize: 2048);

💢... when we said minimal boilerplate, we meant it.

Even using the strictest judgment, that's no more than 2 lines of boilerplate! Merely instantiating the world and building the query aren't directly moving parts of the actor/gravity feature we just built, and should be seen as "enablers" or "infrastructure".

The 💫real magic💫 is that none of this brevity compromises on performance.

---

🥊 Comparisons: Punching above our weight?

So how does fennecs compare to other ECSs?

This library is a tiny, tiny ECS with a focus on good performance and great simplicity. But it cares enough to provide a few things you might not expect.

Important

The idea of fennecs was to fill the gaps that the author felt working with various established Entity Component Systems. This is why this matrix is clearly imbalanced, it's a shopping list of things that fennecs does well and was made to do well; and things it may aspire to do but compromised on in order to be able to achieve the others.

(TL;DR - Foxes are soft, choices are hard - Unity dumb, .NET 8 really sharp.)

🥇🥈🥉 (click to expand) ECS Comparison Matrix

Here are some of the key properties where fennecs might be a better or worse choice than its peers. Our resident fennecs have worked with all of these ECSs, and we're happy to answer any questions you might have.

	fennecs	HypEcs	Entitas	Unity DOTS	DefaultECS
Boilerplate-to-Feature Ratio	3-to-1	5-to-1	12-to-1	27-to-1 😱	7-to-1
Entity-Component Queries	✅	✅	✅	✅	✅
Entity-Target Relations	✅	✅	❌	❌	✅ (Map/MultiMap)
Entity-Object-Relations	✅	🟨 (System.Type only)	❌	❌	❌
Target Querying (find all targets of specific relations)	✅	❌	❌	❌	✅
Wildcard Semantics (match multiple relations in 1 query)	✅	❌	❌	❌	❌
Journaling	❌	❌	🟨	✅	❌
Shared Components	✅ (ref types only)	❌	❌	🟨 (restrictive)	✅
Mutable Shared Components	✅	❌	❌	❌	✅
Reference Component Types	✅	❌	❌	❌	❌
Arbitrary Component Types	✅	✅ (value types only)	❌	❌	✅
Structural Change Events	🟨 (planned)	❌	✅	☠️ (unreliable)	❌
Workload Scheduling	🟨 (planned)	❌	❌	✅ (highly static)	✅
No Code Generation Required	✅	✅	❌	❌	🟨 (roslyn addon)
Enqueue Structural Changes at Any Time	✅	✅	✅	🟨 (restrictive)	🟨
Apply Structural Changes at Any Time	❌	❌	✅	❌	❌
Parallel Processing	⭐⭐	⭐	❌	⭐⭐⭐	⭐⭐
Singleton / Unique Components	🟨 (ref types only)	❌	✅	🟨 (per system)	✅

---

💡Highlights / Design Goals

• Modern C# 12 codebase, targeting .NET 8.

• Full Unit Test coverage.

• Benchmarking suite. (Work in Progress)

• Workloads can be easily parallelized across and within Archetypes

• Expressive, queryable relations between Entities and Objects

• Powerfully intuitive ways to access data... fast!

• No code generation and no reflection required.

---

⏩ Nimble: fennecs benchmarks

Preliminary (WIP) benchmarks suggest you can expect to process over 2 million components per millisecond on a 2020 CPU.

We worked hard to minimize allocations, and if using static anonymous methods or delegates, even with uniform parameters, the ECS iterates Entities allocation-free.

fennecs provides a variety of ways to iterate over and modify components, to offer a good balance of control and elegance without compromising too much.

Here are some raw results from our WIP benchmark suite, from the Vector3 operations parts, better ones soon. (don't @ us)

Example: Allocation-free enumeration of a million entities with a System.Numerics.Vector3 component, calculating a cross product against a uniform value, and writing the result back to memory. Processing methods included parallel jobs with different batch/chunk sizes and single threaded runs.

Method	entities	chunk	Mean	StdDev	Jobs	Contention	Alloc
Cross_JobU	1_000_000	32768	349.9 us	1.53 us	32	0.0029	-
Cross_JobU	1_000_000	16384	350.5 us	5.82 us	64	0.0005	-
Cross_JobU	1_000_000	4096	356.1 us	1.78 us	248	0.0083	-
Cross_Job	1_000_000	4096	371.7 us	15.36 us	248	0.0103	-
Cross_Job	1_000_000	32768	381.6 us	4.22 us	32	-	-
Cross_Job	1_000_000	16384	405.2 us	4.56 us	64	0.0039	-
Cross_RunU	1_000_000	-	1,268.4 us	44.76 us	-	-	1 B
Cross_Run	1_000_000	-	1,827.0 us	16.76 us	-	-	1 B

---

🧡 Acknowledgements

Many thanks to Byteron (Aaron Winter) for creating HypEcs and RelEcs, the inspiring libraries that fennecs evolved from.

Neofox was created by Volpeon and is in the Creative Commons CC BY-NC-SA 4.0, the same license applies to all Neofox-derived works made for this documentation.