These are the docs for 13.0, 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 →

What are workers?

If you want anything to happen in your simulated world, you’ll need workers.

SpatialOS manages the world, keeping track of all the entities and what state they’re in. But on its own, it doesn’t make any changes to the world. All the logic and computation is done by workers.

Workers can be thought of as ‘spatial microservices’ that connect to a simulated world, and can read what’s happening, watch for changes, and make changes of their own. For example, a player’s client is one kind of worker. When a player presses a key, the client sends an update to SpatialOS saying that an event has happened on the entity that is the player’s avatar: for example, that the “fire” button has been pressed.

When this happens, the response to this event is also carried out by workers. A logic worker might need to create a new entity, the bullet. The client visualizes the action of firing. A physics worker checks to see if the bullet collides with anything. And if it hits another player, workers come in again, to carry out the logic of reducing health, and so on.

Which workers you need depends on your simulated world. Most games will need, at least:

  • managed workers (that implement server-side logic and physics)
  • clients (for players to interact with and view the game)

But you can have workers for whatever you need. You could have a worker that fetches data from outside sources (for example from a database, or real-time weather data, or a social network feed) and makes it part of the simulated world, or a worker that specializes in pathfinding and routing.


Building your simulated world in this way allows SpatialOS to scale it massively, without the complexity of more traditional approaches.

The amount of work that each type of worker needs to do will vary. It might be that, for one type of worker, there’s not much for it to do - so you only need one instance of the worker to do the work for the whole world.

But what happens when that amount of work increases, for example if a lot of players connect? Suddenly, that single instance of the worker can’t get all that work done. It might become incredibly slow, or fall over altogether.

This is where it becomes important that every entity in the world has spatial locality: it allows SpatialOS to split up the work in different areas of the world, and allocate it to different instances of a worker. When an instance of a worker is struggling with a high workload, SpatialOS automatically detects this. It then starts up new instances of the worker, and gives them responsibility for an area of the world, reducing the amount of work each instance is doing to a level it can handle.

This also means that an entity won’t necessarily stay on the same worker instance, even if that entity doesn’t move. SpatialOS may change which areas of the world a worker instance is responsible for, so entities move from one worker instance’s area to another. Even though the entity may be staying still, the worker instance itself is effectively moving.

Technical overview

Workers connect to your simulated world. They can:

  • read the current status of entities in the world
  • watch for changes to components
  • make changes of their own

Standard types of workers

You can build a worker in C++, C# or Java, using the C++ worker SDK, C# worker SDK, or Java worker SDK.

Managed and external workers

Most workers that connect to SpatialOS are managed: the workload of instances of the worker is controlled by SpatialOS, and if an instance becomes overloaded, SpatialOS will start more instances to handle the load.

Game clients, used by players to connect to a game, are an exception. Because each instance is tied to a player, and runs in the player’s machine, SpatialOS can’t manage their workload in the same way. These are external workers.

The work that workers do

The work done by workers includes:

  • Get input from the outside world, and write it to a component
  • Watch for changes to components
  • When something changes,
    • Run some logic
    • Write to a component

For more information about the kinds of work a worker can do, see the documentation for the worker.

Component delivery

You can save network bandwidth by controlling which components each of your workers receives when it checks out an entity. For more information, see Component delivery.

Write access to components

Multiple worker instances can read from a component, but only one of them at a time can write to a particular component.

In order to either read or write from an entity, worker types and instances need to be given access, using an access control list on each entity.

For more information, see Understanding write access.

Configuring workers

For information how you can configure workers, see the Configuring a worker page.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums