ue-mass-entity

Name: ue-mass-entity
Author: quodsoler

522installs39forks

How to install ue-mass-entity?

quodsoler/unreal-engine-skills/ue-mass-entity

$npx -y skills add quodsoler/unreal-engine-skills --skill ue-mass-entity

Installs into the current project.

Summary

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 Unre

Files · 1

View on GitHub

SKILL.md

1	# UE Mass Entity Framework
2
3	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.
4
5	## Context Check
6
7	Before proceeding, read `.agents/ue-project-context.md` to determine:
8	- Whether the MassEntity plugin is enabled (and MassAI, MassCrowd, MassGameplay if needed)
9	- The target entity count and performance budget
10	- Whether MassCrowd lane navigation or ZoneGraph is in use
11	- Existing processors, fragments, traits, and entity config assets
12
13	## Information Gathering
14
15	Ask the developer:
16	1. What kind of entities are being simulated? (crowds, projectiles, traffic, wildlife, custom)
17	2. What data does each entity carry? (position, velocity, health, custom state)
18	3. Are entities visualized? If so, what LOD strategy? (ISM, skeletal, actor promotion)
19	4. Is this multiplayer? If so, which entities replicate?
20	5. How many entities at peak? (hundreds vs. tens of thousands)
21
22	---
23
24	## ECS Concepts
25
26	Mass Entity uses an archetype ECS model where entity composition determines memory layout:
27
28	\| Concept \| Class Base \| Purpose \|
29	\|---------\|-----------\|---------\|
30	\| Entity \| `FMassEntityHandle` \| 8-byte identity handle (Index + SerialNumber) \|
31	\| Fragment \| `FMassFragment` \| Per-entity mutable data (position, velocity, health) \|
32	\| Tag \| `FMassTag` \| Zero-size boolean marker for filtering \|
33	\| Shared Fragment \| `FMassSharedFragment` \| Per-archetype mutable data \|
34	\| Const Shared Fragment \| `FMassConstSharedFragment` \| Per-archetype immutable data (mesh params) \|
35	\| Chunk Fragment \| `FMassChunkFragment` \| Per-memory-chunk data (custom chunk-level state) \|
36	\| Archetype \| `FMassArchetypeHandle` \| Unique combination of fragment/tag types \|
37
38	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.
39
40	---
41
42	## Fragment and Tag Definitions
43
44	All types require `USTRUCT()` with `GENERATED_BODY()`:
45
46	```cpp
47	// Per-entity mutable data
48	USTRUCT()
49	struct FHealthFragment : public FMassFragment
50	{
51	GENERATED_BODY()
52	float Current = 100.f;
53	float Max = 100.f;
54	};
55
56	// Zero-size marker — no data members
57	USTRUCT()
58	struct FDeadTag : public FMassTag
59	{
60	GENERATED_BODY()
61	};
62
63	// Shared across all entities in an archetype (mutable)
64	USTRUCT()
65	struct FTeamSharedFragment : public FMassSharedFragment
66	{
67	GENERATED_BODY()
68	int32 TeamID = 0;
69	};
70	```
71
72	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.
73
74	---
75
76	## FMassEntityManager
77
78	The entity manager is NOT a `UObject` -- it is a struct (`TSharedFromThis<FMassEntityManager>`, `FGCObject`). Access it through `UMassEntitySubsystem` (a `UWorldSubsystem`):
79
80	```cpp
81	UMassEntitySubsystem* MassSubsystem = GetWorld()->GetSubsystem<UMassEntitySubsystem>();
82	FMassEntityManager& EntityManager = MassSubsystem->GetMutableEntityManager();
83	// const ref: MassSubsystem->GetEntityManager()
84	```
85
86	### Entity Lifecycle
87
88	```cpp
89	// One-shot creation
90	FMassEntityHandle Entity = EntityManager.CreateEntity(ArchetypeHandle);
91
92	// With shared fragments
93	FMassArchetypeSharedFragmentValues SharedValues;
94	FMassEntityHandle Entity = EntityManager.CreateEntity(ArchetypeHandle, SharedValues);
95
96	// Two-phase (reserve then build)
97	FMassEntityHandle Handle = EntityManager.ReserveEntity();
98	EntityManager.BuildEntity(Handle, ArchetypeHandle);
99
100	// Batch creation (thousands at once)
101	// BatchCreateEntities returns TSharedRef<FEntityCreationContext> — retain it until
102	// observer processors should fire (dropping it early suppresses observer execution).
103	TArray<FMassEntityHandle> Entities;
104	TSharedRef<FEntityCreationContext> CreationContext =
105	EntityManager.BatchCreateEntities(ArchetypeHandle, 5000, Entities);
106
107	// Destruction
108	EntityManager.DestroyEntity(Handle);
109	EntityManager.BatchDestroyEntities(EntityArray);
110	```
111
112	### Validity Checks
113
114	`FMassEntityHandle::IsSet()` (aliased as `IsValid()`) only checks non-zero Index/Seria

