Tutorial 06 - Mass Entity crowds (10K+ agents)

Add one trait to a Mass Entity Config and a crowd navigates in full 3D. No per-agent controller, no tick function, no code.

Time: ~20 minutes. You'll end with: thousands of agents flying to a goal.

A UActor AI agent costs roughly 50 µs/tick once it has a controller, movement component and behaviour tree - a few hundred saturate the game thread. Mass represents agents as ECS fragments instead, so the same work runs in one processor sweep.

Prerequisites

The MassEntity and MassGameplay plugins enabled. LCM Nav3D enables both; if you stripped them, re-enable both or the module fails to load.
An LcmNavigationManagerSVO in the level with navigation built.
Epic's "MassEntity Quick Start" if you have never used Mass - this tutorial only adds a trait on top of the standard flow.

Step 1: Create the agent config

Add → Miscellaneous → Data Asset → MassEntityConfigAsset. Name it DA_MyCrowd.

Open it and add three traits - one from each category:

Trait	Category	Set
LCM Nav3D Agent	Movement - exactly one	`Nav Mode`, `Agent Radius`, `Max Speed`
LCM Nav3D Goal	Goal	`Goal Mode`, and the location or tag
LCM Nav3D ISM Render	Rendering	`Mesh`

Choosing a Nav Mode

Nav Mode	Use it for	Cost
Path Following	Agents with different goals, precise routes, infinite worlds	One path per agent
Flow Field	A crowd sharing one goal - the 10K-scale option	One field, shared by everyone

⚠ Add a rendering trait or your agents are invisible. They spawn and navigate correctly, they just draw nothing - the navigation trait deliberately owns navigation only. This is the most common first-run surprise.

Movement settings worth knowing

Setting	Default	What it does
`Max Turn Rate Deg`	`360`	The knob that turns square corners into arcs. `0` = instant snap
`Max Acceleration`	`2000`	cm/s². With turn rate, this is what makes movement look weighted
`Flight Style`	`Physics`	`Physics` (inertia) vs `Linear` (magic / biological, instant)
`Avoidance Style`	`Reactive`	`Reactive` (boids) / `Predictive` (ORCA, smooth mutual passing) / `None`
`Lane Bias`	`0.6`	Spreads a crowd across a corridor instead of balling up at turns

Defaults give natural movement out of the box.

Step 2: Spawn them

Place a MassSpawner actor in the level.
In Entity Types, reference DA_MyCrowd.
Set Spawn Count - start at 100 while you wire it up.
Give it a spawn-distribution asset so agents start at distinct positions inside your navigation volume.

Step 3: Give them a goal

The LCM Nav3D Goal trait does this with no code:

`Goal Mode`	Set	Behaviour
Fixed Location	`Goal Location`	Everyone paths to that point
Tagged Actor	`Target Actor Tag` (e.g. `ApexGoal`)	Everyone paths to the tagged actor, re-pathing if it moves

Repath Tolerance Cm decides how far a moving target drifts before agents re-path; Arrival Tolerance Cm is where they stop.

Setting a goal from code instead

Write the goal and flip the status; the processors own every transition from there.

auto& Req = EntityManager.GetFragmentDataChecked<FLcmMassPathRequestFragment>(Handle);
Req.Goal   = TargetPos;
Req.Status = ELcmMassPathStatus::Pending;

Status moves Pending → InFlight → Complete (or Failed) and is readable at any time, so your own logic can branch on it.

Step 4: Check it works

Press Validate Entity Config on the asset. It catches the trait mistakes that are silent at runtime and all present as "my agents don't move".
Press Play with r.LcmNav.Mass.DebugDraw 1 - agents draw as status-coloured spheres (grey idle, yellow pending, green complete, red failed) with a line to their waypoint.
Scale up gradually: 100, then 1,000, then 10,000, watching frame time.

If nothing moves

Symptom	Cause	Fix
Nothing visible at all	No rendering trait	Add LCM Nav3D ISM Render
Spheres are red	No path to the goal	Goal is outside the navigation volume, or inside geometry
Spheres stay grey	No goal set	Add the Goal trait, or write the request fragment
Validation error on save	Two movement traits, or Goal on a Flow Field agent	See Mass Trait Reference
Crowd vanishes when you walk away	World Partition streamed the spawner out	See the World Partition section of the trait reference

Tuning

Kill-switches and global overrides. Production authoring is the trait, not the console.

CVar	Default	What it does
`r.LcmNav.Mass.MaxPathsPerTick`	`64`	Spreads a large spawn wave's path requests across frames
`r.LcmNav.Mass.Avoidance`	`1`	Master switch for inter-agent avoidance
`r.LcmNav.Mass.DebugDraw`	`0`	Status-coloured spheres and waypoint lines

Scope

Mass agents resolve both endpoints within the agent's own chunk. Keep crowd goals in the same chunk as the crowd, or use a Behaviour Tree agent for long cross-chunk routes.

Mass Trait Reference - every trait, the combination matrix, and the World Partition trap.
Tutorial 04 - StateTree, the per-entity AI layer that pairs with Mass.