ECS Architecture Documentation

User Tools

Site Tools

Trace: • entitydestroyedtopic • transformchildrenupdatedtopic • ipacketserializationservice • istaticdatafactory • ientityfactory • ientity
ientity

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
ientity [2026/08/15 08:10] – created divinerientity [2026/08/15 08:25] (current) – diviner
Line 3: Line 3:
 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 [[IComponent|Components]]. 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 [[IComponent|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 [[IEntityStaticData|Entity Static Data]] that defines its composition, and manage the Entity's lifecycle.+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 [[IEntityStaticData|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.** 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.**
Line 11: Line 11:
 === Entity Composition === === Entity Composition ===
  
-The composition of an Entity is defined by its [[IEntityStaticData|Entity Static Data]]. Entity Static Data acts as the definition or archetype from which runtime Entities are created and contains the Component Static Data entries describing which Components belong to the Entity.+The composition of an Entity is defined by its [[IEntityStaticData|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 Static Data ID, the factory:+{{ :2026-04-27_17h50_45.png?669 |}}
  
-* Retrieves the corresponding [[IEntityStaticData|Entity Static Data]]. +Entity creation is handled by the [[IEntityFactory]]. When an Entity is created from a StaticDataID, the factory:
-* 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 Entity Static Data and is assembled automatically by the [[IEntityFactory]].+  * Retrieves the corresponding [[IEntityStaticData|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: Conceptually, the relationship can be viewed as:
  
-**[[IEntityStaticData|Entity Static Data]] → Component Static Data → [[IComponent|Runtime Components]] → [[IEntity|Entity Instance]]**+**[[IEntityStaticData|EntityStaticData]] → ComponentStaticData → [[IComponent|Runtime Components]] → [[IEntity|Entity Instance]]**
  
-Entity Static Data defines **what an Entity is composed of**, Component Static Data defines the initial configuration of those Components, and the runtime Components contain the changing state of the individual 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.
  
 === Entities and Components === === Entities and Components ===
Line 41: Line 43:
 === Static Data ID and Entity Identity === === Static Data ID and Entity Identity ===
  
-The ID stored by [[IEntityStaticData|Entity Static Data]] 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 Static Data ID.+The ID stored by [[IEntityStaticData|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 EntityStaticData 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. 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.
Line 49: Line 51:
 There are two internal implementations of [[IEntity]]: ''ArrayEntity'' and ''SetEntity''. Both expose the same IEntity API and this distinction is intentionally hidden from consumers. 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.+The [[IEntityFactory]] automatically selects the implementation based on the number of Components defined by the EntityStaticData.
  
-* **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. +  * **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.+  * **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. This is purely a runtime optimization. Consumers should always interact with [[IEntity]] and should not depend on which concrete implementation the factory selects.
Line 66: Line 68:
 === Properties === === Properties ===
 ^Property | [[IEntityStaticData]] **StaticData** | ^Property | [[IEntityStaticData]] **StaticData** |
-^Description | Returns the [[IEntityStaticData|Entity Static Data]] from which the Entity was created. This describes the Entity's static definition and Component composition. |+^Description | Returns the [[IEntityStaticData|EntityStaticData]] from which the Entity was created. This describes the Entity's static definition and Component composition. |
  
 === Methods === === Methods ===
 ^Method | void **AddComponents**(Dictionary<Type, [[IComponent]]> components) | ^Method | void **AddComponents**(Dictionary<Type, [[IComponent]]> components) |
-^Description | Attaches supplied Components to the Entity. This method is primarily used by the [[IEntityFactory]] during Entity construction after the Component collection has been generated from the Entity's Static Data and generally does not need to be called directly by consumers. |+^Description | Attaches supplied Components to the Entity. This method is primarily used by the [[IEntityFactory]] during Entity construction after the Component collection has been generated from the Entity's StaticData and should never be called directly by consumers. |
  
 ^Method | T **GetComponent<T>**() where T : [[IComponent]] | ^Method | T **GetComponent<T>**() where T : [[IComponent]] |
ientity.1786781400.txt.gz · Last modified: by diviner
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki