Skip to main content

Mass - Concepts

Descriptions of Mass concepts.

Background​

This is part of a series of articles about the Mass system, these articles include:

Mass - Debugging
Mass - Concepts
Mass - Cache Concepts and Optimization

Mass is an Unreal Engine module which implements an Entity Component System or ECS.

Mass Concepts​

A Fragment is a small chunk of data such as a position or a velocity. These can be created in c++ with a class derived from FMassFragment.

A Trait is a set of Fragments and intial values. These can be created in the editor by creating a Data Asset with the structure XXXXX or in c++ with a class derived from UMassEntityTraitBase. A trait assigns fragments to entities. A trait can be thought of as a component.

A Tag is an empty UScriptStruct which can be added to an Archetype to enable a Processor to filter entities based on that tag. Tags are displayed in the Mass debugger so ideally they have meaningful names like "MassVisibilityCulledByDistanceTag".

An Archetype is a unique set of traits and/or tags. If we have traits T1, T2, T3, then (T1, T2) is an archetype and (T1, T3) is a different artchetype. If we have car related fragments FTransformFragment (position), FVelocityFragment (movement speed), and FTrafficAIFragment (AI logic) then (FTransformFragment, FVelocityFragment, FTrafficAIFragment) could define an archetype called Cars. Data is stored by archetypes; multiple occurrences of the same archetype are stored in contiguous memory. An archetype is not the same as a trait; archetypes are composed of traits.

An Entity is a instance of an archetype, so it's data in memory holding the values for a set of Fragments. It can be thought of as a set of fragments associated with a unique ID.

A Processor is an object with functions which operate on a collections of entities. It has a Query which it uses to find the entities to operate on. Processors are normmaly updated every tick. Processors are organised into dependency graph so you can control the sequence of processor calls. Processors are usually auto-registered so the Mass system creates an instance automatically, you don't have to create processor objects.

Mass is always running​

The mass system consists of data (fragments,tags) and processors which act on that data.

Once the mass plugins (listed above) are enabled mass runs as soon as the game is started. Even with us adding any code.

If you make a third-person example project and then:

  • enable the plugins listed above
  • run the game
  • execute the mass.debug console command to bring up the mass debugger, or use Tools > Debug > Mass Debugger
  • then select the play-in-editor instance from the Environment dropdown
  • then click on the Processing Graph tab

This will show you the processors which are running:

If you are running a debug build you can also put a breakpoint inside a processor, such as here:

void UMassZoneGraphAnnotationTagUpdateProcessor::Execute(FMassEntityManager& EntityManager, FMassExecutionContext& Context)
{
	TransientEntitiesToSignal.Reset();

	// Calling super will update the signals, and call SignalEntities() below.
	Super::Execute(EntityManager, Context);

	EntityQuery.ForEachEntityChunk(EntityManager, Context, [this](FMassExecutionContext& Context)
	{
    ...

and see that the processor is running continuously.

Adding a Tag​

If we want to have a MassEntityConfigAsset which is used by a Mass Spawner to spawn zombies, and we want to tag those zombies so we can have a processor query filter them, we add tag:

USTRUCT()
struct SPAWN_API FZombieTag : public FMassTag
{
	GENERATED_BODY()
};

and then add a trait which uses that tag:

UCLASS()
class SPAWN_API UZombieTrait : public UMassEntityTraitBase
{
	GENERATED_BODY()

  public:
	virtual void BuildTemplate( FMassEntityTemplateBuildContext &BuildContext, const UWorld &World ) const override;
};
void UZombieTrait::BuildTemplate( FMassEntityTemplateBuildContext &BuildContext, const UWorld &World ) const
{
	BuildContext.AddTag<FZombieTag>();
}

Then we can add that trait to the MassEntityConfigAsset and the tag will appear in the debugger.

like:

References​