All content in this course uses:

Make a Health Bar with UI Toolkit

Creating a good user interface (UI) for your game helps to add a level of polish to your application as well as convey important information to the player. In this tutorial, you’ll harness the power of Unity’s UI Toolkit to display a health bar in the provided support project.

UI_toolkit-support-project.zip

In this tutorial, you’ll learn the basics of how UI Toolkit works and how to create a health bar using it. This tutorial uses a support project that contains a very simple game you will implement the health bar for.

Overview

To follow this tutorial, you need to have an understanding of how Unity works, what assets are, how to create GameObjects, and how to add components to them.

You’ll also require some basic knowledge of programming; you should know how to create scripts, what functions are, and be familiar with properties and variables in C#.

If you're new to programming, check out the 

 before you continue with this tutorial. There you'll learn fundamental programming concepts such as variables, functions, and basic logic through two practical projects.

Download the attached project and open it. The 

 scene contains a small prototype where you can move the character around by selecting where on the ground you want it to move to. Walking in the red cubes on the ground will damage the character, but in the current state nothing shows the character's amount of health.

Before you begin

UI Toolkit is one of the two UI solutions in Unity. It takes inspiration from web technologies like HTML and CSS and splits UI into three parts:

: defines which component the UI Contains (text, button, container, slider etc.) and their hierarchical relationship. This is defined inside an 

 file, which is similar to an HTML file for the web.

: defines visual properties (color, size, background, etc.) that can be applied to elements. This helps you to reuse style across your whole application or hot swap styles during the application run. This is defined inside a 

 file, which is similar to a CSS file for the web.

: defines how element values are updated  or how they react to interactions (clicking, hovering, etc.). This is defined in your 

It’s possible to write UXML and USS files by hand. However, this is often unnecessary, as Unity comes with a visual tool to author and style UI called 

In this tutorial, you’ll use UI Builder to create and style elements directly. However, you’ll also learn how to use a USS file to define styling. 

What is UI Toolkit

The base of all UI using UI Toolkit is the 

 window, right click inside the folder you want to create the file in and select 

 window is made of multiple sections. But for the moment you only need to focus on the following:

: This window lists all the VisualElements in your UI. VisualElements are the base building blocks of UI, like GameObjects are for your scenes.

: This window lists all existing types of VisualElement you can add to your UI.

: This window is a view of what the UI will look like, shown on a  square called the 

window for GameObjects in the Editor: it displays properties for the currently selected VisualElement.

Let’s start creating your UI by adding the background for the health bar.

The VisualElement is the base element you’ll use to build your UI, and everything else will be derived from it. 

window now contains a VisualElement that, when selected, displays a blue selection border around the 

Rename your VisualElement “HealthBarBackground”. 

 is the bounds of the VisualElement. Right now it fills the 

 because, by default, the layout of elements in UI Toolkit are based on the 

. However, for our purposes, we want to have the health bar in the upper-corner of the screen. 

window, use the foldouts (triangles) to expand the 

 section allows you to define visual styling properties on these elements, things like color, position, size, borders, etc.

You’ll notice that now the bounds of your element are shown as a single point in the upper-left corner. Because the element isn’t handled by the automatic layout system anymore, it has no size by default.

To change the dimension of the element, use the foldouts (triangles) to expand the 

Your health bar should now cover a small section in the upper-left corner of the 

, but it’s still just a bounding rectangle and has no visuals.

 section allows you to define multiple properties of the background of the element.

Now your health bar background should have a visual on the 

Now is the time to actually display the UI in your game. This is done using a UIDocument component. Despite the similar name, this is not to be confused with the UI Document asset, which you created earlier. This is a component on a GameObject that will render the UI on screen.

Create the UI File and the Health Bar Background

For now, your UI is a static visual. Let’s add a dynamic label that will display the current health and show any changes over time. 

 element so it gets added as a child element, then rename it “HealthLabel”.

Note that before changing the bounds, in 

 mode weren’t stretching over all the parent, it stretched horizontally but resized vertically. In 

 mode, the Label will resize to fit their content. 

Use the foldouts (triangles) to expand the 

Most size and position values in UIToolkit can be defined in one of the following ways:

As pixels by only writing a number (what you did with the 

after the number (for example, 150 or 150px).

As a percentage of their parent size, by adding 

Setting width and height to 100% ensures that no matter the size of the 

, the label will be stretched over the whole bounds of its parent.

You’ll notice that your text still doesn’t appear completely centered, and the bounding box of 

 is larger than the background, despite setting its size to 100%. This is because, by default, Labels have margins and padding added to them. 

 reserve extra space outside the element.

 reserves extra space inside the element 

The margins and padding are the green and orange bands you see on the 

Use the foldouts (triangles) to open the 

 reserves space on the left to avoid the 

 that you can change its value through code to display the health amount.

, name it “GameUIHandler”, and add it to the 

Let’s take a closer look at this script:

, which is the script in the provided project that handles everything player related. Don’t forget to assign it in the 

 window; this is the component you added earlier to display your UI.

function is registered to a callback on the 

 script will call that callback when the player’s health changes, so you can react to it and modify the label.

 using code, you’ll need to retrieve a reference to it in the 

 can be made using the shorthand function Q<>. The 

 type has a property called rootVisualElement, which is the root of all elements in the 

This function call will look for child objects of 

Now, you can then change the value of the text in the label like so: 

 to insert variables or function calls. This is equivalent to the following:

Take a moment to review how the final script looks like:

 function to initialize the text on start, so it avoids having to duplicate the text setting code both in 

Now you can press Play and walk on a damaging zone to see how the label value changes.

Add a Label to display Health

To fill the bar based on the remaining health, you’ll need to use the 

 window, use the foldouts (triangles) to open the 

:  Your label might not be visible anymore. If this is the case, it is because your 

. VisualElements are rendered in the order they are listed in the  

(and its child the fill bar) are rendered on top, which hides it. 

 Element so it appears first in the list of child elements.

To create the masking effect, use the foldouts (triangles) to open the 

 width to 50% instead of 100%, your viewport should look like this:

 element that is outside of the bounds of the 

element gets hidden. This is why you had to set the 

 to 500px (an explicit value) instead of 

 (a relative value), because otherwise, the 

 child element would also get resized when you set the mask 

 instead of overflowing and being hidden. 

 percentage to check how the bar gets hidden. Two important values to notice are the following:

 the mask reaches the left side of the fill bar background.

tThe mask hides the entirety of the fill bar.

This means that if you want to change the width of the mask based on how much health is remaining, you have to set it to 

 when health is full and then all the way down to

You also need to update its width in the 

 based on how much health is remaining, then set that percentage as the 

 to define a percentage value, otherwise it would be interpreted as a pixel value. Length.Percent expects a value between (0, 100) not (0.1).

  Enter Play mode and check that your health bar gets updated properly!

 Add a filling bar

For the masking effect to work, the filling bar needed to have its size set manually to the same value as the background. But this means if you want to change the size of the background element, you need to remember to change the filling bar size to match it. 

This is likely to produce errors and is also extra work; instead, you can leverage USS files to share styles between the two elements. A 

 that will apply their associated style to every element they are assigned to. Here is an example of some USS content:

The first code block is called a Class Selector. A 

 starts with a dot (.) then everything between the curly braces are the properties to set. You can then apply that class to multiple elements, and every element that has this class will have its width set to 40%.

 will have the properties in the block applied to it.

) and write your style manually, but the UI Builder has a functionality to extract an inline style and put it into an USS file.

To extract an inline style into a new USS file, follow these instructions:

element, use the foldouts (triangles) to expand the 

Name the new class “healthbar-size” and select the 

Save the new USS file and name it “GameUIStyle.uss”

 window, in the upper-right corner, you will find your new USS file.

 selector, all the properties that can be set are displayed in the 

 window, and the ones that are already set will be in bold with a bar on the left side.

To see the content of the USS file, selecting the 

 icon in the USS Preview button in the lower-right corner of the 

(either by selecting the selector in UI Builder and changing the value in the 

window or by entering “800” instead of “500” in the USS file and saving) you’ll see that the the background bar stretches but the fill bar does not.

That’s because right now, the fill bar doesn’t have the selector applied to it, so its 

window, use the foldouts (triangles to expand the 

section, enter “.healthbar-size” in the text box, and select the 

Your fill bar now has the class applied, but it still hasn't resized! 

This is because Inline Style takes precedence over USS style. You need to remove the Inline Style that forces the 

 so the Element takes its size value from the USS instead. 

Your fill bar now gets its size from the USS class. Try to play with the selector length to make both the fill bar and background the same size.

Use USS to define styling

To bring some life to your health bar, you can use the Built-in animation system in UI toolkit to auto animate changes:

, as the mask is the one that gets changed by code).

 section, and change the property values to the following:

 property. It will interpolate from the old health value to the new value, following the ease out 

There are a lot of easing functions. The simplest ones are linear: they go at a constant linear speed from start to end. There are also ease ones; these use a curve, so will accelerate interpolating to the midpoint then slow down toward the end. For all the others, you can check out the 

Now if you enter Play mode, your health bar should bounce as health reduces!

Animate the health bar filling

You should now have a simple functional health bar for your application!

Feel free to experiment with different ways to fill/empty the bar. Instead of using a mask like you did here, maybe your visual would work better by simply rescalling the fill bar directly. 

The mask can be of an arbitrary shape using the experimental vector image support package. Check out 

Unity Version 6.0