PcoWSkbVqDnWTu_dm2ix
The Developer Hub is now deprecated and information on this page may no longer be accurate. To see our new and improved documentation, please click here. You can read more about the future of documentation here.
Collapse Sidebar
  1. API Reference
  2. SurfaceGui

SurfaceGui

Show deprecated
Hide content
  1. apireference
  2. surfacegui

SurfaceGui

Show deprecated

Note: SurfaceGuis must be descendants of PlayerGui in order to know the player who is interacting with it.Allows for the rendering of GUI elements onto a part’s surface in the 3D world, whilst allowing for basic user interaction to occur.

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.

    Properties

    bool

    Active

    Whether or not mouse events will be passed to objects layered below.
    Instance

    Adornee

    Sets the object that the SurfaceGui is adorned too. In other words, this defines which BasePart the SurfaceGui is attached to.
    bool

    AlwaysOnTop

    Determines whether the SurfaceGui will always be rendered on top of other 3D objects.
    float

    Brightness

    Determines the factor by which the GUI’s light is scaled when SurfaceGui/LightInfluence|LightInfluence is 0.
    Vector2

    CanvasSize

    The size of a ‘virtual screen’, in ‘virtual pixels’, which makes SurfaceGuis pixel-to-pixel compatible with ScreenGuis.
    bool

    ClipsDescendants

    When set to true, portions of GuiObjects that fall outside of the SurfaceGui’s canvas borders will not be drawn.
    NormalId

    Face

    The face that the SurfaceGui is rendered on.
    float

    LightInfluence

    Controls how much the SurfaceGui is influenced by the lighting in the game world.
    float

    PixelsPerStud

    Determines the number of screen-space pixels per world-space stud used to render the contents of the SurfaceGui
    SurfaceGuiSizingMode

    SizingMode

    Determines whether SurfaceGui will render at fixed size or scale with its size in studs.
    float

    ToolPunchThroughDistance

    Sets the distance left clicking starts acting on the surface gui instead of the held tool.
    float

    ZOffset

    Offsets the SurfaceGui relative to the normal of the surface it is attached to.

    Inherited from LayerCollector: Show Hide

    bool

    Enabled

    Toggles the visibility of the LayerCollector.
    bool

    ResetOnSpawn

    Controls how this LayerCollector behaves when its associated Player respawns.
    ZIndexBehavior

    ZIndexBehavior

    Controls how GuiObject/ZIndex behaves on all descendants of the LayerCollector.

    Inherited from GuiBase2d: Show Hide

    Vector2

    AbsolutePosition

    [ReadOnly] [NotReplicated]

    Describes the actual screen position of a UI element, in pixels.
    float

    AbsoluteRotation

    [ReadOnly] [NotReplicated]

    Describes the actual screen rotation of a UI element, in degrees.
    Vector2

    AbsoluteSize

    [ReadOnly] [NotReplicated]

    Describes the actual screen size of a UI element, in pixels.
    bool

    AutoLocalize

    When set to true, localization will be applied to this GuiBase2d and its descendants based on the GuiBase2d/RootLocalizationTable specified for this GuiBase2d.
    Rect

    ClippedRect

    [Hidden] [ReadOnly] [NotReplicated]
    bool

    IsNotOccluded

    [Hidden] [ReadOnly] [NotReplicated]
    bool

    Localize

    [Hidden] [NotReplicated] [Deprecated]

    Automatically set to true when a LocalizationTable’s Root targets this object, or an ancestor of this object.
    Rect

    RawRect2D

    [Hidden] [ReadOnly] [NotReplicated]
    LocalizationTable

    RootLocalizationTable

    A reference to a LocalizationTable to be used to apply automated localization to this GuiBase2d and its descendants.
    float

    TotalGroupScale

    [Hidden] [ReadOnly] [NotReplicated]

    Inherited from Instance: Show Hide

    bool

    Archivable

    Determines if an Instance can be cloned using /Instance/Clone or saved to file.
    string

    ClassName

    [ReadOnly] [NotReplicated]

    A read-only string representing the class this Instance belongs to
    int

    DataCost

    [Hidden] [ReadOnly] [NotReplicated] [Deprecated]

    The cost of saving the instance using data persistence.
    string

    Name

    A non-unique identifier of the Instance
    Instance

    Parent

    [NotReplicated]

    Determines the hierarchical parent of the Instance
    bool

    RobloxLocked

    [Hidden]

    A deprecated property that used to protect CoreGui objects
    int64

    SourceAssetId

    [Hidden] [NotReplicated]
    bool

    archivable

    [Hidden] [NotReplicated] [Deprecated]
    string

    className

    [ReadOnly] [NotReplicated] [Deprecated]

    Functions

    Inherited from Instance: Show Hide

    void

    ClearAllChildren ( )

    This function destroys all of an Instance’s children.
    Instance

    Clone ( )

    Create a copy of an object and all its descendants, ignoring objects that are not Instance/Archivable|Archivable
    void

    Destroy ( )

    Sets the Instance/Parent property to nil, locks the Instance/Parent property, disconnects all connections, and calls Destroy on all children.
    Instance

    FindFirstAncestor ( string name )

    Returns the first ancestor of the Instance whose Instance/Name is equal to the given name.
    Instance

    FindFirstAncestorOfClass ( string className )

    Returns the first ancestor of the Instance whose Instance/ClassName is equal to the given className.
    Instance

    FindFirstAncestorWhichIsA ( string className )

    Returns the first ancestor of the Instance for whom Instance/IsA returns true for the given className.
    Instance

    FindFirstChild ( string name , bool recursive )

    Returns the first child of the Instance found with the given name.
    Instance

    FindFirstChildOfClass ( string className )

    Returns the first child of the Instance whose Instance/ClassName|ClassName is equal to the given className.
    Instance

    FindFirstChildWhichIsA ( string className , bool recursive )

    Returns the first child of the Instance for whom Instance/IsA returns true for the given className.
    Instance

    FindFirstDescendant ( string name )

    Returns the first descendant found with the given Instance/Name.
    Actor

    GetActor ( )

    Returns the Actor associated with the Instance, usually the first Actor ancestor
    Variant

    GetAttribute ( string attribute )

    Returns the attribute which has been assigned to the given name
    RBXScriptSignal

    GetAttributeChangedSignal ( string attribute )

    Returns an event that fires when the given attribute changes
    Dictionary

    GetAttributes ( )

    Returns a dictionary of string → variant pairs for each of the Instance|Instance’s attributes
    Objects

    GetChildren ( )

    Returns an array containing all of the Instance’s children.
    string

    GetDebugId ( int scopeLength )

    [NotBrowsable]

    Returns a coded string of the Instances DebugId used internally by Roblox.
    Array

    GetDescendants ( )

    [CustomLuaState]

    Returns an array containing all of the descendants of the instance
    string

    GetFullName ( )

    Returns a string describing the Instance’s ancestry.
    RBXScriptSignal

    GetPropertyChangedSignal ( string property )

    Get an event that fires when a given property of an object changes.
    bool

    IsA ( string className )

    [CustomLuaState]

    Returns true if an Instance’s class matches or inherits from a given class
    bool

    IsAncestorOf ( Instance descendant )

    Returns true if an Instance is an ancestor of the given descendant.
    bool

    IsDescendantOf ( Instance ancestor )

    Returns true if an Instance is a descendant of the given ancestor.
    void

    Remove ( )

    [Deprecated]

    Sets the object’s Parent to nil, and does the same for all its descendants.
    void

    SetAttribute ( string attribute , Variant value )

    Sets the attribute with the given name to the given value
    Instance

    WaitForChild ( string childName , double timeOut )

    [CustomLuaState] [CanYield]

    Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does.
    Objects

    children ( )

    [Deprecated]

    Returns an array of the object’s children.
    Instance

    clone ( )

    [Deprecated]
    void

    destroy ( )

    [Deprecated]
    Instance

    findFirstChild ( string name , bool recursive )

    [Deprecated]
    Objects

    getChildren ( )

    [Deprecated]
    bool

    isA ( string className )

    [Deprecated] [CustomLuaState]
    bool

    isDescendantOf ( Instance ancestor )

    [Deprecated]
    void

    remove ( )

    [Deprecated]

    Events

    Inherited from Instance: Show Hide

    RBXScriptSignal

    AncestryChanged ( Instance child , Instance parent )

    Fires when the Instance/Parent property of the object or one of its ancestors is changed.
    RBXScriptSignal

    AttributeChanged ( string attribute )

    Fires whenever an attribute is changed on the Instance
    RBXScriptSignal

    Changed ( string property )

    Fired immediately after a property of an object changes.
    RBXScriptSignal

    ChildAdded ( Instance child )

    Fires after an object is parented to this Instance.
    RBXScriptSignal

    ChildRemoved ( Instance child )

    Fires after a child is removed from this Instance.
    RBXScriptSignal

    DescendantAdded ( Instance descendant )

    Fires after a descendant is added to the Instance
    RBXScriptSignal

    DescendantRemoving ( Instance descendant )

    Fires immediately before a descendant of the Instance is removed.
    RBXScriptSignal

    Destroying ( )

    Fires immediately before the instance is destroyed via Instance/Destroy.
    RBXScriptSignal

    childAdded ( Instance child )

    [Deprecated]
    StarterGui TextBox