The Life of a Programmer

Search

My disappointment with Unity’s UI Toolkit

I chose Unity as it’s one of the top tools for game development, and I was growing frustrated with the limitation of my previous tools: an HTML/SVG game engine for the web. I wanted standard now, something I could rely on to do everything I needed.

As part of this, I’ll need to write a UI for my game. I looked at the Dragon Crashers demo and thought, “Wow, this looks great. I’d be quite happy with a toolkit that makes these UIs.” Alas, the elation faded as I delved into UI Toolkit. It has some significant deficiencies.

  • Structure: There’s no clear approach to connecting UXML to scenes and behaviours.
  • Responsiveness: You cannot build a scalable or adjustable layout.
  • Documentation: The API reference is incomplete and there’s no usable concept guide.
  • Incomplete: Several basic UI features are missing.
  • Bulkiness: Creating components requires lots of boilerplate code.
  • Development: This product is evolving at a snail’s pace.

Structure

It was challenging to connect my UXML, USS and MonoBehavior’s together. I could not find any reference for an intended structure.

Why is the UI Toolkit model distinct from the GameObject’s here? Everything I had only recently learned about building scenes, and connecting components and behaviours, is not transferable to UI Toolkit. There’s no Start, no Update, nor any clear component structure here.

I had to basically mirror my UXML structure in code, since I see no other way to connect components. My root element needs code to collect and call Update on key children. Is there any way to build isolated components and plug them into the scene?

The interplay between UXML, scenes, and script code is wholly underdeveloped.

I took a deep look at the Dragon Crashers demo to figure this out. It’s a classic example of spaghetti with meatballs code: objects cross-link across folders, levels, and everywhere. There’s nothing approaching the clean structure of a game scene and behaviours.

Responsiveness

I’m targeting not just the web, but also mobile, and would like my UIs to adjust to the users screen-size, or browser size. This is a fairly standard part of UI design. I know that games typically assume a more fixed layout, but there’s still some variability, and options like HUD/UI-scale are common.

I’m not a big fan of CSS, but it offers several features here. Of those, only flex-box made it into UXML. There is no substitute for these other features critical to responsive UIs:

  • Calculations: Variables are supported, yet they are underpowered if calculations are not available.
  • Media Queries: There’s no ability to respond to screen-size changes in UXML/USS. I’d have to write code to do this, coming up with my own system to pass data into the styles. Also missing are viewport relative sizes.
  • Font Relative Sizes: There does not appear to be font-relative sizes, or any base sizes. This is one of the easiest ways to do UI-scaling.
  • Layout: Other than flex-box, USS is missing grids, which are helpful for display tables of data, and perhaps lesser used: multiple-column layouts. For the layout that is provided, some key properties that are missing are gap and aspect-ratio.

The Dragon Crashes demo claims to be responsive, in a very narrow definition of the word. Sure, everything is specified in percentages, but they’re everywhere. It’s effectively a pixel-by-pixel layout with minimal adjustments to a landscape layout supported.

Documentation

UI Toolkit’s documentation is severely lacking. Primarily, there’s no kind of concept guide. I don’t know how I’m supposed to achieve any of the UI effects I want. Even something as simple as putting an image in the UI took me a while to figure out.

I could overlook documentation if there was another channel to get information. Yet, questions in the UI Toolkit forum go mostly unanswered. There are also no decent demos or tutorials.

Again, the Dragon Crashers demo is a mess. Visually it looks great, but the code structure is complex and there are no hints at understanding it. None of the documents rendered correctly in the UI Builder. It’s not a helpful example.

Perhaps coming from HTML/CSS is my problem here. Unity made UXML/USS similar, but as its feature set is lacking, it just can’t do the things I assume it could. It won’t matter how much documentation there is, if something just can’t be done.

When I started with UI Toolkit, I was motivated to write articles on how to use it. I won’t likely do that now, considering I would recommend people not use UI Toolkit.

Incomplete

I don’t need a fancy UI for my current game, but I almost immediately hit limitations with UI toolkit.

  • Grayscale: There is no way to apply filters to images in the UI. Given that the entire engine is centred on render pipelines and shaders, it is mind-boggling to not be able to do even simply visual adjustments to UI graphics.
  • Image: It took me a while to find the Image element, as well as to figure out what URL’s are supported. It appears broken, not supporting a simple thing like an automatic height based on aspect ratio — perhaps another point against responsiveness.
  • Game Objects: I want to present one of my game objects in the UI. Nope. It’s just not supported. Or rather, it looks like if I do lots of manual processing and trickery, maybe it might work.

Those are what I’ve encountered so far. Looking at the docs I see a terse list of USS properties, and a virtually non-existent list of element types: nothing like ul or table, or inline text rendering. It looks like any high-level component, such as scrolling panels, will need custom programming, if it’s even possible.

Bulkiness

Exposing a custom property in a Unity script is easy:

public Sprite hexTile { get; set; }

Then I just drag the desired object onto this field in the inspector. Simple.

In UXML, to create a property for a custom control, I need to write something like below.

	public class StackTraits : VisualElement.UxmlTraits
    {
        UxmlBoolAttributeDescription center =
            new UxmlBoolAttributeDescription { name = "center", defaultValue = false };
            
        public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
        {
            base.Init(ve, bag, cc);
            var sh = ve as StackElement;
			sh.center = center.GetValueFromBag(bag, cc);
        }
    }	

	private bool _center;
	public bool center  { 
		get { return _center; } 
		set {
			_center = value;
			...
		}
	}

Compare the simple MonoBehaviour approach to this UXML approach. Do you see a difference?

I don’t know what happened here, but this is preposterous.

Development

I expect new systems to have some rough edges. I’m willing to deal with quirks and oddities, knowing solutions are on the horizon. But UI Toolkit isn’t new. It comes from UI Elements, which was first released in the 2018 version of Unity I believe.

I know UI systems are hard to develop. I’ve done a lot of UI work over the years, including a cross-platform GL-based, UI system, in CSharp, for Fuse. Yes, it’s a lot of work. But UI Toolkit has been around a long time now, and it doesn’t even provide essential features yet.

This worries me a lot. I’m leaving HTML/SVG because of a lack of improvements to the core platform, and bugs that will never be fixed. With UI Tookit, I feel like I’m jumping back into the same situation.

Unity says this is the future of UI, but they have not supported that with development effort.

Conclusion

I haven’t looked yet at animations: I couldn’t face the disappointment if they look like CSS animations. Animations in CSS are riddled with problems and a prime motivator for me to run away from my current web engine. Dare I look?

I also wonder about performance. Flex-box style layout has troubles with dynamic changes, forcing global recalculations for even minor changes anywhere in the tree. We did a lot of work at Fuse getting this performant. CSS style changes also end up doing global recalculations; their performance has been a major development point for major browsers. Though solvable, these are challenging problems. I have my doubts, since the team behind UI Toolkit hasn’t solved the basics yet.

Unless I stick with a trivial UI, and forgo basic features, I cannot use UI Toolkit in my games. I feel as though Unity has misled me. How can they promote this as the future of UI? It’s not in a usable state, nor are they properly investing in it.

Please join me on Discord to discuss, or ping me on Mastadon.

My disappointment with Unity’s UI Toolkit

This newest UI offering from Unity is fraught with problems, resulting only in frustration rather than good interfaces.

A Harmony of People. Code That Runs the World. And the Individual Behind the Keyboard.

Mailing List

Signup to my mailing list to get notified of each article I publish.

Recent Posts

Search