`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#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.


BillboardGui

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`.


BillboardGui.Active

Controls whether the descendants will receive input events.


Sets the target `Class.BasePart` or `Class.Attachment` that the
`Class.BillboardGui` is positioned relative to, overriding the parent part
or attachment.


BillboardGui.Adornee

Sets the target part or attachment that the `Class.BillboardGui` is
positioned relative to.


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.


BillboardGui.AlwaysOnTop

Determines whether the `Class.BillboardGui` will always be rendered on top
of other 3D objects.


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`.


BillboardGui.Brightness

Determines the factor by which the `Class.BillboardGui` container's light
is scaled when `Class.BillboardGui.LightInfluence|LightInfluence` is `0`.


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.


BillboardGui.ClipsDescendants

Whether portions of `Class.GuiObject|GuiObjects` that fall outside of the
`Class.BillboardGui` canvas borders will be drawn.


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`.


BillboardGui.CurrentDistance

The current distance in studs that the `Class.BillboardGui` is from the
player's camera.


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.


BillboardGui.DistanceLowerLimit

Determines the distance in studs at which the `Class.BillboardGui` will
stop scaling larger in size.


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`.


BillboardGui.DistanceStep

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`.


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.


BillboardGui.DistanceUpperLimit

Determines the distance in studs at which the `Class.BillboardGui` will
stop scaling smaller in size.


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.


BillboardGui.ExtentsOffset

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.


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`.


BillboardGui.ExtentsOffsetWorldSpace

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.


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.


BillboardGui.LightInfluence

Controls how much the `Class.BillboardGui` is influenced by environmental
lighting.


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.


BillboardGui.MaxDistance

Controls how far away the `Class.BillboardGui` can be displayed before it
stops rendering.


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.


BillboardGui.PlayerToHideFrom

Used by scripts to hide the `Class.BillboardGui` from a specific player.


Controls the size that the `Class.BillboardGui` will have on screen.
Unlike `Class.GuiObject.Size`, the
[scale](/ui/position-and-size#size) components of this property
set the billboard's stud size in 3D space.


BillboardGui.Size

Controls the size that the `Class.BillboardGui` will have on screen.


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.


BillboardGui.SizeOffset

A 2D offset in size-relative units that acts like an anchor point.


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.


BillboardGui.StudsOffset

Determines how the `Class.BillboardGui` is offset from its
`Class.BillboardGui.Adornee|Adornee` in studs, relative to the
`Class.Camera` orientation.


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`.


BillboardGui.StudsOffsetWorldSpace

Determines how the `Class.BillboardGui` is offset from its
`Class.BillboardGui.Adornee|Adornee` in studs, relative to the global
axes.


A container for `Class.GuiObject|GuiObjects` that renders in 3D space facing
the camera.


**LayerCollector** is the base class of 2D UI containers which render
`Class.GuiObject` descendants, such as `Class.ScreenGui`.

For performance improvements, the appearance of a `Class.LayerCollector` is
cached until one of the following events occurs:

- A descendant is added to or removed from it.
- A property of a descendant changes.
- A property of the `Class.LayerCollector` itself changes.


LayerCollector:GetLayoutNodeTree

LayerCollector

Toggles the visibility of this `Class.LayerCollector`. When `false`, the
UI contents will not render, process user input, or update in response to
changes.


LayerCollector.Enabled

Toggles the visibility of this `Class.LayerCollector`.


When set to `false` and this `Class.LayerCollector` is a direct child of
`Class.StarterGui`, it will only be cloned into each player's
`Class.PlayerGui` once and it will not be deleted when the player's
character respawns.

When set to `true` (default), or if this `Class.LayerCollector` is an
**indirect** descendant of `Class.StarterGui`, it will be cloned into each
player's `Class.PlayerGui` when their character respawns, and it will
delete itself when the player's character respawns again.


LayerCollector.ResetOnSpawn

Determines if the `Class.LayerCollector` resets (deletes itself and
re-clones into the player's `Class.PlayerGui`) every time the player's
character respawns.


Controls how `Class.GuiObject.ZIndex` behaves on all descendants of this
`Class.LayerCollector`.

With `Enum.ZIndexBehavior.Sibling` (default), children always render above
their parents, and the `Class.GuiObject.ZIndex|ZIndex` is used to decide
the order in which children of a single UI object will render over each
other.

`Enum.ZIndexBehavior.Global` sorts all descendants according to the
`Class.GuiObject.ZIndex|ZIndex`, then breaks ties using the hierarchy
order. As a result, descendants of a `Class.GuiObject` need to have a
`Class.GuiObject.ZIndex|ZIndex` value that's at least as high as the
parent, or they will render underneath their parent.


LayerCollector.ZIndexBehavior

Controls how `Class.GuiObject.ZIndex` behaves on all descendants of this
`Class.LayerCollector`.


The base class of 2D UI containers which render `Class.GuiObject|GuiObjects`
in layers.


`Class.GuiBase2d` is an abstract class inherited by 2D
`Class.GuiObject|GuiObjects`.


This event fires when the gamepad selection moves to, leaves, or changes
within the connected `Class.GuiBase2d` or any descendant
`Class.GuiObject|GuiObjects`. When the selection highlight moves to a
`Class.GuiObject`, the event bubbles from that `Class.GuiObject` to all of
its ancestors, informing them that the selection has
changed/entered/exited to a `Class.GuiObject` in their descendant tree.


GuiBase2d.SelectionChanged

amISelected

True if the new selection matches the attached GuiBase2d.


previousSelection

newSelection

Fires when the gamepad selection moves to, leaves, or changes within the
connected `Class.GuiBase2d` or any descendant
`Class.GuiObject|GuiObjects`.


GuiBase2d

`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` is a read-only
property that provides the screen position of a `Class.GuiBase2d` element
in pixels. This represents the actual pixel position at which an element
renders as a result of its ancestors' sizes and positions. Note that
`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` always represents the
top-left corner of the `Class.GuiBase2d` element.

If the `Class.GuiBase2d` is in a `Class.ScreenGui`, the
`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` property uses the
`Enum.ScreenInsets|CoreUISafeInsets` viewport coordinate system. The
origin of this coordinate system is located at the bottom-left corner of
the Roblox top bar. Note that this is the same coordinate system used by
the `Class.InputObject.Position` property.

<img src="/assets/engine-api/classes/GuiBase2d/AbsolutePositionCoordinateSystem.png" width="840" alt="Diagram showing the origin of the AbsolutePosition coordinate system." />

See also `Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` and
`Class.GuiBase2d.AbsoluteSize|AbsoluteSize`.


GuiBase2d.AbsolutePosition

Describes the actual screen position of a `Class.GuiBase2d` element, in
pixels.


`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` is a read-only
property that describes the actual screen rotation of a `Class.GuiBase2d`
element, in degrees. It does **not** perform bounds checking, so its value
may not be in the range `0` to `360`.

See also `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` and
`Class.GuiBase2d.AbsoluteSize|AbsoluteSize`.


GuiBase2d.AbsoluteRotation

Describes the actual screen rotation of a `Class.GuiBase2d` element, in
degrees.


`Class.GuiBase2d.AbsoluteSize|AbsoluteSize` is a read-only property that
describes the actual screen size of a `Class.GuiBase2d` element, in
pixels.

See also `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` and
`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation`.


GuiBase2d.AbsoluteSize

Describes the actual screen size of a `Class.GuiBase2d` element, in
pixels.


When set to `true`, localization will be applied to this `Class.GuiBase2d`
and its descendants. The entries used for localization are the same set of
entries returned by `Class.LocalizationService:GetTableEntries()`. Entries
with `Class.GuiBase2d.AutoLocalize|AutoLocalize` enabled are automatically
re-translated after the cloud table loads if necessary.

See also `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable`.


GuiBase2d.AutoLocalize

When set to `true`, localization will be applied to this `Class.GuiBase2d`
and its descendants.


This property is automatically set to true when a localization table's
`Class.LocalizationTable.Root` targets this object, or an ancestor of this
object. `Class.LocalizationTable|LocalizationTables` with their
`Class.LocalizationTable.Root` property pointed at an instance will
localize all `Class.TextLabel.TextButton` that are descendants of the root
instance.


GuiBase2d.Localize

Automatically set to true when a localization table's
`Class.LocalizationTable.Root` targets this object, or an ancestor of this
object.


A reference to a `Class.LocalizationTable` to be used to apply automated
localization to this `Class.GuiBase2d` and its descendants.
`Class.GuiBase2d.AutoLocalize|AutoLocalize` must be set to `true` on the
`Class.GuiBase2d` and its ancestors for automated localization to be
applied.

You can set this to reference a `Class.LocalizationTable` anywhere in the
`Class.DataModel`. The `Class.GuiBase2d` object and all of its children
will try to use that specific `Class.LocalizationTable` and its ancestors
for automatic text replacement before using the tables under
`Class.LocalizationService` in an undefined order and the cloud table.

If there is no translation available in the referenced table, it will look
for a translation in the parent of that table, if it is also a
`Class.LocalizationTable`, and so on.

See also `Class.LocalizationService:GetTableEntries()` which explains how
the `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable` is used
for automated localization.


GuiBase2d.RootLocalizationTable

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


Customizes gamepad selection behavior in the down direction.


GuiBase2d.SelectionBehaviorDown

Customizes gamepad selection behavior in the left direction.


GuiBase2d.SelectionBehaviorLeft

Customizes gamepad selection behavior in the right direction.


GuiBase2d.SelectionBehaviorRight

Customizes gamepad selection behavior in the up direction.


GuiBase2d.SelectionBehaviorUp

Allows for customization of how gamepad selection can move between
buttons, which are descendants of the selection group, leave the group,
and select other buttons.

Setting `Class.GuiBase2d.SelectionGroup|SelectionGroup` to `true` exposes
the `Class.GuiBase2d.SelectionBehaviorUp|SelectionBehaviorUp`,
`Class.GuiBase2d.SelectionBehaviorDown|SelectionBehaviorDown`,
`Class.GuiBase2d.SelectionBehaviorLeft|SelectionBehaviorLeft`, and
`Class.GuiBase2d.SelectionBehaviorRight|SelectionBehaviorRight`
properties. For these selection behaviors, a setting of
`Enum.SelectionBehavior.Escape` (default) means the gamepad selection
tries to first find a selection within the selection group and only moves
outside if it does not find a suitable button. Alternatively, a setting of
`Enum.SelectionBehavior.Stop` means gamepad selection only looks within
the selection group and does not move outside of the group from the
selection behavior direction.


GuiBase2d.SelectionGroup

Allows customization of gamepad selection movement.


An abstract class inherited by 2D `Class.GuiObject|GuiObjects`.


GuiBase is an abstract class which most graphical user interface objects
inherit from.


GuiBase

`Instance` is the base class for all classes in the Roblox class hierarchy
which can be part of the `Class.DataModel` tree.

It is not possible to directly create root `Instance` objects, but the special
`Datatype.Instance.new()` constructor creates objects via code, taking the
name of the class as a parameter and returning the created object.


Demonstrates detecting changes to an instance's ancestry by connecting to the
`Class.Instance.AncestryChanged` event.

The ChangingPart's Parent is set to different values overtime. The parent of
the part is the part's ancestor, so the `Class.Instance.AncestryChanged` event
will fire whenever it changes.


Fires when this instance is reparented or when any of its ancestors is
reparented.

You can use this event to track the deletion of an instance in Studio,
such as manual deletion in the Explorer or through a plugin. If you need
to detect when an instance is destroyed using `Class.Instance:Destroy()`,
use the `Class.Instance.Destroying` event instead.


Instance.AncestryChanged

child

The instance whose `Class.Instance.Parent|Parent` property changed,
which can be this instance or a more distant ancestor, **not**
necessarily the instance the handler is connected to.


parent

The new parent of the `child` parameter.


Fires when the `Class.Instance.Parent` property of this object or one of
its ancestors is changed.


This event fires whenever any attribute is changed on the instance,
including when an attribute is set to `nil`. The name of the changed
attribute is passed to the connected function.

For example, the following code snippet connects the `attributeChanged()`
function to fire whenever one of the part's attributes changes:

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "changed")
end

