SurfaceGui¶
Container for GuiObjects that are rendered on the surface of a part.
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). 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.
Inheritance¶
Object → Instance → GuiBase → GuiBase2d → LayerCollector → SurfaceGuiBase → SurfaceGui
Nova inheritance: Instance → GuiBase → GuiBase2d → LayerCollector → SurfaceGui
Properties¶
Active Supported Property Determines whether the SurfaceGui sinks user input; true by default.
Determines whether the SurfaceGui sinks user input; true by
default.
This property determines whether the SurfaceGui will sink input, for example if the parent or Adornee part contains a ClickDetector class like DragDetector.
Note that interactive UI elements like ImageButtons
and TextButtons inside a SurfaceGui will only
receive user input if they are parented to the PlayerGui (the
SurfaceGui.Adorneee 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.
Adornee Supported Property BasePart on which to apply the SurfaceGui, overriding the default parent association.
BasePart on which to apply the SurfaceGui, overriding the default parent association.
AlwaysOnTop Supported Property Renders the surface GUI on top of world geometry when enabled.
Renders the surface GUI on top of world geometry when enabled.
Nova's surface-GUI render path checks this property.
Brightness Supported Property Scales surface-GUI lighting when LightInfluence is 0.
Scales surface-GUI lighting when LightInfluence is 0.
The property is consumed by the surface-GUI renderer; it is only visible
when LightInfluence is zero.
CanvasOffset Supported Property
CanvasSize Supported Property The size of a "virtual screen" in "virtual pixels" which makes SurfaceGuis pixel-to-pixel compatible with ScreenGuis.
The size of a "virtual screen" in "virtual pixels" which makes SurfaceGuis pixel-to-pixel compatible with ScreenGuis.
ClipsDescendants Supported Property Whether portions of GuiObjects that fall outside of the SurfaceGui canvas borders will be drawn.
Whether portions of GuiObjects that fall outside of the SurfaceGui canvas borders will be drawn.
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.
Enabled Supported Property Toggles the visibility of this LayerCollector.
Toggles the visibility of this LayerCollector. When false, the
UI contents will not render, process user input, or update in response to
changes.
Face Supported Property NormalId face upon which to apply the SurfaceGui.
NormalId face upon which to apply the SurfaceGui.
NormalId face of the SurfaceGui parent (or its Adornee) upon which to apply the SurfaceGui.
LightInfluence Supported Property Controls how much world lighting affects the surface GUI.
Controls how much world lighting affects the surface GUI.
Nova's surface-GUI renderer consumes this value.
MaxDistance Supported Property Controls how far away the SurfaceGui can be displayed before it stops rendering.
Controls how far away the SurfaceGui can be displayed before it stops rendering.
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.
PixelsPerStud Supported Property Determines the density of pixels used for each world-space stud to render the contents of the SurfaceGui.
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.
SizingMode Supported Property Determines whether the SurfaceGui will render at a fixed size or scale with its size in studs.
Determines whether the SurfaceGui will render at a fixed size or scale with its size in studs.
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.
ToolPunchThroughDistance Supported Property Sets the distance in which left clicking starts acting on the SurfaceGui instead of for the held Tool.
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.
ZOffset Supported Property Layers this SurfaceGui in relation to other SurfaceGuis on the same face.
Layers this SurfaceGui in relation to other SurfaceGuis on the same face.
Layers this SurfaceGui in relation to others on the same face (changing this does not visually "lift" or "sink" a SurfaceGui from the surface).
Inherited members¶
Inherited from LayerCollector: 20 properties, 36 methods, 7 events. They are documented on the base class page.
Roblox reference: SurfaceGui
Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.