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

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

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

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