ue-mass-entity
Use when writing or debugging Mass Entity ECS code in Unreal Engine C++ — processors, queries, fragments, tags, observers, traits, spawning and large-scale agent simulation. Also use when the user mentions 'MassEntity', 'UMassProcessor', 'FMassEntityQuery', 'ForEachEntityChunk', 'FMassEntityManager', 'FMassFragment', 'FMassTag', 'FTransformFragment', 'UMassObserverProcessor', 'ObservedTypes', 'Defer', 'archetype', 'AMassSpawner', 'entity config asset', 'MassCrowd', 'ISM crowd', 'entity relations', or 'thousands of agents'. For State Tree behavior on entities, see ue-state-trees; for ZoneGraph and Smart Objects, see ue-ai-navigation; for thread-safety rules, see ue-async-threading.
quodsoler · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add quodsoler/unreal-engine-skills --skill ue-mass-entity技能说明
name: ue-mass-entity description: "Use when writing or debugging Mass Entity ECS code in Unreal Engine C++ — processors, queries, fragments, tags, observers, traits, spawning and large-scale agent simulation. Also use when the user mentions 'MassEntity', 'UMassProcessor', 'FMassEntityQuery', 'ForEachEntityChunk', 'FMassEntityManager', 'FMassFragment', 'FMassTag', 'FTransformFragment', 'UMassObserverProcessor', 'ObservedTypes', 'Defer', 'archetype', 'AMassSpawner', 'entity config asset', 'MassCrowd', 'ISM crowd', 'entity relations', or 'thousands of agents'. For State Tree behavior on entities, see ue-state-trees; for ZoneGraph and Smart Objects, see ue-ai-navigation; for thread-safety rules, see ue-async-threading." metadata: version: "2.0.0" engine: "5.8"
UE Mass Entity
Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".
Mass is an archetype Entity Component System for simulating thousands of agents with cache-friendly data layouts and multi-threaded processors. The core lives in the always-available runtime modules MassEntity and MassCore (plus MassSignals, MassEngine); gameplay-facing pieces (spawning, representation, movement, LOD, replication, actor bridging) come from the MassGameplay (Experimental in 5.8) plugin, and navigation/behavior from MassAI (Experimental in 5.8) and MassCrowd (Experimental in 5.8).
Context
Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.
Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.
| Request is about… | Go to |
|---|---|
| Build.cs, includes, "enable the plugin" | Modules and Build.cs |
| Declaring fragments, tags, shared/chunk data | Fragments, Tags and Archetypes |
| Creating/destroying entities, direct mutation | FMassEntityManager |
| Writing a processor, scheduling, phases | UMassProcessor |
| Selecting entities, requirements, filtering | FMassEntityQuery |
| Reading/writing fragment data in a loop | Iteration and FMassExecutionContext |
| Adding/removing fragments during iteration | Deferred Commands |
| Reacting to fragment/tag add or remove | UMassObserverProcessor |
| One entity outside a processor, fluent build | Single-Entity Access and FEntityBuilder |
| Parent/child links, archetype grouping | Relations and Archetype Groups |
Traits, config assets, AMassSpawner | Traits, Config Assets and Spawning |
| ISM rendering, LOD, actor promotion | Representation and LOD |
| Crowds, lanes, entity AI | Crowd, Navigation and Behavior |
Longer templates live in mass-entity-patterns.md; built-in types and fields in mass-fragment-reference.md.
Modules and Build.cs
There is no MassEntity plugin to enable. MassEntity and MassCore are runtime modules that ship with the engine — add them to Build.cs and they link. Only the gameplay layers are plugins, and those must be enabled in the .uproject.
PublicDependencyModuleNames.AddRange(new string[] {
"Core", "CoreUObject", "Engine",
"MassEntity", // manager, processors, queries, commands, relations
"MassCore", // FMassFragment/FMassTag bases, FTransformFragment, traits
"MassSignals", // UMassSignalSubsystem, UMassSignalProcessorBase
"MassCommon", // UE::Mass::ProcessorGroupNames (MassGameplay)
"MassSpawner", // UMassEntityTraitBase, AMassSpawner (MassGameplay)
"MassMovement", // FMassVelocityFragment (MassGameplay)
"MassRepresentation", // ISM visualization + LOD (MassGameplay)
"MassActors", // UMassAgentComponent, actor bridging (MassGameplay)
"MassNavigation", // FMassMoveTargetFragment (MassAI)
});
Include paths that moved into MassCore are namespaced under Mass/: Mass/EntityElementTypes.h, Mass/EntityFragments.h, Mass/EntityHandle.h, Mass/ExternalSubsystemTraits.h, Mass/ArchetypeGroup.h. MassEntityTypes.h still pulls the element bases in transitively; prefer the explicit Mass/ path.
Fragments, Tags and Archetypes
| Concept | Base / type | Purpose |
|---|---|---|
| Entity | FMassEntityHandle | Index + SerialNumber identity handle |
| Fragment | FMassFragment | Per-entity mutable data |
| Sparse fragment | FMassSparseFragment | Per-entity data stored outside the archetype (no entity move on add) |
| Tag | FMassTag | Zero-size marker used for filtering |
| Sparse tag | FMassSparseTag | Marker added/removed without an archetype change |
| Chunk fragment | FMassChunkFragment | One instance per memory chunk |
| Shared fragment | FMassSharedFragment | Mutable value shared by entities that reference it |
| Const shared fragment | FMassConstSharedFragment | Immutable shared configuration |
| Archetype | FMassArchetypeHandle | A unique fragment/tag composition |
All of these derive from FMassElement and are declared in Mass/EntityElementTypes.h.
// MyMassTypes.h
#pragma once
#include "Mass/EntityElementTypes.h"
#include "MyMassTypes.generated.h"
USTRUCT()
struct FMyHealthFragment : public FMassFragment
{
GENERATED_BODY()
UPROPERTY(EditAnywhere, Category = "Mass")
float Current = 100.f;
UPROPERTY(EditAnywhere, Category = "Mass")
flo
阅读完整来源 ↗