# GUI

## Overview <a href="#overview" id="overview"></a>

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 <a href="#gui-types" id="gui-types"></a>

<table><thead><tr><th width="234">Object</th><th>Description</th></tr></thead><tbody><tr><td>ScreenGui</td><td>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.</td></tr><tr><td>SurfaceGui</td><td>An object used to display 2D UI in a 3D space. Attaches GUI elements to in-game surfaces or objects for interactive purposes.</td></tr><tr><td>BillboardGui</td><td>BillboardGui is an object that displays 2D UI in 3D space, always facing the camera. Because it constantly rotates to align with the player's view, it's commonly used for elements like name tags, health bars, and dialogue boxes.</td></tr><tr><td>Frame</td><td>A 2D object used for designing layouts or grouping elements such as TextLabel, TextButton, ImageLabel, ImageButton.</td></tr><tr><td>ScrollingFrame</td><td>A 2D-based object that provides a scrollable layout. It enables all contained objects to be displayed on screen through scrolling functionality.</td></tr><tr><td>TextLabel</td><td>An object that displays text.</td></tr><tr><td>ImageLabel</td><td>An object that displays images.</td></tr><tr><td>TextButton</td><td>A button that displays text.</td></tr><tr><td>ImageButton</td><td>A button that displays images.</td></tr><tr><td>UIAspectRatioConstraint</td><td>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.</td></tr><tr><td>UIListLayout</td><td>An object that arranges child objects within a parent object in a list format, evenly spaced.</td></tr><tr><td>UIGridLayout</td><td>An object that arranges child objects within a parent in a grid format, using consistent sizes and spacing.</td></tr></tbody></table>

## ScreenGui Properties <a href="#screengui-properties" id="screengui-properties"></a>

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Enabled</td><td>Determines whether all child objects of the ScreenGui are displayed on the screen.</td></tr><tr><td>DisplayOrder</td><td>Determines which ScreenGui will be displayed on top of the screen. Higher value indicates higher priority, making the ScreenGui appear above others.</td></tr></tbody></table>

## SurfaceGui Properties <a href="#surfacegui-properties" id="surfacegui-properties"></a>

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

## BillboardGui Properties

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Enabled</td><td>Controls whether all objects parented to a BillboardGui are visible on the screen.</td></tr><tr><td>Always on Top</td><td>Sets the BillboardGui to always render on top of other 3D objects.</td></tr><tr><td>Light Influence</td><td>Specifies how much the BillboardGui is affected by lighting.</td></tr><tr><td>Brightness</td><td>Sets the brightness applied to the BillboardGui. Higher values make it appear brighter, which is useful for visual emphasis without interaction with 3D lighting. (This can be set only when Light Influence is less than 1.)</td></tr><tr><td>Max Distance</td><td>Sets the maximum distance at which the BillboardGui remains visible to the player.</td></tr><tr><td>Distance Lower Limit</td><td>Sets the distance at which the BillboardGui stops scaling up when it gets too close to the player's camera.</td></tr><tr><td>Distance Upper Limit</td><td>Sets the distance at which the BillboardGui stops scaling down when it gets too far from the player's camera.</td></tr><tr><td>Active</td><td>Determines whether UI elements within the BillboardGui, such as buttons and text boxes, can process clicks, touches, or keyboard input.</td></tr><tr><td>Adornee</td><td>Specifies the object on which the BillboardGui is rendered.</td></tr><tr><td>Clips Descendants</td><td>Specifies whether child UI elements are clipped when they extend beyond the boundaries of the parent GUI. If true, any elements outside the boundaries will not be visible.</td></tr><tr><td>Size</td><td>Sets the size of BillboardGui.</td></tr><tr><td>Position Offset</td><td>Sets the offset from rendering object based on camera.</td></tr><tr><td>Position Offset World Space</td><td>Sets the offset from rendering object based on target object.</td></tr><tr><td>Extents Offset World Space</td><td>Sets the offset from the rendered object in world coordinates. (The value's unit is based on half the size of the model)<br>Adjusts the position of the BillboardGui based on the target's size (Extents). This is useful for naturally placing UI elements such as health bars above characters, as the position automatically adapts to different model sizes.<br>The offset is applied along the target's axes (the parent Part or Adornee) by multiplying the input value (Vector3) with half of the bounding box length (Extents) on each axis.</td></tr><tr><td>Size Offset</td><td>Sets the offset from rendering object based on screen plane.</td></tr></tbody></table>

## Gui Element Properties <a href="#gui-element-properties" id="gui-element-properties"></a>

### Common Properties <a href="#common-properties" id="common-properties"></a>

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Position</td><td><p>Defines the position of the object on the screen.</p><p>It uses the UDim2 format, where you can input ScaleX, OffsetX, ScaleY, and OffsetY in order.</p><ul><li>Scale: A ratio between 0.0 and 1.0, where 0.1 represents 10%.</li><li>Offset: Set in pixels, where 10 represents 10 pixels.</li></ul><p>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.</p></td></tr><tr><td>Rotation</td><td>Adjusts the rotation angle of the object, where 360.0 represents 360 degrees.</td></tr><tr><td>Size</td><td>Defines the size of the object. Uses the UDim2 format similar to Position.</td></tr><tr><td>Visible</td><td>Determines whether the object is visible or hidden.</td></tr><tr><td>Anchor Point</td><td>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.</td></tr><tr><td>ZIndex</td><td>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.</td></tr><tr><td>Clips Descendants</td><td>Clips Descendants: This property determines whether to display the clipped area on the screen if a child UI element clips its parent's UI area.</td></tr></tbody></table>

### Frame <a href="#frame" id="frame"></a>

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Border Pixel Size</td><td>Defines the thickness of the frame's border.</td></tr><tr><td>Border Mode</td><td>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).</td></tr><tr><td>Border Color 3</td><td>Sets the color of the border.</td></tr><tr><td>Background Color 3</td><td>Sets the background color of the frame.</td></tr><tr><td>Background Trnasparency</td><td>Adjusts the background transparency of the frame.</td></tr></tbody></table>

### TextLabel <a href="#textlabel" id="textlabel"></a>

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Text</td><td>Allows you to input the text to be displayed.</td></tr><tr><td>TextScaled</td><td>Automatically adjusts the text size to fit the object's size, ignoring the Text Size value.</td></tr><tr><td>Bold</td><td>Defines the thickness of the displayed text.</td></tr><tr><td>Text Size</td><td>Defines the size of the displayed text in pixels.</td></tr><tr><td>Text Color 3</td><td>Sets the color of the displayed text.</td></tr><tr><td>Text Transparency</td><td>Adjusts the transparency of the displayed text.</td></tr><tr><td>Background Color 3</td><td>Sets the background color.</td></tr><tr><td>Background Transparency</td><td>Adjusts the background transparency.</td></tr></tbody></table>

### ImageLabel <a href="#imagelabel" id="imagelabel"></a>

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Image</td><td>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.</td></tr><tr><td>Image Transparency</td><td>Adjusts the transparency of the image.</td></tr><tr><td>Background Color 3</td><td>Sets the background color.</td></tr><tr><td>Background Transparency</td><td>Adjusts the background transparency.</td></tr></tbody></table>

### TextButton <a href="#textbutton" id="textbutton"></a>

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Text</td><td>Allows you to input the text to be displayed.</td></tr><tr><td>TextScaled</td><td>Automatically adjusts the text size to fit the object's size, ignoring the Text Size value.</td></tr><tr><td>Bold</td><td>Defines the thickness of the displayed text.</td></tr><tr><td>Text Size</td><td>Defines the size of the displayed text in pixels.</td></tr><tr><td>Text Color 3</td><td>Sets the color of the displayed text.</td></tr><tr><td>Text Transparency</td><td>Adjusts the transparency of the displayed text.</td></tr><tr><td>Background Color 3</td><td>Sets the background color.</td></tr><tr><td>Background Transparency</td><td>Adjusts the background transparency.</td></tr></tbody></table>

### ImageButton <a href="#imagebutton" id="imagebutton"></a>

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Image</td><td>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.</td></tr><tr><td>Image Transparency</td><td>Adjusts the transparency of the image.</td></tr><tr><td>Background Color 3</td><td>Sets the background color.</td></tr><tr><td>Background Transparency</td><td>Adjusts the background transparency.</td></tr></tbody></table>

### UIAspectRatioConstraint <a href="#uiaspectratioconstraint" id="uiaspectratioconstraint"></a>

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.

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Aspect Ratio</td><td>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.</td></tr><tr><td>Aspect Type</td><td><p>Determines how the UI element maintains its aspect ratio.</p><ul><li>FitWithinMaxSize : The UI element maintains its ratio while shrinking within the maximum size</li><li>ScaleWithParentSize : The UI element adjusts its ratio based on the parent's size</li><li>SizeRelativeXY : Maintains relative size in both the X and Y directions</li></ul></td></tr><tr><td>Dominant Axis</td><td><p>Determines which axis to prioritize when maintaining the ratio as the UI size changes.</p><ul><li>Width : Adjusts the height based on the width.</li><li>Height : Adjusts the width based on the height.</li></ul></td></tr></tbody></table>

### ScrollingFrame

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>AutomaticCanvasSize</td><td><p>Determines whether to automatically adjust the CanvasSize based on the size of child objects.</p><ul><li>None: No automatic adjustment</li><li>X: Automatic adjustment in the horizontal direction</li><li>Y: Automatic adjustment in the vertical direction</li><li>XY: Automatic adjustment in both horizontal and vertical directions</li></ul></td></tr><tr><td>CanvasSize</td><td>This property sets the size of the scrollable inner area.</td></tr><tr><td>CanvasPosition</td><td>This property allows manual setting or checking of the scroll position.</td></tr><tr><td>ScrollBarImageColor3</td><td>This property sets the image color of the scrollbar.</td></tr><tr><td>ScrollBarImageTransparency</td><td>This property sets the image transparency of the scrollbar.</td></tr><tr><td>ScrollBarThickness</td><td>This property sets the width of the scrollbar in pixels.</td></tr><tr><td>ScrollingDirection</td><td><p>This property sets the scroll direction.</p><ul><li>X: Horizontal scroll</li><li>Y: Vertical scroll</li><li>XY: Both horizontal and vertical scroll</li></ul></td></tr><tr><td>ScrollingEnabled</td><td>This property enables or disables the scrolling function.</td></tr></tbody></table>

### UIListLayout

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>Padding</td><td>Specifies the spacing between UI elements.</td></tr><tr><td>Wraps</td><td>This property determines whether to automatically wrap to the next line.</td></tr><tr><td>FillDirection</td><td><p>Specifies the direction in which UI elements are arranged.</p><ul><li>Horizontal: Arranged horizontally</li><li>Vertical: Arranged vertically</li></ul></td></tr><tr><td>SortOrder</td><td><p>Specifies the way UI elements are sorted.</p><ul><li>LayoutOrder: Sorts by LayoutOrder value for each instance</li><li>Name: Sorts by name</li></ul></td></tr><tr><td>HorizontalAlignment</td><td><p>Specifies the horizontal alignment.</p><ul><li>Left: Align left</li><li>Center: Center</li><li>Right: Align right</li></ul></td></tr><tr><td>VerticalAlignment</td><td><p>Specifies the vertical alignment.</p><ul><li>Top: Top align</li><li>Center: Center</li><li>Bottom: Bottom align</li></ul></td></tr></tbody></table>

### UIGridLayout

<table><thead><tr><th width="234">Property</th><th>Description</th></tr></thead><tbody><tr><td>CellPadding</td><td>Specifies the spacing between cells.</td></tr><tr><td>CellSize</td><td>Specifies the size of a cell.</td></tr><tr><td>FillDirectionMaxCells</td><td>Specifies the maximum number of cells to be filled in the specified direction.</td></tr><tr><td>FillDirection</td><td><p>Specifies the direction in which UI elements are arranged.</p><ul><li>Horizontal: Arranged horizontally</li><li>Vertical: Arranged vertically</li></ul></td></tr><tr><td>SortOrder</td><td><p>Specifies the way UI elements are sorted.</p><ul><li>LayoutOrder: Sorts by LayoutOrder value for each instance</li><li>Name: Sorts by name</li></ul></td></tr><tr><td>HorizontalAlignment</td><td><p>Specifies the horizontal alignment.</p><ul><li>Left: Align left</li><li>Center: Center</li><li>Right: Align right</li></ul></td></tr><tr><td>VerticalAlignment</td><td><p>Specifies the vertical alignment.</p><ul><li>Top: Top align</li><li>Center: Center</li><li>Bottom: Bottom align</li></ul></td></tr></tbody></table>