These are the docs for 11.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 →

A tour of SpatialOS

Welcome to SpatialOS! This hands-on tour will take you through the unique benefits of developing with SpatialOS.

You’ll learn what the platform does, see how a game feature is implemented, and discover the tools and infrastructure that come with SpatialOS.

If you have a SpatialOS account, you can follow the steps yourself.

What is SpatialOS?

SpatialOS is a cloud compute platform that you can use to develop bigger, better multiplayer games, faster, and with smaller teams. You can make games of any genre and size, with game worlds of tens of thousands of square miles, shared by thousands of players.

You develop your game on your machine using a game engine like Unity or Unreal. When you’re ready to launch the game, you deploy it to the cloud. SpatialOS runs many instances of the game engine in headless mode (we call these workers), stitching them together so they form a single game world. All SpatialOS games are multiplayer by default, and you don’t have to write a single line of networking code.

There are no license fees. SpatialOS is free to try, and free throughout development if you qualify for our Games Innovation Program.

The Wizards demo

Wizards is a demo game built using SpatialOS and Unity. The game world is a forest, inhabited by two teams of wizards and lumberjacks. Lumberjacks chop down trees and collect the wood; wizards cast spells (rain and lightning). When trees are chopped down or set on fire, they grow back over time.

It looks like this:

The Wizards demo

This demo looks fairly simple, but it’s actually a massively multiplayer online game with distributed high-fidelity physics and game logic, and thousands of AI-driven NPCs. An unlimited number of players can connect to its continuous game world with an area of a square kilometre. That’s tiny by SpatialOS standards, but it’s enough to show what the platform can do.

Hands-on tour

During the hands-on tour of the Wizards demo, you’ll:

  • set up SpatialOS
  • run the game in the cloud
  • play and explore the game
  • take a closer look at a game feature and the code behind it
  • try the tools and infrastructure

The tour lasts approximately 10 minutes.

Set up SpatialOS

In this step, you’ll install the spatial command-line tool, which you need in order to run the Wizards demo game.

1. Sign up for SpatialOS

If you haven’t already, sign up for SpatialOS.

2. Install the spatial command-line tool

By installing spatial, you agree to the SpatialOS EULA.

On Windows

  1. Install the chocolatey package manager.

  2. Open a terminal window, and run choco install spatial --version 1.1.6 --yes.

On Mac

  1. Install the Homebrew package manager.

  2. Open a terminal window, and run brew tap caskroom/cask && brew update && brew cask install spatial.

3. Check and complete the installation

In the terminal window, run spatial update. You should see the following output:

Current version of the 'spatial' command-line tool: <version number>
Attempting to download the latest version...
Did not update 'spatial'. Latest version is already installed.

Run the game in the cloud

In this step, you’ll download the source code of Wizards, and use the command-line tool to deploy it - that is, run it in the cloud - so that players anywhere in the world can join.

1. Download project source code

Download and unpack this zip file, which contains the complete source code, assets, and configuration files for the Wizards demo.

2. Deploy to the cloud

Once you’re ready to try out a SpatialOS game, you can run it in a cloud deployment. This means that SpatialOS will start workers (ie instances of game engines in headless mode) in the cloud to run the server-side game logic, and you can connect clients to play the game.

Normally, before you run a cloud deployment, you’d need to build all the files your game uses and upload them (using the command spatial upload) to the SpatialOS servers. This includes executable files for the clients and workers, the assets, and so on. We call that set of game files an assembly.

But to make this deployment easy, we’ve already uploaded the Wizards assembly for you. All you need to do is to start the deployment:

  1. Find the project name generated for your account. You can find yours in the SpatialOS console. It will be something like beta_someword_anotherword_000.

  2. Open a terminal, and use cd to navigate to the directory where you extracted the source code of the demo.

  3. In the following command, replace insert_your_project_name_here with your project name (obtained on step 1). Then, run it:

    spatial cloud launch wizards_demo_assembly default_launch.json wizards_demo --snapshot=snapshots/default.snapshot --project_name=insert_your_project_name_here

    After a couple of minutes, you should see Successfully created deployment printed in the terminal.

    Explore the game

    Start a game client

    Players connect to your game by running a game client on their machines. They can download it directly from the SpatialOS servers, or you can distribute it in any way you want (for example, through Steam).

    For this demo, download the game client from the SpatialOS servers:

    1. Install the SpatialOS game launcher (Windows / Mac). You only need to do this once.

    2. Open the SpatialOS console in a new tab.

    3. Click on the name of the deployment (wizards_demo).

    4. Launch the game by clicking ▷ Launch:

    The Launch button

    The Launcher will download the game client and run it. This may take a few seconds.

    Once it’s running, click CONNECT to join the game!

    Open the Inspector

    The Inspector is a web-based tool that lets game developers explore the internal state of a SpatialOS world. You’ll use it through this tour to find out about the main SpatialOS concepts.

    From the deployment page you had open already, click Inspect, which opens the Inspector in a new tab. We suggest putting the game window and the Inspector window side by side:

    Game and Inspector windows

    The Inspector window

    Every thing in your game world is an entity. Entities are made of components which describe their properties (like position, health, waypoints).

    The main area of the Inspector shows you a top-down, real-time view of the entities in your game world. The trees are shown in green, the NPCs in red, and the players in blue. (These colors are completely configurable, of course.)

    The Inspector windows

    The bottom-right list initially shows how many entities of each type there are right now. We’ll look at this area in more detail later.

    The top-right list shows the workers connected to SpatialOS. This includes the workers that run the server-side game logic (in this case, UnityWorker0 and UnityWorker1), and a game client for every player connected (in this case, just one: yours!).

    The number next to each worker represents its load: a measure of how much work it is doing. SpatialOS uses this number to start and stop workers as necessary.

    Optional: stop down a worker

    To see worker management in action, you can stop one of the workers running the game logic, and see how SpatialOS instantly reassigns the whole world to the single remaining worker, while it starts a new one - without any disruption to players at all. To try this:

    1. Click the i icon to the left of UnityWorker0 in the list of workers. This shows details about that worker.
    2. Click the red remove worker button. This shows a confirmation dialog.
    3. Click the Stop Worker button.

    SpatialOS stops the worker immediately. Just a few seconds later, the load-balancing algorithm kicks in, and it starts a new worker. Note that nothing at all happens in the game window - the client isn’t even disconnected. Load-balancing is completely invisible to players!

    Walk around

    In the game window, you can control your character - a wizard with a pointy hat - using the WASD keys. Rotate the camera by holding the right mouse button and moving the cursor; zoom in and out using the scroll wheel.

    The Inspector shows you a live view of the game world, so you can watch your character’s entity moving in the Inspector while you move it in the game window. If you can’t find your entity:

    1. In the Inspector window, pan the view until the entity list on the right shows one Player entity.

    Player entity filter

    1. Click on the word Player in the list. Every other entity in the main area should be dimmed, making the Player entity easier to spot.

    Player entity selected

    1. In the main view, click on the icon of the Player entity to select it. The bottom right area of the inspector shows you the current values of its properties.

    Find the property called coords in the improbable.Position component:

    The Player's position

    Go back to the game window, and use the WASD keys to move your character. You’ll see the values of the position properties changing as you move.

    Optional: cross worker boundaries

    The top-right area of the Inspector shows two workers of type UnityWorker, which run the game logic for the simulation. Hold the CTRL key and click on both. You’ll see red and green outlines appearing in the map view:

    Worker interest regions

    These outlines represent the regions that contain the entities each worker is responsible for (we call these their authority regions). SpatialOS assigns these regions in real time, and they change dynamically in response to what happens in the game world, or when workers start or stop.

    Look again at the components of the Player entity. You can see that one of the two workers currently has write access to most of its components (in this case, UnityWorker7):

    Player workers assignments

    Write access means that that worker can make changes to the component. Other workers might be able to read from it - but only one worker can write.

    Note that the client has write access to two components. This is how the client can send the player’s inputs to SpatialOS.

    In the game window, move your character across the boundaries of the authority regions. At some point you’ll see the components move from being under one worker’s authority to being under another’s, but you won’t see any change in the game - even though the data for the character was handed over to the other worker, which could be running on a different physical machine.

    In SpatialOS all this happens without any effort from the game developer; it’s also entirely invisible to the user.

    Optional: invite more players

    Every SpatialOS game is multiplayer by default, so you can invite other players to join. If you want to do this, follow these steps:

    1. Go to the deployment page for your game in the SpatialOS console.
    2. Click the Share button.
    3. Check the checkbox, and click Get Share URL:


    1. Share the link with anyone you want to invite.

    Start a fire

    In the game window, move your character next to a group of trees that haven’t been chopped down by the lumberjacks. Then, in the Inspector window, select an entity that represents one of these trees.

    The tree entity has a Flammable component with properties that represent whether it is on fire, the size of the flames when it is, and so on. You can see that it is currently not on fire:

    Properties of a tree not on fire

    In the game window, press the E key to go into spellcasting mode, point at the base of a tree with the mouse, and click. The wizard will cast the lightning spell, and within a couple of seconds, the tree will catch fire.

    Trees on fire

    Notice how the values of the Flammable component in the Inspector now show that the tree is on fire.

    Properties of a tree on fire

    After a few seconds you will notice something else: fire propagates to other nearby trees. And if your character is too close to one of the trees, it may catch fire too!

    The trees will eventually burn down completely:

    Trees burnt down

    You can see their final internal state in the Inspector window:

    Properties of a burnt down tree

    Take a closer look at a game feature

    We’ll now take a closer look at the inner workings of the fire propagation feature you just tried.

    Depending on how close the trees are, setting any single one on fire could set the entire game world on fire. This involves game logic, and the propagation of state between entities controlled by different workers.

    So this feature needs both a data model to represent flammable entities, and game logic to make fire spread from one entity to another.

    Data model

    The data model for your entities is defined in the project’s schema. It describes the components that make up the entities, the names and data types of the properties of each component, and the commands that can be performed on them.

    Here’s the relevant part of the schema for the Flammable component, which all flammable entities will have:

    enum FireEffectType {
    BIG = 0;
    SMALL = 1;
    component Flammable {
    id = 1400;
    bool is_on_fire = 1;
    bool can_be_ignited = 2;
    FireEffectType effect_type = 3;
    command Nothing ignite(Nothing);

The Flammable component has three properties that define how flammable entities are represented in this demo (is_on_fire, can_be_ignited, and effect_type) and a command that defines an action that can be performed on flammable entities (ignite).

Game logic

The schema described above defines a data model for flammable entities, but it says nothing about how these entities should behave. This game logic can be implemented using your game engine (Unity or Unreal). The Wizards demo uses Unity.

Here’s the code that runs when the Flammable component receives an ignite command:

private void Ignite()
    if (!flammable.Data.isOnFire && flammable.Data.canBeIgnited)
        spreadFireCoroutine = StartCoroutine(TimerUtils.WaitAndPerform(FireSpreadInterval, SpreadFire));

This does two things - first it calls SendIgniteUpdate, which updates the is_on_fire and can_be_ignited properties previously defined in the schema:

private void SendIgniteUpdate()
    var update = new Flammable.Update();

Send(update) sends this new information to SpatialOS, which automatically propagates it across the game world. This is what allows other workers and clients to know about the state of this particular entity.

Second, it makes SpreadFire run periodically to spread fire to other flammable entities in its vicinity:

private void SpreadFire()
    var count = Physics.OverlapSphereNonAlloc(transform.position, FireSpreadRadius, colliders);
    for (var i = 0; i < count; i++)
        var other = colliders[i].transform.GetComponentInParent<FlammableDataVisualizer>();
        if (other != null && other.canBeIgnited)

This piece of code looks for entities within FireSpreadRadius, and if they have a Flammable component, and are not burnt down or already on fire), sets them on fire.

The code is concise, self-explanatory, and very high-level. It uses a mixture of Unity code (Physics.OverlapSphereNonAlloc), SpatialOS APIs (.Send(update)), and code generated from the schema specifically for your project (update.SetIsOnFire).

There isn’t any networking code, any code to deal with entities migrating across server boundaries, or any code to exchange data between workers. But this code can run, unmodified, in a game world tens of thousands of square miles big, simulated by hundreds of workers.

Try the tools and infrastructure

Your SpatialOS game can run on as few or as many cloud servers as it needs - hundreds if necessary. SpatialOS does all of the heavy lifting associated with running a distributed system of this scale; it also provides the tools to monitor it.

You can access the logs and metrics for your deployment by clicking the relevant button at the top bar of the Inspector window, or at the Details tab of your deployment’s page in the SpatialOS console:

Logs and metrics


The metrics dashboards show detailed information about the health and performance of your deployment, including CPU, memory and bandwidth usage, entity and player counts, worker load, and many more, aggregated across all workers, and plotted over time:


You can also define custom metrics for values that are important for your game (say, the amount of in-game currency traded), and visualize them using the same dashboards.


The logs viewer shows all the information, warning and error messages generated by your game:


Distributed logging is an invaluable tool to diagnose and debug your deployment, and to record noteworthy events. Like the metrics dashboard, the logs are aggregated across all workers.

Stop the deployment

Now you’ve finished with the deployment, click STOP.

STOP button on overview

You should always stop a deployment once you’ve finished using or testing it.

Note: By default, if you don’t stop a deployment, it’ll be stopped automatically 6 hours after it was started.


This tour of the Wizards demo gave you a high-level overview of what SpatialOS can do for your game, how it works, and the tools it gives you. Here are the key takeaways:

  • You can build multiplayer games of any scale using SpatialOS and its game engine integrations.
  • You develop and test the game in your own machine, and run the game at scale on cloud servers managed by SpatialOS.
  • You write game logic using the SpatialOS SDK and your game engine, such as Unity or Unreal, in headless mode. We call these “workers”.
  • There’s no need to write any networking code. By default, every game is multiplayer, and can run on hundreds of servers.
  • SpatialOS runs workers in the cloud - as few or as many as necessary to support a game world as big as you want.
  • You can inspect the internals of your game in real time using the web-based Inspector.
  • You can monitor the health of your game using metrics dashboards and distributed logging.

What’s next?

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums