🔥 Friflo.Engine.ECS

The ECS for finishers 🏁

News

moved Friflo.Engine.ECS to its own repository https://github.com/friflo/Friflo.Engine.ECS
The source code / history will be kept as is in this repo. Further development in the new repo.

Feature highlights

Simple API - no boilerplate, rock-solid 🗿 and bulletproof 🛡️
High-performance 🔥 compact ECS
Low memory footprint 👣. Create 100.000.000 entities in 1.5 sec
Zero ⦰ allocations after buffers are large enough. No struct boxing
High performant / type-safe queries ⊆
Efficient multithreaded queries ⇶
Entity component Search in O(1) ∈
Fast batch / bulk operations ⏩
Command buffers / deferred operations ⏭️
Entity relationships and relations ⌘
Entity hierarchy / tree ⪪
Fully reactive / entity events ⚡
Systems / System groups ⚙️
Watch entities, components, relations, tags, query results, systems, ... in debugger 🐞
JSON Serialization 💿
SIMD Support 🧮
Supports .NET Standard 2.1 .NET 5 .NET 6 .NET 7 .NET 8
WASM / WebAssembly, Unity (Mono, AOT/IL2CPP, WebGL), Godot, MonoGame, ... and Native AOT
100% secure C# 🔒. No unsafe code, native dll bindings and access violations. See Wiki ⋅ Library.

Complete feature list at Wiki ⋅ Features.

Get package on nuget or use the dotnet CLI.

dotnet add package Friflo.Engine.ECS

Projects using friflo ECS

Horse Runner DX

Quote from developer: "Just wanted to let you know that Friflo ECS 2.0.0 works like a charm in my little game.
I use it for basically everything (landscape segments, vegetation, players, animations, collisions and even the floating dust particles are entities).
After some optimization there is no object allocation during gameplay - the allocation graph just stays flat - no garbage collection."

Demos

MonoGame Demo is available as WASM / WebAssembly app. Try Demo in your browser.
Demo projects on GitHub below.


MonoGame	Unity	Godot

Desktop Demo performance: Godot 202 FPS, Unity 100 FPS at 65536 entities.
All example Demos - Windows, macOS & Linux - available as projects for MonoGame, Unity and Godot.
See Demos · GitHub

ECS definition

An entity-component-system (ECS) is a software architecture pattern. See ECS ⋅ Wikipedia.
It is often used in the Gaming industry - e.g. Minecraft - and used for high performant data processing.
An ECS provide two strengths:

It enables writing highly decoupled code. Data is stored in Components which are assigned to objects - aka Entities - at runtime.
Code decoupling is accomplished by dividing implementation in pure data structures (Component types) - and code (Systems) to process them.
It enables high performant system execution by storing components in continuous memory to leverage CPU caches L1, L2 & L3.
It improves CPU branch prediction by minimizing conditional branches when processing components in tight loops.

⏩ Examples

This section contains two typical use cases when using an ECS.
More examples are in the GitHub Wiki.

Examples - General
Explain fundamental ECS types like Entity, Component, Tag, Command Buffer, ... and how to use them.

Examples - Optimization
Provide techniques how to improve ECS performance.

🚀 Hello World

The hello world examples demonstrates the creation of a world, some entities with components
and their movement using a simple ForEachEntity() call.

public struct Velocity : IComponent { public Vector3 value; }

public static void HelloWorld()
{
    var world = new EntityStore();
    for (int n = 0; n < 10; n++) {
        world.CreateEntity(new Position(n, 0, 0), new Velocity{ value = new Vector3(0, n, 0)});
    }
    var query = world.Query<Position, Velocity>();
    query.ForEachEntity((ref Position position, ref Velocity velocity, Entity entity) => {
        position.value += velocity.value;
    });
}

In case of moving (updating) thousands or millions of entities an optimized approach can be used.
See: Enumerate Query Chunks, Parallel Query Job and Query Vectorization - SIMD.
All query optimizations are using the same query but with different enumeration techniques.

⌘ Component Types

in Friflo.Engine.ECS v3.0.0-preview.2

For specific use cases there is now a set of specialized component interfaces providing additional features.
Note: Newly added features do not affect the behavior or performance of existing features.

