Worker flags

During a deployment, a worker instance has access to the worker flags that are associated with its worker type. You can change worker flag values while the deployment is running, which means you can test your game with different parameters and change them during a live playtest. For example, you could vary the walking speed of all player entities.

Define worker flags at launch

You define worker flags and set their initial values in the launch configuration file for a deployment. Follow these guidelines when you define worker flags:

  • Worker flag names should use snake_case.
  • Worker flag names can’t contain periods (full stops).
  • Worker flag values must be strings.

How you define worker flags depends on how you’ve set up the launch configuration file for the deployment. If you're using an autogenerated launch configuration file, you define worker flags in Unreal Editor. If you've created your own launch configuration file manually, you define worker flags in that file.

Autogenerated launch configuration file

If you're using the launch configuration file that is automatically generated by default for a local or a cloud deployment, you define worker flags in the Unreal Editor.

  1. In the Editor Settings panel, expand the Launch section.
  2. Expand the Server Workers heading and then the Flags heading.
  3. Select the ➕ icon and enter a name and a value for your worker flag.

Image: Define a worker flag in Unreal Editor

To delete all worker flags, select the trash icon. To delete one worker flag, select the drop-down to the right of the flag, and then select Delete.

Manually created launch configuration file

If you’ve created your own launch configuration file, for a local or cloud deployment, you define worker flags directly in the file (see this example of how to format worker flags).

Read worker flag values

Use the Get Worker Flag Blueprint function to read a worker flag’s value.

This function takes the name of a worker flag as an input. If a worker flag with that name exists, the function returns:

  • a Return Value of true
  • an Out Flag Value that matches the worker flag’s value

Example

Image: The Get Worker Flag Blueprint function

Change worker flag values while the deployment is running

You can add and remove worker flags, and change their values, while the deployment is running. How you do this depends on whether you’re running a local deployment or a cloud deployment.

Local deployments

Use the SpatialOS CLI commands spatial local worker-flag get, list, and set to add, remove, or change worker flags. You need to add --local_service_grpc_port 9876 to all commands. For example:

spatial local worker-flag get MyWorkerType mycompany_theproject_work_speed --local_service_grpc_port 9876

Cloud deployments

In the SpatialOS Console, on the deployment page, open the Worker flags tab.

Watch for worker flag changes

To watch for worker flag changes, you need to create a function and bind it so that it gets invoked every time a worker flag value changes.

  1. Use the dynamic delegate FOnWorkerFlagsUpdatedBP to bind the function. FOnWorkerFlagsUpdatedBP has the following declaration:
DECLARE_DYNAMIC_DELEGATE_TwoParams(FOnWorkerFlagsUpdatedBP, const FString&, FlagName, const FString&, FlagValue);

Example: binding a function named SetFlagUpdated

FOnWorkerFlagsUpdatedBP WorkerFlagDelegate;
WorkerFlagDelegate.BindDynamic(SpyObj, &UWorkerFlagsTestSpyObject::SetFlagUpdated);
  1. Pass WorkerFlagDelegate as a parameter to BindToOnWorkerFlagsUpdated.

Example

SpatialWorkerFlags->BindToOnWorkerFlagsUpdated(WorkerFlagDelegate);

This invokes the bound function every time a worker flag value changes.

To unbind the function, use UnbindFromOnWorkerFlagsUpdated.

Example

SpatialWorkerFlags->UnbindFromOnWorkerFlagsUpdated(WorkerFlagDelegate);

2020-08-03 Page updated to remove known issue that you can’t change worker flags while deployment is running - with editorial review
2020-06-11 Page created with editorial review

Updated about a year 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.