Worker flags

To change the values that workers use, either at launch or during a deployment, use worker flags. For example, you could vary the walking speed of your entities and see how this affects the gameplay.

Workers of a particular type in a deployment will have access to the same set of flags containing the same values.

Define flags

Define worker flags and their values in the launch configuration file. Each flag is defined by a name and an initial value. All flag values are strings.

Flag names can't contain full stops.

Naming conventions

  • Use snake_case for your flag names.

  • Always prepend your organization and simulation name to avoid name clashing (e.g. prefer mycompany_theproject_work_speed to work_speed).


   "workers": [
         "worker_type": "MyWorkerType",
         "flags": [
                 "name": "mycompany_theproject_work_speed",
                 "value": "15"

In the example above, workers of type MyWorkerType can access the value of the flag called
mycompany_theproject_work_speed. The value of the flag when the deployment starts will be 15, although its value can change at runtime.

Read flag values

A worker can query the value of a flag at any time. This is a local, synchronous operation, which always returns the most up-to-date value for the flag.

The initial values for the flags will be available on the worker as soon as the connection has been established. If SpatialOS fails to provide the flag values, the worker will log an error and disconnect.

For details, see the API documentation: C++, C#, Java.

Change flag values at runtime

You can add and remove flags, and change their values, in the Worker flags tab of your deployment page in the SpatialOS console.

Watch for flag changes

You can watch for flag changes using the callback OnFlagUpdate. See the Dispatcher Callbacks table for C++, C#, Java.

Updated about a month ago

Worker flags

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.

Welcome! Thanks for visiting our developer documentation in its new home.

If you are used to visiting, you may be wondering how and why you teleported here instead. We hope our FAQ explains more. It contains a feedback link if you want to tell us about your visit today and how we could improve it.