TeleportPartyAsync

Yields

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts.

Function of:

TeleportService

Description:

This function teleports a group of Player|Players to the same server instance in the given place. It returns the DataModel/JobId of the server instance the players were teleported to.

This function can only be called from the server.

You may only use this function to teleport to a place in the same game. This function can not teleport more than 50 Player|Players in a single party.

Currently this function may not work reliably when teleporting Player|Players to the same place they are currently in.

Teleport data

A teleportData parameter can be specified. This is data the clients 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).

Loading screen

A customLoadingScreen argument can be specified. This is a ScreenGui that is copied (without scripts) into the CoreGui of the destination place. It can be retrieved at the destination place using TeleportService/GetArrivingTeleportGui and will not be used if the destination place is in a different game.

You are advised to instead set the loading screen on the client using TeleportService/SetTeleportGui. The loading ScreenGui should also be parented to the Player|Players' PlayerGui|PlayerGuis a few seconds before the teleport to ensure a smooth transition using a RemoteEvent. For an example of this see TeleportService/SetTeleportGui|SetTeleportGui.

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 players	Type Objects	Default	Summary An array containing the `Player\|Players` to teleport
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 string	Summary The `DataModel/JobId` of the server instance the `Player\|Players` were teleported to

Code Samples

Teleport all players in the server

This code sample is an example of how TeleportService/TeleportPartyAsync can be used to teleport a group of Player|Players.

In this case, all Player|Players will be teleported to the specified placeId as a party. The DataModel/JobId of the destination server is then printed.

				
					Teleport all players in the server
				
					Expected Output
				
					Expand
					
			local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")

local placeId = 0 -- replace
local playerList = Players:GetPlayers()

local success, result = pcall(function()
    return TeleportService:TeleportPartyAsync(placeId, playerList)
end)

if success then
    local jobId = result
    print("Players teleported to "..jobId)
else
    warn(result)
end
		
				Copy Code
			
				Light Theme

TeleportPartyAsync

Teleport data

Loading screen

Teleport failure

Studio limitation

See also

Parameters

placeId

players

teleportData

customLoadingScreen

Returns

string

Code Samples

Teleport all players in the server