SurfaceGuiBase

SurfaceGuiBase : LayerCollector

Overview

SurfaceGuiBase is a common base class between SurfaceGui and BillboardGui used to render UI elements in 3D space.

Objects that inherit this class are designed to 2D UI elements in a 3D world; these objects define common UI rendering actions such as setting rendering direction, handling offsets, and specifying target with Adornee.

SurfaceGuiBase can be controlled only in client environment.

Properties

Active

bool

Whether or not to process input events.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.Active = false

Adornee

Instance

This property explicitly specifies on which BasePart SurfaceGui is displayed. It allows SurfaceGui to be displayed on a specified part, ignoring the connection type of base parent.

Code Samples

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

SurfaceGui.Adornee = Part

AlwaysOnTop

bool

Specifies whether it is displayed on the topmost layer in 3D space or it can be overlap like normal 3D objects.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.AlwaysOnTop = true

Brightness

number

A brightness multiplier that is used to determine the brightness of an object when LightInfluence is 0.

Default is 1 and this value can be set between 0 and 10.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.Brightness = 8

ClipsDescendants

bool

Determines whether or not to render a UI element when part of it diverges the canvas area of SurfaceGui or BillboardGui.

Default is true and parts diverge the canvas area are not displayed. If it is set false, a UI element may be displayed in full even when whole or part of the element diverges the canvas area.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.ClipsDescendants = false

LightInfluence

number

Specifies the level of influence of environmental lighting, between 0 and 1.

If this value is 1, the world lighting changes are fully applied. If this value is 0, the object is displayed at the same brightness and in the same color regardless of lightings around.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.LightInfluence = 0.5

MaxDistance

number

Specifies the maximum distance from camera to be rendered.

Default is 3000 and if it is set to 0, UI will be rendered regardless of its distance to camera.

If MaxDistance is set unnecessarily large, when rendering outdoors, UI very far away will be rendered and this will negatively affect performance. For this reason, it is recommended to limit the distance to a distance that can actually be seen.

On the other hand, to make UI seamlessly appear or disappear when it becomes too small, set MaxDistance a little higher to reduce abrupt pop-ins and pop-outs.

Code Samples

local SurfaceGui = script.Parent

SurfaceGui.MaxDistance = 1000

Size

UDim2

A read-only property used to represent the size of SurfaceGuiBase.

The size is automatically determined by the size of the side SurfaceGuiBase is attached on.

Code Samples

local SurfaceGui = script.Parent

print(SurfaceGui.Size)

ZIndexBehavior

EZIndexMode

Specifies how ZIndex will behave based on all child GuiObjects.

In default Sibling mode, child UI is always drawn before parent UI. The drawing priority among children with the same parent is determined by the ZIndex value.

On the other hand, in Global mode, all child elements are sorted by the ZIndex value and if there are elements with same value, a hierarchy structure order is used to determine priorities. In this logic, a child element with ZIndex of which value is lower than that of the parent element may be overlapped by the parent element, the value of child element’s ZIndex should be larger than that of the parent element to be properly displayed.

Code Samples

Methods

Events

See also

SurfaceGuiBillboardGui