Creating a ScreenManager to handle switching between views
Nesting uxmls and custom Visual Elements in UI Builder
Creating custom VisualElements
Setting callbacks on OnGeometryChange()
Updating DisplayStyle to switch views
Creating a USS document shared by multiple UXML files
Creating a class list
Extracting inline styles to a class list
Adding classes to elements from StyleSheets
Creating custom styling for :hover and :active states
Styling a view to be responsive to changes in width to be prepared for both mobile and desktop views
Creating headers and footers for game information
Using display flex in UI builder to create responsive designs
Using standard Unity elements to create an interface
Adding a png or SVG background
Creating a ListView
Setting a source of data for the ListView
Creating custom click events and loading data when clicking on an item in ListView
Loading data in between scenes to configure host/client build
Using launch GameObjects to configure a scene to build as a host or a client
Creating a ClientServerBootstrap to stop automatic world creation
Triggering client and server worlds manually
Supporting Thin Clients when creating client worlds
Deleting all entities and worlds
Using UniversalQuery in EntityManager
Clean up to return to initial state
Unity UI Builder + UI Toolkit
UI Builder is a new UI-creation tool by Unity. It allows you to easily create UI's that integrate with your Unity project. UI Toolkit (formerly UIElement) is a collection of features, functionality, resources and tools for developing user interfaces (UI). A good way to think about the relationship between the two is UI Toolkit is the elements needed to create UI and UI Builder is the tool you use to put them together.
Unity’s UI Toolkit is a collection of features, functionality, resources and tools for developing user interfaces (UI). You can use UI Toolkit to develop custom UI and extensions for the Unity Editor, runtime debugging tools, and runtime UI for games and applications.
UI Toolkit is based on, and inspired by, standard web technologies. If you have experience developing web pages or applications, much of your knowledge might be transferable, and many of the core concepts might be familiar.
Although Unity recommends using UI Toolkit for some new UI development projects, it's still missing features that can be found in Unity UI (uGUI) and IMGUI. These older systems are more appropriate for certain use cases, and are required to support legacy projects. For information about which circumstances it is more appropriate to choose an older system instead of the UI Toolkit, visit the Comparison of UI systems in Unity.
Major UI Toolkit Features and functionalities
The UI system contains the core features and functionality required to create user interfaces.
UI Assets are a collection of asset types inspired by standard web formats. Use them to structure and style UI.
Tools and resources crucial for creating and debugging your interfaces, and learning to use UI toolkit.
The core of UI Toolkit is a retained-mode UI system based on recognizable web technologies. It supports stylesheets, and dynamic and contextual event handling.
The UI system includes the following features:
Visual tree: Defines every user interface you build with the UI Toolkit. A visual tree is an object graph, made of lightweight nodes, that holds all the elements in a window or panel.
Controls: A library of standard UI controls such as buttons, popups, list views, and color pickers. You can either use them as-is, or customize them, or create your own controls.
Layout Engine: A layout system based on the CSS Flexbox model. It positions elements based on layout and styling properties.
Event System: This system communicates user interactions to elements; for example, input, touch and pointer interactions, drag and drop operations, and other event types. The system includes a dispatcher, a handler, a synthesizer, and a library of event types.
UI Renderer: A renderingsystem built directly on top of Unity’s graphics device layer.
UI Toolkit Runtime Support (via the UI Toolkit package): Contains the components required to create runtime UI. The UI Toolkit package is currently in preview.
The UI Toolkit provides the following Asset types that you can use to build user interfaces in a way that’s similar to web application development:
UXML documents: Unity eXtensible Markup Language (UXML) is an HTML and XML inspired markup language that you use to define the structure of user interfaces and reusable UI templates. Although you can build interfaces directly in C# files, Unity recommends using UXML documents in most cases.
Unity Style Sheets (USS): Style sheets allow you to apply visual styles and behaviors to user interfaces. They are similar to Cascading Style Sheets (CSS) used on the web, and support a subset of standard CSS properties. Although you can apply styles directly in C# files, Unity recommends using USS files in most cases.
The UI Builder lets you visually create and edit UI assets such as UI Documents (UXML / .uxml assets), and StyleSheets (USS / .uss files), that you use with Unity's UI Toolkit (formerly UIElements). After you set up the UI Builder package, you can open the UI Builder window from the menu (Window > UI Toolkit > UI Builder), or from the Project window (double-click a .uxml asset).
Note: In Unity 2019.x, you open the UI Builder from the Window > UI > UI Builder menu.
There are a couple of ways to work with UI Toolkit. UI Toolkit requires a GameObject in a Scene with a UI Document Component that will hold a Source Asset (Visual Tree Asset).
UI Document Component
Source Asset (Visual Tree Asset)
Multiple UI views and states can be handled by multiple GameObjects. Each view can have its own GameObject and the use of scripts can enable/disable different GameObjects as needed. This will in turn enable/disable different UIs. With this 1:1 GameObject to Source Asset approach you create a good UI flow. This is a fine approach.
Instead, in this gitbook, we will be using a single GameObject per scene, yet have a "ScreenManager" as the Source Asset which will handle enabling/disabling different child Visual Elements. "ScreenManager" is not an official Unity term, but the term we at Moetsi use to indicate a "screen that manages other screens."
In both cases there are multiple visual elements for different views. However it will be easier to navigate among views and edit in our UI Builder when taking the approach we just outlined above.
It is also possible to use the "ScreenManager" approach + multiple GameObjects (and there are probably use cases where this is preferred, so no hate on that approach). In this section we'll demonstrate how to change between different GameObject/SourceAsset combinations because we will be switching between Scenes using our UI.
Single USS sheet
Heads up: In this section we'll be working with one single USS sheet that we apply to all our UXML files. This is not a great approach for large and complicated UI projects. If you are familiar with web development, this is like having one single CSS sheet for an entire web app, which is not great for large complex systems with many teams.
So that being said, here's another reminder that the purpose of this gitbook is to introduce how to work with new technologies and put them together. Separating out a USS sheet per UXML document would be overkill for such a small project and would probably add more confusion than clarity in explaining how to work with UI Builder and UI Toolkit.
If you understand how to work with a single USS sheet it should not be too tough to include more USS sheets on your own. We will mention how to do it in this tutorial (although we will not implement it).
UI Toolkit's Flexbox model
UI Toolkit's layout engine is based on the CSS Flexbox Model. Knowing how to create Flexbox layouts is critical to be able to use UI Builder and UI Toolkit.
If you have not used Flexbox before we highly recommend you complete this rigorous online course to get up to speed: https://flexboxfroggy.com/
UI Toolkit + DOTS
We will integrate our UI with DOTS in the next section of this gitbook called "Multiplayer (NetCode+, UI Toolkit+), not in this section. Instead, this section will focus on integrating UI with scripts (no DOTS) for folks who are not interested in DOTS at all but still want to learn how to use UI Builder and UI Toolkit.