Beginner's GUI Tutorial

Prerequisites

You should have a basic knowledge of a cartesian coordinate plane and some knowledge on scripting to understand this guide. This guide is focused toward scripters and high-end world creators.

Introduction

A GUI is a graphical user interface. It is how humans interact with computers. The pictures you see, the stuff you click, and even the keys you press are all part of your computer's GUI.

A 3D games's GUI is basically consists 2D plane of images and text in a 3D world. Roblox's GUI consists of text, images, and boxes of various colors and size.

Roblox's system

When Roblox first introduced it's new GUI System, it brought with it a new game service, the StarterGui. This is simmilar to a starter pack, only for a GUI. In the player, a new type of Backpack was created: the PlayerGui. This instance is specifically for storing the GUI elements that only a player can see. It can be found in any Player and is named PlayerGui by default.

Roblox's GUI includes GUI elements that draw certain items on the screen. They are:

• BillboardGui - objects that can stick onto 3D parts
• Frame - Creates a box with a background color and border color. When an object is parented under a Frame, the object's position will be relative to the position of the parenting Frame.
• TextLabel - Simply a Frame with a Text property and a TextColor property.
• TextButton - The same as a TextLabel, however it has events with it that recieve user input in mouse-type formats.
• ImageLabel - Simply an Image with a Texture that it draws on the screen. It can be scaled to any size, and also have a background.
• ImageButton - An ImageLabel with events with it that receives user input in mouse-type formats.
• SelectionBox - An element that has a property called "Adornee" that must be set to a brick. It then renders a selection box in a desired color.
• Handles - An element that has a property called "Adornee" that must be set to a brick. It then renders either the drag on axis handles or the resize tool handles. You can change what faces get handles (eg, only top and bottom), and you can also use the events with it that detect mouse input (dragging, clicking, mouseover).

In order to prevent confusion with drawing the images on the screen, all elements must be placed in a new type of Instance called the "ScreenGui". If an element is not a child of the ScreenGui, it will not display. ScreenGuis are commonly placed in the StarterGui, players' PlayerGuis and the Workspace. If the ScreenGui is in a PlayerGui, it will only display to that one player. If it is in the Workspace, it will display to all players.

Documentation

All elements have a Position and a Size (except for SelectionBoxes and Handles). These Positions and Sizes are 2D, so Roblox created a new data type similar to Vector3 and CFrame. It is called UDim2. Like Vector3 and CFrame, to create another UDim2, you use UDim2.new.

You must take note of the fact that your screen has an invisible grid, like a cartesian coordinate plane! You must know that point (0,0) is not in the bottom left, it is in the top-left. If you forget this, you may position things off the screen and think it is not working.

The UDim2.new() function requires four arguments. The first two are for the X value, and the second two are for the Y value. The X values represent the X axis (horizontal), and the Y values represent the Y axis (vertical). The first X value is X scale. A scale value is simply a value relative to the screen's total size. Setting this to 1, is setting the object to the right side of the screen, 0.5 is the half-way mark of the screen. Using scale is useful for making completion or experience bars. The second X value is X offset. Offset is a specific number that sets the position or size of an object. The greater the X offset, the further right on the screen the UDim is. This is useful when the size of the screen doesn't matter, and precise positions and sizes can be measured. The last two arguments are the Y scale, and the Y offset, respectively.

Roblox's GUI elements all have a Position and Size (as stated before). Positioning elements on the screen is fairly easy. If you change the Y Scale and X Scale of an element's Position to 0.5, it will position the element based on the center of the screen. Setting the X Scale and Y Scale of an element's Position to 1 will base the Offset from the bottom left of the screen.

Techniques

You are probably thinking "I just want to know how to create ____!". This is where you might find out this information. See the folowing subsections to learn how to do basic actions, then more complicated.

Positioning an element

You can use code to position an element on someone's screen based on a numberic value, or based on a ratio on their screen. To position an element at the point (100,100), you would use the folowing code.

element.Position = UDim2.new(0, 100, 0, 100)

Note that the first and third arguments are Scale and not Offset. Offset is what you want to use if you are thinking of pixels. Using Offset will not generate a difference between computer screens.

If you wanted to position an element by "screens" not "pixels" (like, put an element a quarter of a "screen" to the left and down), you would use scale.

element.Position = UDim2.new(0.25,0,0.25,0)

Note that using scale will generate a difference between computer screens. If you screen is large, then the look will be different than a small computer screen. If you wanted to position something in the center of the screen, then use this code to say "I want one-half screens on X and Y, then go down by 50 pixels". This is similar to the positioning of the speed indicator on a VehicleSeat.

element.Position = UDim2.new(0.5,0,0.5,-50)

Resizing an element

If you want to make an element bigger, smaller, or just right, you need to do the same thing with Position as you would with Size. Size uses UDim2.new() just like Position. If you wanted something half the WIDTH of your computer screen, then you'de say something like this:

element.Size = UDim2.new(0.5, 0, 0.5, 0)

If the element was positioned at 0,0, it would appear as the top left of your screen is hidden from view! Now, what if you wanted to make the screen all the color of the element's background? You'll need to streach the size of the element to 1 screen wide, and 1 screen tall, by doing this:

element.Size = UDim2.new(1, 0, 1, 0)

However, not a lot of people use Scale (or "screens") to size objects because it varies too much. If you had a TextLabel, and wanted a border around the text, you would use a Y Offset of 15, because the size of the font is 12 that Roblox uses.

element.Size = UDim2.new(0,X,0,15)

Look at how there is an X in that line. You must replace X with a large enough number to make the background be wide enough to cover the whole text. If your text is someone's username, then you should use around 50. If it's a sentence, you may need more length.

Applying button principles

If you didn't want a button to walk on for a regen, you might want to use a GUI TextButton. To do this, you use the events that the TextButton and ImageButton have. Here is an example. It looks extremely similar to a touch script.

function onClick() 
	print("Clicked") 
end 
 
element.MouseButton1Click:connect(onClick)

Do you see where it says "MouseButton1Click"? That can be changed to 9 different events (see the reference section). Button1 is the Left Mouse Button and Button2 is the Right Mouse Button. For more details on the different events for the Elements, see the reference section

Applying mapping principles

...Or a Radar or minimap. They are all similar. This is fairly simple. You use a Frame to represent the baseplate and boxes to represent the objects on the map. You would use a while true do statement to have the map be constantly updated. For the folowing example, put a brick in your place called "Target", and you will see how it is done.

brick = Workspace.Target 
while true do 
	wait(0.1) --how many seconds between updates 
	script.Parent.Position = UDim2.new(0.5,brick.Position.x,0.5,brick.Position.z) 
end

Look at the UDim2.new() statement. It's first and third arguments are 0.5, so the position is based on the middle of the screen (or one-half screens down from the top left and one half to the right of the top left). Then the second and fourth arguments are the Brick's position x and z. Now move around your brick.

To make a minimap, apply this concept to all the players in a game :)

Motion to elements

You might want to have text scroll accross the top of your screen. This can be easily done by changing the Position of something relative (meaning "adding" or "offsetting by") to it's current position. This would make something move accross the screen. Remember that "G" is the changing number.

g = 1 
speed = 0.01 
while true do 
	g = g - speed 
	element.Position = UDim2.new(g,0,0,250) 
	if g < -0.1 then 
		g = 1 
	end 
	wait() 
end

Play around with this code to discover new cool things!

GUIs can also be changed smoothly by tweening their position and/or size.

Reference section

This is basically all the elements and their events. Use the :connect() function to do things when these events fire. You can find a lot more information if you go to the object browser.

Frame

• MouseEnter (When the player first puts their mouse over it)
• MouseLeave (When the player first takes their mouse off of it)
• MouseMoved (When the player moves their mouse on it)

TextLabel

• MouseEnter (When the player first puts their mouse over it)
• MouseLeave (When the player first takes their mouse off of it)
• MouseMoved (When the player moves their mouse on it)

TextButton

• MouseEnter (When the player first puts their mouse over it)
• MouseLeave (When the player first takes their mouse off of it)
• MouseMoved (When the player moves their mouse on it)
• MouseButton1Click (When the player clicks it w/ left button)
• MouseButton1Down (When the player first holds their left mouse button down)
• MouseButton1Up (When the player firsts let's go of their left mouse button)
• MouseButton2Click (When the player clicks it w/ right button)
• MouseButton2Down (When the player holds their right mouse button down)
• MouseButton2Up (When the player firsts let's go of right their mouse button)

ImageLabel

• MouseEnter (When the player first puts their mouse over it)
• MouseLeave (When the player first takes their mouse off of it)
• MouseMoved (When the player moves their mouse on it)

ImageButton

• MouseEnter (When the player first puts their mouse over it)
• MouseLeave (When the player first takes their mouse off of it)
• MouseMoved (When the player moves their mouse on it)
• MouseButton1Click (When the player clicks it w/ left button)
• MouseButton1Down (When the player first holds their left mouse button down)
• MouseButton1Up (When the player firsts let's go of their left mouse button)
• MouseButton2Click (When the player clicks it w/ right button)
• MouseButton2Down (When the player holds their right mouse button down)
• MouseButton2Up (When the player firsts let's go of right their mouse button)

SelectionBox

• Changed (When a script changes any property, use this with the adornee)

Handles

• Changed (When a script changes any property, use this with the adornee)
• MouseEnter (When the player first puts their mouse over it)
• MouseLeave (When the player first takes their mouse off of it)
• MouseButton1Down (When the player first holds their left mouse button down)
• MouseButton1Up (When the player firsts let's go of their left mouse button)
• MouseDrag (When the player drags the cursor while holding left button down)

See also

If you're looking for something similar or closely related to this article, see these:

• Beginner's Guide to GUI