Debugging a Packaged Build

Overview

Once you have Cooked and Packaged a game, you may want to debug that game using a programming IDE. This is more difficult than debugging an editor build because you will need to launch a different executable than normal, possibly with extra command line options and configuration. This page explains the different options for debugging a packaged build using Microsoft Visual Studio, but the process should be similar using other platforms and programming environments.

In this document, strings like 'GameName' should be replaced by your game's internal name (ie, you should have a GameName.uproject file), and 'GameDirectory' with the directory containing your game's .uproject file.

Finding Executables and Symbols

Before you do anything else, you need to know where to find the executable and symbol/PDB files you want to debug. There are several places they might be:

• If you compiled the game locally on a windows machine, both the executable and pdb file will be located in GameDirectory\Binaries\Win64 and named GameName.exe and GameName.pdb for the default Development configuration, or GameName-Win64-Shipping.exe for the shipping configuration. If you compile that configuration locally from Visual Studio it will override these files. Making a client or dedicated server build will also change the exe/pdb names

•  If you packaged locally, the executable will be in PackagingRoot\GameName\Binaries\Win64 where the PackagingRoot was either specified in the package process or uses the default of GameDirectory\Saved\StagedBuilds\WindowsNoEditor\GameName\Binaries\Win64. If you did not make a Release version, this should contain both the pdb and exe files.

• For Release versions of the game or builds generated by a Continuous Integration system, you will need to get the pdbs from earlier in the build process

• You can also use a Symbol Server which needs additional setup

Attaching To a Running Game

The simplest way to debug a packaged build is to start running it like you normally would, and then attach to the already-running game from visual studio. To do this, use the Debug->Attach to Process window, and then find your executable in the list. If you launched the game via the packaged build executable it puts in PackagingRoot, you will have two different exe files, you probably want to attach to the one that has a Title. Once you attach, it will either work right away, or it will complain about missing symbols. If it complains about missing symbols, you can select the symbol location either from the error dialog, or via the Modules window, which can be opened from Debug->Windows->Modules, right clicking the top executable, and picking Load Symbols. Once the Load Symbols dialog is open, you should navigate to wherever your pdbs are, as described in the previous section.

Once you are attached and symbols are working, you should be able to set breakpoints or use the Break All button normally. This is fine if you want to debug something that happens during normal gameplay. But, if you want to debug something that happens early in loading, you need to make your game wait for the debugger at startup. To do this add "-waitforattach" to your command line. For a prebuilt packaged game, one way is to navigate to where the final exec is (NOT the wrapper in PackagingRoot), right click the exe, select Create Shortcut, right click the shortcut and pick Properties, then add "-waitforattach" to the end of the Target section. Or you can launch the executable from a command prompt or other launcher

Launching From Visual Studio

If you want to debug the game multiple times, it is easier to launch the executable directly from visual studio with the debugger already attached. To make this easier, you should install UnrealVS as explained in Setting Up Visual Studio so you can quickly change command line parameters. If you cooked the build locally, you can just switch your configuration in visual studio to Development and hit run, this will launch and use the cooked content in GameDirectory\Saved\Cooked\WindowsNoEditor. When launching this way, load times might be slightly slower because you're launching a Cooked build, but not a true Packaged build as it is not going to be using the .pak files.

You can also launch a true Packaged build, either using an executable you build locally or using the executable/symbols created by someone else. The process is slightly different:

•  For a locally built executable, you set it up the same as testing a local cook, but you need to point it at the packaged data. One way to do this is to add -BaseDir="PackagingRoot\WindowsNoEditor\Engine\Binaries\Win64to your commandline, where PackagingRoot needs to be the full path on your local HD. This can be done with UnrealVS or via the Properties method described below. This method is useful when you want to make local changes and test without recooking, but may fail if your local game version is too different than than of the packaged build. To make sure it works, sync your local source control to the exact changelist used to make the packaged build

• For a prepackaged executable, you can trick visual studio into thinking it built the packaged executable. To do this, first switch to a packaged configuration like Shipping, then right click the project for your game in the solution explorer and select properties, and go to the Debugging tab. Now, you will need to change the Command field to point to the executable you want to run (there's a Browse option on the drop down), the Working Directory to the directory containing the executable, and add -BaseFromWorkingDir to the Command Arguments. This is a different version of the -BaseDir argument from above that will look at the working directory and use that to compute BaseDir for you automatically. Confirm and close the window, then launch normally and it should launch the packaged executable instead of your local one. NOTE: You are modifying the local project settings by doing this, so to return to the default behavior of launching the compiled executable set Command to $(TargetPath) and Working Directory to$(ProjectDir). Also it will get reset automatically for you the next time you generate project files