First steps - integrate the BlackBox tools into an Unreal project

Overview

To send crash reports from your Unreal game to BlackBox, you need to integrate BlackBox into your Unreal project. This section goes into all the details you need to know to accomplish that.

The following video walks you through the simplest integration method, swapping the crash URL.

When you have watched the video, use the instructions in this document to do the integration yourself.

Instructions

Install Unreal Engine 4

We currently support Unreal Engine from version 4.23 up until the latest version.

  • To install Unreal Engine from the Epic Games Launcher, follow these steps on the Epic Games website.

  • To retrieve Unreal Engine source code from GitHub, follow these steps on the Epic Games website.

Download the editor symbols from Epic Games

If you have installed Unreal Engine from the Epic Games Launcher, you will need to download the editor symbols used for debugging.

  1. Open the Epic Games Launcher.

  2. Click Library.

  3. Click the arrow beside Launch and choose Options.

     

  4. Check to select Editor symbols for debugging.

  5. Click Apply and wait for the download to complete.
    You can now move on to the next step and create a game in BlackBox.

 

Create a game in BlackBox

Follow the steps below to create a game in BlackBox:

  1. Log into the BlackBox Web Portal.

    You should have received a user account and login information from an administrator via an invite email. If you haven’t received an email, contact us at blackbox-support@accelbyte.net.

  2. Reset your password if you haven’t already done so.

  3. If you are logging into BlackBox for the first time, choose the game you want to access from the list on the game selection list screen.

  4. If there is more than one game in a namespace, choose a game from the drop-down menu. Each time you login to the BlackBox Web Portal, the game will default to the game you select here.

  5. Create a new game by clicking the Add Game button on the game selection screen or by clicking Add game from the toolbar menu.

  6. Enter the name of your new game. This should be alphanumeric but can include spaces, dashes, and underscores.

  7. Click Add and you will be directed to the API Key window.

  8. Copy the API Key for your new game to the clipboard and save it to a file. You will need the API Key later in this process.

  9. Click the Version option on the sidebar and you will be redirected to the version list screen.

  10. Add a new version by clicking the Add Version button and then filling out the field.
    Note: You can pick any alphanumeric characters as your versioning schema. You might want to do simple dates such as “Jan26“, or changeless id, or owner names.

  11. Click Save and you’ll see the new version has been created.

 

Download and integrate the BlackBox Unreal SDK

The BlackBox Unreal SDK is added to your Unreal project and allows you to start adding BlackBox services, such as crash reporting, build uploads, and performance tests.

This video snippet will show you how to integrate the BlackBox Unreal SDK into your Unreal project.

After you have watched the video, follow the steps below to integrate the BlackBox Unreal SDK into your Unreal project.

  1. Click Download SDK in the Getting Started section on the dashboard or from the sidebar menu.

    On the downloads page you will see the latest builds for the BlackBox Unreal SDK.

  2. Click the Download button.

 

Configure your game to use the BlackBox Unreal SDK

This section explains how to configure your game to use the BlackBox Unreal SDK. It’s a five-minute task to get it integrated. Let’s start!

Enable the BlackBox Unreal SDK plugin

