Connect to SpatialOS

All code examples on this page assume the generated code namespace:

import improbable.worker.*;
import example.*;

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

There are two ways of doing this:

  • Instantiate a improbable.worker.Connection object directly. This allows to connect a managed worker (i.e running in the cloud and started by the SpatialOS runtime) or a remote worker used for debugging (via spatial cloud connect external). The connection is made through the receptionist service of the targeted deployment for which the IP and port should be passed as arguments to the worker. These values can be filled-in automatically at runtime by using the IMPROBABLE_RECEPTIONIST_HOST and IMPROBABLE_RECEPTIONIST_PORT placeholders in your worker's launch configuration.
  • Use the improbable.worker.Locator object to enumerate cloud deployments and connect to a chosen deployment with authentication. This is typically used to connect an external client to a cloud deployment.

The value given for the useExternalIp field in the NetworkParameters class is also relevant.
The table below summarizes the connection possibilities:

Using improbable.worker.Connection directly Using improbable.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.

The example below illustrates a very basic connection setup, where the function takes three arguments specifying the worker’s own ID as well as the receptionist’s IP and port. It will use TCP and connect using the internal IP address.

private static Connection getConnection(String workerId, String hostname, int port) {
  ConnectionParameters parameters = new ConnectionParameters();
  parameters.workerType = "JavaDocsWorker";
  parameters.network = new NetworkParameters();
  parameters.network.connectionType = NetworkConnectionType.ModularTcp;
  parameters.network.useExternalIp = false;
 
  return Connection.connectAsync(hostname, port, workerId, parameters).get();
}

Note that improbable.worker.Connection objects are not thread-safe.

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.