Unreal Engine 4 – Debugging on Android

Debugging is the prose of life for every programmer. In Unreal Engine 4 there are many tools for debugging and profiling a game on Windows and Mac. Even for iOS, the XCode is a fine tool for nice bug hunting. But the Android was always… odd. For a long time the logcat was the only source of information about what is going inside the Unreal Engine game and it was always frustrating when something is crashing on device only. Theoretically, if something works in the editor it should works on the device too, but… this is theory and practice shows something completely different ;)

A new era for Android on Unreal Engine?

It might be, because with Visual Studio 2015 we received a powerful IDE that supports programming and debugging for Android (and other mobile platforms too) out of the box! And, it appears, that with the same tools we can easily debug the native c++ code on Android device!

Let’s get started.

Prerequisites

I’ve tested the following solution using:
  • Visual Studio Community 2015 Update 2 with Visual C++ Android Development (Update 2).
  • Unreal Engine 4.11.2
  • LG Nexus 5 with Android 6.0.1
The Android building environment was:
  • Android SDK API-23
  • NDK r10e (64 bit version)
  • JDK 1.7.0_55
  • Ant 1.9.3
You probably might have the Android building environment from TADP, which is fine. I’m using the newest possible one to be able to add additional libraries, that requires the new Android SDK and NDK. It’s really not that difficult to run Unreal Engine 4 with the newest versions of Android building environment, yet, it still requires few tweaks.

The project

For test purposes I’ve created a new Third Person C++ project with Mobile/Tablet targeting.

Building and deploying

Before debugging the game must be built and deployed to the device. I always use Unreal Frontend for this and I’m strongly recommends this to everyone. This tool gives You much more power with setting up the building/cooking/deploying process than the Editor.
In Build section make sure that “Debug” target is set and that in the Additional Cooker Options there is no “-distribute” argument set.

Creating debugger project

Now, when the game is on device and we can see it’s running, we can create a debugger project in Visual Studio.
Open the Game solution and then right click on your solution and select Add->Existing Project…
Go to the directory with Your game project and then to the Binaries/Android and double click the apk file.
As you can see, based on the given apk, the new project has been created inside the solution.


Unfortunately if you check where the project has been created (right click on it and select Open Folder in File Explorer) you will notice that it was created in the Temp directory. If you want to keep it safe, simply move it somewhere else and add it once again to the solution.

Configuring debugger project

Select the Debug ARM in the Configuration Manager


The ARM option will be created with the just created project.
Then go to the Tools->Options, find Cross Platform->C++->Android section and make sure that all the paths are the same as the ones used to build UE4 game.


Next right click on the project and go to Properties


Make sure the configuration and platform are is still Debug ARM. Almost everything should be set automatically, except the directory where debugging symbols are located. And this will be in Your game directory: Intermediate\Android\APK\obj\local\armeabi-v7a

Launching debugger

Make sure the game on your device is not running and is not even in the background.
Right click on the project, select Debug->Start new instance
If the Visual Studio will ask if to build the project say No!
If you can see this dialog – you are almost here! (It can take few seconds though).


Using debugger

Using debugger is the same as you debug the Windows solution. Let us set the breakpoint in the MoveRight function in the GameCharacter.cpp and try to move the character on the device. As You can see we’ve hit it!


Summary

And that’s it. No more fighting with logcat, now we can normally debug!
Still, there are few things I’d like to mention:
  • I haven’t test it on any other device than my own.
  • I haven’t test it on any other, more complicated, project than the Third Person game from templates, neithter on modified Engine.
  • I haven’t test in on any other Android building environment.
  • I was trying to start debugging using Visual Studio 2013 with nVidia Nsight plugin. It can hit breakpoint but after few seconds there is a crash due to thread fuckups. With Visual Studio 2015 inside debugger everything works like a charm!
  • When you stop debugging process the app will not stop. You have to kill it manually.
  • You can attach debugger to the already running process (right click on the debugger project then Debug->Attach to Android process).