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 →

Setting up Unity as a SpatialOS worker

Things involved in setting up Unity as a SpatialOS worker:

Instead of setting up Unity from scratch, it’s much easier to start from Blank Project, which has all the setup work done for you.

Multiple versions of Unity

If you have multiple versions of Unity installed, you can control which version is used when running spatial build. Set the UNITY_HOME environment variable to the folder you’ve installed Unity to.

For example:

  • On Windows, set UNITY_HOME to C:\Program Files\Unity 5.6.0.
  • On macOS, set UNITY_HOME /Applications/Unity5.6.0. This path cannot contain any spaces.

Directory structure

For information about the required directory structure (including the mandatory worker.json file which contains most of the configuration), see the Unity directory structure page.

WorkerConfigurationData and Bootstrap.cs

The base class for setting up a Unity instance as a SpatialOS worker is SpatialOS, which contains all the relevant methods and callback hooks for dealing with the lifecycle of the worker.

We recommend creating an empty GameObject in the scene and adding a Bootstrap script to it. The following snippet sets up a basic connection to SpatialOS:

public class Bootstrap : MonoBehaviour
    private void Start()
        SpatialOS.ApplyConfiguration(new WorkerConfigurationData());

The WorkerConfigurationData class allows you to specify configuration, including Networking and Debugging, which is a blob of data passed to SpatialOS at connection time.

You’ll be able to edit the configuration from the Bootstrap script in the Unity Editor.

Editing WorkerConfigurationData in Unity

For more information, see the in-code documentation for Improbable.Unity.Configuration.WorkerConfigurationData.

For examples, see the SpatialOS Blank Project on GitHub.


A SpatialOS Unity worker project usually contains two scenes, corresponding to the two types of worker:

  • The Assets/ClientScene.unity - Used to build and start the player’s client. It corresponds to the UnityClient worker type.

  • The Assets/PhysicsServerScene.unity - Used to build and start the physics worker. It corresponds to the UnityWorker worker type.

Read more about Default worker building and how to customise worker build and packaging. There’s also an example of using multiple scenes per worker.


Some of the Unity layers are reserved. You need to name them as shown below if you wish to use the CoreLibrary.

Unity layer Required name Internally used for
31 [Improbable-31] Prefab pools.

Component interests

Component interests define which components a Unity worker will be sent updates for.

To ensure that only relevant component updates are sent through the network, SpatialOS uses a concept of component interests. They are automatically determined by keeping track of all the component readers and writers injected using the [Require] attribute.

You can manually specify initial components to receive updates for by using the initialComponentsToCheckout worker bridge setting, but this configuration is overridden by the automatic interest calculation described above. Workers will receive updates for components they have a registered interest in, as well as the components they have authority on.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums