Fix: Unreal Mass Entity Fragment Not Replicating

A custom Mass fragment FAgentHealthFragment tracks agent HP on the server. Clients never see HP changes. The standard UPROPERTY replication on actors doesn’t apply — Mass entities aren’t actors.

Why Standard Replication Doesn’t Apply

Mass Entity is an ECS framework. Each entity is just an ID plus a set of fragments stored in chunks. There’s no AActor and no UObject wrapper, so the engine’s replication system has no hook to track changes. The MassReplication module bridges this by:

1. Selecting a subset of agents that need replicating (typically those visible to clients).
2. Spawning a lightweight UAActor for each selected agent on the server.
3. Driving that actor’s replicated properties from the agent’s fragments.
4. Spawning a matching client-side actor that pushes data into the client’s local Mass entity.

Without configuring this module, fragments live and die on the server.

Step 1: Enable the Plugin

In the Plugins window, find Mass AI and Mass Gameplay. Enable both. Restart the editor.

Edit Project.uproject to confirm:

{
  "Plugins": [
    { "Name": "MassEntity", "Enabled": true },
    { "Name": "MassGameplay", "Enabled": true }
  ]
}

Step 2: Define a Replicated Fragment

USTRUCT()
struct FAgentHealthFragment : public FMassFragment
{
    GENERATED_BODY()
    UPROPERTY(EditAnywhere) float Health = 100.0f;
};

Add a corresponding replicated mirror struct:

USTRUCT()
struct FAgentHealthReplicated : public FMassNetworkSyncFragmentBase
{
    GENERATED_BODY()
    UPROPERTY(EditAnywhere) float Health = 100.0f;
};

Step 3: Configure the Representation Actor

Create a AMyMassReplicatedActor deriving from AMassClientBubbleHandler. Add a UPROPERTY(Replicated) for Health and override SetReplicatedData to push from fragment to actor.

UCLASS()
class AMyMassReplicatedActor : public AMassClientBubbleHandler
{
    GENERATED_BODY()
public:
    UPROPERTY(Replicated) float Health = 100.0f;
};

Step 4: Register a Processor

Write a Mass Processor that copies fragment data into the replicated actor each tick:

UCLASS()
class UAgentHealthReplicationProcessor : public UMassProcessor
{
    GENERATED_BODY()
protected:
    virtual void Execute(FMassEntityManager& Mgr, FMassExecutionContext& Ctx) override
    {
        EntityQuery.ForEachEntityChunk(Mgr, Ctx, [&](FMassExecutionContext& C)
        {
            auto Healths = C.GetFragmentView<FAgentHealthFragment>();
            for (int32 i = 0; i < C.GetNumEntities(); ++i)
            {
                // push Healths[i].Health into the agent’s representation actor
            }
        });
    }
};

Verifying

Run a Listen Server with a client. On the server, mutate a fragment’s Health value. On the client, read the corresponding representation actor’s Health — it should match within one network tick. Without the replication chain, the client value stays at the initial 100.

“Mass is ECS; ECS doesn’t auto-replicate. Wire up the bridge actors and processors, or fragments stay server-local.”

Mass replication has nontrivial setup — if you only have a dozen agents, regular actors may be simpler than the Mass overhead.