> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/teleportservice.md).

# 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)

-- QR 퍼블리시 환경에서는 AccessCode 값이 빈 문자열("")로 반환될 수 있습니다.
if not success or errorOrAccessCode == nil 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 %}