공개 서버 간의 플레이어 텔레포트 외에도, TeleportService는 특정 플레이어로 제한된 개인 서버로의 텔레포트를 지원합니다. 텔레포트할 수 있는 개인 서버의 두 가지 종류가 있습니다:
- 예약된 서버: 개발자가 생성한 서버로, 개발자가 제공한 ID를 통해 접근합니다. 개인 매치, 협동 세션 또는 누가 참여하는지를 제어하는 모든 시나리오에 유용합니다.
- VIP 서버: 플레이어가 구매한 개인 서버입니다. TeleportOptions.VipServerId를 사용하여 플레이어가 구매한 VIP 서버로 라우팅합니다.
ReservedServerId와 VipServerId는 TeleportOptions 클래스의 속성입니다. 한 번에 하나의 개인 서버 라우팅 필드만 설정할 수 있습니다. 모든 텔레포트 옵션에 대한 개요는 장소 간 텔레포트를 참조하세요.
예약된 서버로 텔레포트하기
예약된 서버는 필요에 따라 생성됩니다: 새로운 ReservedServerId를 사용한 첫 번째 텔레포트가 서버를 생성하고, 동일한 ID를 재사용하면 후속 텔레포트가 동일한 서버로 라우팅됩니다. HttpService:GenerateGUID(false)를 사용하여 ID를 생성합니다:
local HttpService = game:GetService("HttpService")
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")
local TARGET_PLACE_ID = 12345678901234
-- 텔레포트할 사용자 (예: Players:GetPlayers() 또는 매치메이킹 그룹에서)
local player1, player2 = Players:GetPlayers()[1], Players:GetPlayers()[2]
-- 예약된 서버를 위한 고유 ID 생성
local reservedServerId = HttpService:GenerateGUID(false)
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerId = reservedServerId
-- 첫 번째 텔레포트가 서버를 생성합니다
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player1, player2}, teleportOptions)예약된 서버 ID 재사용하기
다른 플레이어가 나중에 동일한 예약된 서버에 참여할 수 있도록, DataStoreService 데이터 저장소에 예약된 서버 ID를 지속시켜 세션과 서버를 넘어 생존하도록 합니다.
예약된 서버를 생성하는 서버에서 첫 번째 텔레포트를 위한 ID를 생성한 후, 세션을 식별하는 키(예: 로비 ID 또는 파티 ID)로 저장합니다:
local DataStoreService = game:GetService("DataStoreService")
local HttpService = game:GetService("HttpService")
local TeleportService = game:GetService("TeleportService")
local reservedServersStore = DataStoreService:GetDataStore("ReservedServers")
-- 서버 간 공유 세션을 식별하는 키
local sessionKey = "lobby-123"
-- 도착지에서 예약된 서버를 생성하기 위해 새로운 ID 생성
local reservedServerId = HttpService:GenerateGUID(false)
reservedServersStore:SetAsync(sessionKey, reservedServerId)
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerId = reservedServerId
TeleportService:TeleportAsync(TARGET_PLACE_ID, { player }, teleportOptions)동일한 예약된 서버로 플레이어를 보내야 하는 다른 서버에서는 동일한 세션 키로 ID를 조회하고 이를 텔레포트의 TeleportOptions.ReservedServerId로 설정합니다:
local DataStoreService = game:GetService("DataStoreService")
local TeleportService = game:GetService("TeleportService")
local reservedServersStore = DataStoreService:GetDataStore("ReservedServers")
local sessionKey = "lobby-123"
local existingId = reservedServersStore:GetAsync(sessionKey)
if existingId then
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerId = existingId
TeleportService:TeleportAsync(TARGET_PLACE_ID, { player }, teleportOptions)
endVIP 서버에서, VIP 서버 ID를 데이터 저장소 없이 도착지 서버에서 사용할 수 있도록 하려면, TeleportOptions:SetTeleportData()를 사용하여 각 플레이어에 첨부합니다:
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.VipServerId = game.PrivateServerId
teleportOptions:SetTeleportData({ vipServerId = game.PrivateServerId })
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)도착 시, 플레이어의 참여 데이터에서 이를 읽어옵니다. 자세한 내용은 텔레포트와 함께 사용자 데이터 전송을 참조하세요.
도착 시 예약된 서버 식별하기
도착지 서버에서 현재 서버가 예약된 서버인지 확인합니다:
local isReserved = game.PrivateServerId ~= "" and game.PrivateServerOwnerId == 0DataModel.PrivateServerId는 제공한 ReservedServerId와 일치하며, 해당 예약된 서버에 대한 모든 서버 인스턴스에서 일정하게 유지됩니다. DataModel.JobId는 실행 중인 인스턴스마다 고유하며 서버가 재시작될 때 변경됩니다.
VIP 서버로 텔레포트하기
VIP 서버는 플레이어가 게임 페이지에서 구매할 수 있는 개인 서버입니다. 플레이어를 VIP 서버로 텔레포트하려면, TeleportOptions.VipServerId를 대상 VIP 서버의 DataModel.PrivateServerId로 설정합니다.
local TeleportService = game:GetService("TeleportService")
local TARGET_PLACE_ID = 12345678901234
-- 도착지 VIP 서버의 PrivateServerId, 예를 들어 플레이어의 텔레포트 데이터에 포함되거나 데이터 저장소에서 읽어온 것
local vipServerId = player:GetJoinData().TeleportData.vipServerId
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.VipServerId = vipServerId
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)TeleportOptions.VipServerId는 TeleportOptions.ReservedServerId와 구별됩니다. 개발자가 생성한 예약된 서버에는 ReservedServerId를 사용하고, 플레이어가 구매한 VIP 서버에는 VipServerId를 사용합니다.
VIP 서버 ID는 VIP 서버를 소유한 경험에 국한됩니다: 해당 경험의 모든 장소의 장소 ID와 함께 사용할 수 있지만, 다른 경험의 장소 ID와는 사용할 수 없습니다.
라우팅 필드를 설정하지 않으면 엔진이 목적지 서버를 선택합니다. 개인 서버 라우팅 필드가 설정되지 않은 텔레포트는 공개 서버에 도착하거나, 플레이어가 최근에 해당 경험의 VIP 서버에 참여한 경우 그 VIP 서버에 도착할 수 있습니다.
이 패턴의 일반적인 사용 사례는 예약된 서버에서 플레이어를 경험의 루트 장소의 VIP 서버로 되돌리는 것입니다. 예약된 서버의 game.PrivateServerId는 자신의 예약 ID이므로 원래 VIP 서버의 ID가 아닙니다. VIP 서버의 ID를 예약된 서버로 가져가려면, 예를 들어 아웃바운드 텔레포트의 teleportData에 전달하거나 예약된 서버 ID 재사용하기에서 보여준 것처럼 데이터 저장소에 지속시킵니다. 그런 다음 반환 텔레포트의 TeleportOptions.VipServerId로 설정합니다.
모든 텔레포트에서 동일한 TeleportOptions.VipServerId를 설정하여 플레이어가 게임 플레이 전반에 걸쳐 동일한 VIP 서버에 머물도록 합니다.
서버 ID 저장 및 공유하기
TeleportAsyncResult 객체는 TeleportService:TeleportAsync()에 의해 반환되며, 목적지에 대한 정보를 포함합니다:
- TeleportAsyncResult.PrivateServerId - 목적지 서버의 개인 서버 ID. 도착지에서 DataModel.PrivateServerId와 일치합니다.
- TeleportAsyncResult.ReservedServerAccessCode - 레거시 액세스 코드 텔레포트에 대해서만 채워집니다. ReservedServerId 또는 VipServerId를 사용할 때는 채워지지 않습니다.
local result = TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)
if result then
print("목적지 PrivateServerId:", result.PrivateServerId)
end레거시 액세스 코드에서 마이그레이션하기
게임이 더 이상 사용되지 않는 TeleportOptions.ReservedServerAccessCode 또는 TeleportOptions.ShouldReserveServer를 사용하는 경우, 액세스 코드 흐름을 GUID 기반 흐름으로 교체하여 ReservedServerId로 마이그레이션합니다:
- 교체 ReserveServerAsync() 및 ReservedServerAccessCode를 HttpService:GenerateGUID(false) 및 ReservedServerId로 교체합니다.
- 저장 생성된 GUID를 저장하여 동일한 서버로의 후속 텔레포트에 재사용할 수 있도록 합니다.
- 업데이트 모든 TeleportOptions 사용을 ReservedServerAccessCode 또는 ShouldReserveServer 대신 ReservedServerId를 설정하도록 업데이트합니다.
이전 (더 이상 사용되지 않음)
-- 더 이상 사용되지 않음: ReserveServerAsync + ReservedServerAccessCode
local accessCode, privateServerId = TeleportService:ReserveServerAsync(TARGET_PLACE_ID)
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerAccessCode = accessCode
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)이후 (현재)
local HttpService = game:GetService("HttpService")
local TeleportService = game:GetService("TeleportService")
-- 현재: GenerateGUID + ReservedServerId
local reservedServerId = HttpService:GenerateGUID(false)
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerId = reservedServerId
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)레거시 ReserveServerAsync() 및 ReservedServerAccessCode는 하위 호환성을 위해 여전히 사용 가능하지만, 새로운 작업에는 권장되지 않습니다. ReserveServerAsync()는 실제로 서버를 미리 예약하지 않고 단순히 무작위 GUID를 생성합니다. 액세스 코드로 생성된 기존 예약 서버는 계속 작동합니다.
실패한 텔레포트 처리하기
개인 서버로의 텔레포트는 네트워크 호출처럼 실패할 수 있습니다. 이를 pcall로 감싸고 필요에 따라 재시도합니다. 텔레포트가 시작되었지만 마지막 순간에 실패하면, TeleportService.TeleportInitFailed가 원래의 TeleportOptions와 함께 발생하므로 동일한 목적지로 재시도할 수 있습니다.
전체 재시도 구현에 대한 내용은 주요 텔레포트 가이드의 실패한 텔레포트 처리하기를 참조하세요.
엔진이 일반 텔레포트를 VIP 서버로 라우팅할 때, VIP 특정 참여 실패(예: 서버가 가득 찼거나 플러드됨)는 TeleportService.TeleportInitFailed를 발생시키는 대신 공개 참여로 대체됩니다. 명시적인 TeleportOptions.VipServerId가 설정된 텔레포트만 이러한 실패를 재시도 핸들러에 전달합니다.
모범 사례
- 서버에서 ID 생성하기. 항상 서버 Script에서 HttpService:GenerateGUID(false)를 호출하여 클라이언트가 예약된 서버 ID를 예측하거나 제어하지 못하도록 합니다.
- 예약된 서버 ID 지속하기. 플레이어가 세션 간 동일한 예약된 서버에 재참여해야 하는 경우 GUID를 데이터 저장소에 저장합니다.
- 올바른 필드 사용하기. 개발자가 생성한 예약된 서버에는 ReservedServerId를 사용하고, 플레이어가 구매한 VIP 서버에는 VipServerId를 사용합니다. 동일한 TeleportOptions 인스턴스에서 두 개를 모두 설정하지 마세요.
- 라우팅 필드를 혼합하지 마세요. 한 번에 ReservedServerId, VipServerId 또는 ServerInstanceId 중 하나만 설정할 수 있습니다. 둘 이상을 설정하면 오류가 발생합니다.