fennecs 0.3.5-beta

This is a prerelease version of fennecs.
dotnet add package fennecs --version 0.3.5-beta
NuGet\Install-Package fennecs -Version 0.3.5-beta
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="fennecs" Version="0.3.5-beta" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add fennecs --version 0.3.5-beta
#r "nuget: fennecs, 0.3.5-beta"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install fennecs as a Cake Addin
#addin nuget:?package=fennecs&version=0.3.5-beta&prerelease

// Install fennecs as a Cake Tool
#tool nuget:?package=fennecs&version=0.3.5-beta&prerelease

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

fennecs logo

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: 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

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.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on fennecs:

Repository Stars
Doraku/Ecs.CSharp.Benchmark
Benchmarks of some C# ECS frameworks.
Version Downloads Last updated
0.3.5-beta 45 5/12/2024
0.3.0-beta 46 5/9/2024
0.2.0-beta 85 3/9/2024
0.1.1-beta 189 3/4/2024
0.1.0-beta 61 3/1/2024
0.0.7-pre 55 2/25/2024
0.0.6-pre 49 2/25/2024
0.0.5-pre 49 2/23/2024
0.0.4-pre 54 2/21/2024
0.0.3-pre 56 2/9/2024
0.0.2-pre 48 2/9/2024
0.0.1-pre 58 2/6/2024