# 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

```lua
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

```lua
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

```lua
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

{% content-ref url="/pages/622TMnOQKflywQnvq8hQ" %}
[Place & Teleport](/manual/studio-manual/game-development/place-and-teleport.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overdare.com/development/api-reference/classes/teleportservice.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.