nommiin/imgui_gm

An ImGui wrapper for modern GameMaker

ImGui_GM

An ImGui wrapper for modern GameMaker

Release

The itch.io page has pre-built Windows packages for GameMaker

Usage (GameMaker)

⚠️ HEADS UP: Ensure you're using a compatible runtime, see Compatibility heading below for more info

0. Import build of ImGui_GM locally or download it from the itch.io page
1. Create a persistent object and call the following functions in their respective events:

• ImGui.__Initialize() in the create event
• ImGui.__Update() in any updating event (suggested: Begin Step)
• ImGui.__Render() in any rendering event (suggested: Draw GUI)

2. Create an instance of the object at the start of your game, then call ImGui.Begin and ImGui.End in the step event to draw. Below is example GML for how to use the library.

ImGui.ShowAboutWindow();

if (ImGui.Begin("Test Window")) {
	ImGui.Text("Hello World :3");
	str = ImGui.InputText("An Input", str);
	
	if (ImGui.Button("Press Me")) {
		show_message(string("your input was: {0}", str));	
	}
	
	ImGui.End();
}

3. See Coverage heading below or the ImGui script in project for ImGui -> GML wrappers

Snake Case

Not a fan of the namespace-esque functions? Add snake_case.gml to your project! This script is automatically generated at build and includes snake case function definitions for ImGui_GM

Coverage

Pretty much everything is covered! Check out COVERAGE.MD to see a list of wrapped functions along with non-standard ImGui_GM-only functions! The wiki also includes some info on some differences and how to use various ImGui features in GML.

Reference

• dll/
  • main.cpp for DLL initialization & game loop hook-ins
  • imgui_gm.h for some configuration like IMGUIGM_NATIVE
  • imgui_*_gm.cpp for wrapped ImGui->GM definitions
  • imgui_impl_gm.cpp for GM backend, includes (currently unusued) GML rendering logic
• scripts/
  • ImGui/ImGui.gml for ImGui static functions, enum definitions, rendering, and internal IO/events
  • ImGui_Misc/ImGui_Misc.gml for input mapping & helper classes
• shaders/
  • shdImGui/shdImGui.fsh for clip-rect shader used by GML renderer
• tools/
  • brief/Program.js for ImGui to GM binding generation

Building

Using premake5 5.0.0-beta2, Windows SDK v10.0, Node.js v16.18.0, built with Visual Studio Community 2022

