Teleport

Function of:

Description:

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.

Teleport data

A teleportData parameter can be specified. This is data the client will transmit to the destination place and can be retrieved using TeleportService/GetLocalPlayerTeleportData.

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 TeleportService/SetTeleportSetting and TeleportService/GetTeleportSetting.

Loading screen

A customLoadingScreen argument can be specified. This is a ScreenGui that is copied (without scripts) into the CoreGui of the destination place.

Note, TeleportService/SetTeleportGui is the preferred alternative to the customLoadingScreen argument as it can be called prior to the teleport.

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

Teleport failure

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/TeleportInitFailed event will fire the error message and a Enum/TeleportResult enumerator 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

Alternative teleport functions

Before using Teleport, you should check to see if an alternative teleport function is more suitable:

TeleportService/TeleportToSpawnByName is used to teleport a player to a place and spawn them at a specific SpawnLocation
TeleportService/TeleportPartyAsync is used to teleport a group of players together to the same server
TeleportService/TeleportToPlaceInstance is used to teleport a player to a specific server in a place
TeleportService/TeleportToPrivateServer is used to teleport a player to a reserved server created using TeleportService/ReserveServer

For more information on how to teleport players, see the Articles/Teleporting Between Places tutorial.

Parameters

Name	Type	Default	Description
Name placeId	Type int64	Default	Summary The ID of the place to teleport to
Name player	Type Instance	Default nil	Summary The `Player` to teleport, if this function is being called from the client this defaults to the `Players/LocalPlayer`
Name teleportData	Type Variant	Default	Summary Optional data to be passed to the destination place. Can be retrieved using `TeleportService/GetLocalPlayerTeleportData`
Name customLoadingScreen	Type Instance	Default nil	Summary Optional custom loading screen to be placed in the `CoreGui` at the destination place. Can be retrieved using `TeleportService/GetArrivingTeleportGui`

Returns

Return Type	Summary
Return Type void	Summary

Code Samples

Teleporting from the server

This snippet demonstrates how TeleportService can be used to teleport a Player from the server.

Expand

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)

Copy Code Light Theme

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