GuiObject

GuiObject : GuiBase2d

Overview

GuiObject는 2D UI를 구성하는 기반 클래스입니다. 이는 BasePart가 3D 객체의 공통 속성을 정의하듯, GUI 요소의 시각적 배치와 크기 등을 관리하기 위한 추상 구조로 작동합니다.

모든 GUI 객체는 InputBegan, InputEnded 등 입력 이벤트를 통해 입력을 감지할 수 있지만, 버튼 계열의 ImageButton과 TextButton은 Activated와 같은 전용 이벤트를 제공하여 상호작용 처리를 간소화할 수 있습니다.

GuiObject는 클라이언트 환경에서만 제어할 수 있습니다.

Properties

Active

bool

입력 이벤트를 처리할지 여부를 지정합니다.

Code Samples

local ScreenGui = script.Parent
local TextButton = ScreenGui:WaitForChild("TextButton")

TextButton.Active = false

AnchorPoint

Vector2

GUI 객체가 갖는 절대 크기를 바탕으로 위치의 중심이 되는 기준점을 어디에 둘지 지정합니다.

이 기준점이 설정되면, 해당 GUI가 화면에서 어떤 지점을 중심으로 배치되는지, 그리고 크기가 어떤 방향으로 넓어지는지가 결정됩니다. 다시 말해, Position 속성은 이 기준점을 기준으로 계산되며, Size는 이 지점에서 양쪽 또는 특정 방향으로 확장됩니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.AnchorPoint = Vector2.new(0.5, 0.5)

BackgroundColor3

Color3

GUI 객체의 배경 색상을 지정합니다.

TextLabel이나 TextButton처럼 텍스트를 포함하는 UI 구성 요소에서 글자색을 변경하려면 TextColor3를 사용해야 하며, 배경색과 글자색이 겹쳐 보이지 않도록 명확한 대비를 두는 것이 중요합니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.BackgroundColor3 = Color3.fromRGB(255, 255, 0)

BackgroundTransparency

number

GUI 객체의 배경 영역의 투명도를 지정합니다.

TextLabel이나 TextButton처럼 텍스트를 포함하는 UI 구성 요소에서는 글자의 투명도를 변경하려면 TextTransparency를 사용해야 합니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.BackgroundTransparency = 0.5

ClipsDescendants

bool

하위 UI 객체가 부모 GUI 객체의 표시 영역을 벗어났을 때 해당 부분을 렌더링할지 여부를 결정합니다.

기본값은 false이며, 이 경우 UI 요소가 경계 밖으로 일부 또는 전체가 벗어나더라도 화면에 표시될 수 있습니다. true로 설정하면 경계를 넘어가는 영역은 표시되지 않습니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.ClipsDescendants = true

LayoutOrder

number

UIGridLayout, UIListLayout 등 UI 레이아웃을 사용할 때, UI 객체가 어떤 순서로 배치될지를 결정합니다.

해당 레이아웃의 SortOrder가 LayoutOrder로 설정된 경우에만 적용되며, 레이아웃 구조가 없다면 동작하지 않습니다.

정렬은 작은 숫자를 가진 요소가 먼저 배치되는 방식으로 처리되며, 동일한 값은 생성된 순서를 기준으로 정렬됩니다.

향후 기존 UI 사이에 새 요소를 자연스럽게 끼워 넣어야 할 가능성이 있다면, 레이아웃 순서를 100 단위로 넉넉하게 설정해두는 것이 실용적입니다. 이렇게 하면 중간에 원하는 순서 값을 쉽게 배정할 수 있습니다.

또한 LayoutOrder는 배치 순서에만 영향을 주며, 실제 화면에서 어떤 요소가 위에 렌더링되는지는 ZIndex 속성으로 제어되므로 필요 시 함께 설정하는 것을 권장합니다.

Code Samples

local ScreenGui = script.Parent
local TextLabels = ScreenGui:GetChildren()

TextLabels[1].LayoutOrder = 10
TextLabels[2].LayoutOrder = 5

Position

UDim2

GUI 객체가 화면에서 어느 위치에 배치될지를 UDim2 값으로 정의합니다.

UDim2는 비율(Scale)과 절대값(Pixel)로 구성되며, 최종 위치는 객체에 설정된 AnchorPoint를 기준으로 계산됩니다. 따라서 AnchorPoint가 어디에 설정되어 있는지에 따라 실제 배치 결과가 달라질 수 있습니다.

Scale 값은 부모 UI 요소의 크기를 기준으로 비례해 적용되며, Pixel 값은 부모의 크기 변화와 무관하게 지정된 픽셀 수만큼 이동합니다. 부모 객체가 없는 경우에는 화면(Viewport)의 크기를 기준으로 위치가 계산됩니다.

실제로 화면에 렌더링된 픽셀 단위 위치는 GuiBase2d.AbsolutePosition 속성을 통해 확인할 수 있습니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.Position = UDim2.new(0.5, 0, 0.5, 0)

Rotation

number

GUI 객체를 몇 도 만큼 회전시킬지를 지정합니다.

회전은 항상 객체의 중앙을 축으로 수행되며, AnchorPoint 설정과는 연관되지 않기 때문에 회전 기준점을 임의로 바꾸는 것은 불가능합니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.Rotation = 90

Size

UDim2

GUI 객체의 크기를 UDim2 값으로 정의합니다.

UDim2는 비율(Scale)과 절대값(Pixel)로 구성되며, Scale 값은 부모 UI의 크기를 기준으로 비례해서 크기가 계산되고, Pixel 값은 부모 크기 변화와 관계없이 지정된 픽셀 값 그대로 적용됩니다. 부모 객체가 없는 경우에는 화면(Viewport)의 크기를 기준으로 크기가 계산됩니다.

실제 화면에 표시되는 최종 픽셀 크기는 GuiBase2d.AbsoluteSize 속성을 통해 확인할 수 있습니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.Size = UDim2.new(1, 0, 0.5, 0)

Visible

bool

GUI 객체와 그 자식 요소들이 화면에 표시될지 여부를 제어합니다.

UIGridLayout·UIListLayout 같은 레이아웃을 사용하는 경우, Visible이 false인 요소는 표시 대상에서 제외합니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.Visible = false

ZIndex

number

GUI 객체가 화면에 그려질 때, 다른 요소들보다 앞에 나타날지 뒤에 나타날지를 결정합니다.

값이 낮을수록 뒤쪽(아래쪽)에 배치되고, 값이 높을수록 화면 상에서 위쪽에 표시됩니다.

향후 여러 UI 사이에 새로운 UI를 끼워 넣어야 할 가능성이 있다면, ZIndex 값을 100 단위로 크게 설정해 두는 것이 유용합니다. 이렇게 하면 기존 요소를 수정하지 않고도 중간값을 쉽게 배정할 수 있습니다.

ZIndex는 렌더링 순서를 의미하며, UIGridLayout·UIListLayout 등 레이아웃의 배치 순서는 LayoutOrder로 결정됩니다.

GUI 객체의 ZIndex와 별개로 ScreenGui·SurfaceGui·BillboardGui는 자체적으로 ZIndexBehavior를 제공하며, 이를 통해 렌더링 우선순위 결정 방식을 변경할 수 있습니다.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

print(TextLabel.ZIndex)

Methods

Events

InputBegan

사용자가 클릭, 터치 등 어떤 방식으로든 GUI 객체와의 상호작용을 시작하는 순간 호출되는 이벤트입니다.

관련 이벤트로는 입력이 끝날 때 발생하는 InputEnded, 입력 값이 변화할 때 호출되는 InputChanged가 있습니다.

유사한 기능을 수행하는 UserInputService.InputBegan 이벤트도 존재하지만, 이는 특정 GUI 요소에 국한되지 않고 전체 입력을 전역적으로 감지하는 데 사용됩니다.

참고로 InputBegan은 현재 TextButton과 ImageButton에서만 지원됩니다.

Parameters

InputObject InputObject

입력과 관련된 세부 정보를 포함하는 객체이며, 하나의 입력이 시작되고 끝날 때까지 동일한 인스턴스로 유지됩니다.

  • Enum.KeyCode KeyCode: 입력된 키

  • Enum.UserInputState UserInputState: 입력 상태

  • Enum.UserInputType UserInputType: 입력 장치 종류

  • Vector3 Delta: 이동 변화량 (Z값은 0으로 고정)

  • Vector3 Position: 입력이 발생한 화면상의 위치 (Z값은 0으로 고정)

Code Samples

local ScreenGui = script.Parent
local TextButton = ScreenGui:WaitForChild("TextButton")

local function OnInputBegan(input)
    local keyCode = input.KeyCode
    local inputState = input.UserInputState
    local inputType = input.UserInputType
    local delta = input.Delta
    local pos = input.Position 
end
TextButton.InputBegan:Connect(OnInputBegan)

InputChanged

사용자가 GUI 객체와 상호작용하는 과정에서 입력 상태가 변할 때마다 발생합니다. 예를 들어 마우스나 터치한 손가락을 누르고 있는 동안 값이 바뀌는 경우 등이 여기에 포함됩니다.

함께 사용되는 관련 이벤트로는 입력이 시작될 때 발생하는 InputBegan, 입력이 종료될 때 호출되는 InputEnded가 있습니다.

참고로 InputChanged는 현재 TextButton과 ImageButton에서만 지원됩니다.

Parameters

InputObject InputObject

입력과 관련된 세부 정보를 포함하는 객체이며, 하나의 입력이 시작되고 끝날 때까지 동일한 인스턴스로 유지됩니다.

  • Enum.KeyCode KeyCode: 입력된 키

  • Enum.UserInputState UserInputState: 입력 상태

  • Enum.UserInputType UserInputType: 입력 장치 종류

  • Vector3 Delta: 이동 변화량 (Z값은 0으로 고정)

  • Vector3 Position: 입력이 발생한 화면상의 위치 (Z값은 0으로 고정)

Code Samples

local ScreenGui = script.Parent
local TextButton = ScreenGui:WaitForChild("TextButton")

local function OnInputChanged(input)
    local keyCode = input.KeyCode
    local inputState = input.UserInputState
    local inputType = input.UserInputType
    local delta = input.Delta
    local pos = input.Position 
end
TextButton.InputChanged:Connect(OnInputChanged)

InputEnded

사용자가 GUI 객체와의 상호작용을 마무리하는 순간 발생합니다. 클릭 중이던 마우스 버튼을 놓거나, 터치하던 손가락을 뗄 때처럼 입력이 종료되는 모든 상황이 여기에 포함됩니다.

함께 사용되는 관련 이벤트로는 입력이 시작될 때 발생하는 InputBegan, 입력 값이 변화할 때 호출되는 InputChanged가 있습니다.

참고로 InputEnded는 현재 TextButton과 ImageButton에서만 지원됩니다.

Parameters

InputObject InputObject

입력과 관련된 세부 정보를 포함하는 객체이며, 하나의 입력이 시작되고 끝날 때까지 동일한 인스턴스로 유지됩니다.

  • Enum.KeyCode KeyCode: 입력된 키

  • Enum.UserInputState UserInputState: 입력 상태

  • Enum.UserInputType UserInputType: 입력 장치 종류

  • Vector3 Delta: 이동 변화량 (Z값은 0으로 고정)

  • Vector3 Position: 입력이 발생한 화면상의 위치 (Z값은 0으로 고정)

Code Samples

local ScreenGui = script.Parent
local TextButton = ScreenGui:WaitForChild("TextButton")

local function OnInputEnded(input)
    local keyCode = input.KeyCode
    local inputState = input.UserInputState
    local inputType = input.UserInputType
    local delta = input.Delta
    local pos = input.Position 
end
TextButton.InputEnded:Connect(OnInputEnded)

See also

GUI
PreviousGuiButtonNextHttpService

Last updated