# TeleportService

TeleportService : `Instance`

## Overview

텔레포트 서비스는 플레이어를 현재 월드와 연결된 다른 플레이스로 이동시키기 위한 기능을 제공하는 시스템입니다. 주로 멀티플레이 게임 환경에서 맵 전환, 서버 이동, 던전 입장, 매치메이킹, 개인 공간(Private Instance) 생성 등의 기능을 구현하는 데 사용됩니다.

텔레포트 서비스는 단순한 위치 이동 기능을 넘어, 플레이어 상태 유지, 서버 간 데이터 전달, 세션 관리 등을 포함하는 핵심 네트워크 시스템으로 동작합니다. 

## Properties

## Methods

### ReserveServerAsync

지정한 Place에 대해 새로운 Private(Reserved) 서버를 미리 예약하고, 해당 서버에 입장할 때 사용할 수 있는 AccessCode를 반환받는 비동기 메서드입니다. 

발급된 AccessCode는 이후 `TeleportAsync` 호출 시 `TeleportOptions.ReservedServerAccessCode`로 전달하여 플레이어들을 같은 예약 서버로 합류시키는 데 사용할 수 있습니다.

이 메서드는 서버에서만 호출할 수 있으며, 퍼블리시된 환경에서만 동작합니다.

#### Parameters

| `number` InPlaceId | 예약 서버를 생성할 대상 Place의 ID입니다. |
| ------------------ | --------------------------- |

#### Return

| `string` AccessCode | 예약 서버의 접근 코드입니다. |
| ------------------- | ---------------- |

#### Code Samples

```lua
local TeleportService = game:GetService("TeleportService")

local targetPlaceId = 1234 -- 월드에 연결된 Place의 Id

-- 전용 서버 생성
local success, errorOrAccessCode = pcall(function()
    return TeleportService:ReserveServerAsync(targetPlaceId)
end)

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

-- TeleportOptions 설정
local options = Instance.new("TeleportOptions")	
options.ReservedServerAccessCode = errorOrAccessCode -- 예약 서버 접근 코드
options.ShouldReserveServer = false                  -- 새로운 예약 서버 생성 여부 (ReservedServerAccessCode 사용시 false여야 합니다.)

-- 텔레포트 실행
local success, errorOrResult = pcall(function()
    local players = { player } -- 텔레포트할 플레이어 목록
		
    local teleportResult = TeleportService:TeleportAsync(targetPlaceId, players, options)     
    return teleportResult
end)

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

### TeleportAsync

지정한 Place로 한 명 또는 여러 명의 플레이어를 이동시키는 비동기 메서드입니다. 

`InOptions`에 전달된 값에 따라 동작이 결정되며, 옵션을 지정하지 않으면 해당 Place의 기존 Public 서버에 합류하거나 없을 경우 새로 생성하여 입장합니다. 

`TeleportOptions.ServerInstanceId`를 지정하면 해당 SessionID의 Public 서버에 합류하고, `TeleportOptions.ReservedServerAccessCode`를 지정하면 `ReserveServerAsync`로 발급받은 Private 서버에 합류합니다. 두 값을 동시에 지정하면 에러가 발생합니다.

한 번에 전달 가능한 플레이어 수는 1\~50명이며, 텔레포트 시작에 실패하면 각 플레이어 대상으로 `TeleportInitFailed` 이벤트가 발생합니다.

이 메서드는 서버에서만 호출할 수 있으며, 퍼블리시된 환경에서만 동작합니다.

#### Parameters

| `number` InPlaceId          | 플레이어들을 이동시킬 대상 Place의 ID입니다.                                                                 |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `Array` InPlayers           | 텔레포트할 `Player` 객체들의 배열입니다. 1명 이상 50명 이하여야 합니다.                                               |
| `TeleportOptions` InOptions | 텔레포트 동작을 제어하는 옵션 객체입니다. 합류할 서버의 SessionID나 예약 서버 AccessCode 등을 지정할 수 있으며, 생략하면 기본 옵션이 사용됩니다. |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local TeleportService = game:GetService("TeleportService")

-- 텔레포트 실행
local success, errorOrResult = pcall(function()
    local targetPlaceId = 1234 -- 월드에 연결된 Place의 Id
    local players = { player } -- 텔레포트할 플레이어 목록
		
    local teleportResult = TeleportService:TeleportAsync(targetPlaceId, players)     
    return teleportResult
end)
```

## Events

### TeleportInitFailed

`TeleportAsync` 요청이 전송된 뒤 텔레포트 시작 단계에서 실패하여 플레이어가 현재 서버에 그대로 남게 되었을 때 발생하는 이벤트입니다. 

실패 사유(`TeleportResultType`)와 에러 메시지, 대상 Place의 ID, 사용된 `TeleportOptions`가 함께 전달되며, 텔레포트에 실패한 각 플레이어마다 개별적으로 발생합니다.

#### Parameters

| `Player` Player                   | 텔레포트에 실패한 플레이어입니다.                                                |
| --------------------------------- | ----------------------------------------------------------------- |
| `TeleportResult` TeleportResult   | 텔레포트 실패 원인을 나타내는 결과 값입니다. 실패 유형에 따라 다양한 상태 값을 반환할 수 있습니다.         |
| `string` ErrorMessage             | 텔레포트 실패 시 반환되는 오류 메시지입니다. 실패 원인에 대한 추가 정보를 포함할 수 있습니다.            |
| `number` PlaceId                  | 플레이어가 이동하려고 시도한 대상 플레이스의 ID입니다.                                   |
| `TeleportOptions` TeleportOptions | 텔레포트 요청 시 사용된 옵션 정보입니다. 예약 서버, 전달 데이터, 인스턴스 설정 등의 정보를 포함할 수 있습니다. |

#### 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/IJpK8Xy2OodL1R6Kcf7g" %}
[Place & Teleport](/korean/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/korean/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.