The following steps explain how to enable the BlackBox Unreal SDK plugin.

  1. Unzip the SDK/CLI download package on your computer.

  2. Copy the BlackBoxSDK subfolder to:

    1 {GAME_PROJECT_FOLDER}/Plugins/BlackBoxSDK

    You may have to create the Plugins folder if you do not already have one.

  3. Open your game’s .uproject file at:

    1 {GAME_PROJECT_FOLDER}/.uproject
  4. Modify the file to use the BlackBoxSDK plugin.

    1 2 3 4 5 6 "Plugins": [ { "Name": "BlackBoxSDK", "Enabled": true } ]

    The following is an example for the AccelMania.uproject. When the plugin is added to the file it should look something like this:

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 { "FileVersion": 3, "EngineAssociation": "4.23", "Category": "", "Description": "", "Modules": [ { "Name": "AccelMania", "Type": "Runtime", "LoadingPhase": "Default" } ], "Plugins": [ { "Name": "BlackBoxSDK", "Enabled": true } ] }
  5. Open the Build.cs file found at:

    1 {GAME_PROJECT_FOLDER}/Source/{GAME_NAME}/{GAME_NAME}.Build.cs
  6. Modify the file to reference the plugin module.

    The following is an example for the Accelmania.Build.cs. The addition is "BlackBoxSDK" and it’s added to the list of module names as shown in the code snippet below.

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 //Copyright 1998-2017 Epic Games, Inc. All Rights Reserved. using UnrealBuildTool; public class AccelMania : ModuleRules { public AccelMania(ReadOnlyTargetRules Target) : base(Target){ PHCUsage = PHCUsageMode.UseExplicitOrSharedPCHs; PublicDependencyModuleNames.AddRange(new string[] {"Core","CoreUObject","Engine","InputCore","HeadMountedDisplay", "BlackBoxSDK"}); } }

    We are assuming you already have at least one C++ file in your project. This file will not exist until you create at least one.

  7. Open the Unreal Editor.

  8. Go to Edit Menu > Plugins.

  9. If you are asked if you wish to you to enable the plugin, click Yes.
    If the project is configured correctly you will see the BlackBoxSDK plugin in your code, as shown earlier. If you do not, contact your team Unreal admin.

  10. If you are asked to restart Unreal and if you want to rebuild, say Yes to both.
    If you need advice on project configuration, get in touch with us.

Support question?  blackbox-support@accelbyte.net 

Add the plugin

Follow the steps below to add the plugin:

  1. Go to Edit Menu > Project Settings.

  2. Scroll down and select Plugins - AccelByte BlackBox SDK.

  3. Complete the fields in the screen as shown below:

     

    • APIKey The unique id for your game. You saved this to a file when you created your new game.

    • Game Version ID The unique id for your version, found on your game dashboard.

    • Namespace The unique id for your organization, found on your game dashboard.

    • Log Severity Choose one of the following values. We recommend that you use INFO if you are unsure.

Log Severity Level

Remarks

VERBOSE

Lowest code severity level

WARNING

Warning condition for potential problems

INFO

Noncritical notification - contains information messages

ERROR

Indicates a problem in your code

  1. Then you just need to:

    • Check Enable Log.

    • Click on Set as Default in the options at the top.

  2. Click Save.

Enable or disable the BlackBox Unreal SDK

To enable or disable the BlackBox Unreal SDK in Unreal Engine, follow the steps below.

  1. In the Unreal editor, click the Settings drop-down.

  2. Select Plugins.

  3. In the Plugin screen, go to the search bar and search for BlackBox.

  4. Once the search result appears, tick the Enabled box to enable the BlackBox Unreal SDK, or leave it unticked to disable the BlackBox Unreal SDK.

  5. Click Restart Now to restart the Unreal Engine editor and implement the changes.

     

Configure the Crash Reporter Client to use BlackBox

Use the following steps to configure the Crash Reporter Client to use BlackBox.

  1. Open the game engine’s DefaultEngine.ini using your text editor of choice.

  2. Change {UE4_Engine_Root} to the install directory of the Unreal Engine.

    1 {UE4_Engine_Root}\Engine\Programs\CrashReportClient\Config\DefaultEngine.ini
  3. Modify the DataRouterUrl line to the following:

    1 DataRouterUrl="https://blackbox.accelbyte.io/data/public/namespaces/{namespace}/crashreport/{APIKey}"

     

  4. Enter the API Key you saved earlier in double quotation marks, and the namespace from your game dashboard.

  5. Save and close the file.

  6. Open Unreal Engine and go to Edit Menu > Project Settings.

  7. Go to Project - Packaging and enable Include Debug Files and Include Crash Reporter.

    You may have to click the arrow at the bottom of the section to show more options.

  8. Click Save All.

