많은 게임은 여러 장소로 나뉘어 있습니다. 예를 들어, 마법의 세계에는 마을, 성, 던전, 광활한 숲이 있습니다. TeleportService를 사용하여 사용자를 장소 간에, 다른 서버로, 또는 다른 게임으로 텔레포트할 수 있습니다.
플레이어 텔레포트
플레이어를 텔레포트하려면 TeleportService:TeleportAsync()를 사용합니다. 이 메서드는 세 개의 매개변수를 받습니다:
- 사용자가 텔레포트할 PlaceId.
- 텔레포트할 Player 인스턴스를 포함하는 배열.
- TeleportAsync() 호출에 대한 사용자 정의 속성을 포함하는 선택적 TeleportOptions 인스턴스.
local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local TARGET_PLACE_ID = 12345678901234 -- 자신의 ID로 교체
local playerToTeleport = Players:GetPlayers()[1] -- 게임에서 첫 번째 사용자 가져오기
TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})텔레포트할 적절한 플레이어를 얻으려면 BasePart.Touched 또는 ProximityPrompt.Triggered 이벤트를 사용하여 개별 Player를 얻을 수 있습니다. 그런 다음 플레이어가 팀(Player.Team) 또는 파티(Player.PartyId)의 일원인지 확인할 수 있습니다. 마지막으로, 전체 그룹을 텔레포트하려면 Team:GetPlayers() 또는 SocialService:GetPlayersByPartyId()를 사용할 수 있습니다.
안전한 텔레포트 구성
세 가지 설정이 텔레포트 보안을 처리합니다.
| 설정 | 설명 |
|---|---|
| (크리에이터 대시보드) 청중 > 접근 설정 > 장소에 대한 접근 제어 | 플레이어가 게임의 모든 장소에 참여할 수 있는지, 아니면 먼저 시작 장소에 참여해야 하는지를 제어합니다. |
| (크리에이터 대시보드) 장소 > 접근 > 직접 접근 제어 | 비시작 장소에 대한 게임 수준의 장소에 대한 접근 제어 설정을 재정의합니다. |
| (스튜디오) 파일 > 경험 설정 > 보안 > 타사 텔레포트 허용 | 소유하지 않은 게임으로부터의 텔레포트를 제어합니다. 이 설정을 비활성화한 상태에서도 소유한 게시된 게임 간에 플레이어를 텔레포트할 수 있습니다. |
장소에 대한 접근 제어는 플레이어가 게임 내부로 텔레포트하는 것을 제어하며, 텔레포트 기반의 악용을 방지하는 데 가장 중요한 설정입니다.

완전히 열림을 선택하면, 플레이어는 어떤 게임에서든 텔레포트를 통해 게임의 모든 장소에 참여할 수 있습니다. 여기에는 딥 링크, 게임 초대, 친구 참여 등이 포함됩니다.
이는 게임에 여러 장소가 있고 친구들이 어떤 장소에 있든 쉽게 서로 참여할 수 있도록 하려는 경우에 좋은 선택입니다. 이 옵션을 선택하지 않으면, 비시작 장소에서 친구에게 참여하려는 플레이어는 대신 게임의 시작 장소에 참여하게 됩니다.
같은 우주로 제한을 선택하면, 플레이어는 게임 내에서 텔레포트를 통해서만 비시작 장소에 참여할 수 있습니다. 이 설정은 클라이언트 및 서버에서 시작된 텔레포트를 모두 허용합니다.
이는 안전한 텔레포트로 마이그레이션하고 싶지 않은 레거시 게임이 있는 경우에 좋은 선택입니다.
우주 내에서만 안전하게를 선택하면, 플레이어는 이 게임 내에서 서버에서 시작된 텔레포트를 통해서만 비시작 장소에 참여할 수 있습니다.
이는 플레이어가 특정 지역에 접근하기 전에 엄격한 진행 시스템이 있는 게임에 좋은 선택입니다. 또한 플레이어가 접근해서는 안 되는 테스트 장소가 있거나 전용 서버만 사용하는 장소에 좋은 선택입니다.
안전한 텔레포트로 마이그레이션
클라이언트 측 텔레포트를 사용하는 기존 게임이 있고 서버에서 시작된 텔레포트를 요구하려는 경우, 목표는 모든 텔레포트 로직을 클라이언트 스크립트에서 서버 스크립트로 이동하는 것입니다:
- Teleport()를 호출하는 모든 클라이언트 스크립트를 찾습니다.
- 이러한 호출을 원격 이벤트를 발생시키도록 변경합니다. 또는 ProximityPrompts, ClickDetectors, 또는 단순히 BasePart.Touched 이벤트를 사용하도록 변경할 수 있습니다.
- TeleportAsync()를 사용하여 서버 스크립트에서 텔레포트를 다시 구현합니다.
사용자 정의 텔레포트 화면 만들기
사용자가 텔레포트를 트리거하면, 새로운 장소가 로드될 때까지 표준 Roblox 로딩 화면이 표시됩니다. 원한다면, 클라이언트에서 TeleportService:SetTeleportGui()를 호출하여 사용자 정의 텔레포트 화면을 추가할 수 있습니다.
다음 예제는 ReplicatedStorage에서 사용자 정의된 ScreenGui를 설정합니다. ScreenGui 내의 모든 스크립트는 실행되지 않습니다.
local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local teleportGui = ReplicatedStorage.TeleportGui
TeleportService:SetTeleportGui(teleportGui)텔레포트 옵션 사용자 정의
특정 서버로 사용자를 텔레포트하거나 텔레포트와 함께 사용자 데이터를 전송하는 등 텔레포트를 사용자 정의할 수 있습니다. TeleportOptions 인스턴스를 설정하고 이를 TeleportService:TeleportAsync() 메서드에 전달합니다.
특정 서버로 텔레포트
사용자를 특정 서버로 텔레포트하려면, TeleportOptions를 사용하여 대상 서버를 설정하고 이를 TeleportAsync() 메서드에 전달합니다. 서버를 지정하지 않으면, 사용자는 공개 서버로 텔레포트됩니다. 목록의 첫 번째 사용자의 정보가 매칭에 사용됩니다.
특정 공개 서버로 사용자를 텔레포트하려면, 유효한 인스턴스 ID인 TeleportOptions.ServerInstanceId 속성을 설정합니다.
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ServerInstanceId = targetServerId특정 예약 서버로 사용자를 텔레포트하려면, 예약 서버에 들어가기 위한 고유 코드인 유효한 TeleportOptions.ReservedServerAccessCode를 설정합니다.
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerAccessCode = reservedServerCode새로운 예약 서버로 사용자를 텔레포트하려면, TeleportOptions.ShouldReserveServer를 true로 설정합니다.
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ShouldReserveServer = true텔레포트와 함께 사용자 데이터 전송
장소 간에 사용자를 텔레포트하면 해당 사용자와 관련된 모든 로컬 데이터가 삭제됩니다. 장소 간 데이터 지속성을 처리하기 위해 다음 접근 방식을 사용할 수 있습니다:
장소 간에 기본 비안전 데이터를 전송하려면, TeleportOptions:SetTeleportData()를 호출한 후 이를 TeleportAsync()에 전달합니다. 이 방법으로 안전한 데이터를 전달하지 마세요; 데이터는 클라이언트에 표시되며 암호화되지 않습니다.
local teleportData = {
randomNumber = RNG:NextInteger(1, 100),
}
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions:SetTeleportData(teleportData)사용자가 텔레포트 후 새로운 장소에 도착할 때 모든 데이터를 검색하려면, Player:GetJoinData() 함수를 사용하여 TeleportData 키가 있는 사전을 반환합니다.
local Players = game:GetService("Players")
local function onPlayerAdded(player)
local joinData = player:GetJoinData()
local teleportData = joinData.TeleportData
local randomNumber = teleportData.randomNumber
print(player.Name .. "가 " .. randomNumber .. " 번호로 참여했습니다.")
end
Players.PlayerAdded:Connect(onPlayerAdded)클라이언트에서 텔레포트 데이터만 검색하려면 TeleportService:GetLocalPlayerTeleportData()를 사용할 수 있습니다.
실패한 텔레포트 처리
네트워크 요청이 포함된 모든 API 호출과 마찬가지로, 텔레포트는 실패할 수 있으며 오류를 발생시킬 수 있습니다. 이를 보호된 호출(pcall())로 감싸야 합니다. 일부 실패는 재시도가 유리하며, 특히 예약 서버와 관련된 경우에는 실패 시 몇 번 재시도하는 것이 좋습니다.
호출이 성공하고 텔레포트가 시작되더라도, 마지막 순간에 오류를 발생시키지 않고 실패할 수 있으며 사용자를 서버에 남겨둘 수 있습니다. 이 경우 TeleportService.TeleportInitFailed 이벤트가 트리거됩니다.
다음 예제 ModuleScript는 보호된 호출로 플레이어를 텔레포트하는 단일 SafeTeleport 함수를 반환하며, 재시도 로직을 포함합니다. 또한 호출이 성공했지만 텔레포트가 발생하지 않은 상황을 처리하는 handleFailedTeleport 함수도 있습니다.
local TeleportService = game:GetService("TeleportService")
local ATTEMPT_LIMIT = 5
local RETRY_DELAY = 1
local FLOOD_DELAY = 15
local function SafeTeleport(placeId, players, options)
local attemptIndex = 0
local success, result -- 결과를 나중에 보고할 수 있도록 루프 외부에서 정의
repeat
success, result = pcall(function()
return TeleportService:TeleportAsync(placeId, players, options) -- 오류를 방지하기 위해 보호된 호출로 사용자를 텔레포트
end)
attemptIndex += 1
if not success then
task.wait(RETRY_DELAY)
end
until success or attemptIndex == ATTEMPT_LIMIT -- 호출이 성공했거나 재시도 한도가 도달할 때까지 텔레포트 시도 중지
if not success then
warn(result) -- 실패 이유를 출력에 인쇄
end
return success, result
end
local function handleFailedTeleport(player, teleportResult, errorMessage, targetPlaceId, teleportOptions)
if teleportResult == Enum.TeleportResult.Flooded then
task.wait(FLOOD_DELAY)
elseif teleportResult == Enum.TeleportResult.Failure then
task.wait(RETRY_DELAY)
else
-- 텔레포트가 유효하지 않은 경우, 재시도하는 대신 오류를 보고
error(("유효하지 않은 텔레포트 [%s]: %s"):format(teleportResult.Name, errorMessage))
end
SafeTeleport(targetPlaceId, {player}, teleportOptions)
end
TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)
return SafeTeleportSafeTeleport 함수는 TeleportAsync() 함수와 동일한 인수를 받습니다. 다음 스크립트를 SafeTeleport 함수와 함께 사용하여 게임의 어디에서나 텔레포트를 수행할 수 있습니다:
local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local ServerScriptService = game:GetService("ServerScriptService")
local SafeTeleport = require(ServerScriptService.SafeTeleport)
local PLACE_TO_TELEPORT_TO = 12345678
local function teleport(touchPart)
local playerToTeleport = game.Players:GetPlayerFromCharacter(touchPart.Parent)
if playerToTeleport then
SafeTeleport(PLACE_TO_TELEPORT_TO, {playerToTeleport})
end
end
script.Parent.Touched:Connect(teleport)