Initial Setup
Every UI Document component references a UI Document asset (.uxml
file) that defines the UI and a Panel Settings asset that renders it. You can connect more than one UI Document asset to a single Panel Settings asset.
Right-click Project window, and then select Create > UI Toolkit > UI Document
- In the Hierarchy right click the Scene, select GameObject > UI Toolkit > UI Document. This creates the following:
- A UI Toolkit folder with a Panel Settings asset and a default runtime theme.
- A GameObject with a UI Document component which in turn the is connected to the Panel Settings asset.
- In the Hierarchy select the UIDocument then drag SimpleRuntimeUI.uxml from your Project window to the inspector (Source Asset)
- Create a companion script that derives from
MonoBehaviour
. - Add SimpleRuntimeUI.cs as a component of the UIDocument GameObject.
- Click on the PanelSettings object Project > Assets > UI Toolkit then drag the theme style sheet (.tss) to the Panel.
- Use the Package Manager to install the Input System package.
- Select Edit > Project Settings > Player.
- Set Active Input Handling to Input System Package (New).
- Select GameObject > UI > Event System. This adds an Event System GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary that includes a Standalone Input Module in the Scene. The module shows an error message along with a button in the Inspector window.
Custom USS
- Right click Project → Create → UI Toolkit → Style Sheet
- Add style sheet to umxl view
- Add a Style tag with src attribute pointing to the style sheet
- In the UI Builder upper left corner (+▼) → Add Existing USS
Using UXML instances as templates
Any UXML file in the project is available as a library object in the UI Builder.
Editing Templates
Open in UI Builder
Library→Project→Component (RMB)→Open UI Builder
Close the current context and open the component in the UI Builder.
Open as Sub-Document
Hierarchy→Component (RMB)→Open Instance in Isolation
Edit the component in the UI Builder, maintaining a breadcrumb to the previous context.
Open Sub-Document in Place
Hierarchy→Component (RMB)→Open Instance in Context
Edit the component while keeping the view on the current component. Maintains a breadcrumb to the previous context.
Common Attributes
- name
- tooltip
- tabindex
Accessing UXML Elements in C#
Typically a controller for a UI Element will is added to the UI Document as a component. Alternately the the UI Document can be set as a field on a MonoBehaviour instance.
Extending the MonoBehaviour class is most expedient way to control a UI component when it has only one instance. Public accessors permit access from other controllers, and should be used sparingly.
Select UI Document, in the Inspector→Add Component→Scripts.
using UnityEngine;
using UnityEngine.UIElements;
public class GameListController : MonoBehaviour {
public string GameListID = "GameList";
private VisualElement Root {
get { return GetComponent<UIDocument>().rootVisualElement; }
}
private ListView GameList{
get { return Root.Q<ListView>(GameListID); }
}
}
Add event handlers to the MonoBehaviour Start method.
public void Start() {
Root.Q<Button>(JoinButtonID).RegisterCallback<ClickEvent>(ClickJoinButton);
}
public UIDocument uiDocument1;
[SerializeReference] private UIDocument uiDocument2;
var uiDocument = GetComponent<UIDocument>();
public VisualElement Root {
get { return GetComponent<UIDocument>().rootVisualElement; }
}
Custom Control Class for UXML Elements [source]
Create a C# class derived from the VisualElement
class or a subclass.
You can initialize the control in the constructor, or when it’s added to the UI.
Event Handling
https://docs.unity3d.com/Manual/UIE-Events.html
You can register an event handler on an existing class, to handle events such as a mouse click.
Dynamically Adding Elements
ScrollView scrollView = Root.Q<ScrollView>(GameListID);
scrollView.contentContainer.Add(new Label("I done got clicked"));
External Links
Override VisualElement.ContainsPoint()
to assign custom intersection logic. [source]
You can also create USS custom properties to style a custom control. [source]
https://docs.unity3d.com/2022.2/Documentation/Manual/UIToolkits.html
https://docs.unity3d.com/2022.2/Documentation/Manual/UIE-get-started-with-runtime-ui.html
https://docs.unity3d.com/ScriptReference/UIElements.VisualElement.html
https://docs.unity3d.com/Manual/UIE-USS.html
https://docs.unity3d.com/Manual/UIE-create-tabbed-menu-for-runtime.html