Use this skill when working with Mass Entity, MassEntity, Mass AI, MassProcessor, MassFragment, MassTag, MassObserver, MassSpawner, MassCrowd, Mass ECS, entity archetype, ForEachEntityChunk, FMassEntityQuery, FMassEntityManager, ISM crowd, or large-scale entity simulation in Unreal Engine. See refer

UE Mass Entity Framework You are an expert in Unreal Engine's Mass Entity framework an archetype based Entity Component System (ECS) designed for high performance simulation of thousands of entities using cache friendly data layouts and parallel processing. Context Check Before proceeding, read .agents/ue project context.md to determine: Whether the MassEntity plugin is enabled (and MassAI, MassCrowd, MassGameplay if needed) The target entity count and performance budget Whether MassCrowd lane navigation or ZoneGraph is in use Existing processors, fragments, traits, and entity config assets Information Gathering Ask the developer: 1. What kind of entities are being simulated? (crowds, projectiles, traffic, wildlife, custom) 2. What data does each entity carry? (position, velocity, health, custom state) 3. Are entities visualized? If so, what LOD strategy? (ISM, skeletal, actor promotion) 4. Is this multiplayer? If so, which entities replicate? 5. How many entities at peak? (hundreds vs. tens of thousands) ECS Concepts Mass Entity uses an archetype ECS model where entity composition determines memory layout: Concept Class Base Purpose Entity FMassEntityHandle 8 byte identity handle (Index + SerialNumber) Fragment FMassFragment Per entity mutable data (position, velocity, health) Tag FMassTag Zero size boolean marker for filtering Shared Fragment FMassSharedFragment Per archetype mutable data Const Shared Fragment FMassConstSharedFragment Per archetype immutable data (mesh params) Chunk Fragment FMassChunkFragment Per memory chunk data (custom chunk level state) Archetype FMassArchetypeHandle Unique combination of fragment/tag types Why archetypes matter: Entities with identical fragment/tag composition share the same archetype. All fragments of the same type within a chunk are stored contiguously, enabling cache friendly iteration over thousands of entities per frame. Fragment and Tag Definitions All types require USTRUCT() with GENERATED BODY() : Chunk fragments ( FMassChunkFragment ) store per memory chunk state shared across all entities in a chunk. Note: FMassRepresentationLODFragment inherits from FMassFragment (per entity), not FMassChunkFragment . Const shared fragments ( FMassConstSharedFragment ) are immutable after archetype creation use for configuration data like FMassRepresentationParameters . See references/mass fragment reference.md for built in types. FMassEntityManager The entity manager is NOT a UObject it is a struct ( TSharedFromThis<FMassEntityManager , FGCObject ). Access it through UMassEntitySubsystem (a UWorldSubsystem ): Entity Lifecycle Validity Checks FMassEntityHandle::IsSet() (aliased as IsValid() ) only checks non zero Index/SerialNumber it does NOT verify the entity exists. Always use the entity manager: Direct Fragment/Tag Mutations (Outside Processors) UMassProcessor Processors iterate over entities matching a query each frame. Subclass UMassProcessor (abstract), override ConfigureQueries() and Execute() : Constructor Configuration EMassProcessingPhase : PrePhysics , StartPhysics , DuringPhysics , EndPhysics , PostPhysics , FrameEnd EProcessorExecutionFlags : None (0), Standalone (1), Server (2), Client (4), Editor (8), AllNetModes (7 = Standalone Server Client) Execution ordering: ExecutionOrder.ExecuteInGroup , ExecuteAfter , ExecuteBefore control processor scheduling relative to named groups and other processors. FMassEntityQuery Queries define which entities a processor operates on. Configure in ConfigureQueries() , then call RegisterQuery() : EMassFragmentAccess Usage None No access (filter only) ReadOnly GetFragmentView<T () TConstArrayView ReadWrite GetMutableFragmentView<T () TArrayView EMassFragmentPresence Meaning All Entity must have this fragment Any At least one Any marked fragment must exist None Entity must NOT have this fragment Optional Access if present, skip if absent Fragment Based Chunk Filtering FMassExecutionContext and Iteration Inside ForEachEntityChunk , the context provides typed views into chunk data: Parallel execution: MovementQuery.ParallelForEachEntityChunk(Context, Lambda) for thread safe processors. Subsystem access: Context.GetMutableSubsystem<T () / Context.GetSubsystem<T () for subsystems declared via AddSubsystemRequirement . Shared/chunk access: Context.GetMutableSharedFragment<T () , Context.GetConstSharedFragment<T () , Context.GetChunkFragment<T () . FMassCommandBuffer (Deferred Mutations) CRITICAL: Inside ForEachEntityChunk , never call entity manager mutations directly. Structural changes during iteration invalidate archetype memory layouts, causing undefined behavior. Use Context.Defer() : Deferred command execution order: Create Add Remove ChangeComposition Set Destroy . This guarantees fragments exist before being written, and entities exist before being modified. PushCommand<T (Command) pushes a typed deferred command. Note: PushCommand does NOT accept a lambda. For custom deferred logic, use PushUniqueCommand(TUniquePtr<FMassBatchedCommand &&) with a subclass of FMassBatchedCommand . See references/mass entity patterns.md for patterns. UMassObserverProcessor Observers react to structural changes when a fragment or tag is added to or removed from an entity. They fire automatically: The observer Execute runs only for entities that just had the observed type added/removed. Use observers for initialization, cleanup, and state change responses instead of per frame polling. FMassEntityView For single entity access outside processor iteration, use FMassEntityView . It is transient never store across frames because archetype memory can relocate: Mass Spawner and Config Assets UMassEntityConfigAsset defines entity templates via traits. Add traits like UMassAssortedFragmentsTrait (custom fragments), UMassVisualizationTrait (ISM visualization), or UMassReplicationTrait (networking). Custom traits subclass UMassEntityTraitBase and override BuildTemplate(FMassEntityTemplateBuildContext&, const UWorld&) to add fragments and configure archetypes. ValidateTemplate() provides editor time validation. AMassSpawner is a world actor that references entity config assets and controls spawn count, timing, and spatial distribution. See references/mass entity patterns.md for trait implementation templates. Common Fragments Fragment Type Purpose FTransformFragment Fragment Entity world transform FMassVelocityFragment Fragment Linear velocity FMassForceFragment Fragment Applied force FAgentRadiusFragment Fragment Agent collision radius FMassMoveTargetFragment Fragment Navigation move target FMassRepresentationFragment Fragment Current visual representation state FMassRepresentationLODFragment Fragment Per entity LOD level and visibility state FMassRepresentationParameters Const Shared Representation type per LOD, update rate config FMassMovementParameters Const Shared Max speed, acceleration See references/mass fragment reference.md for complete field details and trait types. Representation (ISM Visualization) Mass Entity uses Instanced Static Meshes for rendering thousands of entities without per entity actors: EMassRepresentationType Usage StaticMeshInstance ISM for mid/far entities HighResSpawnedActor Full actor for close up (high LOD) LowResSpawnedActor Reduced actor for medium LOD None No visual representation EMassLOD Detail Level High Full detail, actor based Medium Reduced detail Low Minimal (ISM only) Off Not rendered UMassRepresentationSubsystem manages ISM instances. Use UMassVisualizationTrait on entity configs to set meshes and LOD distances. Force game thread for representation processors: TMassSharedFragmentTraits<T ::GameThreadOnly = true . MassCrowd UMassCrowdSubsystem provides lane based navigation using ZoneGraph for pedestrian crowd simulation. Located in Engine/Plugins/AI/MassCrowd/ (not Runtime). Key features: lane state management, waiting slot allocation, density tracking, and avoidance. Thread safe for parallel processors: TMassExternalSubsystemTraits<UMassCrowdSubsystem ::GameThreadOnly = false . Entities use FMassMoveTargetFragment for lane following targets. ZoneGraph defines navigation lanes as connected graphs with automatic density management. StateTree Integration Mass Entity processors can trigger State Tree evaluations for entity AI. State Trees provide hierarchical decision making for Mass entities as an alternative to per entity behavior trees (prohibitively expensive at scale). For State Tree architecture and task patterns, see ue state trees . Common Mistakes Direct mutations inside ForEachEntityChunk: Storing FMassEntityView across frames: Entity views are transient. Archetype memory may relocate between frames, invalidating stored views. Create a fresh FMassEntityView each time. Using IsSet/IsValid for existence: Handle.IsSet() only checks non zero fields. A destroyed entity's handle still returns true. Use EntityManager.IsEntityValid(Handle) . Missing RegisterQuery: Forgetting RegisterQuery(MyQuery) in ConfigureQueries() silently skips the query. Every query used in Execute must be registered. UObject access without game thread flag: Accessing UObject properties from a parallel processor causes races. Set bRequiresGameThreadExecution = true or declare dependencies via AddSubsystemRequirement . Fragment access mismatch: ReadOnly access + GetMutableFragmentView<T () triggers an assertion. Match access mode to view type. Reference Files references/mass entity patterns.md Processor, observer, trait, and deferred command code templates references/mass fragment reference.md Built in fragment types, shared fragments, and trait classes Related Skills ue ai navigation NavMesh pathfinding and AI perception for Mass agents ue procedural generation PCG and ISM patterns relevant to Mass representation ue gameplay framework GameMode/GameState interaction with Mass simulation ue actor component architecture Actor entity bridging via MassAgentComponent ue async threading Parallel execution patterns and thread safety ue cpp foundations USTRUCT, UCLASS, subsystem patterns

ue-mass-entity