Configure the BlackBox Web Portal to use Crash Reporter

  1. Login to the BlackBox Web Portal.

  2. Select your game version by clicking the version number link.

  3. Click the Edit button next to Crash config default configuration.

  4. On the Edit Crash Config screen, click on Add New Config.

     

  5. Select, edit or add a new configuration.

  6. Enable Crash Tracking.

  7. Change the settings as necessary to change the content of crash reports.

    • Store Crash Video: If you enable this option the crash reports will include a video of the last few seconds before the crash occurred.

      • Frame Per Second (FPS): Affects the granularity of the video. Enter a value between 5 and 99.

      • Video Length: The duration in seconds of stored videos. Enter a value between 10 and 30.

      • Subtitle: There are two options: Key name (for key pushed) and Action name (function calls).

      • Key Per Second (KPS): Affects the number of keys we track per second. Enter a value between 5 and 100.

    • Store Hardware and Software Information: If you enable this option, the crash reports will include information about your game engine, platform, and a DxDialog report (under Hardware Information).

Set the Crash config from SDK

This option allows you to set your crash settings locally rather than using the global crash settings on the BlackBox Web Portal. Go to the Download page to get the new SDK https://blackbox.accelbyte.io/admin/download .

Set the Crash Config from the SDK plugin

  1. Open the Unreal editor.

  2. Open the game project that you have integrated SDK BlackBox.

  3. Go to Project setting > Plugins > Blackbox SDK.

  4. In the User Preferences section choose On, Off, or Web Config for each of the fields.

Set the Crash Config from the console command

  1. Type BlackBox on the console command line and the list of settings displays.
    You can set values for basic profiling, crash reporter, hardware info and/or storing crash video.

  2. Set each value using on, off, and web config. For example, to set video to off, use BlackBox.SetStoreCrashVideo off.

 

Usage notes:

  • On and Off settings will override anything set on the Web Portal. Web Config will set the SDK to use the settings in the BlackBox Web Portal.

  • If you change the the EnableHardwareInfoGathering setting, you must restart the engine for it to take effect.

  • Due to the current limitations of the SDK, if you set EnableHardwareInfoGathering as Web Config, it will only gather partial hardware information regardless of whether it is set to On in the BlackBox Web Portal. We will improve this gradually.

  • If enable_crash_reporter is set to Off, the crash is still sent to the Web Portal, but only contains crash context xml. Other things like creating session_id file, generating video, and generating dx_diagnosis file are skipped.

  • Any changes in these properties generate an external config file in [user]/.blackbox/[game_name]/local_config.ini. The content should be something like this:

 

  • You can create this file yourself but if you make changes while the editor/game is running, you must restart the engine.

Install and configure the BlackBox CLI

This snippet shows you how to get the BlackBox CLI set up to allow crashes to be sent to specific game versions on the BlackBox Backend, and thus the BlackBox Web Portal. It also shows you how to set the BlackBox CLI credentials and configuration information.

After you have watched the video, use the steps below to configure the BlackBox CLI yourself.

Install the BlackBox CLI

Follow the steps below to install the BlackBox CLI:

  1. Go to the Tools folder in the BlackBox Unreal SDK folder you already have, and unzip BlackBoxCLI-x64-windows-1.3.8.zip.

  2. Open a command-line console (cmd).

  3. Navigate to the unzipped BlackBoxCLI folder.

Configure the BlackBox CLI for your game

Each time you generate a new game, or switch game context, you will need to run the following commands from the BlackBoxCLI folder.

  1. Run the command:

    1 .\BlackBoxCLI.exe config set
  2. You will be asked to provide several values.

    1 2 3 4 5 New configuration file created… Namespace[]: {NAMESPACE} GameEngine[]: {UNREAL_ENGINE_INSTALL_DIR} GameArchive[]: {GAME_OUTPUT_FOLDER} GameProject[]: {GAME_ROOT_FOLDER}
    • Namespace: The unique id for your organization on the game dashboard.

    • GameEngine: The install directory for your Unreal Engine, e.g. C:\Program Files\Epic Games\UE_4.21 for the Epic Launcher install.

    • GameArchive: The output folder you intend to use for your game project, e.g. {GAME_PROJECT_FOLDER}{OUTPUT_FOLDER}\WindowsNoEditor.
      It is important that you include WindowsNoEditor at the end.

    • GameProject: The root folder of your game project.

  3. Run the command:

    1 .\BlackBoxCLI.exe credentials set
  4. Paste the API Key that you have been using to reference the game project.

    1 2 APIKey: [PASTE_VALUE_FROM_BLACKBOX] Credential details updated…


