ImGui Debug Tools

I often needed to inspect the runtime state of various systems, and building one-off debug tools for each case quickly became repetitive. To address that, I built a shared ImGui-based debug layer in Unreal Engine 5 that makes new tools cheap to add and easy to maintain.

ImGui is a lightweight immediate-mode GUI library for C++ developed by Omar Cornut. Integrating it into Unreal Engine was straightforward thanks to an existing plugin by segross.

I chose ImGui over UMG mainly because it allows much faster iteration for developer-facing tools.

Architecture

The system is built around a central UGameInstanceSubsystem that owns the debug layer lifecycle and drives ImGui drawing each frame. Individual tools are implemented as subclasses of a base UImGuiShard type, overriding InitializeShard() and TickShard() as needed. A UImGuiShard is a small, self-contained ImGui tool responsible for rendering one part of the overall debug interface.

At startup, the subsystem discovers the available shard types, instantiates them, and initializes them. During runtime, it ticks each shard every frame so it can render its portion of the UI.

The ImGui interface includes a menu that allows individual shards to be toggled on and off. This helps keep the interface clean even when many shards are present in the project.

The dependency direction is intentionally one-way: the subsystem knows only about the shard base type, while each shard remains self-contained and does not need explicit registration code or direct awareness of the subsystem. That keeps new tools easy to add, including from other modules, without requiring changes to a central registry.

Build Considerations

This debug layer is intended for non-shipping builds only. The resulting UIs are not meant to look good, they are meant to be functional and fast to iterate on. The subsystem overrides ShouldCreateSubsystem() to avoid being instantiated in shipping builds, and shard-specific code is additionally guarded with compile-time checks where appropriate.

CommonUI Conflict

One integration issue came from using ImGui alongside CommonUI. In my setup, CommonUI’s input routing prevented ImGui windows from receiving input correctly.

I resolved this by adapting an approach used in Cog by Arnaud Jamin: a custom UCommonUIActionRouterBase implementation that routes input between CommonUI and ImGui more predictably. With that in place, both systems were able to coexist correctly in the scenarios I tested.

Example Shards

Inspection Shard. Shows actors in the level, along with some of their properties.

Settings Shard, integrated with my Settings Plugin. It allows inspecting and modifying game settings at runtime.

Audio Devices Shard, showing the audio devices available on the system and allowing the active one to be selected at runtime.