많은 게임은 마을, 성, 던전, 넓은 숲과 같은 여러 장소로 나뉘어 있습니다. TeleportService를 사용하여 사용자들을 장소 간에, 다른 서버로, 심지어는 다른 게임으로 텔레포트할 수 있습니다.
TeleportService는 Roblox Studio에서 플레이 테스트를 지원하지 않습니다. 게임을 게시하고 Roblox 클라이언트에서 테스트해야 합니다.
플레이어 텔레포트
플레이어를 텔레포트하려면 TeleportService:TeleportAsync()를 사용하세요. 이 메서드는 세 가지 매개변수를 받습니다:
- 텔레포트할 사용자에 대한 PlaceId.
- 텔레포트하려는 Player 인스턴스를 포함하는 배열.
- TeleportAsync() 호출을 위한 사용자 지정 속성을 포함하는 선택적 TeleportOptions 인스턴스.
텔레포트할 적절한 플레이어를 얻으려면 BasePart.Touched 또는 ProximityPrompt.Triggered 이벤트를 사용하여 개별 Player를 얻을 수 있습니다. 그런 다음 플레이어가 팀(Player.Team)이나 파티(Player.PartyId)의 일원인지 확인할 수 있습니다. 마지막으로 전체 그룹을 텔레포트하려면 Team:GetPlayers() 또는 SocialService:GetPlayersByPartyId()를 사용할 수 있습니다.
클라이언트 측 악용을 줄이기 위해 TeleportAsync()는 서버 스크립트에서만 호출할 수 있습니다. 필요시 클라이언트 스크립트는 Teleport()를 호출할 수 있지만, 우리는 이를 추천하지 않습니다. 더 많은 정보는 보안 텔레포트 구성을 참조하세요.
보안 텔레포트 구성
세 가지 설정이 텔레포트 보안을 처리합니다.
| 설정 | 설명 |
|---|---|
| (크리에이터 대시보드) 청중 > 접근 설정 > 장소의 접근 제어 | 플레이어가 게임의 모든 장소에 참여할 수 있는지, 혹은 먼저 시작 장소에 참여해야 하는지 제어합니다. |
| (크리에이터 대시보드) 장소 > 접근 > 직접 접근 제어 | 비시작 장소에 대해 게임 수준의 장소 접근 제어 설정을 무효화합니다. |
| (스튜디오) 파일 > 경험 설정 > 보안 > 타사 텔레포트 허용 | 사용자에게 소유하지 않은 게임으로의 텔레포트를 제어합니다. 이 설정을 비활성화해도 소유한 게시된 게임 간에 플레이어를 텔레포트할 수 있습니다. |
장소 접근 제어는 플레이어가 게임에 들어가는 것을 제어하며, 텔레포트 기반 악용을 방지하는 가장 중요한 설정입니다.
완전히 공개를 선택하면 플레이어는 깊은 링크, 게임 초대, 친구 초대 등을 포함하여 게임의 모든 장소에 텔레포트를 통해 참여할 수 있습니다.
이는 게임에 여러 장소가 있고 친구들이 어떤 장소에 있든 서로 쉽게 참여할 수 있기를 원하는 경우에 좋은 선택입니다. 이 옵션을 선택하지 않으면, 비시작 장소에 있는 친구들에게 참여하려는 플레이어는 대신 게임의 시작 장소에 참여하게 됩니다.
같은 유니버스로 제한을 선택하면 플레이어는 게임 내의 비시작 장소에만 텔레포트할 수 있습니다. 이 설정은 클라이언트와 서버 모두에서 시작된 텔레포트를 허용합니다.
이는 보안 텔레포트로 마이그레이션하고 싶지 않은 레거시 게임이 있는 경우에 좋은 선택입니다.
유니버스 내에서만 보안을 선택하면 플레이어는 이 게임 내에서 서버 주도 텔레포트를 통해서만 비시작 장소에 참여할 수 있습니다.
이는 플레이어가 특정 지역에 접근하기 전에 엄격한 진행 시스템이 있는 게임에 좋은 선택입니다. 또는 플레이어가 접근해서는 안 되는 테스트 장소나 예약된 서버에서만 사용하는 장소에 적합합니다.
궁극적으로 귀하의 장소 접근 제어 설정은 구축하고자 하는 게임의 유형에 따라 달라집니다. 많은 게임에서 보안 텔레포트가 필요하지 않습니다.
보안 텔레포트로 마이그레이션
클라이언트 측 텔레포트를 사용하는 기존 게임이 있고 서버 주도 텔레포트를 요구하고 싶은 경우, 목표는 모든 텔레포트 논리를 클라이언트 스크립트에서 서버 스크립트로 이동하는 것입니다:
- Teleport()를 호출하는 모든 클라이언트 스크립트를 찾으세요.
- 이러한 호출을 원격 이벤트를 발생시키도록 변경합니다. 또는 ProximityPrompts, ClickDetectors 또는 심지어 BasePart.Touched 이벤트를 사용할 수 있습니다.
- 서버 스크립트에서 TeleportAsync()를 사용하여 텔레포트를 다시 구현합니다.
사용자 지정 텔레포트 화면 만들기
사용자가 텔레포트를 트리거하면 새로운 장소가 로드 될 때까지 표준 Roblox 로딩 화면이 표시됩니다. 원한다면 클라이언트에서 TeleportService:SetTeleportGui()를 호출하여 사용자 지정 텔레포트 화면을 추가할 수 있습니다.
다음 예시는 ReplicatedStorage의 사용자 지정 ScreenGui를 설정합니다. ScreenGui 내의 모든 스크립트는 실행되지 않습니다.
텔레포트 옵션 사용자 지정
텔레포트를 사용자 지정할 수 있으며, 예를 들어 특정 서버에 사용자를 텔레포트하거나 사용자 데이터를 텔레포트와 함께 전송할 수 있습니다. TeleportOptions 인스턴스를 설정하고 이를 TeleportService:TeleportAsync() 메서드에 전달합니다.
특정 서버로 텔레포트
특정 서버로 사용자를 텔레포트하려면 TeleportOptions를 사용하여 대상 서버를 설정하고 이를 TeleportAsync() 메서드에 전달합니다. 서버를 지정하지 않으면, 사용자는 공용 서버로 텔레포트됩니다. 목록의 첫 번째 사용자 정보가 매치메이킹에 사용됩니다.
특정 공용 서버로 사용자를 텔레포트하려면, 유효한 인스턴스 ID인 TeleportOptions.ServerInstanceId 속성을 설정합니다.
특정 예약 서버로 사용자를 텔레포트하려면, 예약 서버에 들어가기 위한 고유 코드인 유효한 TeleportOptions.ReservedServerAccessCode를 설정합니다.
새로운 예약 서버로 사용자를 텔레포트하려면, TeleportOptions.ShouldReserveServer를 true로 설정합니다.
텔레포트와 함께 사용자 데이터 전송
장소 간에 사용자를 텔레포트하면 해당 사용자와 관련된 모든 로컬 데이터가 버려집니다. 장소 간에 데이터 지속성을 처리하기 위해 다음 접근 방법을 사용할 수 있습니다:
장소 간에 기본 비보안 데이터를 전송하려면, 데이터를 TeleportOptions:SetTeleportData()를 호출하여 설정한 후 TeleportAsync()에 전달하십시오. 보안 데이터를 이 방법으로 전달하지 마십시오. 데이터는 클라이언트에서 볼 수 있으며 암호화되지 않습니다.
사용자가 텔레포트 후 새로운 장소에 도착할 때 모든 데이터를 검색하려면, 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 -- 결과를 나중에 보고할 수 있도록 루프 외부에서 pcall 결과 정의
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 SafeTeleport
SafeTeleport 함수는 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)