/ue-mass-entity

Mass Fragment Reference

Built-in element types, shared fragments and traits, with the header and Build.cs module each one needs in UE 5.8. Headers under Mass/ belong to the MassCore runtime module; the rest come from the MassGameplay, MassAI and MassCrowd plugins (all Experimental in 5.8).

Element base types

All declared in Mass/EntityElementTypes.h (module MassCore), all deriving from FMassElement. MassEntityTypes.h pulls them in transitively.

Per-entity fragments

FTransformFragment

Transform is protected. Use GetTransform() (const ref), GetMutableTransform() (mutable ref) and SetTransform(const FTransform&). A converting constructor from FTransform exists, which is what makes Builder.Add<FTransformFragment>(SpawnTransform) work.

This type moved into MassCore. MassCommonFragments.h only #includes it; MassCommon lists MassCore as a public dependency (MassCommon.Build.cs:19) so it resolves transitively, but include Mass/EntityFragments.h and add MassCore explicitly.

FMassVelocityFragment / FMassForceFragment

Both hold a single FVector Value. Forces are integrated into velocity, velocity into FTransformFragment, by the processors in Movement/MassMovementProcessors.h (UMassApplyMovementProcessor).

FMassMoveTargetFragment

DesiredSpeed is an FMassInt16Real, not a float. The action is private: read it with GetCurrentAction() / GetPreviousAction() and change it with CreateNewAction(EMassMovementAction, const UWorld&). EMassMovementAction (MassNavigationTypes.h) is Stand, Move, Animate.

Chunk fragments

A chunk fragment derives from FMassChunkFragment and holds one instance per memory chunk. Add it to a template with BuildContext.AddChunkFragment<T>(), bind it with Query.AddChunkRequirement<T>(Access, Presence), and read it with Context.GetChunkFragment<T>(). Chunk fragments are the only per-entity-adjacent data a SetChunkFilter predicate may read.

FMassRepresentationLODFragment is not a chunk fragment — it is a per-entity FMassFragment.

Shared and const shared fragments

FMassMovementParameters has no deceleration field; deceleration falls out of the force/velocity integration.

FMassRepresentationParameters::LODRepresentation maps each EMassLOD::Type slot to an EMassRepresentationType, which is how an entity is promoted to an actor up close and demoted back to an ISM instance at distance.

Bind shared data with Query.AddSharedRequirement<T>(Access, Presence) or Query.AddConstSharedRequirement<T>(Presence); read it with Context.GetMutableSharedFragment<T>() / Context.GetConstSharedFragment<T>(). Presence::Any is rejected for both.

Traits

Traits derive from UMassEntityTraitBase (MassEntityTraitBase.h, module MassSpawner) and implement BuildTemplate(FMassEntityTemplateBuildContext&, const UWorld&) const. Optional validation is ValidateTemplate(const FMassEntityTemplateBuildContext&, const UWorld&, FAdditionalTraitRequirements&) const — three parameters.

UMassVisualizationTrait is soft-deprecated (its display name is "DEPRECATED Visualization"). It is still the base class of the movable and stationary traits and still owns the shared properties StaticMeshInstanceDesc (FStaticMeshInstanceVisualizationDesc), SkinnedMeshInstanceDesc, HighResTemplateActor, LowResTemplateActor, Params (FMassRepresentationParameters) and LODParams (FMassVisualizationLODParameters). Author new content against UMassMovableVisualizationTrait or UMassStationaryVisualizationTrait.

Assign traits to a UMassEntityConfigAsset (a UDataAsset in MassEntityConfigAsset.h); AMassSpawner lists config assets in EntityTypes and spawns Count entities.

Enums

EMassRepresentationType (MassRepresentationTypes.h, MassRepresentation)

UE::Mass::Representation::IsValidMeshRepresentation() returns true for the two instanced-mesh values.

EMassLOD (MassLODTypes.h, MassLOD)

EMassLOD is a namespaced enum — namespace EMassLOD { enum Type : int { High, Medium, Low, Off, Max }; } — so it is stored as TEnumAsByte<EMassLOD::Type> and EMassLOD::Max doubles as the array size for LODRepresentation.

EMassVisibility (MassLODTypes.h, MassLOD)

CanBeSeen, CulledByFrustum, CulledByDistance, Max.

EMassObservedOperationFlags (MassEntityTypes.h, MassEntity)

None, AddElement, RemoveElement, CreateEntity, DestroyEntity, Add (= AddElement | CreateEntity), Remove (= RemoveElement | DestroyEntity), All.

EMassCommandOperationType (MassCommands.h, MassEntity)

Flush order is by bucket, not enum order (MassCommandBuffer.cpp:110-119): Create, Add, ChangeComposition, Set, then Remove and Destroy together; commands left as None run last.

Crowd types

UMassCrowdSubsystem derives from UMassSubsystemBase and tracks lane occupancy, density and waiting slots over a ZoneGraph. It specialises TMassExternalSubsystemTraits<UMassCrowdSubsystem> with GameThreadOnly = false and ThreadSafeWrite = false, so parallel processors may declare it through AddSubsystemRequirement.

Signals

UMassSignalSubsystem (MassSignalSubsystem.h, module MassSignals) wakes processors for specific entities instead of ticking every entity every frame. The signal name comes first:

SignalSubsystem->SignalEntity(FName("MyGame.Damaged"), Entity);
SignalSubsystem->DelaySignalEntity(FName("MyGame.Respawn"), Entity, 3.f);
SignalSubsystem->SignalEntityDeferred(Context, FName("MyGame.Damaged"), Entity);

Processors that react to signals derive from UMassSignalProcessorBase (MassSignalProcessorBase.h), which is also the base of UMassStateTreeProcessor.