rojo/.cursor/rules/roblox/reference/engine/classes/BillboardGui.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: BillboardGui
type: class
memory_category: Instances
summary: |
  A container for `Class.GuiObject|GuiObjects` that renders in 3D space facing
  the camera.
description: |
  `Class.BillboardGui` is a container for UI objects to appear in the 3D space
  but always face the camera. The container's position is relative to the parent
  `Class.BasePart` or `Class.Attachment` (or the
  `Class.BillboardGui.Adornee|Adornee`). For `Class.BasePart|BaseParts`, the
  `Class.BasePart.Position|Position` property is used, while for
  `Class.Attachment|Attachments`, the
  `Class.Attachment.WorldPosition|WorldPosition` property is used.

  <img src="/assets/ui/in-experience/BillboardGui-Diagram.jpg" width="800" alt="BillboardGui with a TextLabel describing the screen console it floats above." />

  A billboard's `Class.BillboardGui.Size|Size` property works slightly
  differently than `Class.GuiObject.Size`. While the **offset** components work
  the same, the **scale** components are used as stud sizes in 3D space.

  When creating a size-scaled `Class.BillboardGui` that contains a
  `Class.TextLabel`, it's useful to enable the label's
  `Class.TextLabel.TextScaled|TextScaled` property so that its text scales along
  with the billboard canvas as the camera distance changes.

  Note that interactive UI elements like `Class.ImageButton|ImageButtons` and
  `Class.TextButton|TextButtons` inside a `Class.BillboardGui` will only receive
  user input if they are parented to the `Class.PlayerGui`, typically via
  placing the `Class.BillboardGui` inside `Class.StarterGui`. The
  `Class.BillboardGui.Adornee|Adornee` property can be used to target a part or
  attachment in the 3D world while the `Class.BillboardGui` itself remains in
  the `Class.PlayerGui`.

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

  ##### Caching Behavior

  To help improve performance, the appearance of a `Class.BillboardGui` 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.BillboardGui`.
  - A property of a descendant of the `Class.BillboardGui` changes.
  - A property of the `Class.BillboardGui` itself changes.
code_samples: []
inherits:
  - LayerCollector
descendants: []
tags: []
deprecation_message: ''
properties:
  - name: BillboardGui.Active
    summary: |
      Controls whether the descendants will receive input events.
    description: |
      Controls whether the descendants will receive input events. If the
      `Class.BillboardGui` contains a `Class.GuiButton`, that button will become
      clickable only if `Class.BillboardGui.Active|Active` is set to `true` on
      both the `Class.BillboardGui` **and** the button.

      Note that interactive UI elements like `Class.ImageButton|ImageButtons`
      and `Class.TextButton|TextButtons` inside a `Class.BillboardGui` will only
      receive user input if they are parented to the `Class.PlayerGui`,
      typically via placing the `Class.BillboardGui` inside `Class.StarterGui`.
      The `Class.BillboardGui.Adornee|Adornee` property can be used to target a
      part or attachment in the 3D world while the `Class.BillboardGui` itself
      remains in the `Class.PlayerGui`.
    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: BillboardGui.Adornee
    summary: |
      Sets the target part or attachment that the `Class.BillboardGui` is
      positioned relative to.
    description: |
      Sets the target `Class.BasePart` or `Class.Attachment` that the
      `Class.BillboardGui` is positioned relative to, overriding the parent part
      or attachment.
    code_samples: []
    type: Instance
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.AlwaysOnTop
    summary: |
      Determines whether the `Class.BillboardGui` will always be rendered on top
      of other 3D objects.
    description: |
      This property determines whether the `Class.BillboardGui` will always
      render on top of other 3D objects.

      When set to `false` (default), the `Class.BillboardGui` renders like other
      3D content and is occluded by other 3D objects. When set to `true`, the
      `Class.BillboardGui` 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.BillboardGui.LightInfluence|LightInfluence` is treated as though
        it's `0`.
      - `Class.BillboardGui.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: BillboardGui.Brightness
    summary: |
      Determines the factor by which the `Class.BillboardGui` container's light
      is scaled when `Class.BillboardGui.LightInfluence|LightInfluence` is `0`.
    description: |
      This property determines the factor by which the `Class.BillboardGui`
      container's light is scaled when
      `Class.BillboardGui.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.BillboardGui` can be better matched to its environment. For
      instance, a video billboard can be brightened inside a dark room by
      increasing `Class.BillboardGui.Brightness|Brightness` to `10`.

      Note that `Class.BillboardGui.Brightness|Brightness` is inaccessible in
      Studio and has no effect when either
      `Class.BillboardGui.LightInfluence|LightInfluence` is `1` or
      `Class.BillboardGui.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: BillboardGui.ClipsDescendants
    summary: |
      Whether portions of `Class.GuiObject|GuiObjects` that fall outside of the
      `Class.BillboardGui` canvas borders will be drawn.
    description: |
      When set to `true` (default), portions of `Class.GuiObject|GuiObjects`
      that fall outside of the `Class.BillboardGui` 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: BillboardGui.CurrentDistance
    summary: |
      The current distance in studs that the `Class.BillboardGui` is from the
      player's camera.
    description: |
      The current distance in studs that the `Class.BillboardGui` is from the
      player's camera. A changed event does not fire for this property unless
      `Class.BillboardGui.DistanceStep|DistanceStep` is more than `0`.
    code_samples: []
    type: float
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - UI
  - name: BillboardGui.DistanceLowerLimit
    summary: |
      Determines the distance in studs at which the `Class.BillboardGui` will
      stop scaling larger in size.
    description: |
      Determines the distance in studs at which the `Class.BillboardGui` will
      stop scaling larger in size relative to the player's current camera, with
      a default of `0`. If the
      `Class.BillboardGui.CurrentDistance|CurrentDistance` of the
      `Class.BillboardGui` is below this value, it will not scale any larger
      than it would at this distance.
    code_samples: []
    type: float
    tags:
      - Deprecated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.DistanceStep
    summary: |
      Determines the size `Class.BillboardGui.CurrentDistance|CurrentDistance`
      increments and decrements in studs as the player's camera moves closer and
      further from the `Class.BillboardGui`.
    description: |
      Determines the size `Class.BillboardGui.CurrentDistance|CurrentDistance`
      increments and decrements in studs as the player's camera moves closer and
      further from the `Class.BillboardGui`. The property defaults to `0`.
    code_samples: []
    type: float
    tags:
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: false
    capabilities:
      - UI
  - name: BillboardGui.DistanceUpperLimit
    summary: |
      Determines the distance in studs at which the `Class.BillboardGui` will
      stop scaling smaller in size.
    description: |
      Determines the distance in studs at which the `Class.BillboardGui` will
      stop scaling smaller in size relative to the player's current camera. If
      the `Class.BillboardGui.CurrentDistance|CurrentDistance` of the
      `Class.BillboardGui` is above this value, it will not scale any smaller
      than it would at this distance.

      This property is ignored if the value is less than `0`. The default value
      is `-1`, meaning the property is ignored by default.
    code_samples: []
    type: float
    tags:
      - Deprecated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.ExtentsOffset
    summary: |
      Determines how the `Class.BillboardGui` is offset from its
      `Class.BillboardGui.Adornee|Adornee`, relative to the `Class.Camera`
      orientation, in units half the dimensions of the model's
      `Class.Camera`-aligned bounding box.
    description: |
      This property determines how the `Class.BillboardGui` is offset from its
      `Class.BillboardGui.Adornee|Adornee`, relative to the `Class.Camera`
      orientation, in units half the dimensions of the model's
      `Class.Camera`-aligned bounding box.

      See also `Class.BillboardGui.StudsOffset|StudsOffset` which works
      similarly but uses stud units, or
      `Class.BillboardGui.ExtentsOffsetWorldSpace|ExtentsOffsetWorldSpace` which
      works similarly except the offset orientation is relative to the global
      axes.
    code_samples: []
    type: Vector3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.ExtentsOffsetWorldSpace
    summary: |
      Determines how the `Class.BillboardGui` is offset from its
      `Class.BillboardGui.Adornee|Adornee`, relative to the global axes, in
      units half the dimensions of the model's axis-aligned bounding box.
    description: |
      This property determines how the `Class.BillboardGui` is offset from its
      `Class.BillboardGui.Adornee|Adornee`, relative to the global axes, in
      units half the dimensions of the model's axis-aligned bounding box.

      See also `Class.BillboardGui.StudsOffset|StudsOffset` which works
      similarly but uses stud units, or
      `Class.BillboardGui.ExtentsOffset|ExtentsOffset` which works similarly
      except the offset orientation is relative to the `Class.Camera`.
    code_samples: []
    type: Vector3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.LightInfluence
    summary: |
      Controls how much the `Class.BillboardGui` is influenced by environmental
      lighting.
    description: |
      Controls how much the `Class.BillboardGui` 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: BillboardGui.MaxDistance
    summary: |
      Controls how far away the `Class.BillboardGui` can be displayed before it
      stops rendering.
    description: |
      This property controls how far from the camera the `Class.BillboardGui`
      will be displayed before it stops rendering. A value of `0` or `inf`
      (default) means there is no limit and it will render infinitely far away.

      For `Class.BillboardGui|BillboardGuis` that appear outdoors, it's
      recommended that `Class.BillboardGui.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: BillboardGui.PlayerToHideFrom
    summary: |
      Used by scripts to hide the `Class.BillboardGui` from a specific player.
    description: |
      Used by scripts to hide the `Class.BillboardGui` from a specific player.

      To hide a `Class.BillboardGui` from more than one player, place it into
      `Class.StarterGui` and use a script to set the
      `Class.BillboardGui.Enabled|Enabled` property according to whether the
      `Class.Players.LocalPlayer|LocalPlayer` should be able to see it. The
      `Class.BillboardGui.Adornee|Adornee` property can be used to attach the
      `Class.BillboardGui` to a `Class.BasePart` or `Class.Attachment` in the
      `Class.Workspace`, instead of parenting it.
    code_samples: []
    type: Instance
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.Size
    summary: |
      Controls the size that the `Class.BillboardGui` will have on screen.
    description: |
      Controls the size that the `Class.BillboardGui` will have on screen.
      Unlike `Class.GuiObject.Size`, the
      [scale](../../../ui/position-and-size.md#size) components of this property
      set the billboard's stud size in 3D space.
    code_samples: []
    type: UDim2
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.SizeOffset
    summary: |
      A 2D offset in size-relative units that acts like an anchor point.
    description: |
      A 2D offset in size-relative units that acts like an anchor point. This
      can be used similarly to the `Class.GuiObject.AnchorPoint` property, but
      the values are different.

      <table size="small">
      <thead>
      <th>Size Offset</th>
      <th>Explanation</th>
      </thead>
      <tbody>
      <tr>
      <td><code>0, 0</code></td>
      <td>The default in which UI will be anchored at its center.</td>
      </tr>
      <tr>
      <td><code>0.5, 0.5</code></td>
      <td>UI will anchor at the bottom left.</td>
      </tr>
      <tr>
      <td><code>0.5, -0.5</code></td>
      <td>UI will anchor at the top left.</td>
      </tr>
      <tr>
      <td><code>-0.5, 0.5</code></td>
      <td>UI will anchor at the top right.</td>
      </tr>
      <tr>
      <td><code>-0.5, -0.5</code></td>
      <td>UI will anchor at the bottom right.</td>
      </tr>
      </tbody>
      </table>

      See also `Class.BillboardGui.StudsOffset|StudsOffset`,
      `Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`,
      `Class.BillboardGui.ExtentsOffset|ExtentsOffset`, and
      `Class.BillboardGui.ExtentsOffsetWorldSpace|ExtentsOffsetWorldSpace` which
      are offset properties that work in 3D space instead.
    code_samples: []
    type: Vector2
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.StudsOffset
    summary: |
      Determines how the `Class.BillboardGui` is offset from its
      `Class.BillboardGui.Adornee|Adornee` in studs, relative to the
      `Class.Camera` orientation.
    description: |
      This property determines how the `Class.BillboardGui` is offset from its
      `Class.BillboardGui.Adornee|Adornee` in studs, relative to the
      `Class.Camera` orientation.

      See also `Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`
      which works similarly except the offset orientation is relative to the
      global axes.
    code_samples: []
    type: Vector3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: BillboardGui.StudsOffsetWorldSpace
    summary: |
      Determines how the `Class.BillboardGui` is offset from its
      `Class.BillboardGui.Adornee|Adornee` in studs, relative to the global
      axes.
    description: |
      This property determines how the `Class.BillboardGui` is offset from its
      `Class.BillboardGui.Adornee|Adornee` in studs, relative to the global
      axes.

      See also `Class.BillboardGui.StudsOffset|StudsOffset` which works
      similarly except the offset orientation is relative to the `Class.Camera`.
    code_samples: []
    type: Vector3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
methods: []
events: []
callbacks: []