Teleporting Between Places

If you want to build an experience with many distinct places, such as a fantasy world with multiple towns, castles, dungeons, and a vast forest, you can use TeleportService to enable users to teleport between places in a universe, servers, or even to another experience.

You can use the Teleportation Playground sample experience to see how teleportation works.

Setting Up Teleportation

To enable teleportation in your experience, use TeleportService:TeleportAsync(). The method accepts three parameters:

  • The place ID for users to teleport to.
  • An array containing the Player instances representing the users to teleport.
  • An optional TeleportOptions instance that contains custom properties for the TeleportAsync() call.

1local Players = game:GetService("Players")
2local TeleportService = game:GetService("TeleportService")
3
4local TARGET_PLACE_ID = 1234 -- replace with your own place ID
5
6local playerToTeleport = Players:GetPlayers()[1] -- get the first user in the experience
7
8TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)
9

If you want to take precautions of handling errors when setting up teleportation, see Handling Failed Teleports.

Enabling Cross Experience Teleportation

For security purposes, teleporting a user from your experience to another experience owned by others, or the other way around, fails by default. To enable cross experience teleportation, open Game Settings > Security and enable Allow Third Party Teleports on Studio.

Creating Custom Teleport Screens

When a user triggers a teleport, they see the standard Roblox loading screen as they wait for the new place to load in. You can add a custom teleport screen to improve immersion for users by calling TeleportService:SetTeleportGui() on the client and pass through the ScreenGui to use before teleporting the user. The following example sets a customized ScreenGui located in ReplicatedStorage as the loading screen when a teleport happens. It doesn't run any scripts inside of the ScreenGui.


1local TeleportService = game:GetService("TeleportService")
2local ReplicatedStorage = game:GetService("ReplicatedStorage")
3
4local teleportGui = ReplicatedStorage.TeleportGui
5
6TeleportService:SetTeleportGui(teleportGui)
7

Customizing Teleport Options

You can customize teleportations, such as teleporting users to a specific server and sending user data along with teleports, by setting the TeleportOptions instance and passing it to the TeleportService:TeleportAsync() method.

Teleporting to Specific Servers

To teleport users to specific servers, set the target server using TeleportOptions and pass it to the TeleportService:TeleportAsync() method. If you don't specify a server, users are sorted into any public server.

To teleport users to a specific public server, set the TeleportOptions.ServerInstanceId property as a valid instance ID, which is a unique identifier for a public server.


1local teleportOptions = Instance.new("TeleportOptions")
2teleportOptions.ServerInstanceId = targetServerId
3

To teleport users to a specific reserved server, set a valid TeleportOptions.ReservedServerAccessCode, which is a unique code for entering a reserved server.


1local teleportOptions = Instance.new("TeleportOptions")
2teleportOptions.ReservedServerAccessCode = reservedServerCode
3

To teleport users to a new reserved server, set TeleportOptions.ShouldReserveServer to true.


1local teleportOptions = Instance.new("TeleportOptions")
2teleportOptions.ShouldReserveServer = true
3

Sending User Data Along with Teleports

Teleporting a user between places discards any local data associated with that user. You can use the following approaches to handle data persistence between places.


1local teleportData = {
2 randomNumber = RNG:NextInteger(1, 100);
3}
4
5local teleportOptions = Instance.new("TeleportOptions")
6teleportOptions:SetTeleportData(teleportData)
7

To get the data of a user arriving from a teleport, use the Player:GetJoinData() function, which returns a dictionary including the data associated with the user.


1local Players = game:GetService("Players")
2
3local function onPlayerAdded(player)
4 local joinData = player:GetJoinData()
5 local teleportData = joinData.TeleportData
6 local randomNumber = teleportData.randomNumber
7
8 print(player.Name .. "joined with the number" .. randomNumber)
9end
10
11Players.PlayerAdded:Connect(onPlayerAdded)
12

​​Handling Failed Teleports

Like any API call that involves network requests, teleports might fail and throw an error. Even if a call succeeds and the teleport initiates, it can still fail at the last moment without throwing an error and leave the user in the server. When this happens, it triggers TeleportService.TeleportInitFailed.

Wrap teleports in a protected call (pcall()) and retry if fails. The following example ModuleScript defines a SafeTeleport function to teleport the user in a protected call and a handleFailedTeleport function to retry failed teleports that are one-time hiccups and drops invalid ones that might have errors in the code.


1local TeleportService = game:GetService("TeleportService")
2
3local ATTEMPT_LIMIT = 5
4local RETRY_DELAY = 1
5local FLOOD_DELAY = 15
6
7local function SafeTeleport(placeId, players, options)
8 local attemptIndex = 0
9 local success, result -- define pcall results outside of loop so results can be reported later on
10
11 repeat
12 success, result = pcall(function()
13 return TeleportService:TeleportAsync(placeId, players, options) -- teleport the user in a protected call to prevent erroring
14 end)
15 attemptIndex += 1
16 if not success then
17 task.wait(RETRY_DELAY)
18 end
19 until success or attemptIndex == ATTEMPT_LIMIT -- stop trying to teleport if call was successful, or if retry limit has been reached
20
21 if not success then
22 warn(result) -- print the failure reason to output
23 end
24
25 return success, result
26end
27
28local function handleFailedTeleport(player, teleportResult, errorMessage, targetPlaceId, teleportOptions)
29 if teleportResult == Enum.TeleportResult.Flooded then
30 task.wait(FLOOD_DELAY)
31 elseif teleportResult == Enum.TeleportResult.Failure then
32 task.wait(RETRY_DELAY)
33 else
34 -- if the teleport is invalid, report the error instead of retrying
35 error(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
36 end
37
38 SafeTeleport(targetPlaceId, {player}, teleportOptions)
39end
40
41TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)
42
43return SafeTeleport
44

The SafeTeleport function receives the same arguments as the TeleportAsync() function. You can use the following ModuleScript with the SafeTeleport function to perform teleports from anywhere in your experience to reduce failed teleports.


1local Players = game:GetService("Players")
2local ServerScriptService = game:GetService("ServerScriptService")
3
4local SafeTeleport = require(ServerScriptService.SafeTeleport)
5
6local TARGET_PLACE_ID = 1818 -- replace with your own place ID
7
8local playerToTeleport = Players:GetPlayers()[1] -- get the first user in the game
9
10SafeTeleport(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)
11