We know... oh, we know. π© But in a nutshell, fennecs is...
πΎ zero codegen |
|
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!
π¦>
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);
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.
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) |
β |
-
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.
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 |
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.