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

Introduction to the Unity SDK

You need to set up SpatialOS before you can work on a project using the Unity SDK. For more information, see the setup guides: Windows, macOS, Linux

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 may 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.

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.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums