Get SpatialOS


You are viewing the docs for 11.0, an old version of SpatialOS. 12.0 is the newest →

Worker flags

To change values that workers use, either at simulation startup time or dynamically, use worker flags. For example, you could vary the walking speed of your entities and see how this affects the simulation.

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

Defining 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.

Note: Flag names cannot have full stops in.

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.

Reading 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.

For details, see the (C++, C#, Java, Javascript) API documentation.

Changing flag values at runtime

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

spatial commands

You can get a flag’s value, set a flag’s value, and list flags using the spatial CLI.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums