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
andarguments
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 inspatialos.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
.