Reference API Roblox

Engine API

Website

Related

Reference API Roblox

SurfaceGui

Container for GuiObjects that are rendered on the surface of a part.

Member index 12

HistoryMember
553AlwaysOnTop: bool
553Brightness: float
553CanvasSize: Vector2
553ClipsDescendants: bool
553LightInfluence: float
592MaxDistance: float
553PixelsPerStud: float
553SizingMode: SurfaceGuiSizingMode
553ToolPunchThroughDistance: float
553ZOffset: float
inherited from SurfaceGuiBase
553Active: bool
553Adornee: Instance
553Face: NormalId
inherited from LayerCollector
553Enabled: bool
553ResetOnSpawn: bool
553ZIndexBehavior: ZIndexBehavior
648GetGuiObjectsAtPosition(x: int, y: int): Instances
462GetLayoutNodeTree(): Dictionary
inherited from GuiBase2d
553AbsolutePosition: Vector2
553AbsoluteRotation: float
553AbsoluteSize: Vector2
553AutoLocalize: bool
553RootLocalizationTable: LocalizationTable
553SelectionBehaviorDown: SelectionBehavior
553SelectionBehaviorLeft: SelectionBehavior
553SelectionBehaviorRight: SelectionBehavior
553SelectionBehaviorUp: SelectionBehavior
553SelectionGroup: bool
525SelectionChanged(amISelected: bool, previousSelection: GuiObject, newSelection: GuiObject)
inherited from Instance
553Archivable: bool
635Capabilities: SecurityCapabilities
553Name: string
553Parent: Instance
635Sandboxed: bool
616UniqueId: UniqueId
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
648GetChildren(): Instances
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
641GetStyled(name: string): Variant
576GetTags(): Array
576HasTag(tag: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
580IsPropertyModified(name: string): bool
573Remove(): null
576RemoveTag(tag: string): null
580ResetPropertyToDefault(name: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
648children(): Instances
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
648getChildren(): Instances
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
553childAdded(child: Instance)
inherited from Object
647ClassName: string
647className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
650isA(className: string): bool
647Changed(property: string)

Removed member index 4

HistoryMember
540Active: bool
540Adornee: Instance
310Enabled: bool
540Face: NormalId

Description

SurfaceGui allows for the rendering of UI objects onto a part's surface in the 3D world while also allowing for basic user interaction to occur. Similar to Decals and Textures, UI objects such as TextLabels and ImageLabels parented to a SurfaceGui face the same direction as the surface they're on, editable through the Face property.

SurfaceGui on a 3D part in the place with an ImageLabel child to depict a screen console.

Note that interactive UI elements like ImageButtons and TextButtons inside a SurfaceGui will only receive user input if they are parented to the PlayerGui, typically via placing the SurfaceGui inside StarterGui. The Adornee property can be used to target a part in the 3D world while the SurfaceGui itself remains in the PlayerGui.

See In-Experience UI for a guide on working with SurfaceGui containers.

Caching Behavior

To help improve performance, the appearance of a SurfaceGui is cached until one of the following occurs, after which its appearance will be recomputed on the next rendering frame.

  • A descendant is added to or removed from the SurfaceGui.
  • A property of a descendant of the SurfaceGui changes.
  • A property of the SurfaceGui itself changes.

History 60

Members 12

AlwaysOnTop

TypeDefault
boolfalse

This property determines whether the SurfaceGui will always render on top of other 3D objects.

When set to false (default), the SurfaceGui renders like other 3D content and is occluded by other 3D objects. When set to true, the SurfaceGui always renders on top of 3D content and the appearance changes significantly:

History 4

Brightness

TypeDefault
float1

This property determines the factor by which the SurfaceGui container's light is scaled when LightInfluence is 0. By default, this property is 1 and can be set to any number between 0 and 1000. By modifying this property, the apparent brightness of a SurfaceGui can be better matched to its environment. For instance, a video billboard can be brightened inside a dark room by increasing Brightness to 10.

Note that Brightness is inaccessible in Studio and has no effect when either LightInfluence is 1 or AlwaysOnTop is true.

History 4

CanvasSize

TypeDefault
Vector2800, 600

The size of a "virtual screen" in "virtual pixels" which makes SurfaceGuis pixel-to-pixel compatible with ScreenGuis.

History 5

ClipsDescendants

TypeDefault
boolfalse

When set to true (default), portions of GuiObjects that fall outside of the SurfaceGui canvas borders will not be drawn.

Even when this property is false, GuiObjects that are completely outside of the canvas will not render.

History 4

LightInfluence

TypeDefault
float0

Controls how much the SurfaceGui is influenced by environmental lighting, in a range from 0 to 1. Setting this to 1 means that surrounding lighting has complete control over the appearance, while setting it to 0 means that the lighting has no effect.

History 4

MaxDistance

TypeDefault
float0

This property controls how far from the camera the SurfaceGui will be displayed before it stops rendering. A value of 0 means there is no limit and it will render infinitely far away. The default value of 1000 works fine for most cases.

For SurfaceGuis that appear outdoors, it's recommended that MaxDistance is high enough to ensure that the container's UI is sufficiently small on the screen when it appears or disappears, minimizing the sudden pop‑in/out effect.

History 2

PixelsPerStud

TypeDefault
float50

This property determines the density of pixels used for each world-space stud to render the contents of the SurfaceGui. Higher values will cause the various GuiObjects within to appear smaller if they are kept the same size. Conversely, lower values will cause objects to appear larger. However, if the GuiObjects are scaled proportionally through use of UIScale, GuiObject.Size, TextLabel.TextSize, or similar, this property allows for higher definition to be used.

It's important to select a value based on how far away you expect a player to view the SurfaceGui. Also be mindful that a large pixel density could negatively affect performance if the face of the adorned part is large enough.

History 4

SizingMode

TypeDefault
SurfaceGuiSizingModeFixedSize

When set to SurfaceGuiSizingMode.PixelsPerStud (default), the SurfaceGui renders with a variable size based on PixelsPerStud and the surface's size in studs.

When set to SurfaceGuiSizingMode.FixedSize, the SurfaceGui renders with a fixed size set through CanvasSize.

History 4

ToolPunchThroughDistance

TypeDefault
float0

Sets the distance in which left clicking starts acting on the SurfaceGui instead of for the held Tool. If a character is within this distance of the SurfaceGui, the Tool will not activate on click.

History 4

ZOffset

TypeDefault
float0

Layers this SurfaceGui in relation to others on the same face (changing this does not visually "lift" or "sink" a SurfaceGui from the surface).

History 4

Removed members 4

Active

TypeDefault
bool

History 4

Adornee

TypeDefault
Instance

History 5

Enabled

TypeDefault
bool

History 4

Face

TypeDefault
NormalId

History 4

Settings