These are the docs for 13.8, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 is the newest →

Workers and load balancing

This page covers: Server-workers and load-balancing them. Deployments (in that the Runtime manages the lifecycle of server-workers). Client-workers.

Before you read this page, you should read What is SpatialOS? and World, entities, components.


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.

Server-workers on the world

As a developer using SpatialOS, you will 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.

Server-workers with the world

This - writing code to deal with an arbitrary, not-necessarily-contiguous part of the world - is the largest paradigm change when using SpatialOS, the biggest difference from standard game development. This idea will have the biggest impact on the way you architect features for your game.

All of these server-worker instances run using a copy of the same binary.

Splitting up the world, or “load balancing”

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. When you decide this, you split the world up - there are a few different ways you can do this - into regions; each region will be the area of authority of a server-worker instance.

Read more about authority

For a very small world, one instance might be enough.

We definitely recommend trying to scale your game early. You should test early on with at least two server-worker instances running your world. While there’s lots of stuff SpatialOS does for you, it can be hard to reason about how to architect your game properly to deal with re-assignments of write access authority from one server-worker instance to another. And some problems won’t be obvious until you have multiple server-worker instances behind your game world.


SpatialOS hosts games for you. We call an instance of a running game a deployment.

As you learned above, you decide how many server-worker instances your world needs, and how to organise them across the world. In a deployment, SpatialOS starts those server-worker instances for you, running them on machines in the cloud (and orchestrating this for you - you don’t need to interact with the machines directly).

SpatialOS also mediates client-worker connections.

Deployment diagram


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:

Client-worker diagram

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums