Sites

Menu
These are the docs for 14.3, an old version of SpatialOS. 14.5 is the newest →

Launcher client configuration file

Make sure you don’t confuse the Launcher client configuration file with the similarly-named launch configuration file in the structured and flexible project layouts.

You should use the Launcher client configuration file to configure client-worker types for use with the Launcher. Use this file to explicitly define the correct executable and required arguments to make sure your client-worker instances launch correctly and can participate in playtests.

Set up a Launcher client configuration file

If you’re using the flexible project layout (FPL), you can skip these steps and use an existing file instead as the basis for your Launcher client configuration file. In this case, go straight to the steps on migrating from the flexible project layout.

To set up the Launcher client configuration file with your client-worker type:

  1. Open a text editor and create a file named launcher_client_config.json. You’ll use this JSON file to tell the Launcher exactly how to start your game.
  2. Configure two keys: command and arguments.
  3. Command

    The command value defines which executable within your client zip file should be launched.

    Your client zip file is part of your assembly - specifically, the zip file that contains your built-out client-worker.

    The Launcher automatically changes the working directory to the root of your client zip file before running your client-worker instance, so this command argument must be a relative path.

    For example, if your client executable is named GameClient.exe and is in a folder named bin inside your client zip file, the command value would be bin/GameClient.exe.

    Arguments

    The arguments value defines the arguments to pass to the executable.

    The example below passes all the regular SpatialOS parameters, but you can add or remove more as required, and they are passed to your executable as normal. For example, if you wanted to send custom parameters +enableBaz +foobarLimit "5000" to your client-worker instance when it launches, you could add "+enableBaz", "+foobarLimit", "5000" to the arguments array.

    The ${...} placeholder arguments are special: they allow you to inject variables that are automatically populated with appropriate values, such as the user’s login token or the project name. The table below shows the variables that we currently support.

    Variable Description
    ${IMPROBABLE_DEPLOYMENT_NAME} The name of the deployment to use.
    ${IMPROBABLE_PROJECT_NAME} The name of the project containing the deployment to use.
    ${IMPROBABLE_LOGIN_TOKEN} The login token to use to log in to the deployment.
    ${IMPROBABLE_PLAYER_IDENTITY_TOKEN} The player identity token to use to log in to the deployment.
    ${IMPROBABLE_LOCATOR_HOSTNAME} The hostname of the Locator to use to log in to the deployment.
    ${IMPROBABLE_API_URL} The URL of the Improbable API, if the client-worker instance requires it.

    Note that unrecognized ${...} placeholder values are passed to your client-worker instance exactly as written, so make sure that any placeholder values you use are spelled exactly as shown above.

    Example Launcher client configuration file

    Below is a Launcher client configuration file that would launch a GDK for Unity client-worker instance on MacOS:

    {
    "command": "./UnityClient@Mac.app/Contents/MacOS/UnityClient@Mac",
    "arguments": [
        "+appName", "${IMPROBABLE_PROJECT_NAME}",
        "+projectName", "${IMPROBABLE_PROJECT_NAME}",
        "+deploymentName", "${IMPROBABLE_DEPLOYMENT_NAME}",
        "+loginToken", "${IMPROBABLE_LOGIN_TOKEN}",
        "+playerIdentityToken", "${IMPROBABLE_PLAYER_IDENTITY_TOKEN}",
        "+locatorHost", "${IMPROBABLE_LOCATOR_HOSTNAME}",
        "+infraServicesUrl", "${IMPROBABLE_API_URL}",
        ] 
    }
    

  4. Add your launcher_client_config.json configuration file to the root level of your client zip file using your preferred archive tool.
  5. The client zip file must be named one of <Unity|Unreal|Launcher>Client@<Windows|Mac>.zip. For example:

    • the client zip file for the above example would be named UnityClient@Mac.zip.
    • an Unreal client-worker type on Windows would have a client zip file named UnrealClient@Windows.zip.
    • a client-worker instance running on Windows on an engine other than Unity or Unreal would be named LauncherClient@Windows.zip.

    Regardless of engine or platform, the launcher_client_config.json file must be located in the root of this client zip file.

    Migrate from the flexible project layout

    If you’re using the flexible project layout (FPL), you can use the values in your auto-generated improbable_client_launch_config.json file to populate your launcher_client_config.json file.

    For example, the following improbable_client_launch_config.json contains this FPL configuration for running an Unreal client-worker instance on Windows:

    {
      "launcherCommand": "bin/Windows/GameClient.exe",
      "launcherArguments": [
      	"+loginToken",
      	"${IMPROBABLE_LOGIN_TOKEN}",
      	"+playerIdentityToken",
      	"${IMPROBABLE_PLAYER_IDENTITY_TOKEN}"
      ]
    }
    

    This translates to the following launcher_client_config.json file:

    {
      "command": "bin/windows/GameClient.exe",
      "arguments": [
    	"+loginToken",
    	"${IMPROBABLE_LOGIN_TOKEN}",
    	"+playerIdentityToken",
    	"${IMPROBABLE_PLAYER_IDENTITY_TOKEN}"
      ] 
    }
    

    In this example, your client zip file would be named UnrealClient@Windows.zip, and the launcher_client_config.json file containing the above JSON would be in the root of the client zip file.

    Example configurations

    GDK for Unity

    The configurations below are suitable starting points for client-worker types created with the GDK for Unity.

    MacOS

    Your client zip file should be named UnityClient@Mac.zip and your launcher_client_config.json file should contain the following:

    {
      "command": "./UnityClient@Mac.app/Contents/MacOS/UnityClient@Mac",
      "arguments": [
        "+appName", "${IMPROBABLE_PROJECT_NAME}",
        "+projectName", "${IMPROBABLE_PROJECT_NAME}",
        "+deploymentName", "${IMPROBABLE_DEPLOYMENT_NAME}",
        "+loginToken", "${IMPROBABLE_LOGIN_TOKEN}",
        "+playerIdentityToken", "${IMPROBABLE_PLAYER_IDENTITY_TOKEN}",
        "+locatorHost", "${IMPROBABLE_LOCATOR_HOSTNAME}",
        "+infraServicesUrl", "${IMPROBABLE_API_URL}",
      ]
    }
    

    Windows

    Your client zip file should be named UnityClient@Windows.zip and your launcher_client_config.json file should contain the following:

    {
      "command": "./UnityClient@Windows.exe",
      "arguments": [
        "+appName", "${IMPROBABLE_PROJECT_NAME}",
        "+projectName", "${IMPROBABLE_PROJECT_NAME}",
        "+deploymentName", "${IMPROBABLE_DEPLOYMENT_NAME}",
        "+loginToken", "${IMPROBABLE_LOGIN_TOKEN}",
        "+playerIdentityToken", "${IMPROBABLE_PLAYER_IDENTITY_TOKEN}",
        "+locatorHost", "${IMPROBABLE_LOCATOR_HOSTNAME}",
        "+infraServicesUrl", "${IMPROBABLE_API_URL}",
      ]
    }
    

    GDK for Unreal

    The example configuration below is a suitable starting point for client-worker types created with the GDK for Unreal.

    Windows

    This example assumes that your game client executable is named GameClient.exe and is in the root of your client zip file. If you copy this example, make sure you change the command to the correct path for your game client executable.

    For example, if your game client executable is located at Binaries\Win64\MyShooterGame.exe, you would set the command value to ./Binaries/Win64/MyShooterGame.exe.

    Your client zip file should be named UnrealClient@Windows.zip and your launcher_client_config.json file should contain the following:

    {
      "command": "./GameClient.exe",
      "arguments": [
        "+appName", "${IMPROBABLE_PROJECT_NAME}",
        "+projectName", "${IMPROBABLE_PROJECT_NAME}",
        "+deploymentName", "${IMPROBABLE_DEPLOYMENT_NAME}",
        "+loginToken", "${IMPROBABLE_LOGIN_TOKEN}",
        "+playerIdentityToken", "${IMPROBABLE_PLAYER_IDENTITY_TOKEN}",
        "+locatorHost", "${IMPROBABLE_LOCATOR_HOSTNAME}",
        "+infraServicesUrl", "${IMPROBABLE_API_URL}",
        "+useExternalIpForBridge", "true"
      ]
    }
    


    ————
    2019-01-09 Page added with editorial review.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums