SurfaceGuiBase

SurfaceGuiBase : LayerCollector

Overview

SurfaceGuiBase는 3D 공간에 UI 요소를 렌더링하기 위한 SurfaceGui와 BillboardGui의 공통 기반 클래스입니다.

이 클래스를 상속하는 객체들은 2D UI를 3D 월드에 배치할 수 있도록 설계되어 있으며, 렌더링 방향, 오프셋 처리, Adornee를 통한 대상 지정 등 공통적인 UI 렌더링 동작을 정의합니다.

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

Properties

Active

boolean

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

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.Active = false

Adornee

Instance

어떤 BasePart에 표시될지를 명시적으로 지정하는 속성으로, 기본 부모 기준의 연결 방식을 무시하고 지정한 파트에 SurfaceGui가 표시되도록 합니다.

Code Samples

local SurfaceGui = script.Parent
local Workspace = game:GetService("Workspace")
local Part = Workspace:WaitForChild("Part")

SurfaceGui.Adornee = Part

AlwaysOnTop

boolean

3D 공간에서 항상 위에 표시될지, 아니면 일반 3D 오브젝트처럼 가려질 수 있을지를 지정합니다.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.AlwaysOnTop = true

Brightness

number

LightInfluence가 0인 상태에서 얼마나 밝게 표현될지를 결정하는 밝기 배율 값입니다.

기본값은 1이며, 0에서 10 사이의 값으로 설정할 수 있습니다.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.Brightness = 8

ClipsDescendants

boolean

UI 요소가 SurfaceGui 또는 BillboardGui의 캔버스 영역을 벗어났을 때 해당 부분을 렌더링할지 여부를 결정합니다.

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

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.ClipsDescendants = false

LightInfluence

number

환경 조명의 영향을 얼마나 받을지를 0에서 1 사이의 값으로 지정합니다.

값이 1이면 월드의 조명 변화가 그대로 반영되고, 0이면 주변 조명과 무관하게 항상 동일한 밝기와 색상으로 표시됩니다.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.LightInfluence = 0.5

MaxDistance

number

카메라로부터 렌더링될 최대 거리를 지정합니다.

기본값은 3000이며, 0으로 설정하면 거리 제한 없이 매우 먼 거리에서도 렌더링됩니다.

야외처럼 넓은 환경에서는 MaxDistance를 불필요하게 크게 설정하면 멀리 있는 UI까지 렌더링하게 되어 성능에 부담이 될 수 있습니다. 따라서 실제로 확인 가능한 거리까지만 적절히 제한하는 것이 좋습니다.

반대로 UI가 충분히 작아졌을 때 자연스럽게 나타나거나 사라지도록 하고 싶다면 MaxDistance를 조금 더 높게 설정해 갑작스러운 팝인·팝아웃을 줄일 수 있습니다.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.MaxDistance = 1000

Size

UDim2

SurfaceGuiBase의 크기를 나타내는 읽기 전용 속성입니다.

크기는 SurfaceGuiBase가 부착된 면의 크기에 따라 자동으로 결정됩니다.

Code Samples

local SurfaceGui = script.Parent

print(SurfaceGui.Size)

ZIndexBehavior

Enum.ZIndexMode

모든 하위 GuiObject를 기준으로 ZIndex가 어떻게 동작할지를 지정합니다.

기본 설정인 Sibling 모드에서는 자식 UI가 항상 부모 UI보다 앞에 그려지며, 동일한 부모를 가진 자식 간의 우선순위는 ZIndex 값을 기준으로 정해집니다.

반면 Global 모드에서는 모든 하위 요소를 ZIndex 값 기준으로 전체 정렬하고, 값이 같은 경우 계층 구조 순서를 사용해 우선순위를 결정합니다. 이 방식에서는 자식 요소의 ZIndex가 부모보다 낮을 경우 부모 뒤에 가려질 수 있으므로, 하위 요소는 부모 이상의 ZIndex를 설정해야 올바르게 표시됩니다.

Code Samples

Methods

Events

See also

SurfaceGuiBillboardGui