Patcher

Overview

The Patcher service combines BuildInfo, BuildUtil, and Differ tools that enable you to upload and publish 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 manifst. BuildInfo is comprised of two components:

  1. BuildInfo Service This service handles all functions related to the build process. Every communication between the BuildInfo system and third-party services is managed by this service.
  2. 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 to be recorded by BuildInfo.

Differ

Differ is a service that can compare different uploaded versions of a game. This allows your players to update their game to a new version without completely re-downloading the game file.

Tutorials

In this tutorial, you will learn how to perform the required setup before you can upload your game using BuildUtil. Before you start, make sure you have read about Namespace.

Creating BuildUtil Client Credentials

In order to 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:

How to Create BuildUtil Client Credentials

  1. In the Admin Portal, click Platform Configurations and select OAuth Clients. The list of existing OAuth Clients appears.

patcher

  1. Click Create New in the top-right corner. The Create New OAuth2 Client form appears.

patcher

  1. Fill in the Create New OAuth2 Client form:

patcher

  • Client ID is automatically filled in.
  • Input the Client Name. The client name can include the separators ' , . - , as well as spaces.
  • Select Confidential for the Client Type. BuildUtil is a private client so the client type must be Confidential.
  • Input a unique Client Secret. Or, you can click Generate Client Secret and the Admin Portal will generate a secret for you.
  • Select the publisher namespace from the Namespace dropdown list.
  • 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. if you left it empty then the configuration will be available for all clients.

When you’re finished, click Create.

  1. After creating the new client credentials, you’ll be directed to the Client Details.

patcher

  1. In the Client Details window, open the Permissions tab to add permissions to the newly created client.

patcher

  1. Click Add in the top-right corner. The Add Client Permissions form appears.

patcher

  1. Input the permissions Resource in the text field and select the Action. Below are some examples of how to fill in the Resource parameter:
  • 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.

patcher

  1. When you’re finished., click Confirm. The client permissions will be updated in the Client Permissions panel.

patcher

Creating Game Client Credentials

You’ll need to create client credentials for your game in order to connect it with our services. To do so, follow these steps:

How to Create Game Client Credentials

  1. In the Admin Portal, click Platform Configurations and select OAuth Clients. The list of existing OAuth Clients appears.

patcher

  1. Click Create New in the top-right corner. The Create New OAuth2 Client form appears.

patcher

  1. Fill in the Create New OAuth2 Client form:
  • Client ID is automatically filled in.
  • Input the name of your game in the Client Name field.
  • 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, you can click Generate Client Secret and the Admin Portal will generate a secret for you.
  • Select the publisher namespace from the Namespace dropdown list.
  • Select the Target Audience. For your game you can fill in clients that will connect to your game, such as Matchmaking. If you leave this field empty, the game client will be available to all other clients.

When you’re finished, click Create.

patcher

  1. After creating the new client credentials, you’ll be directed to the Client Details.

patcher

  1. In the Client Details window, open the Permissions tab to add permissions to the newly created client.

patcher

  1. Click Add in the top-right corner. The Add Client Permissions form appears.

patcher

  1. Input the permissions Resource in the text field and select the Action. Below is an example of how to fill in the Resource parameter:
  • NAMESPACE::MATCHMAKING:CHANNEL

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

patcher

  1. When you’re finished, click Confirm. The client permissions will be updated in the Client Permissions panel.

patcher

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 and save the file in your directory.
  2. Then, open your terminal or command line to run the latest Build Util using the following ./justice-build-util-v3.3.1-linux_amd64 configure -i.

Note:

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

  1. After that, a new line in your terminal or command line will appear: Insert IAM URL. Input your IAM URL and click Enter. E.g.: https://justice.dev.accelbyte.io/iam/

  2. Then, a new line will appear: Insert Uploader’s Client ID. Input the BuildUtil Client ID you previously created and click Enter.

  3. Next, a new line will appear: Insert Uploader’s Client Secret. Input the BuildUtil Client Secret you previously created and click Enter.

  4. After that, a new line will appear: Insert Log level (OPTIONAL). The log level determines how detailed the log files will be. You can also leave this line empty if you choose, so that no extra information is added to the log. When you’re done, click Enter.

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

    patcher

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

    ./justice-build-util-v3.3.1-linux_amd64
    configure --clientid <buildutil_client_id> --clientsecret <buildutil_client_secret> --iamurl <iam_url>

Uploading a Game using BuildUtil

Once you have set up the requirements below, you can start to upload your game using BuildUtil.

Prerequisites

  1. Make sure you have set up a Currency in your Publisher Namespace.
  2. Make sure you have created a Game Namespace.
  3. Make sure you have already Published a store.
  4. Make sure you have created Build Util Client Credentials.
  5. Make sure you have created Game Client Credentials.
  6. Make sure you have set up Payment Configuration.
  7. Make sure you have set up Adyen or Xsolla as your payment aggregator.
  8. Make sure you have configure BuildUtil.

How to Upload a Game Using BuildUtil

You can upload the game using BuildUtil with command upload. If this is the first time you want to upload a game, you need to configure build util by following steps in the previous section.

  1. Set up the Game SDK configuration. Please see below for the example of the Unity SDK configuration.

    {
    "PublisherNamespace":"AccelByte",
    "Namespace":"AccelByte",
    "ClientId":"899e6970d63b4df893e6da7d346c4989",
    "RedirectUri":"http://127.0.0.1"
    }
  2. Then, run the upload command. Please use the note below for more information:

    • --url (-u): Base URL to the service. For example: ./justice-build-util-v3.3.1-linux_amd64

    • --namespace (-n): The publisher namespace.

    • --appID (-a): The app id of the game to upload. The app id should be unique, one for each game.

    • --dir (-d): Absolute path of the directory containing the file to be uploaded.

    • --entrypoint (-e): Entrypoint/executable game relative path in 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): 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 the Windows 32-bit then pick the 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 just place the file named .ignoreconfig inside the directory of the game to be uploaded and just skip this flag. In that case, BuildUtil will automatically read your file.

    • --type (-t): Type of the game to upload. Currently only support GAME or DLC. For example GAME.

    Here is the syntax to upload command:

    ./justice-build-util-v3.3.1-linux_amd64 upload -u <base_url> -n <publisher_namespace> -a <game_appid> -v <game_version> -e <entrypoint_file> -f <absolute_path_to_sdk_config> -d <absolute_path_to_game_directory> -p <game_ platformid>

    For example :

    ./justice-build-util-v3.3.1-linux_amd64 upload -u https://justice.dev.accelbyte.io -n accelbyte -t GAME -a other123 -v 1.0 -e "otherexe.exe" -f "/home/taufiqi/Downloads/UnitySDKConfig.json" -d "/home/taufiqi/Documents/samplegame" -p win64

    uploading-a-game

    uploading-a-game

Viewing the Uploaded Game and Set as Current

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

How to View the Uploaded Game and Set as Current

  1. Select Payment Configurations > App Distributions menu in Admin Portal and the App Distributions page will appear.

    uploading-a-game

  2. Then, find the game you uploaded from the list. In this process, the name of the uploaded game is other123.

    uploading-a-game

  3. Click the View button to view the uploaded game details. The uploaded game details page will appear.

    uploading-a-game

  4. In the Build Info panel, click the Set as current button to set the uploaded game as the current available version. The Set as current modal will appear.

    uploading-a-game

  5. Click the Set button to proceed and click the Cancel button to cancel the process.

Setting Up the Current Version from BuildUtil

You can also set up a version as current using BuildUtil through the command prompt or terminal. This process is actually resulting in the same output as using the Admin Portal, only in a different way.

How to Set Up the Current Version from BuildUtil

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

  • --url (-u): Base URL to the service. For example https://alpha.justice.accelbyte.net

  • --appID (-a) Game’s AppId which will be updated

  • --namespace (-n) The publisher namespace. To find your publisher namespace you need to login in Admin Portal page the default namespace used is publisher namespace.

  • --platformId (-p) The target platform identifier where the uploaded game will run. Pick one of these value : [ win32, win64, windows, darwin, linux-ia32, linux-amd64, linux-generic ]. For example, you’re targeting the Windows 32-bit then pick the win32.

  • --version (-v) Version of the game to upload. For example 1.0.0, 1.0-alpha, etc

Here is the example of the updated command:

./justice-build-util-v3.3.1-linux_amd64 setcurrent --url https://(your base url name).com -a other123 -n accelbyte -v 1.0 -p win64

Also here is an example of how it looks in the terminal:

uploading-a-game

Downloading a Game Using BuildUtil

You can download the game using BuildUtil as an optional choice for debugging purpose.

The real mechanism of download should only happen in Launcher.

How to Download a Game Using BuildUtil

To download a game run download command with following parameters:

  • --url (-u): Base URL to the service. For example https://alpha.justice.accelbyte.net

  • --namespace (-n): The publisher namespace.

  • --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 -r flag as 1, then fill this param with value 1. If no value of -r supplied during upload, then fill this param with value 2. Any values other than 1 and 2 are invalid.

Here is the example of the updated command:

./justice-build-util-v3.3.1-linux_amd64 download -d ~/Documents/samplegame -n accelbyte -b Ru3DBU-sLr --url https://(your base url name).com -r 2

Also, here is the example how it looks like in terminal:

uploading-a-game

Once you are done, you can find the downloaded file in the directory that you have specified before.

What's Next?