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.
A teleportData parameter can be specified. This is data the client will transmit to the destination place and can be retrieved using
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
A customLoadingScreen argument can be specified. This is a
ScreenGui that is copied (without scripts) into the
CoreGui of the destination place.
TeleportService/SetTeleportGui is the preferred alternative to the customLoadingScreen argument as it can be called prior to the teleport.
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.
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/TeleportInitFailedevent will fire the error message and a
Enum/TeleportResultenumerator 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
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.
Alternative teleport functions
Before using Teleport, you should check to see if an alternative teleport function is more suitable:
TeleportService/TeleportToSpawnByNameis used to teleport a player to a place and spawn them at a specific
TeleportService/TeleportPartyAsyncis used to teleport a group of players together to the same server
TeleportService/TeleportToPlaceInstanceis used to teleport a player to a specific server in a place
TeleportService/TeleportToPrivateServeris used to teleport a player to a reserved server created using
For more information on how to teleport players, see the
Articles/Teleporting Between Places tutorial.
The ID of the place to teleport to
Optional data to be passed to the destination place. Can be retrieved using
Optional custom loading screen to be placed in the
Teleporting the local player
This snippet demonstrates how
TeleportService can be used to teleport the
Players/LocalPlayer|LocalPlayer from the client.
It also shows how
TeleportService/SetTeleportGui can be used to define a custom loading GUI. Note, this
ScreenGui will need to be retrieved at the destination place using
TeleportService/GetArrivingTeleportGui and be parented to the
local TeleportService = game:GetService("TeleportService") local ReplicatedStorage = game:GetService("ReplicatedStorage") local Players = game:GetService("Players") local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui") local placeId = 0 -- replace here local loadingGui = ReplicatedStorage:FindFirstChild("LoadingGui") -- replace here -- parent the loading gui for this place loadingGui.Parent = playerGui -- set the loading gui for the destination place TeleportService:SetTeleportGui(loadingGui) -- teleport the user TeleportService:Teleport(placeId)
Teleporting from the server
This snippet demonstrates how
TeleportService can be used to teleport a
Player from the server.
local Players = game:GetService("Players") local TeleportService = game:GetService("TeleportService") local placeId = 0 -- replace here local userId = 1 -- replace with player's userId -- find the player local player = Players:GetPlayerByUserId(userId) -- teleport the player TeleportService:Teleport(placeId, player)