Fix: Unreal Mass Entity Fragments Not Replicating

Here is how to fix Unreal Mass Entity simulations where the server runs thousands of entities perfectly but clients see nothing or only a few static positions. Mass replication is opt-in and substantially more involved than standard Actor replication. Without the right module, processors, and network IDs, your fragments simply do not cross the wire.

The Symptom

A Mass simulation runs on the server, populating fragments with position, velocity, animation state. On the client, the entities are missing or appear stuck at spawn position. stat MassEntities shows expected counts on server, near zero on client.

What Causes This

MassReplication module missing. The base Mass framework does not include replication; it is a separate module.

No replication processor. Even with the module, processors must be registered to drive the replication pipeline.

Replication grid missing. Mass replication uses a spatial grid to determine which entities are relevant per client. Without a grid, no entities are flagged for relevance.

FMassNetworkID not assigned. Without per-entity network IDs, the client cannot reconstruct the mapping.

The Fix

Step 1: Add Mass modules.

// MyProject.Build.cs
PublicDependencyModuleNames.AddRange(new string[] {
    "MassEntity",
    "MassCommon",
    "MassReplication",
    "MassActors",
    "MassMovement",
    "MassRepresentation",
    "NetCore"
});

Step 2: Configure the Mass replication grid. Create a UMassReplicationGrid2DSubsystem subclass or use the default. In your level’s WorldSettings or a custom GameMode subsystem:

void AMassNetGameMode::PreInitializeComponents()
{
    Super::PreInitializeComponents();

    UMassReplicationSubsystem* repl = GetWorld()->GetSubsystem<UMassReplicationSubsystem>();
    repl->RegisterBubbleInfoClass(AMyBubbleInfo::StaticClass());
}

Step 3: Define a Bubble Info actor. The Bubble is the per-client replicated container holding networked entity state. AMyBubbleInfo extends AMassClientBubbleInfoBase and pairs with an FBubbleHandler describing serialization.

Step 4: Add networked fragments. Mark fragments you want replicated by including them in the replication processor’s FragmentRequirements:

void UMyReplicationProcessor::ConfigureQueries()
{
    EntityQuery.AddRequirement<FTransformFragment>(EMassFragmentAccess::ReadOnly);
    EntityQuery.AddRequirement<FMassNetworkIDFragment>(EMassFragmentAccess::ReadOnly);
    EntityQuery.AddRequirement<FAgentLastPathFragment>(EMassFragmentAccess::ReadOnly);
}

Step 5: Network LOD for performance. Replicating thousands of entities every tick saturates connections. Use the LOD system:

Replication LOD bands:
  Tier 1 (close):    full fragments, every tick
  Tier 2 (medium):   pos + velocity, every other tick
  Tier 3 (far):      pos only, every 10 ticks
  Tier 4 (very far): not replicated

Configure in the Mass Schema and the NetworkLODProcessor.

Verifying Replication

On a client, run stat MassEntities and stat NetMass. If client count matches server count (or matches the LOD-relevant subset), replication is working. If client count is 0, the bubble is not registered or the grid is missing.

Check the Network Profiler (net dump) to see Mass-related RPC traffic. Lack of any traffic means the replication pipeline is not running.

Common Pitfalls

Adding fragments to entities that the replication processor does not include. Those fragments stay server-only.

Forgetting to call StartUpInternal or the equivalent on your custom subsystem. Without that, processors are never scheduled.

Mismatched fragment definitions between server and client. Replication serialization assumes both sides have identical fragment layouts.

“Mass replication is its own subsystem. Module + grid + bubble + processor + LOD. Five pieces, all required.”

Related Issues

For Multicast RPC issues, see Multicast RPC. For physics constraint replication, see Physics Constraint Load.

Module, grid, bubble, processor, LOD. Five pieces and the entities cross the wire.