fennecs 0.1.1-beta

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

visit fennecs.tech for api docs, demos, and the cookbook!

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

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 Position = 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<Position>().Id();

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

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

💢... when we said minimal boilerplate, we foxing 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.

Features: What's in the box?

fennECS is a tiny, tiny ECS with a focus on performance and simplicity. And it cares enough to provide a few things you might not expect. Our competition sure didn't.

💡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

• Entity Structural Changes with O(1) time complexity (per individual change).

• Entity-Component Queries with O(1) runtime lookup time complexity.

• 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, though convenience, especially parallelization, has a tiny GC cost.

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 benchmark suite, from the Vector3 operations parts, better ones soon. (don't @ us)

Executing a System.Numerics.Vector3 cross product and writing the result back with various calling methods

🧡 Acknowledgements

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