all-encompassing method to teleport a player or group of players from one server to another "> PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar

TeleportAsync

This function serves as the all-encompassing method to teleport a player or group of players from one server to another.

Previous iterations of the TeleportService relied on several different functions for each scenario. This function combines the previous functions into a single method.

There are several scenarios where this may be used, including:

  • 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

Errors

The errors we have listed here are mainly input validation, there could also be unexpected runtime errors (for example an http request error) that could cause the API to fail.

Error Description
Invalid placeId placeId below 0
Players empty If the size of list of players is less than 1
List of players instances is incorrect Any member of the players list is not of type Player
TeleportOptions not of correct type teleportOption is not of type TeleportOptions
TeleportAsync called from Client Can only be called from the server
Incompatible Parameters
  • ReservedServerAccessCode + ServerInstanceId
  • ShouldReserveServer + ServerInstanceId
  • ShouldReserveServer + ReservedServerAccessCode

See also

For more information on how to teleport players between servers, take a look at the Telporting Between Places article.

Parameters

Name Type Default Description

The placeId the player(s) should be teleported to

An array containing the player(s) to teleport

nil

An instance that contains optional arguments to the TeleportAsync call

Returns

Return Type Summary

An instance of TeleportAsyncResult that provides information on the Teleport


Code Samples


Teleporting To a Reserved Server

The example below demonstrates how to use TeleportService/TeleportAsync to teleport a player to a reserved server and then save the TeleportAsyncResult/ReservedServerAccessCode to a datastore for later use to teleport other players to the same server. Saving off the access code is important because players cannot join reserved servers via the TeleportService without the reserved server access code.

Developers must save the reserved access code via GlobalDataStore|DataStores or some other location in order to keep it. For example, developers can create a DataStore for access codes and then save the reserved server access code as the value and the PrivateServerId as the key. By saving the access code to a datastore using the TeleportAsyncResult/PrivateServerId as the key, developers can get the server access code from within the reserved server and send it to other servers using the MessagingService.

For example, the MessagingService can be used as a part of an invitation system that allows players on a reserved server to invite players on different servers to their server. The reserved server access code can be sent using this service to be handled by a subscribed server containing the invited player. The invited player’s server can then handle the message and teleport the invited player using a TeleportAsync specifying the access code through the TeleportOptions/ReservedServerAccessCode property of the TeleportOptions.

local DataStoreService = game:GetService("DataStoreService")
local TeleportService = game:GetService("TeleportService")

local ServerAccessCodes = DataStoreService:GetDataStore("ReservedServerAccessCodes")

-- Teleport the player to a reserved server
local teleportOptions = Instance.new(“TeleportOptions”)
teleportOptions.ShouldReserveServer = true
local teleportResult = TeleportService:TeleportAsync(game.PlaceId, {player}, teleportOptions)

-- Save the ReservedServerAccessCode from the TeleportResult instance
ServerAccessCodes:SetAsync(teleportResult.PrivateServerId, teleportResult.ReservedServerAccessCode)

-- To retrieve the access code (can only be done from in the reserved server)
local accessCode = game.PrivateServerId ~= "" and ServerAccessCodes:GetAsync(game.PrivateServerId)