Repository files navigation

The ECS for finishers 🏁
Leading performance in most ECS aspects.
Performance Ratio - seeC# ECS Benchmark

• FinallyFriflo.Engine.ECS is now in its own new repository!
  The ECS is moved including its git history. Everything not related to the ECS is omitted.

• PublishedFriflo.Engine.ECS.Boost to enableboosted queries with maximum performance.

• UpdatedWiki ⋅ Optimization examples. Changes marked with 🔥Update.

• Released v3.0.0-preview
  Introduced:Entity Relationships 1:1 and 1:many,Relations and full-textSearch in O(1). SeeComponent Types

• New GitHub benchmark repositoryECS.CSharp.Benchmark - Common use-cases

• 🔥 Friflo.Engine.ECS
  • Feature highlights
  • Projects using friflo ECS
  • Demos
  • ECS definition
• ⏩ Examples
  • 🚀 Hello World
  • ⌘ Component Types
  • ⚙️ Systems
• 📖 Wiki
• 🏁 Benchmarks

• 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 ⚙️
• 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
• Debug Tools 🐞: Watch entities, components, tags, relations, query results, systems, ...
  Screenshot - Watch ad-hoc query result in debugger

  
• 100% verifiably safe 🔒 C#. Nounsafe code,native dll bindings andaccess violations.
  Behavior of access violation bugs using unsafe code

  

Complete feature list atWiki ⋅ Features.

Get package onnuget or use the dotnet CLI.

dotnet add package Friflo.Engine.ECS

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."

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 forMonoGame,Unity andGodot.
SeeDemos · GitHub

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

1. It enables writinghighly decoupled code. Data is stored inComponents which are assigned to objects - akaEntities - at runtime.
   Code decoupling is accomplished by dividing implementation in pure data structures (Component types) - and code (Systems) to process them.

2. It enableshigh 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.

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

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

Examples - Optimization
Provide techniques how to improve ECS performance.

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

publicstructVelocity:IComponent{publicVector3value;}publicstaticvoidHelloWorld(){varworld=newEntityStore();for(intn=0;n<10;n++){world.CreateEntity(newPosition(n,0,0),newVelocity{value=newVector3(0,n,0)});}varquery=world.Query<Position,Velocity>();query.ForEachEntity((refPositionposition,refVelocityvelocity,Entityentity)=>{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 andQuery Vectorization - SIMD.
All query optimizations are using the samequery but with different enumeration techniques.

inFriflo.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 adirected graphusing entities asnodes and links or relations asedges.

Use cases for relations:

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

Big shout out tofennecs andflecsfor the challenge to improve the feature set and performance of this project!

Systems are new inFriflo.Engine.ECS v2.0.0

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

Using Systems is optional but they have some significant advantages.

System features

• Enable chaining multiple decoupledQuerySystem classes in aSystemGroup.
  Each group provide aCommandBuffer.

• A system can have state - fields or properties - which can be used as parameters inOnUpdate().
  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 singleSystemRoot instance.
  root.Update() will execute every system on all worlds.

publicstaticvoidHelloSystem(){varworld=newEntityStore();for(intn=0;n<10;n++){world.CreateEntity(newPosition(n,0,0),newVelocity(),newScale3());}varroot=newSystemRoot(world){newMoveSystem(),//  new PulseSystem(),//  new ... multiple systems can be added. The execution order still remains clear.};root.Update(default);}classMoveSystem:QuerySystem<Position,Velocity>{protectedoverridevoidOnUpdate(){Query.ForEachEntity((refPositionposition,refVelocityvelocity,Entityentity)=>{position.value+=velocity.value;});}}

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

structPulsating:ITag{}classPulseSystem:QuerySystem<Scale3>{floatfrequency=4f;publicPulseSystem()=>Filter.AnyTags(Tags.Get<Pulsating>());protectedoverridevoidOnUpdate(){foreach(varentityinQuery.Entities){refvarscale=refentity.GetComponent<Scale3>().value;scale=Vector3.One*(1+0.2f*MathF.Sin(frequency*Tick.time));}}}

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

root.SetMonitorPerf(true);

When enabled system monitoring captures

• Number of system executions.
• System execution duration in ms.
• Memory heap allocations per system in bytes.
• The number of entities matching a query system.

In a game editor like Unity system monitoring is available in theECS System Set component.

Screenshot:ECS System Set component in Play mode

The performance statistics available atSystemPerf.
To get performance statistics on console use:

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

The log result will look like:

stores:1onlastmssummsupdateslastmemsummementities-----------------------------------------------------------------------Systems[2]+0.0763.322101281392|ScaleSystem+0.0382.088106469610000|PositionSystem+0.0381.222106469610000

on                  + enabled  - disabledlast ms, sum ms     last/sum system execution time in msupdates             number of executionslast mem, sum mem   last/sum allocated bytesentities            number of entities matching a QuerySystem

TheGitHub Wiki provide you detailed information about the ECS and illustrate them by examples.

• Examples - General
  Explain fundamental ECS types likeEntity,Component,Tag,Command Buffer, ... and show you how to use them.
  Contains an example forNative AOT integration.

• Examples - Optimization
  Provide you techniques how to improve ECS performance.

• Extensions
  Projects extending Friflo.Engine.ECS with additional features.

• Features
  Integration possibilities, a complete feature list and performance characteristics 🔥.

• Library
  List supported platforms, properties of the assembly dll and build statistics.

• Release Notes
  List of changes of every release available on nuget.

Created a new GitHub repositoryECS.CSharp.Benchmark - Common use-cases.
It compares the performance of multiple ECS projects withsimple benchmarks.
So they can be used as aguide to migrate form one ECS to another.
See discussion ofreddit announcement Post.

Performance comparison using popularECS C# benchmark on GitHub.
Two benchmarks - subset ofGitHub ⋅ Ecs.CSharp.Benchmark + PR #38running on a Mac Mini M2.

SeeBenchmark results.

License

This project is licensed under LGPLv3.

Friflo.Engine.ECS
Copyright © 2024   Ullrich Praetz -https://github.com/friflo