Configure the BlackBox CLI for your game version

Execute these commands each time you are working with a new game version or switch context.

  1. Run the following command using the same version id that you entered when you created the game.

    1 .\BlackBoxCLI.exe version set --name "{VERSION ID}"

    To use a new version id, use the add command instead of set.

    1 .\BlackBoxCLI.exe version add --name "{VERSION ID}"

    This creates another game version id in BlackBox and update the contents of your game project’s plugin settings to pick up this value.

  2. Run the following command:
    For a shipping build:

    1 .\BlackBoxCLI.exe build register --platform-name windows --platform-arch x64

    For an editor build:

    1 .\BlackBoxCLI.exe build register --platform-name windows --platform-arch x64 --editor-build

    If you have already registered a build with your environment use the --new flag to add a new build.

    This will generate the required BlackBox.ini file found in:

    1 {GAME_PROJECT_FOLDER}\Config

     

You will no longer be able to edit plugin settings in Unreal settings. In future, before packaging a build, you must always use the BlackBox CLI to set or add a version using either version set or version add

You must always register using the BlackBox CLI before using Unreal to package a build.

Upload a build to the BlackBox Backend

This section explains how to upload a build to the BlackBox Backend.

  1. Open Unreal Editor and go to File Menu > Package Project > Windows > Windows (64-bit).

  2. Navigate to the {GAME_OUTPUT_FOLDER} for the BlackBox CLI.

Create the folder if it does not already exist.

  1. Click Select Folder and wait for the build to complete.

  2. When the build is complete, check that the .EXE and .PDB files were created in your output folder.

    1 {GAME_OUTPUT_FOLDER}\WindowsNoEditor\{PROJECT_NAME}\Binaries\Win64

If you do not see the .EXE or .PDB files in this folder, you may have used the Epic Launcher to install Unreal Engine and not downloaded the editor symbols. Go back up to the Install the Unreal Engine section and follow the instructions for how to do this.

 

Support question?  blackbox-support@accelbyte.net 

 

  1. On the Command line, navigate to the BlackBox CLI and run the following command:
    For a shipping build:

    1 .\BlackBoxCLI.exe upload

    For an editor build:

    1 .\BlackBoxCLI.exe upload --editor-build

If you have already registered a build with your environment use the --new flag to add a new build.

  1. Login to BlackBox.

  2. Select your Version and go to the Session menu.

Test your setup in the Unreal Editor

  1. Go to the Unreal Editor.

  2. Click Play > New Editor Window (PIE).

  3. Perform an action that will crash your build, such as a memory overflow state.

  4. Get a default crash dump in Unreal Editor by pressing ~ and typing debug crash.

  5. Tick the Include log file with submission… box.

  6. Click Send and Close.

  7. Login to BlackBox and select your game version.
    The Crash Reporter section will be updated.

  8. Click your issue number.

  9. Click the General tab to see the crash type where the issue occurred in the Editor build.

     

Test your Crash Reporter setup on the packaged build

Follow the steps below to test that Crash Reporter is set up correctly:

  1. Run your build from its .exe file, which is usually found in the WindowsNoEditor folder.

  2. Perform an action that will crash your build, for example a memory overflow state.

  3. Tick the Include log file with submission… box.

  4. Click Send and Close.

  5. Login to BlackBox.

  6. Select your game version (Game List > Your Game > Version).
    The Crash Reporter section of the screen will be updated.

  7. Click your issue number.

  8. Click the General tab to see the crash type where the issue occurs in thpackaged build.