Some trivially copyable types that work with Fragments:

• FVector
• FQuat
• TWeakObjectPtr
• float

These types are not trivially copyable and cause a Fragment to be not copy safe:

• TInstancedStruct
• Dynamic Array containers, usually (as a rule of thumb) it’s also good to mark it non-trivial when using TArray with a static size since it can be forcibly resized.

This is enforced at compile time. If your Fragment isn’t trivially copyable you’ll hit a static_assert telling you to either fix it or opt out by specializing TMassFragmentTraits(declared in Mass/ExternalSubsystemTraits.h). Opting out is deliberate documentation to Mass that you accepted the cost:

This will mark the entire Fragment as a non-trivial copy type, so it is recommended to make Fragments with only the non-trivial types you intend to use to avoid the least amount of memory impact.

USTRUCT()
struct FMyInstancedStructFragment : public FMassFragment
{
    GENERATED_BODY()
public:
    UPROPERTY(Transient)
    TInstancedStruct<FMyInstancedStruct> Struct;
};

// -SEMI-OPTIONAL-
// This is not necessary for all non-trivial Fragments, but some do require this.
// Makes sure it can't be trivially copied.
template<>
struct TStructOpsTypeTraits<FMyInstancedStructFragment> : public TStructOpsTypeTraitsBase2<FMyInstancedStructFragment>
{
    enum
    {
        WithCopy = false
    };
};

// Notify Mass that it's not a trivial copy fragment.
template<>
struct TMassFragmentTraits<FMyInstancedStructFragment> final
{
    enum
    {
        AuthorAcceptsItsNotTriviallyCopyable = true
    };
};

You can see an example of this with FMassUAFFragment, which holds a TInstancedStruct and uses both that opt-out and TStructOpsTypeTraits<FMassUAFFragment> { WithCopy = false }. Otherwise, you can use your IDE’s search everywhere functionality for examples using TMassFragmentTraits since there are numerous that Epic uses it with.

The cost of a structural change is documented in MassCommands.h

// MassCommands.h
// - Sparse elements are handled in-place (no archetype move). Non-sparse types: single entity move.

So adding 3 Fragments and 1 Tag at once is considered 1 move operation and not four. But modifying Fragments without any Tag add/remove operations is move free.

Ideally it’s recommended to use Tag’s in these general scenarios:

• For infrequent state changes. IE: Stunned state for 3 seconds.
• Skipping whole chunks during queries. IE: Active only query vs dead only query since they’re in different Archetypes.
• Scale of lots of Entities where we want to have less memory for certain state.

For Fragments:

• The state is changing every frame or almost every frame.
• Needing to read values but rarely branching the Archetype.

This approach is the most flexible when operating outside of a Processor where you specify the bitset to add/remove and then call a function on the Entity Manager to update it based on that bitset using a composition wrapper struct.

Currently, the composition struct has some boilerplate, so there may be some improvements that can be done regarding this flow.

FMassFragmentBitSet FragmentsToRemove;
FragmentsToRemove.Add<FMyFragment>();

FMassTagBitSet TagsToRemove;
TagsToRemove.Add<FMyTag>();
TagsToRemove.Add<FMyOtherTag>();

FMassArchetypeCompositionDescriptor Composition(MoveTemp(FragmentsToRemove), MoveTemp(TagsToRemove),
    FMassChunkFragmentBitSet(), FMassSharedFragmentBitSet(), FMassConstSharedFragmentBitSet());

EntityManager.RemoveCompositionFromEntity(Entity, Composition);

The Entity manager has a bunch of functions that can be called to handle Add/Removal of Tags/Fragments, you can do this for a single Entity or for multiple.

These functions are synchronous: they change the Archetype immediately and will assert if called during a processing phase (use the Mass Commands path for that). They support single Entities and batches.

Most batched operations work on FMassArchetypeEntityCollections. You can build them from loose handles with UE::Mass::Utils::CreateEntityCollections(EntityManager, Entities, DuplicatesHandling, OutCollections).

The exception is BatchAddFragmentInstancesForEntities, which takes FMassArchetypeEntityCollectionWithPayload instead. Build those with FMassArchetypeEntityCollectionWithPayload::CreateEntityRangesWithPayload(EntityManager, Entities, DuplicatesHandling, FMassGenericPayloadView(GenericPayload), OutCollections). The payload is what carries the per-Entity Fragment values, which is why that call needs its own collection type.

When working within a Processor you HAVE to use the ::Defer() function to access the Mass Command Buffer to defer those add/remove operations until after the Processor is done to avoid race conditions, this is done using the provided FMassExecutionContext struct.

Context.Defer().AddTag<FMyTag>(Entity);
Context.Defer().RemoveFragment<FMyLastFragment>(Entity);
Context.Defer().PushCommand<FMassCommandAddFragments<FMyFragment, FMyOtherFragment>>(Entity);

Commands flush in a fixed order regardless of push order: Create -> Add -> ChangeComposition -> Set -> Remove -> Destroy (Remove and Destroy share the last slot).