These are the docs for 13.3, 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 →

Connecting to SpatialOS

All code examples on this page assume import improbable.worker.*; and import example.*; (the generated code namespace).

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

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"; = new NetworkParameters(); = NetworkConnectionType.Tcp; = false;

    return Connection.connectAsync(hostname, port, workerId, parameters).get();

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

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums