UI Toolkit at runtime performance vs Canvases

I’m learning about UI Toolkit, and my use case typically involves a lot of elements that are to be displayed over other entities in the scene as each entity moves around.

Think targeting brackets, and other visuals like status effect icons, and even clickable buttons.

I understand how to do this with canvases, but UI Toolkit has been a little frustrating and I’m wondering if this isn’t really how UI Toolkit was intended to be used. And if that’s the case, is this likely to result in poor performance?

Anyone have some insight here?

You should be able to get very performance if you set the DynamicTransform hint the the elements that move around. This will allow UI Toolkit to transform these elements on the GPU, otherwise all the transformations happen on the CPU by default.

Can you elaborate on which parts you find frustrating? UI Toolkit is definitely designed to handle these use-cases, but there may be some hiccups that we can help you with.

1 Like

Your tip about DynamicTransform was very helpful, thank you.

I read some cautions about some devices not being able to handle many of these. Is this to suggest that other methods might be better (canvases, quads), or are they just going to be similarly limited too?


As far as frustrations, the current API documentation is very minimal and bereft of code usage examples once you go past the surface layer.

Maybe it’s my use cases, but the first things I ever need are:

  • Elements positioned in relation to GameObjects
  • Elements that reflect game information
  • Buttons that do things.

Everything else is secondary. I don’t need a 30 minute tutorial to show me how to align bold text in the center of the screen or what padding does. Without initial learning bits directly related to my use cases, I find there’s no good mental framework to slot new information into. Maybe that’s just me.

Looking up information has been frustrating because there’s also a lot of ambiguity if the information pertains to the editor or runtime, or if is outdated (Including “runtime” in a google search doesn’t help much.) Several times I’ve found myself puzzling over a tutorial only to find it isn’t for runtime.

I know there’s some crossover, but just not much in my 3 initial use cases.

For example:

The first thing I saw was Unity Learn: UI Toolkit - First Steps
Ok, I guess I gotta start somewhere. And it’s for the editor - not what I’m after. But then there’s nothing. No links to other areas, no way to back out to, say, a table of contents about UI Toolkit.
I tried searching for “UI Toolkit Runtime” which leads me right back to the same tutorial that’s definitely not about runtime.
So I tried to search with google: Ah ha! Unity Learn - UIElements, sounds promising: “Sorry, this learning content is no longer available.”

I’ve gathered that UI Toolkit is somehow based on a thing called FlexBox. But looking up that yields a lot of ambiguity too. (FlexBox 4 Unity? References to paid assets? Oh, I see, it’s depreciated. This kind of noise is distracting.) And I’m pretty sure learning about FlexBox is not a path to my first 3 requirements anyway.

Getting an element to visually appear over a GameObject was a wild ride because using transform.position is wrong, and VisualElement.style.width (and similar) can’t be read from. Instead it’s VisualElement.resolvedStyle.width, which I found on accident.

Now, I’m seeing conflicting information on how to make a button do something.
Some things use RegisterCallback
And others use event handlers that look like delegates.
There was another way too maybe, but I think it’s for extending the editor.

Is this just because some things are out of date, or…?

1 Like

I wouldn’t worry about these limitations since they only appears on (very) low-end devices running the Mali-400 family of GPUs. It’s very rare to find these devices “in the wild” and when we do, they aren’t used for gaming. Furthermore, we expect Unity to deprecate support for these devices (running GLES2) in the short/medium term.

In terms of how to use UI Toolkit, there isn’t much difference between editor and runtime, so any editor-specific documentation will probably be useful for runtime as well. The main difference is mostly about how you hook yourself in an EditorWindow for editor work, or on a GameObject for runtime using UIDocument + PanelSettings.

That being said, I understand your frustration. UI Toolkit evolved a lot in the past years and there is definitely some outdated documentation out there. I’ll forward your feedback to the team, this is certainly something we are working to improve.

In the meantime, this blog post might be of some help:
https://blog.unity.com/technology/ui-toolkit-at-runtime-get-the-breakdown

Hi again, here’s some more runtime UI Toolkit documentation that we released recently, hope this helps as well: