Create a health display with UI Toolkit

1. Overview

When you create a game with a health system, it’s almost always helpful to share key information from that system with players. When a player knows their character’s current health status, they can make choices that take that status into account; prioritizing finding health collectibles to restore lost health, for example. This information is often communicated through the game user interface (or UI).

For your Beginner 2D adventure game, you’re going to use Unity’s UI Toolkit system to create a health bar for the player character. Status display bars are also sometimes called heads-up displays (HUDs).

By the end of this tutorial, you’ll be able to do the following:

• Describe the UI Toolkit approach to user interface construction.

• Create a UI Document asset.

• Manipulate sprite assets to construct and position a health bar.

• Display the player character’s health on your health bar UI.

Working on your own project?

This tutorial is part of Beginner 2D: Adventure Game, but you might find it useful if you want to learn about creating UI to display information using UI Toolkit. For further guidance on creating UI with this system, refer to the UI Toolkit documentation.

Note: For the purposes of this tutorial, we chose to use the Ruby’s Adventure asset set, and the file paths used in instructions will reflect this. If you chose another asset set, the file names will be the same, but in your corresponding theme folder.

2. UI systems in Unity

There are two different systems that you can use to create runtime UI — user interfaces that players will see in your game. These systems are the following:

• UI Toolkit: The newest UI system for Unity, based on standard web technologies. You can structure and style the UI created with this system using similar approaches to working with HTML and CSS.

• The Unity UI package (uGUI): An older, GameObject-based UI system. You can create and configure interfaces using GameObjects and components.

Unity UI is currently still our recommended UI solution for integrating UI into a 3D scene (for example, a screen on a computer in the game) or for applying special materials and effects to UI. Your 2D adventure game only needs a visual display of the player’s health, so the new UI Toolkit system is a good fit.

3. Create a UI Document

The UI Toolkit system uses a text file asset called a UI Document to store the structure of the UI for your game.

UI Documents can be complicated to write from scratch, so the UI Toolkit system includes a tool called UI Builder that you can use to visually author the UI for your game.

To create and open a UI Document asset for your game, follow these instructions:

1. Open the Unity project for your game, if you haven’t already done so.

2. In the Project window, navigate to the Assets folder.

3. Right-click in the folder to access the context menu, then select Create > UI Toolkit > UI Document.

4. Name your new asset “GameUI”.

5. Double-click the GameUI asset to open the UI Builder window.

Note: You can dock the UI Builder window by left clicking and dragging the name tab next to the Scene view. To maximize the window, double click on its name.

UI Builder overview

The UI Builder tool functions similarly to the Unity Editor but with a very specific purpose: you can use it to create and configure the UI for your game.

There are four panels that you’re going to use to create the basic UI for your game:

• Hierarchy: This window is used to organize the hierarchy of your UI, like you organize GameObjects in the Unity Editor Hierarchy window.

• Library: This window lists the different UI elements that you can add to create your interface.

• Viewport: This window is a preview of how the UI will look in your game, like the Unity Editor Scene view.

• Inspector: This window displays the properties of a selected UI element.

4. Set the UI Canvas size to match the Game view

The viewport is currently very small; you might find it helpful to set it to the size of the Game view so you have a more accurate representation of where the UI elements will be positioned for players.

To adjust the UI Canvas size in the UI Builder window, follow these instructions:

1. In the UI Builder window, go to the Hierarchy window and select the GameUI.uxml asset.

2. In the Inspector window, use the foldout (triangle) to expand the Canvas Size section and enable Match Game View.

If you want to, you can also enable the Canvas Background section and set a different color background for the Viewport window. By default, the canvas background is transparent.

3. Save your changes.

5. Add a VisualElement for the health bar frame

Whatever set of assets you are using for your game, there are three different sprites for the health bar:

• A background panel.

• A character portrait that fits the space on the left side of the panel.

• A coloured bar to represent the character’s health.

Follow these instructions to add the background frame sprite to your GameUI asset:

1. Drag a VisualElement container from the Library window and release it over the Viewport window or Hierarchy window.

Any VisualElement can use an image file as its background, so there’s no specific element that you need to use for sprites.

2. In the Inspector window, locate the VisualElement header, select the name box, and enter “HealthBarBackground”.

3. Use the foldout (triangle) to expand the Inlined Styles section and then expand the Background section.

4. Set the Image property to Sprite using the dropdown menu.

5. Select the Image property picker (⊙), then search and choose the correct UIHealthFrame sprite for your asset pack.

6. In the Flex section of the Inspector window, change the Grow parameters to 0. That will stop your element from filling the whole height of the screen so you can set an explicit height.

Important: The frame sprite may disappear from the viewport when you set this property, depending on when you last saved your project. Don’t worry — this issue will be resolved when you configure the size and style of the element in the next step.

7. If your frame sprite is no longer visible, in the Inspector window, use the foldout (triangle) to expand the Size section. Set the Size property to 50 for both Width and Height, and use the dropdown menu to set the Type to %.

There are two different types of value you can provide to determine element size with UI Toolkit:

• A specific value in pixels.

• A percentage of the parent UI element (which in this case would be the entire viewport, as the Visual Element container is at the root of the GameUI asset).

8. Save your changes. The UI Builder window displays a small * next to its name in the window header whenever you have made unsaved updates — this will disappear when you save.

The health display frame should now be visible in the Viewport window, but you won’t see it yet in the Unity Editor.

6. Display the UI in the Game view

You’ve added the background element for your health display, but at the moment it’s only visible in the UI Builder window. To display the UI in the Game view, follow these instructions:

1. In the Unity Editor, go to the Hierarchy window. Right-click to open the context menu and select UI Toolkit > UI Document. This creates a new GameObject to display your UI.

2. In the Inspector window, locate the UI Document component, select the Source Asset property picker (⊙), and select the GameUI asset.

Tip: You might find it helpful to use the search functionality to find this asset quickly.

3. Select the Game tab to switch to the Game view — this shows the UI overlaid on the rest of your game, matching its position in the UI Builder window.

The health display frame looks great, but it’s currently very large. You’ll fix this next.

4. In the UI Builder window, go to the Hierarchy window and select HealthBarBackground.

5. In the Inspector window, under the Inlined Styles section, use the foldout (triangle) to expand the Background section and set the Scale Mode property to scale-to-fit (the rightmost icon).

This mode stops the sprite from looking stretched.

The last step is to ensure you have a proper scaling strategy if the user has a different screen size than the one you used during development.

6. Select UIDocument in the Hierarchy window. In the Inspector window, locate the UI Document component, select the PanelSettings property to highlight the corresponding file in your project, and select that file.

The Inspector window will now display all the panel settings.

7. Open the Scale Mode property dropdown and select Scale with Screen Size

8. Open the Screen Match Mode dropdown and select Match Width or Height. In the Reference Resolution property, enter 1920 for the X value and 1080 for the Y value.

You designed your UI for a 1920x1080 screen and the UI will be scaled up or down based on the ratio of your user resolution on that resolution.

This will ensure that the UI takes the exact same space on the screen no matter the resolution used, but refer to the documentation on this settings for all the possible scaling strategies.

9. Rescale the element until you’re happy with how it looks in the Game view.

10. Save your changes.

7. Configure the character portrait element

Now the background is set up! To apply what you know to add a player character portrait to its slot in the frame, follow these instructions:

1. Drag a VisualElement container from the Library window and release it over the HealthBarBackground element in the Hierarchy window. This will create the new element as a child element of the existing element.

2. In the Inspector window, locate the VisualElement header, select the name box, and enter “CharacterPortrait”.

3. Use the foldout (triangle) to expand the Inlined Styles section and then expand the Background section.

4. Set the Image property to Sprite using the dropdown menu.

5. Select the Image property picker (⊙) and choose the CharacterPortrait sprite for your asset pack.

The portrait won’t be exactly positioned in the correct space yet — this is because the elements have been automatically laid out by UI Toolkit. This automatic layout can be helpful if you want to create common user interface types like menus or grids, but in this situation it’s not helpful because you need to position an image in a very specific place.

6. Set the Scale Mode property to scale-to-fit (the rightmost icon).

7. Use the foldout (triangle) to expand the Position section, then set the Position property to Absolute.

8. In the Viewport window, resize the portrait until it fits the frame, then position it in the center of the portrait space.

9. Save your changes.

8. Configure the health bar element

There’s one vital part of the UI display that you still need to create: the bar that will represent the player character’s health as it increases and decreases.

To set up the element for the health bar, follow these instructions:

1. Drag a VisualElement container from the Library window and release it over the HealthBarBackground element in the Hierarchy window to create another child element.

2. Right-click the new element to open the context menu and select Rename. Name the element “HealthBarContainer”.

3. Follow the same process to add another element as the child of HealthBarContainer. Name the new child element “HealthBar”.

This particular Hierarchy window structure for your health bar UI means that you can take advantage of UI Toolkit’s percentage size functionality to display character health. This feature means that you can change the HealthBar element’s width to be a percentage of the HealthBarContainer element, without needing to specify a particular size.

4. In the Hierarchy window, select the HealthBar element. In the Inspector window, use the foldout (triangle) to expand the Background section and repeat the following configuration instructions:

• Set the Image property type to Sprite using the dropdown menu.

• Select the Image property picker (⊙) and choose the UIHealthBar sprite.

You should notice that the UIHealthBar sprite is now completely covering the portrait. This is because all child elements of a particular element are drawn from top to bottom, so UI Toolkit currently draws the CharacterPortrait element first and then the HealthBar element on top.

Important: The sprite for this VisualElement needs to stretch so that you can configure it to be resized based on the player character’s health level. Make sure that the Scale Mode property is set to stretch-to-fill (the default setting), not the mode that you used for the other elements.

5. In the Hierarchy window, drag the CharacterPortrait element to the bottom of the list so the bar is drawn before the portrait. Make sure that the portrait remains a child element of the HealthBarBackground element but is not a child element of the HealthBarContainer element.

6. Use the foldout (triangle) to expand the Position section, then set the Position property to Absolute.

7. The sprite might have shrunk too much. Resize the container element in the Viewport window until it fits over the area of the frame for the health bar, and position it within the frame

Caution: Make sure that you are working with the HealthBarContainer element, and not its child element HealthBar. If you select something else at any point in this process, check that you have the correct element selected before continuing and that you don’t accidentally change element alignment settings using the Viewport window overlay.

8. Save your changes.

You can now close the UI Builder window — the heads-up display is fully laid out in the Game view!

9. More things to try

If you want to further develop your skills, explore new concepts, or improve your project, check out some of the optional activities below. Each one is tagged as either Easy, Medium, or Difficult, so you can choose the level of challenge.

These activities are entirely optional, so if you’re not interested, no problem — just skip this step. We do recommend attempting at least one of them in order to get the most out of this learning experience. Good luck!

Easy: Mix and customize your assets

We’ve provided sprite assets for the health display in each asset pack — take some time to explore them all and choose the ones that work best for your vision for your own game. You can also make adjustments like changing the color of the health bar to customize the display even more, or even find or create your own assets to use for the display.

10. Next steps

You’ve created a display interface, but at the moment it doesn’t provide the player with any information. In the next tutorial, you’ll create a new script to update the display based on the player character’s health level.