Manual
Manual
UI documents and controls
A game's menus and HUD are kept in UI documents, files of their own beside the scenes. This page covers making a document, editing it on its own, the controls the UI menu makes and the components they are made of, an element's layout, background and border in the Inspector, and showing a document in a scene, on the screen or on a panel in the world.
What a document is
A UI document is a .ui file in your assets. It is written in the format scenes and prefabs are (see Scenes and prefabs), and its elements are entities with Bevy's UI components on them: a Node for the layout, Text, an image, a Button and the rest. Elements are laid out by Taffy, with flexbox, grid and block layout, as a web page is.
A document is kept apart from the scene. Its elements are never saved with a scene and never listed among the scene's entities. A scene shows a document with a UI Document component, or your code opens one (see UI from code).
Three things shape a document:
- Its elements and their values, edited in the editor as a scene is.
- Its style sheets, CSS files that say how its elements look and react to the pointer; see Style sheets.
- Its class, C# the build writes from the document, with a member for each named element and a handler for each thing a control can do; see UI from code.
Make a document
In the Project panel, choose UI Document in the + menu, or New UI Document in a folder's right-click menu. A document is made in the assets folder or one inside it, named NewUIDocument.ui until you type its name.
It starts as a screen-filling column called Screen, with a Title and a Play button in its middle. A style sheet of the same name is made beside it, NewUIDocument.css, holding the look: the title's size and color, and the button's color, lit as the pointer is over it and darker as it is pressed. The document keeps where each element is, and the sheet what it looks like. Rename the document and its sheet is renamed with it.
The document's class is named after its file: main menu.ui makes MainMenu. The name is kept inside the document, so renaming the file later keeps the class, unless the class still has the name the old file gave it.
Style Sheet in the same menus makes a sheet on its own, with example rules to change.
The document's Inspector
Pick a .ui file in the Project panel to see it in the Inspector:
| Row | What it does |
|---|---|
| Class | The class the build makes of the document. Renamed here, it is renamed in its script too. |
| Elements | Each named element, as the class calls it: Title, Play. |
| Style Sheets | The sheets it is styled by, in order, above the project's theme. Drag a sheet by its grip to reorder, × takes it away, and the slot below adds one, picked from a list or dropped from the Project panel. |
| Classes | Each element's classes, apart by spaces: what a sheet's .class selects. |
| Navigation | How keys and a gamepad move between its elements; see Keys and a gamepad. |
Below them, the Inspector lists the handlers the document's script can implement, such as partial void OnPlayClicked(), and offers Create Script, which writes the class's other half into the scripts folder, or Open Script once there is one.
Nothing here changes while the document is open on its own: edit it there instead.
Edit a document on its own
Double-click a document in the Project panel. The open scene is set aside with its changes and its undo history, as it is for a prefab, and:
- the Hierarchy lists the document's elements alone, under a band with a way back to the scene;
- the Scene panel shows the document on a canvas, drawn as the game draws it;
- the Inspector edits the element picked;
- the Style Sheets panel opens behind the Hierarchy, listing the rules of the document's sheets and the theme.
Every change is one step of Ctrl+Z, and Ctrl+S writes the document. Going back to the scene, or opening another file, asks first about changes not saved. Started from a command line, --document opens a document this way.
You can open a document while the game plays. Saving it shows it again in the playing game, from its file, as the game also does for a document saved by anything else.
The canvas
The row along the top of the Scene panel picks the screen the document is laid out as: Reference, the size Project Settings lays the interface out for; Game panel, the Game panel's size; common screens, from HD · 1280×720 to 4K · 3840×2160, phones and a tablet; and Typed, a width and height you type. Picking another screen changes nothing in the document. The button at the row's right end frames the whole screen again, as F does.
| Do this on the canvas | To |
|---|---|
| Click | Pick what is drawn there. Click again at the same spot to pick what is beneath it. |
| Shift or Ctrl and click | Add to what is picked, or take away |
| Drag an element | Move it. One its sheets place by its insets moves by them; one in its parent's flow is carried among what is in it, or into another, where a line says it goes |
| Drag the dots round what is picked | Size it: an absolute element by any edge, one in the flow by its right and bottom |
| Escape, while dragging | Put it back |
| Double-click text | Type it where it is drawn. Enter, or a click elsewhere, keeps it; Escape leaves it |
| Turn the wheel | Zoom about the pointer |
| Drag with the middle or right button, or Alt and the left | Pan |
| F | Frame the screen |
What is picked is outlined in orange, and what the pointer is over in a fainter line.
The buttons :hover, :focus, :active and :checked on the row hold the one element picked in that state, so you see what its sheets say for it and the Inspector marks those rules. .open holds a dropdown open, its list drawn where it opens. Each element keeps the states it is held in while the document is open.
The Phone button beside them shows the whole document as on a phone or a tablet, whatever is picked: its top element has the class touch, and a dropdown that opens as the screen suits opens in the middle.
Controls
While a document is open on its own, the Hierarchy's + menu and its right-click menu list UI controls in place of a scene's objects. Each control is made whole, with the parts it needs to work, and each part is given a class the project's theme styles:
| Control | What it is made of | Classes |
|---|---|---|
| Panel | A Node laid out as a column, with padding and a gap | panel |
| Text | A line of Text | text |
| Image | A 128-pixel square with an image, none until you give it one | image |
| Button | A Button with a Label inside it | button, button-label |
| Toggle | A Checkbox: the row, holding a Box and a Label, so a click on the label turns it too | toggle, toggle-box, toggle-label |
| Slider | A Slider with a Rail, and a Handle in a track as wide as the slider less the handle | slider, slider-rail, slider-handle |
| Dropdown | A UI Dropdown: a Label, an Arrow, and a List that scrolls, with three options | dropdown, dropdown-label, dropdown-arrow, dropdown-list, dropdown-option |
| Scroll View | A Scroll Area scrolling up and down, with an Item in it | scroll-view, scroll-item |
| Text Field | A UI Text Field, empty | text-field |
The first time a control of a kind is made, its rules are added to the project's theme, so every control of every document looks alike and a change to the theme restyles them all. Where the project has no theme yet, ui/theme.css is made and named as the theme. The rules give each control its colors, corners and text, its states, and a ring round it while a key or a gamepad has given it focus.
Create Empty makes an Element, a Node with nothing else. What you make with nothing picked goes under the document's top element, since a document is shown from its top. An image dragged from the Project panel onto the canvas or the rows makes an image element at the image's own size, and a material dropped on the canvas draws the element under it (see Material).
Templates: a document inside a document
Drag a .ui file from the Project panel onto the rows or the canvas of the document open on its own to place it there as a template, as a prefab is placed in a scene. Its rows are teal, and its own elements are under it. What you change in one instance, its text, its classes or a control's value, is kept as that instance's, and the rest follows the template's file: save the template, and every instance of it changes, in the editor and in a game that is playing. A document cannot hold itself, nor a template that holds it.
Each instance gets its template's own class as the game shows it, so a button placed six times is heard by six objects; see Templates.
Node
Every element has a Node, its layout. The Inspector shows it in groups, in the order a layout is thought through:
| Group | What is in it |
|---|---|
| Display | Display (Flex, Grid, Block or None), Box Sizing, Overflow X and Overflow Y, Clip Margin, Scrollbar Width and Inline Direction |
| Position | Position Type, Relative or Absolute, and Left, Right, Top and Bottom. Open on its own for an element placed absolutely. |
| Flex | Basis, Shrink and Grow, Direction, Wrap, and the Gap between rows and columns |
| Align | Align Items, Justify Content, Align Self and Align Content |
| Size | Width and Height side by side, Min - Max folded below them, and Aspect Ratio |
| Background | The element's color, gradients and image; see Background |
| Margin & Padding | Margin and Padding |
| Border | The border's Width, the corners' Radius, and its Color and gradients |
| Grid | Auto Flow, Justify Items, Justify Self, and where the element sits among the rows and columns. Open on its own for an element whose Display is Grid. |
| Other | Anything of Node's that no group names |
A length is one row: the number, and its unit in the same box, px, %, vw, vh, vmin, vmax or auto. Direction, Wrap and the four alignments are rows of pictures, one for each value, drawn along the element's own direction. A rectangle's four sides, such as Margin or a corner's Radius, are one length, with a dash where the sides differ and a fold that opens each side.
A value one of the document's style sheets sets is marked with a violet dot; see Rules in an element's Inspector.
Background
The Background group holds what fills the element, each a layer the element has or not, put on by the group's + and taken off by its ×. They are drawn in this order: the color, the gradients over it, and the image over both.
- Color: one color. Put on, it starts white.
- Gradient: one or more gradients. Each is Linear, along a line at an Angle (zero is up, turning clockwise); Radial, out from a Center to a Shape; or Conic, round a center from a Start. Mix In picks the color space its stops are mixed in, Oklab by default, which mixes as the eye sees. Its stops are handles along a bar: drag one to move it, click the bar to add one, and drag one off the bar, or press Delete, to take it away. A gradient keeps two stops at least.
- Image: an image from your assets, dropped on its slot or picked from a list. Mode is Stretch, across the whole element; Tile; 9-Slice, its corners kept and its middle and sides stretched, starting with an 8-pixel inset all round; or Natural, the element sized to the picture. Tint, Flip X and Y, Box (the content, the padding or the border) and Region, a rectangle of the image, follow.
The Border group draws the border the same way: its Color, one swatch for its four sides and a fold for each, and gradients of its own. A border shows only where its Width is more than zero.
UI Transform
UI Transform moves, turns and scales an element after the layout has placed it, pushing nothing else aside: Translation, Rotation in degrees, clockwise, and Scale. It is what an animation moves to slide a panel in, or a UI Follow to keep a health bar over a character.
UI Transform Origin
UI Transform Origin is the point an element's UI Transform turns and scales it around, of its own box: its middle without one. Its Origin is a point of the box placed as a gradient's middle is, from a side or a corner. A stylesheet sets it as transform-origin; see Motion.
UI Opacity
UI Opacity draws an element and everything under it see-through: Opacity from 1, as it is, to 0, not drawn at all. An element under another with one is faded by both. It is laid out and can be clicked at any opacity. A stylesheet sets it as opacity, and moves it over a transition; an animation clip moves it as Opacity.
Text
Text is what an element says, typed in its section or on the canvas. A sheet's color and font set on an element reach the text inside it, unless the text sets its own.
Text is drawn in Roboto until a style sheet names another font; see Fonts.
In a localized game, Localize at the right of the Text row makes the text a string of the game's, said in each language; see Text in a UI document.
Text Font
Text Font sets the font's size, weight and the rest of how the text is drawn. A size is a length, typed with its unit.
Text Color
Text Color is the text's color.
Text Layout
Text Layout is how the text sits in its element: Justify, its alignment, and Linebreak, where it breaks a line that runs out of room.
Line Height
Line Height is how far apart its lines are, a length typed with its unit.
Letter Spacing
Letter Spacing is the room between its letters, a length typed with its unit.
Text brings its Node, Text Font, Text Color, Text Layout, Line Height and Letter Spacing with it, so each is there as soon as an element has text.
Button
A Button is clicked by the mouse's left button, pressed and let go of over it, or by the UI map's Submit while it has focus: Enter, or a gamepad's South button. A press on what is inside a button, its icon or its label, is the button's. Its class hears both the click and the press as the mouse goes down; see Events.
Checkbox
A toggle is a Checkbox. A click anywhere on it turns it on or off, so it is best the row holding its box and its label. While it is on, it has Bevy's Checked marker, which a sheet's :checked selects: .toggle:checked > .toggle-box lights the box.
Slider
A Slider holds a value between the ends of its range. Drag its thumb, or press the track to put the thumb there and drag on. The arrows step it while it has focus. Track Click says what a press on the track does, and Orientation whether it lies down or stands up, worked out from its shape unless you say.
Slider Value
Slider Value is where it is now.
Slider Range
Slider Range is its Start and End, zero to one unless you set others.
Slider Step
Slider Step is how far a key moves it, one unless you set another. Give it a step to suit the range: with a range of zero to one, a step of 0.1 is ten steps.
Slider Thumb
Slider Thumb marks the element the engine moves along the slider as its value changes: the slider's Handle. Put it inside an element as long as the slider less the thumb's own width, as the Slider control's Track is, so the thumb ends where the slider does.
Scroll Area
A Scroll Area scrolls what is inside it with the mouse's wheel. Its Node's Overflow Y, or Overflow X, is set to Scroll. When focus moves to an element inside it by a key or a gamepad, the view scrolls to show it.
UI Text Field
A UI Text Field is typed into. Value is the text it starts with, which the player types over, and Max Characters how many it takes, zero for no limit. Its caret is drawn in its text's color, and its text is all picked as a key or a gamepad gives it focus, so what is typed replaces it. Submit, Enter or a gamepad's South button, submits it.
UI Dropdown
A UI Dropdown shows which of its options is picked and opens a list of them to pick another from. Its parts are elements of the document, drawn by its sheets like any other:
- UI Dropdown Label on an element under it: its text is made the picked option's.
- UI Dropdown List on the element that opens, hidden until it does.
- UI Dropdown Option on each option, in the order they are under it. An option's words are its own Text, or the first text inside it, so each option can be localized with its own Localize button.
Picked is the option picked, which the Inspector lists by the options' words; code reads it as the option's place among them, from 0. Opens says where the list opens:
| Opens | Where |
|---|---|
| Auto | In the middle of the screen on a phone, a tablet, or a browser on a touch screen; under the field anywhere else |
| Under the Field | Under the dropdown, or above it where the screen has no room below; at least as wide as the dropdown, and kept on the screen |
| Centered | In the middle of the screen, over a backdrop that covers the rest |
The list is drawn over everything, other documents too, and isn't cut off by a scroll view it's in. Give it a max-height in its sheet, and an overflow that scrolls, for a long list.
- The pointer: a click on the dropdown opens it. A click on an option picks it and closes the list. A click anywhere else, or on the backdrop, closes it as it was.
- Keys and a gamepad: Submit opens it with focus on the picked option, Up and Down move along the options, Submit picks one, and Cancel closes it as it was. While it's closed, Left and Right pick the option before or after without opening it.
While it's open, the dropdown has the class open and its list under or centered. The backdrop the engine puts behind a centered list has the class dropdown-backdrop. The picked option is :checked, and the one the keys are on :focus-visible:
.dropdown.open .dropdown-arrow { rotate: 180deg; }
.dropdown-list.centered { width: 80vw; max-width: 600px; max-height: 70vh; }
.dropdown-list.centered .dropdown-option { padding: 14px 16px; font-size: 22px; }
.dropdown-option:checked { font-weight: 600; }
.dropdown-backdrop { background-color: #05070e9e; }Its class hears each option the player picks. Code reads and sets Picked, gives it options of its own and binds it to a number; see Dropdowns.
UI Classes
UI Classes are the element's classes, apart by spaces, as an HTML element's are: what a sheet's .class selects. The document's Inspector lists every element's classes at once, and code changes them one at a time; see Classes.
Style Sheets
Style Sheets is on a document's top element: the sheets the document is styled by, in order, a later one's rules above an earlier one's. Drag a sheet by its grip to reorder it, × takes it away, and the slot below adds one. It is the same list as the document's Inspector shows, edited on the element while the document is open on its own. On a template's top inside a document, it names sheets that style that template's elements after the document's own.
See Style sheets for what goes in them.
Material
An element can be drawn by a material of your own, above its background and its image and below its text. The Material section is a slot: drop a material file on it, or pick one from the list, which shows only the project's UI materials. A material dropped on the canvas draws whatever element is on top where it lands.
A UI material runs a UI Shader, made with UI Shader in the Project panel's + menu in a shaders folder (see Shaders). Its fragment stage takes Bevy's UiVertexOutput: where in the element a pixel is, the element's size and its rounded corners. The template draws the element's color filled from its left as far as its fill says, which code sets; see Elements drawn by a material. A mesh's shader on an element draws it magenta, and the log says why.
Keys and a gamepad
The Input System's UI map works a document from the keyboard and a gamepad (see Input actions):
- Navigate, the arrows, the left stick or the pad's arrows, moves focus to the element in that direction, worked out from where the elements are drawn. Held, it moves on again after a moment.
- Submit, Enter or South, presses what has focus.
- Cancel, Escape or East, is heard by a modal document; see Modal documents.
- Tab goes through a document's elements in order.
A control keeps the keys it hears itself: Enter on a button, the arrows on a slider, and every key on a text field. A sheet's :focus-visible draws a ring round what has focus once a key or a stick has moved it. Buttons, toggles, sliders and text fields can have focus.
In the default actions, the UI map is off when the game starts. Switch it on for your menus with input.Enable(Actions.Maps.UI); a modal document switches it on by itself.
Where the guess from where elements are drawn is wrong, set where each direction goes in the document's Inspector, under Navigation: a row for each element that can have focus. Open one to pick where Up, Down, Left and Right go from it, another element by its name or Automatic for the guess, and to tick Focus First. While a row is shut, it says what it has set.
UI Navigation
UI Navigation keeps an element's directions, by the names of other elements of its document: Up, Down, Left and Right, empty for the guess. The document's Inspector writes it.
UI Focus First
UI Focus First marks the element that has focus as its document is shown, so a gamepad presses it at once. A document has one. A modal document gives focus to its first element that can have it where none is marked.
Documents in a scene
UI Document
A UI Document shows a document while the game plays. Make one with UI ▸ UI Document in the Hierarchy's + menu, or add it to any entity with Add Component:
| Field | What it does |
|---|---|
| Document | The .ui file shown, dropped on the slot or picked from a list |
| Sort Order | Of two documents drawn by one camera, the one of the higher order is drawn above |
| Modal | Holds the game while it is shown; see Modal documents |
On a camera, the document is drawn by that camera. On anything else, it is drawn by the game's camera of the highest order, which draws over the others.
While you edit the game, the Game panel shows the document as a preview: drawn, but with no class made and nothing heard. From Play it is the game's: its class is made and its controls work. At Stop it goes, and the preview is shown again. The pointer in the Game panel works it as the mouse does in a built game. Only the mouse's left button presses an element.
While the game plays, Show the Game's Interface in the Hierarchy's right-click menu lists the documents the game shows, template instances and all, under a heading of their own, to look at and pick.
Modal documents
A document whose UI Document is ticked Modal holds the game while it is shown, as a pause menu or an inventory does:
- focus stays inside it, and nothing under it can be picked;
- the game's input maps are off and the UI map on, until it goes, so the game does not move behind it;
- it gives focus to its element ticked Focus First, or its first that can have it, so a gamepad presses at once;
- the UI map's Cancel is heard by its class, as
OnCancel().
A key held as the document opens is not a press of the UI map until it is let go of, so the key that opened a menu does not also press something in it.
The screen documents are laid out for
A document is laid out for one screen size, the reference resolution, and scaled from there to the screen it is drawn on. Set it in Edit ▸ Project Settings… ▸ UI:
| Setting | What it does |
|---|---|
| Theme | The style sheet every document is styled by, beneath its own; see Style sheets |
| Reference Resolution | The screen documents are laid out for, in pixels: 1920 by 1080 unless you set another |
| Scale With Screen | Whether documents are scaled with the screen at all. Off, they are drawn at the window's own scale. |
| Match | How far the scale follows the screen's height rather than its width: Width at zero, Height at one, the default |
The settings are saved in settings/ui.json. A game's code can lay its interface out for another screen as it plays:
world.SetUiReference(1280, 720, matchHeight: 0.5f); // halfway between matching width and heightUI Panel
A UI Panel shows its entity's UI Document in the world, on a quad, rather than on the screen: a sign, a terminal, a menu on a wall. Make one with UI ▸ UI Panel in the Hierarchy's + menu; it brings the UI Document it needs.
| Field | What it does |
|---|---|
| Size | How big it is in the world, in world units, width and height: 1.6 by 0.9 to start |
| Pixels Per Unit | How many of the document's pixels a world unit holds: how sharp it is up close, 400 to start. The document is laid out for the reference resolution whatever it is. |
| Always On Top | Draws it over everything in front of it, and lets it be used through it |
| Flat | Draws it for a 2D camera, flat in the entity's XY plane as a sprite is |
The header says how many pixels the panel's picture is, at most 4096 either way. The picture has mipmaps, so text far off fades rather than shimmers. The panel faces along its entity's Z, and what stands in front of it hides it unless it is Always On Top. In the Scene panel, a panel is picked where it is drawn and outlined with its rectangle and a line out of its front.
The mouse works a panel as it works the screen, hovering, clicking, dragging and scrolling, where the cursor points at the panel's front and no element on the screen that shows anything is under the cursor. A slider dragged past the panel's edge keeps following the cursor.
Keys and a gamepad work the panel in front of the player, the one the middle of the screen looks at, or else the one seen nearest it. Submit with nothing focused engages it: its first element gets focus, the UI map comes on and the game's maps go off, and focus goes round that panel alone until Cancel lets go of it. A game whose UI map is off engages one from code; see Panels in the world.
UI Follow
A UI Follow beside an entity's UI Document puts the document's top element, each frame, where the camera draws a point of the entity: a health bar over a character, or a name over a head. It stays as sharp as the rest of the screen and is drawn over the world. Add it with Add Component.
| Field | What it does |
|---|---|
| Offset | Where the point followed is from the entity, in world units and the world's directions: (0, 2, 0) for two units up |
| Pivot | Which point of the top element sits on the point followed, in shares of its width and height from its top left: (0.5, 1), its bottom middle, to start |
The element is moved after layout, by its UI Transform, so following lays nothing out again. Where the point is behind the camera, or the entity is hidden, the element is moved off the screen.
Animate elements
An Animator on an element plays clips that move it and what is under it: its UI Transform, a color one part at a time, or a length of its Node in its own unit. A curve names an element by the names down to it from the Animator. What a clip wrote goes back as it stops, to what the sheets and the element say then. An Animator ticked Unscaled Time plays on real time, so a pause menu slides in while the game is paused.
In the Animation window, Create makes a clip for an element of the document open on its own, its Animator on Unscaled Time, and Record keys what you change in the Inspector or on the canvas. See UI elements in Animation clips.
In a built game
A build packs every UI document of the game and its packages, whether a scene reaches it or not, since code can open any of them by its class. Each goes in the main pack, or in its group's pack where it is addressable in a group of its own (see Packs), with what it reaches: its templates, its images, its sheets, the sheets they import and the fonts they name. The theme goes in the main pack. A built game draws its documents in its own window, laid out for the reference resolution and scaled to the window.
In the Scripting API
- UiView and UiElement: a document's class, and one of its elements.
- GameUi: the documents a game shows, opened and closed from code.
- UiSettings: the theme and the reference resolution,
settings/ui.json. - UiDocumentFiles: a
.uifile, read and written.
