**TeleportService** is responsible for transporting `Class.Player|Players`
between different places and servers.

For more information on how to teleport players between servers, see
[Teleporting Between Places](/projects/teleport).


This function fires when the `Class.Players.LocalPlayer` enters the place
following a teleport. The `teleportData` and `customLoadingScreen` are
provided as arguments.

When fetching _teleportData_ and the _customLoadingScreen_ you are advised
to use `Class.TeleportService:GetLocalPlayerTeleportData()` and
`Class.TeleportService:GetArrivingTeleportGui()` instead. This is because
these functions can be called immediately without having to wait for this
event to fire.

This event should be connected immediately in a `Class.LocalScript`
parented to `Class.ReplicatedFirst`. Otherwise, when the connection is
made the event may have already fired.

#### Loading Screen

During a teleport, while the destination place is loading, the
_customLoadingScreen_ is parented to the `Class.CoreGui`. Once the place
has loaded the `Class.ScreenGui|loading screen` is
`Class.Instance.Parent|parented` to _nil_.

If you wish to preserve the _customLoadingScreen_ and perform your own
transitions, you will need to parent it to the local player's
`Class.PlayerGui`. For example, using the following code inside a
`Class.LocalScript` in `Class.ReplicatedFirst`:

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

TeleportService.LocalPlayerArrivedFromTeleport:Connect(function(customLoadingScreen, teleportData)
	local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
	ReplicatedFirst:RemoveDefaultLoadingScreen()

	customLoadingScreen.Parent = playerGui
	-- animate screen here
	wait(5)
	-- destroy screen
	customLoadingScreen:Destroy()
end)
```

The _customLoadingScreen_ will not be used if the destination place is in
a different game.

#### Studio Limitation

Note that this service does not work during playtesting in Roblox Studio;
to test aspects of your experience using it, you must publish the
experience and play it in the Roblox application.


TeleportService.LocalPlayerArrivedFromTeleport

loadingGui

The _customLoadingScreen_ the `Class.Players.LocalPlayer|LocalPlayer`
arrived into the place with.


dataTable

The _teleportData_ the `Class.Players.LocalPlayer|LocalPlayer` arrived
into the place with.


Fires when the `Class.Players.LocalPlayer|LocalPlayer` enters the place
following a teleport.


This event fires on both the client and the server when a request to
teleport from a function such as `Class.TeleportService:TeleportAsync()`
fails and the player does not leave the current server. It provides a
reason for the failure, as well as all of the information necessary to
retry the teleport. If a group teleport fails, the event will fire once
per player.

#### TeleportOptions

The `Class.TeleportOptions` object provided by this event is not identical
to the one passed to the original `Class.TeleportService:TeleportAsync()`
call. It is a new object populated with the necessary parameters to retry
the teleport and send the player to the exact same destination. This is
especially important for facilitating group teleports when they fail.

<table>
    <thead>
        <tr>
            <th>Original Teleport Type</th>
	          <th>Teleport Data</th>
	          <th>ReservedServerAccessCode</th>
	          <th>ServerInstanceId</th>
	          <th>ShouldReserveServer</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Individual player to place</td>
            <td>Original value</td>
            <td>None</td>
            <td>None</td>
            <td>false</td>
        </tr>
        <tr>
            <td>Player(s) to reserved server</td>
            <td>Original value</td>
            <td>Original value, or the code generated if ShouldReserveServer was originally true</td>
            <td>None</td>
            <td>false</td>
        </tr>
        <tr>
            <td>Player(s) to specific server</td>
            <td>Original value</td>
            <td>None</td>
            <td>Original value</td>
            <td>false</td>
        </tr>
        <tr>
            <td>Players to place</td>
            <td>Original value</td>
            <td>None</td>
            <td>Same destination ID as the other players in the original teleport</td>
            <td>false</td>
        </tr>
    </tbody>
</table>

For more information on how to teleport players between servers, see
[Teleporting Between Places](/projects/teleport).


TeleportService.TeleportInitFailed

player

The `Class.Player` instance that failed to teleport.


teleportResult

errorMessage

The message provided to the player explaining the teleport failure.


placeId

The original target place ID of the teleport.


teleportOptions

A `Class.TeleportOptions` object that can be passed back to
`Class.TeleportService:TeleportAsync()` to retry the failed teleport.


Fires when a teleport fails to start, leaving the player in their current
server.


The following code, when placed inside a `LocalScript` in `ReplicatedFirst`
will preserve a custom teleport loading screen for five seconds before
destroying it.

This function returns the _customLoadingScreen_ the
`Class.Players.LocalPlayer|LocalPlayer` arrived into the place with.

Note, the _customLoadingScreen_ will not be used if the destination place
is in a different game.

#### Loading Screen

During a teleport, while the destination place is loading, the
_customLoadingScreen_ is parented to the `Class.CoreGui`. Once the place
has loaded the `Class.ScreenGui|loading screen` is
`Class.Instance.Parent|parented` to _nil_.

If you wish to preserve the _customLoadingScreen_ and perform your own
transitions, you will need to parent it to the local player's
`Class.PlayerGui`. For an example of this, see the code sample below.

#### Studio Limitation

Note that this service does not work during playtesting in Roblox Studio;
to test aspects of your experience using it, you must publish the
experience and play it in the Roblox application.


TeleportService:GetArrivingTeleportGui

Returns the _customLoadingScreen_ the
`Class.Players.LocalPlayer|LocalPlayer` arrived into the place with.


When put into StarterPlayerScripts, this example runs when the player joins
the game, and prints any teleport data provided by the player's previous
server.

This function returns the teleport data the `Class.Players.LocalPlayer`
arrived with. It can only be called from the client.

Exploiters can spoof teleport data. Send secure data such as player
currency through a server-side service such as `Class.DataStoreService` to
prevent tampering.


TeleportService:GetLocalPlayerTeleportData

The teleport data the `Class.Players.LocalPlayer` arrived into the
place with.


Returns the _teleportData_ the `Class.Players.LocalPlayer` arrived into
the place with.


The code sample below, when placed inside a `Script` within
`ServerScriptService`, will teleport a player who's following another player
to the associated place/server. Note that this will not work if the player
being followed is in a reserved server.

This function returns the `Class.DataModel.PlaceId|PlaceId` and
`Class.DataModel.JobId|JobId` of the server the user with the given
`Class.Player.UserId|UserId` is in, provided it is in the same game as the
current place.

Then, `Class.TeleportService:TeleportToPlaceInstance()` can be called with
this information to allow a user to join the target user's server.

Upon a successful lookup, the function returns the following values:

<table>
	<thead>
		<tr>
			<th>#</th>
			<th>Name</th>
			<th>Type</th>
			<th>Description</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td><b>1</b></td>
   			<td> currentInstance</td>
			<td>bool</td>
			<td>A bool indicating if the user was found in the current instance</td>
		</tr>
		<tr>
			<td><b>2</b></td>
   			<td>error</td>
			<td>string</td>
			<td>An error message in the event of the lookup failing</td>
		</tr>
		<tr>
			<td><b>3</b></td>
   			<td>placeId</td>
			<td>int64</td>
			<td>The PlaceId of the server the user is in</td>
		</tr>
		<tr>
			<td><b>4</b></td>
   			<td>instanceId</td>
			<td>string</td>
			<td>The JobId of the server the user is in</td>
		</tr>
	</tbody>
</table>

If there is a problem during lookup, such as the user being offline, an
error is thrown. It is recommended that you wrap calls to this function in
`pcall`.

#### Limitations

You should be aware of the following limitations when using this function:

- This function can only be called by the server.
- This function may fail to return the correct information if the user is
  teleporting.
- It is possible for this function to throw an error, hence developers
  should wrap it in a `Global.LuaGlobals.pcall()` (see example below)
- As this function returns the JobId of the server and not the access code
  returned by `Class.TeleportService:ReserveServer()`, the ID returned is
  not appropriate for use with reserved servers.

#### Studio Limitation

Note that this service does not work during playtesting in Roblox Studio;
to test aspects of your experience using it, you must publish the
experience and play it in the Roblox application.


TeleportService:GetPlayerPlaceInstanceAsync

userId

The `Class.Player.UserId` of the `Class.Player`.


Returns the `Class.DataModel.PlaceId|PlaceId` and
`Class.DataModel.JobId|JobId` of the server the user with the given
`Class.Player.UserId|UserId` is in provided it is in the same game as the
current place.


This function retrieves a teleport setting saved using
`Class.TeleportService:SetTeleportSetting()` using the given key.

This method is intended for use on the client only and should not be used
on the server.

Teleport settings are preserved across teleportations within the same
game. This means data can be saved using
`Class.TeleportService:SetTeleportSetting()` in one place and retrieved
using GetTeleportSetting in another place the user has been teleported to.

For example, in a game that allowed crouching you could save whether the
user is currently crouching prior to teleporting as a teleport setting.
This could then be retrieved in the destination place after the
teleportation:

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

local isCrouching = TeleportService:GetTeleportSetting("isCrouching")
```

