1. Epic GamesDeveloper
  3. FEntityBuilder

FEntityBuilder

[FEntityBuilder](API\Runtime\MassEntity\FEntityBuilder) is a utility struct that provides a convenient way to create and configure entities in the Mass framework.

API > API/Runtime > API/Runtime/MassEntity

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(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().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() .Add() .Add(FAgentRadiusFragment{ .Radius = 35.f}) .Add() .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
   
Name FEntityBuilder
Type struct
Header File /Engine/Source/Runtime/MassEntity/Public/MassEntityBuilder.h
Include Path #include "MassEntityBuilder.h"

Syntax

struct FEntityBuilder

Derived Classes

Constructors

Name Remarks Include Path Unreal Specifiers

FEntityBuilder ( const FEntityBuilder& Other
)

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

FEntityBuilder ( const TSharedRef< FMassEntityManager >& InEntityManager
)

 Constructs a FEntityBuilder using a shared reference to a FMassEntityManager. MassEntityBuilder.h  

FEntityBuilder ( FMassEntityManager& InEntityManager
)

 Constructs a FEntityBuilder using a reference to a FMassEntityManager. MassEntityBuilder.h  

Destructors

Name Remarks Include Path Unreal Specifiers

~FEntityBuilder()

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

Structs

Name Remarks
FPendingRelationParams Type used to store parameters for relations to be created once the target entity is created.
FStructInstanceFindingPredicate  

Variables

Protected

Name Type Remarks Include Path Unreal Specifiers
ArchetypeCreationParams FMassArchetypeCreationParams Stores optional FMassArchetypeCreationParams, that will be used if the target archetype doesn't exist yet MassEntityBuilder.h  
CachedArchetypeHandle FMassArchetypeHandle   MassEntityBuilder.h  
CachedSharedFragmentValues FMassArchetypeSharedFragmentValues   MassEntityBuilder.h  
Composition FMassArchetypeCompositionDescriptor   MassEntityBuilder.h  
ConstSharedFragments TArray< FInstancedStruct >   MassEntityBuilder.h  
EntityHandle FMassEntityHandle   MassEntityBuilder.h  
EntityManager TSharedRef< FMassEntityManager >   MassEntityBuilder.h  
Fragments TArray< FInstancedStruct >   MassEntityBuilder.h  
RelationsParams TArray< FPendingRelationParams >   MassEntityBuilder.h  
SharedFragments TArray< FInstancedStruct >   MassEntityBuilder.h  
State EState   MassEntityBuilder.h  

Functions

Public

Name Remarks Include Path Unreal Specifiers

FEntityBuilder & Add ( TNotNull< const UScriptStruct* > ElementType
)

 Adds the ElementType to the target archetype's composition MassEntityBuilder.h  

FEntityBuilder & Add ( FInstancedStruct&& ElementInstance
)

   MassEntityBuilder.h  

FEntityBuilder & Add ( const FInstancedStruct& ElementInstance
)

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

FEntityBuilder & Add ( TArgs&&... InArgs
)

 Adds a fragment of type T to the entity, constructing it with the provided arguments. MassEntityBuilder.h  
Adds a chunk fragment of type T to the entity. MassEntityBuilder.h  
Inlines and specializations. MassEntityBuilder.h  

T & 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. MassEntityBuilder.h  
Templated helper function for calling the other AddRelation function MassEntityBuilder.h  

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

 Adds information about a specific relation instance to be added once the entity gets created. MassEntityBuilder.h  

bool AppendDataFromEntity ( const FMassEntityHandle SourceEntityHandle
)

 Appends all element types and values stored by the entity indicated by SourceEntityHandle. MassEntityBuilder.h  
Finalizes the creation of the entity with the specified fragments and configurations. MassEntityBuilder.h  
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" MassEntityBuilder.h  

void ConfigureArchetypeCreation ( const FMassArchetypeCreationParams& InCreationParams
)

 Advanced functionality. MassEntityBuilder.h  

bool CopyDataFromEntity ( const FMassEntityHandle SourceEntityHandle
)

 Copies all element types and values stored by the entity indicated by SourceEntityHandle. MassEntityBuilder.h  

T * Find()

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

void ForEachRelation ( const TFunctionRef< bool(FPendingRelationParams&)>& Operator
)

 Calls the provided Operator function for every stored pending relation data instance. MassEntityBuilder.h  

FMassArchetypeHandle GetArchetypeHandle()

   MassEntityBuilder.h  

FMassEntityHandle GetEntityHandle()

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

TSharedRef< FMassEntityManager > GetEntityManager()

   MassEntityBuilder.h  

T & GetOrCreate ( TArgs&&... InArgs
)

 Adds a fragment of type T to the entity and returns a reference to it, constructing it with the provided arguments. MassEntityBuilder.h  

bool HasReservedEntityHandle()

   MassEntityBuilder.h  

bool IsCommitted()

   MassEntityBuilder.h  

bool IsValid()

 Checks whether the builder is in a valid, expected state MassEntityBuilder.h  

void Reprepare()

 If the builder is in "Committed" state it will roll back to ReadyToSubmit and reset the stored entity handle MassEntityBuilder.h  

void Reset ( const bool bReleaseEntityHandleIfReserved
)

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

bool SetReservedEntityHandle ( const FMassEntityHandle ReservedEntityHandle
)

 Stores ReservedEntityHandle as the cached EntityHandle. MassEntityBuilder.h  

Protected

Name Remarks Include Path Unreal Specifiers

void CacheArchetypeHandle()

   MassEntityBuilder.h  

void CacheSharedFragmentValue()

   MassEntityBuilder.h  

void InvalidateCachedData()

   MassEntityBuilder.h  

Static

Name Remarks Include Path Unreal Specifiers

static void CreateEntityImpl ( FMassEntityManager& EntityManager,
FMassEntityHandle EntityHandle,
const FMassArchetypeHandle& ArchetypeHandle,
const FMassArchetypeSharedFragmentValues& SharedFragmentValues,
TConstArrayView< FInstancedStruct > Fragments,
TConstArrayView< FPendingRelationParams > RelationsParams
)

   MassEntityBuilder.h  

static FEntityBuilder Make ( const TSharedRef< FMassEntityManager >& InEntityManager,
const FMassArchetypeCompositionDescriptor& Composition,
TConstArrayView< FInstancedStruct > InitialFragmentValues,
TConstArrayView< FConstSharedStruct > ConstSharedFragments,
TConstArrayView< FSharedStruct > SharedFragments
)

 Creates an instance of FEntityBuilder and populates it with provided data MassEntityBuilder.h  

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

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

Operators

Name Remarks Include Path Unreal Specifiers
Assignment operator - copies represent new entities, with no carryover of reserved handle from the original. MassEntityBuilder.h  
Move assignment operator - moves over all the data from Other, including the internal state (like whether the entity handle has already been reserved) MassEntityBuilder.h  

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page