UE::Mass::FEntityBuilder Struct Reference

#include <MassEntityBuilder.h>

Inheritance diagram for UE::Mass::FEntityBuilder:

Classes
struct	FPendingRelationParams
struct	FStructInstanceFindingPredicate

Public Member Functions
UE_API	FEntityBuilder (FMassEntityManager &InEntityManager)
UE_API	FEntityBuilder (const TSharedRef< FMassEntityManager > &InEntityManager)
UE_API	FEntityBuilder (const FEntityBuilder &Other)
UE_API FEntityBuilder &	operator= (const FEntityBuilder &Other)
UE_API FEntityBuilder &	operator= (FEntityBuilder &&Other)
UE_API	~FEntityBuilder ()
UE_API FMassEntityHandle	Commit ()
UE_API FMassEntityHandle	CommitAndReprepare ()
UE_API void	Reprepare ()
UE_API void	Reset (const bool bReleaseEntityHandleIfReserved=true)
UE_API bool	SetReservedEntityHandle (const FMassEntityHandle ReservedEntityHandle)
UE_API bool	AppendDataFromEntity (const FMassEntityHandle SourceEntityHandle)
UE_API bool	CopyDataFromEntity (const FMassEntityHandle SourceEntityHandle)
template<typename T , typename... TArgs> requires (CElement<T> && !(CTag<T> || CChunkFragment<T>))
T &	Add_GetRef (TArgs &&... InArgs)
template<typename T , typename... TArgs> requires (CElement<T> && !(CTag<T> || CChunkFragment<T>))
T &	GetOrCreate (TArgs &&... InArgs)
template<CTag T>
FEntityBuilder &	Add ()
template<CChunkFragment T>
FEntityBuilder &	Add ()
template<typename T , typename... TArgs> requires (CElement<T> && !(CTag<T> || CChunkFragment<T>))
FEntityBuilder &	Add (TArgs &&... InArgs)
UE_API FEntityBuilder &	Add (const FInstancedStruct &ElementInstance)
UE_API FEntityBuilder &	Add (FInstancedStruct &&ElementInstance)
UE_API FEntityBuilder &	Add (TNotNull< const UScriptStruct * > ElementType)
UE_API FEntityBuilder &	AddRelation (UE::Mass::FTypeHandle RelationTypeHandle, FMassEntityHandle OtherEntity, Relations::ERelationRole InputEntityRole=Relations::ERelationRole::Object)
template<UE::Mass::CRelation T>
FEntityBuilder &	AddRelation (FMassEntityHandle OtherEntity, Relations::ERelationRole InputEntityRole=Relations::ERelationRole::Object)
UE_API void	ForEachRelation (const TFunctionRef< bool(FPendingRelationParams &)> &Operator)
template<typename T > requires (CElement<T> && !(CTag<T> || CChunkFragment<T>))
T *	Find ()
void	ConfigureArchetypeCreation (const FMassArchetypeCreationParams &InCreationParams)
UE_API FMassEntityHandle	GetEntityHandle () const
UE_API FMassArchetypeHandle	GetArchetypeHandle ()
bool	IsValid () const
bool	HasReservedEntityHandle () const
bool	IsCommitted () const
TSharedRef< FMassEntityManager >	GetEntityManager ()

Static Public Member Functions
static UE_API FEntityBuilder	Make (const TSharedRef< FMassEntityManager > &InEntityManager, const FMassArchetypeCompositionDescriptor &Composition, TConstArrayView< FInstancedStruct > InitialFragmentValues={}, TConstArrayView< FConstSharedStruct > ConstSharedFragments={}, TConstArrayView< FSharedStruct > SharedFragments={})
static UE_API FEntityBuilder	Make (const TSharedRef< FMassEntityManager > &InEntityManager, const FMassArchetypeCompositionDescriptor &Composition, TArray< FInstancedStruct > &&InitialFragmentValues, TArray< FConstSharedStruct > &&ConstSharedFragments, TArray< FSharedStruct > &&SharedFragments)

