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 is SpatialOS?

SpatialOS is a platform for running large-scale simulated worlds. The most common use case is creating online multiplayer game worlds; but you can also use it to create other simulated worlds, for example a virtual city, a simulation of the internet, or a model of the brain.

As long as you can express the simulated world in terms of independent entities that have a location in space, you can use SpatialOS to simulate it.

Watch this video of our CTO, Rob Whitehead, explaining what SpatialOS is:

How it works

Creating the world

You set up your SpatialOS world by specifying: what are the objects in it? These will be the world’s entities: all meaningful objects in the world are entities.

Each entity consists of one or more components; each component adds additional behaviour or functionality. This is similar to the entity-component-system architectural pattern, common in software engineering.

Instead of systems, SpatialOS has workers, in an entity-component-worker architecture. Workers are described in more detail below.

You can read more about entities on the Entities concepts page.

To start with, you create a snapshot that lists all of the entities in the world and what their properties are (for example, their position in the world). Once you’ve done that, you can start the world running in a deployment.

Once the world is running

In a running deployment, SpatialOS manages and keeps track of the world, but it doesn’t actively make changes to entities and their components. Only workers can make changes to the world. Workers are programs, that you create, that read from and write to the entities in the world.

Because a worker is just a program, it can do a lot of things that aren’t related to the SpatialOS world - like executing game logic, or communicating with external databases. If it wants to interact with the SpatialOS world, it must use the SpatialOS APIs to do that.

Managed vs external workers

Workers can be managed or external.

Managed workers are called managed workers because their lifecycle is managed by SpatialOS. Based on how many instances of the worker the world needs, SpatialOS runs worker instances, and allocates them to different sections of the world.

If a worker instance gets overloaded, SpatialOS can start up another worker instance to help; if there’s too little work to do, it can stop worker instances. This is called load-balancing, and it’s one of the things that means SpatialOS can run very big virtual worlds. You can control some aspects of load-balancing, so it works in the right way for your world.

External workers are usually game clients. They aren’t managed by SpatialOS: instead, their lifecycle is controlled by a player connecting or disconnecting.

How workers interact with the world

It’s important to understand that workers only know about a part of the world. Managed workers know about the part of the world that SpatialOS allocates to them, plus a region around those areas. External workers only know about the part of the world around the player’s entity.

This means that, when you’re writing code for workers, you must write as though you only know about the world around you, for any arbitrary section of the world. SpatialOS automatically sends workers information about what’s happening to the entities within the areas they know about. If you want information about the world further away, the worker must query SpatialOS for it.

SpatialOS diagram

Overlap: In the diagram, you can see that more than one worker instance knows about the same part of the world. In order to prevent two workers trying to make changes at the same time, only one worker instance at a time is allowed to write to a given component of a given entity. Many workers may be able to read from the entity; but only one can write to that particular component on that particular entity.

Entities can freely move into and out of an area that a worker instance knows about. SpatialOS manages this handover of entity data seamlessly, so players shouldn’t notice when this is happening.

You can read more about workers on the Workers concepts page.

The state of the world

It’s important to understand that canonical state of the world is in SpatialOS, not in the worker. This matters because it means that workers need to send information to SpatialOS. You can keep information locally on a worker, if you only need that worker to know about it.

But if any other worker will ever need to know that information, it must be sent to SpatialOS.

Developing with SpatialOS

There are SDKs that let you write workers in several different languages: C++, C#, and Java.

When you’re developing a worker, you can write the worker code and try it out in a local deployment for debugging and testing. This is very similar to running a SpatialOS deployment in the cloud - just smaller. When you’re ready to try running your world at scale, you can deploy to the cloud, which also means you can make it available to external players.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums