Last Updated: 11/24/2022, 8:24:26 AM

# App Distribution

# Overview

The App Distribution service combines BuildInfo, BuildUtil, and Differ tools to enable you to distribute your game. Each of these three services is described below.

# BuildInfo

BuildInfo manages your game’s build version. This system stores every detail of a game’s build version in a build manifest. BuildInfo is comprised of two components:

  • BuildInfo Service This service handles all functions related to the build process. All communication between the BuildInfo system and third-party services is managed by this service.
  • BuildInfo CLI This component is a command line tool which consumes the BuildInfo service. This program is used to automate game deployment and should be put in CI/CD tools.

# BuildUtil

BuildUtil is used to upload your game binary to the cloud for distribution. While the binary is uploading, BuildUtil provides the meta information recorded by BuildInfo.

# Differ

Differ compares different uploaded versions of a game. This allows your players to update their game to a new version without completely re-downloading the game files.

# Tutorial

In this tutorial, you will learn how to perform the required setup to upload your game using BuildUtil. This tutorial assumes you have a basic familiarity with Namespaces (opens new window).

# Creating BuildUtil Client Credentials

Before you upload your game, you must first create client credentials for BuildUtil. This will ensure that BuilUtil will be able to upload your game. To do so, follow these steps:

  1. In the Admin Portal, click Platform Configurations and select OAuth Clients.

    game-uploading-guide

  2. On the top-right of the OAuth Clients page, select Create New. The Create New OAuth2 Client form will appear.

    game-uploading-guide

  3. Fill in the Create New OAuth2 Client form.

    game-uploading-guide

    • Client ID is automatically filled in.
    • Select Confidential for the Client Type. A game client is a private client so the client type must be Confidential.
    • Input a unique Client Secret or click Generate Client Secret and the Admin Portal will generate a secret for you.
    • Input the Client Name. The client name can include the separators ' , . - , as well as spaces.
    • Select your publisher namespace from the Namespace dropdown list.
    • Select the Platform this relates client relates to (optional).
    • Select the Target Audience. For BuildUtil, this often includes the IAM and BuildInfo clients. If you leave this field empty, BuildUtil will be available to all clients.
    • Input the Base URI. This is an optional field and is used to make sure that the token of your application is intended to be used by your client.
    • Input the Redirect URI. IAM services will call this redirect URI if the user is already authenticated.

    Once completed, click Create.

  4. The Client Details page will appear with your new client credentials.

    game-uploading-guide

  5. In the Client Details window, open the Permissions tab. Click Add to add permissions to the client.

    game-uploading-guide

  6. The Add Client Permissions form will appear.

    game-uploading-guide

    Input the permission’s Resource in the text field and select the Action from the available check boxes. Some Resource examples you could use include:

    • ADMIN:NAMESPACE:{namespace}:BUILDINFO

    This permission allows an admin to access BuildInfo in whatever client they’re logged into.

    • ROLE

    This permission allows admins to access data related to Roles.

    TIP

    See AccelByte's Permissions (opens new window) documentation for a full list of Resource options and how to use them.

    Once completed, click Confirm.

  7. Your client permission will be added to the Client Permissions panel.

    game-uploading-guide

# Creating Game Client Credentials

You’ll need to create client credentials for your game in order to connect it with our services. The procedure to create Game Client Credentials is similar to BuildUtil Client Credentials. To do so, follow these steps:

  1. On the OAuth Clients page, click Create New in the top-right corner. The Create New OAuth2 Client form will appear.

    game-uploading-guide

  2. Fill in the Create New OAuth2 Client form.

    game-uploading-guide

    • Client ID is automatically filled in.
    • Select Confidential for the Client Type. A game client is a private client so the client type must be Confidential.
    • Input a unique Client Secret or click Generate Client Secret and the Admin Portal will generate a secret for you.
    • Input the Client Name. The client name can include the separators ' , . - , as well as spaces.
    • Select your publisher namespace from the Namespace dropdown list.
    • Select the Platform this relates client relates to (optional).
    • Select the Target Audience. For BuildUtil, this often includes the IAM and BuildInfo clients. If you leave this field empty, BuildUtil will be available to all clients.
    • Input the Base URI. This is an optional field and is used to make sure that the token of your application is intended to be used by your client.
    • Input the Redirect URI. IAM services will call this redirect URI if the user is already authenticated.

    Once completed, click Create.

  3. The Client Details page will appear with your new client credentials.

    game-uploading-guide

  4. In the Client Details window, open the Permissions tab. Click Add to add permissions to the Game Client.

    game-uploading-guide

  5. The Add Client Permissions form will appear.

    game-uploading-guide

    Input the permission’s Resource in the text field and select the Action from the available check boxes. Some Resource examples you could use include:

    • NAMESPACE:*:MATCHMAKING:CHANNEL

    This permission allows admins to access data related to Matchmaking in-game.

    TIP

    See AccelByte's Permissions (opens new window) documentation for a full list of Resource options and how to use them.

    Once completed, click Confirm.

  6. Your client permission will be added to the Client Permissions panel.

    game-uploading-guide

# Configuring BuildUtil

If this is your first time uploading a game, you’ll need to configure BuildUtil using the credentials you just created. You can skip this step if you’ve configured BuildUtil before.

  1. Download the latest BuildUtil.exe (opens new window) and save the file in your directory.

  2. Open your terminal or command line to run the latest BuildUtil using the following command:

    NOTE

    If you use Linux and you can’t locate the BuildUtil executable file you just downloaded, use chmod +x ./justice-build-util-3.13.0-linux_amd64 to change the access level for BuildUtil so that it can be executed in Linux.

  3. Once completed, a new line in your terminal or command line will appear: Insert IAM URL. Input your IAM URL (e.g., https://demo.accelbyte.io/iam/) and click Enter.

  4. A new line will appear: Insert Uploader’s Client ID. Input the BuildUtil Client ID you previously created and click Enter.

  5. A new line will appear: Insert Uploader’s Client Secret. Input the BuildUtil Client Secret you previously created and click Enter.

  6. A new line will appear: Insert Log level (OPTIONAL). The log level determines how detailed the log files will be. You can leave this line empty if you choose, so that no extra information is added to the log. Once completed, click Enter.

  7. When you’re finished, your terminal should look like this:

    Linux:

    game-uploading-guide

    Windows:

    game-uploading-guide

    You can also use the following command to configure BuildUtil if you’re already familiar with the above procedure:

# Uploading a Game using BuildUtil

Once you have created the client credentials both for BuildUtil and the Game Client, you can begin to upload the game into your publishing platform. In doing so, you need to make sure that you have the game binary of the game you want to publish already prepared. You can upload the game using BuildUtil with the upload command. If this is the first time you’re uploading a game, you will need to configure BuildUtil by following steps in the previous section.

  1. Set up the Game SDK configuration. Below is an example of the Unity SDK configuration.

  2. Run the upload command. Refer to the table below for information about each command.

Command Description
--url (-u) Base URL to the service. For example: ./justice-build-util-v3.3.1-linux_amd64
--namespace (-n) The publisher namespace. This is the default namespace in the Admin Portal.
--appID (-a) The app id of the game to upload. The app id should be unique for each game.
--dir (-d) The absolute path of the directory containing the file to be uploaded.
--entrypoint (-e) Entrypoint/executable game relative path in the build folder. Please note that this is relative to the game directory (--dir).

For example, if the entrypoint is /home/dev/GameA/executable/Game.exe and the specified directory is /home/dev/GameA, then the entrypoint value should be executable/Game.exe.

--version (-v) A version of the game to upload. For example: 1.0.0, 1.0-alpha, etc.
--platformid (-p) The target platform identifier where the uploaded game will run. Pick one of these values: win32, win64, windows, darwin, linux-ia32, linux-amd64, linux-generic. For example, you’re targeting Windows 32-bit, choose win32.
--sdkconfig (-f) Absolute path to the SDK config file.
--ignore (-g) Optional. Absolute path to the ignore file. If you’re going to ignore certain files, create an ignore file with the same pattern with git ignore file and save it somewhere. You can also place the file named .ignoreconfig inside the directory of the game to be uploaded and skip this flag. In this case, BuildUtil will automatically read your file.
--type (-t) The type of game to be uploaded. The two options are GAME or DLC.

Here is the syntax of the upload command:

For example:

Here is what the upload looks like in the terminal:

Linux:

game-uploading-guide

Windows:

game-uploading-guide

# Setting Up the Current Version Through the Admin Portal

After you have successfully uploaded your game using BuildUtil, you can check your uploaded game in the App Distributions menu in Admin Portal. Follow these steps to view your uploaded game.

  1. In the Admin Portal, click the Platform Configurations dropdown menu and select App Distributions.

    game-uploading-guide

  2. Find the game you uploaded from the list. Click View to view the uploaded game details.

    game-uploading-guide

  3. In the Builds panel, choose the build you want to set as the current build by clicking the ellipsis button in the Actions column, then choose Set as current.

    game-uploading-guide

  4. The Set as current modal will appear. Click the Set button to confirm.

    game-uploading-guide

# Setting Up the Current Version from BuildUtil

You can also set up a game version as current using BuildUtil through the command prompt or terminal. The result is identical to setting a game version as current from the Admin Portal.

In order to set up the current version using BuildUtil, run the setcurrent command with the following parameters.

Command Description
--url (-u) Base URL to the service.
--appID (-a) AppId for the game which will be updated.
--namespace (-n) The publisher namespace, which is the default namespace in the Admin Portal.
--platformid (-p) The target platform identifier where the uploaded game will run. Pick one of these values: win32, win64, windows, darwin, linux-ia32, linux-amd64, linux-generic. For example, if you’re targeting Windows 32-bit, choose win32.
--version (-v) The version of the game to be set as the current version. For example: 1.0.0, 1.0-alpha, etc.

Here is the example of the updated command:

./justice-build-util-3.13.0-linux_amd64 setcurrent --url https://demo.accelbyte.io -a lightfantasticwindows -n accelbyte -v 0.0.19 -p win64

Here is an example of how this command will look in the terminal:

Linux:

game-uploading-guide

Windows:

game-uploading-guide

# Add a Launch Argument through the Admin Portal

You can add or update a launch argument for your builds through the Admin Portal by following the steps below.

  1. In the Admin Portal, click the Platform Configurations dropdown menu and open the App Distributions menu.

    game-uploading-guide

  2. Find the game you want to edit and click the View button.

    game-uploading-guide

  3. Here you can see the list of your builds. In the Actions column, click the ellipsis button and choose Edit Launch Argument.

    game-uploading-guide

  4. The Edit Launch Argument form will appear. Here you can input the desired arguments.

    game-uploading-guide

    • If there is a build that cannot run using VGA because it will crash, you can input --novga as the launch argument to run it without using the GPU, as long as that build supports the specific argument.

    WARNING

    Updating the launch arguments will rewrite the previous launch arguments.

  5. Here’s what the launch arguments look like after they’re updated:

    game-uploading-guide

# Delete a Game Build using the Admin Portal

You can delete any unused game builds in the Admin Portal to free up your storage. By default there is a grace period of 30 days before the build is actually deleted, allowing you to cancel the deletion if necessary. If you want to change the duration of this grace period, you can do so by configuring the BUILDINFO_CLEANER_TIME variable in the config map of the helm deployment to the desired value, in minutes.

Once a game build has been requested to be deleted, you won’t be able to edit its launch argument or set it as current via the Admin Portal or BuildUtil. To delete a game build, follow the steps below.

NOTE

The currently used game build cannot be deleted. To delete this build, first set a different build as the current one.

  1. In the Admin Portal, click the Platform Configurations dropdown menu and open the App Distributions menu.

    game-uploading-guide

  2. Choose the App ID for the game whose build you want to delete. Then, click the View button next to the App ID.

    game-uploading-guide

  3. Here you can see the list of game builds. Choose the game build you want to delete, click the ellipsis button under the Action column, and click Delete Build.

    game-uploading-guide

  4. The Delete Build confirmation window appears. Type DELETE in the text box, then click Delete.

    game-uploading-guide

  5. The selected game build will be moved to the Deletion Request section, and its status will change to Requested.

    game-uploading-guide

  6. Once the build has been deleted, its status will change to Deleted.

    game-uploading-guide

# Cancel a Game Build Deletion Request using the Admin Portal

You can also cancel the game build delete request as long as the build’s status is still Requested. To cancel a game build deletion request, follow the steps below.

  1. In the Admin Portal, click the Platform Configurations dropdown menu and open the App Distributions menu.

    game-uploading-guide

  2. Choose the App ID for the game whose build you want to delete. Then, click the View button next to the App ID.

    game-uploading-guide

  3. You can see the list of game builds that are waiting to be deleted in the Deletion Request section.

    game-uploading-guide

  4. You can filter the list of builds by selecting either Filter by Platform, Filter by Date, or Filter by Build ID.

    game-uploading-guide

  5. You can also sort the builds based on their deletion status.

    game-uploading-guide

  6. Choose the game build whose deletion you want to cancel, then click Cancel under the Actions column next to the build.

    game-uploading-guide

  7. The Cancel Deletion confirmation window appears. Click the Cancel Deletion button.

    game-uploading-guide

  8. When you’re done, the game build will be removed from the Deletion Request section. It will be moved back to the list of active game builds.

# Downloading a Game Using BuildUtil

You can download the game using BuildUtil for debugging purposes.

NOTE

Actual player downloads should only happen in Launcher. This procedure is for debugging purposes only.

To download a game, run the download command with the following parameters:

Command Description
--url (-u) Base URL to the service.
--namespace (-n) The publisher namespace. This is the default namespace in the Admin Portal.
--dir (-d) The directory where the game will be downloaded.
--sourceID (-b) The Build ID of the game.
--buildInfoVersion (-r) The BuildInfo version to be used. If you’re uploading the game and specifying the -r flag as 1, then fill this parameter with value 1. If no -r value is supplied during the upload, then fill this parameter with value 2. Any values other than 1 or 2 are invalid.

Here is an example of the updated command:

Here is how the command will look in the terminal:

Linux:

game-uploading-guide

Windows:

game-uploading-guide

Once you are finished, you can find the downloaded file in the directory that you previously specified.