Manage your game version
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.
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
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
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]
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 Command | Subcommand | Options and Parameters | |
|---|---|---|---|
| Name | Description | ||
version | upload-metadata | -d, --directory | Directory of the data for upload |
| -f, --file | File for upload | ||
| -t, --type | Metadata type | ||
| -n, --namespace | Namespace | ||
| -a, --apikey | API Key | ||
| -p, --game-project | Game project path | ||
| -F, --force-parse | Force parsing header and footer | ||
| -N,--version-name | Override 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.
| Type | Description |
|---|---|
| performanceTest | Specify the file as a Performance test |
| sniffTest | Specify 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 Command | Subcommand | Options and Parameters | |
|---|---|---|---|
| Name | Description | ||
version | add-changelist-info | -a, --apikey | API Key |
| -n, --namespace | Namespace | ||
| -A, --author | Author of the changelist | ||
| -t, --datetime | Date and time of the changelist in iso8601 format | ||
| -D, --description | Description of the changelist | ||
| -c, --changelist-num | changelist number | ||
| -p, --game-project | Game project path | ||
version | add-changelists-bulk | -a, --apikey | API Key |
| -n, --namespace | Namespace | ||
| -f, --file | Changelist file | ||
| -p, --game-project | Game 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