Community Mass Sample

Note: This project requires Git LFS for it to work properly, zip downloads won't work.

Authors:

• Karl Mavko - @Megafunk
• Alvaro Jover - @vorixo

Our very WIP understanding of Unreal Engine 5's experimental Entity Component System (ECS) plugin with a small sample project. We are not affiliated with Epic Games and this system is actively being changed often so this information might not be totally accurate.

We are totally open to contributions, If something is wrong or you think it could be improved, feel free to open an issue or submit a pull request.

Currently built for the Unreal Engine 5 latest version binary from the Epic Games launcher. This documentation will be updated often!

⚠ 5.2 Bugfix ⚠

There is a bug in 5.2 for setting Execution Flags for the world and Mass processors that can be resolved either in the Mass config or engine changes here!

Requirements:

• Unreal Engine 5.3 (latest version as of writing) from the Epic Games launcher
• Git version control:
  • Windows
  • Linux/Unix & macOS
• Git Large File Storage

Download instructions (Windows):

After installing the requirements from above, follow these steps:

1. Right-Click where you wish to hold your project, then press Git Bash Here.

2. Within the terminal, clone the project:

   git clone https://github.com/Megafunk/MassSample.git

3. Pull LFS:

   git lfs pull

4. Once LFS finishes, close the terminal.

Table of Contents

1. Mass
2. Entity Component System
3. Sample Project
4. Mass Concepts
   4.1 Entities
   4.2 Fragments
         4.2.1 Shared Fragments
   4.3 Tags
   4.4 Subsystems
   4.5 The archetype model
         4.5.1 Tags in the archetype model
         4.5.2 Fragments in the archetype model
   4.6 Processors
   4.7 Queries
         4.7.1 Access requirements
         4.7.2 Presence requirements
         4.7.3 Iterating Queries
         4.7.3 Mutating entities with Defer()
   4.8 Traits
   4.9 Observers
         4.9.1 Observers limitations
         4.9.2 Observing multiple Fragment/Tags
   4.10 Multithreading
5. Common Mass operations
   5.1 Spawning entities
   5.2 Destroying entities
   5.3 Operating Entities
6. Mass Plugins and Modules
   6.1 MassEntity
   6.2 MassGameplay
   6.3 MassAI
7. Other Resources

1. Mass

Mass is Unreal's in-house ECS framework! Technically, Sequencer already used one internally but it wasn't intended for gameplay code. Mass was created by the AI team at Epic Games to facilitate massive crowd simulations, but has grown to include many other features as well. It was featured in the Matrix Awakens demo Epic released in 2021.

2. Entity Component System

Mass is an archetype-based Entity Componenet System. If you already know what that is you can skip ahead to the next section.

In Mass, some ECS terminology differs from the norm in order to not get confused with existing unreal code:

Typical Unreal Engine game code is expressed as Actor objects that inherit from parent classes to change their data and functionality based on what they are. In an ECS, an entity is only composed of fragments that get manipulated by processors based on which ECS components they have.

An entity is really just a small unique identifier that points to some fragments. A Processor defines a query that filters only for entities that have specific fragments. For example, a basic "movement" Processor could query for entities that have a transform and velocity component to add the velocity to their current transform position.

Fragments are stored in memory as tightly packed arrays of other identical fragment arrangements called archetypes. Because of this, the aforementioned movement processor can be incredibly high performance because it does a simple operation on a small amount of data all at once. New functionality can easily be added by creating new fragments and processors.

Internally, Mass is similar to the existing Unity DOTS and FLECS archetype-based ECS libraries. There are many more!

3. Sample Project

Currently, the sample features the following:

• A bare minimum movement processor to show how to set up processors.
• An example of how to use Mass spawners for zonegraph and EQS.
• Mass-simulated crowd of cones that parades around the level following a ZoneGraph shape with lanes.
• Linetraced projectile simulation example.
• Simple 3d hashgrid for entities.
• Very basic Mass blueprint integration.
• Grouped niagara rendering for entities.

4. Mass Concepts

Sections

4.1 Entities
4.2 Fragments
4.3 Tags
4.4 Subsystems
4.5 The archetype model
4.6 Processors
4.7 Queries
4.8 Traits
4.9 Observers

4.1 Entities

Small unique identifiers that point to a combination of fragments and tags in memory. Entities are mainly a simple integer ID. For example, entity 103 might point to a single projectile with transform, velocity, and damage data.

4.2 Fragments

Data-only UStructs that entities can own and processors can query on. To create a fragment, inherit from FMassFragment.

USTRUCT()
struct MASSCOMMUNITYSAMPLE_API FLifeTimeFragment : public FMassFragment
{
	GENERATED_BODY()
	float Time;
};

With FMassFragments each entity gets its own fragment data, to share data across many entities, we can use a shared fragment.

4.2.1 Shared Fragments

A Shared Fragment is a type of Fragment that multiple entities can point to. This is often used for configuration common to a group of entities, like LOD or replication settings. To create a shared fragment, inherit from FMassSharedFragment.

USTRUCT()
struct MASSCOMMUNITYSAMPLE_API FVisibilityDistanceSharedFragment : public FMassSharedFragment
{
	GENERATED_BODY()
	
	UPROPERTY()
	float Distance;
};

In the example above, all the entities containing the FVisibilityDistanceSharedFragment will see the same Distance value. If an entity modifies the Distance value, the rest of the entities with this fragment will see the change as they share it through the archetype. Shared fragments are generally added from Mass Traits.

Make sure your shared fragments are Crc hashable or else you may not actually create a new instance when you call GetOrCreateSharedFragmentByHash. You can actually pass in your own hash with GetOrCreateSharedFragmentByHash, which can help if you prefer to control what makes each one unique.

Thanks to this sharing data requirement, the Mass entity manager only needs to store one Shared Fragment for the entities that use it.

4.3 Tags

Empty UScriptStructs that processors can use to filter entities to process based on their presence/absence. To create a tag, inherit from FMassTag.

USTRUCT()
struct MASSCOMMUNITYSAMPLE_API FProjectileTag : public FMassTag
{
	GENERATED_BODY()
};

Note: Tags should never contain member properties.

4.4 Subsystems

Starting in UE 5.1, Mass enhanced its API to support UWorldSubsystems in our Processors. This provides a way to create encapsulated functionality to operate Entities. First, inherit from UWorldSubsystem and define its basic interface alongside your functions and variables:

UCLASS()
class MASSCOMMUNITYSAMPLE_API UMyWorldSubsystem : public UWorldSubsystem
{
	GENERATED_BODY()

public:
	void Write(int32 InNumber);
	int32 Read() const;

protected:
	// UWorldSubsystem begin interface
	virtual void Initialize(FSubsystemCollectionBase& Collection) override;
	virtual void Deinitialize() override;
	// UWorldSubsystem end interface
	
private:
	UE_MT_DECLARE_RW_ACCESS_DETECTOR(AccessDetector);
	int Number = 0;
};

Following next, we present an implementation example of the provided interface above (see MassEntityTestTypes.h):

void UMyWorldSubsystem::Initialize(FSubsystemCollectionBase& Collection)
{
	// Initialize dependent subsystems before calling super
	Collection.InitializeDependency(UMyOtherSubsystemOne::StaticClass());
	Collection.InitializeDependency(UMyOtherSubsystemTwo::StaticClass());
	Super::Initialize(Collection);

	// In here you can hook to delegates!
	// ie: OnFireHandle = FExample::OnFireDelegate.AddUObject(this, &UMyWorldSubsystem::OnFire);
}

void UMyWorldSubsystem::Deinitialize()
{
	// In here you can unhook from delegates
	// ie: FExample::OnFireDelegate.Remove(OnFireHandle);
	Super::Deinitialize();
}

void UMyWorldSubsystem::Write(int32 InNumber)
{
	UE_MT_SCOPED_WRITE_ACCESS(AccessDetector);
	Number = InNumber;
}

int32 UMyWorldSubsystem::Read() const
{
	UE_MT_SCOPED_READ_ACCESS(AccessDetector);
	return Number;
}

The code above is multithread-friendly, hence the UE_MT_X tokens.

Finally, to make this world subsystem compatible with Mass, you must define its subsystem traits, which inform Mass about its parallel capabilities. In this case, our subsystem supports parallel reads:

/**
 * Traits describing how a given piece of code can be used by Mass. 
 * We require author or user of a given subsystem to 
 * define its traits. To do it add the following in an accessible location. 
 */
template<>
struct TMassExternalSubsystemTraits<UMyWorldSubsystem> final
{
	enum
	{
		ThreadSafeRead = true,
		ThreadSafeWrite = false,
	};
};
/**
* this will let Mass know it can access UMyWorldSubsystem on any thread.
*
* This information is being used to calculate processor and query 
* dependencies as well as appropriate distribution of
* calculations across threads.
*/

If you want to use a UWorldSubsystem that has not had its traits defined before and you cannot modify its header explicitly, you can add the subsystem trait information in a separate header file (see MassGameplayExternalTraits.h).

4.5 The archetype model

As mentioned previously, an entity is a unique combination of fragments and tags. Mass calls each of these combinations archetypes. For example, given three different combinations used by our entities, we would generate three archetypes:

The FMassArchetypeData struct represents an archetype in Mass internally.

4.5.1 Tags in the archetype model

Each archetype (FMassArchetypeData) holds a bitset (TScriptStructTypeBitSet<FMassTag>) that contains the tag presence information, whereas each bit in the bitset represents whether a tag exists in the archetype or not.

Following the previous example, Archetype 0 and Archetype 2 contain the tags: TagA, TagC and TagD; while Archetype 1 contains TagC and TagD. Which makes the combination of Fragment A and Fragment B to be split in two different archetypes.

4.5.2 Fragments in the archetype model

At the same time, each archetype holds an array of chunks (FMassArchetypeChunk) with fragment data.

Each chunk contains a subset of the entities included in our archetype where data is organized in a pseudo-struct-of-arrays way:

The following Figure represents the archetypes from the example above in memory:

By having this pseudo-struct-of-arrays data layout divided in multiple chunks, we are allowing a great number of whole-entities to fit in the CPU cache.

This is thanks to the chunk partitoning, since without it, we wouldn't have as many whole-entities fit in cache, as the following diagram displays:

In the above example, the Chunked Archetype gets whole-entities in cache, while the Linear Archetype gets all the A Fragments in cache, but cannot fit each fragment of an entity.

The Linear approach would be fast if we would only access the A Fragment when iterating entities, however, this is almost never the case. Usually, when we iterate entities we tend to access multiple fragments, so it is convenient to have them all in cache, which is what the chunk partitioning provides.

The chunk size (UE::Mass::ChunkSize) has been conveniently set based on next-gen cache sizes (128 bytes per line and 1024 cache lines). This means that archetypes with more bits of fragment data will contain less entities per chunk.

Note: It is relevant to note that a cache miss would be produced every time we want to access a fragment that isn't on cache for a given entity.

4.6 Processors

Processors combine multiple user-defined queries with functions that compute entities.

