TeleportService

TeleportService : Instance

Overview

The Teleport Service is a system that provides functionality for transferring players to other places connected to the current world. It is primarily used in multiplayer game environments to implement features such as map transitions, server transfers, dungeon entry, matchmaking, and private instance creation.

Beyond simple positional movement, the Teleport Service operates as a core networking system that manages player state persistence, cross-server data transfer, and session management.

Properties

Methods

ReserveServerAsync

An asynchronous method that pre-reserves a new Private (Reserved) server for the specified Place and returns an AccessCode that can be used to enter that server.

The issued AccessCode can later be passed as TeleportOptions.ReservedServerAccessCode when calling TeleportAsync to bring players together into the same reserved server.

This method can only be called on the server and only works in published environments.

Parameters

number InPlaceId	The ID of the target Place for which the reserved server will be created.

Return

string AccessCode	Access code for the reserved server.

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)

TeleportAsync

An asynchronous method that teleports one or more players to the specified Place.

Its behavior is determined by the values passed in InOptions; if no options are provided, the players join the existing Public server for that Place, or a new one is created and entered if none exists.

Specifying TeleportOptions.ServerInstanceId makes the players join the Public server with that SessionID, while specifying TeleportOptions.ReservedServerAccessCode makes them join a Private server previously issued by ReserveServerAsync. Specifying both values at the same time raises a error.

Between 1 and 50 players can be passed at once, and if starting the teleport fails, a TeleportInitFailed event is fired for each affected player.

This method can only be called on the server and only works in published environments.

Parameters

number InPlaceId	The ID of the target Place to teleport the players to.
Array InPlayers	An array of Player objects to teleport. Must contain between 1 and 50 players.
TeleportOptions InOptions	An options object that controls teleport behavior. It can specify values such as the SessionID of the server to join or the reserved server AccessCode; if omitted, default options are used.

Return

void

Code Samples

local TeleportService = game:GetService("TeleportService")

-- 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)     
    return teleportResult
end)

Events

TeleportInitFailed

An event that fires when, after a TeleportAsync request is sent, the teleport fails during its initialization stage and the player remains on the current server.

The failure reason (TeleportResultType), an error message, the ID of the target Place, and the TeleportOptions used are delivered together, and the event fires individually for each player whose teleport failed.

Parameters

Player Player	The player whose teleport request failed.
TeleportResult TeleportResult	The result value indicating the reason for the teleport failure. Different status values may be returned depending on the failure type.
string ErrorMessage	The error message returned when the teleport fails. It may contain additional information about the failure.
number PlaceId	The ID of the destination place the player attempted to teleport to.
TeleportOptions TeleportOptions	The options used for the teleport request. This may include reserved server information, teleport data, and instance settings.

Code Samples

local TeleportService = game:GetService("TeleportService")

local function OnTeleportInitFailed(player, teleportResult, errorMessage, placeId, teleportOptions)
    print("[TeleportInitFailed] playerName : ", player.Name)		  
    print("[TeleportInitFailed] Result : ", teleportResult)
    print("[TeleportInitFailed] Error : ", errorMessage)
    print("[TeleportInitFailed] Target Place : ", placeId)       
end
TeleportService.TeleportInitFailed:Connect(OnTeleportInitFailed)	

See also

Place & Teleport