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