You are here:

Unreal Engine 3 (UE3) Debugging

Note: While reading this document you will see [GAME]. This symbol is intended to be replaced by the name of your game. For instance, Unreal Engine 3 comes with ExampleGame and UDKGame.

Unreal Engine 3 Changes

The following sub-sections outline the changes that need to be made to the Unreal Engine 3 (UE3) tool-chain, depending on which Visual Studio project of UE3 solution you would like to debug.

Build.bat

This change is required for all UE3 users to enable debugging as a whole. The UE3 tool-chain renames some of its files during the build process, but GDB requires that the symbols names match the library name.

Otherwise if Win7 and below, you can modify the build scripts to do this automatically. The file we need to modify within the UE3 root directory is: Development\Src\Android\java\build.bat.

Just after the following line:

copy %1-Android-%2.so libs\armeabi-v7a\libUnrealEngine3.so > NUL

Add the following:

ECHO Creating a symbolic link to allow debugging because file names must match.
mklink /H libUnrealEngine3.so %1-Android-%2.so > NUL

NOTE: mklink will not work on newer versions of Windows without enhanced permissions. You may need to copy instead.

AndroidToolChain

This modification is recommended to ensure that all call stack entries can retrieve source code files. Only some projects may have problems without this change, but it is easier to make the change sooner than to remember why it is behaving poorly later.

Modify Development\Src\Android\UnrealBuildTool\System\AndroidToolChain.cs inside of the function GetCLArguments_Global(). From here, find the following line:

Result += "-ffunction-sections";

You can comment this out or move this line to the area lower in the function, to where release optimizations are being applied (such as –O2). This flag has pros and cons so you should profile your app in release mode and look at the file size since it can affect either in both good or bad ways.

We also recommend:

For performance profiling (Debug or release)

Result += " -g";|
Result += " -funwind-tables"
Result += " -fno-omit-frame-pointer”
Result += " -marm

Target fast modern architectures

Result += " -march=armv7-a";
Result += " -mtune=cortex-a15";
Result += " -mfloat-abi=softfp";

Target fast floating point uses using either:

```
Result += " -mfpu=vfpv4";
```
```
Result += " -mfpu=neon-vfpv4";
```

But for neon, the user must either do additional hand coding of neon assembly, or add additional unsafe math flags and work out the issues that may result.

Replacing the Toolchain (optional)

Some users have chosen to move to newer versions of NDK and even move to the win64 toolchain so that they can make incredibly large linked files. Here are somethings to consider.

You may need to modify the NDKROOT to point to the new NDK. UE3 build tools typically sets its own if this environment variable is not set. This is done in AndroidToolChain.cs.

To move to win64, tools paths in AndroidToolChain.cs need to switch from windows to windows-x86_64.

Preparing Your Level Data

At this point, be sure that your project builds normally. Use UnrealFrontEnd.exe before using Nsight Tegra, Visual Studio Edition so that UnrealFrontEnd.exe may load the game level data to the target device. Even with Nsight Tegra, you will need to use this tool to load the game data, but Nsight Tegra will be able to update the game's APK.

The Project for Debugging

In the earlier steps, you have prepared UE3 so that it compiles and packages everything correctly in preparation for debugging. The work there is done by the Unreal Build Tools. Now we must set up a project for the Nsight Tegra debugger to appropriately launch and attach to your UE3 based game.

New Project

Create a new project in your existing UE3 solution by going to File> New> Project…
Pick Android from the templates column on the left. Then select Android Project (External Build System).
We recommend setting the project directory to: Development\Src\Debugger.
In the project wizard, fill in the following fields:
Working directory = $(SolutionDir)\..\Intermediate\[GAME]\Android\$(Configuration)
Path to APK = $(SolutionDir)\..\Intermediate\[GAME]\Android\$(Configuration) \bin\UnrealEngine3-$(Configuration).apk
Symbols Directories = $(SolutionDir)\..\Intermediate\[GAME]\Android\$(Configuration)
Java source code directories = $(SolutionDir)\Android\java\src
Complete the project creation.

Configure for Launch and Dependency Building

Right-click on the new project and set it as your start-up project.
Right-click on the project and select Project Dependencies. Check [GAME] Android, which you would use to compile the game normally.
Set up the platform first by changing the platform on the toolbar to Tegra-Android. Then modify the platform configuration setting by going to Build >Configuration Manager.
1. Make sure the platform in to top left is still set to Tegra-Android.
2. Find the row for project [GAME] Android. Set it to build and ensure that its platform is Win32. This will enable F5 and other build and debug commands that are needed to compile the complete project.

Building and Launching

Make sure the platform in the toolbar is set to Tegra-Android.
You may use any of the conventional methods to debug and launch in one step:
- F5
- The Start Debugging toolbar button
- From the Visual Studio menu, Debug > Start Debugging.
Alternately, you may use the corresponding build commands to build separately.