Try SpatialOS



How to learn SpatialOS

There’s plenty you need to learn in order to build a game on SpatialOS.

This page runs you through a suggested order of things to learn, and tells you about the resources available to you to do that.

Beginner level

This is the stuff you must know in order to do anything with SpatialOS, otherwise it won’t make sense.

1. The fundamentals of the system

Firstly, you need to understand about SpatialOS as a system: how it fundamentally works.

The game world

In a game running on SpatialOS, the world is a core concept. The SpatialOS world is the canonical source of truth about things in your game.

Entities are the things in your game. All of the data needs to be stored in entities, using their components.

Where you can learn about the SpatialOS world

  • The SpatialOS tour gets you to set up a running world, so you can inspect the entities in it.
  • It might be worth reading Designing components to help you understand what kind of data you can store in an entity.

To start with, you just want to cover these as background concepts. Leave practical details (like how you’d create an entity) til a bit later.

Making the world go

Defining the world separately in this way isn’t how you’d usually do it. The reason for having this separately-defined world is that you’ve got to store this state somewhere, and it’s no longer on a single server.

The whole point of SpatialOS is to exceed those limits: instead of one server/program managing the server-side of the game world, SpatialOS co-ordinates multiple programs to do that.

Each program can only see part of the world.

The game world

Any program that connects to the SpatialOS, we call a worker.

Normally, you’ll have two main types of worker:

  • Managed workers on the server side. These are the ones that SpatialOS co-ordinates and load-balances.
  • Client workers are the programs that players run on their machines to connect to the game.

Where you can learn about workers

Practical stuff: Deployments and snapshots

This isn’t conceptually interesting, it’s just stuff you need to do to make things happen.

You’ll need to know how to start (and stop) a deployment - which is really just a running instance of your game - both locally and in the cloud.

The command-line cheat sheet (preview below) might be useful here:

spatial cheat sheet

You’ll also need to know how to create and manipulate snapshots. Snapshots are a snapshot of the state of a SpatialOS world. You need one to run a deployment, because we need to know what the state of the world is when the game starts.

Where you can learn about deployments and snapshots

Practical stuff: schema

Your schema is how you define what components entities can have. The reason SpatialOS gets you to define this is to make it easy for different workers to communicate with each other.

You’ll generally only interact with schema when you’re adding new components or changing existing ones.

You need to know roughly what schemalang is, and how you need to use it. You also need to know about generating code from schema: you have to do this every time you change schema.

As part of this, you’ll learn that components can have three constituent parts: properties, events and commands.

Where you can learn about schema

2. Tools you have

So you’ve got a world, and you’re going to write code for your workers that interacts with the world.

The next thing to learn is: What can you actually do to the world from your worker code?

Game engine SDKs; core SDKs; using your own engine

You need to know that there are different SDKs for working with SpatialOS, so you know which one you’re going to use.

If you want to use a game engine to work with SpatialOS, you can use the raw SDKs to build an integration:

You can also make workers using any of those SDKs without integrating a game engine.

Where you can learn about SDKs

Components: Properties

You learned about properties as part of schema: they’re an element of a component that stores persistent data about an entity.

You’ll need to know what data you should use properties for, and when a property isn’t appropriate. Some data doesn’t need to be stored at all - for example, if it’s only local to a client.

From workers, you can get the value of properties, set them, or watch for and respond when a property changes.

Where you can learn about properties

  • If you didn’t read it before, take a look at Designing components for an overview of the different elements of a component.

Components: Events

You learned about events as part of schema: they’re an element of a component that stores transient data about an entity that happens as a single event.

You’ll need to know what data you should use events for, and when an event isn’t appropriate - for example, when a command might be better.

Where you can learn about events

Components: Commands

You learned about commands as part of schema: they’re an element of a component that lets you send a request, or message, between workers (like an RPC).

You’ll need to learn how to send commands, and how to know which worker will receive a command (it’s to do with authority, which we’ll talk about below). You’ll also need to know about the caveats and limitations of commands

This will help you understand what situations you should use commands in, and when commands aren’t appropriate.

