Multiserver offloading

Out of the box, the GDK for Unreal has a single Unreal server-worker instance. However, you can set up your Unreal project to split the computation done by that single server-worker instance across multiple server-worker instances.

There are two ways to do this - offloading and zoning:

  • Offloading: Two or more server-worker instances compute the whole game world, dividing the compute load between them by Actor type.
  • Zoning: Two or more server-worker instances compute the functionality for a limited area of the game world, computing for all Actors in their area.


Zoning is currently in development and not available for use in the GDK for Unreal. This documentation describes offloading only.

With offloading, some CPU-intensive game systems that cannot easily use multithreading with Unreal’s native architecture are no longer limited by the processing power of a single server. You can offload computationally expensive but latency-tolerant systems, such as AI decision-making, onto a separate, dedicated server-worker instance. In addition, not all input from game clients needs to be computed by the same server-worker instance. This leaves your main server-worker instance to compute other game systems at a larger scale.

To offload to additional server-worker instances, you must set up one or more additional Unreal server-worker types and then associate each server-worker type with specific Actor groups. Each type you set up uses the same Unreal server-worker executable that you get out of the box. With offloading set up, at your game’s runtime, the SpatialOS Runtime spins up one instance of each server-worker type, including one instance of the main out-of-the-box server-worker type.

Offloading: Offloaded Unreal server-worker instance has authority only over Red Actors and the Main Unreal server-worker instance that runs major game systems has authority over all Actors except the Red Actors.

Offloading increases CPU resources at the cost of bandwidth. If you want more interaction between the offloaded server-worker instance and the main server-worker instance, the cost of bandwidth and the CPU consumption on communication between them increase. Therefore, when you design your game feature using offloading, carefully consider what information is sent between servers.

Actor groups

Actor groups facilitate multiserver functionality through offloading. You set them up to configure which Actor types instances of a server-worker type have authority over. In the Unreal Editor, you can create Actor groups, assign Actor classes to a group, and then assign each group to a server-worker type via the SpatialOS Runtime Settings panel.

To get started with configuring Actor groups, see the offloading tutorial.

Best practices

Adapt game logic for offloading

Before you offload Actors, consider the following scenarios that you need to update the game code to work correctly in:

  • IsServer()

    Because the IsServer() function returns true for both the main Unreal server and all offloaded servers, to ensure that the logic is called only on a server-worker that has authority over an Actor, take one of the following options:

  • <NM_Client or == NM_DedicatedServer check
    Same as above

  • Server RPCs follow similar logic to their usage in a single-server model.

    • When sent from clients: if a client net-owns an actor and invokes a server RPC, it sends that RPC to the server that has authority, which can be either the main Unreal server-worker or offloaded server-worker.
    • When sent from an offloaded server: Server RPCs invoked by an offloaded worker run only on that offloaded server worker. However, if you want Server RPCs to be run on another server worker you should use Cross-server RPCs.
  • Calls to SpawnActor on a server that doesn't have authority over the spawned Actor

    You might want to spawn an Actor from a server where a different server has authority over the spawned Actor. For example, an offloaded AI might drop items that the main Unreal server-worker instance should have authority over.

    However, this might cause issues when the initialization logic in the calls such as BeginPlay and PostInitializeComponent is executed on the wrong server-worker instance. You can usually work around these issues using callbacks / RepNotify-s on the main Unreal server-worker instance to defer the execution of such logic until when the correct server-worker instance has authority over the offloaded Actor.

2020-04-16 Page updated with editorial review: added introductory text about offloading
2019-08-08 Page updated with editorial review: updated first part of overview
2019-07-26 Page added with limited editorial review

Updated about a month ago

Multiserver offloading

Suggested Edits are limited on API Reference Pages

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