SurfaceGui
Container for GuiObjects that are rendered on the surface of a part.
Memory category | Instances |
---|
Member index 12
Removed member index 4
History | Member | |
---|---|---|
540 | Active: bool | |
540 | Adornee: Instance | |
310 | Enabled: bool | |
540 | Face: 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.
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
- 592 Change Tags of MaxDistance from [NotBrowsable] to []
- 590 Add MaxDistance
- 557 Add
- 557 Add
- 553 Change Default of ZOffset from to 0
- 553 Change Default of ToolPunchThroughDistance from to 0
- 553 Change Default of SizingMode from to FixedSize
- 553 Change Default of PixelsPerStud from to 50
- 553 Change Default of LightInfluence from to 0
- 553 Change Default of ClipsDescendants from to false
- 553 Change Default of CanvasSize from to Vector2(800, 600)
- 553 Change Default of Brightness from to 1
- 553 Change Default of AlwaysOnTop from to false
- 540 Remove Face
- 540 Remove Adornee
- 540 Remove Active
- 540 Change Superclass of SurfaceGui from LayerCollector to SurfaceGuiBase
- 486 Change ThreadSafety of ZOffset from ReadOnly to ReadSafe
- 486 Change ThreadSafety of ToolPunchThroughDistance from ReadOnly to ReadSafe
- 486 Change ThreadSafety of SizingMode from ReadOnly to ReadSafe
- 486 Change ThreadSafety of PixelsPerStud from ReadOnly to ReadSafe
- 486 Change ThreadSafety of LightInfluence from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Face from ReadOnly to ReadSafe
- 486 Change ThreadSafety of ClipsDescendants from ReadOnly to ReadSafe
- 486 Change ThreadSafety of CanvasSize from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Brightness from ReadOnly to ReadSafe
- 486 Change ThreadSafety of AlwaysOnTop from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Adornee from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Active from ReadOnly to ReadSafe
- 481 Change Category of Brightness from Appearance to Data
- 480 Add Brightness
- 462 Change ThreadSafety of ZOffset from to ReadOnly
- 462 Change ThreadSafety of ToolPunchThroughDistance from to ReadOnly
- 462 Change ThreadSafety of SizingMode from to ReadOnly
- 462 Change ThreadSafety of PixelsPerStud from to ReadOnly
- 462 Change ThreadSafety of LightInfluence from to ReadOnly
- 462 Change ThreadSafety of Face from to ReadOnly
- 462 Change ThreadSafety of ClipsDescendants from to ReadOnly
- 462 Change ThreadSafety of CanvasSize from to ReadOnly
- 462 Change ThreadSafety of AlwaysOnTop from to ReadOnly
- 462 Change ThreadSafety of Adornee from to ReadOnly
- 462 Change ThreadSafety of Active from to ReadOnly
- 383 Add SizingMode
- 383 Add PixelsPerStud
- 383 Change Category of CanvasSize from Data to Sizing
- 340 Add ClipsDescendants
- 329 Change ValueType of Adornee from Object to Instance
- 310 Remove Enabled
- 291 Add LightInfluence
- 280 Add ZOffset
- 257 Add Enabled
- 258 Remove Enabled
- 241 Add AlwaysOnTop
- 152 Add ToolPunchThroughDistance
- 131 Add Face
- 131 Add Enabled
- 131 Add CanvasSize
- 131 Add Adornee
- 131 Add Active
- 131 Add SurfaceGui
Members 12
AlwaysOnTop
Type | Default | |
---|---|---|
bool | false |
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:
- Colors match how they appear inside a ScreenGui.
- Text may appear sharper on high DPI devices.
- LightInfluence is treated as though it's
0
. - Brightness has no effect.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of AlwaysOnTop from to false
- 486 Change ThreadSafety of AlwaysOnTop from ReadOnly to ReadSafe
- 462 Change ThreadSafety of AlwaysOnTop from to ReadOnly
- 241 Add AlwaysOnTop
Brightness
Type | Default | |
---|---|---|
float | 1 |
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
.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of Brightness from to 1
- 486 Change ThreadSafety of Brightness from ReadOnly to ReadSafe
- 481 Change Category of Brightness from Appearance to Data
- 480 Add Brightness
CanvasSize
Type | Default | |
---|---|---|
Vector2 | 800, 600 |
The size of a "virtual screen" in "virtual pixels" which makes SurfaceGuis pixel-to-pixel compatible with ScreenGuis.
Thread safety | ReadSafe |
---|---|
Category | Sizing |
Loaded/Saved | true |
History 5
- 553 Change Default of CanvasSize from to Vector2(800, 600)
- 486 Change ThreadSafety of CanvasSize from ReadOnly to ReadSafe
- 462 Change ThreadSafety of CanvasSize from to ReadOnly
- 383 Change Category of CanvasSize from Data to Sizing
- 131 Add CanvasSize
ClipsDescendants
Type | Default | |
---|---|---|
bool | false |
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.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
History 4
- 553 Change Default of ClipsDescendants from to false
- 486 Change ThreadSafety of ClipsDescendants from ReadOnly to ReadSafe
- 462 Change ThreadSafety of ClipsDescendants from to ReadOnly
- 340 Add ClipsDescendants
LightInfluence
Type | Default | |
---|---|---|
float | 0 |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of LightInfluence from to 0
- 486 Change ThreadSafety of LightInfluence from ReadOnly to ReadSafe
- 462 Change ThreadSafety of LightInfluence from to ReadOnly
- 291 Add LightInfluence
MaxDistance
Type | Default | |
---|---|---|
float | 0 |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 2
- 592 Change Tags of MaxDistance from [NotBrowsable] to []
- 590 Add MaxDistance
PixelsPerStud
Type | Default | |
---|---|---|
float | 50 |
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.
Thread safety | ReadSafe |
---|---|
Category | Sizing |
Loaded/Saved | true |
History 4
- 553 Change Default of PixelsPerStud from to 50
- 486 Change ThreadSafety of PixelsPerStud from ReadOnly to ReadSafe
- 462 Change ThreadSafety of PixelsPerStud from to ReadOnly
- 383 Add PixelsPerStud
SizingMode
Type | Default | |
---|---|---|
SurfaceGuiSizingMode | FixedSize |
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.
Thread safety | ReadSafe |
---|---|
Category | Sizing |
Loaded/Saved | true |
History 4
- 553 Change Default of SizingMode from to FixedSize
- 486 Change ThreadSafety of SizingMode from ReadOnly to ReadSafe
- 462 Change ThreadSafety of SizingMode from to ReadOnly
- 383 Add SizingMode
ToolPunchThroughDistance
Type | Default | |
---|---|---|
float | 0 |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of ToolPunchThroughDistance from to 0
- 486 Change ThreadSafety of ToolPunchThroughDistance from ReadOnly to ReadSafe
- 462 Change ThreadSafety of ToolPunchThroughDistance from to ReadOnly
- 152 Add ToolPunchThroughDistance
ZOffset
Type | Default | |
---|---|---|
float | 0 |
Layers this SurfaceGui in relation to others on the same face (changing this does not visually "lift" or "sink" a SurfaceGui from the surface).
Thread safety | ReadSafe |
---|---|
Category | Appearance |
Loaded/Saved | true |