Search Unity

UIElements is a new retained mode UI framework for Unity, available now as a public API for Unity 2019.1. In its current form, it’s a tool that makes it easier for you to extend the Unity Editor. In-game support and visual authoring will come in future releases.

Traditionally, building custom Editor windows and inspectors in Unity meant using IMGUI, an immediate mode API. IMGUI makes it easy to start building user interfaces but fails to scale when you’re building more complex applications. It’s also difficult for the system to optimize rendering because the user can drastically change the structure of the UI at any time within the current frame. Lastly, all UI is declared in C# which means that any future tool for authoring UI visually would need to generate C# code, which is a complicated proposition.

In UIElements, as a retained mode API, the idea is that you build your UI hierarchy of objects and let the system render it for you. This way, the system can optimize what it draws, and when it draws, leading to better overall performance. This paradigm also lets you decouple your hierarchy and styling from functionality, which results in a better separation of concerns and more approachable UI authoring for both artists and programmers.

Retained Mode

The basic building block of UIElements is the VisualElement class. All elements are either a VisualElement or inherit from it. Individual VisualElements can be parented to each other to form your UI hierarchy. Layouting, styling, and other systems then traverse this hierarchy to properly render your UI to screen.

In the Editor, each EditorWindow has a rootVisualElement property which represents the top VisualElement of your hierarchy. Elements need to be added as children to this root in order for the system to know about them and draw them.

As long as the element is in the hierarchy, it will continue to draw, update, and consume user events, without input from the developer. This is where retained mode differs from immediate mode the most. The developer only needs to declare what should happen, and when, but doesn’t need to manage the frame-to-frame rendering.

To stop drawing an element, like this slider, you can either make it temporarily invisible with a styling change or remove it permanently from the hierarchy.

Retained mode also allows for a document model that lets you separate your hierarchy (using UXML) and styling (USS) declarations into separate assets. In C#, you can focus on just binding your declared UI with functionality and data using the built-in query system and event system.

With separate assets for hierarchy and styling, authoring UI visually becomes a possibility. This will make it easier for all users to tweak, author, and design UI in Unity.

Reusable Templates (UXML)

You can assemble your hierarchy of elements entirely in C#. However, just like styles, most of your hierarchy won’t change very much throughout the lifetime of your UI. Therefore, we recommend that you modularize your UI by defining your hierarchy in a separate XML-based asset called UXML.

Tag names correspond to C# types, with full support for user-defined types inheriting from VisualElement. Attributes will be set on the new elements on creation, and nested tags will become children of their parent tag.

You can load this .uxml asset like any other Unity asset, constructing a VisualTreeAsset object in the process. You can then instantiate (or clone) this VisualTreeAsset under any element and as many times as you wish.

Getting to the elements that we just created via UXML is done via the query system described shortly below.

Shared Styles (USS)

Styles can be set directly on VisualElements via properties in C#. However, since most styles are statically defined, it makes sense to separate their descriptions from the UI logic in C#. UIElements uses Unity-specific StyleSheet assets, called USS, which uses a subset of the CSS standard. You can use the same selectors familiar from CSS to identify which elements should get which styles, while the styles themselves are key-value pairs.

You can load this .uss asset like any other Unity asset, constructing a StyleSheet object in the process. You can then assign it to your desired element and it will automatically apply the styles within to this element, as well as all its children. If children are added afterward, the styles will be applied to them as well.

While styles can be applied by name attribute or by C# type, for better style reuse you can also assign your elements one (or more) style classes and match your styles in USS by these classes. You can think of them as tags.

You can also add multiple StyleSheets to the same element and have multiple rules matching the same element. Use USS to setup complex overriding rules while reusing styles as much as possible. Iterating on shared styles, like the color of your generic button, becomes trivial – especially since you no longer have to wait for C# to recompile. StyleSheet (USS) asset changes are automatically applied in the Editor on file save.

UQuery

The query system in UIElements is called UQuery. It’s similar to its web counterpart jQuery in that it lets you find elements in your hierarchy using a combination of their name attribute, currently assigned style class list, and C# type.

You can also build a Query object for optimized reuse where you need to run a query many times on a dynamic hierarchy.

Events

UIElements comes with an event system. Events are usually sent to specific elements and then propagate down and up the UI tree until they are consumed, but this propagation behavior is customizable. Basic events, like MouseMoveEvent, are sent by the system and you can register to receive. You can also define and send your own custom user events.

