GUI

Overview

GUI refers to graphical elements within the game that allow interaction with players. Using GUI, you can add various elements such as buttons, text, images, and progress bars to the game screen.

GUI Types

Object	Description
ScreenGui	An object used to display 2D-based elements on the screen. 2D objects such as Frame, TextButton, ImageButton, etc., must be children of Gui objects such as ScreenGui/SurfaceGui objects to be rendered. ScreenGui itself does not display any information.
SurfaceGui	An object used to display 2D UI in a 3D space. Attaches GUI elements to in-game surfaces or objects for interactive purposes.
Frame	A 2D object used for designing layouts or grouping elements such as TextLabel, TextButton, ImageLabel, ImageButton.
TextLabel	An object that displays text.
ImageLabel	An object that displays images.
TextButton	A button that displays text.
ImageButton	A button that displays images.
UIAspectRatioConstraint	Provides the functionality to set the aspect ratio of 2D-based objects. If you want to set the aspect ratio for objects like Frame, ImageLabel, ImageButton, or TextButton, you can add a UIAspectRatioConstraint as a child and adjust the ratio. The ratio will be maintained based on the current size of the parent object.

ScreenGui Properties

Property	Description
Enabled	Determines whether all child objects of the ScreenGui are displayed on the screen.

SurfaceGui Properties

Object	Description
Enabled	Determines whether all child objects of the SurfaceGui are displayed on the screen.
Always on Top	Ensures that the SurfaceGui is always rendered on top of other 3D objects.
Light Influence	Controls how much the SurfaceGui is affected by lighting.
Max Distance	Sets the maximum distance at which the SurfaceGui remains visible to the player.
Active	Determines whether UI elements within the SurfaceGui, such as buttons and text boxes, can process clicks, touches, or keyboard input.
Adornee	Specifies the object on which the SurfaceGui is rendered.
Face	Determines which face of the part the GUI is displayed on.

Gui Element Properties

Common Properties

Object	Description
Position	Defines the position of the object on the screen. It uses the UDim2 format, where you can input ScaleX, OffsetX, ScaleY, and OffsetY in order. Scale: A ratio between 0.0 and 1.0, where 0.1 represents 10%. Offset: Set in pixels, where 10 represents 10 pixels. The Scale and Offset values are combined to determine the on-screen position. For example, if ScaleX is 0.25 and OffsetX is 10, the object will move 25% to the right from the Anchor Point (the center point of the Frame) and an additional 10 pixels to the right.
Rotation	Adjusts the rotation angle of the object, where 360.0 represents 360 degrees.
Size	Defines the size of the object. Uses the UDim2 format similar to Position.
Visible	Determines whether the object is visible or hidden.
Anchor Point	Defines the object's anchor point. It uses a Vector2 format, and the default (0.0, 0.0) sets the top-left corner as the anchor point.
ZIndex	Determines the stacking order of UI elements. If FrameA is obscured by FrameB, you can use the ZIndex value to ensure FrameA appears above FrameB.

Frame

Object	Description
Border Pixel Size	Defines the thickness of the frame's border.
Border Mode	A property that determines how the border is displayed relative to the Frame's edge. You can set it to Insert (inside), Middle (center), or Outline (outside).
Border Color 3	Sets the color of the border.
Background Color 3	Sets the background color of the frame.
Background Trnasparency	Adjusts the background transparency of the frame.

TextLabel

Object	Description
Text	Allows you to input the text to be displayed.
TextScaled	Automatically adjusts the text size to fit the object's size, ignoring the Text Size value.
Bold	Defines the thickness of the displayed text.
Text Size	Defines the size of the displayed text in pixels.
Text Color 3	Sets the color of the displayed text.
Text Transparency	Adjusts the transparency of the displayed text.
Background Color 3	Sets the background color.
Background Transparency	Adjusts the background transparency.

ImageLabel

Object	Description
Image	Sets the AssetId of the image to be displayed. You can use the AssetId of an image registered in the Asset Manager or Asset Drawer.
Image Transparency	Adjusts the transparency of the image.
Background Color 3	Sets the background color.
Background Transparency	Adjusts the background transparency.

TextButton

Object	Description
Text	Allows you to input the text to be displayed.
TextScaled	Automatically adjusts the text size to fit the object's size, ignoring the Text Size value.
Bold	Defines the thickness of the displayed text.
Text Size	Defines the size of the displayed text in pixels.
Text Color 3	Sets the color of the displayed text.
Text Transparency	Adjusts the transparency of the displayed text.
Background Color 3	Sets the background color.
Background Transparency	Adjusts the background transparency.

ImageButton

Object	Description
Image	Sets the AssetId of the image to be displayed. You can use the AssetId of an image registered in the Asset Manager or Asset Drawer.
Image Transparency	Adjusts the transparency of the image.
Background Color 3	Sets the background color.
Background Transparency	Adjusts the background transparency.

UIAspectRatioConstraint

When the size of an ImageLabel is set to { 0.5, 0, 0.5, 0 }, or 50% of the client device’s size on both the X and Y axes, adding a UIAspectRatioConstraint as a child and setting its Aspect Ratio property to 1.0 ensures the ImageLabel maintains a 1:1 ratio. This prevents the image from stretching horizontally or vertically.

Object	Description
Aspect Ratio	Sets the desired ratio of the parent object. The default value is 1.0, where the X and Y axes maintain a 1:1 ratio.
Aspect Type	Determines how the UI element maintains its aspect ratio. FitWithinMaxSize : The UI element maintains its ratio while shrinking within the maximum size ScaleWithParentSize : The UI element adjusts its ratio based on the parent's size SizeRelativeXY : Maintains relative size in both the X and Y directions
Dominant Axis	Determines which axis to prioritize when maintaining the ratio as the UI size changes. Width : Adjusts the height based on the width. Height : Adjusts the width based on the height.