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.
TeleportService doesn't support playtesting in Roblox Studio. You must publish the experience and use it on the Roblox application for testing.
Set up teleportation
To enable teleportation in your experience, use TeleportService:TeleportAsync(). The method accepts three parameters:
- The PlaceId 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.
You can only call TeleportAsync() from server-side scripts. This limitation reduces client-side exploitation. If necessary, you can call Teleport() from client-side scripts, but TeleportAsync() is the recommended method.
If you want to take precautions of handling errors when setting up teleportation, see how to handle failed teleports.
Enable 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.
Create 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.
Customize 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.
Teleport 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 teleported into a matchmade public server. The information of the first user in the list is used to matchmake to that 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.
To teleport users to a specific reserved server, set a valid TeleportOptions.ReservedServerAccessCode, which is a unique code for entering a reserved server.
To teleport users to a new reserved server, set TeleportOptions.ShouldReserveServer to true.
Send 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.
If your experience utilizes secure user data like in-experience currency or inventory, implement data stores or memory stores to maintain data from place to place.
To send basic non-secure data from place to place, call TeleportOptions:SetTeleportData() before passing it to TeleportAsync().
Don't pass secure data using TeleportOptions:SetTeleportData() because it has the risk of exploitation.
To get all data of a user arriving from a teleport on the server, use the Player:GetJoinData() function, which returns a dictionary including the data associated with the user.
local Players = game:GetService("Players")
local function onPlayerAdded(player)
local joinData = player:GetJoinData()
local teleportData = joinData.TeleportData
local randomNumber = teleportData.randomNumber
print(player.Name .. "joined with the number" .. randomNumber)
end
Players.PlayerAdded:Connect(onPlayerAdded)
To retrieve only the teleport data on the client, you can use TeleportService:GetLocalPlayerTeleportData().
Handle failed teleports
Like any API call that involves network requests, teleports can fail and throw an error. Wrap them in protected calls (pcall()). Some failures benefit from retries, particularly those involving reserved servers, so we recommend retrying some number of times on failures.
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 the TeleportService.TeleportInitFailed event.
The following example ModuleScript defines a SafeTeleport function to teleport the user in a protected call with retry logic. It also has a handleFailedTeleport function to deal with situations in which the call was successful, but the teleport didn't occur.
local TeleportService = game:GetService("TeleportService")
local ATTEMPT_LIMIT = 5
local RETRY_DELAY = 1
local FLOOD_DELAY = 15
local function SafeTeleport(placeId, players, options)
local attemptIndex = 0
local success, result -- define pcall results outside of loop so results can be reported later on
repeat
success, result = pcall(function()
return TeleportService:TeleportAsync(placeId, players, options) -- teleport the user in a protected call to prevent erroring
end)
attemptIndex += 1
if not success then
task.wait(RETRY_DELAY)
end
until success or attemptIndex == ATTEMPT_LIMIT -- stop trying to teleport if call was successful, or if retry limit has been reached
if not success then
warn(result) -- print the failure reason to output
end
return success, result
end
local function handleFailedTeleport(player, teleportResult, errorMessage, targetPlaceId, teleportOptions)
if teleportResult == Enum.TeleportResult.Flooded then
task.wait(FLOOD_DELAY)
elseif teleportResult == Enum.TeleportResult.Failure then
task.wait(RETRY_DELAY)
else
-- if the teleport is invalid, report the error instead of retrying
error(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
end
SafeTeleport(targetPlaceId, {player}, teleportOptions)
end
TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)
return SafeTeleport
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.