Version:

Immediate Mode GUI (ImGui) Gem

The Immediate Mode GUI (ImGui) Gem provides the 3rdParty library Dear ImGui , which can be used to create run time immediate mode menus and overlays for debugging and profiling information in Open 3D Engine (O3DE). You can use it to access existing O3DE tooling or set up your own ImGui menus for your components or other game code.

One of the great things about ImGui is that there is next to no overhead when the ImGui game overlay is not visible, which is the default state. It is also very lightweight while in use.

Accessing ImGui menus

ImGui can be accessed by pressing the ~ key in the editor, game or server launchers.

ImGui Menus in Viewport

Server launchers support ImGui if rendering is active. ImGui requires the rhi cvar to not be null.

You can use a keyboard, mouse or controller to navigate the ImGui menus.

Keyboard navigation

For keyboard use the arrow keys to navigate the menus and Space to activate or select an option.

Game controller navigation

You can use the imgui_EnableController CVAR to enable game controller input support, or use the imgui_EnableControllerMouse CVAR to simulate mouse input with a game controller.

The following inputs are supported when using a game controller:

InputDescription
D-PadMove Focus / Navigation
Tweak values (when activated with A)
Resize Window (when holding X)
Left StickScroll
Move Window (when holding X)
X (Left Face Button)Tap: Toggle Menu
Hold + L1/R1: Focus Window
Hold + D-Pad: Resize Window
Hold + Left Stick: Move Window
Y (Upper Face Button)Exit text / on-screen keyboard
B (Right Face Button)Cancel / Close / Exit
A (Lower Face Button)Activate / Open / Toggle
Tweak values with D-Pad
(+ L1/R1 to tweak slower/faster)

The following inputs are supported when simulating mouse input with a game controller:

InputDescription
Left stickMove Mouse Pointer
A (Lower Face Button)Left Mouse Button (Btn1)
B (Right Face Button)Right Mouse Button (Btn2)

You can adjust the sensitivity using imgui_ControllerMouseSensitivity.

Discrete input mode

When ImGui is visible, input is sent to both ImGui and the O3DE game/editor. Sometimes, it is more desirable to only control either ImGui or the game/editor at any given time. To facilitate this, the ImGui Gem supports a discrete input mode.

By default, discrete input mode is off. It can be turned on in the ImGui O3DE menu, or with the CVAR imgui_DiscreteInputMode.

When this mode is enabled, ImGui will be given a 2nd visibility state, at this point, when toggling ImGui visibility via the HOME button or L3/R3 on a game controller, it will toggle through three states instead of just on and off.

  1. ImGui is off - ImGui is not visible.
  2. All input goes to ImGui - ImGui is visible and receiving all input.
  3. All input goes to the Game - ImGui is visible but input is going to the game. This allows ImGui profiling tools and others to be visible on screen while interacting with O3DE.

You can look at the upper right hand corner of the ImGui Main Menu bar to see the current state of ImGui input. You can also interact with this menu for some input tips.

ImGui Input Status

Using ImGui in your component

You will need to:

  1. Ensure the ImGui Gem is active in your project. See the O3DE guide on Adding Gems in a project .
  2. Sign up for ImGui::ImGuiUpdateListenerBus::Handler or use the ImGuiLYCommonMenu class as a base.
  3. Inside the handler perform your ImGui actions.
        void MyImGuiComponent::OnImGuiUpdate()
        {
            // .. do imgui stuff ...
        }

Example O3DE ImGui tools

O3DE ships with many ImGui tools so the options you see will be dependent on the specific gems active in your project.

CVARs

ImGui uses the following Console variables (CVARs) either at runtime via the console, or by placing them in configuration. See the general CVAR guide for more information on configuring CVARs.

NameDescription
imgui_AutoEnableComponentsDeprecated
imgui_ControllerMouseSensitivityAllows the user to set the sensitivity of the left stick mouse movement when using the Controller Mouse Input mode.
imgui_DiscreteInputModeToggles on or off Discrete Input Mode, which can help pipe input to ImGui, the game, or both, while using ImGui.
imgui_EnableAssetExplorerDeprecated
imgui_EnableCameraMonitorDeprecated
imgui_EnableEntityOutlinerDeprecated
imgui_EnableControllerToggles Contextual Controller support functionality. This is off by default, but you can use this to customize your experience on any platform that supports controllers.
imgui_EnableControllerMouseToggles Virtual Mouse Controller support functionality. Occasionally preferable to the contextual controller support.
imgui_EnableImGuiToggles visibility of ImGui, will be visible at startup if in a .cfg file. Roughly equivalent to pressing HOME or L3/R3 as well.