The code in this sample demonstrates how a sound parented to a Part or
Attachment will play locally and experience volume drop off the further the
player's camera is away from the part.

A part is instanced, and a sound is instanced and parented to the part. A
click detector is set up on the part that will check if the sound is playing,
using `Class.Sound.IsPlaying` and play or stop the sound depending.

`Class.Sound` is an object that emits sound. When placed in a `Class.BasePart`
or an `Class.Attachment`, this object will emit its sound from that part's
`Class.BasePart.Position` or the attachment's
`Class.Attachment.WorldPosition`. In this placement, a `Class.Sound` exhibits
the Doppler effect, meaning its frequency and pitch varies with the relative
motion of whatever attachment or part it is attached to. Additionally, its
volume will be determined by the distance between the client's sound listener
(by default the `Class.Camera` position) and the position of the sound's
parent. For more information, see `Class.Sound.RollOffMode|RollOffMode`.

A sound is considered "global" if it is **not** parented to a `Class.BasePart`
or an `Class.Attachment`. In this case, the sound will play at the same volume
throughout the entire place.


This code sample includes a function that will play a sound and allow it to
loop for a given number of times before stopping it.

Fires whenever the `Class.Sound` loops. Returns `soundId` and
`numOfTimesLooped`, giving the content ID of the sound and the number of
times looped respectively.

When the `Class.Sound` is stopped through `Class.Sound:Stop()|Stop()`, the
looped counter resets meaning the next `Class.Sound.DidLoop|DidLoop` event
will return `1` for `numOfTimesLooped`.


Sound.DidLoop

soundId

The `Class.Sound.SoundId|SoundId` of the `Class.Sound` that looped.


numOfTimesLooped

The number of times the `Class.Sound` has looped.


Fires when the `Class.Sound` has completed playback and stopped. This
event is often used to destroy a sound when it has completed playback:

```
sound:Play()
sound.Ended:Wait()
sound:Destroy()
```

Note that this event will **not** fire for sounds with
`Class.Sound.Looped|Looped` set to `true`, as they continue playing upon
reaching their end. This event will also **not** fire when the sound is
stopped before playback has completed; for this use the
`Class.Sound.Stopped|Stopped` event.


Sound.Ended

The `Class.Sound.SoundId|SoundId` of the `Class.Sound` that has ended.


Fires when the `Class.Sound` has completed playback and stopped.


This simple function will verify a Sound has loaded by checking the
Sound.IsLoaded property. If Sound.IsLoaded is false it will wait for the
Loaded event before resuming.

It is important to check Sound.IsLoaded before connecting to the Sound.Loaded
event, as if the sound has already loaded the Sound.Loaded event will not fire
and the function will yield indefinitely.

Fires when the `Class.Sound` is loaded.

As this event only fires at the time the sound is loaded, it's recommended
to check the sound's `Class.Sound.IsLoaded|IsLoaded` property prior to
connecting to this event.


Sound.Loaded

The `Class.Sound.SoundId|SoundId` of the `Class.Sound` that loaded.


This sample gives a simple demonstration of what each of the Sound functions
(Sound.Play, Sound.Stop, Sound.Pause and Sound.Resume) do to Sound.Playing and
Sound.TimePosition.

Fires whenever the `Class.Sound` is paused using
`Class.Sound:Pause()|Pause()`.


Sound.Paused

The `Class.Sound.SoundId|SoundId` of the `Class.Sound` that was
paused.


Fires whenever the `Class.Sound` is played using
`Class.Sound:Play()|Play()`. This event will **not** fire if the
`Class.Sound` is played due to `Class.Sound.PlayOnRemove|PlayOnRemove`
being set to `true` and the sound being destroyed.


Sound.Played

The `Class.Sound.SoundId|SoundId` of the `Class.Sound` that was
played.


Fires whenever the `Class.Sound` is played using
`Class.Sound:Play()|Play()`.


Fires when the `Class.Sound` is resumed using
`Class.Sound:Resume()|Resume()`.


Sound.Resumed

The `Class.Sound.SoundId|SoundId` of the `Class.Sound` being resumed.


Fires when the `Class.Sound` is stopped through using
`Class.Sound:Stop()|Stop()`. Destroying a sound while it is playing will
not cause this event to fire.


Sound.Stopped

The `Class.Sound.SoundId|SoundId` of the `Class.Sound` that stopped.


Fires when the `Class.Sound` is stopped through using
`Class.Sound:Stop()|Stop()`.


This method pauses playback of the `Class.Sound` if it is playing, setting
`Class.Sound.Playing|Playing` to `false`. Unlike
`Class.Sound:Stop()|Stop()`, it does not reset
`Class.Sound.TimePosition|TimePosition`, meaning the sound can be resumed
using `Class.Sound:Resume()|Resume()`.


Sound:Pause

Pauses playback of the `Class.Sound` if it is playing.


This method plays the `Class.Sound` and sets
`Class.Sound.TimePosition|TimePosition` to the last value set by a script
(or `0` if it has not been set), then sets `Class.Sound.Playing|Playing`
to `true`.


Sound:Play

This method resumes the `Class.Sound` and sets
`Class.Sound.Playing|Playing` to `true`. Does not alter
`Class.Sound.TimePosition|TimePosition` and thus can be used to resume
playback of a sound paused through `Class.Sound:Pause()|Pause()`.


Sound:Resume

This method stops the `Class.Sound` and sets `Class.Sound.Playing|Playing`
to `false`, then sets `Class.Sound.TimePosition|TimePosition` to `0`.


Sound:Stop

Sound:pause

Sound:play

Sound:stop

Sound

Sound.ChannelCount

The minimum distance, in studs, at which a 3D `Class.Sound` (direct child
of a `Class.BasePart` or `Class.Attachment`) will begin to attenuate
(decrease in volume).

Sounds parented to a `Class.BasePart` or `Class.Attachment` that are
descendants of the `Class.Workspace` are considered 3D sounds and their
volume while playing is dependent on the distance between the client's
sound listener (`Class.Camera` position by default) and the Sound's
parent. Two properties influence this behavior EmitterSize and
`Class.Sound.RollOffMode`.

The way the `Class.Sound` attenuates (fades out) after the distance
between the listener and the sound exceeds the EmitterSize is determined
by RollOffMode.


Sound.EmitterSize

The minimum distance, in studs, at which a 3D `Class.Sound` (direct child
of a `Class.BasePart` or `Class.Attachment`) will begin to attenuate
(decrease in volume).


This property is `true` when the `Class.Sound` has loaded from Roblox
servers and is ready to play. You can use this property and the
`Class.Sound.Loaded|Loaded` event to verify a sound has loaded before
playing it.


Sound.IsLoaded

This property is `true` when the `Class.Sound` has loaded from Roblox
servers and is ready to play.


Sound.IsMutedForCapture

This code sample contains demonstrates when the Sound.IsPlaying and
Sound.IsPaused properties will be true or false.

A sound is instanced in the Workspace and the Sound.IsLoaded property is
checked to ensure it has loaded, if it has not the Sound.Loaded event is used
to yield the script until the sound has.

As the sound is played, paused and stopped the Sound.IsPlaying and
Sound.IsPaused properties are printed to demonstrate how they respond to each
of these functions. Note Sound.IsPaused will always be true if even if the
sound has been stopped rather than paused.

This read-only property returns `true` when the `Class.Sound` is not
playing. Note that it can return `true` if a sound has been paused using
`Class.Sound:Pause()|Pause()`, if it has been stopped using
`Class.Sound:Stop()|Stop()`, or the sound has never been played.

As `Class.Sound.IsPaused|IsPaused` is read-only, it cannot be used to stop
the sound; `Class.Sound:Stop()|Stop()` or `Class.Sound:Pause()|Pause()`
should be used instead.


Sound.IsPaused

Read-only property which returns `true` when the `Class.Sound` is not
playing.


This read-only property returns true when the `Class.Sound` is playing.

As `Class.Sound.IsPlaying|IsPlaying` is read-only, it cannot be used to
play the sound; `Class.Sound:Play()|Play()` should be used instead.


Sound.IsPlaying

Read-only property which returns `true` when the `Class.Sound` is playing.


A range denoting a desired loop start and loop end within the
`Class.Sound.PlaybackRegion|PlaybackRegion`, in seconds.

- If `Class.Sound.LoopRegion|LoopRegion.Min` `>`
  `Class.Sound.PlaybackRegion|PlaybackRegion.Min`, the loop starts from
  `Class.Sound.LoopRegion|LoopRegion.Min`.

- If `Class.Sound.LoopRegion|LoopRegion.Min` `<`
  `Class.Sound.PlaybackRegion|PlaybackRegion.Min`, the loop starts from
  `Class.Sound.PlaybackRegion|PlaybackRegion.Min`.

