Eyas's Blog

Occasional musings on software development, tech, the Middle East, and anything else.

Unity Short: Building User Interfaces

Usage RightsPhoto by KOBU Agency

For the third and final “short” of this week’s Unity for Software Engineers, I give an overview of building in-game User Interfaces in Unity. As a reminder, this week’s installment is packaged as a series of short-form outlines, introducing readers to the breadth of the Unity toolkit.

Just like rendering and the Input System, Unity has a few technologies that can be used to render UI in a game. Unity’s documentation includes a comparison of these UI toolkits. Of these, only two technologies can be used for in-game user interfaces. We’ll discuss these here:

  1. Unity UI (sometimes UGUI) is the mature, GameObject-based UI system in Unity.

    It is included by default in every Unity project in package form (com.unity.ugui).

  2. UI Toolkit (sometimes UIElements) is the next generation UI system, inspired by HTML, CSS, and flexbox.

    While a basic form of the toolkit is shipped in every Unity Editor as part of the core editor experience, using the toolkit requires the com.unity.ui package. com.unity.ui is currently still in preview.

Which Toolkit Should I Use?

Using the UI Toolkit for runtime interfaces (as opposed to custom editors, etc.) is still pretty new and not yet well-documented. I would only recommend the UI Toolkit for:

  • experimental projects where you want to learn something new,
  • you have a tolerance for reading forum posts in lieu of proper documentation,
  • you’re comfortable with Unity already, and
  • you are eager to use constructs from HTML, CSS, and flexbox in your Unity interfaces.

For any serious project, or in all experimental cases where you don’t want to waste a few days pulling your hair, Unity UI remains the best option here.

Unlike Unity’s various render pipelines or the input system, Unity’s various UI toolkits are not mutually exclusive. You can render a HUD in a canvas using UGUI and your main menu in the UI Toolkit.

Unity UI

Unity UI (UGUI) is GameObject-based. If a regular UI is represented in a node tree describing a document object model, a UGUI UI is represented in a nested tree of Game Objects.

To get started with UGUI, create a Canvas in your scene. While a canvas will be rendered as a huge flat rectangle within the 3D scene view, the Canvas will by default only render in screen space when the game is running.

More details about Canvas

Layout and Positioning

Every Game Object under a Canvas will show a Rect Transform instead of a regular 3D Transform. The Rect transform UI allows you to define the layout of your object and its nested objects.

You can insert empty GameObjects within your tree hierarchy to define specific layout groups, just as you might with an empty <div> in HTML.

More details about Layout

Individual Components

Within your layouts, you can have various UI components. Particularly, Text and Image.

Before using Text, it is recommended to install the TextMeshPro package, as it dramatically improves text rendering.

More detail about Visual Components

Binding

Text and Image components can be controlled by C#, just as you would normally. There’s nothing special about UI bindings; instead, you can create a C# component that takes a reference to an Image or Text component and sets/updates various values on that component.

For example, see this step-by-step article on Health bars in Unity using raw sprites and Image.fillAmount.

Closing

Writing UI in Unity can be cumbersome if you’re used to more modern reactive tooling, but it gets the job done. UGUI is GameObject-based and thus is relatively easy to reason about. The UI Toolkit allows you to use UXML and USS (similar to HTML and CSS, respectively) to define and style interfaces, but bindings and runtime instantiation are still cumbersome.