Computer displays, mobile phones, and TV screens come in all shapes andsizes. To ship a game, you’ll need to support different screen ratiosand resolutions. It can be hard to build responsive interfaces thatadapt to all platforms. Thankfully, Godot comes with robust tools todesign and manage a responsive User Interface.
Godot’s editor is made with the engine’s UI framework
This guide will get you started with UI design. You will learn:
- The five most useful control nodes to build your games’ interface
- How to work with the anchor of UI elements
- How to efficiently place and arrange your user interface usingcontainers
- The five most common containers (at a later time, you can learn more about containers inthe GUI Containers documentation page).
To learn how to control the interface and connect it to other scripts,read Build your first game UI in Godot.
To design your UI, you’ll use the Control nodes. These are the nodes with green icons in theeditor. There are dozens of them, for creating anything from life bars tocomplex applications. Godot’s editor itself is built using Control nodes.
Control nodes have unique properties that allow them to work well with one another.Other visual nodes, like Node2D and Sprite don’t have these capabilities. So tomake your life easier use Control nodes wherever possible when building your UIs.
All control nodes share the same main properties:
- Anchor
- Bounding rectangle
- Focus and focus neighbor
- Size flags
- Margin
- The optional UI theme
Once you understand the basics of the Control node, it will take you less time to learn all thenodes that derive from it.
The 5 most common UI elements¶
Godot ships with dozens of Control nodes. A lot of them are here to helpyou build editor plugins and applications.
For most games, you’ll only need five types of UI elements, and a fewContainers. These five Control nodes are:
- Label: for displaying text
- TextureRect: used mostly for backgrounds, or everything that shouldbe a static image
- TextureProgress: for lifebars, loading bars, horizontal, vertical orradial
- NinePatchRect: for scalable panels
- TextureButton: to create buttons
The 5 most common Control nodes for UI design
TextureRect¶
TextureRect displays a texture or image inside a UI.It seems similar to the Sprite node, but it offers multiple scaling modes.Set the Stretch Mode property to change its behavior:
Scale On Expand (compat)
scales the texture to fit the node’s bounding rectangle,only ifexpand
property istrue
; otherwise, it behaves likeKeep
mode.Default mode for backwards compatibility.Scale
scales the texture to fit the node’s bounding rectangle.Tile
makes the texture repeat, but it won’t scale.Keep
andKeep Centered
force the texture to remain at itsoriginal size, in the top left corner or the center of the framerespectively.Keep Aspect
andKeep Aspect Centered
scales the texture but force it to remainits original aspect ratio, in the top left corner or the center of the frame respectively.Keep Aspect Covered
works just likeKeep Aspect Centered
but the shorter sidefits the bounding rectangle and the other one clips to the node’s limits.
As with Sprite nodes, you can modulate the TextureRect’s color. Clickthe Modulate
property and use the color picker.
TextureRect modulated with a red color
TextureButton¶
TextureButton is like TextureRect, except it has 5 texture slots:one for each of the button’s states. Most of the time, you’ll use theNormal, Pressed, and Hover textures. Focused is useful if your interfacelistens to the keyboard’s input. The sixth image slot, the Click Mask,lets you define the clickable area using a 2-bit, pure black and whiteimage.
In the Base Button section, you’ll find a few checkboxes that change howthe button behaves. When Toggle Mode
is on, the button will togglebetween active and normal states when you press it. Disabled
makes itdisabled by default, in which case it will use the Disabled
texture.TextureButton shares a few properties with the texture frame: it has amodulate
property, to change its color, and Resize
and Stretch
modes tochange its scale behavior.
TextureButton and its 5 texture slots
TextureProgress¶
TextureProgress layers up to 3 sprites to create a progress bar. TheUnder and Over textures sandwich the Progress one, which displays thebar’s value.
The Mode
property controls the direction in which the bar grows:horizontally, vertically, or radially. If you set it to radial, theInitial Angle
and Fill Degrees
properties let you limit the range of thegauge.
To animate the bar, you’ll want to look at the Range section. Set theMin
and Max
properties to define the range of the gauge. For instance,to represent a character’s life, you’ll want to set Min
to 0,
and Max
tothe character’s maximum life. Change the Value
property to update thebar. If you leave the Min
and Max
values to the default of 0
and 100,
and set the Value
property to 40
, 40% of the Progress
texture will showup, and 60% of it will stay hidden.
TextureProgress bar, two thirds filled
Label¶
Label prints text to the screen. You’ll find all its properties inthe Label section, in the Inspector. Write the text in the Text
property, and check Autowrap if you want it to respect the textbox’ssize. If Autowrap is off, you won’t be able to scale the node. You canalign the text horizontally and vertically with Align and Valign,respectively.
Picture of a Label
NinePatchRect¶
NinePatchRect takes a texture split in 3 rows and 3 columns. Thecenter and the sides tile when you scale the texture, but it neverscales the corners. It is useful to build panels, dialog boxesand scalable backgrounds for your UI.
NinePatchRect scaled with the min_size property
There are two workflows to build responsive UIs¶
There are two workflows to build scalable and flexible interfaces in Godot:
- You have many container nodes at your disposal that scale and place UI elements for you. They take control over their children.
- On the other side, you have the layout menu. It helps you to anchor, place and resize a UI element within its parent.
The two approaches are not always compatible. Because a container controls its children, you cannot use the layout menu on them. Each container has a specific effect, so you may need to nest several of them to get a working interface. With the layout approach you work from the bottom up, on the children. As you don’t insert extra containers in the scene it can make for cleaner hierarchies, but it’s harder to arrange items in a row, column, grid, etc.
As you create UIs for your games and tools, you’ll develop a sense for what fits best in each situation.
Place UI elements precisely with anchors¶
Control nodes have a position and size, but they also have anchors andmargins. Anchors define the origin, or the reference point, for theLeft, Top, Right and Bottom edges of the node. Change any of the 4anchors to change the reference point of the margins.
The anchor property
How to change the anchor¶
Like any properties, you can edit the 4 anchor points in the Inspector,but this is not the most convenient way. When you select a control node,the layout menu appears above the viewport, in the toolbar. It gives youa list of icons to set all 4 anchors with a single click, instead ofusing the inspector’s 4 properties. The layout menu will only show upwhen you select a control node.
The layout menu in the viewport
Anchors are relative to the parent container¶
Each anchor is a value between 0 and 1. For the left and top anchors, avalue of 0 means that without any margin, the node’s edges will alignwith the left and top edges of its parent. For the right and bottomedges, a value of 1 means they’ll align with the parent container’sright and bottom edges. On the other hand, margins represent a distanceto the anchor position in pixels, while anchors are relative to theparent container’s size.
Margins are relative to the anchor position, which is relative to theanchors. In practice, you’ll often let the container update marginsfor you
Margins change with the anchor¶
Margins update automatically when you move or resize a control node.They represent the distance from the control node’s edges to its anchor,which is relative to the parent control node or container. That’s whyyour control nodes should always be inside a container, as we’ll see ina moment. If there’s no parent, the margins will be relative to thenode’s own bounding Rectangle, set in the Rect section, in theinspector.
Margins on a CenterContainer set to the “Full Rect” anchor
Try to change the anchors or nest your Control nodes inside Containers:the margins will update. You’ll rarely need to edit the marginsmanually. Always try to find a container to help you first; Godot comeswith nodes to solve all the common cases for you. Need to add spacebetween a lifebar and the border of the screen? Use the MarginContainer.Want to build a vertical menu? Use the VBoxContainer. More on thesebelow.
Use size tags to change how UI elements fill the available space¶
Every control node has Size Flags. They tell containers how the UIelements should scale. If you add the “Fill” flag to the Horizontal orVertical property, the node’s bounding box will take all the space itcan, but it’ll respect its siblings and retain its size. If there are 3TextureRect nodes in an HBoxContainer, with the “Fill” flags on bothaxes, they’ll each take up to a third of the available space, but nomore. The container will take over the node and resize it automatically.
3 UI elements in an HBoxContainer, they align horizontally
The “Expand” flag lets the UI element take all the space it can, andpush against its siblings. Its bounding rectangle will grow against theedges of its parent, or until it’s blocked by another UI node.
The same example as above, but the center node has the “Expand” sizeflag
You’ll need some practice to understand the size tags, as their effectcan change quite a bit depending on how you set up your interface.
Arrange control nodes automatically with containers¶
Containers automatically arrange all children Control nodes includingother containers in rows, columns, and more. Use them to add paddingaround your interface or center nodes in their bounding rectangles. Allbuilt-in containers update in the editor, so you can see the effectinstantly.
Containers have a few special properties to control how they arrange UIelements. To change them, navigate down to the Custom Constants sectionin the Inspector.
The 5 most useful containers¶
If you build tools, you might need all of the containers. But for mostgames, a handful will be enough:
- MarginContainer, to add margins around part of the UI
- CenterContainer, to center its children in its bounding box
- VboxContainer and HboxContainer, to arrange UI elements in rows orcolumns
- GridContainer, to arrange Controls nodes in a grid-like pattern
CenterContainer centers all its children inside of its boundingrectangle. It’s one you typically use for title screens, if you want theoptions to stay in the center of the viewport. As it centers everything,you’ll often want a single container nested inside it. If you usetextures and buttons instead, they’ll stack up.
CenterContainer in action. The life bar centers inside its parentcontainer.
The MarginContainer adds a margin on any side of the child nodes. Add aMarginContainer that encompasses the entire viewport to add a separationbetween the edge of the window and the UI. You can set a margin on thetop, left, right, or bottom side of the container. No need to tick thecheckbox: click the corresponding value box and type any number. It willactivate automatically.
The MarginContainer adds a 40px margin around the Game User Interface
There are two BoxContainers: VBoxContainer and HBoxContainer. You cannotadd the BoxContainer node itself, as it is a helper class, but you canuse vertical and horizontal box containers. They arrange nodes either inrows or columns. Use them to line up items in a shop, or to buildcomplex grids with rows and columns of different sizes, as you can nestthem to your heart’s content.
The HBoxContainer horizontally aligns UI elements
VBoxContainer automatically arranges its children into a column. It putsthem one after the other. If you use the separation parameter, it willleave a gap between its children. HBoxContainer arranges UI elements ina row. It’s similar to the VBoxContainer, with an extra add_spacer
method to add a spacer control node before its first child or after itslast child, from a script.
The GridContainer lets you arrange UI elements in a grid-like pattern.You can only control the number of columns it has, and it will set thenumber of rows by itself, based on its children’s count. If you havenine children and three columns, you will have 9÷3 = 3 rows. Add threemore children and you’ll have four rows. In other words, it will createnew rows as you add more textures and buttons. Like the box containers,it has two properties to set the vertical and horizontal separationbetween the rows and columns respectively.
A GridContainer with 2 columns. It sizes each column automatically.
Godot’s UI system is complex, and has a lot more to offer. To learn howto design more advanced interfaces, head to the GUI section of the docs.