Workers and load balancing

GDK for Unreal

If you're using the GDK for Unreal, this page does not apply to you. See the GDK documentation on workers and load balancing.

To get the most out of this page, we recommend you read the previous pages on SpatialOS concepts. If you need further information about terminology used, take a look at the glossary.


In SpatialOS, you have a separately-defined game world, outside of any code you write. This is because SpatialOS is designed to exceed the limits of the game world a single server could hold. So instead, SpatialOS coordinates multiple programs to do that. We call these programs “server-workers”.

As a developer using SpatialOS, you write the game code that runs within server-worker instances.

SpatialOS will run instances of server-workers, and use their combined computation to simulate the whole world. This means that the server-worker instances don’t know anything about each other - they might not even be on the same machine in the cloud. So when you’re writing the code for server-workers, you need to write code that can cope with only knowing about part of the world.

Writing code to deal with an arbitrary and not-necessarily-contiguous part of the world is the biggest difference from standard game development. It is the largest paradigm change when using SpatialOS and has the biggest impact on the way you architect features for your game.

Load balancing (splitting up the world)

One of the decisions you need to make as a developer is, “How many server-worker instances does my world need?” To decide this, you’re working out how much computation your world needs, and how many server-worker instances you need to do that work. In a multi-worker deployment, you use load balancing to split up the computation and control which worker instance does what computation.

There are different ways you can split up the world if you need to:

  • Zoning is a grid-based load balancing strategy that divides computation up for multiple server-worker instances by areas of authority.
  • Offloading is an alternative load-balancing strategy, which divides computation up by entity type.

We recommend trying to scale your game early. You should test with at least two server-worker instances running your world. Some problems won’t be obvious until you have multiple server-worker instances behind your game world.


Because each client-worker instance is tied to a player, and runs on the player's local machine, SpatialOS doesn't manage a client-worker's workload in the same way as it manages a server-worker's workload. This means that during game development, you set up client-workers and server-workers differently. The main difference is around how you sync data to and from the game world.

Like server-workers, client-workers can only see a part of the world. However, client-workers can see across server-worker boundaries, as shown in the diagram below:

More information

2019-12-10 Page updated with editorial review: Updated to clarify language and improve diagram
2019-09-11 Page updated with editorial review: Moved deployment information into separate page
2019-08-20 Page updated with editorial review: Added "Deployment runs"

Updated about a year ago

Workers and load balancing

Suggested Edits are limited on API Reference Pages

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