[Released] NimGui, a 1 Draw Call Immediate Mode GUI for Unity

NimGui stands for Nimble Immediate Mode General User Interface and is designed to be a replacement library to Unity's runtime ImGui.

I have always found Unity’s runtime ImGui solution to be lackluster and displaying any kind of widgets on runtime is just too annoying to get it setup easily. Similarly, with Unity’s UGUI solution, there’s too much set up required in order to display some information or set up widgets to tweak values in your game. While Debug.Log is extremely useful, when debugging many pieces of information it can be difficult to search through and contextualize information.

This framework was designed with performance and simplicity in mind, so you can focus on drawing widgets to interact/display/debug information while developing your game.

Asset Store Link
Grab it on the Asset Store.

Features

• Supports builtin render pipeline and URP
  • Built for Windows, Mac, Linux, & WebGL
• Simple immediate static API to draw widgets
  • Draw Scopes via using pattern to begin and end areas (see the API Example below!)
  • Write GUI naturally in MonoBehaviour.Update() and DOTS’ SystemBase.OnUpdate()
• High performance
  • Utilizes C# Job System & Burst Compiler
• A library of built widgets
  • Box
  • Button
  • Collapsible Area
  • Dropdown Menu
    
  • Label
  • Line
  • Pane
  • Progress Bar
  • Toggle Button
  • Scroll Area
  • Slider (float & int)

Limitations

• Static APIs cannot be called from separate threads simultaneously
• Static APIs cannot be called from LateUpdate as this will throw a warning in the rendered UI
• Static APIs can be called from FixedUpdate but will only appear for a frame as UI gets updated every frame and FixedUpdate does not
• Does not support the new InputSystem yet

Performance

NImGui can process 250 widgets in 1 millisecond on the main thread in the Editor. On a build, you can expect it to take 0.4 millisecond instead. This is achieved via multithreading using Unity’s Job System and Burst Compiler.

These stats were recorded on an Intel Core i7-7700HQ @ 2.8 GHz. More stats will be collected across varying hardware and operating systems.

Versions Supported

• Unity 2020.3 LTS
• Unity 2021.1
• Unity 2021.2

Dependencies

• Unity Collections
• Unity Jobs

API Style

The API follows an immediate mode style. Here is an example of the API you would be writing:

Code (csharp):

1.  
2. using (ImPane pane = new ImPane("Sample Pane", new float2(500), new float2(500))) {
3.    if (pane.IsVisible) {
4.        var t = Mathf.PingPong(Time.time * 0.5f, 1f);
5.        ImGui.Label("Here's an example of drawing panes and widgets");
6.        ImGui.ProgressBar(t);
7.        ImGui.Dropdown("Dropdown", options);
8.  
9.        if (ImGui.Button("Click me to toggle")) {
10.            showMsg = !showMsg;
11.        }
12.  
13.        if (showMsg) {
14.            ImGui.Label("Message shown!");
15.        }
16.  
17.        ImGui.Slider("Int Slider", 0, 10);
18.  
19.        using (new ImScrollArea("Scroll Area")) {
20.            using (ImCollapsibleArea group = new ImCollapsibleArea("Group")) {
21.                if (group.IsVisible) {
22.                    if (ImGui.Toggle("Show Box")) {
23.                        ImGui.Box(300, Color.red, true);
24.                    }
25.                }
26.            }
27.        }
28.    }
29. }
30.  

This would produce an output like so:

Demo

The demo can be tested at the following link on itch.io:
https://initialprefabs.itch.io/nimgui

Immediate Roadmap

The first version of NImGui is expected to be released at the end of 2021/early 2022 as there are few things that I need to finish such as:

• escape characters support in the Label API (for new line and tabs)
• Textfield API
• Support Unity’s new Input System
• a browsable API / docs website
• LateUpdate support for drawing widgets
• One draw call UI (right now each widget drawn will issue between 1 to a few draw calls)
  • This may also allow me to shift away from using TextMeshPro materials as it is a current dependency

Longer Term Goals

