TeleportService¶
Enables transporting Players between places and servers. For more information on how to teleport players between servers, see Teleport between places.
Note: Teleport, reserved servers, place instances, and teleport data are wired to the official platform.
Description¶
TeleportService is responsible for transporting Players between different places and servers.
For more information on how to teleport players between servers, see Teleport between places.
Inheritance¶
Object → Instance → TeleportService
Nova inheritance: Instance → TeleportService
Properties¶
CustomizedTeleportUI Supported Property Deprecated Legacy teleport-UI flag. Nova stores it, but the teleport UI does not read it.
Legacy teleport-UI flag. Nova stores it, but the teleport UI does not read it.
Modern Roblox removed the default teleport message and documents this as doing nothing. Nova's 2016 property is likewise stored but not consumed by the current teleport flow.
Methods¶
GetLocalPlayerTeleportData Supported Function Returns the _teleportData_ the Players.LocalPlayer arrived into the place with.
Returns the teleportData the Players.LocalPlayer arrived into the place with.
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.
GetPlayerPlaceInstanceAsync Supported 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.
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
Global.LuaGlobals.pcall()(see example below) - As this function returns the JobId of the server and not the access code returned by 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.
GetTeleportSetting Supported Function Retrieves a teleport setting saved using TeleportService.SetTeleportSetting() using the given key.
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¶
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.
ReserveServer Supported Function Deprecated Returns an access code that can be used to teleport players to a reserved server, along with the DataModel.PrivateServerId for it.
Returns an access code that can be used to teleport players to a reserved server, along with the DataModel.PrivateServerId for it.
This function is deprecated and no longer supported. It remains available for backward compatibility but should not be used for new work.
SetTeleportSetting Supported Function Stores a value under a given key that persists across all teleportations in the same game.
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 = false
TeleportService:SetTeleportSetting("isCrouching", isCrouching)
The stored value may only contain value types. It cannot contain Instances or other types that reference engine state, as these cannot safely cross the boundary between servers.
Allowed values:
- Primitives: a
bool, anumber, or astring - Value types such as Vector3, CFrame,
Color3, UDim2, NumberSequence,
ColorSequence,
Enumitems, 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):
- Instance and instance references
- Connections, RBXScriptSignal, and functions
SharedTable- Types that reference engine or DataModel state, such as InputObject, RaycastParams, and 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:
- 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¶
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.
Roblox reference signature
Teleport Supported Function Deprecated Teleports a Player to the place associated with the given placeId.
TeleportService:Teleport(int placeId, Instance player = nil, Variant teleportData, Instance customLoadingScreen = nil)
Teleports a Player to the place associated with the given
placeId.
This method should not be used for new work; the numerous teleport functions have been combined into a single method, TeleportAsync(), which should be used instead.
Roblox reference signature
TeleportCancel Supported Function
No description available.
RobloxScriptSecurityTeleportToPlaceInstance Supported Function Deprecated Teleports a Player to the server instance associated with the given _placeId_ and _instanceId_.
TeleportService:TeleportToPlaceInstance(int placeId, string instanceId, Instance player = nil, string spawnName = , Variant teleportData, Instance customLoadingScreen = nil)
Teleports a Player to the server instance associated with the given placeId and instanceId.
This method should not be used for new work; the numerous teleport functions have been combined into a single method, TeleportAsync(), which should be used instead.
Roblox reference signature
TeleportToPrivateServer Supported Function Deprecated Teleport a group of Players to a reserved server created using TeleportService.ReserveServerAsync().
TeleportService:TeleportToPrivateServer(int placeId, string reservedServerAccessCode, Objects players, string spawnName = , Variant teleportData, Instance customLoadingScreen = nil)
Teleport a group of Players to a reserved server created using TeleportService.ReserveServerAsync().
This method is deprecated and no longer supported. It remains available for backward compatibility but should not be used for new work. Use TeleportAsync() with TeleportOptions.ReservedServerId instead.
Roblox reference signature
TeleportToSpawnByName Supported Function Deprecated A variant of TeleportService.Teleport() that causes the Player to spawn at a SpawnLocation of the given name at the destination place.
TeleportService:TeleportToSpawnByName(int placeId, string spawnName, Instance player = nil, Variant teleportData, Instance customLoadingScreen = nil)
A variant of TeleportService.Teleport() that causes the Player to spawn at a SpawnLocation of the given name at the destination place.
This method should not be used for new work; the numerous teleport functions have been combined into a single method, TeleportAsync(), which should be used instead.
Roblox reference signature
Events¶
LocalPlayerArrivedFromTeleport Supported Event Fires when the LocalPlayer enters the place following a teleport.
Fires when the LocalPlayer enters the place following a teleport.
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 Class.ScreenGui|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 local player'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¶
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.
Callbacks¶
ConfirmationCallback Supported Callback
No description available.
RobloxScriptSecurityErrorCallback Supported Callback
No description available.
RobloxScriptSecurityInherited members¶
Inherited from Instance: 8 properties, 36 methods, 7 events. They are documented on the base class page.
20 modern Roblox member(s) are not implemented yet — expand to inspect
Members declared by Roblox's TeleportService class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.
Methods¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
Block |
TeleportService:Block(): null |
Not yet | — | RobloxScriptSecurity |
GetArrivingTeleportGui |
TeleportService:GetArrivingTeleportGui(): Instance |
Not yet | Returns the customLoadingScreen the LocalPlayer arrived into the place with. | — |
GetThirdPartyTeleportInfo |
TeleportService:GetThirdPartyTeleportInfo(goForth: bool): Tuple |
Not yet | — | RobloxScriptSecurity |
PromptExperienceDetailsAsync |
TeleportService:PromptExperienceDetailsAsync(player: Player, universeId: int64): PromptExperienceDetailsResult |
Not yet | Prompts a Player with information about the specified experience. The player can choose to teleport to the target experience through the prompt. | Yields |
PromptExperienceDetailsCompleted |
TeleportService:PromptExperienceDetailsCompleted(resultEnum: PromptExperienceDetailsResult, errorMessage: string): null |
Not yet | — | RobloxScriptSecurity |
ReserveServerAsync |
TeleportService:ReserveServerAsync(placeId: int64): Tuple |
Not yet | Returns an access code that can be used to teleport players to a reserved server, along with the DataModel.PrivateServerId for it. | Yields |
SetTeleportGui |
TeleportService:SetTeleportGui(gui: Instance): null |
Not yet | Sets the custom Class.ScreenGui\|teleport GUI that will be shown to the local user during teleportation, prior to the teleport being invoked. |
— |
TeleportAsync |
TeleportService:TeleportAsync(placeId: int64, players: Instances, teleportOptions: Instance = nil): Instance |
Not yet | The all-encompassing method to teleport a player or group of players from one server to another. | Yields |
TeleportedPlacesBackHistory |
TeleportService:TeleportedPlacesBackHistory(): Array |
Not yet | — | RobloxScriptSecurity |
TeleportedUniversesBackHistory |
TeleportService:TeleportedUniversesBackHistory(): Array |
Not yet | — | RobloxScriptSecurity |
TeleportPartyAsync |
TeleportService:TeleportPartyAsync(placeId: int64, players: Instances, teleportData: Variant, customLoadingScreen: Instance = nil): string |
Not yet | Teleports a group of Players to the same server of the place with the given PlaceId, returning the JobId of th… | Yields, PreferredDescriptorName, ThreadSafety, PreferredDes… |
TeleportReconnect |
TeleportService:TeleportReconnect(): null |
Not yet | — | RobloxScriptSecurity |
TeleportSwitchServer |
TeleportService:TeleportSwitchServer(): null |
Not yet | — | RobloxScriptSecurity |
TeleportTrustedBackForth |
TeleportService:TeleportTrustedBackForth(goForth: bool): null |
Not yet | — | RobloxScriptSecurity |
TeleportTrustedBackHistory |
TeleportService:TeleportTrustedBackHistory(placeId: int64): null |
Not yet | — | RobloxScriptSecurity |
UnblockAsync |
TeleportService:UnblockAsync(): Tuple |
Not yet | — | Yields, RobloxScriptSecurity |
Events¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
MenuTeleportAttempt |
MenuTeleportAttempt() |
Not yet | — | RobloxScriptSecurity |
OpenExperienceDetailsPrompt |
OpenExperienceDetailsPrompt(universeId: int64) |
Not yet | — | RobloxScriptSecurity |
ReconnectTeleportInitFailed |
ReconnectTeleportInitFailed(player: Instance, teleportResult: TeleportResult, errorMessage: string, placeId: int64, teleportOptions: Instance) |
Not yet | — | RobloxSecurity |
TeleportInitFailed |
TeleportInitFailed(player: Instance, teleportResult: TeleportResult, errorMessage: string, placeId: int64, teleportOptions: Instance) |
Not yet | Fires when a teleport fails to start, leaving the player in their current server. | — |
Roblox reference: TeleportService
Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.