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.

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:

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

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.

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.

• Debugging PhysX
• Multiplayer helpers

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.