SurfaceGui
Allows for the rendering of GUI elements onto a part's surface in the 3D world, while allowing for basic user interaction to occur. SurfaceGuis must be descendants of PlayerGui in order to know which player is interacting with it.
Caching static UI for performance improvements
A Gui's appearance is cached until one of the following events occurs:
- A descendant is added to the Gui.
- A descendant is removed from the Gui.
- A property of a descendant of the Gui changes.
- A property of the Gui changes.
If any of these events occur, the Gui's appearance will be recomputed the next frame it gets rendered.
Resumen
Propiedades
Determines whether the SurfaceGui will always be rendered on top of other 3D objects.
Determines the factor by which the GUI's light is scaled when LightInfluence is 0.
The size of a 'virtual screen', in 'virtual pixels', which makes SurfaceGuis pixel-to-pixel compatible with ScreenGuis.
When set to true, portions of GuiObjects that fall outside of the SurfaceGui's canvas borders will not be drawn.
Controls how much the SurfaceGui is influenced by the lighting in the game world.
Controls how far away the SurfaceGui can be displayed before it stops rendering.
Determines the number of screen-space pixels per world-space stud used to render the contents of the SurfaceGui.
Determines whether SurfaceGui will render at fixed size or scale with its size in studs.
Sets the distance left clicking starts acting on the surface gui instead of the held tool.
Offsets the SurfaceGui relative to the normal of the surface it is attached to.
Toggles the visibility of this LayerCollector.
Determines if the LayerCollector resets (deletes itself and re-clones into the player's PlayerGui) every time the player's character respawns.
Controls how GuiObject.ZIndex behaves on all descendants of this LayerCollector.
Describes the actual screen position of a UI element, in pixels.
Describes the actual screen rotation of a UI element, in degrees.
Describes the actual screen size of a UI element, in pixels.
When set to true, localization will be applied to this GuiBase2d and its descendants.
A reference to a LocalizationTable to be used to apply automated localization to this GuiBase2d and its descendants.
Customizes gamepad selection behavior in the down direction.
Customizes gamepad selection behavior in the left direction.
Customizes gamepad selection behavior in the right direction.
Customizes gamepad selection behavior in the up direction.
Allows customization of gamepad selection movement.
Eventos
Eventos heredados de GuiBase2d- SelectionChanged(amISelected : bool,previousSelection : GuiObject,newSelection : GuiObject):RBXScriptSignal
Fires when the gamepad selection moves to, leaves, or changes within the connected GuiBase2d or any descendant GuiObjects.
Propiedades
AlwaysOnTop
Determines whether the SurfaceGui will render over top of 3D content, or be occluded by it.
When set to false, the SurfaceGui will render like other 3D content, and will be occluded by other 3D objects.
When set to true, it 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.
- SurfaceGui.LightInfluence is treated as though it was 0.
- SurfaceGui.Brightness has no effect.
Brightness
Brightness determines the factor by which the GUI's emitted light is scaled. By default, this property is 1 and can be set to any number on the range [0, 1000].
By modifying this property, the apparent brightness of a GUI can be better matched to its environment. For instance, a video billboard like those found in Times Square can be made brighter to be clearly visible on a bright day.
This property won't produce any effect in the following scenarios wherein the GUI does not emit light.:
- When AlwaysOnTop is true, the color of each pixel is the color shown on-screen.
- When LightInfluence is 1, all light from the GUI is reflected from the environment instead of being emit.
CanvasSize
The size of a 'virtual screen', in 'virtual pixels', which makes SurfaceGuis pixel-to-pixel compatible with ScreenGuis.
ClipsDescendants
When set to true, portions of GuiObjects that fall outside of the SurfaceGui's canvas borders will not be drawn.
Even when this property is false, objects that are completely outside of the canvas of the SurfaceGui will not render.
LightInfluence
Controls how much the SurfaceGui is influenced by the lighting in the game world.
MaxDistance
Controls how far away the SurfaceGui can be displayed before it stops rendering. A value of 0 means there is no limit, and it will render infinitely far away.
For experiences with many SurfaceGuis, it's recommended to set this to an appropriate value for each SurfaceGui. The default value when inserting a SurfaceGui in Studio is 1000, which should be fine for most usages.
For UIs that are outdoors, you should set the MaxDistance far enough away so that the UI is small on the screen when it pops out, around 10 pixels across. This makes it less noticeable when it pops in or out.
You can reduce the pop in effect even more by adding a similar looking decal underneath the SurfaceGui, or by changing the part color to match the background color of your UI.
For indoor spaces, the MaxDistance should be set slightly larger than the size of the room, so that the UI won't render when the player is in a different room.
PixelsPerStud
PixelsPerStud determines the density of pixels used for each world-space stud to render the contents of the SurfaceGui.
Higher values will cause the various GuiObject 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 (either by using a UIScale or modifying Size or TextLabel.TextSize etc.), 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. Be mindful that a large pixel density could negatively affect performance if the face of the adorned part is large enough.
SizingMode
When set to Enum.SurfaceGuiSizingMode.FixedSize, SurfaceGui renders with a fixed size set using SurfaceGui.CanvasSize.
When set to Enum.SurfaceGuiSizingMode.PixelsPerStud, SurfaceGui renders with a variable size based on SurfaceGui.PixelsPerStud and the SurfaceGui's size in studs.
ToolPunchThroughDistance
Sets the distance left clicking starts acting on the surface gui instead of the held tool. If a character is within this distance of the surface gui, then the tool will not activate on click.