장소 간 순간이동

판타지 세계, 여러 마을, 성, 광활한 숲과 같은 많은 고유한 장소로 구성된 경험을 빌드하려는 경우 TeleportService를 사용하여 사용자가 우주, 서버 또는 다른 경험 간에 순간이동할 수 있도록 할 수 있습니다.

순간 이동 설정

경험에서 순간이동을 활성화하려면 TeleportService:TeleportAsync()를 사용하십시오. 메서드는 세 가지 매개변수를 허용합니다.

• 사용자가 순간이동할 수 있는 PlaceId
• 사용자를 텔레포트데 사용되는 배열에 포함된 Player 인스턴스.
• TeleportOptions 호출에 대한 사용자 지정 속성을 포함하는 선택적 TeleportAsync() 인스턴스.

local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")

local TARGET_PLACE_ID = 1234 -- 자체 장소 ID로 교체

local playerToTeleport = Players:GetPlayers()[1] -- 경험에서 첫 번째 사용자 가져오기

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)

순간 이동을 설정할 때 오류 처리 방법을 취하려면 오류가 발생한 경우의 처리 방법을 참조하십시오 실패한 순간 이동 처리 방법.

교차 경험 순간 이동 활성화

보안상의 이유로, 사용자를 경험에서 다른 사람이 소유하는 경험으로 순간이동하거나 그 반대로 순간이동하는 것은 기본적으로 실패합니다.교차 경험 순간 이동을 활성화하려면 게임 설정 > 보안 > 타사 순간 이동 허용 을 Studio에서 열고 활성화하십시오.

사용자 지정 순간 이동 화면 생성

사용자가 텔레포트트리거하면 새로운 장소가 로드될 때까지 표준 Roblox 로딩 화면을 볼 수 있습니다.클라이언트에서 TeleportService:SetTeleportGui() 를 호출하여 사용자의 몰입도를 향상시키기 위해 사용자 전송 전에 사용할 ScreenGui 화면을 사용자 지정으로 추가할 수 있습니다.다음 예제에서는 순간이동이 발생할 때 로딩 화면으로 ScreenGui 위치한 사용자 지정 ReplicatedStorage 을 설정합니다.그것은 내부의 스크립트를 실행하지 않습니다 ScreenGui .

local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

순간이동 옵션 사용자 지정

사용자를 특정 서버로 순간이동 및 순간이동과 함께 사용자 데이터 전송과 같은 사용자 순간이동을 사용자 정의할 수 있도록 인스턴스를 설정하고 메서드에 전달하면됩니다.

특정 서버로 순간이동

사용자를 특정 서버로 순간이동하려면 TeleportOptions를 사용하여 대상 서버를 설정하고 TeleportService:TeleportAsync() 메서드에 전달합니다.서버를 지정하지 않으면 사용자가 매치메이드 공용 서버로 순간이동됩니다.목록의 첫 번째 사용자의 정보가 해당 공용 서버와 매치메이킹하는 데 사용됩니다.

사용자를 특정 공용 서버로 순간이동하려면 TeleportOptions.ServerInstanceId 속성을 공용 서버에 대한 유일한 식별자인 유효한 인스턴스 ID로 설정하십시오.

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

텔레포트와 함께 사용자 데이터 전송

장소 간에 사용자를 순간이동하면 해당 사용자와 관련된 모든 로컬 데이터가 삭제됩니다.장소 간의 데이터 지속성을 처리하기 위해 다음 방법을 사용할 수 있습니다.

• 경험이 경험 내 통화나 인벤토리와 같은 보안 사용자 데이터 를 사용하고 장소에서 플레이스데이터를 유지하려면 데이터 저장소 또는 메모리 저장소를 구현하십시오.

• 장소에서 플레이스기본 보안되지 않은 데이터를 보내려면 전송하기 전에 를 호출하십시오.

local teleportData = {
    randomNumber = RNG:NextInteger(1, 100),
}

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions:SetTeleportData(teleportData)

서버에서 텔레포트로 도착하는 사용자의 모든 데이터를 가져오려면 Player:GetJoinData() 함수를 사용하여 사용자와 관련된 데이터가 포함된 사전을 반환합니다.

local Players = game:GetService("Players")

local function onPlayerAdded(player)
    local joinData = player:GetJoinData()
    local teleportData = joinData.TeleportData
    local randomNumber = teleportData.randomNumber

    print(player.Name .. "joined with the number" .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

클라이언트에서 전송 데이터만 검색하려면 TeleportService:GetLocalPlayerTeleportData()를 사용할 수 있습니다.

처리된 텔레포트 실패 Handle failed teleports

네트워크 요청이 포함된 모든 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(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

SafeTeleport 함수는 TeleportAsync() 함수와 동일한 인수를 받습니다.경험의 어디서나 순간이동을 수행하기 위해 ModuleScript 함수와 SafeTeleport 함수를 사용하여 순간이동 실패를 줄일 수 있습니다.

local Players = game:GetService("Players")
local ServerScriptService = game:GetService("ServerScriptService")

local SafeTeleport = require(ServerScriptService.SafeTeleport)

local TARGET_PLACE_ID = 1818 -- 자체 장소 ID로 교체

local playerToTeleport = Players:GetPlayers()[1] -- 게임에서 첫 번째 사용자 가져오기

SafeTeleport(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)