Events are the main way for you to know when a state in the UI has changed or the user has performed an action. In the example below, we detect when the user has changed the slider value and display this new value in the label element.

Debugger

If your UI appears broken, or if you simply don’t see elements that should be on screen, the UIElements Debugger will be your friend. It will feel familiar to those that have used the website debuggers in Chrome and Firefox.

To debug an element in your UI with this debugger, you can enable Pick and hover over it or you can right-click on it and select Inspect. The debugger displays the full live hierarchy of the current window on the left pane and a styles inspector on the right pane. In this styles inspector, you can look at what styles are assigned to an element and where each style value is coming from (ie. which StyleSheet asset and which selector). Finally, you can live append and edit style values and see their effects in your UI.

Other Features

  • Bindings: Many controls can be bound to SerializedObjects to link the UI with your asset data. Any element implementing the IBindable interface (like all our built-in fields) can accept a string binding path to a SerializedProperty. You can then explicitly Bind() your element hierarchy to SerializedObjects.
  • IMGUIContainer: If you have a lot of existing Editor UI written in IMGUI, you can use the special IMGUIContainer element to embed IMGUI UI within a UIElements UI as just another element. The IMGUIContainer takes a callback that serves as your OnGUI() loop, receiving all the events from outside as it normally would.
  • Scheduler: UIElements comes with a simple built-in scheduler. You can use the scheduler to delay a callback a set amount of time, and/or executed it repeatedly at a set interval.

Future Releases

We’re actively working on supporting use of UIElements for in-game UI. In addition, we plan to have a visual workflow around UIElements to enable people to design and build functional UI with little or no C# coding.

In the meantime, more and more of Unity itself will be built using UIElements, including Inspectors, new tools using dedicated Editor windows, and toolbars.

We will continue to maintain, and in some cases improve, IMGUI and uGUI and we have no plans for obsolescence in the foreseeable future. That said, UIElements will become the recommended and most supported way to build UI in Unity, starting with the Unity Editor in Unity 2019.1.

How do I get started?

The Unite LA 2018 talk on UIElements is a good place to start. It comes with a sample project that you can use to follow along, highlights the main differences and equivalences between IMGUI and UIElements, and covers most of UIElements’ main features in a functional example-driven way.

You can download the example project from GitHub.

For more in-depth information on the API, see Unity 2019.1 Manual.

49 コメント

コメントの配信登録

