====== ECS Core Architectural Overview ======

The Core Architecture defines and enforces clean separation between the following architectural layers:

* **Data Model**
  * Static State
    * Entity Static Data
    * Component Static Data 
    * System Static Data
  * Runtime State 
    * [[Entity]]
    * [[Component]]  
* **Business Logic**
  * Services
  * Systems

==== Data Model ====

The Data Model defines the Application State. It is cleanly separated into Runtime Model, state generated, modified and disposed during the Application runtime, and Static Model, immutable state generated and serialized during application design time, and loaded into the application on start up. Static State can also be thought of as Application Configuration. Dependency happens from Runtime Model to Static Model and never the other way around. The general pattern used throughout this architecture is that Static State is loaded into Systems during application start, and then this Static State is used by these systems as instructions to generate Runtime State. 

=== Static State ===

The way static state is serialized depends on the implementor of the architecture. Static State can be serialized as XML, Json, Plain Text or binaries, or Game Engine dependent structures like Unity's Scriptable Objects. The only thing affected is how the [[IStaticDataFactory]] is implemented to load the serialized state into memory. The Unity plug ins provided with this architecture expect the Static State to be serialized as Json with the appropriate serialization settings as defined by the included Serializers. 

The architecture defines two different types of Static State: EntityStaticData (and its dependent ComponentStaticData) and SystemStaticData. 

The EntityStaticData defines instructions for the [[IEntityFactory]] used to generate a type of Transient Runtime State called [[Entity]] (described below). From the same EntityStaticData configuration, multiple Entities can be instantiated. There can also be multiple different EntityStaticData serialized files, each configuring a different type of [[Entity]]. The EntityStaticData class is sealed and concrete. The way it defines different behaviors for different Entities is via composition, by a populated ComponentStaticData array. ComponentStaticData cannot exist on its own, it only makes sense as an entry to an EntityStaticData's Component collection, and each ComponentStaticData needs an implementation. For example, the [[ITransformComponentStaticData]] defines an Entity that has a Transform, and by extension can have a position and rotation in 3D space, as well as be part of Transform hierarchies. EntityStaticData without this specific ComponentStaticData will lack this capability.

Unlike EntityStaticData, SystemStaticData is meant to be implemented by concrete implementations and cannot exist as is. Each implementation can only have one serialized file, and the implementation is registered by the dependency injection framework as Singleton. Therefore every reference to the same SystemStaticData always points to the same object, and that singleton instance can be injected via constructor injection. Where EntityStaticData define Entities and their behaviors, SystemStaticData usually act as configuration files for specific systems and services (hence their name).

=== Runtime State ===

Runtime state is any state created during the lifetime of the Application. As such, it can be any class necessary to service the business logic. However, there is one structure that is treated exceptionally by the architecture: the [[Entity]]. The following diagram showcases how an [[Entity]] structure is composed.

{{ :2026-04-27_17h50_45.png?669 |}}