- If `Class.Sound.LoopRegion|LoopRegion.Max` `>`
  `Class.Sound.PlaybackRegion|PlaybackRegion.Max`, the loop starts at
  `Class.Sound.PlaybackRegion|PlaybackRegion.Max`.

- If `Class.Sound.LoopRegion|LoopRegion.Max` `<`
  `Class.Sound.PlaybackRegion|PlaybackRegion.Max`, the loop starts at
  **exactly** that time.

- If `Class.Sound.LoopRegion|LoopRegion.Min` `==`
  `Class.Sound.LoopRegion|LoopRegion.Max`, the `Class.Sound` uses the
  `Class.Sound.PlaybackRegion|PlaybackRegion` property instead.


Sound.LoopRegion

A range denoting a desired loop start and loop end within the
`Class.Sound.PlaybackRegion|PlaybackRegion`, in seconds.


This sets whether or not the `Class.Sound` repeats once it has finished
playing. Looped sounds are suitable for a range of applications including
music and background ambient sounds.

The `Class.Sound.DidLoop|DidLoop` event can be used to track the number of
times as sound has looped.


Sound.Looped

Sets whether or not the `Class.Sound` repeats once it has finished
playing.


This sample includes a brief demonstration of how Sound.MaxDistance works.

A Part is instanced in the Workspace with a looped Sound playing within it. A
function is made to listen to the Sound's MaxDistance and change the size of a
sphere whenever it changes. The sphere's radius will always be equal to the
Sound's MaxDistance.

