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.

<!--- Introduce here table of contents -->

<a name="tocs"></a>

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

<!--ProposalFUNK: How about a "FAQ" of sorts for debugging etc? like: --> <!--Why isn't anything being used in my query?--> <!--When should I use Mass?--> <!--General debug UI info etc--> <!-- REVIEWMEVORI: I would split it in two different subsections: - Common issues - Mass FAQ Although I don't know if these should have their own section each one, or if we can group them under the same section (making the subsections). -->

<a name="mass"></a>

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.

<a name="ecs"></a>

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:

ECS	Mass
Entity	Entity
Component	Fragment
System	Processor

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!

<a name="sample"></a>

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.

<a name="massconcepts"></a>

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

<a name="mass-entities"></a>

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.

<!-- TODO: Document the different ways in which we can identify an entity in mass and their purpose? FMassEntityHandle, FMassEntity, FMassEntityView?? -->

<a name="mass-fragments"></a>

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.

<a name="mass-fragments-sf"></a>

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.

<a name="mass-tags"></a>

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.

<a name="mass-subsystems"></a>

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.

<!-- FIXMEVORI-UE5: Maybe a section exposing the different UE_MT_X tokens? (Get informed about their full scope) -->

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).

<a name="mass-arch-mod"></a>

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.

<a name="mass-arch-mod-tags"></a>

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.

<a name="mass-arch-mod-fragments"></a>

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