part.AttributeChanged:Connect(attributeChanged)
```

See also `Class.Instance:GetAttributeChangedSignal()` which returns an
event that fires when a specific given attribute changes.


Instance.AttributeChanged

attribute

The name of the attribute that has been changed.


Fires whenever an attribute is changed on the `Class.Instance`.


This snippet prints the names of objects as they are added to the Workspace:


Fires after an object is parented to this `Class.Instance`.

Note, when using this method on a client to detect objects created by the
server it is necessary to use `Class.Instance:WaitForChild()` when
indexing these object's descendants. This is because the object and its
descendants are not guaranteed to replicate from the server to the client
simultaneously. For example:

```
local Workspace = game:GetService("Workspace")

Workspace.ChildAdded:Connect(function(child)
	-- Use WaitForChild() since descendants may not have replicated yet
	local head = child:WaitForChild("Head")
end)
```

Note, this event only operates for immediate children of the
`Class.Instance`. For an event that captures all descendants, use
`Class.Instance.DescendantAdded`.

See also `Class.Instance.ChildRemoved`.


Instance.ChildAdded

The `Class.Instance` that has been added.


Fires after an object is parented to this `Class.Instance`.


Instance.childAdded

This snippet prints the names of objects as they are removed from the
Workspace:


Fires after a child is removed from this `Class.Instance`.

Removed refers to when an object's parent is changed from this
`Class.Instance` to something other than this `Class.Instance`. Note, this
event will also fire when a child is destroyed (using
`Class.Instance:Destroy()`) as the destroy function sets an object's
parent to `nil`.

This event only operates for immediate children of the `Class.Instance`.
For an event that captures all descendants, use
`Class.Instance.DescendantRemoving`.

See also `Class.Instance.ChildAdded`.


Instance.ChildRemoved

The `Class.Instance` that has been removed.


Fires after a child is removed from this `Class.Instance`.


This following example will print the name of any object that is added to the
Workspace:


This event fires after a descendant is added to the `Class.Instance`.

As it fires for every descendant, parenting an object to the
`Class.Instance` will fire the event for this object and all of its
descendants individually.

If you're only concerned with the **direct children** of the
`Class.Instance`, use `Class.Instance.ChildAdded` instead.

See also `Class.Instance.DescendantRemoving`.


Instance.DescendantAdded

descendant

Fires after a descendant is added to the `Class.Instance`.


The following example prints the name of any descendant as it is being removed
from the Workspace:


This event fires **immediately before** the parent `Class.Instance`
changes such that a **descendant** instance will no longer be a
descendant. `Class.Instance:Destroy()|Destroy()` changes an instance's
`Class.Instance.Parent|Parent` to `nil`, so calling that method on a
descendant of the parent will cause this event to fire.

Since this event fires **before** the descendant's removal, the parent of
the descendant will be unchanged at the time of this event firing. If the
descendant is also a **direct child** of the parent, this event will fire
before `Class.Instance.ChildRemoved`.

If a descendant has children, this event fires with the descendant first,
followed by its descendants.

#### Warning

This event fires with the descendant object that is being removed.
Attempting to set the `Class.Instance.Parent|Parent` of the descendant to
something else will fail. Below is an example that demonstrates this:

```
local Workspace = game:GetService("Workspace")

Workspace.DescendantRemoving:Connect(function(descendant)
	-- Do not manipulate the parent of the descendant in this function!
	-- This event fires BECAUSE the parent was manipulated, and the change hasn't happened yet
	-- Therefore, it is problematic to change the parent like this:
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil
```

See also `Class.Instance.DescendantAdded|DescendantAdded`.


Instance.DescendantRemoving

The `Class.Instance` that is being removed.


Fires immediately before a descendant of the `Class.Instance` is removed.


This sample demonstrates how, when using Immediate signal behavior, an
Instance being destroyed remains in place until the connected function yields.


This sample demonstrates how, when using Deferred signal behavior, an Instance
is destroyed before the signal fires.


The `Class.Instance` will never be deleted from memory while a connected
function is still using it. However, if the function yields at any point,
the `Class.Instance` and its descendants will be parented to `nil`.

If the `Class.Workspace.SignalBehavior` property is set to
`Enum.SignalBehavior.Immediate`, this event fires immediately before the
`Class.Instance` or one of its ancestors is destroyed with
`Class.Instance:Destroy()`.

If the `Class.Workspace.SignalBehavior` property is set to
`Enum.SignalBehavior.Deferred`, this event fires at the next resumption
point, which will be after the `Class.Instance` or one of its ancestors is
destroyed with `Class.Instance:Destroy()`.

With `Enum.SignalBehavior.Deferred|Deferred` behavior, connecting a script
to its own `Class.Instance.Destroying` event is problematic, as the script
will be destroyed before the callback can be called (meaning it will not
execute).

When deleting an `Class.Instance` in Studio, such as manually deleting
through the [Explorer](/studio/explorer) or through a plugin,
the `Class.Instance` isn't destroyed. Instead, the parent is set to `nil`
which you can track with `Class.Instance.AncestryChanged`.


Instance.Destroying

Fires immediately before (or is deferred until after) the instance is
destroyed via `Class.Instance:Destroy()`.


This event fires whenever any style property is changed on the instance,
including when a property is set to `nil`.

```lua
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local playerGui = player.PlayerGui
local HUDContainer = playerGui:WaitForChild("HUDContainer")
local meterBar = HUDContainer.MeterBar

local function stylePropertyChanged()
	print("Styled properties changed")
end

meterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)
```


Instance.StyledPropertiesChanged

Fires whenever any style property is changed on the instance, including
when a property is set to `nil`.


This method applies a tag to the instance, with no effect if the tag is
already applied. Successfully adding a tag will fire a signal created by
`Class.CollectionService:GetInstanceAddedSignal()` with the given tag.

#### Warnings

- An instance's tags that were added client-side will be dropped if the
  server later adds or removes a tag on that instance because the server
  replicates all tags together and overwrites previous tags.

- When tagging an instance, it is common that some resources are used to
  give the tag its functionality, for example event connections or tables.
  To prevent memory leaks, it's a good idea to clean these up (disconnect,
  set to `nil`, etc.) when no longer needed for a tag. Do this when
  calling `Class.Instance:RemoveTag()`, calling
  `Class.Instance:Destroy()`, or in a function connected to a signal
  returned by `Class.CollectionService:GetInstanceRemovedSignal()`.


Instance:AddTag

The children function returns an array of the object's children.


Instance:children

Returns an array of the object's children.


This method destroys all of an instance's children and descendants.

```
local part = Instance.new("Part")

-- Add some sparkles
for i = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part

  local sc = Instance.new("Sparkles")
  sc.Parent = sparkles
end

print("Children:", #part:GetChildren())  --> Children: 3

part:ClearAllChildren()

print("Children:", #part:GetChildren())  --> Children: 0
```

If you do not wish to destroy **all** children and descendants, use either
`Class.Instance:GetChildren()` or `Class.Instance:GetDescendants()` to
loop through those children/descendants and select what to destroy. For
example, the following code sample will destroy all
`Class.BasePart|BaseParts` descending from a `Class.Model`:

```
local Workspace = game:GetService("Workspace")

local model = Workspace:FindFirstChild("TestModel")

for _, descendant in model:GetDescendants() do
	if descendant:IsA("BasePart") then
		descendant:Destroy()
	end
end
```


Instance:ClearAllChildren

This method destroys all of an instance's children.


Demonstrates cloning a model using `Class.Instance:Clone()`.


`Clone()` creates a copy of an instance and all of its descendants,
ignoring all instances that are not
`Class.Instance.Archivable|Archivable`. The copy of the root instance is
returned by this method and its `Class.Instance.Parent|Parent` is set to
`nil`. Note that if the instance itself has
`Class.Instance.Archivable|Archivable` set to `false`, this method will
return `nil`.

If a reference property such as `Class.ObjectValue.Value` is set in a
cloned instance, the value of the copy's property depends on the
original's value:

- If a reference property refers to an instance that was **also** cloned,
  the copy will refer to the copy.
- If a reference property refers to an instance that was **not** cloned,
  the same value is maintained in the copy.


Instance:Clone

Create a copy of an instance and all its descendants, ignoring instances
that are not `Class.Instance.Archivable|Archivable`.


Instance:clone

Demonstrates destroying a Part using the `Class.Instance:Destroy()` function.

This function is the correct way to dispose of objects that are no longer
required.


Sets the `Class.Instance.Parent` property to `nil`, locks the
`Class.Instance.Parent` property, disconnects all connections, and calls
`Destroy()` on all children. This method is the correct way to dispose of
objects that are no longer required.

Disposing of unneeded objects is important, since unnecessary objects and
connections in a place use up memory which can lead to serious performance
issues over time.

As a best practice after calling `Destroy()` on an object, set any
variables referencing the object (or its descendants) to `nil`. This
prevents your code from accessing anything to do with the object.

```lua
local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- Don't do this:
print(part.Name)  --> "Hello, world"
-- Do this to prevent the above line from working:
part = nil
```

Once an `Class.Instance` has been destroyed by this method, it cannot be
reused because the `Class.Instance.Parent` property is locked. To
**temporarily** remove an object instead of destroying it, set
`Class.Instance.Parent|Parent` to `nil`. For example:

```
local Workspace = game:GetService("Workspace")

object.Parent = nil
task.wait(2)
object.Parent = Workspace
```

To destroy an object after a set amount of time, use
`Class.Debris:AddItem()`.


Instance:Destroy

Sets the `Class.Instance.Parent` property to `nil`, locks the
`Class.Instance.Parent` property, disconnects all connections, and calls
`Destroy()` on all children.


Instance:destroy

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

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

The following code snippet would find the first ancestor of the object
named `Car`.

```
local car = object:FindFirstAncestor("Car")
```

For variants of this method that find ancestors of a specific class,
please see `Class.Instance:FindFirstAncestorOfClass()` and
`Class.Instance:FindFirstAncestorWhichIsA()`.


Instance:FindFirstAncestor

name

The `Class.Instance.Name` to be looked for.


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


Returns the first ancestor of the `Class.Instance` whose
`Class.Object.ClassName` is equal to the given className.

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

A common use of this method is finding the `Class.Model` a
`Class.BasePart` belongs to. For example:

```
local model = part:FindFirstAncestorOfClass("Model")
```

This method is a variant of `Class.Instance:FindFirstAncestor()` which
checks the `Class.Object.ClassName` property rather than
`Class.Instance.Name`. `Class.Instance:FindFirstAncestorWhichIsA()` also
exists, using the `Class.Object:IsA()` method instead to respect class
inheritance.


Instance:FindFirstAncestorOfClass

className

The `Class.Object.ClassName` to be looked for.


Returns the first ancestor of the `Class.Instance` whose
`Class.Object.ClassName` is equal to the given className.


Returns the first ancestor of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

Unlike `Class.Instance:FindFirstAncestorOfClass()`, this method uses
`Class.Object:IsA()` which respects class inheritance. For example:

```
print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true
```

Therefore, the following code sample will return the first
`Class.BasePart` ancestor, regardless of if it is a `Class.WedgePart`,
`Class.MeshPart` or `Class.Part`.

```
local part = object:FindFirstAncestorWhichIsA("BasePart")
```

See also `Class.Instance:FindFirstAncestor()`.


Instance:FindFirstAncestorWhichIsA

Returns the first ancestor of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.


The below would look in Workspace for an object name "Brick". If found, it
will change the name of the object to "Foo".


Returns the first child of the `Class.Instance` with the given name, or
`nil` if no such child exists. If the optional `recursive` argument is
`true`, this method searches all descendants rather than only the
immediate children of the `Class.Instance`.

#### Checking the Existence of an Object

`FindFirstChild()` is necessary if you need to verify an object exists
before continuing. Attempting to index a child by name using the dot
operator throws an error if the child doesn't exist.

```lua
local Workspace = game:GetService("Workspace")

-- The following line errors if the part doesn't exist in the workspace
Workspace.Part.Transparency = 0.5
```

A better approach is to use `FindFirstChild()` to first check for `Part`,
then use an `if` statement to run code that needs it.

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace:FindFirstChild("Part")
if part then
	part.Transparency = 0.5
end
```

#### Finding a Child Whose Name Matches a Property

Sometimes the `Class.Instance.Name|Name` of an object is the same as that
of a property of its `Class.Instance.Parent|Parent`. When using the dot
operator, properties take precedence over children if they share a name.

In the following example, a `Class.Folder` called `Color` is added to a
`Class.Part`, which also has the `Class.Part.Color` property. Notice that
`part.Color` refers to the `Datatype.Color3` property value, not the child
`Class.Folder` instance. A benefit of using
`Class.Instance:FindFirstChild()|FindFirstChild()` is that the
introduction of new properties does not impose a risk on your code.

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- The property
local c2 = part:FindFirstChild("Color")  -- The child folder
```

#### Performance Notes

`Class.Instance:FindFirstChild()|FindFirstChild()` takes about 20% longer
than using the dot operator and almost 8 times longer than simply storing
a reference to an object. Therefore, you should avoid calling it in
performance-dependent code such as in tight loops or functions connected
to `Class.RunService.Heartbeat` and `Class.RunService.PreRender`. Instead,
store the result in a variable, or consider using
`Class.Instance.ChildAdded|ChildAdded` or
`Class.Instance:WaitForChild()|WaitForChild()` to detect when a child of a
given name becomes available.


Instance:FindFirstChild

The `Class.Instance.Name` to be searched for.


recursive

Whether or not the search should be conducted recursively.


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


Instance:findFirstChild

Returns the first child of the `Class.Instance` whose
`Class.Object.ClassName|ClassName` is equal to the given `className`.
Unlike `Class.Instance:FindFirstChildWhichIsA()`, this method only returns
objects whose class matches `className`, ignoring class inheritance. If no
matching child is found, this method returns `nil`.


Instance:FindFirstChildOfClass

Returns the first child of the `Class.Instance` whose
`Class.Object.ClassName|ClassName` is equal to the given class name.


Returns the first child of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.

If no matching child is found, this method returns `nil`. If the optional
recursive argument is true, this method searches all descendants rather
than only the immediate children of the `Class.Instance`.

Unlike `Class.Instance:FindFirstChildOfClass()`, this method uses
`Class.Object:IsA()` which respects class inheritance. For example:

```lua
print(part:IsA("Part")) --> true
print(part:IsA("BasePart")) --> true
print(part:IsA("Instance")) --> true
```

Therefore, the following code sample will return the first
`Class.BasePart` child, regardless of if it is a `Class.WedgePart`,
`Class.MeshPart` or `Class.Part`.

```
local part = object:FindFirstChildWhichIsA("BasePart")
```

Developers looking for a child by name, should use
`Class.Instance:FindFirstChild()` instead.


Instance:FindFirstChildWhichIsA

The `Class.Object.ClassName` to be searched for.


Returns the first child of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.


Returns the first descendant found with the given `Class.Instance.Name`.

This method is disabled and cannot be used. To find the first descendant
of an instance, consider using the `recursive` parameter on
`Class.Instance:FindFirstChild()` instead.


Instance:FindFirstDescendant

Returns the first descendant found with the given `Class.Instance.Name`.


Instance

`Instance` is the base class for all classes in the Roblox class hierarchy
which can be part of the `Class.DataModel` tree.


/reference/engine/classes/BillboardGui.yaml