Get SpatialOS




You can use the game engine Unity as a worker in a SpatialOS project, to add physics, game logic, and visualization to a SpatialOS simulated world. We provide a Unity SDK to make it easier to use Unity as a worker.

Compatible Unity versions: Unity versions 5.5.3 and 5.6.0 have been tested with SpatialOS. Later versions will probably work fine, but have not been extensively tested.

The relationship between SpatialOS and Unity

When you’re using Unity on its own, a Unity scene is the canonical source of truth about the game world. What’s in the Unity scene is in the game world.

When you use Unity as a SpatialOS worker, this isn’t true any more: the canonical source of truth is the world of the SpatialOS simulation, and the entities in that world. Each Unity worker has a view onto part of that world. It represents the entities from SpatialOS as GameObjects in a scene.

A Unity worker can do whatever it likes to its own representation of the world, run whatever logic it likes, etc etc. But, if the worker doesn’t send these changes to SpatialOS in the form of an update to a SpatialOS entity, those changes will only ever be local: they can’t be seen by any other worker.

Sometimes this is fine. For example, if on a client worker, you are making a purely visual change to a scene, no other worker needs to know about it, so it doesn’t need to be represented in SpatialOS.

But for anything else that another worker would need to be aware of, those changes must be made to a SpatialOS entity.

How can Unity workers change the SpatialOS world?

They can:

  • create entities
  • delete entities
  • set properties of an entity
  • trigger an event on an entity
  • send a command to an entity

How do Unity workers get information about the SpatialOS world?

Within the worker’s area of interest, SpatialOS will send the worker updates about changes to components/entities it can read. So a worker can:

  • get the value of a property
  • watch for events being triggered
  • watch for commands being called

Outside its area of interest, a worker can find out about the world by querying for entities.

What to use Unity for

Typical usages of Unity with SpatialOS include:

  • A player’s game client reads the position of each visible SpatialOS entity, and updates the position of the corresponding Unity GameObjects.
  • A player’s game client writes the user’s input to a component on the player’s entity, so it gets synchronized to other workers in the world.
  • A physics worker applies forces to GameObjects, based on properties or events in the world. It then updates the position of each of the GameObject’s corresponding entities.

SpatialOS and Unity concepts

Entities and GameObjects

SpatialOS entities correspond to Unity GameObjects. You can associate entities with a prefab by specifying the name of the prefab when you create an entity.

When an entity is created, the Unity SDK will create and manage a GameObject for that entity.

For information on how to create an entity, see Creating an entity.

You can have GameObjects in your scene that don’t have entities associated with them: it’s just that they’ll only exist on one worker, and no other workers will know about them.


The terminology here can be confusing, because both SpatialOS and Unity have something called “components”.

In SpatialOS, components are the features of entities, defined in your schema. In Unity, components describe parameters and scripts that exist on GameObjects.

The SDK lets you access SpatialOS components from Unity components, by providing component Readers and Writers. You can use these from C# MonoBehaviour scripts to read from and write to SpatialOS components.

Useful software for developing with Unity

These aren’t required, but when you’re developing with Unity, you might find the following tools useful:

Internal features

The Unity SDK is provided as source files to aid in debugging. This means that internal classes, structs and methods are all visible to your code. You should take care to avoid using these items, as they can change without notice outside of major versions.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums