TeleportToPlaceInstance

Unsafe

For thread safety, this property is not safe to read in an unsynchronized thread.

Function of:

Description:

The numerous teleport functions have been combined into a single method, TeleportService/TeleportAsync|TeleportAsync, which should be used instead and may be used to:

Teleport any number of players to a Public Server
Follow a Friend to a Different Place
Teleport any number of Players to a Reserved Server

This function teleports a Player to the place instance associated with the given placeId and instanceId. It can only be used to teleport to places in the same game.

The placeId is the DataModel/PlaceId of the server and the instanceId is the DataModel/JobId|JobId.

This function can not be used to teleport Player|Players to servers created using TeleportService/ReserveServer (reserved servers). For this, see TeleportService/TeleportToPrivateServer.

Spawn name

An optional spawnName parameter can be provided, which will cause the Player to initially spawn at the SpawnLocation of that name in the destination place. The SpawnLocation must be valid for the Player to spawn on. For example, it must be SpawnLocation/Neutral|neutral or set to the same SpawnLocation/TeamColor|TeamColor as the Team the Player will be assigned to upon joining the game.

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.

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

Studio limitation

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.

Parameters

Name	Type	Default	Description
Name placeId	Type int64	Default	Summary The ID of the place to teleport to
Name instanceId	Type string	Default	Summary The `DataMode/JobId` of the server instance 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 spawnName	Type string	Default	Summary Optional name of the `SpawnLocation` to spawn at
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 No return

Code Samples

Following Another Player

The code sample below, when placed inside a Script within ServerScriptService, will teleport a player who’s following another player to the associated place/server. Note that this will not work if the player being followed is in a reserved server.

			
				Following Another Player

				Expected Output
			
				Expand
				
			local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	-- Is this player following anyone?
	local followId = player.FollowUserId
	-- If so, find out where they are
	if followId and followId ~= 0 then
		local success, errorMessage = pcall(function()
			-- followId is the user ID of the player that you want to retrieve the place and job ID for
			currentInstance, _, placeId, jobId = TeleportService:GetPlayerPlaceInstanceAsync(followId)
		end)
		if success then
			-- Teleport player
			TeleportService:TeleportToPlaceInstance(placeId, jobId, player)
		end
	else
		warn("Player " .. player.UserId .. " is not following another player!")
	end
end)
		
				Copy Code
			
				Light Theme

TeleportToPlaceInstance

Spawn name

Teleport data

Loading screen

Teleport failure

Studio limitation

See also

Parameters

placeId

instanceId

player

spawnName

teleportData

customLoadingScreen

Returns

void

Code Samples

Following Another Player