Blueprint Debugging

Pause execution using Breakpoints to inspect graphs and the values of variables.

Windows
MacOS
Linux

Blueprint debugging is a very powerful feature that allows you to pause execution of the game in Play In Editor or Simulate In Editor mode and step through any graph of a Blueprint or Level Blueprint through the use of Breakpoints.

Debugging Controls

The Blueprint Debugger provides control over execution of the game during PIE and SIE sessions. The controls become enabled in the Toolbar when the game is running. Different debugging controls appear depending on the type of Blueprint being debugged and the current state of the debugging session. Some controls only become enabled when relevant, such as when a Breakpoint is hit.

debugging_editor.png

Both the Debug tab, which can be opened from the Blueprint Editor's window menu, and the Blueprint Debugger will display the context-sensitive debugging buttons when PIE or SIE modes are active.

blueprint_debugger.png

Breakpoints

Breakpoints are markers that can be placed on Blueprint graph nodes. When a node with a Breakpoint is about to be executed during PIE or SIE mode, the game will pause and the developer will be taken to the node in the Blueprint Editor's graph view. This provides the opportunity to observe the values of variables and examine or step through the flow of execution within the Blueprint. All Breakpoints for a given Blueprint are displayed in the Debug tab, and can be viewed in the Blueprint's graph when selected. To place a Breakpoint on a node, right-click the node and select Add Breakpoint from the context menu, at which point a solid, red octagon will appear in the upper-left corner of the node. The Breakpoint can be removed by right-clicking the node again, or by right-clicking the Breakpoint's entry in the Debug tab, and selecting the Remove Breakpoint command.

ActiveBreakpoint.png

This Breakpoint will interrupt the game when the Print node is about to be executed.

To disable a Breakpoint temporarily without fully removing it, you can right-click on either the Blueprint node itself, or the Breakpoint's entry in the Debug tab, and choose Disable Breakpoint from the context menu. A disabled Breakpoint will appear as a an outline of a red octagon. Disabled Breakpoints will not execute, but can easily be enabled again. This process is more convenient and less prone to human error than destroying and remaking Breakpoints repeatedly.

InactiveBreakpoint.png

This Breakpoint has been disabled and currently does nothing, but can easily be enabled again if it is needed.

To enable a disabled Breakpoint, Right-click on the node and choose Enable Breakpoint or click the icon next to the Breakpoint in the Debug tab. This can also be done by Right-clicking the Breakpoint in the Debug tab and choosing Enable Breakpoint. Breakpoints can be created, disabled, enabled, or destroyed at any time, including during a debugging session. Breakpoints are saved in project .ini files, so they will persist between Editor sessions.

If a Breakpoint is placed at an invalid location, it may appear yellow and feature an exclamation point. In some cases, compiling the Blueprint will resolve the issue. If this is not the case, holding the mouse cursor over the Breakpoint icon will reveal an explanation.

WarningBreakpoint.png

This Breakpoint is invalid and will never be hit. In some cases, recompiling the Blueprint can fix this.

When pausing execution with a Breakpoint, the Editor will highlight and focus the node, and will place a large, red arrow over it.

BreakingOnBreakpoint.png

This Breakpoint has just been hit, pausing execution.

Debug Tab and Blueprint Debugger

The Debug tab shows information designated as important by the designer in the form of Breakpoints and watch values as well as a trace stack of all nodes belonging to the Blueprint that have been executed. This window also shows controls for controlling execution of the game when using Breakpoints.

Watch Window

The Blueprint Watch Window is designed to speed up debugging by giving you access to the variables and nodes that you want to watch, even across multiple Blueprints. Watch data from every Blueprint that you open in the Editor, and that is part of the current callstack, will be consolidated into a single list, which will be populated with current data whenever Blueprint execution is paused. Using this list, you can inspect variables and function outputs, and jump between Blueprints with ease. Arrays, Sets, Maps, and other data structures can be expanded, making drill-down examination of any data they contain quick and convenient. You can also click on an entry in the "Node Name" column to go to the named node in any Blueprint, or select an entry in the "Object Name" column to select that specific Object instance.

Call Stack

The Call Stack that is available during debugging sessions is similar in concept to the call stack that is found in most C++ development environments. The Call Stack reveals the flow of execution between Blueprint and native (C++) code with the Blueprint Function currently being executed at the top of the stack.

Blueprint Macros do not show up in the Call Stack. Instead, a Blueprint Macro will appear as part of the Blueprint Function which called it.

ActiveBreakpoint.png

The Blueprint Function above recursively performs Factorial calculation. A Breakpoint has been set at the end of the function.

When a Breakpoint is hit, the Call Stack lists the functions currently in operation, starting with the current function at the top, and proceeding downward to the calling functions. This means that each line entry contains the name of a function that was called by the function named on the line immediately below it. In the case of a recursive (self-calling) function, the same function name may appear multiple times in a row.

CallStack_FiveFactorial.png

This Call Stack shows a five-deep recursive call into the Factorial function shown above, which was originally called from the Actor's main Blueprint graph, which in turn was responding to the BeginPlay Event called from native (C++) code.

CallStack.png

To view (or hide) the Call Stack, select it from the Window dropdown, under the Developer Tools submenu.

Execution Trace

The Execution Trace stack shows a list of the nodes executed with the most recent at the top.

Blueprint Debugging - Execution Trace Stack

This list updates as you step through the graph when debugging.

Tags
Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback