Unity's UI Toolkit & UI Builder: What is It, and How Do You Make It Work ? - Space's Aces Devlog #03

it's a cold fall day the clouds have come in following a cold front chlorophyll in the leaves has died and disappeared revealing the brilliant colors of the sunburns that have accumulated over the year brilliant yellows oranges and reds and then leaves fall welcome to another spaces aces devlog today we're diving deep into something new in unity and that doesn't have a lot of coverage every game at some point has to do with how users navigate the game or interact with information the game is trying to give them to help a user in this case we create a user interface aka ui while trying to continue working on the first level in particular game modes i came across the need for a better ui solution so that i may display things like whose language team score and more in a clean consistent way for the player currently i'm using unity's canada system for this i believe they call this ugui the unity gui system that utilizes canvases is very much an outdated way of solving issues with ui it has its uses like with my world hud elements and glowing effect of the targeting system but for cleanly displaying useful information it has some critical flaws for one if i add a new item onto the screen it may be overlapping with other items to solve this i need to manually shift other items out of the way and items in the canvas have a set resolution because they always need a sprite and if they're scaled up they can become pixelated other solutions have vector based options and for each button or visual element in a canvas i add another piece of clutter to my scene hierarchy this is because unity ugoi uses game objects as ui elements this is a very straightforward and headstrong method for handling ui and it's not very efficient another issue is that keeping a consistent style is difficult without the use of excessive prefabs and folder clutter as you will have to manually design each canvas and manually place size and color each button and element used this adds more room for human error and where possible it's always good to code away the possibility of human error this system doesn't allow for it and last but not least each item in the canvas is rendered as a texture on a 3d plane this means that for each item we have two tries or six verts being rendered and regenerated each time the canvas updates this is really inefficient in the long run so what i want is a ui solution that doesn't have these issues luckily for me and other devs out there unity has been working on a solution for a couple years now called ui toolkit now before we dive into this kit let's lay out some learning goals let's learn what the kit actually is and learn how to layout some visual elements with the ui builder then we can learn how to use style sheets to control the look of visual elements and then we can get into the code and control individual elements with the code then we can look at creating custom controls with the code and then we'll use transitions and animations to create a clean and appealing main menu with navigation to other menus so let's start by learning what ui toolkit and ui builder are and how they can help us the ui toolkit is based on web technologies and exists to specifically solve the issues i listed a minute ago the web tech it's based on is html xml and css respectively unity uses what they call uxml which stands for unity extensible markup language and uss which stands for unity stylesheets the way we're going to create the uxml and uss code is through unity's ui builder so i actually tried to dive into this a few months ago but i wasn't in a clear enough mindspace to learn a whole new system so i ended up building my ui the old-fashioned uguy way i opened it up and tried to place a simple button and couldn't get it to move right or really at all so i closed it out and didn't look back until i began asking myself if there was a better way to handle ui and while of course there was i literally turned it down only a month prior to asking that question so i gave it another chance and this time instead of diving in head first and not looking at any resources i watched a unity presentation on the topic and then i opened up an example project once i took the time to understand the basics and get the good practices of ui builder it became obvious this is a way better system for creating ui it's not just more efficient it's way easier to get an actually good result now it's worth noting at the beginning i learned from an example project but as i became more confident in the toolkit i began inventing my own better methods for accomplishing some tasks this is bound to happen with anything if you work with it critically and you like to optimize your workflow so let's look at ui builder now the way ui builder works is that you have this preview window in the middle of your ui builder window you can set that to match your main camera if you want this screen is your uxml file and when you add a visual element the ui builder generates eqxml code to show that element and position it from here you can change its size color add a sprite and more if you get the vector graphics preview package you can even use those instead of the sprites i also believe freya homer has some vector tools available somewhere if you just throw a button into the uxml window you'll have a really hard time putting it anywhere you want to you can manually tell any item in absolute location to be but that's not a good practice to get into the reason for this is that you want your items to interact in accordance with each other's positions if you have a series of buttons at the top of your screen and you add another you want all the buttons to adjust their positions to fit the new one so instead of dragging buttons around and setting absolute locations we're going to create anchors to use for relative position so far it seems the best practice for this is to add visual element containers as anchors so first we'll add a visual element that stretches the whole screen top bottom and left to right and aligns itself left to right we'll call this screen as it represents our whole screen we'll also set its size to 100 then we'll add a new element for left center and right and now we have those as anchors so now let's add a button to the bottom left we can go to the left element and we could add a top center or bottom as visual elements or we can just start building from the bottom and work our way up if we need i'll just do that here since i may never need anything else on the side then we can add padding or anything else we need to offset our visuals the way we want so now we have some visuals so let's style them we may want to style this button we could go into the right panel here and start changing things like color and size but what if we want all of our buttons to be consistent with each other this is where your unity style sheet or uss comes into play using stylesheets you can add a class that defines how certain elements should look the css term for these styles are classes here in the builder they're called selectors you can also think of them as tags anything you tag as header will have a specific defined font style color and whatever else you come up with just drag the tag or class onto the item and voila your ui is now styled consistently you can also add multiple tags so header may only affect the font but we can add another tag or button that affects the color and size of our button and not the text then if we add more buttons and tag them the same we have a consistent style for our buttons you will notice too that with the default buttons if you zoom in they are vector graphics there's no pixelation we can also control curved corners or slicing on sprites if we do include a sprite this gives you really strong control over your game's ui you can also use the ui toolkit and subsequent ui builder to create ui for debugging tools and the inspector if you so please if we want our ui to appear in the game we can go to create find the ui toolkit and create a ui document then we select the uxml as our tree also make sure you have an event system in your scene if you want any buttons to work an important element of ui is controlling it with code so let's see how to control screens with code this is a pretty important aspect of the ui i need to be able to tell every label what to say and every button what to do and it also needs to be able to be changed as information changes this applies to the way i previously set up my multiplayer i have all this code that connects people together to servers in different rooms and uses the ui to tell you where you are but now it's totally wrong because i've changed the way it all works so i need to rewrite it one crucial step is getting the information from our multiplayer launcher to display correctly in our new ui previously we could simply define a bunch of game objects and text elements and change them as needed but now we need to access info that isn't available in our scene hierarchy code is the part that held me up the longest in the video because the kit is new and so people hadn't come up with solutions yet so i started looking at unity's example projects and one thing i found is that monobehaviour scripts still work with ui toolkit as long as they know to look for the ui document object in the hierarchy to access elements in the ui you need to find the root visual element this is simply the first element that holds all others in the hierarchy to do this you can simply say visual element root equals git component ui document dot root visual element from here the rest is as easy as root.query or queue and then the type and then the string name of it not including the hashtag it generates so your type could be visual element or button or you don't need to list a type if it's just a visual element and then the name as a string to test this with monobehaviour i added a clock into my main menu that displays your real system time i wrote some code to convert this from a 24 hour clock into a 12 hour clock with am and pm conditions to get it to display i just have to query the root element for a label named systemclock and tell its text to display a chosen string this works pretty simply root.q in carrots label in parentheses as a string system clock dot text equals our string that we're trying to set being an artist first for a long time it did take me longer than i should have to realize that query was how i was going to access everything in the ui for a minute i thought you could only query from a script that inherited from visual element and not about a behavior so to access an individual element i didn't know what to do well as it turns out an amount of behavior is as simple as asking the root element for the item you're looking for so i'm able to find any aspect of my ui and change it instantly since i have access to the root so if i want to change the displayed version number of the game i can just say root.q label version number dot text equals game version string this works exactly the same as changing a text component with the old ui system just instead of getting the component we query for a label the old version of this is text.text since i can still simply grab an item like this i can take this further with some small changes to my old multiplayer launcher when my launcher script starts connecting to a server it quarries for the main menu manager and asks it to turn on the connecting screen then on connected we asked the main menu manager to enable the multiplayer menu the system is so simple i don't have to actually rewrite any of my multiplayer launcher code other than getting rid of a lot of game object references that are no longer needed in exchange for queries i've also learned how to connect other scripts with the code so now my main menu manager runs the code scenecontrollerequalscenecontroller dot find object of type scenecontroller with this we can now set ui functions to control what scene we're in i use this to set up a quick layout for players you can press the exit button and the game will turn off if it's a build this is also how i get the ui to talk to the multiplayer launcher let's actually dive into this area a little bit further since i didn't explain what my menu manager was to control the ui from the root we need to make a custom control to manage all the screens and buttons for me this is called menu manager and is a normal cs file when you edit the script and you want it to appear as a custom control you do need to do a few things one at the top you need to add using unity engine.ui elements then instead of inheriting from modded behavior we should inherit from visual element this will make our code an actual visual element third to have the control appear is something we can use in the ui builder we need to add these lines of code public new class uxml factory colon uxml factory and then the name of your script comma uxml traits and then these silly little curly braces and then public new class uxml traits colon visual element.uxml traits and then more of the silly little curly braces these can hold some custom data i believe but i don't need any for now so they're just required to get the control to appear correctly before we need to actually initialize this code here we create a public and then the name of her class for me mini manager so it's a public menu manager and inside this we want to register the callback geometry changed events then we create our function for non-geometry changed and now we can make this code our root object for the ui document create a uxml and apply menu manager as the first item in the hierarchy and make that uxml the tree that the ui document is looking for now we should be able to affect our screens with code from our menu manager and we should be able to ask our menu manager to affect our screens based on code from other mono behaviors in the ui document so if we go back into our menu manager and look at on geometry changed here we can assign screens and run all of our code for our buttons when you click on a button on geometry changed is run allowing you to then check which button was clicked to find which button was clicked and run a function we once again use query since the script is our root object we can simply tell a button to run a function by saying this question mark dot q let's say return home screen question mark dot register call back click event and then we say our event leads to enable home screen and then we can have a public void enable enable home screen to enable and disable elements in the ui document we'll be changing the display style between flex and none so in the enable home screen we can say home buttons dot style dot display equals display style dot flex now that enables the home buttons but we also want to disable all other elements the unity example projects did this in the individual functions for each screen but i've chosen to split mine up a little some things i know i want to manually choose when they enable and disable but some i know i only ever want to see on their appropriate screens so i found it more efficient just to create a function called disable all screens and run some code to disable each element and then on the individual functions to activate elements i just write in each element i want to reactivate this shortened my code significantly so now if we click the button called return to home screen it will run the function enable home screen and then disable all screens and then enable the elements that make my home screen work this is a part where things start becoming more powerful and more efficient now with query i can start coding by simply searching for what i need to i can ask if my connect to random room button has been pressed and if so i can ask the multiplayer launcher to connect me to a random room then the multiplayer launcher asks the ui to display that i am connecting to the room then once i'm connected the multiplayer launcher can check if we have enough players and once we have enough players it can send a message to the ui and start a countdown then once that countdown reaches 0 it can load in everyone into the same scene since the multiplayer launcher is a mono behavior i can start a co routine to count down and each second i can have it change the string of the label that it uses you can use the custom control code to do more than manage the menus i wanted a control that defined how profile information was displayed as a nameplate so i set up my code and added in images and labels to represent the data that i wanted then i added styles with the code so i created a reference for an image then i created my image using my image equals do image and then i added the image to simply using add dot my image and this added it to the root that this class is based in after some tweaking and setting up the styles and getting the sizing right i eventually had a profile nameplate that appealed to me so now let's talk about pseudo classes transitions and animations it's hard for someone like me who isn't trained at all in ui to create the perfect ui in one go so at some point i'll have to call it for adding new elements and constantly changing the ui but before i finish up and call the video done there is something that has been bothering me ever since i added my own style to the buttons i lost the change of color they get when you hover over them with the mouse for a while this has been frustrating me in the background and i've been telling myself i'll cross that bridge some time before i end the video well that time is now i went and took another stroll through unity documentation and i found what i'm looking for every class in the stylesheet or dot uss file can be linked to a certain pseudo class this is controlled by typing the class name colon pseudoclass name when you create a selector in css pseudo classes are built in and describe certain conditions in unity it works the same though we have a few less than css at the moment here are the pseudo classes currently provided by unity hover active inactive focus disabled enabled checked and root each has a different condition that will allow the pseudo class to override the main class so for example if i were to take my button class for the multiplayer button and add a pseudo class that turns it yellow when hovered then while my mouse is hovering the button will turn yellow automatically convenient isn't it most of these i feel are self-explanatory if you need a more in-depth explanation on the other pseudo classes you should be able to find the manual by looking up unity ui toolkit pseudo classes something i noticed while trying to add the pseudo classes was that the hover capability would not work in play mode for whatever reason it only seemed to work in preview mode i eventually found out that the answer was i was using the event system for ui input but it was the one for unity's old ui so i simply needed to replace that component with the one designed specifically for ui toolkit and now it works as expected now this isn't actually a problem anymore in unity 2021.2 which contains the first supported build release of ui toolkit i actually ended up upgrading my unity to 2021.2 not for this reason but you'll see why in a second having gotten pseudo classes working i thought this would be a great time to end the video but then i found out something new in unity 2021.2 they fix a lot of bugs i've been having with ui toolkit that's one reason why i upgraded it's considered a supported release and no longer experimental but another big reason is because they added transitions to the styles i was going to cut the video saying i didn't get to animations but this will cover some basic ones really easy for example we were about to end with me having created a pseudo class for hover now in that pseudo class i can add some scale instead of pivot point and then in the base class i can add some transition time and voila just like that that easy we have a very simple animation that tweens from the smaller size to the larger size whenever i hover and increases the feedback and professionalism of our ui and does so with some truly minimal effort on my part so long gone are the days of storing animation files throughout the project quickly experimenting with this using the pseudo class for disabled i can move this panel out of the way when it's unusable and pull it back when i'm ready to use it it's not too great so i took a small break and came back ready to see if i can take this further in looking further into the unity documentation i found some important events one really important event is the transition end event using the styles we can create a selector i call these selectors animation classes and using events we can time actions to play out in relation to our animations for example if i click on the start screen i want the title to fade and after it's finished animating i want to enable the home screen to do this i can create an animation class opacity out and on the click event i can add the opacity out class to the title screen this will trigger a transition to a clear screen and then i can have a listener for transition end event on the title art this means that when the title screen has fully transitioned to my opacity out animation class we can run the function enable home the code looks like this got my title screen register callback click event and then be queried by title art and add to class opacity out then on my tile screen we register the callback for transition invent and whenever the transition is over we enable home i can animate using transition time without adding classes as well to do this your object simply needs transition time you can also set that in the code and then you need to define a change you can manually change opacity with code for example at one point i created this progress bar to keep track of progress when connecting to the servers in my game this bar starts with a width of 0 and i change it to 100 when you're finished connecting i also have some other numbers in between for each part of the contacting process each time the number changes the transition time automatically tweens between our previous width and our new width and then once the number reaches 100 percent i tell the code to open the multiplayer select menu using the transition end event that way the bar always finishes animating to 100 before the screen switches at this point i've explained all my main points and hopefully didn't miss on anything crucial explaining the process of the weeks of research i put into this so hopefully you can skip much of that research process i do however super highly recommend giving the documentation a good read on your own as i certainly didn't cover everything just enough that you can get a professional looking start on your own in the next one i hope to finally work on creating the game mode system that requires ui so if i learn anything new about the ui toolkit i'll share that in the next log until then make what you need to make try to never look back at ugui if you can help it because this ui toolkit is the future of unity ui the only thing i really can't do is give you world space ui but you can use code to match screen position to world position and i don't think you can affect the ui with post processing like i have here with my glow effect on the ui but i also haven't tried it yet alright that's the end of the log see ya [Music] hey folks this video is pretty much three weeks of research crammed into one video ui toolkit is very much a new feature to unity and thus there isn't a lot of good information outside of unity documentation about how to use it so everything i learned was through unity documentation and unity example projects this video went through my process learning it and should hopefully give you watching a head start on figuring it out if you need to go back and take note of specific code snippets needed to accomplish tasks in uitk i should have hopefully showed enough of my code as i went that everything you need to accomplish what i have can be done a recommendation i have is a program called obsidian i've been using that to take notes and build my own personal documentation for how i understand systems and code i also wrote my script for the video in obsidian having your own explanation of these systems and code in your own documentation and why it's useful to you is really useful for grasping new concepts anyway i hope i've helped and thanks for watching subscribe for insight into my upcoming game mode system hopefully and see you in a few

Channel: KookaNova

Views: 768

Keywords: ui toolkit, ui builder, unity, devlog, dev log, development, log, vlog

Id: EVdtUPnl3Do

Length: 24min 31sec (1471 seconds)

Published: Sun Nov 28 2021

Reddit Comments

[u/KookaNova]

I needed better UI for my Space-Fighter game. I decided now would be a good time to learn the new UI Toolkit and UI Builder, and I gotta say, I like it WAY better than using Canvases. In this Space's Aces Devlog, I go over why I needed the new UI Toolkit, why you may need it, and I feature a detailed tutorial with code snippets that will have you creating sleek menu UI in no-time.

This is actually my most viewed video, likely due to the fact that there's not a lot of resources on UI Toolkit yet. The most recent help I could find was 6 months ago. The only help Unity provides as a video is a 2 year old introduction to the system.

Edit: Don't what to watch the whole thing? It's split into chapters for easy skipping, replaying, and whatever else you may need. But if that's still too much for you, honestly I'll just answer your questions here if you want. Just ask and I'll try to get back to you when I can. I just like to help.