TeleportOptions

TeleportOptions : Instance

Overview

An options instance passed to TeleportService:TeleportAsync() to specify the detailed behavior of where a player should be teleported.

It allows you to set an access code for a reserved server, designate a specific server instance ID, or indicate whether a new server should be reserved. Some of these options cannot be combined with each other, so refer to the property descriptions below and use only one approach at a time.

Properties

ReservedServerAccessCode

string

Specifies the access code that identifies the reserved server to teleport to.

By setting this property to the access code of a server reserved in advance through TeleportService:ReserveServer() or a similar API, you can teleport players to that server.

This property cannot be specified together with ServerInstanceId, and it must be empty when ShouldReserveServer is true.

Code Samples

local TeleportService = game:GetService("TeleportService")

local targetPlaceId = 1234 -- PlaceId of a Place connected to the current World

-- Create a reserved server
local success, errorOrAccessCode = pcall(function()
    return TeleportService:ReserveServerAsync(targetPlaceId)
end)

if not success or errorOrAccessCode == nil or errorOrAccessCode == "" then
    return
end

-- Configure TeleportOptions
local options = Instance.new("TeleportOptions")	
options.ReservedServerAccessCode = errorOrAccessCode -- Reserved server access code
options.ShouldReserveServer = false                  -- Whether to create a new reserved server session (must be false when using ReservedServerAccessCode)

-- Execute teleport
local success, errorOrResult = pcall(function()
    local players = { player } -- Players to teleport
		
    local teleportResult = TeleportService:TeleportAsync(targetPlaceId, players, options)     
    return teleportResult
end)

print("TeleportAsyncResult.ReservedServerAccessCode : ", errorOrResult.ReservedServerAccessCode)

ServerInstanceId

string

Specifies the ID of the target server instance to which players will be teleported. Set the server instance ID when you want to send players to a specific server instance that is already running.

This property cannot be specified together with ReservedServerAccessCode, and it must be empty when ShouldReserveServer is true.

Code Samples

local TeleportService = game:GetService("TeleportService")
local DataStoreService = game:GetService("DataStoreService") 
local SessionStore = DataStoreService:GetDataStore("PlayerPrevSessionId")

-- Load the previously saved session Id
local jobId = nil
local success, errorOrLoadValue = pcall(function()
    return SessionStore:GetAsync(player.UserId)
end) 

if not success or errorOrLoadValue == nil then
    return
end
jobId = errorOrLoadValue 

-- Configure TeleportOptions
local options = Instance.new("TeleportOptions")	
options.ServerInstanceId = jobId    -- Join a specific public server (pass a game.JobId value)
options.ShouldReserveServer = false -- Whether to create a new reserved server session (must be false when using ServerInstanceId)

-- Execute teleport
local success, errorOrResult = pcall(function()
    local targetPlaceId = 1234 -- PlaceId of a Place connected to the current World
    local players = { player } -- Players to teleport
		
    local teleportResult = TeleportService:TeleportAsync(targetPlaceId, players, options)     
    return teleportResult
end)

ShouldReserveServer

boolean

Specifies whether a new server should be reserved as part of the teleport request and players sent to that server. When set to true, a new server is reserved together with the teleport request, and in that case both ReservedServerAccessCode and ServerInstanceId must be empty.

The default value is false.

Code Samples

local TeleportService = game:GetService("TeleportService")

-- Configure TeleportOptions
local options = Instance.new("TeleportOptions")	
options.ShouldReserveServer = true -- Whether to create a new reserved server session

-- Execute teleport
local success, errorOrResult = pcall(function()
    local targetPlaceId = 1234 -- PlaceId of a Place connected to the current World
    local players = { player } -- Players to teleport
		
    local teleportResult = TeleportService:TeleportAsync(targetPlaceId, players, options)     
    return teleportResult
end)

Methods

Events

See also

Place & Teleport