fennecs

The fennecs roadmap outlines the evolution of the ECS from its current beta state toward a stable 1.0.0 release. Key upcoming milestones include:

• Aspects (v0.7.0): Introduction of self-contained collections of Archetypes with contiguous memory layouts to group hot data and reduce fragmentation.
• Unified Entity (v0.7.x): A refactor of the entity struct to improve memory bandwidth and support new key types like hash keys.
• Easy SIMD (v0.8.0+): Methods for SIMD-accelerated arithmetic operations on Component data, inspired by TensorPrimitives.
• Benchmark Suite (v0.9.0+): An internal benchmark suite (fennecs Arena) to ensure performance and memory usage standards.
• Stable Release (v1.0.0): Marks the end of Beta, featuring complete documentation, web support (including Godot via Godot 4.4+), and expanded 3rd party engine demos (Stride, Flax, MonoGame, etc.).

A Component is any piece of data attached to an Entity. Components are the primary way to provide entities with properties, behaviors, and relationships. In fennecs, components can be value types (structs), reference types (classes), tags (zero-size markers), or relationships to other entities and objects.

Whenever a component is added to or removed from an entity, that entity moves to a new Archetype.

// Simple data component
entity.Add(new Position { X = 10, Y = 20 });

// Tag component (zero-size marker)
entity.Add<Enemy>();

// Relation to another entity
entity.Add<ChildOf>(parentEntity);

// Link to a managed object
entity.Add(Link.With(gameObject));

An Entity is a lightweight, immutable 64-bit handle (implemented as a readonly record struct) that represents an identity within a World. It is used to attach components to create composable game state. Entities can be stored in variables, collections, or as components on other entities.

To use an entity, you typically spawn it from a World and then use methods to add or remove data.

var player = world.Spawn();           // Create an entity
player.Add(new Health { Value = 100 }); // Give it components
player.Add<Player>();                   // Tag it as the player

Avoid using primitive types (like float or int) directly as components. Using primitives leads to ambiguity (e.g., which float is speed vs. health?) and prevents you from having multiple components of the same primitive type on a single entity. Instead, wrap primitives in unique record struct types to make components self-documenting and distinct.

Avoid:

entity.Add<float>(10.0f); // Ambiguous

Use Type Wrapping:

public record struct Speed(float Value);
public record struct Health(float Value);

entity.Add(new Speed(10.0f));
entity.Add(new Health(100.0f));

An entity can hold multiple components of the same type if they are distinguished by different match expressions. For example, you can have multiple int components if some are plain values and others are relations to different entities.

entity.Add<int>(100);              // Plain int
entity.Add<int>(50, target1);      // int relation to target1
entity.Add<int>(25, target2);      // int relation to target2

// The entity now contains three distinct int components

// All of these are different components!
entity.Add<int>(100);              // Plain int
entity.Add<int>(50, target1);      // int relation to target1
entity.Add<int>(25, target2);      // int relation to target2

Console.WriteLine(entity.Get<int>(Match.Any).Length);  // 3

When performing Queries or using structural change methods like Remove<C>(Match), you can use Wildcard Match Expressions to target whole categories of secondary keys.

Supported wildcard expressions include:

• Match.Any
• Match.Target
• Entity.Any
• Link.Any

These allow you to, for example, strip all components of a certain type that match a specific relationship pattern in a single operation.

In fennecs, entities with identical combinations of component types share the same Archetype.

This grouping allows the engine to store entities with the same "shape" together in contiguous memory, enabling high-performance iteration. When you add or remove a component that changes an entity's composition, the entity moves to a different Archetype.

Warning: When an entity is despawned, all its components are removed, and the handle becomes a stale reference to a recycled identity.