GUI

개요

GUI는 게임 내에서 플레이어와 상호작용할 수 있는 그래픽 요소를 의미합니다. GUI를 활용하면 버튼, 텍스트, 이미지, 진행 바 등 다양한 요소를 게임 화면에 추가할 수 있습니다.

종류

오브젝트	설명
ScreenGui	2D 기반 오브젝트들을 화면에 보여주기 위한 오브젝트입니다. 2D 기반 오브젝트인 Frame, TextButton, ImageButton 등은 ScreenGui/SurfaceGui 등 Gui 오브젝트의 자식으로 존재해야만 화면에 표시됩니다. ScreenGui 자체는 화면에 어떠한 정보도 표시하지 않습니다.
SurfaceGui	Surface GUI는 3D 공간에서 2D UI를 보여주기 위한 오브젝트입니다. 게임 내의 표면이나 오브젝트에 GUI를 붙여서 상호작용을 가능하게 합니다.
BillboardGui	Billboard Gui는 2D UI를 3D 공간에서 항상 카메라를 향하도록 표시해주는 오브젝트입니다. 이 GUI는 항상 플레이어의 시선 방향을 향해 회전하므로 주로 이름표, 체력바, 대화창 등에 활용됩니다.
Frame	레이아웃을 디자인 하거나 TextLabel, TextButton, ImageLabel, ImageButton 등의 오브젝트를 그룹화할 수 있는 기능을 제공하는 2D 기반 오브젝트입니다.
TextLabel	텍스트를 표시할 수 있는 오브젝트입니다.
ImageLabel	이미지를 표시할 수 있는 오브젝트입니다.
TextButton	텍스트를 표시할 수 있는 버튼입니다.
ImageButton	이미지를 표시할 수 있는 버튼입니다.
UIAspectRatioConstraint	2D 기반 오브젝트들의 가로 세로 비율을 설정할 수 있는 기능을 제공하는 오브젝트입니다. Frame/ImageLabel/ImageButton/TextButton 등의 비율 설정을 원할 경우, 자식으로 UIAspectRatioConstraint를 두고 비율을 수정할 수 있습니다. 부모 오브젝트의 현재 Size를 기준으로 비율을 유지하게 됩니다.

ScreenGui의 프로퍼티

프로퍼티	설명
Enabled	ScreenGui가 자식으로 하는 모든 오브젝트를 화면에서 보여줄 지 여부를 변경할 수 있습니다.
DisplayOrder	어떤 ScreenGui가 화면의 위쪽에 표시될지 결정합니다. 값이 클수록 우선순위가 높아지며, 위쪽에 표시됩니다.

SurfaceGui의 프로퍼티

프로퍼티	설명
Enabled	SurfaceGui가 자식으로 하는 모든 오브젝트를 화면에서 보여줄 지 여부를 변경할 수 있습니다.
Always on Top	다른 3D 오브젝트 위에 항상 SurfaceGui가 렌더링되도록 설정합니다.
Light Influence	SurfaceGUI가 조명에 영향을 받는 정도를 설정합니다.
Max Distance	SurfaceGUI가 플레이어로부터 멀리 떨어져 있어도 보일 수 있는 최대 거리를 설정하는 데 사용됩니다.
Active	SurfaceGUI에 포함된 버튼, 텍스트 박스 등과 같은 UI 요소들이 클릭, 터치 또는 키보드 입력을 처리할 수 있는지 여부를 결정합니다.
Adornee	SurfaceGUI가 렌더링되는 오브젝트를 설정합니다.
Face	Part의 어느 면에 GUI가 표시될지를 설정합니다.

BillboardGui의 프로퍼티

프로퍼티	설명
Enabled	BillboardGui가 자식으로 하는 모든 오브젝트를 화면에서 보여줄 지 여부를 변경할 수 있습니다.
Always on Top	다른 3D 오브젝트 위에 항상 BillboardGui가 렌더링되도록 설정합니다.
Light Influence	BillboardGui가 조명에 영향을 받는 정도를 설정합니다.
Brightness	BillboardGui에 적용되는 밝기입니다. 숫자가 클수록 더 밝게 표시되며, 3D 조명과의 상호작용 없이 시각적으로 강조할 때 유용합니다. (Light Influence가 1 미만이면 설정할 수 있습니다.)
Max Distance	BillboardGui가 플레이어로부터 멀리 떨어져 있어도 보일 수 있는 최대 거리를 설정하는 데 사용됩니다.
Distance Lower Limit	BillboardGui가 플레이어의 카메라에 너무 가까워졌을 때, 더 이상 확대되지 않도록 제한하는 거리입니다.
Distance Upper Limit	BillboardGui가 플레이어의 카메라로부터 멀어질 때, 더 이상 작아지지 않도록 제한하는 거리입니다.
Active	BillboardGui에 포함된 버튼, 텍스트 박스 등과 같은 UI 요소들이 클릭, 터치 또는 키보드 입력을 처리할 수 있는지 여부를 결정합니다.
Adornee	BillboardGui가 렌더링되는 오브젝트를 설정합니다.
Clips Descendants	하위 UI 요소들이 부모 GUI의 경계를 벗어났을 때 잘릴지 여부를 설정합니다. true일 경우 경계를 벗어난 요소는 보이지 않습니다.
Size	BillboardGui의 크기를 설정합니다.
Position Offset	렌더링되는 오브젝트로부터의 오프셋을 로컬 좌표 기준으로 설정합니다.
Position Offset World Space	렌더링되는 오브젝트로부터의 오프셋을 월드 좌표 기준으로 설정합니다.
Extents Offset World Space	렌더링되는 오브젝트로부터의 오프셋을 월드 좌표 기준으로 설정합니다. (값 단위는 모델 크기의 절반 기준)
Size Offset	Size 값에 상대적으로 적용되는 오프셋으로 앵커 포인트처럼 사용할 수 있습니다.

Gui 요소의 프로퍼티

공통 프로퍼티

프로퍼티	설명
Position	화면 상 위치를 변경할 수 있는 속성 입니다. UDim2 형식을 사용하며, ScaleX, OffsetX, ScaleY, OffsetY 값을 순서대로 입력할 수 있습니다. Scale: 0.0 ~ 1.0 사이의 비율 단위이며, 0.1은 10%를 의미합니다. Offset: Pixel 단위이며, 10은 10Pixel을 의미합니다. Scale과 Offset 값은 합산하여 화면에 표현 됩니다. 예를 들어 ScaleX 값이 0.25이고 OffsetX 값이 10이면, 설정된 Anchor Point(Frame의 중심점)을 기준으로 좌측으로부터 25% 만큼 우측으로 이동하고 OffsetX인 10Pixel 만큼 추가로 우측으로 이동 됩니다.
Rotation	회전 각도를 변경할 수 있는 속성 입니다. 360.0은 360도를 의미합니다.
Size	크기를 변경할 수 있는 속성 입니다. Position과 마찬가지로 UDim2 형식을 사용합니다.
Visible	보이거나 보이지 않게 설정하는 속성 입니다.
Anchor Point	중심점을 의미합니다. Vector2 형식을 사용하며 기본값 0.0, 0.0이면 Frame의 좌측 상단이 중심점 입니다.
ZIndex	UI 요소의 스택 순서를 정의하는 속성 입니다. FrameA가 FrameB와 위치 상 FrameB에 가려지는 경우 ZIndex 값에 따라 FrameB 보다 위에 FrameA가 보이도록 할 수 있습니다.

Frame

프로퍼티	설명
Border Pixel Size	Frame의 테두리 두께를 설정할 수 있는 속성 입니다.
Border Mode	테두리를 Frame의 가장자리 기준으로 insert(안쪽)/middle(중앙)/Outline(바깥쪽) 중 어느 기준으로 보여줄 지 설정할 수 있는 속성 입니다.
Border Color 3	테두리 색을 변경할 수 있는 속성 입니다.
Background Color 3	Frame의 배경 색을 변경할 수 있는 속성 입니다.
Background Trnasparency	Frame의 배경 투명도를 변경할 수 있는 속성 입니다.

TextLabel

프로퍼티	설명
Text	보여줄 텍스트를 입력할 수 있는 속성 입니다.
TextScaled	보여줄 텍스트의 크기를 Text Size 값을 무시하고 오브젝트의 Size 값에 맞게 자동으로 변화할 수 있도록 기능을 제공하는 속성 입니다.
Bold	보여줄 텍스트의 두께를 변경할 수 있는 속성 입니다.
Text Size	보여줄 텍스트의 크기를 Pixel 단위로 변경할 수 있는 속성 입니다.
Text Color 3	보여줄 텍스트의 색상을 변경할 수 있습니다.
Text Transparency	보여줄 텍스트의 투명도를 변경할 수 있습니다.
Background Color 3	배경 색을 변경할 수 있는 속성 입니다.
Background Transparency	배경 투명도를 변경할 수 있는 속성 입니다.

ImageLabel

프로퍼티	설명
Image	이미지를 보여주기 위한 AssetId를 입력하는 속성 입니다. Asset Manager 또는 Asset Drawer에 등록된 이미지의 AssetId 값을 사용할 수 있습니다.
Image Transparency	이미지의 투명도를 변경할 수 있는 속성 입니다.
Background Color 3	배경 색을 변경할 수 있는 속성 입니다.
Background Transparency	배경 투명도를 변경할 수 있는 속성 입니다.

TextButton

프로퍼티	설명
Text	보여줄 텍스트를 입력할 수 있는 속성 입니다.
TextScaled	보여줄 텍스트의 크기를 Text Size 값을 무시하고 오브젝트의 Size 값에 맞게 자동으로 변화할 수 있도록 기능을 제공하는 속성 입니다.
Bold	보여줄 텍스트의 두께를 변경할 수 있는 속성 입니다.
Text Size	보여줄 텍스트의 크기를 Pixel 단위로 변경할 수 있는 속성 입니다.
Text Color 3	보여줄 텍스트의 색상을 변경할 수 있습니다.
Text Transparency	보여줄 텍스트의 투명도를 변경할 수 있습니다.
Background Color 3	배경 색을 변경할 수 있는 속성 입니다.
Background Transparency	배경 투명도를 변경할 수 있는 속성 입니다.

ImageButton

프로퍼티	설명
Image	이미지를 보여주기 위한 AssetId를 입력하는 속성 입니다. Asset Manager 또는 Asset Drawer에 등록된 이미지의 AssetId 값을 사용할 수 있습니다.
Image Transparency	이미지의 투명도를 변경할 수 있는 속성 입니다.
Background Color 3	배경 색을 변경할 수 있는 속성 입니다.
Background Transparency	배경 투명도를 변경할 수 있는 속성 입니다.

UIAspectRatioConstraint

ImageLabel의 Size가 { 0.5, 0, 0.5, 0 }으로 X축과 Y축 모두 클라이언트 기기의 50% 크기로 설정되어 있을 때, UIAspetRatioConstraint를 자식으로 두고 Aspect Ratio 속성을 1.0으로 설정하면 ImageLabel의 Size에 1:1 비율이 적용되어 좌우 또는 상하로 이미지가 늘어나지 않도록 할 수 있습니다.

프로퍼티	설명
Aspect Ratio	부모 오브젝트에 대해 보여주고 싶은 비율을 설정할 수 있습니다. 기본값은 1.0이며, x, y가 각각 1:1 비율을 갖습니다.
Aspect Type	UI 요소의 비율을 어떻게 유지할지를 결정하는 속성입니다. FitWithinMaxSize : UI 요소가 최대 크기 내에서 비율을 유지하며 축소됨 ScaleWithParentSize : 부모 UI 요소의 크기에 맞춰 비율을 유지하며 조정됨 SizeRelativeXY : X, Y 방향 모두 상대적인 크기를 유지함
Dominant Axis	UI의 크기가 변경될 때 어느 축을 기준으로 비율을 유지할지를 결정합니다. Width : 가로 기준으로 높이 조정 Height : 세로 기준으로 너비 조정