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.
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
When teleporting multiple players, they can only be teleported to a place within the same game universe. This function can not teleport more than 50 players in a single party.
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 |
|
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 |
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)