If no teleport setting exists under the given key, this function will
return _nil_.

#### Differences from GlobalDataStores

Although they share some similarities, there are some key differences
between teleport settings and datastores:

- `Class.GlobalDataStore:SetAsync()` stores the data on Roblox servers
  whereas SetTeleportSetting stores the data locally
- Data stored in a `Class.GlobalDataStore` is preserved after the user
  leaves the game universe whereas teleport settings are not
- `Class.GlobalDataStore|GlobalDataStores` can only be accessed on the
  server, whereas teleport settings can only be accessed on the client
- `Class.GlobalDataStore|GlobalDataStores` have usage limits, whereas
  teleport settings do not

In general teleport settings should be used to preserve client side
information within a single play session across different places in a
game. `Class.GlobalDataStore|GlobalDataStores` should be used to save
important player data that needs to be accessed across player sessions.

#### Teleport settings and security

As teleport settings are stored locally, it is possible they can be
manipulated by malicious users. This risk can be mitigated by employing
server side validation.

#### Studio Limitation

Note that this service does not work during playtesting in Roblox Studio;
to test aspects of your experience using it, you must publish the
experience and play it in the Roblox application.


TeleportService:GetTeleportSetting

setting

The key the value was stored under using
`Class.TeleportService:SetTeleportSetting()`.


Retrieves a teleport setting saved using
`Class.TeleportService:SetTeleportSetting()` using the given key.


The following code would send everyone in the current game to a reserved
server. Since reserved servers can only be joined by using
`Class.TeleportService:TeleportToPrivateServer()`, nobody will join the
reserved server afterwards.

Mind that, since everyone will be teleported, the current server will
(probably) shutdown as nobody would be left in it.

The following code would reserve one server, if it hasn't be reserved before.
Whenever someone says "reserved", they will be teleported to the private
server.

This function returns an access code that can be used to teleport players
to a reserved server, along with the server's
`Class.DataModel.PrivateServerId`. It can only be called on the server.

#### Reserved Servers

You can access reserved servers using:

- `Class.TeleportService:TeleportAsync()` with the
  `Class.TeleportOptions.ReservedServerAccessCode` parameter.
- `Class.TeleportService:TeleportToPrivateServer()`, with the access code
  `ReserveServer` returns.
  - A server is started when the access code is first used.
  - Access codes remain valid indefinitely, meaning reserved servers can
    still be joined if no game server is running (in this case a new
    server will be started).

You can see if the current server is a reserved server by using the
following code:

```lua
local isReserved = game.PrivateServerId ~= "" and game.PrivateServerOwnerId == 0
```

The `Class.DataModel.PrivateServerId` is constant across all server
instances associated with the server access code, the
`Class.DataModel.JobId` is not.

#### Studio Limitation

Note that this service does not work during playtesting in Roblox Studio;
to test aspects of your experience using it, you must publish the
experience and play it in the Roblox application.

#### Cross-Platform Play

Players on Xbox and PlayStation with cross‑play disabled will arrive in a
different server than players with cross‑play enabled. This can cause
multiple game servers with the same
`Class.DataModel.PrivateServerId|PrivateServerId` to exist. You can use
`Class.DataModel.MatchmakingType` to differentiate these game servers.


TeleportService:ReserveServer

The `Class.DataModel.PlaceId` of the place the reserved server is
being created for.


The server access code required by
`Class.TeleportService:TeleportToPrivateServer()` and the
`Class.DataModel.PrivateServerId` for the reserved server.


Returns an access code that can be used to teleport players to a reserved
server, along with the `Class.DataModel.PrivateServerId` for it.


This snippet demonstrates how `TeleportService` can be used to teleport the
`Class.Players.LocalPlayer|LocalPlayer()` from the client.

It also shows how `Class.TeleportService:SetTeleportGui()` can be used to
define a custom loading GUI. Note, this `ScreenGui` will need to be retrieved
at the destination place using
`Class.TeleportService:GetArrivingTeleportGui()` and be parented to the
`PlayerGui`.

This function sets the custom `Class.ScreenGui|teleport GUI` that will be
shown to the local user during teleportation, prior to the teleport being
invoked.

Note, the `Class.ScreenGui|teleport GUI` will not be used if the
destination place is in a different game. It will also not persist across
multiple teleports and will need to be set prior to each one.

This function should only be used on the client. If the teleportation
function is called from the server (as is the case with
`Class.TeleportService:TeleportAsync()`) then this function should be
called on the client prior to this. One way of doing this is listening to
a `Class.RemoteEvent` that fires several seconds before teleportation.

#### Loading screen

During a teleport, while the destination place is loading, the
_customLoadingScreen_ is parented to the `Class.CoreGui`. Once the place
has loaded the `Class.ScreenGui|loading screen` is
`Class.Instance.Parent|parented` to _nil_.

This `Class.ScreenGui` can be fetched at the destination place using
`Class.TeleportService:GetArrivingTeleportGui()`, allowing you to parent
it to the `Class.PlayerGui` and perform your own transitions.

You are advised to also `Class.Instance.Parent|parent` the
`Class.ScreenGui` to the `Class.PlayerGui` in the start place while the
teleport is initiating.

#### Studio Limitation

Note that this service does not work during playtesting in Roblox Studio;
to test aspects of your experience using it, you must publish the
experience and play it in the Roblox application.


TeleportService:SetTeleportGui

The loading `Class.ScreenGui` that is to be displayed during
teleportation.


Sets the custom `Class.ScreenGui|teleport GUI` that will be shown to the
local user during teleportation, prior to the teleport being invoked.


This function stores a value under a given key that persists across all
teleportations in the same game.

This method is intended for use on the client only and should not be used
on the server.

The stored value can later be retrieved using
`Class.TeleportService:GetTeleportSetting()`. This will work in the
current place and any subsequent places the `Class.Players.LocalPlayer`
teleports to, provided they are in the same game.

For example, in a game that allowed crouching you could save whether the
user is currently crouching prior to teleporting as a teleport setting:

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

