Community Mass Sample

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

• 5.6 update: Updated the code to 5.6 with many small improvements and fixes. Apologies for the lack of response to PRs and questions, we have been very busy at work.
• A lot of this documentation is still valid, but I will need to do a full redo of some of the code examples written in the readme as they might use outdated pre-5.6 code. When in doubt the code is always the most reliable indicator of how the API should be called.

Authors:

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

Our somewhat 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!

Requirements:

• Unreal Engine 5.6 (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: bash git clone https://github.com/Megafunk/MassSample.git

3. Pull LFS: bash 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: | 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!

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, *Arch