コメント受付を終了しました。

  1. I would really like to have a visual editor for this where I can design the UI by simply placing components on an artboard without having to code the layout.

    1. Damian Campeanu

      6月 20, 2019 5:17 pm

      We are working on a visual editor. Should have something for you to try around the 2019.3 release.

  2. david limkys

    6月 3, 2019 9:19 am

    Great work, I wonder what are the reason you decided to build a new xml, css and javascript implementations instead of using html css and js allowing us to use existing frameworks?

    Also I would love a hint on when will this be possible for in game UI

    1. Damian Campeanu

      6月 3, 2019 7:40 pm

      We aim to be CSS, FlexBox, and XML complaint as much as possible. Definitely not trying to invent new languages or formats. However, in terms of implementation, we needed something that was integral to Unity and was able to run both in Editor and on all the platforms we support.

      We also wanted to freedom to not support all features of a standard, and potentially go against the standard, if we need to meet performance or usability requirements.

      As for support for game UI, we are aiming for a preview (package) later this year (2019), with full support in 2020.

  3. Kevin Karsopawiro

    5月 15, 2019 10:27 am

    Amazing progress but in my opinion the Unity team should focus on getting this system working for in-game UI as soon as possible. Since the game we’re working on is quite UI heavy we have been trying all sorts of approaches to make our UI development easier. We’re currently using the Chromium Embedded Framework that has been implemented into our game with all sorts of hackery just so we’re able to have the modularity and ease of development we needed. This UIElements system changes all that and makes our CEF implementation obsolete. No more compute heave Chromium running in front of our game. Please please please make this a priority for the sake of not just my team of developers but for all Unity developers that struggle with the current UI system.

    1. Damian Campeanu

      5月 15, 2019 3:31 pm

      In-game UI is definitely a priority going forward. Thank you for the detailed info on your pipeline. We should have something for you to try soon!

  4. Alexis Pautrot

    5月 13, 2019 8:14 pm

    “In its current form, it’s a tool that makes it easier for you to extend the Unity Editor.”
    Sorry, but I can’t see how this could be true. Node based declaration (UXML) is the worst solution when iterating a UI, a use case where IMGUI can’t be beat. And style sheets are at best a time-wasting toy for real production tools.
    I can’t see another usage than for in-game UI. But then what about the UnityEngine.UI stuff ?

    1. Damian Campeanu

      5月 13, 2019 8:28 pm

      I recommend a look at the Unite LA 2018 presentation (linked at the end of the blog above). It goes into great (probably too much) detail on how UIElements is different from IMGUI, including iteration speeds.

      As for UnityEngine.UI, it will continue to exist for a long time, however, UIElements will become the new API runtime UI once it is ready.

      1. Arnaud Jamin

        5月 15, 2019 12:02 am

        For an in game UI, UnityEngine.UI seems to fit better with overall Unity GameObject/Component philosophy. It also work nicely with the nested prefabs feature because you can now edit nested UI components. So what are the reasons UIElements will deprecate UnityEngine.UI framework for an in game UI? Thanks!

        1. Damian Campeanu

          5月 15, 2019 7:21 pm

          We wanted to have a common UI framework for both runtime and Editor. UIElements was the end result of this want and it is why we are moving forward with it for both Editor and Runtime. In addition, as we move into the DOTS world, we cannot be so closely tied to GameObjects. UIElements is independent of GameObjects or Entities (DOTS) so it can work on top of either system.

          As for the current GameObject world and prefabs, as part of our runtime support work, UIElements will enter the GameObject world and start existing in the scene like uGUI. It just won’t be exactly the same mapping as before.

          That said, UIElements does have a prefab system of sorts within, namely, UXML templates. You can embed templates within templates and override styles and attributes on them. It’s similar to the prefab system but sepcifically optimized and designed for UI workflows.

        2. Arnaud Jamin

          5月 16, 2019 12:27 am

          Thanks for the answer.
          I think you had a great workflow with UnityEngine.UI. Begin able to add UI elements in the scene view, and reference them directly in a .cs file by exposing a member is very straightforward in a good way. It makes the process very fast, and still leave the possibility to have a separation of roles (programmer & designer).
          The new workflow seems to follow the html/xaml trend. This is probably more ‘standard’ but it come at the cost of editing multiple files outside of the scene view. The editor will remove the need to edit the uxml and uss files by hand. However, using queries to find your fields is less elegant than the uGui method.
          I hope the lifetime of UIElements will be greater than uGui.
          Thanks.

  5. Damian Turnbull

    5月 3, 2019 2:54 am

    I’m really excited about this. I am hoping to build a node-based editor tool and I’d love to get my hands on the GUI code for the Shader Graph or even a demo class for node-based interfaces using UIElements.

    1. I second this!

  6. @Ashkan — Take a look at Noesis. It’s a XAML runtime for Unity. It is pretty much WPF but it works in Unity3D and it works *amazingly* well.

  7. Patrik Nordberg

    4月 27, 2019 11:42 am

    Will UIElements support SVG files, without the SVG importer?

    Thinking icons, and other graphical assets you want to have in your UI.

    1. Damian Campeanu

      4月 30, 2019 4:34 pm

      Yes. We are currently looking at SVG support in UIElements. We’ll share more on this in the future.

      1. Patrik Nordberg

        4月 30, 2019 6:35 pm

        That is great to hear. If you combine that with CSS *cough* I mean USS animations ;) then that could be really useful for in-game UI.
        Thinking it could be much easier to create a responsive UI, supporting all resolutions with crisp graphics. Just the way we’re used to browsing.

        Just out of curiosity, do you use something like chromium or other engine to render the UI, or would that be overkill?

        1. Damian Campeanu

          5月 1, 2019 10:18 pm

          We have our own optimized UI renderer that plays well with the rest of Unity’s render pipeline. UIElements will eventually be the UI system for in-game UI so we have to integrate well with the runtime.

  8. I do like how clean the fonts look in those screenshots and the revamped “maximize window button” is absolutely fabulously too!

  9. There’s a bug in your documentation for Retained Mode.

    IntSlider slider = new IntSlider();

    should be:

    SliderInt slider = new SliderInt();

    1. Damian Campeanu

      4月 30, 2019 4:32 pm

      Thanks for the note. It will be fixed soon.

  10. How can I implement my component UI without creating a new UXML?

    1. Nvm. Got it.

  11. Michael Nischt

    4月 24, 2019 10:31 pm

    Old but still great arguments for an immediate API: https://youtu.be/Z1qyvQsjK5Y 🙃

  12. Why not a WPF and XAML like thing instead of this? seriously curious to know

    1. Konstantin Khaldin

      4月 25, 2019 7:27 am

      What wpf features are you missing, exactly?
      Awkward styling?
      Obscure binding semantics?
      Ugly dependency/attached properties declaration?
      Tons of generated back code?

    2. Dave bacher

      6月 7, 2019 12:52 am

      Noesis (https://www.noesisengine.com/) has a drop-in XAML with close to the full feature set for Unity..

      If you use a XAML user control for a unit tile in user interface, a mod or DLC can copy the XAML file and add features to it – and so it’s a lot more flexible. Data Triggers, in particular, can be awesome for mods and DLC = and can be combined with Storyboards.

  13. Emil "AngryAnt" Johansen

    4月 24, 2019 1:05 pm

    Looking forward to authoring systems as a blend of this and IMGUI. Seemingly a very nice case of both worlds bestness.

  14. Christoph Dolar

    4月 24, 2019 11:39 am

    That’s _exactly_ what we’ve hoped to come along. And the main question is: when will this be availably in-game :)

    1. Damian Campeanu

      4月 24, 2019 9:51 pm

      No set dates for runtime UI yet but we should have a preview of runtime later this year.

  15. I was hoping Unity will come up with something like WPF/XAML, and yet here we are, restudy everything, again…

  16. Does it support tables?

    1. Damian Campeanu

      4月 24, 2019 9:53 pm

      No tables yet, but the capability to build your own custom elements (like tables) is fully supported. You can also continue to use IMGUI solutions for specific controls or elements that have no good equivalent in UIElements.

  17. Barış Dayak

    4月 24, 2019 6:34 am

    Perfect contents and codes . Thank you.

  18. Gotta love how so many developers love to bash on web development, and yet more and more of native desktop applications are steering towards similar paradigms to that of web development.

    1. Andrew Ackerman

      4月 24, 2019 8:05 am

      Web development sucks because it’s a chaotic wasteland of lawlessness and non-standardized practices. Take paradigms made common in web development and apply them to other disciplines and they suddenly become bearable to use.

  19. Awesome. This looks like the silver bullet, but also sounds like having 3 different systems for UI may end up being a hard to solve puzzle… some will have to let go sooner rather than later…
    On a side note, I was wondering if recent controls like Treeview will be ported to this new system?

    1. Damian Campeanu

      4月 24, 2019 9:56 pm

      More complex controls like TreeView will come in a future release. That said, there’s enough flexibility in the current public API, along with more basic controls like a virtualized ListView, that you can use to build your own TreeView control.

  20. Patrik Nordberg

    4月 24, 2019 3:12 am

    Will UIElements support the box-sizing property of CSS, with the border-box value?

    1. Russ Painter

      4月 24, 2019 8:12 am

      Hopefully Border-Box is the default. It’s the obviously sensible option which SHOULD have been the default in html/css.

      1. Christoph Dolar

        4月 24, 2019 11:39 am

        Yes.

      2. Damian Campeanu

        4月 24, 2019 10:22 pm

        Actually, box-sizing: border-box is already the *default* in UIElements (like CSS should have been). We just don’t support the actual “box-sizing” property because we ONLY support border-box.

        1. André B. Amundsen

          5月 3, 2019 11:04 am

          <3

    2. Damian Campeanu

      4月 24, 2019 9:58 pm

      We are focusing on visual UI authoring and runtime support for the immediate future. However, more advanced CSS features will trickle in over time.

  21. Nicholas Ventimiglia

    4月 24, 2019 1:40 am

    Just wow. What year is this, I feel like I have gone back in time to 2006. Im terrified of this new paradigm and how branched it is from ugui and ecs.

  22. Alan Mattano

    4月 23, 2019 9:53 pm

    So many changes and improvements. Is incredible how fast this engine is growing! Thx Unity Awesome team!

  23. Next feature – UReact ?

  24. Gustav Olsson

    4月 23, 2019 9:11 pm

    Thank you, I’ve waited a long time for something like this.