Connect to SpatialOS

All code examples in this section assume you have defined a MyComponents function as described in Providing components, and set up the following preamble:

#include <improbable/standard_library.h>
#include <improbable/worker.h>
#include <example.h>

using namespace improbable;

Before it can interact with the simulated world, the worker must connect to SpatialOS.

There are two ways of doing this:

Connecting a managed worker

To connect a managed worker, instantiate a worker::Connection object directly. Note that worker::Connection objects are not thread-safe.

This should be used to connect a server-worker, or a worker connecting for debugging purposes via spatial cloud connect external.

The connection is made through the receptionist service of the target deployment; the IP and port for that deployment are passed as arguments to the worker. To have these values filled in automatically, use the IMPROBABLE_RECEPTIONIST_HOST and IMPROBABLE_RECEPTIONIST_PORT placeholders in your worker's launch configuration.

Connecting an external/client worker

Use the worker::Locator object to enumerate cloud deployments and connect to a chosen deployment with authentication.

This is typically used to connect clients to a cloud deployment.

Values for UseExternalIP

You need to use the correct value for the UseExternalIp field in NetworkParameters.

The table below summarizes the connection possibilities:

Using worker::Connection directly Using worker::Locator
UseExternalIp == true Local client connecting via spatial cloud connect external proxy External client connecting to cloud deployment
UseExternalIp == false Managed cloud worker; local client connecting to local deployment Local client connecting to a local deployment as if it were a cloud deployment.

Connecting to a local Locator

When running the local API service, local clients can connect to local deployments using the local Locator. This allows clients to use largely the same code when connecting to either local or cloud deployments.

When connecting to the local Locator, you need to change your connection to connect to "localhost" and your local API port (rather than "" and "443"). By default the local API port is 9876 but you can also choose it when starting the local API service. You also need to enable the LocatorParameter UseInsecureConnection.

Example connection setup

The example below illustrates a very basic connection setup, where the function takes one argument specifying the worker's own ID, and an optional second one representing the receptionist IP address. If the latter is not provided, the worker connects to localhost. In either case, it uses TCP and connects using the internal IP address.

worker::Connection GetConnection(const std::string& worker_id, const std::string& hostname) {
  worker::ConnectionParameters parameters;
  parameters.WorkerType = "CppDocsWorker";
  parameters.Network.ConnectionType = worker::NetworkConnectionType::kModularTcp;
  parameters.Network.UseExternalIp = false;
  return worker::Connection::ConnectAsync(MyComponents(), hostname, 7777, worker_id, parameters).Get();

Worker attributes

A worker instance is assigned some static attributes when it connects to the SpatialOS Runtime:

  • a worker ID which is a unique identifier string for this particular worker instance.
  • a worker attribute that is used to determine which layer the worker instance is part of, and therefore which components it can simulate, either automatically or by the developer through ACLs.

Get the values of these configuration settings using Connection.GetWorkerId() and Connection.GetWorkerAttributes().

Updated about a year ago

Connect to SpatialOS

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.