local isCrouching = false
TeleportService:SetTeleportSetting("isCrouching", isCrouching)
```

The stored value can take one of the following forms:

- A table without mixed keys (all strings or all integers)
- A string
- A number
- A bool

If data is already stored under the given key, the previous value will be
overwritten by the new value.

#### Differences from GlobalDataStores

Although they share some similarities, there are some key differences
between teleport settings and datastores:

- `Class.GlobalDataStore:SetAsync()` stores the data on Roblox servers
  whereas SetTeleportSetting stores the data locally
- Data stored in a `Class.GlobalDataStore` is preserved after the user
  leaves the game universe whereas teleport settings are not
- `Class.GlobalDataStore|GlobalDataStores` can only be accessed on the
  server, whereas teleport settings can only be accessed on the client
- `Class.GlobalDataStore|GlobalDataStores` have usage limits, whereas
  teleport settings do not

In general teleport settings should be used to preserve client side
information within a single play session across different places in a
game. `Class.GlobalDataStore|GlobalDataStores` should be used to save
important player data that needs to be accessed across player sessions.

#### Teleport settings and security

As teleport settings are stored locally, it is possible they can be
manipulated by malicious users. This risk can be mitigated by employing
server side validation.

#### Studio Limitation

Note that this service does not work during playtesting in Roblox Studio;
to test aspects of your experience using it, you must publish the
experience and play it in the Roblox application.


TeleportService:SetTeleportSetting

The key to store the _value_ under. This key can be used to retrieve
the value using `Class.TeleportService:GetTeleportSetting()`.


value

Stores a value under a given key that persists across all teleportations
in the same game.


This snippet demonstrates how `TeleportService` can be used to teleport a
`Player` from the server.

This method should not be used for new work; the numerous teleport
functions have been combined into a single method,
`Class.TeleportService:TeleportAsync()|TeleportAsync()`, which should be
used instead.


TeleportService:Teleport

The `Class.Player` to teleport, if this function is being called from
the client this defaults to the `Class.Players.LocalPlayer`.


teleportData

Optional data to be passed to the destination place. Can be retrieved
using `Class.TeleportService:GetLocalPlayerTeleportData()`.


customLoadingScreen

Optional custom loading screen to be placed in the `Class.CoreGui` at
the destination place. Can be retrieved using
`Class.TeleportService:GetArrivingTeleportGui()`.


Teleports a `Class.Player` to the place associated with the given
`placeId`.


This function serves as the all-encompassing method to teleport a player
or group of players from one server to another. It can be used to:

- Teleport players to a different place.
- Teleport players to a specific server.
- Teleport players to a reserved server.

#### Group Teleport Limitations

- Groups of players can only be teleported within a single experience.
- No more than 50 players can be teleported with a single
  `Class.TeleportService:TeleportAsync()` call.

#### Potential Errors

This is a list of potential reasons a teleport may fail, ranging from
invalid teleports to network issues.

<table>
    <thead>
        <tr>
            <th>Error</th>
           	<th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Invalid placeId</td>
            <td>The provided place ID is below 0.</td>
        </tr>
        <tr>
            <td>Players empty</td>
            <td>The provided list of players to teleport is empty.</td>
        </tr>
        <tr>
            <td>List of players instances is incorrect</td>
            <td>Any of the provided players is not a Player object.</td>
        </tr>
        <tr>
            <td>TeleportOptions not of correct type</td>
            <td>The provided teleportOption is not a TeleportOptions object.</td>
        </tr>
        <tr>
            <td>TeleportAsync called from Client</td>
            <td>The client called TeleportAsync, which can only be called from the server.</td>
        </tr>
        <tr>
            <td>Incompatible Parameters</td>
            <td>
              Conflicting teleport options were used and TeleportService doesn't know where to send the player.<br><br>
              Conflicting TeleportOption parameters:<br>
               * ReservedServerAccessCode and ServerInstanceId<br>
               * ShouldReserveServer and ServerInstanceId<br>
               * ShouldReserveServer and ReservedServerAccessCode
            </td>
        </tr>
    </tbody>
</table>

For more information on how to teleport players between servers and
receive user data from a teleport, see
[Teleporting Between Places](/projects/teleport#sending-user-data-along-with-teleports).


TeleportService:TeleportAsync

The place ID the player(s) should be teleported to.


players

An optional `Class.TeleportOptions` object containing additional
arguments to the `Class.TeleportService:TeleportAsync()` call. If this
is not passed, no result will be returned.


If a `Class.TeleportOptions` parameter is passed, this will be a
`Class.TeleportAsyncResult` object that provides information about the
final teleport destination.


The all-encompassing method to teleport a player or group of players from
one server to another.


This code sample is an example of how
`Class.TeleportService:TeleportPartyAsync()` can be used to teleport a group
of `Player|Players`.

In this case, all `Player|Players` will be teleported to the specified
_placeId_ as a party. The `Class.DataModel.JobId` of the destination server is
then printed.

TeleportService:TeleportPartyAsync

An array containing the `Class.Player|Players` to teleport.


The `Class.DataModel.JobId` of the server instance the
`Class.Player|Players` were teleported to.


Teleports a group of `Class.Player|Players` to the same server of the
place with the given `Class.DataModel.PlaceId|PlaceId`, returning the
`Class.DataModel.JobId|JobId` of the server instance they were teleported
to.


TeleportService:TeleportToPlaceInstance

instanceId

The `Class.DataModel.JobId` of the server instance to teleport to.


spawnName

Optional name of the `Class.SpawnLocation` to spawn at.


Teleports a `Class.Player` to the server instance associated with the
given _placeId_ and _instanceId_.


TeleportService:TeleportToPrivateServer

reservedServerAccessCode

The reserved server access code returned by
`Class.TeleportService:ReserveServer()`.


An array of `Class.Player|Players` to teleport.


Teleport a group of `Class.Player|Players` to a reserved server created
using `Class.TeleportService:ReserveServer()`.


This code will teleport a player to Crossroads, and if there is a spawn named
"TeleportSpawn" then the player would spawn on it. This assumes it's being
used in a `Class.LocalScript`.

TeleportService:TeleportToSpawnByName

The name of the `Class.SpawnLocation` to spawn at.


A variant of `Class.TeleportService:Teleport()` that causes the
`Class.Player` to spawn at a `Class.SpawnLocation` of the given name at
the destination place.


TeleportService

This property used to control whether or not a `Class.Message` would be
shown by default. The default message has been removed, so this no longer
does anything.


TeleportService.CustomizedTeleportUI

Enables transporting `Class.Player|Players` between places and servers.


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

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

The `Class.Instance.Name` to search for.


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


If the `Class.Instance` is an `Class.Actor`, the `Class.Actor` itself is
returned. Otherwise, its closest ancestor `Class.Actor` is returned. If no
ancestor is an `Class.Actor`, the result is `nil`.


Instance:GetActor

Returns the `Class.Actor` associated with the Instance, if any.


This method returns the value which has been assigned to the given
attribute name. If no attribute has been assigned, `nil` is returned.

For example, the following code snippet sets and then gets the value of
the instance's `InitialPosition` attribute:

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

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local initialPosition = instance:GetAttribute("InitialPosition")
print(initialPosition)
```