0. Use Premake5 to generate project files (vs2022 tested and working, others unknown)
1. Run copy_dependencies.bat to copy required .cpp and .h files from thirdparty/* into dll/
2. Open dll.sln in Visual Studio (support for versions older than 2022 is unknown)
3. Build for x64, resulting imgui_gm.dll file should be automatically copied to ../extensions/ImGui_GM/imgui_gm.dll and wrapped functions should be generated by brief/main.js in ImGui_GM.yyp
4. Open ImGui_GM.yyp and create a local package containing ImGui_GM (extension), ImGui (script), and ImGui_Misc (script)
5. Import local package into your game and create a controller object that calls ImGui.__Initialize() once, ImGui.__Update() every frame, and ImGui.__Render() in a draw event

Toolchain

I'm not sure if toolchain is the correct term here, but it sounds cool so I'll run with it. Here are some extra words on how the extension building works.

• Upon building inside of Visual Studio, the tools/brief/main.js script will be called. This scripts reads imgui.h to collect IMGUI_API forward declarations for COVERAGE.MD and enums for GML, it also collects any .cpp files ending in "_gm.cpp" (Any uses of GMFUNC outside of files ending in _gm.cpp will not be read) and parses out functions defined using the GMFUNC macro. These parsed functions are then added to the extensions/ImGui_GM/ImGui_GM.yy file and static methods are created in the @section Binds section of the scripts/ImGui/ImGui.gml file automatically. Enums from ImGui are also defined in the @section Enums section. You can use the various preprocessor definition to hint attributes for wrapped functions and their arguments. See brief/Wrapper.js's modifier method for how various attributes are handled.

Compatibility

Platform

ImGui_GM implements a platform-agnostic renderer via GML, which allows for ImGui_GM to hypothetically work on any platform you can compile libraries for. Development and testing has been carried out on Windows, but you could use premake to generate makefiles for other platforms (note: compiling for Linux via WSL seems to maybe possibly work, but needs more testing.)

Runtime

This extension makes extensive use of the changed static behavior in beta runtime v2023.100.0.264 and onward. Be sure to use a runtime that has these changes in them, otherwise usage may not work as expected. If you're unsure about if your runtime supports these new behaviours or not, check if the static_get function exists; if so, you're good! Otherwise, you'll likely need to upgrade (or switch to the beta). As a good rule of thumb, it's best to assume this project will be using the latest beta release of GameMaker. You can also check the .yyp file's metadata for an IDE version.

At the time of writing, the aforementioned changes to static are only avaliable on the beta branch of GameMaker; using stable builds currently unsupported

Last Updated: 1/29/2023

Notes

• Functions like ImGui.Begin may not return what you expect, see "ImGuiReturnMask Usage" for more info

• Functions that accept an array of items as an argument (such as ImGui.DragInt3, ImGui.SliderFloat2, etc) will directly modify the given array. Keep this in mind when using them. Analogous functions that accept single elements (such as ImGui.DrawInt, ImGui.SliderFloat) will not make any changes directly to the value, and the return value should be used.

• Like the above, ColorEdit4 and ColorPicker4 take the GML class ImColor (or any struct) and mutates it directly; this is worth mentioning as ColorEdit3 returns a BGR colour

• Honestly, I dunno the difference between a "wrapper" and a "bind", so you'll probably see the two terms are used interchangably

Special Thanks

• Omar Cornut for creating Dear ImGui
• rousr for creating ImGuiGML which inspired development of this
• @nkrapivin for providing general assistance with YYRunnerInterface magic
• @kraifpatrik's GMD3D11 for serving as reference on how to retrieve textures from GameMaker

imgui_gm's Issues

Selectable Item Overlap no longer works

In v1.0.12 doing the following worked totally fine:

// Create Selectable Item
ImGui.Selectable("", false, ImGuiSelectableFlags.AllowItemOverlap);

// Collapse Arrow
ImGui.SetCursorPos(posX + 4, posY + 2);
ImGui.Image(collapseArrow, global.environment.dropdowns[i]);
if (ImGui.IsItemClicked()) global.environment.dropdowns[i] = !global.environment.dropdowns[i];

However, in v1.0.13 it no longer works as expected, where the code in the if statement doesn't execute.

v1.0.14 Crashes When Changing Room

ImGui_GM v1.0.14
IDE v2023.8.2.108
Runtime v2023.8.2.152

Crash message:

Reproduction:

1. Follow the setup steps in the readme in a blank project.
2. Add another room to the project.
3. Call room_goto to change rooms.

I believe this also happens on game_restart and game_end but did not double check.
v1.0.13 works as expected.

YYZ attached in the .zip.
ImGui_GM Bug Report.zip

ImGui.Image causes a memory leak

When using ImGui.Image it causes the memory to continue creeping up by a few fractions of a megabyte per second.

Can't compile DLL

First of all, thank you for this work. But I have a problem.
I opened the C++ project with VS2022 to add the Freetype feature. By the way, this part was quite challenging. I think it would be great if some more information about the C part is given.
All files and includes are ok. But when I try to compile 'imgui_gm.cpp' is on line 98;
BufferWrite(g_CommandBuffer, (texture & 0xF) != TextureType_Raw ? texture : 0, cmd_offset);
gives some errors.

Severity Code Description Project File Line Suppression State
Error (active) E2140 expression must have integral or unscoped enum type imgui_gm E:\ImGui_GM-main\dll\imgui_impl_gm.cpp 98
Error C2296 '&': not valid as left operand has type 'ImTextureID' imgui_gm E:\ImGui_GM-main\dll\imgui_impl_gm.cpp 98
Error C2672 'BufferWrite': no matching overloaded function found imgui_gm E:\ImGui_GM-main\dll\imgui_impl_gm.cpp 98

This issue seems to be more related to libraries.

My compile settings are:
Release x64

Toolset v143
C++ standard : ISO C++ 14 standard
C Lang default (Legacy MSVC)

Missing/Unsupported Features

Missing:

• Tables & Columns
• Storage
• Data Plotting
• Value() Helpers
• Tabs
• Docking
• Viewports (not sure if this even possible?)
• Logging
• Drag & Drop
• Clip Rect
• Callbacks
• Drawlists
• User Input (kbm/mouse/gamepad, maybe not, since GM already has this)
• Fonts (glyph ranges aren't implemented at the moment)
• Shortcuts

Unsupported:

• Non-Windows platforms: ImGui_GM uses the graphics context and device from os_get_info to render draw data, unfortunately this is not provided for non-Windows platforms. Hypothetically, ImDrawData can be passed into GameMaker and handled via GML but there are some performance concerns there, and GM does not support index buffers
  Rendering via GML can be enabled with IMGUIGM_NATIVE, compiling the library for macOS/Linux is unsupported

YYC doesn't compile for LTS

Fantastic wrapper! This saves a huge amount of time.

I did notice the wrapper doesn't seem to work for YYC. I receive this error when compiling with VS2022:

Could not find function "__imgui_end_frame" in "C:\Users\<user>\AppData\Local\GameMakerStudio2-LTS\GMS2TEMP\ImGUI_GM_98112BF_YYC\imgui_gm.dll" with argument types

I know you don't fully officially support LTS versions but I'm using Runtime v2022.0.2.49 if you're interested in taking a look.

Thanks again for the great tool!

Documentation

definitely need some sort of SPA (maybe) or markdown documentation for the extension, searching through the main ImGui script is a bit cumbersome and slow

can probably work some documentation generation into the preprocessor tooling, not sure if i'd want to make my own docs code or get something off the shelf. suggestions appreciated!

Compile Time Error w/GM Long Term Stable (LTS) build

build: Long Term Stable
runtime version: v2022.0.0.12

error: Script: ImGui at line 4092 : Assignment operator expected

Keyboard inputs not working!

Keyboard does not work in any widget. Mouse left + CTRL works on sliders, but I can't type anything. It's as if all keyboard inputs were turned off. Is there a solution to this?

Edit : This happens when I compile the DLL myself in version 1.0.12. It works fine with the DLL I compiled in 1.0.11 version.

Known Issues

• ImGui uses your mouse position in the window, which doesn't translate well to the GUI layer (Fixed with v1.0.9)
• Sprites are drawn cropped (if enabled by texture packer) (NOTE: Disabling texture cropping for sprites you want to draw in ImGui fixes this problem, but I'll eventually look into changing ImGui.Image to take cropped transparency into account)
• GUI size is not reset after ImGui renders
  • The above issue has been fixed but not released as of v1.0.9, see here to find the fix (hint: swap the order of display_set_gui_size/maximize)