> For the complete documentation index, see [llms.txt](https://friflo.gitbook.io/friflo.engine.ecs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://friflo.gitbook.io/friflo.engine.ecs/readme.md).
# Start
**friflo ECS**, a small and high-performance **C# ECS** - Entity Component System.\
Its an archetype based ECS with focus on performance and simplicity.
**🚀 New in v3.5.0**\
Introduced new pattern to process events on adding/removing components concise in **O(1)**.\
See: [Map components to enums](/friflo.engine.ecs/documentation/events.md#map-components-to-enums) and [Map tags to enums](/friflo.engine.ecs/documentation/events.md#map-tags-to-enums).
**🚀 New in v3.6.0**\
Introduced **Query Generator** to generate highly efficient query code and reduce the amount of boiler plate to a minimum.\
See: [Query Generator](/friflo.engine.ecs/documentation/query-optimization.md#query-generator)
🛈 What is an Entity Component System?
An Entity Component System (**ECS**) is a software architecture pattern. [Wikipedia](https://en.wikipedia.org/wiki/Entity_component_system).\
It is often used in software development for **Games**, **Simulation**, **Analytics** and **In-Memory Database** providing high performant data processing.
An ECS has two major strengths:
1. 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.
2. It provides **high performant query execution** by storing components in continuous memory to leverage L1 CPU cache and its prefetcher.\
It improves CPU branch prediction by minimizing conditional branches when processing components in tight loops. [Data-oriented design ⋅ Wikipedia](https://en.wikipedia.org/wiki/Data-oriented_design).
### Design goals
🔥 High Performance
Optimal and efficient query / system execution.\
Fast entity creation and component changes.
🎯 Simple
Simple API - convenient to debug. No boilerplate code.\
CLS Compliant API - supporting all .NET languages: C#, F#, VB.NET,...
🔄 Low memory footprint
Minimal heap allocations at start phase.\
No heap allocations after internal buffers grown large enough.\
No GC pauses / no frame drops.
🛡️ Reliable
100% verifiably **safe C#**. No **unsafe** code or native bindings.\
Full test coverage. Expressive runtime errors. Actively maintained.\
Your code requires no **Unsafe** quirks for maximum performance.
🤏 Small
Friflo.Engine.ECS.dll size: only 320 kb.\
No code generation. No 3rd party dependencies.
## Overview
A common ECS provide the basic features listed bellow.\
To solve other common use-cases not covered by basic implementations this ECS provide the listed extensions.
### Basic features
> An ECS acts like an in-memory database and stores entities in an [EntityStore](/friflo.engine.ecs/documentation/entity.md#entitystore) aka *World*.\
> An [Entity](/friflo.engine.ecs/documentation/entity.md) is a value type - aka `struct` - with a unique `Id`.
> Data is stored in [Components](/friflo.engine.ecs/documentation/entity.md#component) added to entities.\
> Components are stored highly packed in continuous memory.
> The major strength of an archetype based ECS is efficient and performant [Query](/friflo.engine.ecs/documentation/query.md) execution.\
> [Query filters](/friflo.engine.ecs/documentation/query.md#query-filter) are used to reduce the amount of components returned by the query result.
### Extended features
> Support [Events](/friflo.engine.ecs/documentation/events.md) to subscribe entity changes like adding or removing components.\
> Event handlers can be added to a single `Entity` or the entire `EntityStore`.
> [Index / Search](/friflo.engine.ecs/documentation/component-index.md) to enable lookup entities with specific component values. **v3.0.0**\
> A lookup for a specific component value - aka search - executes in **O(1)** \~ 4 ns.\
> *Possibly the first and only ECS that supports indexing.*
> [Relationships](/friflo.engine.ecs/documentation/relationships.md) to create links between entities. **v3.0.0**\
> A link is directed and bidirectional. Deleting *source* or *target* entity removes a link.
> [Relations](/friflo.engine.ecs/documentation/relations.md) to add multiple *"components"* to an entity. **v3.0.0**\
> Relations are not implemented as components to avoid *archetype fragmentation*.
> [Systems](/friflo.engine.ecs/documentation/systems.md) are optional. They are used to group queries or custom operations.\
> They support logging / monitoring of execution times and memory allocations in realtime.
> [Hierarchy / Scene tree](/friflo.engine.ecs/documentation/entity.md#hierarchy) used to setup a child/parent relationship between entities.\
> An entity in the hierarchy provide direct access to its children and parent.
> [JSON Serialization](/friflo.engine.ecs/documentation/entity.md#json-serialization) to serialize entities or the entire EntityStore as JSON.
### Library
> 100% verifiably safe 🔒 C#. No [*unsafe code*](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/unsafe-code) or native bindings.\
> This prevents *segmentation faults*, *access violations* and *memory corruption*.
> Minimal heap allocations.\
> After internal buffers grown large enough no heap allocation will occur.\
> At this point no garbage collection will be executed. This avoids frame stuttering / lagging caused by GC runs.\
> Especially no allocation when
>
> * Creating or deleting entities
> * Adding or removing components / tags
> * Adding or removing relations or relationships
> * Emitting events
> * Changes in entity hierarchy
> * Query or system execution
> Aims for 100% test coverage:\
> Code coverage: [](https://app.codecov.io/gh/friflo/Friflo.Engine.ECS/tree/main/src/ECS)
## Project
[Release Notes](/friflo.engine.ecs/project/package/release-notes.md) - document all nuget releases.
[Library](/friflo.engine.ecs/project/package/library.md) describes assembly specific characteristics.
[Unity Extension](/friflo.engine.ecs/project/unity-extension.md) with ECS integration in Unity Editor.
### External Links
GitHub:
Discord: [friflo ECS](https://discord.gg/nFfrhgQkb8)
Benchmark: [C# ECS Benchmarks](https://github.com/friflo/ECS.CSharp.Benchmark-common-use-cases)
### GitHub
[](https://github.com/friflo/Friflo.Engine.ECS)
💖 In case you like this project?\
Leave a ⭐ on [GitHub ⋅ friflo/Friflo.Engine.ECS](https://github.com/friflo/Friflo.Engine.ECS)