Xbox consoles crash reporter integration guide
Overview
This documentation will provide step-by-step instructions to enable the Xbox Crash Reporter for Xbox Series X (XSX) and Xbox One consoles. Once enabled, crash reports will automatically be sent to the ADT Web Dashboard for analysis.
Prerequisites
Before proceeding, ensure the following:
BlackBoxSDK Integration
Confirm the Windows version of the BlackBoxSDK is already integrated. Refer to the ADT SDK Integrations Documentation for detailed guidance.
Unreal Engine source code
Ensure your Unreal engine is forked from the source code (not downloaded from the Epic Games Store), as the latter does not support console development.
ADT SDK and CLI Setup
a. Navigate to Game Settings → Game Integration
b. Under the Target Platform section, select Xbox One (GDK) or Xbox Series X
c. Download the required add-on from the ADT Download page
Xbox add-on integration
Extract the downloaded add-on. This will generate a folder named BlackBox-UE4SDK-x64-XSX-(SDKVersion).
Open the folder and copy the BlackBoxSDK directory.
Paste the BlackBoxSDK directory into your game project’s plugin folder
Steps to enable the Xbox Crash Reporter
After successfully creating a version (refer to Create versions and register builds document), you need to follow the following instructions:
Register your Xbox builds
Select the appropriate target platform:
a. xboxonegdk for Xbox One builds.
b. xsx for Xbox Series X builds.
c. Run the following command to add a new build ID:
.\BlackBoxCLI.exe build register --smartbuild --platform-name xsx --platform-arch x64 --apikey <your_api_key> --game-project <game_project_path> --game-engine <game_engine_path>
Set the Crash URL in Unreal Engine
Run the command below to register the crash URL:
.\BlackBoxCLI.exe crash-url set
Modify the Unreal Engine (Restricted)
This step is restricted to ADT customers due to NDA compliance with Microsoft. Contact our support team for detailed instructions.
Packaging and uploading
Package your game
a. Open the .uproject file.
b. Use the Unreal Engine Editor and select Platform -> XSX -> Package Project.
Upload PDB files
Once the cook has completed, upload the PDBs by using this command:
.\Blackboxcli.exe upload --platform-name XSX --platform-arch x64 --apikey <your_api_key> --game-project <game_project_path> --game-engine <game_engine_path>
Upload binary files
Run the command below to upload the binary file to the ADT system:
.\BlackBoxCLI.exe build upload-binaries --game-archive <the path for the game archive> --entry-point <the .xvc file for the game> --apikey <your_api_key> --game-project <game_project_path> --game-engine <game_engine_path>
Testing the Xbox Crash Reporter
After uploading the build to ADT, follow these steps to test the crash functionality:
Donwload and Deploy the build
a. Login to Accelbyte Development Toolkit Hub (download from ADT website if not installed).
b. Navigate to the "Channels" or "Versions" page to locate your uploaded build.
c. Click Download, and once complete, the button changes to Deploy.
d. Select your devkit and deploy the build (refer to Connect Devkits for instructions).
Trigger a crash a. Launch the game on the devkit and intentionally crash it when it's fully launched.
b. Navigate to the System folder, open the System Scratch folder on the devkit, and locate the crash report. Files will be named: xboxgdkcrash<iso8601_time>.
Verify Crash Report Upload a. Relaunch the game to trigger the upload of the crash report to the ADT Backend.
b. Verify the crash details on the ADT Web Dashboard.
Xbox crash reports are uploaded upon the next game launch after a crash occurs.