Sites

Menu
These are the docs for 14.1, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.3 is the newest →

Server-worker configuration file

Use this file to specify the configuration parameters of a server-worker.

File structure and fields

The server-worker configuration file has no naming conventions, but it should have the following structure:

{
  "workerType": "...",
  "layer": "...",
  "entityInterest": {
    "rangeEntityInterest": {
      "radius": 2
    }
  },
  "streamingQuery": [
    ...
  ],
  "componentDelivery": {
    "default": "RELIABLE_ORDERED",
    "checkoutAllInitially": true
  },
  "componentSettings": {
    ...
  },
  "permissions": {
    "entity_creation": {
        "allow": true
    },
    "entity_deletion": {
        "allow": true
    },
    "entity_query": {
        "allow": true
    }
  },
  "launchConfiguration": {
    "localDeployment": {
      ...
    },
    "cloudDeployment": {
      ...
    }
  }
}

The following table shows the fields that you are required or optional to specify in a server-worker configuration file:

Field Required/Optional Description
workerType Required Used to identify this worker type in your project. A workerType must be unique project-wide. The workerType specified in this field must also match the workerType that your worker instance reports in its ConnectionParameters when connecting to a deployment. For more information, see the API reference.
layer Required The name of the simulation layer of this worker type, used to determine the load balancing strategy. For more information, see the layers documentation.
entityInterest Optional Specifies the entities to subscribe to in addition to the ones the worker is has write access authority over. The semantics are analogous to the entity_interest field in the previous configuration version.
streamingQuery Optional Specifies the streaming queries the bridge will subscribe to. Analogous to streaming_query in the previous configuration version.
componentDelivery Optional Specifies the delivery settings for the worker’s components. Analogous to component_delivery in the previous configuration version.
componentSettings Optional Defines component specific settings. Analogous to component_settings in the previous configuration version.
permissions Optional Specifies the worker’s entity permissions. Analogous to permissions in the previous configuration version, with the difference that the permissions property here is a single permission object rather than an array.
launchConfiguration Required Describes how to start a worker instance. It contains two fields:
- localDeployment: Specifies how to start a worker instance locally. See below for more information.
- cloudDeployment: Specifies how to start a worker instance in the cloud. See below for more information.

Local launch configuration

Use the local launch configuration section to specify how to launch a server-worker instance locally. Below is an example excerpt:

      "windows": {
        "localBuildDirectory": "bin/x64/ReleaseWindows",
        "command": "MyWorker.exe",
        "arguments": [
          "${IMPROBABLE_RECEPTIONIST_HOST}",
          "${IMPROBABLE_RECEPTIONIST_PORT}",
          "${IMPROBABLE_WORKER_ID}",
          "--my_additional_flag=true"
        ]
      },
      "macos": {
        "localBuildDirectory": "bin/x64/ReleaseMacOS",
        "command": "MyWorker.app",
        "arguments": [
          "${IMPROBABLE_RECEPTIONIST_HOST}",
          "${IMPROBABLE_RECEPTIONIST_PORT}",
          "${IMPROBABLE_WORKER_ID}",
          "--my_additional_flag=true"
        ]
      },
      "linux": {
        "localBuildDirectory": "bin/x64/ReleaseLinux",
        "command": "MyWorker",
        "arguments": [
          "${IMPROBABLE_RECEPTIONIST_HOST}",
          "${IMPROBABLE_RECEPTIONIST_PORT}",
          "${IMPROBABLE_WORKER_ID}",
          "--my_additional_flag=true"
        ]
      }

There must be a configuration for each platform the worker will be run on. The platform name can be one of windows, macos or linux. Each of these can have the following fields:

Field Required/Optional Description
localBuildDirectory Required The directory containing the binary to be executed. Your built-out worker must be self-contained in the localBuildDirectory and all files that your worker might depend on while running must be in this folder. Files outside this folder will not be uploaded to the cloud as part of your project assembly.
command Required The base command to be executed to start a worker instance.
arguments Required A list of arguments to provide to the base command. The arguments can contain placeholder strings, like {IMPROBABLE_RECEPTIONIST_HOST}, which are interpolated by SpatialOS when the worker is launched. For a full list of supported placeholder strings, see our documentation on worker launch configurations.

Cloud launch configuration

Use the cloud launch configuration section to specify how to launch a server-worker instance in the cloud. It is the same as the local deployment configuration at the moment, with the following exceptions:

  • We support only the linux platform because worker instances are always run in an Linux environment in the cloud.
  • A zip file containing the directory specified in localBuildDirectory will be uploaded to the cloud.
  • We’ll add additional fields in the future, allowing you to specify where the worker binaries are uploaded.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums