Skip to main content

Manage your game version

Last updated on October 2, 2023

Overview

You can associate multiple games to your namespace. Each game can have many versions, each of which has a unique game version ID. In this guide, you will learn how to use the BlackBox CLI to list, set up, and control game versions.

info

It's important to know that the Game Version ID is a unique ID generated for each game in a namespace and isn't related to versions that are shown on the Versions page. This is a legacy naming convention that we're improving.

List the game versions

Before adding a new game version, choose a command from the list below to list the game versions that are available.

Without inline configuration

BlackBoxCLI.exe version list

With inline configuration

BlackBoxCLI.exe version list --namespace <your namespace> --apikey <yourapikey>

When you execute the command, the system lists available game versions, as shown in the example below. The Game Version ID is shown with their names are listed.

ID                                             | Name
-----------------------------------------------------------
2646fc64-b247-4150-8fcd-46ab883cb110 | 1.2.0
f5d6c34e-8391-4fb1-8863-f67d28247371 | 1.1.0
-----------------------------------------------------------

Add a new game version

To add a new game version, run one of the following commands based on the configuration.

Without inline configuration

BlackBoxCLI.exe version add --name <new version name>

With inline configuration

BlackBoxCLI.exe version add --name <new version name> --namespace <your namespace>  --apikey asdf1234 --game-project <your project path>

In the following example, we add version 1.1.9.

BlackBoxCLI.exe version add --name "1.1.9" --namespace MyAwesomeNamespace  --apikey asdf1234 --game-project D:\MyProject\MyAwesomeGame
info

If you don't want the BlackBox CLI to set the game version, use --no-set option.

If you created versions, you can decide which to use. In this example, we use version 1.1.9.

BlackBoxCLI version set --name "1.1.9" --namespace MyAwesomeNamespace --apikey asdf1234 --game-project D:\MyProject\MyAwesomeGame
info

The version add and version set commands have an --enable-set-datarouter flag that you can use to modify Unreal's Crash Report Client target URL.

Add custom metadata [DEPRECATED]

caution

We deprecated this subcommand; ADT no longer supports adding metadata to a version.

Follow this command to add custom data to any file you want to tie to your version.

  BlackBoxCLI.exe version upload-metadata <option and parameter>

Without inline configuration

  BlackBoxCLI.exe version upload-metadata --type sniffTest --directory D:\path\to\sniffTestdir

With inline configuration

  BlackBoxCLI.exe version upload-metadata --type sniffTest --directory D:\path\to\sniffTestdir --game-project D:\path\to\myawesomegame --apikey asdf1234 --namespace myawesomegame

Here are the references for the subcommand that helps you add arbitrary data.

Main CommandSubcommandOptions and Parameters
NameDescription
versionupload-metadata -d, --directoryDirectory of the data for upload
-f, --fileFile for upload
-t, --typeMetadata type
-n, --namespaceNamespace
-a, --apikeyAPI Key
-p, --game-projectGame project path
-F, --force-parseForce parsing header and footer
-N,--version-nameOverride version using name for the version (optional) |

For the metadata value, you can input any file type to tie it to your version. We also have a predefined file type, as shown.

TypeDescription
performanceTestSpecify the file as a Performance test
sniffTestSpecify the file as a sniff test

Add Perforce changelist information

When working on Unreal Engine games with Perforce (P4), sometimes you may need to add information such as changelist name, author, description, etc. into the build pipeline. The following example shows a subcommand to do this.

  BlackBoxCLI.exe version add-changelist-info --author johndoe --changelist-num 1234 --datetime "2020-01-01T09:37:56Z" --description "add more awesomeness"
BlackBoxCLI.exe version add-changelist-info --author johndoe --changelist-num 1234 --datetime "2020-01-01T09:37:56Z" --description "add more awesomeness" --namespace myawesomegame --apikey asdf1234 --game-project D:\path\to\myawesomegame

Here are the references for add-changelist-info and add-changelist-bulk.

Main CommandSubcommandOptions and Parameters
NameDescription
versionadd-changelist-info-a, --apikeyAPI Key
-n, --namespaceNamespace
-A, --authorAuthor of the changelist
-t, --datetimeDate and time of the changelist in iso8601 format
-D, --descriptionDescription of the changelist
-c, --changelist-numchangelist number
-p, --game-projectGame project path
versionadd-changelists-bulk-a, --apikeyAPI Key
-n, --namespaceNamespace
-f, --fileChangelist file
-p, --game-projectGame project path

If you want to upload available changelists, use the add-changelists-bulk command to tie them to your game version. The JSON format is shown here.

[
{
"id" : <change list number>,
"description" : "commit description",
"Author":"author name",
"Time":"datetime in ISO 8601 format",
},
...
]

Once you fill out the values, it will look like this.

[
{
"id" : 139737,
"description" : "adding weapon to the main character",
"author":"hdarwintha",
"time":"2020-09-15T03:08:00+00:00",
},
{
"id" : 139720,
"description" : "remove unused shader on main menu UI",
"author":"tomnook",
"time":"2020-09-14T03:08:00+00:00",
},
]

Here's the add-changelist-bulk example command without inline configuration:

BlackBoxCLI.exe version add-changelist-bulk --file D:\path\to\changelist_list.json