Community Mass Sample

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

• 5.7 update: Updated the code to 5.7. I will have to update the readme over time
• 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:

   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](https://docs.unrealengine.com/5.0/en-US/API