26 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

TeleportService

Inherits from: Instance → Object

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.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Properties

Inherited from Instance

Inherited from Object

TeleportService.CustomizedTeleportUI

Deprecated. This item is deprecated since the default message it controls has been removed. Do not use it for new work.

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

Methods

Inherited from Instance

Inherited from Object

TeleportService: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 local player's 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.

Returns

Code samples: View on Creator Hub (handling-a-teleport-loading-gui).

TeleportService: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

Code samples: View on Creator Hub (getting-LocalPlayer-teleport-data).

TeleportService: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:

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

Parameters

Returns

Code samples: View on Creator Hub (following-a-player-in-a-universe).

TeleportService: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

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.

Parameters

Returns

TeleportService:PromptExperienceDetailsAsync

Prompts the specified 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 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 for steps to enable cross-experience teleportation.
• This function currently can only be called from the client with 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.

Parameters

Returns

Code samples: View on Creator Hub (present-experience-details-page).

TeleportService:ReserveServer

Deprecated. Use ReserveServerAsync() instead.

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

Parameters

Returns

Code samples: View on Creator Hub (TeleportService-ReserveServer1, teleportservice-teleport-to-a-reserved-server-via-chat).

TeleportService:ReserveServerAsync

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

Reserved Servers

You can access reserved servers using:

• TeleportService:TeleportAsync() with the TeleportOptions.ReservedServerAccessCode parameter.
• 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:

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

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 PrivateServerId to exist. You can use DataModel.MatchmakingType to differentiate these game servers.

Parameters

Returns

Code samples: View on Creator Hub (TeleportService-ReserveServer1, teleportservice-teleport-to-a-reserved-server-via-chat).

TeleportService: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.

External references

The teleport GUI and all of its descendants are carried to the destination place, but any property that references an Instance outside the GUI's own tree is cleared during the teleport. For example, a Sound inside the GUI whose SoundGroup points to a SoundGroup under 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.

Parameters

Returns

Code samples: View on Creator Hub (teleporting-the-local-player).

TeleportService: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 = 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, a number, or a string
• Value types such as Vector3, CFrame, Color3, UDim2, NumberSequence, 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):

• 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

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.

Parameters

Returns

TeleportService:Teleport

Deprecated. Use TeleportAsync() for server-side teleports. For client-side teleports, use a RemoteEvent to signal the server to call TeleportAsync(). For a migration guide, see Teleport between places.

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.

Parameters

Returns

Code samples: View on Creator Hub (teleporting-the-local-player, teleporting-from-the-server).

TeleportService:TeleportAsync

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 RemoteEvent to signal the server, then call TeleportService:TeleportAsync() from a server Script. Client-side teleports using TeleportService:Teleport() is not recommended for new work. See Teleport between places 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 TeleportService:TeleportAsync() call.

Potential Errors

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

For more information on how to teleport players between servers and receive user data from a teleport, see Teleport between places.

Parameters

Returns

TeleportService:TeleportPartyAsync

Deprecated. Use TeleportAsync() instead. For a migration guide, see Teleport between places.

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.

Parameters

Returns

Code samples: View on Creator Hub (teleport-all-players-in-the-server).

TeleportService:TeleportToPlaceInstance

Deprecated. Use TeleportAsync() instead. For a migration guide, see Teleport between places.

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.

Parameters

Returns

Code samples: View on Creator Hub (following-a-player-in-a-universe).

TeleportService:TeleportToPrivateServer

Deprecated. Use TeleportAsync() instead. For a migration guide, see Teleport between places.

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.

Parameters

Returns

Code samples: View on Creator Hub (teleportservice-teleport-to-a-reserved-server-via-chat, TeleportService-ReserveServer1).

TeleportService:TeleportToSpawnByName

Deprecated. Use TeleportAsync() instead. For a migration guide, see Teleport between places.

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.

Parameters

Returns

Code samples: View on Creator Hub (TeleportService-TeleportToSpawnByName1).

Events

Inherited from Instance

Inherited from Object

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

Parameters

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

For more information on how to teleport players between servers, see Teleport between places.

Parameters