Protected Member Functions
UE_API void	CacheSharedFragmentValue ()
UE_API void	CacheArchetypeHandle ()
UE_API void	InvalidateCachedData ()

Detailed Description

FEntityBuilder is a utility struct that provides a convenient way to create and configure entities in the Mass framework. It bridges multiple APIs from FMassEntityManager, MassSpawnerSubsystem, MassEntityTemplates, and other related components, allowing for streamlined entity creation and configuration.

Key Features:

• Can be seamlessly used in place of FMassEntityHandle, allowing for consistent and intuitive usage.
• An entity only gets created once Commit() is called
• Copyable, but copied instances represent new entities without carrying over the reserved entity handle.

Example Usage: { FEntityBuilder Builder(EntityManager); Builder.Add<FTransformFragment>(FTransform(FVector(100, 200, 300))) .Commit(); // the entity gets reserved and built by this call }

{ FEntityBuilder Builder(EntityManager); FMassEntityHandle ReservedEntity = Builder; // Entity handle reserved, can be used for commands. Builder.Add_GetRef<FTransformFragment>().GetMutableTransform().SetTranslation(FVector(100, 200, 300)); Builder.Commit(); // Entity creation is finalized at this point. }

// Example of chaining with FMassEntityManager's MakeEntityBuilder() method: FMassEntityHandle NewEntity = EntityManager.MakeEntityBuilder() .Add<FMassStaticRepresentationTag>() .Add<FTransformFragment>() .Add<FAgentRadiusFragment>(FAgentRadiusFragment{ .Radius = 35.f}) .Add<FMassVelocityFragment>() .Commit();

Current Limitations:

• Committing entities while Mass's processing is in progress is not yet supported; this functionality will be implemented in the near future.
• no support for entity grouping

Constructor & Destructor Documentation

FEntityBuilder() [1/3]

UE::Mass::FEntityBuilder::FEntityBuilder ( FMassEntityManager &  InEntityManager )

explicit

Constructs a FEntityBuilder using a reference to a FMassEntityManager.

FEntityBuilder() [2/3]

UE::Mass::FEntityBuilder::FEntityBuilder ( const TSharedRef< FMassEntityManager > &  InEntityManager )

explicit

Constructs a FEntityBuilder using a shared reference to a FMassEntityManager.

FEntityBuilder() [3/3]

UE::Mass::FEntityBuilder::FEntityBuilder

(

const FEntityBuilder &

Other

)

Copy constructor - copies-create a new instance that represents a new entity and does not carry over reserved handle.

~FEntityBuilder()

UE::Mass::FEntityBuilder::~FEntityBuilder

(

)

Destructor - automatically commits entity creation if not explicitly aborted or committed beforehand.

Member Function Documentation

Add() [1/6]

template<CChunkFragment T>

FEntityBuilder & UE::Mass::FEntityBuilder::Add

(

)

Adds a tag of type T to the entity.

Returns

Reference to this FEntityBuilder for method chaining.

Add() [2/6]

template<CChunkFragment T>

FEntityBuilder & UE::Mass::FEntityBuilder::Add

(

)

Adds a chunk fragment of type T to the entity.

Returns

Reference to this FEntityBuilder for method chaining.

Add() [3/6]

FEntityBuilder & UE::Mass::FEntityBuilder::Add

(

const FInstancedStruct &

ElementInstance

)

Adds a fragment instance to the Entity Builder, treating the contents according to its type

Add() [4/6]

FEntityBuilder & UE::Mass::FEntityBuilder::Add

(

FInstancedStruct &&

ElementInstance

)

Add() [5/6]

template<typename T , typename... TArgs>
requires (CElement<T> && !(CTag<T> || CChunkFragment<T>))

FEntityBuilder & UE::Mass::FEntityBuilder::Add

(

TArgs &&...

InArgs

)

Adds a fragment of type T to the entity, constructing it with the provided arguments.

Returns

Reference to this FEntityBuilder for method chaining.

Add() [6/6]

FEntityBuilder & UE::Mass::FEntityBuilder::Add

(

TNotNull< const UScriptStruct * >

ElementType

)

Adds the ElementType to the target archetype's composition

Add_GetRef()

template<typename T , typename... TArgs>
requires (CElement<T> && !(CTag<T> || CChunkFragment<T>))

T & UE::Mass::FEntityBuilder::Add_GetRef

(

TArgs &&...

InArgs

)

Adds a fragment of type T to the entity and returns a reference to it, constructing it with the provided arguments. The function will assert if an element of type T already exists.

Parameters

T	- The type of fragment to add.
InArgs	- Constructor arguments for initializing the fragment.

Returns

A reference to the added fragment.

AddRelation() [1/2]

template<UE::Mass::CRelation T>

FEntityBuilder & UE::Mass::FEntityBuilder::AddRelation	(	FMassEntityHandle	OtherEntity,
		Relations::ERelationRole	InputEntityRole = Relations::ERelationRole::Object
	)

templated helper function for calling the other AddRelation function

AddRelation() [2/2]

FEntityBuilder & UE::Mass::FEntityBuilder::AddRelation	(	UE::Mass::FTypeHandle	RelationTypeHandle,
		FMassEntityHandle	OtherEntity,
		Relations::ERelationRole	InputEntityRole = Relations::ERelationRole::Object
	)

Adds information about a specific relation instance to be added once the entity gets created. The function will simply store the information without any checks for validity or duplication. If you want to override existing relation data call ForEachRelation.

AppendDataFromEntity()

bool UE::Mass::FEntityBuilder::AppendDataFromEntity

(

const FMassEntityHandle

SourceEntityHandle

)

Appends all element types and values stored by the entity indicated by SourceEntityHandle.

Parameters

SourceEntityHandle

valid handle for a fully constructed, built entity.

Returns

whether the operation was successful

CacheArchetypeHandle()

void UE::Mass::FEntityBuilder::CacheArchetypeHandle ( )

protected

CacheSharedFragmentValue()

void UE::Mass::FEntityBuilder::CacheSharedFragmentValue ( )

protected

Commit()

FMassEntityHandle UE::Mass::FEntityBuilder::Commit

(

)

Finalizes the creation of the entity with the specified fragments and configurations. Note that this function needs to be called manually, no automated entity creation will take place upon builder's destruction.

CommitAndReprepare()

FMassEntityHandle UE::Mass::FEntityBuilder::CommitAndReprepare

(

)

A wrapper for "Commit" call that, once that's done, prepares the builder for another commit, forgetting the handle for the entity just created, and reverting the state back to "ReadyToCommit"

See also

Commit

ConfigureArchetypeCreation()

void UE::Mass::FEntityBuilder::ConfigureArchetypeCreation ( const FMassArchetypeCreationParams &  InCreationParams )

inline

Advanced functionality. Can be used to provide additional parameters that will be used to create the entity's target archetype. Note that these parameters will take effect only if the target archetype doesn't exist yet.

CopyDataFromEntity()

bool UE::Mass::FEntityBuilder::CopyDataFromEntity

(

const FMassEntityHandle

SourceEntityHandle

)

Copies all element types and values stored by the entity indicated by SourceEntityHandle. Any existing builder data will be overridden

Parameters

SourceEntityHandle

valid handle for a fully constructed, built entity.

Returns

whether the operation was successful

Find()

template<typename T >
requires (CElement<T> && !(CTag<T> || CChunkFragment<T>))

T * UE::Mass::FEntityBuilder::Find

(

)

Finds and retrieves a pointer to a fragment of type T if it exists.

Parameters

T	- The type of fragment to find.

Returns

Pointer to the fragment, or nullptr if it does not exist.

ForEachRelation()

void UE::Mass::FEntityBuilder::ForEachRelation

(

const TFunctionRef< bool(FPendingRelationParams &)> &

Operator

)

Calls the provided Operator function for every stored pending relation data instance. The return value of the Operator is used to determine whether the relation data instance should be kept (meaning: return false for each element you want to remove). The potential element removal is stable.

GetArchetypeHandle()

FMassArchetypeHandle UE::Mass::FEntityBuilder::GetArchetypeHandle

(

)

GetEntityHandle()

FMassEntityHandle UE::Mass::FEntityBuilder::GetEntityHandle

(

)

const

Converts the builder to a FMassEntityHandle, reserving the entity handle if not already committed.

GetEntityManager()

TSharedRef< FMassEntityManager > UE::Mass::FEntityBuilder::GetEntityManager ( )

inline

Returns

the EntityManager instance this entity builder is working for

GetOrCreate()

template<typename T , typename... TArgs>
requires (CElement<T> && !(CTag<T> || CChunkFragment<T>))

T & UE::Mass::FEntityBuilder::GetOrCreate

(

TArgs &&...

InArgs

)

Adds a fragment of type T to the entity and returns a reference to it, constructing it with the provided arguments. If a fragment of the given type already exists then it will be overriden and its reference returned.

Returns

A reference to the added fragment.

HasReservedEntityHandle()

bool UE::Mass::FEntityBuilder::HasReservedEntityHandle ( ) const

inline

Returns

whether the builder has an entity handle reserved and the data has not been committed yet

InvalidateCachedData()

void UE::Mass::FEntityBuilder::InvalidateCachedData ( )

protected

IsCommitted()

bool UE::Mass::FEntityBuilder::IsCommitted ( ) const

inline

Returns

whether the builder has already committed the data

IsValid()

bool UE::Mass::FEntityBuilder::IsValid ( ) const

inline

Checks whether the builder is in a valid, expected state

Make() [1/2]

FEntityBuilder UE::Mass::FEntityBuilder::Make ( const TSharedRef< FMassEntityManager > &  InEntityManager, const FMassArchetypeCompositionDescriptor &  Composition, TArray< FInstancedStruct > &&  InitialFragmentValues, TArray< FConstSharedStruct > &&  ConstSharedFragments, TArray< FSharedStruct > &&  SharedFragments  )

static

Creates an instance of FEntityBuilder and populates it with provided data, using move-semantics on said data

Make() [2/2]

FEntityBuilder UE::Mass::FEntityBuilder::Make ( const TSharedRef< FMassEntityManager > &  InEntityManager, const FMassArchetypeCompositionDescriptor &  Composition, TConstArrayView< FInstancedStruct >  InitialFragmentValues = {}, TConstArrayView< FConstSharedStruct >  ConstSharedFragments = {}, TConstArrayView< FSharedStruct >  SharedFragments = {}  )

static

Creates an instance of FEntityBuilder and populates it with provided data

operator=() [1/2]

FEntityBuilder & UE::Mass::FEntityBuilder::operator=

(

const FEntityBuilder &

Other

)

Assignment operator - copies represent new entities, with no carryover of reserved handle from the original.

operator=() [2/2]

FEntityBuilder & UE::Mass::FEntityBuilder::operator=

(

FEntityBuilder &&

Other

)

Move assignment operator - moves over all the data from Other, including the internal state (like whether the entity handle has already been reserved)

Reprepare()

void UE::Mass::FEntityBuilder::Reprepare

(

)

if the builder is in "Committed" state it will roll back to ReadyToSubmit and reset the stored entity handle

Reset()

void UE::Mass::FEntityBuilder::Reset

(

const bool

bReleaseEntityHandleIfReserved = true

)

Resets the builder to its initial state, discarding all previous entity configurations.

Parameters

bReleaseEntityHandleIfReserved

configures what to do with the reserved entity handle, if it's valid.

SetReservedEntityHandle()

bool UE::Mass::FEntityBuilder::SetReservedEntityHandle

(

const FMassEntityHandle

ReservedEntityHandle

)

Stores ReservedEntityHandle as the cached EntityHandle. The ReservedEntityHandle is expected to be valid and represent a reserved entity. These expectations will be checked via ensures. If the existing EntityHandle also represents a valid, reserved entity, that handle will be released.

Returns

whether the ReservedEntityHandle has been stored.

---

The documentation for this struct was generated from the following files:

• Engine/Source/Runtime/MassEntity/Public/MassEntityBuilder.h
• Engine/Source/Runtime/MassEntity/Private/MassEntityBuilder.cpp