PcoWSkbVqDnWTu_dm2ix
The Developer Hub is now deprecated and information on this page may no longer be accurate. Instead, you should go to our new and improved documentation. You can also learn more about the future of documentation.
Collapse Sidebar

TeleportAsync

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

All forms of player teleportation are consolidated into this single function, which is used to:

  • Teleport players to a different place
  • Teleport players to a specific server
  • Teleport players to a reserved server

Potential Errors

This is a list of potential reasons a teleport may fail, ranging from invalid teleports to network issues.

Error Description
Invalid placeId The provided placeId is below 0.
Players empty The provided list of players to teleport is empty.
List of players instances is incorrect Any of the provided players is not a Player object.
TeleportOptions not of correct type The provided teleportOption is not a TeleportOptions object.
TeleportAsync called from Client The client called TeleportAsync, which can only be called from the server.
Incompatible Parameters Conflicting teleport options were used and TeleportService doesn't know where to send the player:
  • ReservedServerAccessCode + ServerInstanceId
  • ShouldReserveServer + ServerInstanceId
  • ShouldReserveServer + ReservedServerAccessCode

See also

For an in-depth guide on teleporting players and properly handling teleport failures, see the Teleporting Between Places article.

Parameters

Name Type Default Description

The place ID the player(s) should be teleported to.

An array of the player(s) to teleport.

nil

An optional TeleportOptions object containing additional arguments to the TeleportAsync call.

Returns

Return Type Summary

A TeleportAsyncResult object that provides information about the final teleport destination.


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)