rojo/.cursor/rules/roblox/reference/engine/classes/SurfaceGui.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: SurfaceGui
type: class
memory_category: Instances
summary: |
  Container for GuiObjects that are rendered on the surface of a part.
description: |
  `Class.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 `Class.Decal|Decals` and `Class.Texture|Textures`, UI
  objects such as `Class.TextLabel|TextLabels` and
  `Class.ImageLabel|ImageLabels` parented to a `Class.SurfaceGui` face the same
  direction as the surface they're on, editable through the
  `Class.SurfaceGui.Face|Face` property.

  <img src="/assets/ui/in-experience/SurfaceGui-Diagram.jpg" width="800" alt="SurfaceGui on a 3D part in the place with an ImageLabel child to depict a screen console." />

  Note that interactive UI elements like `Class.ImageButton|ImageButtons` and
  `Class.TextButton|TextButtons` inside a `Class.SurfaceGui` will only receive
  user input if they are parented to the `Class.PlayerGui`, typically via
  placing the `Class.SurfaceGui` inside `Class.StarterGui` (the
  `Class.SurfaceGui.Adornee|Adornee` property can be used to target a part in
  the 3D world while the `Class.SurfaceGui` itself remains in the
  `Class.PlayerGui`). Additionally, the part's
  `Class.BasePart.CanQuery|CanQuery` property must be `true` for the interactive
  UI element to receive input.

  See [In-Experience UI](../../../ui/in-experience-containers.md#surface-ui) for
  a guide on working with `Class.SurfaceGui` containers.

  ##### Caching Behavior

  To help improve performance, the appearance of a `Class.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 `Class.SurfaceGui`.
  - A property of a descendant of the `Class.SurfaceGui` changes.
  - A property of the `Class.SurfaceGui` itself changes.
code_samples: []
inherits:
  - SurfaceGuiBase
descendants: []
tags: []
deprecation_message: ''
properties:
  - name: SurfaceGui.AlwaysOnTop
    summary: |
      Determines whether the `Class.SurfaceGui` will always be rendered on top
      of other 3D objects.
    description: |
      This property determines whether the `Class.SurfaceGui` will always render
      on top of other 3D objects.

      When set to `false` (default), the `Class.SurfaceGui` renders like other
      3D content and is occluded by other 3D objects. When set to `true`, the
      `Class.SurfaceGui` always renders on top of 3D content and the appearance
      changes significantly:

      - Colors match how they appear inside a `Class.ScreenGui`.
      - Text may appear sharper on high DPI devices.
      - `Class.SurfaceGui.LightInfluence|LightInfluence` is treated as though
        it's `0`.
      - `Class.SurfaceGui.Brightness|Brightness` has no effect.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.Brightness
    summary: |
      Determines the factor by which the `Class.SurfaceGui` container's light is
      scaled when `Class.SurfaceGui.LightInfluence|LightInfluence` is `0`.
    description: |
      This property determines the factor by which the `Class.SurfaceGui`
      container's light is scaled when
      `Class.SurfaceGui.LightInfluence|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 `Class.SurfaceGui`
      can be better matched to its environment. For instance, a video billboard
      can be brightened inside a dark room by increasing
      `Class.SurfaceGui.Brightness|Brightness` to `10`.

      Note that `Class.SurfaceGui.Brightness|Brightness` is inaccessible in
      Studio and has no effect when either
      `Class.SurfaceGui.LightInfluence|LightInfluence` is `1` or
      `Class.SurfaceGui.AlwaysOnTop|AlwaysOnTop` is `true`.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.CanvasSize
    summary: |
      The size of a "virtual screen" in "virtual pixels" which makes
      `Class.SurfaceGui|SurfaceGuis` pixel-to-pixel compatible with
      `Class.ScreenGui|ScreenGuis`.
    description: |
      The size of a "virtual screen" in "virtual pixels" which makes
      `Class.SurfaceGui|SurfaceGuis` pixel-to-pixel compatible with
      `Class.ScreenGui|ScreenGuis`.
    code_samples: []
    type: Vector2
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Sizing
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.ClipsDescendants
    summary: |
      Whether portions of `Class.GuiObject|GuiObjects` that fall outside of the
      `Class.SurfaceGui` canvas borders will be drawn.
    description: |
      When set to `true` (default), portions of `Class.GuiObject|GuiObjects`
      that fall outside of the `Class.SurfaceGui` canvas borders will not be
      drawn.

      Even when this property is `false`, `Class.GuiObject|GuiObjects` that are
      **completely** outside of the canvas will not render.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Behavior
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.LightInfluence
    summary: |
      Controls how much the `Class.SurfaceGui` is influenced by environmental
      lighting.
    description: |
      Controls how much the `Class.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.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.MaxDistance
    summary: |
      Controls how far away the `Class.SurfaceGui` can be displayed before it
      stops rendering.
    description: |
      This property controls how far from the camera the `Class.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 `Class.SurfaceGui|SurfaceGuis` that appear outdoors, it's recommended
      that `Class.SurfaceGui.MaxDistance|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.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.PixelsPerStud
    summary: |
      Determines the density of pixels used for each world-space stud to render
      the contents of the `Class.SurfaceGui`.
    description: |
      This property determines the density of pixels used for each world-space
      stud to render the contents of the `Class.SurfaceGui`. Higher values will
      cause the various `Class.GuiObject|GuiObjects` within to appear smaller if
      they are kept the same size. Conversely, lower values will cause objects
      to appear larger. However, if the `Class.GuiObject|GuiObjects` are scaled
      proportionally through use of `Class.UIScale`, `Class.GuiObject.Size`,
      `Class.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 `Class.SurfaceGui`. Also be mindful that a large pixel density
      could negatively affect performance if the face of the adorned part is
      large enough.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Sizing
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.SizingMode
    summary: |
      Determines whether the `Class.SurfaceGui` will render at a fixed size or
      scale with its size in studs.
    description: |
      When set to `Enum.SurfaceGuiSizingMode.PixelsPerStud` (default), the
      `Class.SurfaceGui` renders with a variable size based on
      `Class.SurfaceGui.PixelsPerStud|PixelsPerStud` and the surface's size in
      studs.

      When set to `Enum.SurfaceGuiSizingMode.FixedSize`, the `Class.SurfaceGui`
      renders with a fixed size set through
      `Class.SurfaceGui.CanvasSize|CanvasSize`.
    code_samples: []
    type: SurfaceGuiSizingMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Sizing
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.ToolPunchThroughDistance
    summary: |
      Sets the distance in which left clicking starts acting on the
      `Class.SurfaceGui` instead of for the held `Class.Tool`.
    description: |
      Sets the distance in which left clicking starts acting on the
      `Class.SurfaceGui` instead of for the held `Class.Tool`. If a character is
      within this distance of the `Class.SurfaceGui`, the `Class.Tool` will not
      activate on click.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: SurfaceGui.ZOffset
    summary: |
      Layers this `Class.SurfaceGui` in relation to other
      `Class.SurfaceGui|SurfaceGuis` on the same face.
    description: |
      Layers this `Class.SurfaceGui` in relation to others on the same face
      (changing this does not visually "lift" or "sink" a `Class.SurfaceGui`
      from the surface).
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
methods: []
events: []
callbacks: []