This example helps demonstrate how the sound is only audible when the client's
listener (by default the Camera's position) is within the sphere.

The maximum distance, in studs, a client's listener can be from the
`Class.Sound` origin and still hear it. Only applies to Sounds parented to
a `Class.Part` or `Class.Attachment` (3D sounds).

How MaxDistance impacts the attenuation of a sound (manner in which it
fades out) is dependent on the `Class.Sound.RollOffMode` property. When
RollOffMode is set to use an inverse type distance model (Inverse or
InverseTapered) the MaxDistance will not effect the attenuation of the
sound. This means that low values for MaxDistance will cause the sound to
abruptly cut off when the listener reaches the MaxDistance. In most cases
this is not desirable and developers are advised not to use low
MaxDistance values.

When RollOffMode is set to a linear type distance model (Linear or
LinearSquared) the sound will attenuate between `Class.Sound.EmitterSize`
and MaxDistance (with playback volume reaching zero at MaxDistance). This
is less realistic, but in some cases allows attenuation to be handled in a
more intuitive way.


Sound.MaxDistance

The maximum distance, in studs, a client's listener can be from the
`Class.Sound|Sound\s` origin and still hear it. Only applies to Sounds
parented to a `Class.Part` or `Class.Attachment` (3D sounds).


The minimum distance at which a 3D `Class.Sound` (direct child of a
`Class.BasePart` or `Class.Attachment`) will begin to attenuate.
Effectively, the emitter size.


Sound.MinDistance

Sets how high pitched and fast a `Class.Sound` is when it is played. The
greater the integer, the higher and faster the sound is.


Sound.Pitch

Sets how high pitched and fast a `Class.Sound` is when it is played. The
greater the integer, the higher and faster the `Class.Sound` is.


When `true`, the `Class.Sound` will play when it is removed from the
experience by parenting the `Class.Sound` or one if its ancestors to
`nil`. This means all of the following will cause the sound to play when
`Class.Sound.PlayOnRemove|PlayOnRemove` is `true`:

- `sound:Destroy()`
- `sound.Parent = nil`
- `sound.Parent.Parent = nil`


Sound.PlayOnRemove

When `true`, the `Class.Sound` will play when it is removed from the
experience.


In this sample Sound.PlaybackLoudness is used to create an amplitude bar that
shows the amplitude of a sound playing.

This code sample should be placed in StarterPlayerScripts.

A simple GUI is created, a frame holding that bar and a frame containing the
bar. A Sound is then played and the size of the bar is set to reflect the
Sound.PlaybackLoudness on a loop.

A number between `0` and `1000` indicating how loud the `Class.Sound` is
currently playing back. This property reflects the amplitude of the
sound's playback in the instance of time it is read.


Sound.PlaybackLoudness

A number between `0` and `1000` indicating how loud the `Class.Sound` is
currently playing back.


A range denoting a desired start and stop time within the
`Class.Sound.TimeLength|TimeLength`, in seconds.

- If `Class.Sound.PlaybackRegion|PlaybackRegion.Min` `>` `0`, the sound
  begins to play from the `Class.Sound.PlaybackRegion|PlaybackRegion.Min`
  time.

- If `Class.Sound.PlaybackRegion|PlaybackRegion.Min` `<` `0`, the sound
  begins to play from `0`.

- If `Class.Sound.PlaybackRegion|PlaybackRegion.Max` `>`
  `Class.Sound.TimeLength`, the sound stops at `Class.Sound.TimeLength`.

- If `Class.Sound.PlaybackRegion|PlaybackRegion.Max` `<`
  `Class.Sound.TimeLength`, the sound stops at **exactly** that time.

- If `Class.Sound.PlaybackRegion|PlaybackRegion.Min` `==`
  `Class.Sound.PlaybackRegion|PlaybackRegion.Max`, this property is
  inactive.


Sound.PlaybackRegion

A range denoting a desired start and stop time within the
`Class.Sound.TimeLength|TimeLength`, in seconds.


If `true`, this property gives your `Class.Sound` access to the
`Class.Sound.PlaybackRegion|PlaybackRegion` and
`Class.Sound.LoopRegion|LoopRegion` properties which can more-accurately
control its playback.


Sound.PlaybackRegionsEnabled

In this example a Sound is played in the Workspace. The PlaybackSpeed property
is increased and decreased at intervals to demonstrate its impact on the
playback of the Sound.

Determines the speed at which a `Class.Sound` will play, with higher
values causing the sound to play faster and at a higher pitch.


Sound.PlaybackSpeed

This sample demonstrates how the Sound.Playing property can be used to start
and stop playback of a sound.

A sound is instanced in the Workspace and playback is started by setting
Sound.Playing to true. After ten seconds the playback is stopped by setting
Sound.Playing to false. When the playback is again resumed using Sound.Playing
it resumes at the previous Sound.TimePosition it was stopped at. This is
demonstrated by printing the TimePosition property immediately after resuming
the sound.

Indicates whether the `Class.Sound` is currently playing. This can be
toggled, and this property will always replicate.

In Studio's [Properties](/studio/properties) window, while in
**Edit** mode, toggling `Class.Sound.Playing|Playing` to `true` does not
begin playing the sound, but the sound will begin playing during runtime.

This property should not be confused with
`Class.Sound.IsPlaying|IsPlaying` which is a read-only property.

Note that when `Class.Sound.Playing|Playing` is set to `false`, the
`Class.Sound.TimePosition|TimePosition` property of the sound will not
reset, meaning that when `Class.Sound.Playing|Playing` is set to `true`
again, the audio will continue from the time position it was at when it
was stopped. However, if the `Class.Sound:Play()|Play()` function is used
to resume the sound, the time position will reset to `0`.


Sound.Playing

Indicates whether the `Class.Sound` is currently playing.


The maximum distance, in studs, a client's listener can be from the
sound's origin and still hear it. Only applies to `Class.Sound|Sounds`
parented to a `Class.BasePart` or `Class.Attachment`.

How `Class.Sound.RollOffMaxDistance|RollOffMaxDistance` impacts the
attenuation of a sound (manner in which it fades out) is dependent on the
`Class.Sound.RollOffMode|RollOffMode` property.


Sound.RollOffMaxDistance

The maximum distance, in studs, a client's listener can be from the
sound's origin and still hear it. Only applies to `Class.Sound|Sounds`
parented to a `Class.BasePart` or `Class.Attachment`.


The minimum distance, in studs, at which a `Class.Sound` which is parented
to a `Class.BasePart` or `Class.Attachment` will begin to attenuate
(decrease in volume).

How `Class.Sound.RollOffMinDistance|RollOffMinDistance` impacts the
attenuation of a sound (manner in which it fades out) is dependent on the
`Class.Sound.RollOffMode|RollOffMode` property.


Sound.RollOffMinDistance

The minimum distance, in studs, at which a `Class.Sound` which is parented
to a `Class.BasePart` or `Class.Attachment` will begin to attenuate
(decrease in volume).


This property controls how the volume of a `Class.Sound` which is parented
to a `Class.BasePart` or `Class.Attachment` attenuates (fades out) as the
distance between the listener and parent changes.

For details on the different modes, see `Enum.RollOffMode`.


Sound.RollOffMode

Controls how the volume of a `Class.Sound` which is parented to a
`Class.BasePart` or `Class.Attachment` attenuates (fades out) as the
distance between the listener and parent changes.


The `Class.SoundGroup` that is linked to this `Class.Sound`.


Sound.SoundGroup

This property is the content ID of the sound file to associate with the
`Class.Sound`. See [Audio Assets](/audio/assets) for more
information.


Sound.SoundId

Content ID of the sound file to associate with the `Class.Sound`.


This code sample includes a simple function that uses Sound.TimeLength and
Sound.PlaybackSpeed to play a sound that'll take the given duration to
complete. It achieves this by setting the PlaybackSpeed of the sound to be
equal to the TimeLength of the sound divided by the desired duration.

Note that as TimeLength is equal to 0 when the sound has not loaded, the
function will yield while it loads the sound.

The length of the `Class.Sound` in seconds. If the `Class.Sound` is not
loaded, this value will be `0`.

This property is often used in conjunction with
`Class.Sound.PlaybackSpeed|PlaybackSpeed` to adjust the speed of a sound
so that it lasts for a specific duration.


Sound.TimeLength

The length of the `Class.Sound` in seconds.


This sample demonstrates how Sound.TimePosition can be used to jump to
particular points in an audio file both before and during Sound playback.

A Sound is created in the Workspace and set to start at 30 seconds in. During
playback, it jumps forwards to 100 seconds and then back to the start (0
seconds).

This property reflects the progress of the `Class.Sound` in seconds. It
can be changed to move the playback position of the sound both before and
during playback.

As a `Class.Sound` is played, `Class.Sound.TimePosition|TimePosition`
increases at a rate of `Class.Sound.PlaybackSpeed|PlaybackSpeed` per
second. Once `Class.Sound.TimePosition|TimePosition` reaches
`Class.Sound.TimeLength|TimeLength`, the sound will stop unless it is
`Class.Sound.Looped|Looped`.

Note that setting `Class.Sound.TimePosition|TimePosition` to a value
greater than the length in a looped track will not cause it to wrap
around. If that behavior is desired, consider the following code snippet:

```
local newPosition = 1.5

if newPosition >= sound.TimeLength then
	newPosition = newPosition - sound.TimeLength
end
sound.TimePosition = newPosition
```


Sound.TimePosition

Progress of the `Class.Sound` in seconds. Can be changed to move the
playback position of the `Class.Sound` both before and during playback.


The volume of the `Class.Sound`. Can be set between `0` and `10` and
defaults to `0.5`.

Note that if the `Class.Sound` is a member of a `Class.SoundGroup`, its
playback volume (but not its `Class.Sound.Volume|Volume` property) will be
influenced by the group's `Class.SoundGroup.Volume` property.


Sound.Volume

Sound.isPlaying

An object that emits sound. This object can be placed within a
`Class.BasePart` or `Class.Attachment` to emit a sound from a particular
position within a place or world, or it can be attached elsewhere to play the
sound at a constant volume throughout the entire place.


`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 the `Class.Instance.Parent` property of the object or one of
its ancestors is changed.

This event includes two parameters: `child` refers to the `Class.Instance`
whose `Class.Instance.Parent` was actually changed, while `parent` refers
to this instance's new `Class.Instance.Parent`.

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 `Class.Instance` whose `Class.Instance.Parent` has been changed.


parent

The new `Class.Instance.Parent` of the `Class.Instance` whose
`Class.Instance.Parent` was changed.


Fires when the `Class.Instance.Parent` property of the 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 function 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 function only works for immediate children of the
`Class.Instance`. For a function 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`.


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 function only works for immediate children of the `Class.Instance`.
For a function 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`.


Instance.childAdded

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

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


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


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

This function 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 function 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 function 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 function is finding the `Class.Model` a
`Class.BasePart` belongs to. For example:

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

This function 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 function 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 function 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 function 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.


Returns the first child of the `Class.Instance` whose
`Class.Object.ClassName|ClassName` is equal to the given `className`.
Unlike `Class.Instance:FindFirstChildWhichIsA()`, this function only
returns objects whose class matches `className`, ignoring class
inheritance. If no matching child is found, this function 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 function returns `nil`. If the
optional recursive argument is true, this function searches all
descendants rather than only the immediate children of the
`Class.Instance`.

Unlike `Class.Instance:FindFirstChildOfClass()`, this function 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

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


Instance

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


Sound

Code Samples

Summary

Properties

Methods

Events

Properties

Methods

Events

On this page