MassEntity Overview

Overview of Unreal Engine's MassEntity system.

Choose your operating system:

Windows

macOS

Linux

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.