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
726AlwaysOnTop: bool
726Brightness: float
726CanvasSize: Vector2
726ClipsDescendants: bool
726LightInfluence: float
726MaxDistance: float
726PixelsPerStud: float
726SizingMode: SurfaceGuiSizingMode
726ToolPunchThroughDistance: float
726ZOffset: float
inherited from SurfaceGuiBase
726Active: bool
726Adornee: Instance
726Face: NormalId
inherited from LayerCollector
726Enabled: bool
726ResetOnSpawn: bool
726ZIndexBehavior: ZIndexBehavior
648GetGuiObjectsAtPosition(x: int, y: int): Instances
462GetLayoutNodeTree(): Dictionary
inherited from GuiBase2d
726AbsolutePosition: Vector2
726AbsoluteRotation: float
726AbsoluteSize: Vector2
726AutoLocalize: bool
726RootLocalizationTable: LocalizationTable
726SelectionBehaviorDown: SelectionBehavior
726SelectionBehaviorLeft: SelectionBehavior
726SelectionBehaviorRight: SelectionBehavior
726SelectionBehaviorUp: SelectionBehavior
726SelectionGroup: bool
525SelectionChanged(amISelected: bool, previousSelection: GuiObject, newSelection: GuiObject)
inherited from Instance
726Archivable: bool
726Capabilities: SecurityCapabilities
726IsInSandbox: bool
726Name: string
726Parent: Instance
726PredictionMode: PredictionMode
726Sandboxed: bool
726UniqueId: 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
707GetDescendants(): Instances
486GetFullName(): string
706GetStyled(name: string, selector: string?): Variant
657GetStyledPropertyChangedSignal(property: string): RBXScriptSignal
576GetTags(): Array
576HasTag(tag: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
664IsPropertyModified(property: string): bool
698QueryDescendants(selector: string): Instances
573Remove(): null
576RemoveTag(tag: string): null
664ResetPropertyToDefault(property: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
726children(): Instances
726clone(): Instance
726destroy(): null
726findFirstChild(name: string, recursive: bool = false): Instance
726getChildren(): Instances
726isDescendantOf(ancestor: Instance): bool
726remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
657StyledPropertiesChanged()
726childAdded(child: Instance)
inherited from Object
726ClassName: string
726className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
726isA(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). Additionally, the part's CanQuery property must be true for the interactive UI element to receive input.

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 72

Members 12

AlwaysOnTop

TypeDefault
bool

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 5

Brightness

TypeDefault
float

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 5

CanvasSize

TypeDefault
Vector2

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

History 6

ClipsDescendants

TypeDefault
bool

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 5

LightInfluence

TypeDefault
float

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 5

MaxDistance

TypeDefault
float

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 3

PixelsPerStud

TypeDefault
float

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 5

SizingMode

TypeDefault
SurfaceGuiSizingMode

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 5

ToolPunchThroughDistance

TypeDefault
float

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 5

ZOffset

TypeDefault
float

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 5

Removed members 4

Active

TypeDefault
bool

History 4

Adornee

TypeDefault
Instance

History 5

Enabled

TypeDefault
bool

History 4

Face

TypeDefault
NormalId

History 4

Settings