##### See Also

- `Class.Instance:SetAttribute()` which sets the attribute with the given
  name to the given value.
- `Class.Instance:GetAttributes()` which returns a dictionary of key‑value
  pairs for each of the instance's attributes.


Instance:GetAttribute

The name of the attribute being retrieved.


The value which has been assigned to the given attribute name. If no
attribute has been assigned, `nil` is returned.


Returns the value which has been assigned to the given attribute name.


This function returns an event that behaves exactly like the
`Class.Object.Changed|Changed` event, except that it only fires when the
specific given attribute changes; effectively it is similar to
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()` but
for attributes.

It's generally a good idea to use this method instead of a connection to
`Class.Object.Changed|Changed` with a function that checks the attribute
name. Subsequent calls to this method on the same object with the same
attribute name return the same event.

The following code example returns a signal that fires the function
`attributeChanged()` when the part's `InitialPosition` attribute changes:

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

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local function attributeChanged()
	print("Attribute changed")
end

part:GetAttributeChangedSignal("InitialPosition"):Connect(attributeChanged)
```

See also `Class.Instance.AttributeChanged` which fires whenever any
attribute is changed on the instance.


Instance:GetAttributeChangedSignal

The name of the specified attribute for which the change signal is
being returned.


An event that fires when the given attribute changes.


Returns an event that fires when the given attribute changes.


This method returns a dictionary of key‑value pairs for each attribute
where the key is the attribute's name and the value is a non‑`nil` value.

For example, the following code snippet outputs an instance's attributes
and values:

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

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)
part:SetAttribute("CanUse", true)

for name, value in part:GetAttributes() do
	print(name .. " = " .. value)
end
```

See also `Class.Instance:GetAttribute()` which returns the value that has
been assigned to the given attribute name.


Instance:GetAttributes

A dictionary of string → variant pairs for each attribute where the
string is the name of the attribute and the variant is a non-nil
value.


Returns a dictionary of the instance's attributes.


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/TeleportService.yaml

TeleportService

Summary

Properties

Methods

Events

Properties

Methods

Events