ECS Architecture Documentation

An IEntity is the central runtime structure of the ECS architecture and the primary container for application state. Most state represented by the ECS exists as an Entity composed of one or more Components.

An Entity itself intentionally contains very little domain-specific state or behavior. Instead, its purpose is to group Components into a single runtime object, provide access to those Components, retain the EntityStaticData that defines its composition, and manage the Entity's lifecycle.

This separation is fundamental to the architecture: the Entity represents the object, while its Components represent the individual pieces of state and functionality that make that object what it is.

Broadcasts Events: EntityIsNullTopic

The composition of an Entity is defined by its EntityStaticData. EntityStaticData acts as the definition or archetype from which runtime Entities are created and contains the ComponentStaticData entries describing which Components belong to the Entity.

Entity creation is handled by the IEntityFactory. When an Entity is created from a StaticDataID, the factory:

• Retrieves the corresponding EntityStaticData.
• Examines the Component Static Data contained within it.
• Determines the runtime IComponent type associated with each Component Static Data type.
• Creates each required Component.
• Associates each Component with the newly created Entity and its corresponding Component Static Data.
• Initializes Component properties configured to receive values from Static Data.
• Attaches the completed Component collection to the Entity.

As a result, users do not normally construct an Entity and manually decide which Components it contains. The Entity's composition originates from its EntityStaticData and is assembled automatically by the IEntityFactory.

Conceptually, the relationship can be viewed as:

EntityStaticData → ComponentStaticData → Runtime Components → Entity Instance

EntityStaticData defines what an Entity is composed of, ComponentStaticData defines the initial configuration of those Components, and the runtime Components contain the changing state of the individual Entity instance.

An Entity can contain many Components, with each Component type representing a particular capability or piece of state. Systems and services can query an Entity for a specific Component rather than depending on a specialized Entity class.

For example, the presence of an ITransformComponent allows an Entity to contain positional state, while an IEntityIdentifierComponent allows it to participate in the framework's UID system. These capabilities are determined by composition rather than inheritance.

An Entity therefore should generally be treated as a collection of capabilities. Code interested in a particular capability should query for the corresponding Component using GetComponent, TryGetComponent or HasComponent.

The ID stored by EntityStaticData identifies the type or definition of Entity being created, not a unique runtime Entity instance. Multiple Entity instances can be created from the same Entity Static Data and therefore share the same StaticDataID.

When an Entity requires a persistent unique runtime identifier, it contains an IEntityIdentifierComponent. That Component's UID is used by systems such as serialization to identify a specific Entity instance independently of its Static Data definition.

There are two internal implementations of IEntity: ArrayEntity and SetEntity. Both expose the same IEntity API and this distinction is intentionally hidden from consumers.

The IEntityFactory automatically selects the implementation based on the number of Components defined by the Entity Static Data.

• ArrayEntity is currently used for Entities with fewer than 10 Components. Components and their Types are stored in arrays and Component lookups perform a small linear search. This avoids the additional overhead of a dictionary for Entities with small Component collections.
• SetEntity is currently used for Entities with 10 or more Components. Components are stored by Type in a dictionary, providing more efficient type-based lookup as the number of Components increases.

This is purely a runtime optimization. Consumers should always interact with IEntity and should not depend on which concrete implementation the factory selects.

Entities should normally be created through the IEntityFactory, which performs Component composition, initialization and registration with the rest of the framework.

Calling Destroy begins the Entity's destruction process. Its Components are first unregistered as Message Broker broadcasters and the Entity transitions into its null state, broadcasting an EntityIsNullTopic. The framework uses this notification to perform the remaining cleanup associated with the Entity.

Destroying an Entity that has already been destroyed has no effect.