Basic Concepts
MassEntity is a framework for data-oriented calculations available in Unreal Engine 5.
MassEntity's primary data structure is the Fragment, which represents an atomic piece of data used in calculations. Common examples for Fragments include Transform, Velocity and LOD Index. Fragments can be grouped into collections, and an instance of such a collection can be associated with an ID. This collection instance is called an Entity.
Creating an Entity is similar to class instancing in object-oriented programming. However, instead of strictly declaring a class and its functionality, Entities are built by Fragment composition. These compositions can be changed at runtime. For example, an Entity's composition can include two Fragments such as a Transform and a Velocity.
It is important to note that Fragments and Entities are data-only elements which do not contain any logic.
Archetypes are a collection of Entities of identical composition. Each Archetype is composed of different types of Fragments in a specific configuration. For example, an Archetype can have the Fragment composition of [Transform, Velocity]. This means that all Entities associated with this Archetype will have the same Fragment composition.
Entities in an Archetype are organized in memory Chunks. This ensures best performance when retrieving Fragments associated with Entities of the same Archetype from memory.
Processors are stateless classes that supply the processing logic for Fragments. Processors use EntityQuery to specify which types of Fragments they need to perform their operations. EntityQueries provide batches of Fragments to the Processor without regard to individual Entity identifiers.
A Tag is a trivial Fragment that contains no data. The existence or absence of Tags is used as data itself. Tags are part of an Entity's composition.
A ChunkFragment is a Fragment associated with a Chunk, instead of an Entity. ChunkFragments are used to store per-Chunk data used in managerial processing, such as Level of Detail (LOD) calculations. ChunkFragments are part of an Entity's composition.
Processing the Entities
MassCommandBuffer
Processors can change an Entity's composition by adding or removing Fragments or Tags. However, changing the composition of an Entity while it is being processed would result in that Entity being moved from one Archetype to another.
Processors can request a composition change by using the MassCommandBuffer command. These commands are batch-processed at the end of the current processing batch to avoid the issues mentioned above.
EntityView
Serial processing of Fragments is the most efficient way of performing operations on Entities. However, it is sometimes necessary to access other Entities that are not currently being processed. Processors can accomplish this by using the EntityView command.
EntityView provides a safe and optimized way of accessing data of other Entities not currently in the processing queue.
Subsystems
The MassEntity framework is divided into several subsystems for encapsulation and code organization. All of the subsystems are World subsystems, which means their lifetime is bound to that of the World where they were created.
MassEntity Subsystem
The MassEntity subsystem is the most important subsystem of the MassEntity framework. This subsystem creates and hosts the Entity Archetypes.
This subsystem serves as the interface to Entity operations, such as adding and removing Fragments. It is also responsible for moving Entities between Archetypes. Other subsystems can use the MassCommandBuffer command to asynchronously call this functionality.
MassSimulation Subsystem
The MassSimulation subsystem is responsible for orchestrating cyclic, per-frame runs of MassEntity.This subsystem uses the MassProcessingPhaseManager to separate the Processors into groups that are executed at different engine tick phases.
Note that the MassEntity framework can be used to process data without interacting with the MassSimulation subsystem.
MassSpawner Subsystem
The MassSpawner subsystem spawns and manages the Entities based on the MassSpawners and procedural calls. This subsystem owns a MassEntityTemplateRegistry instance that hosts information on available Entity templates.
Entity Template
Entity Templates are generated from data in the MassEntityConfig assets created in the Unreal Engine Editor. These assets can declare a set of Traits that can be added to an Entity during its creation. In addition, MassEntityConfig assets can have a parent asset and inherit Traits from it.
Traits
A Trait is a collective name for Fragments and Processors supplying a given functionality. Any number of Trait instances can be added to an Entity. Each Trait instance is responsible for adding and configuring Fragments in a way that results in the Entity exhibiting the behavior supplied by the Trait. Common examples for Traits include Avoidance behavior, Look-At Target, and using State Tree.
MassRepresentation Subsystem
The MassRepresentation subsystem is responsible for spawning and managing different visual aspects of Entities. Spawning Entities is done via the UMassActorSpawner subsystem.
MassActorSpawner Subsystem
The MassActorSpawner Subsystem contains all the functionality needed to spawn Actors by the MassEntity framework.
MassActor Subsystem
The MassActor subsystem tracks the Actors that have been spawned by MassEntity.
MassAgent Subsystem
The MassAgent subsystem manages Actors that contain the MassAgent component. These Actors receive functionality from the component, such as additional Traits to the Entity associated with the Actor.
Actors with a MassAgent component can communicate with MassEntity even while not being part of the simulation. Example: the player's location can be used to calculate avoidance for a crowd of agents.
MassEntity can also communicate with any Actor that has the MassAgent component, even if the Actor is outside of the simulation.
MassCrowd Subsystem
The MassCrowd subsystem orchestrates agent crowd movement by using the Zone Graph data available in the level. The subsystem uses the data available regarding lanes and their state to drive the crowd movement.
MassMovement Subsystem
The MassMovement subsystem hosts the spatial hash grid used by agents to gather other nearby agents' locations.
MassStateTree Subsystem
The MassStateTree subsystem is used to integrate the StateTree system with MassEntity. Its main function is to track and manage the StateTree assets used by the MassEntity framework.
MassDebugger Subsystem
The MassDebugger subsystem is the interface to MassEntity's debugging functions. This system provides all relevant data to the Gameplay Debugger system so it can display MassEntity debugging information in the viewport at runtime.