Friflo ECS

Friflo.Engine.ECS is a high-performance, high-security Entity Component System (ECS) for C#. It is designed for developers who want a simple, boilerplate-free API without sacrificing performance.

Key characteristics include:

• High Performance & Low Memory: Capable of creating 100,000,000 entities in 1.5 seconds with zero allocations once buffers are sufficiently sized.
• Security: 100% secure C# implementation with no unsafe code, no native DLL bindings, and no access violations.
• Advanced Features: Supports entity relationships, hierarchies, reactive entity events, command buffers for deferred operations, and SIMD support.
• Broad Compatibility: Supports .NET Standard 2.1, .NET 5/6/7/8, WASM, Unity (Mono, AOT/IL2CPP, WebGL), Godot, MonoGame, and Native AOT.

An ECS is a software architecture pattern used for high-performance data processing, common in the gaming industry. It provides two main strengths:

1. Decoupled Code: Data is stored in Components which are assigned to Entities at runtime. Implementation is divided into pure data structures (Component types) and code (Systems) that process them.
2. High Performance: Components are stored in continuous memory to leverage CPU caches (L1, L2, L3) and improve CPU branch prediction by minimizing conditional branches during tight loops.

Friflo ECS follows the standard Entity-Component-System architecture pattern to enable decoupled code and high-performance data processing:

• Entities: Objects that exist at runtime to which data is assigned.
• Components: Pure data structures (Component types) that are assigned to Entities.
• Systems: The logic/code used to process the data stored in Components.

By storing components in continuous memory, the engine leverages CPU caches (L1, L2, L3) and improves branch prediction, making it ideal for high-performance scenarios like game development.

Version 3.0.0 introduced several advanced data modeling features:

• Index / Search: Allows searching for entities with specific component values in $O(1)$ time. Useful for looking up entities by specific IDs (e.g., Guid, long, or string) within a component.
• Relationships: Enables creating links or connections between entities, allowing you to build directed graphs where entities are nodes and relations are edges (e.g., for pathfinding or social networks).
• Relations: Allows adding multiple instances of the same component type to a single entity, which is useful for modeling one-to-many structures like inventories.

You can add Friflo ECS to your C# project using the NuGet package manager or the dotnet CLI. It supports .NET Standard 2.1, .NET 5 through .NET 10, WASM, Unity, Godot, and MonoGame.

dotnet add package Friflo.Engine.ECS

If you are experiencing performance bottlenecks during query execution in Friflo.Engine.ECS, you can use the Friflo.Engine.ECS.Boost extension.

This extension improves performance by using unsafe code to elide array bounds checks during query execution. This is particularly effective for large query result sets, where it can provide a performance boost of approximately 30%.

Warning: While the core Friflo.Engine.ECS library uses only verifiably safe code, Friflo.Engine.ECS.Boost utilizes unsafe code. While this is done to optimize performance, users should be aware that unsafe code can lead to access violation errors if bugs are present in the unsafe implementation.

The mddocs tool (via the Grynwald.MdDocs package) is used to generate API documentation as Markdown. It is preferred for its ability to combine overloaded methods into a single file and maintain stable file paths based on the namespace/class/[constructor|fields|methods|properties] structure.

To generate documentation, you must point the tool to your compiled assembly (e.g., Friflo.Engine.ECS.dll) and provide a configuration file.

# Install the tool globally
dotnet tool install --global Grynwald.MdDocs

# Generate documentation
# Note: Run this from the directory containing your compiled DLL
cd Tests/bin/Release/net8.0
mddocs apireference --assemblies "Friflo.Engine.ECS.dll" --configurationFilePath ../../../../scripts/api-reference.json

To get started with friflo ECS, you need to create an EntityStore (the world), create entities with components, and then use a Query to iterate over them. Components must implement the IComponent interface.

For high-performance scenarios involving millions of entities, consider using optimized enumeration techniques like Enumerate Query Chunks, Parallel Query Job, or Query Vectorization (SIMD).

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;
    });
}

To ensure compatibility with NativeAOT and suppress reflection-related trim warnings (such as IL2070), you can use the UnconditionalSuppressMessage attribute. This is useful when a method is intentionally not called during NativeAOT execution but would otherwise trigger a warning.

[UnconditionalSuppressMessage("ReflectionAnalysis", "IL2070", Justification = "Not called for NativeAOT")]