Worker launch configuration

Managed worker launch configuration

The managed field of a worker configuration file specifies how SpatialOS starts managed workers.

You can specify separate launch configurations for Windows, macOS and Linux. The field has the following overall structure:

"managed": {
    "windows": { ... },
    "macos": { ... },
    "linux": { ... }
}

Each of these has the following fields:

• artifact_name is the name of the zip file that contains the worker binary.
• command is the command to run to start the worker. It will be executed relative to the root directory of the unzipped worker. Note that multiple instances of the worker can be executed from the same directory.
• arguments is a list of strings that are passed as command line arguments to the worker binary.

When SpatialOS runs a managed worker, it will unzip it into a temporary directory, set the working directory to this temporary directory, and invoke the specified command with the given arguments.

For example, the following configuration extracts a worker from myworker.zip and runs bin/worker --important_switch=true to launch it:

{
    "artifact_name": "myworker.zip",
    "command": "bin/worker",
    "arguments": ["--important_switch=true"]
}

The arguments can contain the following placeholder strings, which will be interpolated by SpatialOS before the worker is launched:

• ${IMPROBABLE_API_URL}: the services URL that should be used.
• ${IMPROBABLE_ASSEMBLY_NAME}: the assembly name.
• ${IMPROBABLE_PROJECT_NAME}: the project name.
• ${IMPROBABLE_RECEPTIONIST_HOST}: the IP or hostname where a managed worker should connect to.
• ${IMPROBABLE_RECEPTIONIST_PORT}: the port where a managed worker should connect to.
• ${IMPROBABLE_WORKER_ID}: the ID of the worker.
• ${IMPROBABLE_WORKER_NAME}: the type of the worker.
• ${IMPROBABLE_LOG_FILE}: a fresh log file.

External worker launch configuration

The external field of a worker configuration file specifies how SpatialOS starts external workers.

It contains one or more named configurations.

Each configuration contains a run_type field specifying how SpatialOS should run it on Windows, macOS, or Linux. The values can be:

• EXECUTABLE_ZIP, which has the same behaviour as above.

• EXECUTABLE specifies an executable directly. This can save time if your worker is very large, or you haven’t built it out yet.

  In that case, only command and arguments need to be provided. The command will be executed from the directory where the worker json is defined.

The arguments can contain the following placeholder strings, which will be interpolated by SpatialOS before the worker is launched:

• ${IMPROBABLE_PROJECT_ROOT}: the root path of the project.
• ${IMPROBABLE_PROJECT_NAME}: the name of the project as specified in spatialos.json.

Example

This example defines two configurations, config1 and config2.

This worker can be run on Windows or Linux. When it’s built, it creates a zip file called MyWorker@Windows.zip containing MyWorker.exe, and a zip file called MyWorker@Linux.zip containing MyWorker.

It also creates a standalone binary in workers/my_worker/bin/MyWorker.exe that only runs on Windows.

This results in the following two configurations:

{
  "external": {
    "config1": {
      "run_type": "EXECUTABLE_ZIP",
      "windows": {
        "artifact_name": "MyWorker@Windows.zip",
        "command": "MyWorker.exe",
        "arguments": [ "--important_switch_one=true", "--important_switch_two=false" ]
      },
      "linux": {
        "artifact_name": "MyWorker@Linux.zip",
        "command": "./MyWorker",
        "arguments": [ "--important_switch_one=true", "--important_switch_two=false" ]
      }
    },
    "config2": {
      "run_type": "EXECUTABLE",
      "windows": {
        "command": "bin/MyWorker.exe",
        "arguments": [ "--important_switch_one=true", "--important_switch_two=false" ]
      }
    }
  }
}

These can then be invoked via spatial local worker launch MyWorker config1 and spatial local worker launch MyWorker config2 respectively. You can learn more about how to run workers by typing spatial local worker launch --help.

Search results