The specialized component types enable entity relationships, relations and full-text search.
Typical use case for entity relationships in a game are:

Attack systems
Path finding / Route tracing
Model social networks. E.g friendship, alliances or rivalries
Build any type of a directed graph using entities as nodes and links or relations as edges.

Use cases for relations:

Inventory systems
Add multiple components of the same type to an entity

Use case / Example	Component interface type	Description
Entity Relationships	Link Component	A single link on an entity referencing another entity
	Link Relation	Multiple links on an entity referencing other entities
Relations	Relation Component	Add multiple components of same type to an entity
Search & Range queries	Indexed Component	Full text search of component fields executed in O(1). Range queries on component fields having a sort order.

Big shout out to fennecs and flecs for the challenge to improve the feature set and performance of this project!

⚙️ Systems

Systems are new in Friflo.Engine.ECS v2.0.0

Systems in ECS are typically queries.
So you can still use the world.Query<Position, Velocity>() shown in the "Hello World" example.

Using Systems is optional but they have some significant advantages.

System features

Enable chaining multiple decoupled QuerySystem classes in a SystemGroup.
Each group provide a CommandBuffer.
A system can have state - fields or properties - which can be used as parameters in OnUpdate().
The system state can be serialized to JSON.
Systems can be enabled/disabled or removed.
The order of systems in a group can be changed.
Systems have performance monitoring build-in to measure execution times and memory allocations.
If enabled systems detected as bottleneck can be optimized.
A perf log (see example below) provide a clear overview of all systems their amount of entities and impact on performance.
Multiple worlds can be added to a single SystemRoot instance.
root.Update() will execute every system on all worlds.

public static void HelloSystem()
{
    var world = new EntityStore();
    for (int n = 0; n < 10; n++) {
        world.CreateEntity(new Position(n, 0, 0), new Velocity(), new Scale3());
    }
    var root = new SystemRoot(world) {
        new MoveSystem(),
    //  new PulseSystem(),
    //  new ... multiple systems can be added. The execution order still remains clear.
    };
    root.Update(default);
}
        
class MoveSystem : QuerySystem<Position, Velocity>
{
    protected override void OnUpdate() {
        Query.ForEachEntity((ref Position position, ref Velocity velocity, Entity entity) => {
            position.value += velocity.value;
        });
    }
}

A valuable strength of an ECS is establishing a clear and decoupled code structure.
Adding the PulseSystem below to the SystemRoot above is trivial.
This system uses a foreach (var entity in Query.Entities) as an alternative to Query.ForEachEntity((...) => {...})
to iterate the query result.

class PulseSystem : QuerySystem<Scale3>
{
    float frequency = 4f;
    
    protected override void OnUpdate() {
        foreach (var entity in Query.Entities) {
            ref var scale = ref entity.GetComponent<Scale3>().value;
            scale = Vector3.One * (1 + 0.2f * MathF.Sin(frequency * Tick.time));
        }
    }
}

⏱ System monitoring

System performance monitoring is disabled by default.
To enable monitoring call:

root.SetMonitorPerf(true);

The performance statistics available at SystemPerf.
To get performance statistics on console use:

root.Update(default);
Console.WriteLine(root.GetPerfLog());

The log result will look like:

stores: 1                  on   last ms    sum ms   updates  last mem   sum mem  entities
---------------------      --  --------  --------  --------  --------  --------  --------
Systems [2]                 +     0.076     3.322        10       128      1392
| ScaleSystem               +     0.038     2.088        10        64       696     10000
| PositionSystem            +     0.038     1.222        10        64       696     10000

on                  + enabled  - disabled
last ms, sum ms     last/sum system execution time in ms
updates             number of executions
last mem, sum mem   last/sum allocated bytes
entities            number of entities matching a QuerySystem

📖 Wiki

Wiki moved to gitbook.io ➜ friflo.gitbook.io/friflo.engine.ecs

🏁 ECS Benchmarks

ECS.CSharp.Benchmark - Common use-cases

Created a new GitHub repository ECS.CSharp.Benchmark - Common use-cases.
It compares the performance of multiple ECS projects with simple benchmarks.
So they can be used as a guide to migrate form one ECS to another.
See discussion of reddit announcement Post.

License

This project is licensed under LGPLv3.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!