TeleportAsync
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.
For thread safety, this property is not safe to read in an unsynchronized thread.
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
- Groups of players can only be teleported within a single experience.
- No more than 50 players can be teleported with a single
TeleportService/TeleportAsynccall.
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:
|
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 |
Returns
| Return Type | Summary |
|---|---|
|
A |
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)