# This file is automatically generated. Please don't edit it manually. # To submit a bug report on the content, see # https://devforum.roblox.com/c/bug-reports/documentation-issues/72 name: TeleportService type: class memory_category: Instances summary: | Enables transporting `Class.Player|Players` between places and servers. For more information on how to teleport players between servers, see [Teleport between places](../../../projects/teleport.md). description: | **TeleportService** is responsible for transporting `Class.Player|Players` between different places and servers. For more information on how to teleport players between servers, see [Teleport between places](../../../projects/teleport.md). code_samples: [] inherits: - Instance descendants: [] tags: - NotCreatable - Service deprecation_message: '' properties: - name: TeleportService.CustomizedTeleportUI summary: | No longer functional. description: | 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. code_samples: [] type: boolean tags: - NotReplicated - Deprecated deprecation_message: | This item is deprecated since the default message it controls has been removed. Do not use it for new work. security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: false capabilities: - Teleport methods: - name: TeleportService:GetArrivingTeleportGui summary: | Returns the _customLoadingScreen_ the `Class.Players.LocalPlayer|LocalPlayer` arrived into the place with. description: | 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. code_samples: - handling-a-teleport-loading-gui parameters: [] returns: - type: Instance summary: | The _customLoadingScreen_ the `Class.Players.LocalPlayer|LocalPlayer` arrived into the place with. tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - UI - Teleport - name: TeleportService:GetLocalPlayerTeleportData summary: | Returns the _teleportData_ the `Class.Players.LocalPlayer` arrived into the place with. description: | 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. code_samples: - getting-LocalPlayer-teleport-data parameters: [] returns: - type: Variant summary: | The teleport data the `Class.Players.LocalPlayer` arrived into the place with. tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Teleport - name: TeleportService:GetPlayerPlaceInstanceAsync summary: | 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. description: | 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:
# Name Type Description
1 currentInstance bool A bool indicating if the user was found in the current instance
2 error string An error message in the event of the lookup failing
3 placeId int64 The PlaceId of the server the user is in
4 instanceId string The JobId of the server the user is in
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:ReserveServerAsync()`, 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. code_samples: - following-a-player-in-a-universe parameters: - name: userId type: User default: summary: | The `Class.Player.UserId` of the `Class.Player`. returns: - type: Tuple summary: | See the table above. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Teleport - name: TeleportService:GetTeleportSetting summary: | Retrieves a teleport setting saved using `Class.TeleportService:SetTeleportSetting()` using the given key. description: | 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. code_samples: [] parameters: - name: setting type: string default: summary: | The key the value was stored under using `Class.TeleportService:SetTeleportSetting()`. returns: - type: Variant summary: | The value stored under the given key. tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Teleport - name: TeleportService:PromptExperienceDetailsAsync summary: | Prompts a `Class.Player` with information about the specified experience. The player can choose to teleport to the target experience through the prompt. description: | Prompts the specified `Class.Player` with information of the specified experience. The prompt includes the experience name, creator name, maturity rating, etc. The prompt also includes a **Join** button which the player can use to be teleported to the target experience. If the player is ineligible to join the target experience, the button will be disabled. Any teleport failures after the player clicks the **Join** button will also fire `Class.TeleportService.TeleportInitFailed` providing a reason for the failure. #### Limitations - For security purposes, teleporting a user from your experience to another experience owned by others fails by default. See [here](../../../projects/teleport.md#enable-cross-experience-teleportation) for steps to enable cross-experience teleportation. - This function currently can only be called from the client with `Class.Players.LocalPlayer` as the `player` parameter. - The join button will always be disabled during Studio playtesting; to test aspects of your experience using it, you must publish the experience and play it in the Roblox application. code_samples: - present-experience-details-page parameters: - name: player type: Player default: summary: | The `Class.Player` to be presented the prompt. - name: universeId type: int64 default: summary: | `Class.DataModel.UniverseId` of the experience to be presented to the `Class.Player`. returns: - type: PromptExperienceDetailsResult summary: | `Enum.PromptExperienceDetailsResult` tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Teleport - name: TeleportService:ReserveServer summary: | Returns an access code that can be used to teleport players to a reserved server, along with the `Class.DataModel.PrivateServerId` for it. description: '' code_samples: - TeleportService-ReserveServer1 - teleportservice-teleport-to-a-reserved-server-via-chat parameters: - name: placeId type: int64 default: summary: | The `Class.DataModel.PlaceId` of the place the reserved server is being created for. returns: - type: Tuple summary: | The server access code required by `Class.TeleportService:TeleportToPrivateServer()` and the `Class.DataModel.PrivateServerId` for the reserved server. tags: - Yields - Deprecated deprecation_message: | Use `Class.TeleportService:ReserveServerAsync()|ReserveServerAsync()` instead. security: None thread_safety: Unsafe capabilities: - Teleport - name: TeleportService:ReserveServerAsync summary: | Returns an access code that can be used to teleport players to a reserved server, along with the `Class.DataModel.PrivateServerId` for it. description: | 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 `ReserveServerAsync` 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. code_samples: - TeleportService-ReserveServer1 - teleportservice-teleport-to-a-reserved-server-via-chat parameters: - name: placeId type: int64 default: summary: | The `Class.DataModel.PlaceId` of the place the reserved server is being created for. returns: - type: Tuple summary: | The server access code required by `Class.TeleportService:TeleportToPrivateServer()` and the `Class.DataModel.PrivateServerId` for the reserved server. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Teleport - name: TeleportService:SetTeleportGui summary: | Sets the custom `Class.ScreenGui|teleport GUI` that will be shown to the local user during teleportation, prior to the teleport being invoked. description: | 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. #### External references The teleport GUI and all of its descendants are carried to the destination place, but any property that references an `Class.Instance` **outside** the GUI's own tree is cleared during the teleport. For example, a `Class.Sound` inside the GUI whose `Class.Sound.SoundGroup|SoundGroup` points to a `Class.SoundGroup` under `Class.SoundService` will arrive with that reference set to `nil`, because the target lives outside the GUI and cannot safely cross the boundary between servers. References that point to other instances **within** the GUI tree are preserved. If your loading screen depends on an external instance, recreate that instance inside the GUI tree. #### 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. code_samples: - teleporting-the-local-player parameters: - name: gui type: Instance default: summary: | The loading `Class.ScreenGui` that is to be displayed during teleportation. returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - UI - Teleport - name: TeleportService:SetTeleportSetting summary: | Stores a value under a given key that persists across all teleportations in the same game. description: | 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 may only contain value types. It cannot contain `Class.Instance|Instances` or other types that reference engine state, as these cannot safely cross the boundary between servers. Allowed values: - Primitives: a `bool`, a `number`, or a `string` - Value types such as `Datatype.Vector3`, `Datatype.CFrame`, `Datatype.Color3`, `Datatype.UDim2`, `Datatype.NumberSequence`, `Datatype.ColorSequence`, `Enum` items, and similar - A table without mixed keys (all strings or all integers) containing only the allowed types above Not allowed (these will be removed before the teleport completes): - `Class.Instance` and instance references - `Datatype.RBXScriptConnection|Connections`, `Datatype.RBXScriptSignal`, and functions - `SharedTable` - Types that reference engine or `Class.DataModel` state, such as `Class.InputObject`, `Datatype.RaycastParams`, and `Datatype.RaycastResult` If a stored setting contains a disallowed type, that value is removed and an error is written to the developer console. Convert instance references to plain values (for example, a numeric ID or a string path). 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. code_samples: [] parameters: - name: setting type: string default: summary: | The key to store the _value_ under. This key can be used to retrieve the value using `Class.TeleportService:GetTeleportSetting()`. - name: value type: Variant default: summary: | The value to store. returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Teleport - name: TeleportService:Teleport summary: | Teleports a `Class.Player` to the place associated with the given `placeId`. description: | 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. code_samples: - teleporting-the-local-player - teleporting-from-the-server parameters: - name: placeId type: int64 default: summary: | The ID of the place to teleport to. - name: player type: Instance default: nil summary: | The `Class.Player` to teleport, if this function is being called from the client this defaults to the `Class.Players.LocalPlayer`. - name: teleportData type: Variant default: summary: | Optional data to be passed to the destination place. Can be retrieved using `Class.TeleportService:GetLocalPlayerTeleportData()`. - name: customLoadingScreen type: Instance default: nil summary: | Optional custom loading screen to be placed in the `Class.CoreGui` at the destination place. Can be retrieved using `Class.TeleportService:GetArrivingTeleportGui()`. returns: - type: () summary: '' tags: [] deprecation_message: | Use `Class.TeleportService:TeleportAsync()|TeleportAsync()` for server-side teleports. For client-side teleports, use a `Class.RemoteEvent` to signal the server to call `TeleportAsync()`. For a migration guide, see [Teleport between places](../../../projects/teleport.md#migrate-to-secure-teleports). security: None thread_safety: Unsafe capabilities: - UI - Teleport - name: TeleportService:TeleportAsync summary: | The all-encompassing method to teleport a player or group of players from one server to another. description: | 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. #### Server-Only This method can only be called from the server. If you need to initiate a teleport from the client, use a `Class.RemoteEvent` to signal the server, then call `Class.TeleportService:TeleportAsync()` from a server `Class.Script`. Client-side teleports using `Class.TeleportService:Teleport()` is not recommended for new work. See [Teleport between places](../../../projects/teleport.md) for more information. #### 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.
Error Description
Invalid placeId The provided place ID is below 0.
Players empty The provided list of players to teleport is empty.
List of players instances is incorrect Any of the provided players is not a Player object.
TeleportOptions not of correct type The provided teleportOption is not a TeleportOptions object.
TeleportAsync called from Client The client called TeleportAsync, which can only be called from the server.
Incompatible Parameters Conflicting teleport options were used and TeleportService doesn't know where to send the player.

Conflicting TeleportOption parameters:
* ReservedServerAccessCode and ServerInstanceId
* ShouldReserveServer and ServerInstanceId
* ShouldReserveServer and ReservedServerAccessCode
For more information on how to teleport players between servers and receive user data from a teleport, see [Teleport between places](../../../projects/teleport.md#sending-user-data-along-with-teleports). code_samples: [] parameters: - name: placeId type: int64 default: summary: | The place ID the player(s) should be teleported to. - name: players type: Instances default: summary: | An array of the player(s) to teleport. - name: teleportOptions type: Instance default: nil summary: | An optional `Class.TeleportOptions` object containing additional arguments to the `Class.TeleportService:TeleportAsync()` call. If this is not passed, no result will be returned. returns: - type: Instance summary: | If a `Class.TeleportOptions` parameter is passed, this will be a `Class.TeleportAsyncResult` object that provides information about the final teleport destination. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - UI - Teleport - name: TeleportService:TeleportPartyAsync summary: | 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. description: | 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. code_samples: - teleport-all-players-in-the-server parameters: - name: placeId type: int64 default: summary: | The ID of the place to teleport to. - name: players type: Instances default: summary: | An array containing the `Class.Player|Players` to teleport. - name: teleportData type: Variant default: summary: | Optional data to be passed to the destination place. Can be retrieved using `Class.TeleportService:GetLocalPlayerTeleportData()`. - name: customLoadingScreen type: Instance default: nil summary: | Optional custom loading screen to be placed in the `Class.CoreGui` at the destination place. Can be retrieved using `Class.TeleportService:GetArrivingTeleportGui()`. returns: - type: string summary: | The `Class.DataModel.JobId` of the server instance the `Class.Player|Players` were teleported to. tags: - Yields - Deprecated deprecation_message: | Use `Class.TeleportService:TeleportAsync()|TeleportAsync()` instead. For a migration guide, see [Teleport between places](../../../projects/teleport.md#migrate-to-secure-teleports). security: None thread_safety: Unsafe capabilities: - UI - Teleport - name: TeleportService:TeleportToPlaceInstance summary: | Teleports a `Class.Player` to the server instance associated with the given _placeId_ and _instanceId_. description: | 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. code_samples: - following-a-player-in-a-universe parameters: - name: placeId type: int64 default: summary: | The ID of the place to teleport to. - name: instanceId type: string default: summary: | The `Class.DataModel.JobId` of the server instance to teleport to. - name: player type: Instance default: nil summary: | The `Class.Player` to teleport, if this function is being called from the client this defaults to the `Class.Players.LocalPlayer`. - name: spawnName type: string default: summary: | Optional name of the `Class.SpawnLocation` to spawn at. - name: teleportData type: Variant default: summary: | Optional data to be passed to the destination place. Can be retrieved using `Class.TeleportService:GetLocalPlayerTeleportData()`. - name: customLoadingScreen type: Instance default: nil summary: | Optional custom loading screen to be placed in the `Class.CoreGui` at the destination place. Can be retrieved using `Class.TeleportService:GetArrivingTeleportGui()`. returns: - type: () summary: '' tags: - Deprecated deprecation_message: | Use `Class.TeleportService:TeleportAsync()|TeleportAsync()` instead. For a migration guide, see [Teleport between places](../../../projects/teleport.md#migrate-to-secure-teleports). security: None thread_safety: Unsafe capabilities: - UI - Teleport - name: TeleportService:TeleportToPrivateServer summary: | Teleport a group of `Class.Player|Players` to a reserved server created using `Class.TeleportService:ReserveServerAsync()`. description: | 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. code_samples: - teleportservice-teleport-to-a-reserved-server-via-chat - TeleportService-ReserveServer1 parameters: - name: placeId type: int64 default: summary: | The ID of the place to teleport to. - name: reservedServerAccessCode type: string default: summary: | The reserved server access code returned by `Class.TeleportService:ReserveServerAsync()`. - name: players type: Instances default: summary: | An array of `Class.Player|Players` to teleport. - name: spawnName type: string default: summary: | Optional name of the `Class.SpawnLocation` to spawn at. - name: teleportData type: Variant default: summary: | Optional data to be passed to the destination place. Can be retrieved using `Class.TeleportService:GetLocalPlayerTeleportData()`. - name: customLoadingScreen type: Instance default: nil summary: | Optional custom loading screen to be placed in the `Class.CoreGui` at the destination place. Can be retrieved using `Class.TeleportService:GetArrivingTeleportGui()`. returns: - type: () summary: '' tags: - Deprecated deprecation_message: | Use `Class.TeleportService:TeleportAsync()|TeleportAsync()` instead. For a migration guide, see [Teleport between places](../../../projects/teleport.md#migrate-to-secure-teleports). security: None thread_safety: Unsafe capabilities: - UI - Teleport - name: TeleportService:TeleportToSpawnByName summary: | 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. description: | 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. code_samples: - TeleportService-TeleportToSpawnByName1 parameters: - name: placeId type: int64 default: summary: | The ID of the place to teleport to. - name: spawnName type: string default: summary: | The name of the `Class.SpawnLocation` to spawn at. - name: player type: Instance default: nil summary: | The `Class.Player` to teleport, if this function is being called from the client this defaults to the `Class.Players.LocalPlayer`. - name: teleportData type: Variant default: summary: | Optional data to be passed to the destination place. Can be retrieved using `Class.TeleportService:GetLocalPlayerTeleportData()`. - name: customLoadingScreen type: Instance default: nil summary: | Optional custom loading screen to be placed in the `Class.CoreGui` at the destination place. Can be retrieved using `Class.TeleportService:GetArrivingTeleportGui()`. returns: - type: () summary: '' tags: - Deprecated deprecation_message: | Use `Class.TeleportService:TeleportAsync()|TeleportAsync()` instead. For a migration guide, see [Teleport between places](../../../projects/teleport.md#migrate-to-secure-teleports). security: None thread_safety: Unsafe capabilities: - UI - Teleport events: - name: TeleportService.LocalPlayerArrivedFromTeleport summary: | Fires when the `Class.Players.LocalPlayer|LocalPlayer` enters the place following a teleport. description: | 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. code_samples: [] parameters: - name: loadingGui type: Instance default: summary: | The _customLoadingScreen_ the `Class.Players.LocalPlayer|LocalPlayer` arrived into the place with. - name: dataTable type: Variant default: summary: | The _teleportData_ the `Class.Players.LocalPlayer|LocalPlayer` arrived into the place with. tags: [] deprecation_message: '' security: None capabilities: - Teleport - name: TeleportService.TeleportInitFailed summary: | Fires when a teleport fails to start, leaving the player in their current server. description: | 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.
Original Teleport Type Teleport Data ReservedServerAccessCode ServerInstanceId ShouldReserveServer
Individual player to place Original value None None false
Player(s) to reserved server Original value Original value, or the code generated if ShouldReserveServer was originally true None false
Player(s) to specific server Original value None Original value false
Players to place Original value None Same destination ID as the other players in the original teleport false
For more information on how to teleport players between servers, see [Teleport between places](../../../projects/teleport.md). code_samples: [] parameters: - name: player type: Instance default: summary: | The `Class.Player` instance that failed to teleport. - name: teleportResult type: TeleportResult default: summary: | The reason for the teleport failure. - name: errorMessage type: string default: summary: | The message provided to the player explaining the teleport failure. - name: placeId type: int64 default: summary: | The original target place ID of the teleport. - name: teleportOptions type: Instance default: summary: | A `Class.TeleportOptions` object that can be passed back to `Class.TeleportService:TeleportAsync()` to retry the failed teleport. tags: [] deprecation_message: '' security: None capabilities: - Teleport callbacks: []