Command line arguments

In the SpatialOS GDK for Unreal, you can use GDK-specific command line arguments to customize how the GDK runs. For example, you can specify how a worker instance connects to a deployment or choose which network stack a worker instance uses to communicate with the SpatialOS Runtime.

Note: Command line arguments are available by default in non-shipping builds. To enable them in a shipping build, use the bEnableSpatialCmdlineInShipping target rule. See the Unreal documentation on build configurations and targets for more information.

Connection arguments

You can use one of the following methods to connect a worker instance to a SpatialOS deployment:

  • Use the Receptionist to connect a client-worker or server-worker instance to a local or cloud deployment.
  • Use the Locator to connect a client-worker instance to a cloud deployment.

Note: You can only use command-line connection arguments when automatically connecting to SpatialOS. You can't use them if you enable the following setting in the Unreal Editor: Project Settings > SpatialOS GDK for Unreal > Runtime Settings > Cloud Connection > Prevent Client Cloud Deployment Auto Connect. This setting is disabled by default.

Each time you connect one worker instance to a deployment, you can choose only one method for connection. You might need to add both general connection arguments and method-specific arguments.

If you specify both Receptionist arguments and Locator arguments to connect one worker instance to a deployment, errors might occur.

When you use either method to connect a worker instance to a deployment, you can add the following general connection arguments:

Argument Type Description
-workerId string

The worker ID that the worker instance uses to connect to a SpatialOS deployment. 

If you don’t specify a value, the worker instance generates a random worker ID and uses it to connect to a deployment.

-workerType string

The worker type that the worker instance uses to connect to a SpatialOS deployment. In the GDK, you can specify the following worker types:

  • UnrealWorker for server-workers
  • UnrealClient for client-workers
  • For example, to connect a server-worker instance to a local deployment, run:

    MyProject.exe MyMap -server -workerType UnrealWorker

    Here are the default settings when you launch a deployment without specifiying any workerType:

  • When you run the command with the -server argument, you connect a server-worker instance to the deployment.
  • When you run the command without the -server argument, you connect a client-worker instance to the deployment.
  • -useExternalIpForBridge bool

    Set to true to connect a worker instance to a deployment in either of the following ways:

  • To connect to a deployment on a different machine from the worker instance’s machine (not hosted in the cloud).
  • To connect to a cloud deployment using spatial cloud connect external.
  • Default: false

    -linkProtocol string The network stack that the worker instance uses to communicate with the SpatialOS Runtime. The available options are KCP and TCP 

    Note: The GDK does not support the RakNet network stack.

    Default: KCP

    Receptionist arguments

    When you connect a client-worker or server-worker instance to a deployment without the authentication flow, you can add the following Receptionist arguments before you launch the deployment:

    Argument Type Description
    -receptionistHost string The IP of the deployment that the worker instance connects to.

    Default: 127.0.0.1

    -receptionistPort string The port of the deployment that the worker instance connects to.

    Default: 7777

    For example, to connect a server-worker instance to a deployment on a different machine using Receptionist, run:

    MyProject.exe MyMap -server -workerType UnrealWorker -receptionistHost <IP of a different machine> -useExternalIpForBridge true

    Locator arguments

    The following arguments enable the client-worker to connect to a deployment through the player authentication service. When using the SpatialOS Launcher, they are provided automatically.

    Argument Type Description
    -playerIdentityToken string The PlayerIdentityToken (PIT) that the client-worker instance passes to the Locator service to prove its player identity within SpatialOS.
    -loginToken string The LoginToken that the client-worker instance passes to the Locator service to be permitted to join the deployment.

    Other arguments

    In addition to the arguments for worker connections, you can use the following arguments for other settings:

    Argument Type Descrption
    -NoLogToSpatial flag Use this flag to stop a server-worker instance from sending warning or error log messages to SpatialOS.

    Note: You can add this flag to help improve performance if SpatialOS is generating a large number of warning or error log messages.

    -enableWorkerSDKProtocolLogging bool Set this argument to true to enable protocol logging. When protocol logging is enabled, the GDK records any protocol data exchanged between a server-worker instance or client-worker instance and the SpatialOS deployment it’s connected to. This applies to both local and cloud deployments.

    For information on the log file location and name, see WorkerSDK Op and WorkerSDK Protocol log file paths.

    Default value: false

    Example: -enableWorkerSDKProtocolLogging true

    -enableWorkerSDKOpLogging bool Set this argument to true to enable user-level op logging. When user-level op logging is enabled, the GDK records any user-level ops exchanged between a server-worker instance or client-worker instance and the SpatialOS deployment it’s connected to. This applies to both local and cloud deployments.

    For information on the log file location and name, see WorkerSDK Op and WorkerSDK Protocol log file paths.

    Default value: false

    Example: -enableWorkerSDKOpLogging false

    -workerSDKLoggingPrefix string If you are recording protocol logs or user-level op logs, you can use this argument to specify a custom file name prefix for the log file. This is useful if you want to force the GDK to write to a specific log file for a particular deployment run.

    Example: -workerSDKLoggingPrefix run12-

    For information on the log file location and name, see WorkerSDK Op and WorkerSDK Protocol log file paths.

    Tip: To make your file name more readable, we recommend that you separate your prefix from the rest of the file name with a hyphen. For example, if you specify run12- as the prefix, the file name looks like this: run12-UnrealWorker938B9ADE486BF1F9E6EEDD96273A1795-0.log

    To switch log recording on, use the following arguments, described elsewhere on this page:

  • enableWorkerSDKProtocolLogging
  • enableWorkerSDKOpLogging
  • -OverrideSpatialNetworking bool Use this argument to override any other setting that you've configured for the networking mode:
  • When you run the command with the -OverrideSpatialNetworking or the -OverrideSpatialNetworking=true argument, you enable SpatialOS networking.
  • When you run the command with the -OverrideSpatialNetworking=false argument, you disable SpatialOS networking and use native Unreal networking instead.
  • Map travel URL options

    In the GDK, so that a client-worker instance executes a map travel, you add the following URL options to the ClientTravel URL.

    Note: Provide your own options when using ClientTravel if you do not want to use the defaults. You can't use connection arguments when connecting via URL.

    See Connection workflows for more information on ClientTravel and the Unreal documentation for more information on travel.

    Option Type Description
    locator flag

    To connect a client-worker instance to a deployment using the Locator, add this flag to the ClientTravel URL.

    Note: If you add this option, ensure that you also add the playeridentity option and the login option to the URL.
    playeridentity string The PlayerIdentityToken (PIT) that the client-worker instance passes to the Locator service to prove its player identity within SpatialOS.
    login
    string The LoginToken that the client-worker instance passes to the Locator service to be permitted to join the deployment.
    useExternalIpForBridge
    bool

    Set to true to connect a client-worker instance to a deployment in either of the following ways:

  • To connect to a deployment on a different machine from the worker instance's machine (not hosted in the cloud).

  • To connect to a cloud deployment using spatial cloud connect external.

  • Default: false


    2020-09-10 Page updated with editorial review: added automatic connection note to connection arguments and corrected note in Map travel URL options
    2020-09-08 Page updated with editorial review: corrected links to Receptionist and Locator
    2020-09-02 Page updated with editorial review: added note about shipping and non-shipping builds
    2020-08-07 Page updated with editorial review: updated introduction to Map Travel URL options
    2020-07-14 Page updated with editorial review: removed reference to Playtest Hub
    2020-06-05 Page updated with editorial review: logging arguments
    2019-06-13 Page added with editorial review

    Updated about a year ago


    Command line arguments


    Suggested Edits are limited on API Reference Pages

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