Replication Graph

Unreal Replication Graph Plugin

The Unreal Replication Graph Plugin allows you to efficiently replicate a large number of Actors in a multiplayer game for a large number of players. Instead of using each replicated Actor to determine if an update should go to each client, the replication graph builds lists of Actors to replicate to each client. The replication graph caches the information across multiple frames and shares it between client connections, which reduces the computation required for replication. For more information on the replication graph, see the Unreal Engine documentation: Replication Graph.

You can see an example of our implementation of a replication graph in the SpatialOS TestGyms project.

Enable replication graph support

To enable replication graph support in the GDK for Unreal, follow these steps:

  1. Open the Game/Config/DefaultEngine.ini file for your project.

  2. Find the [/Script/OnlineSubsystemUtils.IpNetDriver] section. If it does not exist, add it.

  3. Set the ReplicationDriverClassName to the replication graph class you want to use.
    For example:
    [/Script/OnlineSubsystemUtils.IpNetDriver]
    ReplicationDriverClassName=/Script/GDKTestGyms.TestGymsReplicationGraph

Note: You must extend USpatialReplicationGraph if you want to use the replication graph functionality within the GDK.

Key differences between the native Unreal replication graph and the SpatialOS replication graph

The implementation of the replication graph in SpatialOS is different from the implementation in native Unreal. This is because the network topologies are different. If you are porting an existing replication graph to SpatialOS, you should consider how these differences might affect your implementation.

How does native Unreal use the replication graph?

In native Unreal, the server connects to every client, parses the replication graph and sends the appropriate replication data, determined by the graph, to each client.

How does SpatialOS use the replication graph?

In SpatialOS, a server-worker instance connects to the SpatialOS Runtime, parses the replication graph and sends the appropriate replication data, determined by the graph, to the Runtime. The Runtime then sends that data to every client and server-worker instance that has interest in the data.

For more information on the SpatialOS network topology, see How the GDK for Unreal fits into your game stack.

The replication process in native Unreal

In native Unreal, the replication graph constructs and maintains a series of nodes that it parses to determine what Actors it should replicate to each client. Some of the nodes on the replication graph are global and the Unreal server uses them to output lists of Actors that every client might have interest in. Some of the nodes are specific to client connections, for example, nodes for the player controller.

The native Unreal server follows these steps to replicate Actors for each client:

  1. Parse the client’s nodes.

    • Output a list of Actors for each node.
  2. Parse each global node.

    • Output a list of Actors for each node.
  3. Process each list to identify relevant Actors and replicate them to the client.

  4. Repeat these steps for the next client.

Because the server only needs to process the Actors that are on the lists, this process is a lot more efficient than if the server had to process every Actor in the world.

The replication process in SpatialOS

In SpatialOS, the replication graph constructs and maintains a series of nodes using the same process as native Unreal, however SpatialOS does not create a list for each client. SpatialOS has a single connection to the Runtime and creates only one replication list of Actors.

SpatialOS follows these steps to replicate Actors to the Runtime:

  1. Create an empty replication list to store Actors to replicate.

  2. For each client:

    • Parse the client’s nodes.
    • Parse each global node.
    • Store Actors in the replication list.
  3. After each client has been parsed:

    • Parse the global SpatialOS nodes (these are unique to SpatialOS). For more information on these nodes see Global SpatialOS nodes.
    • Store Actors in the replication list.
  4. Process the list to identify relevant Actors and replicate them to the Runtime.

As with native Unreal, because the server only needs to process the Actors that are on the replication list, this process is a lot more efficient than if the server had to process every Actor in the world. In addition, SpatialOS only replicates the relevant Actors in the replication list to the Runtime once, so the process is a lot more efficient than native Unreal.

Global SpatialOS nodes

The UReplicationGraphNode class is extended in SpatialOS so that global SpatialOS nodes are parsed just once per frame, even if many clients are connected. These nodes are ideal for storing Actors that don’t need to be parsed multiple times with each client’s details.

For example, you might want to define the AlwaysRelevant node as a global SpatialOS node because all clients have interest in Actors in this node. In native Unreal the AlwaysRelevant node is parsed for each client, but in SpatialOS a global SpatialOS node is parsed once, and the Runtime replicates all the Actors in the AlwaysRelevant node for all clients. When not running in SpatialOS, global SpatialOS nodes revert to normal global nodes that are processed once per connection.

To create and add global SpatialOS nodes to the replication graph, use the following function:
UReplicationGraphNode::SetProcessOnSpatialConnectionOnly()

Note: When you pass FConnectionGatherActorListParameters into global SpatialOS nodes, the parameters NetViewer (which details the client connection and location information) and VisibleLevelNames (which details the client loaded level names) are included for every client.

Replication graph implementation details

What is currently not supported?

  • Actor channels are not closed automatically when they are not relevant.
  • The following GDK settings are not used when you use the replication graph:
    ActorReplicationRateLimit
    EntityCreationRateLimit
    bUseIsActorRelevantForConnection

Replication graph and load balancing

To maintain consistency, Actor hierarchies need to be load balanced together. If you want to migrate an Actor that is part of a hierarchy then you need to migrate all of the hierarchy. This also means that when load balancing, you need to replicate Actors from the same hierarchy together, even if they are not part of the same replication node in the frame when they are migrated.

SpatialOS uses the dependent Actor list to ensure Actor hierarchies are load balanced together. When an Actor changes owner, the Actor is added to the owner’s dependent Actor list.

Note: When you migrate an Actor, the refresh rate of the Actor is ignored for that frame.

If you do not want to use the dependent Actor list in this way, you can disable this process by overriding USpatialReplicationGraph::OnOwnerUpdated to do nothing. In this case you must replicate Actor hierarchies together at a given frame and with the same refresh rate.


2020-10-02 Page added with editorial review.

Updated 12 months ago


Replication Graph


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.