TeleportService
TeleportService is responsible for transporting Players between different places and servers.
All teleporting functionality is consolidated into a single TeleportService:TeleportAsync() function, which is used to:
- Teleport players to a different place
- Teleport players to a specific server
- Teleport players to a reserved server
For more information on how to teleport players between servers, see Teleporting Between Places.
Summary
Properties
Methods
Returns the customLoadingScreen the LocalPlayer arrived into the place with.
Returns the teleportData the Players.LocalPlayer arrived into the place with.
Retrieves a teleport setting saved using TeleportService:SetTeleportSetting() using the given key.
Sets the custom teleport GUI that will be shown to the local user during teleportation, prior to the teleport being invoked.
Stores a value under a given key that persists across all teleportations in the same game.
Teleports a Player to the place associated with the given placeId.
Teleports a Player to the server instance associated with the given placeId and instanceId.
Teleport a group of Players to a reserved server created using TeleportService:ReserveServer().
A variant of TeleportService:Teleport() that causes the Player to spawn at a SpawnLocation of the given name at the destination place.
Returns an access code that can be used to teleport players to a reserved server, along with the DataModel.PrivateServerId for it.
The all encompassing method to teleport a player or group of players from one server to another.
Events
Fires when the LocalPlayer enters the place following a teleport. Provides the Player's teleportData and customLoadingScreen.
Fires when a teleport fails to start, leaving the player in their current server.
Properties
Methods
GetArrivingTeleportGui
This function returns the customLoadingScreen the 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 CoreGui. Once the place has loaded the loading screen is parented to nil.
If you wish to preserve the customLoadingScreen and perform your own transitions, you will need to parent it to the LocalPlayer's PlayerGui. For an example of this, see the code sample below.
Studio limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Returns
The customLoadingScreen the LocalPlayer arrived into the place with.
Code Samples
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")
local ReplicatedFirst = game:GetService("ReplicatedFirst")
local customLoadingScreen = TeleportService:GetArrivingTeleportGui()
if customLoadingScreen then
local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
ReplicatedFirst:RemoveDefaultLoadingScreen()
customLoadingScreen.Parent = playerGui
task.wait(5)
customLoadingScreen:Destroy()
end
GetLocalPlayerTeleportData
This function returns the teleport data the 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 DataStoreService to prevent tampering.
Returns
The teleport data the Players.LocalPlayer arrived into the place with.
Code Samples
local TeleportService = game:GetService("TeleportService")
local teleportData = TeleportService:GetLocalPlayerTeleportData()
print("Local player arrived with this data:", teleportData)
GetTeleportSetting
This function retrieves a teleport setting saved using 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 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:
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:
- GlobalDataStore:SetAsync() stores the data on Roblox servers whereas SetTeleportSetting stores the data locally
- Data stored in a GlobalDataStore is preserved after the user leaves the game universe whereas teleport settings are not
- GlobalDataStores can only be accessed on the server, whereas teleport settings can only be accessed on the client
- 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. 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
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Parameters
The key the value was stored under using TeleportService:SetTeleportSetting().
Returns
The value stored under the given key.
SetTeleportGui
This function sets the custom teleport GUI that will be shown to the local user during teleportation, prior to the teleport being invoked.
Note, the 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 TeleportService:TeleportAsync()) then this function should be called on the client prior to this. One way of doing this is listening to a RemoteEvent that fires several seconds before teleportation.
Loading screen
During a teleport, while the destination place is loading, the customLoadingScreen is parented to the CoreGui. Once the place has loaded the loading screen is parented to nil.
This ScreenGui can be fetched at the destination place using TeleportService:GetArrivingTeleportGui(), allowing you to parent it to the PlayerGui and perform your own transitions.
You are advised to also parent the ScreenGui to the PlayerGui in the start place while the teleport is initiating.
Studio Limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Parameters
Returns
Code Samples
local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local PLACE_ID = 0 -- replace here
local loadingGui = ReplicatedStorage:FindFirstChild("LoadingGui")
-- parent the loading gui for this place
loadingGui.Parent = playerGui
-- set the loading gui for the destination place
TeleportService:SetTeleportGui(loadingGui)
TeleportService:Teleport(PLACE_ID)
SetTeleportSetting
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 TeleportService:GetTeleportSetting(). This will work in the current place and any subsequent places the 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:
local TeleportService = game:GetService("TeleportService")local isCrouching = falseTeleportService: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:
- GlobalDataStore:SetAsync() stores the data on Roblox servers whereas SetTeleportSetting stores the data locally
- Data stored in a GlobalDataStore is preserved after the user leaves the game universe whereas teleport settings are not
- GlobalDataStores can only be accessed on the server, whereas teleport settings can only be accessed on the client
- 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. 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
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Parameters
The key to store the value under. This key can be used to retrieve the value using TeleportService:GetTeleportSetting().
The value to store.
Returns
Teleport
The numerous teleport functions have been combined into a single method, TeleportAsync, which should be used instead and may be used to:
- Teleport any number of players to a Public Server
- Follow a Friend to a Different Place
- Teleport any number of Players to a Reserved Server
This function teleports a Player to the place associated with the given placeId.
Teleport can be called both from the client and the server (see examples below).
When teleporting from the client, as only the Players.LocalPlayer can be teleported, no player argument is required.
You may only teleport players to places within the same game or active start places for other games.
Teleport data
A teleportData parameter can be specified. This is data the client will transmit to the destination place and can be retrieved using TeleportService:GetLocalPlayerTeleportData().
The teleportData can take any of the following forms:
- A table without mixed keys (all keys are strings or integers)
- A string
- A number
- A bool
As the teleportData is transmitted by the client it is not secure. For this reason it should only be used for local settings and not sensitive items (such as the users' score or in-game currency).
If you need teleport data to persist across multiple teleports, you can use TeleportService:SetTeleportSetting() and TeleportService:GetTeleportSetting().
Loading screen
A customLoadingScreen argument can be specified. This is a ScreenGui that is copied (without scripts) into the CoreGui of the destination place.
Note, TeleportService:SetTeleportGui() is the preferred alternative to the customLoadingScreen argument as it can be called prior to the teleport.
The loading ScreenGui can be obtained in the destination place using TeleportService:GetArrivingTeleportGui(), where developers can parent it to the PlayerGui. It will not be used if the destination place is in a different game.
Teleport failure
In some circumstances a teleport may fail. This can be due to the developer configuring the teleport incorrectly or issues with Roblox's servers.
- If a teleportation request is rejected the TeleportService.TeleportInitFailed event will fire the error message and a TeleportResult enumerator describing the issue
- Teleports can fail 'in transit', after the user has left the server, due to issues with Roblox's servers. In this case the user will be shown an error message and be required to rejoin the game
Studio limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Parameters
The ID of the place to teleport to.
The Player to teleport, if this function is being called from the client this defaults to the Players.LocalPlayer.
Optional data to be passed to the destination place. Can be retrieved using TeleportService:GetLocalPlayerTeleportData().
Optional custom loading screen to be placed in the CoreGui at the destination place. Can be retrieved using TeleportService:GetArrivingTeleportGui().
Returns
Code Samples
local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local PLACE_ID = 0 -- replace here
local loadingGui = ReplicatedStorage:FindFirstChild("LoadingGui")
-- parent the loading gui for this place
loadingGui.Parent = playerGui
-- set the loading gui for the destination place
TeleportService:SetTeleportGui(loadingGui)
TeleportService:Teleport(PLACE_ID)
local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local PLACE_ID = 0 -- replace here
local USER_ID = 1 -- replace with player's UserId
local player = Players:GetPlayerByUserId(USER_ID)
TeleportService:Teleport(PLACE_ID, player)
TeleportToPlaceInstance
The numerous teleport functions have been combined into a single method, TeleportAsync, which should be used instead and may be used to:
- Teleport any number of players to a Public Server
- Follow a Friend to a Different Place
- Teleport any number of Players to a Reserved Server
This function teleports a Player to the place instance associated with the given placeId and instanceId. It can only be used to teleport to places in the same game.
The placeId is the DataModel.PlaceId of the server and the instanceId is the JobId.
This function can not be used to teleport Players to servers created using TeleportService:ReserveServer() (reserved servers). For this, see TeleportService:TeleportToPrivateServer().
Spawn name
An optional spawnName parameter can be provided, which will cause the Player to initially spawn at the SpawnLocation of that name in the destination place. The SpawnLocation must be valid for the Player to spawn on. For example, it must be neutral or set to the same TeamColor as the Team the Player will be assigned to upon joining the game.
Teleport data
A teleportData parameter can be specified. This is data the client will transmit to the destination place and can be retrieved using TeleportService:GetLocalPlayerTeleportData().
The teleportData can take any of the following forms:
- A table without mixed keys (all keys are strings or integers)
- A string
- A number
- A bool
As the teleportData is transmitted by the client it is not secure. For this reason it should only be used for local settings and not sensitive items (such as the users' score or in-game currency).
If you need teleport data to persist across multiple teleports, you can use TeleportService:SetTeleportSetting() and TeleportService:GetTeleportSetting().
Loading screen
A customLoadingScreen argument can be specified. This is a ScreenGui that is copied (without scripts) into the CoreGui of the destination place.
Note, TeleportService:SetTeleportGui() is the preferred alternative to the customLoadingScreen argument as it can be called prior to the teleport.
The loading ScreenGui can be obtained in the destination place using TeleportService:GetArrivingTeleportGui(), where developers can parent it to the PlayerGui.
Teleport failure
In some circumstances a teleport may fail. This can be due to the developer configuring the teleport incorrectly or issues with Roblox's servers.
- If a teleportation request is rejected the TeleportService.TeleportInitFailed event will fire the error message and a TeleportResult enumerator describing the issue
- Teleports can fail 'in transit', after the user has left the server, due to issues with Roblox's servers. In this case the user will be shown an error message and be required to rejoin the game
Studio limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Parameters
The ID of the place to teleport to.
The DataModel.JobId of the server instance to teleport to.
The Player to teleport, if this function is being called from the client this defaults to the Players.LocalPlayer.
Optional name of the SpawnLocation to spawn at.
Optional data to be passed to the destination place. Can be retrieved using TeleportService:GetLocalPlayerTeleportData().
Optional custom loading screen to be placed in the CoreGui at the destination place. Can be retrieved using TeleportService:GetArrivingTeleportGui().
Returns
Code Samples
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")
Players.PlayerAdded:Connect(function(player)
-- Is this player following anyone?
local followId = player.FollowUserId
-- If so, find out where they are
if followId and followId ~= 0 then
local _currentInstance, _errorMessage, placeId, jobId
local success, errorMessage = pcall(function()
-- followId is the user ID of the player that you want to retrieve the place and job ID for
_currentInstance, _errorMessage, placeId, jobId = TeleportService:GetPlayerPlaceInstanceAsync(followId)
end)
if success then
-- Teleport player
TeleportService:TeleportToPlaceInstance(placeId, jobId, player)
else
warn(errorMessage)
end
else
warn("Player " .. player.UserId .. " is not following another player!")
end
end)
TeleportToPrivateServer
The numerous teleport functions have been combined into a single method, TeleportAsync, which should be used instead and may be used to:
- Teleport any number of players to a Public Server
- Follow a Friend to a Different Place
- Teleport any number of Players to a Reserved Server
This function teleports one or more Players to a reserved server created using TeleportService:ReserveServer().
The reservedServerAccessCode parameter is the access code returned by ReserveServer.
TeleportToPrivateServer can only be called on the server.
Spawn name
An optional spawnName parameter can be provided, which will cause the Players to initially spawn at the SpawnLocation of that name in the destination place. The SpawnLocation must be valid for the Players to spawn on. For example, it must be neutral or set to the same TeamColor as the Team the Players will be assigned to upon joining the game.
Teleport data
A teleportData parameter can be specified. This is data the clients will transmit to the destination place and can be retrieved using TeleportService:GetLocalPlayerTeleportData().
The teleportData can take any of the following forms:
- A table without mixed keys (all keys are strings or integers)
- A string
- A number
- A bool
As the teleportData is transmitted by the client it is not secure. For this reason it should only be used for local settings and not sensitive items (such as the users' score or in-game currency).
If you need teleport data to persist across multiple teleports, you can use TeleportService:SetTeleportSetting() and TeleportService:GetTeleportSetting().
Loading screen
A customLoadingScreen argument can be specified. This is a ScreenGui that is copied (without scripts) into the CoreGui of the destination place.
You are advised to instead set the loading screen on the client using TeleportService:SetTeleportGui(). The loading ScreenGui should also be parented to the Player's PlayerGui a few seconds before the teleport to ensure a smooth transition using a RemoteEvent. For an example of this see SetTeleportGui
The loading ScreenGui can be obtained in the destination place using TeleportService:GetArrivingTeleportGui(), where developers can parent it to the PlayerGui.
Teleport failure
In some circumstances a teleport may fail. This can be due to the developer configuring the teleport incorrectly or issues with Roblox's servers.
- If a teleportation request is rejected the TeleportService.TeleportInitFailed event will fire the error message and a TeleportResult enumerator describing the issue
- Teleports can fail 'in transit', after the user has left the server, due to issues with Roblox's servers. In this case the user will be shown an error message and be required to rejoin the game
Studio limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Parameters
The ID of the place to teleport to.
The reserved server access code returned by TeleportService:ReserveServer().
Optional name of the SpawnLocation to spawn at.
Optional data to be passed to the destination place. Can be retrieved using TeleportService:GetLocalPlayerTeleportData().
Optional custom loading screen to be placed in the CoreGui at the destination place. Can be retrieved using TeleportService:GetArrivingTeleportGui().
Returns
Code Samples
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local dataStore = DataStoreService:GetGlobalDataStore()
-- Get the saved code
local code = dataStore:GetAsync("ReservedServer")
if typeof(code) ~= "string" then -- None saved, create one
code = TeleportService:ReserveServer(game.PlaceId)
dataStore:SetAsync("ReservedServer", code)
end
local function joined(player)
player.Chatted:Connect(function(message)
if message == "reserved" then
TeleportService:TeleportToPrivateServer(game.PlaceId, code, { player })
end
end)
end
Players.PlayerAdded:Connect(joined)
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")
local code = TeleportService:ReserveServer(game.PlaceId)
local players = Players:GetPlayers()
TeleportService:TeleportToPrivateServer(game.PlaceId, code, players)
-- You could add extra arguments to this function: spawnName, teleportData and customLoadingScreen
TeleportToSpawnByName
The numerous teleport functions have been combined into a single method, TeleportAsync, which should be used instead and may be used to:
- Teleport any number of players to a Public Server
- Follow a Friend to a Different Place
- Teleport any number of Players to a Reserved Server
This function behaves the same as TeleportService:Teleport() with the exception that it includes a spawnName parameter, causing the Player to spawn at the SpawnLocation of that name at the destination place.
The SpawnLocation must be valid for the Player to spawn on. For example, it must be neutral or set to the same TeamColor as the Team the Player will be assigned to upon joining the game.
The Player will still spawn at the correct SpawnLocation even the teleport is to a place in a different universe. The spawn will also be correct if Players.CharacterAutoLoads is false in the destination place and the Character is loaded manually using LoadCharacter.
The teleportation will only affect the SpawnLocation used initially. If the Player respawns again subsequently it will not necessarily be at this SpawnLocation.
Studio limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Parameters
The ID of the place to teleport to.
The name of the SpawnLocation to spawn at.
The Player to teleport, if this function is being called from the client this defaults to the Players.LocalPlayer.
Optional data to be passed to the destination place. Can be retrieved using TeleportService:GetLocalPlayerTeleportData().
Optional custom loading screen to be placed in the CoreGui at the destination place. Can be retrieved using TeleportService:GetArrivingTeleportGui().
Returns
Code Samples
local TeleportService = game:GetService("TeleportService")
TeleportService:TeleportToSpawnByName(1818, "TeleportSpawn")
GetPlayerPlaceInstanceAsync
This function returns the PlaceId and JobId of the server the user with the given UserId is in, provided it is in the same game as the current place.
Then, 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 pcall() (see example below)
- As this function returns the JobId of the server and not the access code returned by TeleportService:ReserveServer(), the id returned is not appropriate for use with reserved servers.
Studio limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
See also:
Parameters
The Player.UserId of the Player.
Returns
See the table above.
Code Samples
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")
Players.PlayerAdded:Connect(function(player)
-- Is this player following anyone?
local followId = player.FollowUserId
-- If so, find out where they are
if followId and followId ~= 0 then
local _currentInstance, _errorMessage, placeId, jobId
local success, errorMessage = pcall(function()
-- followId is the user ID of the player that you want to retrieve the place and job ID for
_currentInstance, _errorMessage, placeId, jobId = TeleportService:GetPlayerPlaceInstanceAsync(followId)
end)
if success then
-- Teleport player
TeleportService:TeleportToPlaceInstance(placeId, jobId, player)
else
warn(errorMessage)
end
else
warn("Player " .. player.UserId .. " is not following another player!")
end
end)
ReserveServer
This function returns an access code that can be used to teleport players to a reserved server, along with the DataModel.PrivateServerId for it.
ReserveServer can only be called on the server.
Reserved Servers
The following are characteristics of reserved servers:
- They can only be accessed using TeleportService:TeleportToPrivateServer(), with the access code ReserveServer returns
- A game 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 game server will be started)
You can see if the current server is a reserved server by using the following code:
local isReserved = game.PrivateServerId ~= "" and game.PrivateServerOwnerId == 0
The DataModel.PrivateServerId is constant across all server instances associated with the server access code, the DataModel.JobId is not.
Studio limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Cross-Platform Play
Players on Xbox One with cross-platform play disabled will arrive in a different server with players with cross-platform play enabled. This can cause multiple game servers with the same PrivateServerId to exist."
Parameters
The DataModel.PlaceId of the place the reserved server is being created for.
Returns
The server access code required by TeleportService:TeleportToPrivateServer() and the DataModel.PrivateServerId for the reserved server.
Code Samples
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")
local code = TeleportService:ReserveServer(game.PlaceId)
local players = Players:GetPlayers()
TeleportService:TeleportToPrivateServer(game.PlaceId, code, players)
-- You could add extra arguments to this function: spawnName, teleportData and customLoadingScreen
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local dataStore = DataStoreService:GetGlobalDataStore()
-- Get the saved code
local code = dataStore:GetAsync("ReservedServer")
if typeof(code) ~= "string" then -- None saved, create one
code = TeleportService:ReserveServer(game.PlaceId)
dataStore:SetAsync("ReservedServer", code)
end
local function joined(player)
player.Chatted:Connect(function(message)
if message == "reserved" then
TeleportService:TeleportToPrivateServer(game.PlaceId, code, { player })
end
end)
end
Players.PlayerAdded:Connect(joined)
TeleportAsync
This function serves as the all-encompassing method to teleport a player or group of players from one server to another.
All forms of player teleportation are consolidated into this single function, which is 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 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 placeId 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 Teleporting Between Places.
Parameters
The place ID the player(s) should be teleported to.
An array of the player(s) to teleport.
An optional TeleportOptions object containing additional arguments to the TeleportAsync call.
Returns
A TeleportAsyncResult object that provides information about the final teleport destination.
TeleportPartyAsync
The numerous teleport functions have been combined into a single method, TeleportAsync, which should be used instead and may be used to:
- Teleport any number of players to a Public Server
- Follow a Friend to a Different Place
- Teleport any number of Players to a Reserved Server
This function teleports a group of Players to the same server instance in the given place. It returns the DataModel.JobId of the server instance the players were teleported to.
This function can only be called from the server.
You may only use this function to teleport to a place in the same game. This function can not teleport more than 50 Players in a single party.
Currently this function may not work reliably when teleporting Players to the same place they are currently in.
Teleport data
A teleportData parameter can be specified. This is data the clients will transmit to the destination place and can be retrieved using TeleportService:GetLocalPlayerTeleportData().
The teleportData can take any of the following forms:
- A table without mixed keys (all keys are strings or integers)
- A string
- A number
- A bool
As the teleportData is transmitted by the client it is not secure. For this reason it should only be used for local settings and not sensitive items (such as the users' score or in-game currency).
Loading screen
A customLoadingScreen argument can be specified. This is a ScreenGui that is copied (without scripts) into the CoreGui of the destination place. It can be retrieved at the destination place using TeleportService:GetArrivingTeleportGui() and will not be used if the destination place is in a different game.
You are advised to instead set the loading screen on the client using TeleportService:SetTeleportGui(). The loading ScreenGui should also be parented to the Players' PlayerGuis a few seconds before the teleport to ensure a smooth transition using a RemoteEvent. For an example of this see SetTeleportGui.
Teleport failure
In some circumstances a teleport may fail. This can be due to the developer configuring the teleport incorrectly or issues with Roblox's servers.
- If a teleportation request is rejected the TeleportService.TeleportInitFailed event will fire the error message and a TeleportResult enumerator describing the issue
- Teleports can fail 'in transit', after the user has left the server, due to issues with Roblox's servers. In this case the user will be shown an error message and be required to rejoin the game
Studio limitation
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
See also:
Parameters
The ID of the place to teleport to.
Optional data to be passed to the destination place. Can be retrieved using TeleportService:GetLocalPlayerTeleportData().
Optional custom loading screen to be placed in the CoreGui at the destination place. Can be retrieved using TeleportService:GetArrivingTeleportGui().
Returns
The DataModel.JobId of the server instance the Players were teleported to.
Code Samples
local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local PLACE_ID = 0 -- replace
local playerList = Players:GetPlayers()
local success, result = pcall(function()
return TeleportService:TeleportPartyAsync(PLACE_ID, playerList)
end)
if success then
local jobId = result
print("Players teleported to", jobId)
else
warn(result)
end
Events
LocalPlayerArrivedFromTeleport
This function fires when the 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 TeleportService:GetLocalPlayerTeleportData() and 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 LocalScript parented to 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 CoreGui. Once the place has loaded the loading screen is parented to nil.
If you wish to preserve the customLoadingScreen and perform your own transitions, you will need to parent it to the LocalPlayer's PlayerGui. For example, using the following code inside a LocalScript in ReplicatedFirst:
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
This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.
Parameters
The customLoadingScreen the LocalPlayer arrived into the place with.
The teleportData the LocalPlayer arrived into the place with.
TeleportInitFailed
This event fires on both the client and the server when a request to teleport from a function such as 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 TeleportOptions object provided by this event is not identical to the one passed to the original 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 Teleporting Between Places.
Parameters
The reason for the teleport failure.
The message provided to the player explaining the teleport failure.
The original target place ID of the teleport.
A TeleportOptions object that can be passed back to TeleportService:TeleportAsync() to retry the failed teleport.