• RTL language support
• Complex text layout support (e.g. support for Arabic, Khmer, Thai, etc)
• Command Buffer like API for dynamic widgets and panes & multithreading support
• Stateful FixedUpdate support (e.g if you need to debug netcode which will run on a Fixed Timestep, it will make sense to store and display the information until the next Fixed Timestep)

Documentation
​

Initial feedback and questions are welcomed! Feel free to comment in this thread below.

 

Thought I'd post a new update since it's been two weeks since the last time I made this post (I can't guarantee that I'll be posting an update every 2 weeks but I'll try).

I decided to remove my dependency on TextMeshPro. TextMeshPro is great but there were some problems I ran into:

• TextMeshPro materials had to be dilated in order to remove jaggedness (there's some setting that I haven't figured out and going through TextMeshPro source code is a pain).
• TextMeshPro did not generate glyphs for certain characters despite the Font actually supporting the character
  • This made it almost impossible for me to aim for a 1 draw call UI.

So what replaces TextMeshPro?

NimGui has its own SDF Font Texture generator and is based off of the AntiAliased Euclidean Distance formula by Stefan Gustavson: https://weber.itn.liu.se/~stegu/edtaa/ (MIT license will be included in the source file where it's used).

See the sdf_texture.jpg attachment below for an example.

With the underlining font rendering system replaced, what are the limitations that come with it?

• Unfortunately, this means that you cannot load new fonts and render multiple fonts. You can only have 1 font loaded in at a time as the shader is extremely simple and only takes in a single texture.
• The SDF texture generated by NimGui takes up more space than TextMeshPro. There is no texture packer to make the texture more compressed.
• Loading in custom images will no longer be supported.

However, despite these downsides, I am now able to render everything in 1 draw call, which reduces the complexity in building the mesh as well the command buffer that will render the content.

1 Draw Call UI

However, with these changes, I cannot take advantage of hardware scissoring so scroll views will need to be reworked such that content is interpolated and clipped if it is out of bounds. This will be my immediate step after finishing converting widgets such as Sliders.

 

Hey all, another update!

With the change to a 1 draw call UI, hardware scissoring was no longer supported. This meant that I had to write my own "software" scissor technique which allowed me to cull content that is out of view (which is very useful for scroll areas).

Right now the implementation is based off interpolating UVs to the correct value when vertices are culled out of view. This ensures that glyphs that are rendered are not compressed in a limited space which would cause each glyph to look distorted.

For performance stats, I'll need to optimize software based scissoring, right now for 6k vertices, software scissoring takes 0.5ms on a Core i3-8100 @3.6GHz. Without software scissoring, the job takes 0.15ms to run, so we can see that software scissoring makes the job run 3x longer.

As for next steps, I'll continue and move onto implementing Textfield.

 

Hey all,

Here are some updates with ImGui. First and foremost:

Optimization
For 6k vertices, software scissoring originally took 0.5ms to run. Without software scissoring, the job originally takes 0.15ms to run. This is pretty much a 3x performance lost. To improve the performance, after some optimizations on the Bursted Job, it now takes approximately 0.35ms to perform software scissoring on all vertices.

Some further optimizations I can do include:

• Only scissor vertices when scissor rects are introduced
• Use an approximation of the sqrt to produce fewer assembly instructions when interpolating

If software scissoring is not an option, I'll consider offloading it the GPU, however I would like to keep the SDF shader extremely simple.

Textfield
The Textfield API is pretty much functional with western based languages. RTL and complex text layout is not supported yet and is on my todo list in the near future.

You can input text via keyboard and press or hold backspace to delete text. See the gif below:

Next Steps
The Textfield API needs some cleanup and additional features such that you can move the cursor and insert characters in the middle of the textfield and be able to highlight. I'll also explore complex text layout such that I can plan for additional changes to the logic / API.

After that the base API is pretty much done, so I'll be updating the documentation and demo.

 

New updates from the recent week.

TextField API

TextFields are primarily done and backspace detection is done using Unity's Input.inputString. (Instead of using Input.GeyKey(KeyCode.Backspace) variants, I check for a \b to see if the user has pressed backspace.) To help GC load with string generation, I'm considering that instead of returning a string type, the TextField will write to an allocated StringBuilder. This will have a lighter load to C#'s garbage collector.

Project Cleanup

TextMeshPro is finally removed from the library! This means NimGui officially uses its own SDF texture generation & SDF shader. The SDF shader is kept as simple as possible therefore it does not implement all features presently found in TextMeshPro.

Documentation

Documentation is updated to reflect an additional step in the installation process. This involves opening the Setup Wizard and clicking the Add Shader button, which will add the SDF shader to your graphics settings' Always Included Shaders.

The Setup Wizard attached below, although extremely simple for now, will also include a hyperlink to the documentation.

Next Steps

• Switch TextField to take in StringBuilder that the developer allocates themselves to lighten the GC Load
• Update the Setup wizard to include a link to the documentation
• Allow the Setup wizard to appear on project open & provide users with a way to disable the auto popup after start.
• Update documentation on workflow when introducing new fonts & the limitations that it has.
• Begin researching into complex text layout

 

Hi all another update.

I've been busy doing some clean up to the amount of padding widgets have and migrating the documentation from originally, mdbook to DocFX because generating the XML API documentation to work with mdbook wasn't a good idea.

The link to where the documentation currently lives here.

Inline code documents will be picked up in your IDE of choice, although inline code examples vary in how they are rendered per IDE. (Please see the attached image below.)



The screenshot above is based on the following snippet

Code (csharp):

1. /// <summary>
2. /// Returns the current state of the Toggle box. If the box is checked, then
3. /// the state is true, otherwise returns false.
4. /// <remarks>
5. /// The control ID is useful for pruning cached global states. You only need to
6. /// prune when you are no longer using the Toggle functionality.
7. /// </remarks>
8. /// <code>
9. /// class UIBehaviour {
10. ///     uint toggleID;
11. ///     // Gets called once per frame.
12. ///     void Update() {
13. ///         if (ImGui.Toggle(out toggleID)) {
14. ///             ...
15. ///         }
16. ///     }
17. ///
18. ///     ~UIBehaviour() {
19. ///         // Internally this will remove the cached Toggle state from
20. ///         // it's internal hashmap, when this Object is destroyed.
21. ///         ImGui.PruneToggle(toggleID);
22. ///     }
23. /// }
24. /// </code>
25. /// </summary>
26.  

Next Steps

Over the next few weeks, I will be continuing updating the documentation by swapping some still images with gifs (as I think gifs will get the purpose across better with interactive widgets), updating docStrings with code examples, and cleaning out the API.

I'll also need to start prepping for asset store and itch.io release.

 

Hi all,

It's been roughly 3 weeks since I've last posted and there are a few updates I can provide:

WebGL Issue
I have disabled WebGL builds at itch.io temporarily until I can solve the the performance degradation on WebGL. Before making NimGui 1 draw call I have been exclusively using bursted

IJob.Run()

to build the UI. I may have to write preprocessor defines to make sure that WebGL exclusively uses

IJob.Run()

instead of

IJob.Schedule()

.

I have provided demo builds for Windows, Linux (Ubuntu 20.04), macOS (Intel only) on the itch.io page. Please feel free to download them and test out the UI. Initial feedback is welcomed!

Itch Link: https://initialprefabs.itch.io/nimgui

TextField
I forgot to add text slicing on textfields so I will need to address that and add it in before finally pushing it to the asset store. This means that you can continuously type and the text will wrap to the next line, which is not desired behavior.

Overall, I think I can say I'm 85% done with the first major release of NimGui. Documentation is updated and currently reflects the most up to date information on how widgets are used.

Documentation: https://initialprefabs.gitlab.io/imgui.book/

 

Hi all,

Another week, another update.

Textfield Fixes
Textfields properly slice off characters that are off screen. This means as you keep typing many characters, the textfield will not show the characters at the beginning of the field.

Documentation

• Documentation for Textfield has been updated to define limitations.
• Broken links within the documentation site has been fixed.
• Added information about pruning and cleaning up internal cached IDs.

Documentation Link​

 

Apologies for the month long silence. Post 2021 end of year break had me pretty busy and I didn't have enough time to wrap up the documentation and finishing up the asset store release.

Some minor things I had done since the past month is migrate the current documentation over to a new site, nimgui.initialprefabs.com. I'll need to grab statistics and create a more public facing demo hosted on Github (which will involve me using BoatAttack to demo what NimGui can be used for). This won't be embedded in the unity package as the package will just have a NimGui widget gallery showing all the available widgets currently supported.

 

Apologies for the lack of updates, I've been pretty busy with work so I haven't had the time to update NimGui outside of a few minor bug fixes.

 

Hey all,

Here are some updates to NimGui which have been put off during my 2 month hiatus. First, the collapse and close buttons are clickable relative to the order of the pane being rendered. In the video below, if the Stats pane is rendered on top, then the collapse and close buttons are clickable, instead of the Widgets Gallery window.

Input System
NimGui now supports Unity's Input System. If your project uses Input System as its backend, then NimGui will strictly use it for all inputs. If you use the old Input Manager, then NimGui uses the Input Manager and polls the inputs each frame. If you happen to use both, then the Input Manager will be the default input backend.

Post Processing
Any post processing that will cause a Final Blit Post Processing pass in SRP will ultimately affect NimGui. Using the BoatAttack demo as a baseline when creating a demo made this painfully obvious. One possible solution is for me to create a derivative of URP that is backwards compatible and introduce a new RenderPass + Subpass that composites NimGui as the final image. I had asked around the forums to see if this was possible but I haven't gotten much of a response so I will try to solve this issue sometime in the future.

https://forum.unity.com/threads/extending-urp-with-additional-subpasses.1235923/#post-7875304

Ultimately, introducing a new RenderPass/SubPass would allow me to separate NimGui's rendering from the main render loop, similar to how UI Toolkit and UGUI are rendered.

That said, I will look into hosting binaries on Github which will provide a demo of the Widget gallery instead of integrating NimGui into BoatAttack.

Documentation
Documentation for the Input System can be found in the Installation section, which details the same info above.

Next Steps
With these minor fixes, I will be moving onto grabbing screenshots and filling out the Asset store info. The same info will be submitted to itch io also. Once that is done - I'll make a forum post on when it's submitted.

Happy deving and thanks for the patience.

 

With Entities 0.50 released on the package manager, I'll be on the look out for the other dependency updates and see how it affects NimGui in the coming weeks.

 

NimGui is compatible with Entities 0.50. Although the static API works nicely with SystemBase's OnUpdate, if you're looking for Bursted System support, that won't come until the future. There are still managed object that need to be accessed with NimGui, but I can look into a fully Bursted API if there is enough need for that (the priority right now is just really low).

 

WebGL

Some additional updates I'd like to point out is: WebGL build will also work, however to achieve a higher frame rate you must validate your memory allocation settings in your player settings. Current settings I am using in the screenshot below are:

• Initial Memory Size: 32
• Memory Growth Mode: Linear
• Maximum Memory Size: 2048
• Linear Memory Growth Step: 16

Your mileage may vary, however these are the settings that I found worked as the problem I had to debug was more of a memory allocation problem more so than a runtime performance operation.



More Fixes
Some more fixes that will be in the initial release of NimGui are:

• Added a Linear to Gamma color conversion as NimGui was built with Gamma Color Space initially. This will prevent a washed out color if you happen to use Linear color space. NimGui will automatically convert the color space depending on the QualitySettings.activeColorSpace. See the screenshot below.
  
  
• Dropdown menus will respect that it is overlapping an element so that interactable widgets behind the menu will not be interacted with. (Similar to the collapse/close bug).
  

 

Thanks for the patience everyone!

Everything has been submitted to the Asset Store! The NimGui Itch page is live, however once the Asset store listing goes live, I will list the Itch version also.

 

Hi all!

NimGui has been approved and released to the Asset Store and Itch! Thanks so much for your patience, I'll be continuing to support NimGui for a while as it is my active daily GUI I'm using as I build things out in Unity Entities, so I'll be fielding for feedback.

I'll have some external demos in the coming weeks of other integrations I will be doing with Entities and NimGui that I've been slowly working on in the background.

 

Hey all,

Immediate Steps

I've got some early feedback in making the setup for NimGui much easier which I've posted an issue here:

https://github.com/InitialPrefabs/nimgui/issues/2

While the setup and installation process is all documented here it's worth making the setup extremely obvious per supported render pipeline.

This will be an editor only check to not affect a built game's runtime.

Next Major Steps

The next major feature I would like to work on is world to screen space drawing so you can reference a point in world space but draw it within the screen. This would be great for widgets such as the Label and Progress Bar (think of a health bar or displaying some some values next to a character or object. As always I'll try to post screenshots of update to this thread.

If you have any requests for this feature let me know, so I can consider it and figure out how to architecture it.

 

Hey all,

NimGui 1.0.1 is released which provides a 1 click setup for all of your URP RenderPipeline Assets. You will still need to add URP_ENABLED to your scripting define.

For an example of the 1 click setup please see the video below.

Documentation has also been updated and can be viewed online here or in the PDF when downloading the package. For visbility, the issue can be viewed here: https://github.com/InitialPrefabs/nimgui/issues/2

I am currently working on issue 3 & 4 which is due to some initialization issues with Domain Reload & how Unity initializes the InputSystem.

 

With DOTS 0.51 out - I'll be updating NimGui to support it.

 

Changes to NimGui to support Collections 1.3.1 and 2021.3 LTS have been submitted for review to the Asset store.

 

Changes have been published to the Asset Store with dependency updates for Collections 1.3.1 and 2021.3.4 LTS

 

I got a problem, why the character 's' is in the third line? just as the picture showed as below. The character 's' is flashing, sometimes it was in the same line with the second line, but sometimes it jump to third line.

Unity 2021.3.4f1c1 and I use the DOTS Framework

here is my code

Code (CSharp):

1. ImGui.Label($"{World.DefaultGameObjectInjectionWorld.GetExistingSystem<FPSSystem>().curFPS} FPS", in textStyle);
2. ImGui.SameLine();
3. ImGui.Label(notification, in textStyle.WithColor(Color.red));
4.  
5. var data = GetSingleton<AccTimerData>();
6. ImGui.Label(data.seismicName.ToString() + " | " + $"Time: {data.elapsedTime:0.0}s/{data.seismicFinishTime:0.0}s", in textStyle.WithColor(DefaultStyles.Text));
7. ImGui.Label($"PGA: {data.curPGA:0.0}g", in textStyle.WithColor(DefaultStyles.Text));

Could you please give me any advises, thanks

 

Hey sorry, this is a bug with the text layout engine. I've been meaning to rewrite it to make it more accurate with how scopes are handled. I can't give an ETA on when it will be fix as I have been pretty busy with work these past couple of months.

It is very likely that I may have to compute and round the size of the text/scopes to the nearest integer instead of a float to make it more deterministic/accurate.

 

OK, fine, this problem is not very emergency for me now. And I have another question, can I change the button or dropdown and anything else's state according to code, such as set button true or false, or change dropdown current index.

 

There is a way to update the state internally for toggles/dropdowns. I'll need to take a look at the source today and point you in the right direction. They're likely internal variables so an assembly definition reference might be needed to expose them publicly to other assembly definitions.

 

If you want to change the state of a widget programmatically like a dropdown menu, they are stored in the ImWindow.UnmanagedWindow. This is an internal variable, so if you would like to create some safe bindings, I would create an assembly definition reference and expose the following pointers under the "Behaviour States" comment as references from the ImUnmanagedWindow struct.

This can be found between line 119 to 135 in ImWindow.cs.

For additional reference with dropdown menu, you can look at line 159 in Dropdowns.cs. This is where the dropdown fetches the last known state of itself and knows which option to correctly place the dot.

 

Great, thanks a lot

 

Hey all,

With Entities 1.0 out as a preview, I'll be taking a look at NimGui and migrating some of the existing Job API to use IJobFor and checking for any compatibility issues.

 

Hey all,

An update with NimGui and some upcoming changes!

What's currently in progress right now is HDRP support which I'm currently struggling with as I'm trying to figure out how to inject the renderpass nicely into HDRP's renderpass (thread here if anyone is interested - if I can't figure it out before GDC - I'll likely defer progress for HDRP support).

Fixes

• Words will not be broken apart when the word cannot fit on the line (text layout fixes)
• Duplicate vertices are removed reducing the # of total vertices and indices in the mesh in the final draw call

New Widgets
Password Field - let's you type a hidden input


Table - allows you to layout a series of a data automatically into a grid format


Lastly, there is a MenuBar which allows you to register actions and toggles allowing you to execute functions or show/hide things.


These features are currently being developed against 2022.2.5 and Entities-1.0.0-pre.15. The update will either drop before Entities 1.0 is officially released or roughly the same time. I'll be updating the website pretty soon to include these new widgets and changes.

 

Great work! Really liking the framework and excited for the new features… but as long as it does not work with domain reload disabled I cannot use it in our projects (I would love to use this for debugging overlays and menus). Any news on fixing that issue https://github.com/InitialPrefabs/nimgui/issues/3 ?

 

Oh let me take a look at that issue again, can you send me a screenshot of your domain reload settings so I can give it a try. (Apologies, I've been on and off with NimGui support, will be putting this on my immediate queue tho!)

 

Sure, attached are the settings I use in our projects. Mind you I could not get it working with URP in a new project so this is with the BRP (tried 2021.3.18 LTS and 2022.2.6).

 

Thanks I'll go check it out.

 

So the demo works with the version on the asset store for me with the settings you've provided. Do you have a min repo that I can take a look at?

Also what version of NimGui are you running? Version 1.1.0, that's provided on the asset store? I can definitely get the issue with domain reload turn off with version 1.0.0. I haven't been able to reproduce this with my local tests on 2022.2.6 & 2021.3.18.

Also I'm a little curious on what broke for URP (was it the same issue or was something not rendering?)

 

Hope the code can run in burst.
And can you add a Time New Roman font to the default? I use the font generator with this font, it displays strange, some characters were display right, but some characters are display horizontal.

 

I have some plans converting it to be Burst friendly with ISystem structs, but it's a bit of an undertaking and I'll likely do this after Unity officially releases Entities as I need to remove some classes and turn them into structs with pointers.

As for the font issue - I'll have to take a look at that. I haven't seen that issue yet. I'll open an issue for this on Github.

 

I made a small project can display the error, I don't know whether it caused by wrong parameter or other problem.
But I will very appreciate if you can give me any advice.

 

Thanks for the min repo - will try to take a look in the next few days.

 

I took a look at the issue and can reproduce it. Now the issue I'm seeing is the uv coordinates reported back by Unity's text engine which is causing the text to look sideways.

Now there are a few options I can try to solve this:

1. Try to force Unity's text engine to give me back the correct UV coordinates, but this is starting to be a bit of endeavor when working on it today. Will continue to see if I can get it to work correctly this week otherwise I will consider option 2 and 3 instead.
   
2. I can opt for a different technique and use msdf texture generation instead. This makes the text much more crisp and actually compacts the glyphs. This route looks more promising but needs a bit more investigation and looks like it will only initially support Windows first (as I need to compile and make sure it works for OSX and Linux too)
   
3. I can opt to use TextMeshPro's textures, but truthfully I'd like to avoid using TextMeshPro as a solution as it was pretty hard to get working correctly and browsing its internal source code is a bit confusing.

 

Just an update I'm looking to using msdf texture generation to replace the old texture generation (windows will have support first, the old texture generation will still exist alongside the new version, but will eventually phase it out).

 

This looks nice. I'm currently making a VR game where we're using an extensive debug menu using simple OnGUI and we would also like to be able to use this in world space on the player's wrist for example, so you can use the same debug tools in VR, without having to write the same code twice for regular UI. Can this asset do this?

 

I don't have support for world space UI. It's on the queue but I won't be tackling it yet immediately. As for VR, this will most likely not work, I'd have to change up how I draw the UI because it uses an orthographic projection in order to draw the UI in "screen space," and VR has 2 screens I'll need to draw the elements to.