Beginner's GUI Tutorial

Prerequisites (Requirements)

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.
• 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 recieve 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.

GUI Scripting - Documentation

All Elements have a Position and Size (exept 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 say 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.

GUI Scripting - 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 thier 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 simmilar to the positioning of the speed indecator 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 larrge 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 simmilar 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() statment. 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

(to be removed once wiki reference section is complete)

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

Frame

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

TextLabel

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

TextButton

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

ImageLabel

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

ImageButton

• MouseEnter (When the player first puts thier mouse over it)
• MouseLeave (When the player first takes thier mouse off of it)
• MouseMoved (When the player moves thier mouse on it)
• MouseButton1Click (When the player clicks it w/ left button)
• MouseButton1Down (When the player first holds thier left mouse button down)
• MouseButton1Up (When the player firsts lets go of thier left mouse button)
• MouseButton2Click (When the player clicks it w/ right button)
• MouseButton2Down (When the player holds thier right mouse button down)
• MouseButton2Up (When the player firsts lets go of right thier 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 thier mouse over it)
• MouseLeave (When the player first takes thier mouse off of it)
• MouseButton1Down (When the player first holds thier left mouse button down)
• MouseButton1Up (When the player firsts lets go of thier 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