在地點之間傳送 | 文件 - Roblox 創作者中心

許多遊戲被劃分為多個地點，例如一個擁有城鎮、城堡、地牢和廣闊森林的奇幻世界。使用 TeleportService 在地點、不同的伺服器甚至其他遊戲之間傳送用戶。

TeleportService 不支援在 Roblox Studio 中進行遊戲測試。您必須發佈遊戲並在 Roblox 客戶端中進行測試。

傳送玩家

要傳送玩家，使用 TeleportService:TeleportAsync()。此方法接受三個參數：

用戶要傳送到的 PlaceId。
一個包含您想要傳送的 Player 實例的數組。
一個可選的 TeleportOptions 實例，包含 TeleportAsync() 呼叫的自定義屬性。


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

local TARGET_PLACE_ID = 12345678901234 -- 替換為您自己的
local playerToTeleport = Players:GetPlayers()[1] -- 獲取遊戲中的第一位用戶

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

要獲得要傳送的適當玩家，您可以使用 BasePart.Touched 或 ProximityPrompt.Triggered 事件來獲取單個 Player。然後，您可以檢查玩家是否是某個隊伍的成員 (Player.Team) 或派對 (Player.PartyId)。最後，如果您想傳送整個小組而不僅僅是單個玩家，可以使用 Team:GetPlayers() 或 SocialService:GetPlayersByPartyId()。

為了減少客戶端方面的利用，您只能從伺服器腳本中調用 TeleportAsync()。如果需要，客戶端腳本可以調用 Teleport()，但我們不建議這樣做。更多信息，請參見配置安全傳送。

配置安全傳送

三個設置負責處理傳送安全性。

設置	描述
(創作者儀表板) 觀眾 > 訪問設置 > 地點的訪問控制	控制玩家是否可以通過傳送加入您遊戲中的任何地點，或必須先加入起始地點。
(創作者儀表板) 地點 > 訪問 > 直接訪問控制	覆蓋非起始地點的遊戲級地點的訪問控制設置。
(Studio) 文件 > 體驗設置 > 安全 > 允許第三方傳送	控制從您的遊戲到您不擁有的遊戲的傳送。您可以保持此設置禁用，仍然可以在您擁有的發佈遊戲之間傳送玩家。

地點的訪問控制控制玩家傳送進入您的遊戲，這是防止基於傳送的利用最關鍵的設置。

創作者中心的地點訪問控制

如果您選擇完全開放，則玩家可以通過來自任何遊戲的傳送加入您遊戲中的任何地點，包括深度鏈接、遊戲邀請、加入朋友等。

如果您的遊戲有多個地點，並且希望朋友能夠隨時輕鬆地加入彼此，這是一個不錯的選擇。如果您不選擇此選項，嘗試在非起始地點加入朋友的玩家將直接進入您的遊戲的起始地點。
如果您選擇限於同一宇宙，則玩家只能通過在您遊戲中的傳送加入非起始地點。此設置允許客戶端和伺服器發起的傳送。

如果您有一個遺留遊戲，不希望將其遷移到安全傳送，這是一個不錯的選擇。
如果您選擇僅在宇宙內安全，則玩家只能通過在此遊戲內發起的伺服器傳送進入非起始地點。

如果您的遊戲在玩家可以訪問某些區域之前有嚴格的進度系統，這是一個不錯的選擇。如果您的遊戲有一個測試地點，玩家不應該訪問，或者某些僅使用保留伺服器的地點，這也是不錯的選擇。

最終，您的地點的訪問控制設置取決於您想要構建的遊戲類型。許多遊戲不需要安全傳送。

遷移到安全傳送

如果您有一個使用客戶端傳送的現有遊戲，並希望要求伺服器發起的傳送，目標是將所有傳送邏輯移出客戶端腳本並放入伺服器腳本中：

找到所有調用 Teleport() 的客戶端腳本。
將這些調用改為觸發遠程事件。作為替代方案，您還可以將調用改為使用 ProximityPrompts、ClickDetectors，甚至僅使用 BasePart.Touched 事件。
使用 TeleportAsync() 在伺服器腳本中重新實現傳送。
當不再存在 Teleport() 調用時，將地點的訪問控制更改為安全。

創建自定義傳送螢幕

當用戶觸發傳送時，他們會看到標準的 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() 方法。如果您不指定伺服器，則用戶將被傳送到公共伺服器；將使用列表中第一個用戶的信息進行匹配。

要將用戶傳送到特定的公共伺服器，請將 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

隨傳送發送用戶數據

在地點之間傳送用戶會丟棄與該用戶相關的任何本地數據。您可以使用以下方法處理地點之間的數據持久性：

如果您的遊戲使用安全用戶數據，例如遊戲內貨幣或庫存，請實現數據存儲或內存存儲以維持地點之間的數據。
要將基本的不安全數據從一個地點發送到另一個地點，請在將其傳遞給 TeleportAsync() 之前調用 TeleportOptions:SetTeleportData()。不要使用此方法傳遞安全數據；因為該數據對客戶端是可見且未加密的。


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 -- 在循環外部定義 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)