Debugging Basics for Unreal Engine
About five years ago, I began a journey that took me through a fundamental understanding of Unreal Engine and what the platform itself could do for our digital world.
At that time, I was the President of a software company dedicated to creating high quality simulation training for humanitarian organizations around the globe. We had transitioned from VBS (a common defense simulation engine, as well as the underpinnings of the popular Arma series of video games), to Unreal Engine for its openness, performance, and community.
As I stay connected through these years to the Unreal Engine development community I notice one constant, in that there are numerous people chasing a dream: whether to render a movie, create their first video game, or simply try to learn the engine to enter into the industry.
One critical issue that all of these individuals tend to share is that they lack a basic understanding of “figuring out” Unreal Engine, available through a suite of debugging and performance tools. Thus, they follow any number of online tutorials, only to be completely stymied when one portion does not work. The tools, tips, and tricks below are intended to give you a sampling of basic debugging functions, primarily through Blueprint (Unreal Engine’s scripting language).
I must caveat however, that I will not be addressing performance profiling, nor will I handle basics of installing Unreal Engine, as both those concepts can be found at the following links and often vary according to your specific development platform:
Installing Unreal Engine Guides
A simple print command with append can allow you to identify values, sort information, and dig down into actual problems. Often, on forums or Reddit, a user will ask the question, “I’m shooting XYZ with a projectile but I’m not getting collision”.
My solution always has them printing out values for comparison, i.e. what objects is your projectile hitting. This then gives them a comparison for what type of collision settings they need to look at.
The excellent link above gives a great deal of valuable information for new programmers regarding traces, what constitutes an overlap or a multi-hit, etc.
One key thing I always emphasize though is to use the Draw Debug node on any trace before you consider it done. Seeing a trace and determining a hit or a pass-through can sort out multitudes of issues before they stump your progress.
Draw Debug X
There are many Draw Debug Types. I will focus on the two primary ones I use, debug points and lines, but there are a number for a variety of different uses. As you become more experienced in Unreal Engine, you can start to try out these other debug functions and help sort your problems.
Quick, dirty, and one of the simplest ways to compare to points in Unreal Engine, especially with regards to impacts. Doing this with a larger duration will allow you to track something over time, such as a projectile. Doing this with 0.1 duration can help you figure out stutters in animation when combining physical and animation graphs.
Drawing Debug Lines is one of Unreal Engine’s most versatile debug options. It is less strenuous on your system (try drawing lots of debug spheres and seriously hits your system), and with a little imagination, can serve as an excellent guide/explainer as to what your actors are doing in real-time.
When debugging how to orient an object, occasionally Unreal will throw us a curve ball. This is especially true when using transforms. For newer users, some of the terminology associated with transforms can be difficult to figure out, and know what the end result is can be useful. The below blueprint macro is a simple one that demonstrates four things about an object, its physical location, as well as its forward, right, and up vectors colored to imitate the editor widget. This means, during simulation or after a particular function, you can use this to ensure your object is truly in the right orientation, or give you an idea of what went askew should it not be there. The duration input is especially useful if it is a transformation over time.
This extremely simple macro does one thing, visually locates a representation for you from a known object. When you do some operation, and discover an object has disappeared from your character, using this macro will let you know where it is, and based on that, it gives you some clues on how to fix that. For example, I recently used a set transform function. The object I was setting disappeared. Using this macro, I found that object just off of the world origin. What does that mean? It means I used a relative transform in place of a world transform.
Environmental Query System
If you are doing anything using the Environmental Query System (EQS) the EQS testing pawn is a must. First, you must enable your Environmental Query System in the Editor settings. Next, make a new blueprint from EQS Testing Pawn class. Go into the blueprint, and give it an editable Actor variable named Target Actor.
Next, make a query context (deriving from EnvQueryContext_BlueprintBase). Click the functions on the left, and select Provide Single Actor. You will cast to the EQS Testing Pawn you just made, and get the variable you just set. That will be your return.
Now, in any environmental query you make, using that query context will get the actor you set in the Testing Pawn, giving you a solid sense of what exactly is being returned to your query.
Function Definition Checks (C++ Required)
If you happen to have Visual Studio 2017 installed with the Unreal Engine prerequisites, you can always double click on a Blueprint Node to see the actual code definition. This will bring up the header file, which you should navigate through to find the definition file. This file will explain how all of the particular methods involved in Unreal Engine class work, and what type of behavior you should be expecting. Sometimes this is useful, though usually the Blueprint Nodes are pretty decently named and it doesn’t take much to sort out what they will do.
Google-fu
In this line of debug and guide thinking, I also include Reddit and the Unreal Engine Forums. Both are reasonably good sources for help, and a cursory search can typically answer a number of questions you may have had.
If the search doesn’t do it for you, ask for a question on those websites, and potentially, in a day, a week, or longer, it may be answered. This is often my second to last step to a particular programming issues, as often I solve the problem just by debugging and visualizing it.
This is most people last option for which to turn. Typically I would have already posted in the Unreal forums, Reddit, and checked multitudes of Google pages
However, sometimes we all just hit that wall, and depending where you live in the world, sometimes a good example is exactly what you need to move forward. Unfortunately, people who post free example projects neither have the time nor the ability to constantly update their work, nor should they. This is where the Marketplace shines, as each item is listed by which versions of Unreal Engine it is compatible with. Thus, if able, a small(ish) purchase can give you the leg up to need to solve that particular programming problem. But again, I leave this as a last resort.
Using the above tools and tips to guide your development efforts will save you hours of efforts and tons of heartache. Though these concepts are basic, artfully applied, they can describe exactly what is happening within your game, and thus aid you in zeroing in on the specific behavior you need for your render or game.
I hope this helps Unreal Engine newbies make their dreams come true, and if you are a more experienced programmer, please feel free to add your tips and tricks in the comments below!
