Get SpatialOS

Sites

Menu

Connect to the SpatialOS Runtime

This document relates to both MonoBehaviour and ECS workflows.

The SpatialOS Runtime manages your game world by keeping track of all SpatialOS entities and the current state of their components. To execute any kind of logic on these entities, we use workers. You can set up many different types of workers but the two main types are server-workers and client-workers.

(To find out more about workers in the GDK, see the introduction to workers in the GDK.)

It’s the workers (both server-workers and client-workers) which create a connection between your game and the SpatialOS Runtime. In order for them to do this, you need to set up the configuration of your worker types as part of your game development. Then, when your game runs, it creates worker instances which connect to the SpatialOS Runtime. During their creation, worker instances attempt to connect to the SpatialOS Runtime. If the connection fails, the creation of the worker instance fails.

If you are using the [MonoBehaviour workflow or the ECS workflow]/unity/alpha/content/intro-workflows-spatialos-entities), you can use the Worker Connector or the Worker to set up your workers (server-workers and client-workers) to connect to SpatialOS. Upon successfully connecting to the SpatialOS Runtime, your worker stores a Connection object.

Which connection flow to use

We provide two types of connection flow, depending on what kind of worker and what kind of deployment you want to connect to. In all cases, your worker contains a reference to a Connection object after successfully connecting to the SpatialOS Runtime.

Receptionist service connection flow

Use the Receptionist service connection flow in the following cases:

  • Connecting a server-worker or a client-worker instance to a local deployment.
  • Connecting server-worker instances to a cloud deployment.
  • The special case of connecting a client-worker instance to a cloud deployment from your Unity Editor for debugging. (Note you can also use the Locator to connect in this situation.)

Notes:

  • You usually connect client-worker instances to a cloud deployment via the Locator connection flow (outlined below) but you may want to debug your client-worker instance from your Unity Editor In this case, you can either use the Receptionist service connection flow via spatial cloud connect external <deploymentname> or the Locator service connection flow via the development-authentication. See the SpatialOS documentation to find out more about spatial cloud connect external <deploymentname>.
  • For mobile development, you need to use the new v13.5+ Locator connection flow to launch client-workers to the cloud from your Unity Editor.

Locator connection flow

From SpatialOS v13.5, there are two versions of the Locator connection. The new v13.5+ Locator, in alpha, has additional functionality to the existing v10.4+ Locator which is the stable version.

v10.4+ Locator connection flow (stable version)

Use this Locator service connection flow for:

New v13.5+ Locator connection flow (alpha version)

Use this Locator service connection flow for:

When to use the Connection object

Upon successfully connecting to the SpatialOS Runtime, your worker stores a Connection object. Use this object for:

Protocol logging

You can use protocol logging to log additional data to the data your worker sends and receives while connected to the SpatialOS Runtime.

This is disabled by default as the logs can get very big in size, very fast.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums