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 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. Create the file

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 the keys

Within the file, configure two keys: command and arguments.

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": "./[email protected]/Contents/MacOS/[email protected]",
"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}"
    ] 
}

3. Add to your client zip

Add your launcher_client_config.json configuration file to the root level of your client zip file using your preferred archive tool.

The client zip file must be named one of <Unity|Unreal|Launcher>[email protected]<Windows|Mac>.zip. For example:

  • the client zip file for the above example would be named [email protected].
  • an Unreal client-worker type on Windows would have a client zip file named [email protected].
  • a client-worker instance running on Windows on an engine other than Unity or Unreal would be named [email protected].

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 [email protected], 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 [email protected] and your launcher_client_config.json file should contain the following:

{
  "command": "./[email protected]/Contents/MacOS/[email protected]",
  "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 [email protected] and your launcher_client_config.json file should contain the following:

{
  "command": "./[email protected]",
  "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 [email protected] 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.

Updated about a year ago


Launcher client configuration file


Suggested Edits are limited on API Reference Pages

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