Over the last few months I've been building a node-based scene editor for
game projects and also as an excuse to spend some quality time with Dear ImGui.
Most of the game projects I've worked on are built with Java using
libGDX, and this node editor work is motivated in part because I've repeatedly bounced off of the default
ui layout system built into libGDX: Scene2d.ui. It works quite well
for relatively simple user interfaces but every time I think I have a grip on it, I run into some layout issue that devolves into poking
at layout code randomly and with increasing desperation trying to get it to cooperate.
Dark Souls - I want you, to git gud!
Based on some sophisticated user interfaces built with the Scene2d toolkit; such as Spine and
Talos VFX, this is clearly a đ skill issue and I should just stop whining
and git gud. That said, it's possible that I'm a closet masochist and secretly enjoy being frustrated by the "I have no idea what I'm
doing" stage of learning new things, because instead of reading the docs and source code, and experimenting until I solidified my
understanding, I took this struggle with Scene2d as a sign that I should make my life even harder by learning not just a different UI
library, but one that requires Java bindings to work in my accustomed language and framework!
Since Dear ImGui and imgui-node-editor are c++ libraries, the first step was to pick one of the
Java bindings libraries, and the two most likely picks were:
Both already include the imgui-node-editor extension in the bindings, and while gdx-imgui is more directly tied into libGDX
it is also a bit less mature than imgui-java and I ran into a couple issues with how the node editor extension is set up, so
I went with imgui-java. If you just need vanilla imgui support in a libGDX application then gdx-imgui may be a
better choice.
There is some platform-specific code that can't live directly in the libGDX core module, so I created an interface that can
be implemented in both the lwjgl3 and core modules:
The implementation of this interface for desktop platforms in the lwjgl3 module has to be created on app launch, and I pass
it into the game's ApplicationAdapter class (called Main in this snippet) where it can be used by the
platform-agnostic implementation:
// in lwjgl3/Lwjgl3Launcher.java...
private static Lwjgl3Application createApplication() {
var imguiDesktop = new ImGuiDesktop();
var configuration = getDefaultConfiguration();
return new Lwjgl3Application(new Main(imguiDesktop), configuration);
}
And the lwjgl3 implementation looks roughly like this:
public class ImGuiDesktop implements ImGuiPlatform {
public long window;
public ImGuiImplGlfw imGuiGlfw;
public ImGuiImplGl3 imGuiGl3;
public final Map<String, ImFont> fontMap = new HashMap<>();
@Override
public void init() {
if (Gdx.graphics instanceof Lwjgl3Graphics lwjgl3Graphics) {
imGuiGlfw = new ImGuiImplGlfw();
imGuiGl3 = new ImGuiImplGl3();
window = lwjgl3Graphics.getWindow().getWindowHandle();
if (window == 0) {
throw new GdxRuntimeException("Failed to create the GLFW window");
}
ImGui.createContext();
ImGui.getIO().setIniFilename(null);
initDocking();
initFonts();
imGuiGlfw.init(window, true);
imGuiGl3.init("#version 150");
} else {
throw new GdxRuntimeException("This ImGui platform requires Lwjgl3");
}
}
@Override
public void startFrame() {
imGuiGl3.newFrame();
imGuiGlfw.newFrame();
}
@Override
public void endFrame() {
imGuiGl3.renderDrawData(ImGui.getDrawData());
}
@Override
public void dispose() {
imGuiGl3.shutdown();
imGuiGl3 = null;
imGuiGlfw.shutdown();
imGuiGlfw = null;
}
@Override
public ImFont getFont(String name) {
return fontMap.get(name);
}
private void initDocking() {
// NOTE: skipped in this example, docking support configured here if needed
}
private void initFonts() {
// NOTE: skipped in this example, but I'll come back to fonts later
}
}
Then the platform-agnostic implementation can call into the desktop implementation as needed:
public class ImGuiCore implements ImGuiPlatform {
private final ImGuiPlatform platform;
private InputProcessor imGuiInputProcessor;
public ImGuiCore(ImGuiPlatform platform) {
this.platform = platform;
this.imGuiInputProcessor = null;
}
// NOTE: call this in the main ApplicationAdapter's 'create()' lifecycle method
@Override
public void init() {
platform.init();
}
// NOTE: call this in the main ApplicationAdapter's 'dispose()' lifecycle method
@Override
public void dispose() {
platform.dispose();
ImGui.destroyContext();
}
@Override
public void startFrame() {
// restore the input processor after ImGui caught all inputs
if (imGuiInputProcessor != null) {
Gdx.input.setInputProcessor(imGuiInputProcessor);
imGuiInputProcessor = null;
}
platform.startFrame();
ImGui.newFrame();
}
@Override
public void endFrame() {
ImGui.render();
platform.endFrame();
// if ImGui wants to capture the input, disable libGDX's input processor
if (ImGui.getIO().getWantCaptureKeyboard() || ImGui.getIO().getWantCaptureMouse()) {
imGuiInputProcessor = Gdx.input.getInputProcessor();
Gdx.input.setInputProcessor(null);
}
}
@Override
public ImFont getFont(String name) {
return platform.getFont(name);
}
}
Finally, in a game screen where you want to use imgui, setup the render() lifecycle method like this:
@Override
public void render(SpriteBatch batch) {
ScreenUtils.clear(backgroundColor);
imgui.startFrame();
ImGui.pushStyleVar(ImGuiStyleVar.WindowRounding, 10f);
// update within the imgui frame to make sure the imgui input processor is active
imguiScene.update();
// imgui window fills entire screen, layout of panes and widgets is handled internally in the scene
ImGui.setNextWindowPos(0, 0, ImGuiCond.Always);
ImGui.setNextWindowSize(ImGui.getMainViewport().getSize());
imguiScene.render();
ImGui.popStyleVar();
imgui.endFrame();
}
The one quirk of imgui-node-editor that has had the most substantial impact on the way I planned to build the editor is that
any widgets that rely on the imgui child window API just don't work when embedded in a node.
Unfortunately this impacts some foundational widget types:
Using any of these widgets in a node requires some fiddly workarounds if it's even possible at all. For example, I don't think the
Table API is usable in a node or at least I haven't figured out how to make it work yet.
The main way to work around this limitation is to 'fake' the widget type in the node context; i.e. between
NodeEditor.begin/endNode(), and then use it 'normally' outside that context, typically by triggering a popup on a click
within the node context, and then displaying the popup after NodeEditor.endNode(), often in a
NodeEditor.suspend/resume() pair.
This is a little vague so let's look at a concrete example for the combo widget...
Node sizing can be challenging, mostly because the nodes are set up to expand to fit their content. What this means in practice is that I
have to really fight to get a node layout just right.
// add these utility methods wherever it's appropriate, like the main 'Node' class
public void beginColumn() {
ImGui.beginGroup();
}
public void nextColumn() {
ImGui.endGroup();
ImGui.sameLine();
ImGui.beginGroup();
}
public void endColumn() {
ImGui.endGroup();
}
// usage between a 'NodeEditor.begin/endNode()' pair
public void renderNodeContents() {
ImGui.setNextItemWidth(columnSize1);
beginColumn();
// render widgets in first column
ImGui.setNextItemWidth(columnSize2);
nextColumn();
// render widgets in second column
endColumn();
}
Since I've spent a fair amount of time on this, I plan to make a standalone node editor available on github. There are several
architectural things that I have yet to work out about how to make it generally useful for any game rather than the one I'm currently
working on. I'll update this post with a link to the repo once I've started work on it.
Additionally, since there are some fundamental incompatibilities between imgui-node-editor and some of the core widgets
provided by imgui, I've been considering setting up my own library using bindings created with the new
Java Foreign Functions and Memory API
similar to what I did with SDL3 as a learning project:
github - jsdl3. This would allow me to integrate some of the workarounds that folks
have put together that haven't been merged into imgui-node-editor itself for various reasons so that people could use more
(if not all) of the imgui widgets directly rather than having to implement workarounds.