People who liked this also viewed

6 picks

Type

ue-mass-entity

522installs39forks

View on GitHub

How to install ue-mass-entity?

quodsoler/unreal-engine-skills/ue-mass-entity

$npx -y skills add quodsoler/unreal-engine-skills --skill ue-mass-entity

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# UE Mass Entity Framework
2
3	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.
4
5	## Context Check
6
7	Before proceeding, read `.agents/ue-project-context.md` to determine:
8	- Whether the MassEntity plugin is enabled (and MassAI, MassCrowd, MassGameplay if needed)
9	- The target entity count and performance budget
10	- Whether MassCrowd lane navigation or ZoneGraph is in use
11	- Existing processors, fragments, traits, and entity config assets
12
13	## Information Gathering
14
15	Ask the developer:
16	1. What kind of entities are being simulated? (crowds, projectiles, traffic, wildlife, custom)
17	2. What data does each entity carry? (position, velocity, health, custom state)
18	3. Are entities visualized? If so, what LOD strategy? (ISM, skeletal, actor promotion)
19	4. Is this multiplayer? If so, which entities replicate?
20	5. How many entities at peak? (hundreds vs. tens of thousands)
21
22	---
23
24	## ECS Concepts
25
26	Mass Entity uses an archetype ECS model where entity composition determines memory layout:
27
28	\| Concept \| Class Base \| Purpose \|
29	\|---------\|-----------\|---------\|
30	\| Entity \| `FMassEntityHandle` \| 8-byte identity handle (Index + SerialNumber) \|
31	\| Fragment \| `FMassFragment` \| Per-entity mutable data (position, velocity, health) \|
32	\| Tag \| `FMassTag` \| Zero-size boolean marker for filtering \|
33	\| Shared Fragment \| `FMassSharedFragment` \| Per-archetype mutable data \|
34	\| Const Shared Fragment \| `FMassConstSharedFragment` \| Per-archetype immutable data (mesh params) \|
35	\| Chunk Fragment \| `FMassChunkFragment` \| Per-memory-chunk data (custom chunk-level state) \|
36	\| Archetype \| `FMassArchetypeHandle` \| Unique combination of fragment/tag types \|
37
38	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.
39
40	---
41
42	## Fragment and Tag Definitions
43
44	All types require `USTRUCT()` with `GENERATED_BODY()`:
45
46	```cpp
47	// Per-entity mutable data
48	USTRUCT()
49	struct FHealthFragment : public FMassFragment
50	{
51	GENERATED_BODY()
52	float Current = 100.f;
53	float Max = 100.f;
54	};
55
56	// Zero-size marker — no data members
57	USTRUCT()
58	struct FDeadTag : public FMassTag
59	{
60	GENERATED_BODY()
61	};
62
63	// Shared across all entities in an archetype (mutable)
64	USTRUCT()
65	struct FTeamSharedFragment : public FMassSharedFragment
66	{
67	GENERATED_BODY()
68	int32 TeamID = 0;
69	};
70	```
71
72	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.
73
74	---
75
76	## FMassEntityManager
77
78	The entity manager is NOT a `UObject` -- it is a struct (`TSharedFromThis<FMassEntityManager>`, `FGCObject`). Access it through `UMassEntitySubsystem` (a `UWorldSubsystem`):
79
80	```cpp
81	UMassEntitySubsystem* MassSubsystem = GetWorld()->GetSubsystem<UMassEntitySubsystem>();
82	FMassEntityManager& EntityManager = MassSubsystem->GetMutableEntityManager();
83	// const ref: MassSubsystem->GetEntityManager()
84	```
85
86	### Entity Lifecycle
87
88	```cpp
89	// One-shot creation
90	FMassEntityHandle Entity = EntityManager.CreateEntity(ArchetypeHandle);
91
92	// With shared fragments
93	FMassArchetypeSharedFragmentValues SharedValues;
94	FMassEntityHandle Entity = EntityManager.CreateEntity(ArchetypeHandle, SharedValues);
95
96	// Two-phase (reserve then build)
97	FMassEntityHandle Handle = EntityManager.ReserveEntity();
98	EntityManager.BuildEntity(Handle, ArchetypeHandle);
99
100	// Batch creation (thousands at once)
101	// BatchCreateEntities returns TSharedRef<FEntityCreationContext> — retain it until
102	// observer processors should fire (dropping it early suppresses observer execution).
103	TArray<FMassEntityHandle> Entities;
104	TSharedRef<FEntityCreationContext> CreationContext =
105	EntityManager.BatchCreateEntities(ArchetypeHandle, 5000, Entities);
106
107	// Destruction
108	EntityManager.DestroyEntity(Handle);
109	EntityManager.BatchDestroyEntities(EntityArray);
110	```
111
112	### Validity Checks
113
114	`FMassEntityHandle::IsSet()` (aliased as `IsValid()`) only checks non-zero Index/Seria

People who liked this also viewed

6 picks

Type