Skip to content
This repository has been archived by the owner on Oct 11, 2019. It is now read-only.

Latest commit

 

History

History
82 lines (56 loc) · 3.87 KB

introduction.md

File metadata and controls

82 lines (56 loc) · 3.87 KB
Raw

Introduction to the SpatialOS SDK for Unity

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

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

Compatible Unity versions: Unity versions 2017.3.0 and 2018.1.3 have been tested with SpatialOS. Other versions may work fine, but have not been extensively tested.

License

Documentation

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 and run whatever logic it likes 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 SpatialOS SDK for Unity 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.