Unreal classes deriving from UMassProcessor are automatically registered with Mass and added to the EMassProcessingPhase::PrePhsysics processing phase by default. Each EMassProcessingPhase relates to an ETickingGroup, meaning that, by default, processors tick every frame in their given processing phase. They can also be created and registered with the UMassSimulationSubsystem but the common case is to create a new type. Users can configure to which processing phase their processor belongs by modifying the ProcessingPhase variable included in UMassProcessor:

In their constructor, processors can define rules for their execution order, the processing phase and which type of game clients they execute on:

UMyProcessor::UMyProcessor()
{
	// This processor is registered with mass by just existing! This is the default behaviour of all processors.
	bAutoRegisterWithProcessingPhases = true;
	// Setting the processing phase explicitly
	ProcessingPhase = EMassProcessingPhase::PrePhysics;
	// Using the built-in movement processor group
	ExecutionOrder.ExecuteInGroup = UE::Mass::ProcessorGroupNames::Movement;
	// You can also define other processors that require to run before or after this one
	ExecutionOrder.ExecuteAfter.Add(TEXT("MSMovementProcessor"));
	// This executes only on Clients and Standalone
	ExecutionFlags = (int32)(EProcessorExecutionFlags::Client | EProcessorExecutionFlags::Standalone);
	// This processor should not be multithreaded
	bRequiresGameThreadExecution = true;
}

On initialization, Mass creates a dependency graph of processors using their execution rules so they execute in order (ie: In the example above we make sure to move our entities with MSMovementProcessor before we call Execute in UMyProcessor).

The ExecutionFlags variable indicates whether this processor should be executed on Standalone, Server or Client.

By default all processors are multithreaded, however, they can also be configured to run in a single-thread if necessary by setting bRequiresGameThreadExecution to true.

Note: Mass ships with a series of processors that are designed to be inherited and extended with custom logic. ie: The visualization and LOD processors.

4.7 Queries

Queries (FMassEntityQuery) filter and iterate entities given a series of rules based on Fragment and Tag presence.

Processors can define multiple FMassEntityQuerys and should override the ConfigureQueries to add rules to the different queries defined in the processor's header:

void UMyProcessor::ConfigureQueries()
{
	MyQuery.AddTagRequirement<FMoverTag>(EMassFragmentPresence::All);
	MyQuery.AddRequirement<FHitLocationFragment>(EMassFragmentAccess::ReadOnly, EMassFragmentPresence::Optional);
	MyQuery.AddSubsystemRequirement<UMassDebuggerSubsystem>(EMassFragmentAccess::ReadWrite);
	MyQuery.RegisterWithProcessor(*this);

	ProcessorRequirements.AddSubsystemRequirement<UMassDebuggerSubsystem>(EMassFragmentAccess::ReadWrite);
}

To execute queries on a processor, we must register them by calling RegisterWithProcessor passing the processor as a parameter. FMassEntityQuery also offers a parameter constructor that calls RegisterWithProcessor, which is employed in some processors from various Mass modules (ie: UDebugVisLocationProcessor).

ProcessorRequirements is a special query part of UMassProcessor that holds all the UWorldSubsystems that get accessed in the Execute function outside the queries scope. In the example above, UMassDebuggerSubsystem gets accessed within MyQuery's scope (MyQuery.AddSubsystemRequirement) and in the Execution function scope (ProcessorRequirements.AddSubsystemRequirement).

Queries are executed by calling the ForEachEntityChunk member function with a lambda, passing the related FMassEntityManager and FMassExecutionContext.

Processors execute queries within their Execute function:

void UMyProcessor::Execute(FMassEntityManager& EntityManager, FMassExecutionContext& Context)
{
	//Note that this is a lambda! If you want extra data you may need to pass it in the [] operator
	MyQuery.ForEachEntityChunk(EntityManager, Context, [](FMassExecutionContext& Context)
	{
		//Loop over every entity in the current chunk and do stuff!
		for (int32 EntityIndex = 0; EntityIndex < Context.GetNumEntities(); ++EntityIndex)
		{
			// ...
		}
	});
}

Be aware that the index we employ to iterate entities, in this case EntityIndex, doesn't identify uniquely your entities along time, since chunks' disposition may change and an entity that has an index this frame, may be in a different chunk with a different index in the next frame.

Note: Queries can also be created and iterated outside processors.

4.7.1 Access requirements

Queries can define read/write access requirements for Fragments and Subsystems:

FMassFragments use AddRequirement to add access and presence requirement to our fragments. While FMassSharedFragments employ AddSharedRequirement. Finally, UWorldSubsystems use AddSubsystemRequirement.

Here are some basic examples in which we add access rules in two Fragments from a FMassEntityQuery MyQuery:

void UMyProcessor::ConfigureQueries()
{
	// Entities must have an FTransformFragment and we are reading and writing it (EMassFragmentAccess::ReadWrite)
	MyQuery.AddRequirement<FTransformFragment>(EMassFragmentAccess::ReadWrite);
		
	// Entities must have an FMassForceFragment and we are only reading it (EMassFragmentAccess::ReadOnly)
	MyQuery.AddRequirement<FMassForceFragment>(EMassFragmentAccess::ReadOnly);

	// Entities must have a common FClockSharedFragment that can be read and written
	MyQuery.AddSharedRequirement<FClockSharedFragment>(EMassFragmentAccess::ReadWrite);

	// Entities must have a UMassDebuggerSubsystem that can be read and written
	MyQuery.AddSubsystemRequirement<UMassDebuggerSubsystem>(EMassFragmentAccess::ReadWrite);

	// Registering the query with UMyProcessor
	MyQuery.RegisterWithProcessor(*this);
}

ForEachEntityChunks can use the following functions to access ReadOnly or ReadWrite data according to the access requirement:

Find below an example:

MyQuery.ForEachEntityChunk(EntityManager, Context, [this, World = EntityManager.GetWorld()](FMassExecutionContext& Context)
{
	UMassDebuggerSubsystem& Debugger = Context.GetMutableSubsystemChecked<UMassDebuggerSubsystem>(World);

	const auto TransformList = Context.GetFragmentView<FTransformFragment>();
	const auto ForceList = Context.GetMutableFragmentView<FMassForceFragment>();

	for (int32 EntityIndex = 0; EntityIndex < Context.GetNumEntities(); ++EntityIndex)
	{
		FTransform& TransformToChange = TransformList[EntityIndex].GetMutableTransform();
		const FVector DeltaForce = Context.GetDeltaTimeSeconds() * ForceList[EntityIndex].Value;
		TransformToChange.AddToTranslation(DeltaForce);
		Debugger.AddShape(EMassEntityDebugShape::Box, TransformToChange.GetLocation(), 10.f);
	}
});

Note: Tags do not have access requirements since they don't contain data.

4.7.2 Presence requirements

Queries can define presence requirements for Fragments and Tags:

4.7.2.1 Presence requirements in Tags

To add presence rules to Tags, use AddTagRequirement.

void UMyProcessor::ConfigureQueries()
{
	// Entities are considered for iteration without the need of containing the specified Tag
	MyQuery.AddTagRequirement<FOptionalTag>(EMassFragmentPresence::Optional);
	// Entities must at least have the FHorseTag or the FSheepTag
	MyQuery.AddTagRequirement<FHorseTag>(EMassFragmentPresence::Any);
	MyQuery.AddTagRequirement<FSheepTag>(EMassFragmentPresence::Any);
	MyQuery.RegisterWithProcessor(*this);
}

ForEachChunks can use DoesArchetypeHaveTag to determine if the current archetype contains the the Tag:

MyQuery.ForEachEntityChunk(EntityManager, Context, [](FMassExecutionContext& Context)
{
	if(Context.DoesArchetypeHaveTag<FOptionalTag>())
	{
		// I do have the FOptionalTag tag!!
	}

	// Same with Tags marked with Any
	if(Context.DoesArchetypeHaveTag<FHorseTag>())
	{
		// I do have the FHorseTag tag!!
	}
	if(Context.DoesArchetypeHaveTag<FSheepTag>())
	{
		// I do have the FSheepTag tag!!
	}
});

4.7.2.2 Presence requirements in Fragments

Fragments and shared fragments can define presence rules in an additional EMassFragmentPresence parameter through AddRequirement and AddSharedRequirement, respectively.

void UMyProcessor::ConfigureQueries()
{
	// Entities are considered for iteration without the need of containing the specified Fragment
	MyQuery.AddRequirement<FMyOptionalFragment>(EMassFragmentAccess::ReadWrite, EMassFragmentPresence::Optional);
	// Entities must at least have the FHorseFragment or the FSheepFragment
	MyQuery.AddRequirement<FHorseFragment>(EMassFragmentAccess::ReadWrite, EMassFragmentPresence::Any);
	MyQuery.AddRequirement<FSheepFragment>(EMassFragmentAccess::ReadWrite, EMassFragmentPresence::Any);
	MyQuery.RegisterWithProcessor(*this);
}

ForEachChunks can use the length of the Optional/Any fragment's TArrayView to determine if the current chunk contains the Fragment before accessing it:

MyQuery.ForEachEntityChunk(EntityManager, Context, [](FMassExecutionContext& Context)
{
	const auto OptionalFragmentList = Context.GetMutableFragmentView<FMyOptionalFragment>();
	const auto HorseFragmentList = Context.GetMutableFragmentView<FHorseFragment>();	
	const auto SheepFragmentList = Context.GetMutableFragmentView<FSheepFragment>();
	for (int32 i = 0; i < Context.GetNumEntities(); ++i)
	{
		// An optional fragment array is present in our current chunk if the OptionalFragmentList isn't empty
		if(OptionalFragmentList.Num() > 0)
		{
			// Now that we know it is safe to do so, we can compute
			OptionalFragmentList[i].DoOptionalStuff();
		}

		// Same with fragments marked with Any
		if(HorseFragmentList.Num() > 0)
		{
			HorseFragmentList[i].DoHorseStuff();
		}
		if(SheepFragmentList.Num() > 0)
		{
			SheepFragmentList[i].DoSheepStuff();
		}		
	}
});

4.7.3 Mutating entities with Defer()

Within the ForEachEntityChunk we have access to the current execution context. FMassExecutionContext enables us to get entity data and mutate their composition. The following code adds the tag FDead to any entity that has a health fragment with its Health variable less or equal to 0, at the same time, as we define in ConfigureQueries, after the FDead tag is added, the entity won't be considered for iteration (EMassFragmentPresence::None):

void UDeathProcessor::ConfigureQueries()
{
	// All the entities processed in this query must have the FHealthFragment fragment
	DeclareDeathQuery.AddRequirement<FHealthFragment>(EMassFragmentAccess::ReadOnly, EMassFragmentPresence::All);
	// Entities processed by this queries shouldn't have the FDead tag, as this query adds the FDead tag
	DeclareDeathQuery.AddTagRequirement<FDead>(EMassFragmentPresence::None);
	DeclareDeathQuery.RegisterWithProcessor(*this);
}

void UDeathProcessor::Execute(FMassEntityManager& EntityManager, FMassExecutionContext& Context)
{
	DeclareDeathQuery.ForEachEntityChunk(EntityManager, Context, [&,this](FMassExecutionContext& Context)
	{
		auto HealthList = Context.GetFragmentView<FHealthFragment>();

		for (int32 EntityIndex = 0; EntityIndex < Context.GetNumEntities(); ++EntityIndex)
		{
			if(HealthList[EntityIndex].Health <= 0.f)
			{
				// Adding a tag to this entity when the deferred commands get flushed
				FMassEntityHandle EntityHandle = Context.GetEntity(EntityIndex);
				Context.Defer().AddTag<FDead>(EntityHandle);
			}
		}
	});
}

In order to Defer Entity mutations we require to obtain the handle (FMassEntityHandle) of the Entities we wish to modify. FMassExecutionContext holds an array with all the Entity handles. We can access it through two different methods:

The following Subsections will employ the keywords EntityHandle and EntityHandleArray when handling singular or plural operations, respectively.

4.7.3.1 Basic mutation operations

The following Listings define the native mutations that you can defer:

Deferring is commonly done from a processor's FMassExecutionContext with .Defer() but these can be done outside processing with a EntityManager->Defer() call.

Fragments:

Context.Defer().AddFragment<FMyFragment>(EntityHandle);
Context.Defer().RemoveFragment<FMyFragment>(EntityHandle);

Tags:

Context.Defer().AddTag<FMyTag>(EntityHandle);
Context.Defer().RemoveTag<FMyTag>(EntityHandle);
Context.Defer().SwapTags<FOldTag, FNewTag>(EntityHandle);

Destroying entities:

Context.Defer().DestroyEntity(EntityHandle);
Context.Defer().DestroyEntities(EntityHandleArray);

These are all convenient wrappers for the internal template based deferred commands.

4.7.3.2 Advanced mutation operations

There is a set of FCommandBufferEntryBase commands that can be used to defer some more useful entity mutations. The following subsections provide an overview.

4.7.3.2.1 FMassCommandAddFragmentInstanceList

Defers adding new fragment data to an existing entity.

In the example below we mutate the FHitResultFragment with HitResult data, and a FSampleColorFragment fragment with a new color and add (or set if already present) them to an existing entity.

FHitResultFragment HitResultFragment;
FSampleColorFragment ColorFragment = FSampleColorFragment(Color);

// Sets fragment data on an existing entity
EntityManager->Defer().PushCommand<FMassCommandAddFragmentInstances>(Entity, ColorFragment, HitResultFragment);

// It can add single fragment instances as well, and should set data on existing fragments safely
EntityManager->Defer().PushCommand<FMassCommandAddFragmentInstances>(Entity, SomeOtherFragment);

4.7.3.2.2 FMassCommandBuildEntity

Defers Creating an Entity and adds a list of fragments with data to it.

FTransformFragment MyTransformFragment;
MyTransformFragment.SetTransform(FTransform::Identity);

// We build a new entity and add data to it in one command!
EntityManager->Defer().PushCommand<FMassCommandBuildEntity>(ReserverdEntity, MyTransformFragment, SomeOtherFragment);
));

4.7.3.2.3 FMassCommandBuildEntityWithSharedFragments

Similar to FMassCommandBuildEntity but it takes a FMassArchetypeSharedFragmentValues struct to set shared fragment values on the entity as well. This requires some extra work to find or create the shared fragment.

FMassArchetypeSharedFragmentValues SharedFragmentValues;
// This is what traits use to create their shared fragment info as well
FConstSharedStruct& SharedFragment = EntityManager->GetOrCreateConstSharedFragment(MySharedFragment);
SharedFragmentValues.AddConstSharedFragment(SharedFragment);

// MoveTemp is required here...
EntityManager->Defer().PushCommand<FMassCommandBuildEntityWithSharedFragments>(EntityHandle, MoveTemp(SharedFragmentValues), TransformFragment, AnotherFragmentEtc);

4.7.3.2.4 FMassDeferredSetCommand

Defers the execution of the TFunction lambda passed in as a parameter. It is useful for performing Mass-related operations that none of the other commands cover. This is a smart way to handle Actor mutations, as those usually need to happen on the main thread.

EntityManager->Defer().PushCommand<FMassDeferredSetCommand>(
   [&](FMassEntityManager& Manager)
  {
      	// This runs when the deferred commands are flushed
      	MyActor.DoGameThreadWork();
      	// Regular Mass manager calls can happen in here as well. For example:
  	EntityManager.BuildEntity(ReservedEntity, InstanceStructs, EntityTemplate.GetSharedFragmentValues());
  });

Note: The TFunction lambda does have a FMassEntityManager& as a function parameter you should include in every lambda using this command.

FMassDeferredCreateCommand,FMassDeferredSetCommand and the other similarly named types are each templated to set specific EMassCommandOperationType

These are designed to organize deferred commands into different operation types. For example: we want to create entities before we change fragments on them! Here they are and what they do in order when commands are flushed:

4.8 Traits

Traits are C++ defined objects that declare a set of Fragments, Tags and data for authoring new entities in a data-driven way.

To start using traits, create a DataAsset that inherits from UMassEntityConfigAsset and add new traits to it. Each trait can be expanded to set properties if it has any.

In addition, it is possible to inherit Fragments from another UMassEntityConfigAsset by setting it in the Parent field.

Between the many built-in traits offered by Mass, we can find the Assorted Fragments trait, which holds an array of FInstancedStruct that enables adding Fragments to this trait from the editor without the need of creating a new C++ Trait.

Traits are often used to add Shared Fragments in the form of settings. For example, our visualization traits save memory by sharing which mesh they are displaying, parameters etc. Configs with the same settings will share the same Shared Fragment.

4.8.1 Creating a trait

Traits are created by inheriting UMassEntityTraitBase and overriding BuildTemplate. Here is a very basic example:

UCLASS(meta = (DisplayName = "Debug Printing"))
class MASSCOMMUNITYSAMPLE_API UMSDebugTagTrait : public UMassEntityTraitBase
{
	GENERATED_BODY()
public:
	virtual void BuildTemplate(FMassEntityTemplateBuildContext& BuildContext, UWorld& World) const override
	{
		// Adding a tag
		BuildContext.AddTag<FMassSampleDebuggableTag>();
		
		// Adding a fragment
		BuildContext.AddFragment<FTransformFragment>();

		// _GetRef lets us mutate the fragment
		BuildContext.AddFragment_GetRef<FSampleColorFragment>().Color = UserSetColor;
	};

	// Editable in the editor property list for this asset
	UPROPERTY(EditAnywhere)
	FColor UserSetColor;
};

Note: We recommend looking at the many existing traits in this sample and the mass modules for a better overview. For the most part, they are fairly simple UObjects that occasionally have extra code to make sure the fragments are all valid and set correctly.

Shared Fragments

Here is a partial BuildTemplate example for adding a shared struct, which can do some extra work to see if a shared fragment identical to the new one already exists:

	//Create the actual fragment struct and set up the data for it however you like 
	FMySharedSettings MyFragment;
	MyFragment.MyValue = UserSetValue;

	//Get a hash of a FConstStructView of said fragment and store it
	uint32 MySharedFragmentHash = UE::StructUtils::GetStructCrc32(FConstStructView::Make(MyFragment));
	
	//Search the Mass Entity subsystem for an identical struct with the hash. If there are none, make a new one with the set fragment.
	FSharedStruct MySharedFragment = 
		EntityManager.GetOrCreateSharedFragment<FMySharedSettings>(MySharedFragmentHash, MyFragment);

	//Finally, add the shared fragment to the BuildContext!
	BuildContext.AddSharedFragment(MySharedFragment);

4.8.2 Validating traits

Traits can override ValidateTemplate to provide custom validation code for the trait. Native traits use this function to log errors and/or change the BuildContext if required. This function is called after BuildTemplate and is invoked for all of the traits of the current template.

In the following snippet, we check if a field of the trait is nullptr and log an error:

void UMSNiagaraRepresentationTrait::ValidateTemplate(FMassEntityTemplateBuildContext& BuildContext, UWorld& World) const
{
	// If our shared niagara system is null, show an error!
	if (!SharedNiagaraSystem)
	{
		UE_VLOG(&World, LogMass, Error, TEXT("SharedNiagaraSystem is null!"));
		return;
	}
}

4.9 Observers

The UMassObserverProcessor is a type of processor that operates on entities that have just performed a EMassObservedOperation over the Fragment/Tag type observed:

Observers do not run every frame, but every time a batch of entities is changed in a way that fulfills the observer requirements.

For example, this observer changes the color to the entities that just had an FColorFragment added:

UMSObserverOnAdd::UMSObserverOnAdd()
{
	ObservedType = FSampleColorFragment::StaticStruct();
	Operation = EMassObservedOperation::Add;
	ExecutionFlags = (int32)(EProcessorExecutionFlags::All);
}

void UMSObserverOnAdd::ConfigureQueries()
{
	EntityQuery.AddRequirement<FSampleColorFragment>(EMassFragmentAccess::ReadWrite);
}

void UMSObserverOnAdd::Execute(FMassEntityManager& EntityManager, FMassExecutionContext& Context)
{
	EntityQuery.ForEachEntityChunk(EntityManager, Context, [&,this](FMassExecutionContext& Context)
	{
		auto Colors = Context.GetMutableFragmentView<FSampleColorFragment>();
		for (int32 EntityIndex = 0; EntityIndex < Context.GetNumEntities(); ++EntityIndex)
		{
			// When a color is added, make it random!
			Colors[EntityIndex].Color = FColor::MakeRandomColor();
		}
	});
}

4.9.1 Entity Manager Observer calls

At the time of writing, Observers are only triggered by the Mass Manager directly during these specific Entity actions. This mainly comes up due to some of the specific single-entity modifying functions like addfragmenttoentity

• Entity changes in the entity manager:
  • FMassEntityManager::BatchBuildEntities
  • FMassEntityManager::BatchCreateEntities
  • FMassEntityManager::BatchDestroyEntityChunks
  • FMassEntityManager::AddCompositionToEntity_GetDelta
  • FMassEntityManager::RemoveCompositionFromEntity
  • FMassEntityManager::BatchChangeTagsForEntities
  • FMassEntityManager::BatchChangeFragmentCompositionForEntities
  • FMassEntityManager::BatchAddFragmentInstancesForEntities
• The deferred commands that change entity should all call one of the above.

This covers processors and spawners but not single Entity changes from C++.

Thankfully a recent commit on ue5-main has rectified this issue.

If you need to, asking the observer manager to check for changes should only require calling OnCompositionChanged() with the delta of newly added or removed components.

4.9.2 Observing multiple Fragment/Tags

Observers can also be used to observe multiple operations and/or types. For that, override the Register function in UMassObserverProcessor:

// header file
UPROPERTY()
UScriptStruct* MyObserverType = nullptr;

EMassObservedOperation MyOperation = EMassObservedOperation::MAX;


// cpp file 
UMyMassObserverProcessor::UMyMassObserverProcessor()
{
	ObservedType = FSampleColorFragment::StaticStruct();
	Operation = EMassObservedOperation::Add;
	ExecutionFlags = (int32)(EProcessorExecutionFlags::All);
	MyObserverType = FSampleMaterialFragment::StaticStruct();
	MyOperation = EMassObservedOperation::Add;
}

void UMyMassObserverProcessor::Register()
{
	check(ObservedType);
	check(MyObservedType);

	UMassObserverRegistry::GetMutable().RegisterObserver(*ObservedType, Operation, GetClass());
	UMassObserverRegistry::GetMutable().RegisterObserver(*ObservedType, MyOperation, GetClass());
	UMassObserverRegistry::GetMutable().RegisterObserver(*MyObservedType, MyOperation, GetClass());
	UMassObserverRegistry::GetMutable().RegisterObserver(*MyObservedType, Operation, GetClass());
	UMassObserverRegistry::GetMutable().RegisterObserver(*MyObservedType, EMassObservedOperation::Add, GetClass());
}

As noted above, it is possible to reuse the same EMassObservedOperation operation for multiple observed types, and vice-versa.

4.10 Multithreading

Out of the box Mass can spread out work to threads in two different ways:

• Per-Processor threading based on the processor dependency graph by setting the console variable mass.FullyParallel 1

• Per-query parrallel for calls that spread the job of one query over multiple threads by using the command argument ParallelMassQueries=1 for the given Unreal process. This is currently used nowhere in the Mass modules or sample and currently it seems to break when deferring commands from it multiple times a frame.

5. Common Mass operations

This section is designed to serve as a quick reference for how to perform common operations with Mass. As usual, we are open to ideas on how to organize this stuff!!

As a rule of thumb, most entity mutations (adding/removing components, spawning or removing entities) are generally done by deferring them from inside of processors.

5.1 Spawning entities

In this Section we are going to review different methods to spawn entities. First, we review the Mass Spawner, which is useful to spawn entities with predefined data. Then, we'll move to more complex spawning methods that enable us to have fine grained control over the spawning.

5.1.1 Spawn entities with data predefined in the Editor - Mass Spawner

Mass Spawners (AMassSpawner) are useful to spawn entities with static data in the world (predefined CDO and spawning transform).

Mass Spawners require two things to spawn entities:

• An array of entity types: Define which entities to spawn through a UMassEntityConfigAsset.
• An array of Spawn Data Generators (FMassSpawnDataGenerator): Define where to spawn entities (their starting transform).

In the details panel of a AMassSpawner we can find the following:

In the above image, the MEC_DebugVisualize Entity Config is used to spawn 25 entities on BeginPlay (bAutoSpawnOnBeginPlay is set to true).

The spawning location of these entities is generated by the EQS SpawnPoints Generator, which is a built-in generator that uses the Environmental Query System to find locations in the world to spawn. In this example, we are creating a circle of locations around the spawner actor:

The result in game on BeginPlay:

Mass Spawners are placed in the level and can be queried in runtime to trigger spawns by calling DoSpawning() from C++ or Blueprints:

Mass Spawners provide a minimal API to do spawn related operations, following next we provide some of the user-friendly accessible functions from both, blueprints and C++:

• DoSpawning(): Performs the spawning of all the agent types of this spawner.
• DoDespawning(): Despawns all mass agents spawned by this spawner.
• ScaleSpawningCount(float Scale): Scales the spawning counts. Scale is the number to multiply the all counts of each agent types.
• GetCount(): Returns the unscaled count of entities to spawn.
• GetSpawningCountScale(): Returns the number to multiply the all counts of each agent types.

Note: The Matrix demo uses extensively the Mass Spawner system.

5.1.2 Spawn entities with runtime data

In this section we explore more flexible spawn mechanism, in which we are able to spawn entities on demand with runtime data (ie: a passed in location).

These spawning methods can be benefitial when we require to mutate entities on spawn, or when when the spawning data cannot be predefined (ie: the initial transform data for a projectile spawning from a weapon).

5.1.2.1 Batch Spawning

In C++, you can just call BatchCreateEntities() on an instance of a FMassEntityManager by passing in a specific archetype with the number you want. This is actually how AMassSpawner spawns stuff internally! It calls BatchSetEntityFragmentsValues() afterwards to set the initial data on the returned FEntityCreationContext.

5.1.2.2 Single Entity Spawning

Spawning a new Entity only requires asking the Mass Entity Subsystem for a new entity. Here are some common ways to create new entities with data.

Entity with Fragment data

Check out this example with FBuildEntityFromFragmentInstance from the commands section:

We currently recommend not calling UMassEntitySubsystem::BuildEntity directly unless you are sure don't need observers to trigger for the entity. The shared fragments go in there as well as the third function argument!

Entity with Fragment data and Tags

Currently, my best guess is to use FMassCommandBuildEntity and then defer however many Context.Defer().AddTag<FTagType>(EntityReservedEarlier); you need.

A note on observers

It is very important to remember that Observers are only triggered explicitely in certain functions out of the box. Check out the list here.

5.2 Destroying entities

• Deferred

The preferred way of destroying entities is to defer it (especially when processing, to stay safe.)

EntityManager->Defer().DestroyEntities(Entities);
EntityManager->Defer().DestroyEntity(Entity);

• Directly

BatchDestroyEntityChunks is preferred as it calls the observer manager for you. This is only truly safe to call outside of processing on the main thread, like other direct composition changes. UMassSpawnerSubsystem::DestroyEntities calls this as well.

EntityManager->BatchDestroyEntityChunks(Collection) 

5.3 Operating Entities

In this Section we are going to explore the most relevant tools Mass offers to operate Entities. This covers all the get and set operations and structures to work with them (fragment, archetype, tags...).

Note: In cases where we need to operate with Entities outside the current processing context (e.g. avoidance between Entity crowds) it is possible to call all of the regular Mass Subsystem functions or deferred actions on them. This is not ideal for cache coherency but it is nearly unavoidable in gameplay code.

5.2.1 FMassEntityView

FMassEntityView is a struct that eases all kinds of Entity operations. One can be constructed with a FMassEntityHandle and a FMassEntityManager. On construction, the FMassEntityView caches the Entity's archetype data, which will later reduce repeated work needed to retrieve information about the Entity.

Following next, we expose some of the relevant functions of FMassEntityView:

In the following contrived processor example, we check if NearbyEntity is an enemy, if it is, we damage it:

FMassEntityView EntityView(Manager, NearbyEntity.Entity);

//Check if we have a tag
if (EntityView.HasTag<FEnemyTag>())
{
	if(auto DamageOnHitFragment = EntityView.GetFragmentDataPtr<FDamageOnHit>())
	{
	    // Now we defer something to do to the other entity!
 	    FDamageFragment DamageFragment;
 	    DamageFragment.Damage = DamageOnHitFragment.Damage * AttackPower;
        Context.Defer().PushCommand<FMassCommandAddFragmentInstances>(EntityView.GetEntity, DamageFragment);
	}
}

6. Mass Plugins and Modules

This Section overviews the three main Mass plugins and their different modules:

6.1 MassEntity
6.2 MassGameplay
6.3 MassAI

6.1 MassEntity

MassEntity is the main plugin that manages everything regarding Entity creation and storage.

6.2 MassGameplay

The MassGameplay plugin compiles a number of useful Fragments and Processors that are used in different parts of the Mass framework. It is divided into the following modules:

6.2.1 MassCommon
6.2.2 MassMovement
6.2.3 MassRepresentation
6.2.4 MassSpawner
6.2.5 MassActors
6.2.6 MassLOD
6.2.7 MassReplication
6.2.8 MassSignals
6.2.9 MassSmartObjects

6.2.1 MassCommon

Basic fragments like FTransformFragment.

6.2.2 MassMovement

Features an important UMassApplyMovementProcessor processor that moves entities based on their velocity and force.

6.2.3 MassRepresentation

Processors and fragments for rendering entities in the world. They generally use an ISMC to do so, but can also swap entities out with full Unreal actors at user specified distances.

6.2.4 MassSpawner

A highly configurable actor type that can spawn specific entities where you want. There are two ways of choosing locations built in, one that uses an Environmental Query System asset and one that uses a ZoneGraph tag-based query. The Mass Spawner actor appears to be intended for things that spawn all at once initially like NPCs,trees etc, rather than dynamically spawned things like projectiles, for example.

6.2.5 MassActors

A bridge between the general UE5 actor framework and Mass. A type of fragment that turns entities into "Agents" that can exchange data in either direction (or both ways).

6.2.6 MassLOD

LOD Processors that can manage different kinds of levels of detail, from rendering to ticking at different rates based on fragment settings. They are used in visualization and replication currently as well.

6.2.7 MassReplication

Replication support for Mass! Other modules override UMassReplicatorBase to replicate stuff. Entities are given a separate Network ID that gets passed over the network, rather than the EntityHandle. An example showing this is planned for much later.

6.2.8 MassSignals

A system that lets entities send named signals to each other.

6.2.9 MassSmartObjects

Lets entities "claim" SmartObjects to interact with them.

6.3 MassAI

MassAI is a plugin that provides AI features for Mass within a series of modules:

6.3.1 ZoneGraph
6.3.2 StateTree
6.3.3 ...

This section, like the rest of the document, is still work in progress.

6.3.1 ZoneGraph

In-level splines and shapes that use config defined lanes to direct zonegraph pathing things around! Think sidewalks, roads etc. This is the main way Mass Crowd members get around.

6.3.2 StateTree

A new lightweight generic statemachine that can work in conjunction with Mass. One of them is used to give movement targets to the cones in the parade in the sample.

7. Other Resources

7.1 Mass

This section compiles very useful Mass resources to complement this documentation.

Epic Games Official resources:

• [Documentation] MassEntity: Overview of Unreal Engine's MassEntity system.
• [Documentation] Mass Avoidance: Mass Avoidance is a force-based avoidance system integrated with MassEntity.
• [Documentation] Smart Objects: Smart Objects represent a set of activities in the level that can be used through a reservation system.
• [Documentation] StateTree: Overview of the Mass AI StateTree system.
• [Video] State of Unreal : Large Numbers of Entities with Mass: Mario Palermo (Global Unreal Engine 5 Lead Evangelist) showcases Mass in detail in a 30-minute video.

@quabqi's blog posts (Chinese):

• ECS of UE5: MASS framework (1): Mass memory hierarchy, entity and archetype introduction.
• ECS of UE5: MASS framework (2): Mass basic execution.
• ECS of UE5: MASS framework (3): A deep dive in MassGameplay.
• MassAI crowd drawing of UE5 CitySample: How are the pedestrians of the UE5 CitySample handled?

7.2 General Entity Component Systems (ECS)

• Sander's Entity Component System FAQ: This FAQ is for anyone interested in ECS & modern, high performance game development.
• Data-Oriented Design by Richard Fabian: A book detailing a style/paradigm of programming called "Data-Oriented Design". Entity Component System libraries like Mass make data oriented design easy!
• Evolve Your Hierarchy by Mick West: An article demonstrating how to use composition over inheritance to represent game entities.