Where you can learn about commands

What can a worker see?

By this point you’ve understood that SpatialOS co-ordinates multiple workers to cover the whole world.

There’s an important consequence to that, which is that workers can’t see the whole world. They only get a view onto part of the world (we say this is the area they have checked out).

You need to understand:

  • the idea that each worker has a checkout area
  • what “checking out” is
  • that the code you write has to take this into account

Where you can learn about worker view

  • Glossary entry on checking out
  • For a more advanced view on this, see the glossary entry on interest. Interest controls what it is that a worker sees.


You learned that workers can’t see the whole world. But sometimes they’ll need to get information about entities outside of their view.

There are two tools you’ll need to know about to do this:

  • normal queries, which let a worker search for entities and get information about them at a single point in time
  • streaming queries, which let a worker (effectively) check out an entity outside their checkout area

Where you can learn about queries

Adding new entities

You’ve already learned about entities - now you need to know how to create them.

You’ll need to know that an entity is essentially just a group of components (defined in schema, remember?) so when you’re creating an entity you need to specify which components it has.

You also need to specify which workers can read from and write to those components - there’s more about this in Authority below.

Where you can learn about adding entities

  • It’s worth taking a look at Designing entities if you’re adding entities for the first time.

Practical stuff: the required components

Alongside components that you define yourself, there are also components from the standard schema library that Improbable provides.

You need to know which components all entities must have, and what they’re for.

Where you can learn about required components

Practical stuff: Building

You need to know how to build your worker code into what we call an assembly. (You should have come across this term earlier, as you need an assembly to run a deployment.)

It’s worth knowing what things you need to build when: do you need to re-generate code from schema, compile code for a managed or client worker, or something else? Making sure you only build what’s necessary will speed you up a lot.

Where you can learn about building

  • All the tutorials and recipes will tell you what you need to build in their context.
  • There’s a general page on Building.

3. Authority and checking out

You learned earlier that workers can only see part of the world. Now you need to know why that is, and this should fundamentally shape how you think about developing with SpatialOS.

In order to prevent two workers trying to change the same thing at the same time, for each component on each entity, only one worker can write to that component: we call this write access “authority”.

So if the view of two workers overlaps - for example, if a client and a managed worker can “see” the same part of the world - only one of them will be able to write. The other will only be able to read.

Where you can learn about authority

Practical stuff: Worker attributes, worker requirements

You need to decide which type of worker is allowed write access to each component. The type of worker is called a worker attribute; at the component end, worker requirements specify which worker types are allowed to write to it.

Practically speaking, this is done using a special component called an access control list, or ACL. Each entity needs to have an ACL.

Where you can learn about worker attributes and ACLs


Earlier we discussed how workers can only see part of the world. Which part of the world they see is determined by their interest.

You need to understand both entity and component interest, and how it affects what your workers can see. In particular, you need to know about the entity interest radius, which affects

Where you can learn about interest

Intermediate level

The topics at this level will help you become a decent SpatialOS developer. You’ll learn how to reason about the system, and build good architecture that makes use of the features without falling into common traps.

At the moment this is just a list of topics; more detail will come in a future documentation release.

4. Thinking spatially (ie how to use the tools to architect something sensible)

What should happen on each worker

  • What should happen locally
  • How to use those tools to design a game feature
  • Designing authority


Designing components


Global state

No resources yet.

5. Starting from scratch, things you have to do when you’re setting up a project

Useful resources:

6. Optimisation and load balancing

Chunks and world units

How interest and authority are calculated

7. Tools for debugging

8. Interacting with external systems

9. Managing deployments

Advanced level

At the moment this is just a list of topics; more detail will come in a future documentation release.

10. Configuring workers

Build configuration

  • Build configuration

    Inside the worker.json. Including using the generated build scripts, and writing custom build scripts.

Bridge configuration

Launch configuration

Worker flags

Configuring load balancing

  • Load balancing

    Inside the worker.json. Including singleton workers and static and dynamic load-balancing.

Worker permissions

11. Integrating a game engine

12. Running a playtest

No resources yet.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums