Dịch chuyển giữa các địa điểm | Tài liệu

Nếu bạn muốn xây dựng một trải nghiệm với nhiều nơi địa lý khác nhau, chẳng hạn như một thế giới giả tưởng với nhiều thị trấn, lâu đài, dungeon và một rừng rộng lớn, bạn có thể sử dụng TeleportService để cho phép người dùng dịch chuyển gi

TeleportService không hỗ trợ playtesting trong Roblox Studio. Bạn phải xuất bản trải nghiệm và sử dụng nó trên ứng dụng Roblox để kiểm tra.

Cài đặt dịch chuyển

Để bật khả năng dịch chuyển trong trải nghiệm của bạn, hãy sử dụng TeleportService:TeleportAsync() . Phương thức nhận ba tham số:

Class.DataModel.PlaceId|PlaceId cho người dùng để dịch chuyển đến.
Một mat阵 đứng chứa các Player 实例 đại diện cho người dùng để dịch chuyển.
Một đối tượng TeleportOptions tùy chỉnh chứa các thuộc tính tùy chỉnh cho cuộc gọi TeleportAsync() .


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

local TARGET_PLACE_ID = 1234 -- thay thế bằng ID chỗ của riêng bạn

local playerToTeleport = Players:GetPlayers()[1] -- nhận người dùng đầu tiên trong trải nghiệm

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

Bạn chỉ có thể gọi TeleportAsync() từ các脚本 bên máy chủ. Giới hạn này giảm thiểu sự lợi dụng của client-side. Nếu cần thiết, bạn có thể gọi Teleport() t

Nếu bạn muốn có những biện pháp cần thiết để xử lý lỗi khi cài đặt dịch chuyển, xem Xử lý dịch chuyển bị lỗi .

Mở khóa Dịch chuyển Thông qua Kinh nghiệm

Vì mục đích an ninh, dịch chuyển một người từ trải nghiệm của bạn sang trải nghiệm của người khác, hoặc theo cách khác, thất bại bằng cách mặc định. Để kích hoạt dịch chuyển trải nghiệm, hãy mở Cài đặt trò chơi > An toàn

Tạo màn hình Teleport Tùy chỉnh

Khi một người dùng kích hoạt một cuộc dịch chuyển, họ sẽ thấy màn hình chờ đợn tải mớ


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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

Tùy chỉnh tùy chọn dịch chuyển

Bạn có thể tùy chỉnh dịch chuyển, chẳng hạn như dịch chuyển người dùng đến một máy chủ cụ thể và gửi dữ liệu người dùng cùng với dịch chuyển , bằng cách thiết lập TeleportOptions instan

Dịch chuyển đến các máy chủ cụ thể

Để dịch chuyển người dùng đến các máy chủ cụ thể, hãy cài đặt máy chủ mục tiêu bằng cách sử dụng TeleportOptions và truyền cho phương thức TeleportService:TeleportAsync(). Nếu bạn không cung cấp một máy chủ, người dù

Để dịch chuyển người dùng đến một máy chủ công khai cụ thể, hãy cài đặt thuộc tính TeleportOptions.ServerInstanceId như một ID máy chủ công khai để định danh độc nhất cho máy chủ công khai.


local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ServerInstanceId = targetServerId

Để dịch chuyển người dùng đến một máy chủ được dự trữ cụ thể, hãy cài đặt một mã độc đáo TeleportOptions.ReservedServerAccessCode, which is a unique code để tham gia vào một máy chủ dự trữ.


local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerAccessCode = reservedServerCode

Để dịch chuyển người dùng đến một máy chủ dự phòng mới, hãy đặt TeleportOptions.ShouldReserveServer lên true.


local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ShouldReserveServer = true

Gửi dữ liệu người dùng kèm theo với dịch chuyển

Dịch chuyển một người dùng giữa các nơi thảo tài xóa bất kỳ dữ liệu nào liên quan đến người dùng đó. Bạn có thể sử dụng các phương pháp sau đây để xử lý sự kiên cối dữ liệu giữa các nơi.

Nếu trải nghiệm của bạn sử dụng dữ liệu người dùng an toàn như tiền tệ trong kinh nghiệm hoặc kho đại lý, thực hiện lưu trữ dữ liệu hoặc lưu trữ bộ nhớ để duy trì dữ liệu từ nơi này sang địa điểmkhác.
Để gửi dữ liệu không chắc chắn từ nơi này đến địa điểm, hãy gọi TeleportOptions:SetTeleportData() trước khi gửi nó đến TeleportAsync() .

Đừng sử dụng dữ liệu an toàn bằng cách sử dụng TeleportOptions:SetTeleportData() vì nó có nguy cơ bị lợi dụng.


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

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

Để nhận tất cả dữ liệu của một người dùng đến từ một teleport trên máy chủ, hãy sử dụng chức năng Player:GetJoinData(), which returns a dictionary including the data associates with the user.


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)

Để chỉ lấy dữ liệu dịch chuyển trên client, bạn có thể sử dụng TeleportService:GetLocalPlayerTeleportData() .

Xử lý các mối qua lại không thành công

Giống như bất kỳ cuộc gọi API liên quan đến yêu cầu mạng, teleport có thể thất bại và ném một lỗi. Ngay cả khi một cuộc gọi thành công và kích hoạt, nó vẫn có thể không thành công ở phút cuối mà không ném một lỗi và để lại người dùng trên máy chủ.

Wrap teleports in a protected call ( pcall() ) and retry if it fails. The following example ModuleScript defines a SafeTeleport function to teleport the user in a protected call and a 1> HandleFailedTeleport1> function to retry failed teleports that are one-time hiccups and drops invalid


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 -- định义 pcall kết quả ngoài vòng lặp để kết quả có thể được báo cáo sau đó

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- dịch chuyển người dùng trong một cuộc gọi được bảo vệ để ngăn chặn lỗi
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- dừng cố gắng dịch chuyển nếu cuộc gọi thành công hoặc nếu đã đạt đến giới hạn thử lại

    if not success then
        warn(result) -- in lý do thất bại để ra ngoài
    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
        -- nếu dịch chuyển không hợp lệ, báo cáo lỗi thay vì thử lại
        error(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

Hàm SafeTeleport nhận cùng một số lý do như hàm TeleportAsync(). Bạn có thể sử dụng điều này với ModuleScript với hàm 1> SafeTeleport1> để thực hiện các lượt dịch chuyển


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

local SafeTeleport = require(ServerScriptService.SafeTeleport)

local TARGET_PLACE_ID = 1818 -- thay thế bằng ID chỗ của riêng bạn

local playerToTeleport = Players:GetPlayers()[1] -- nhận người dùng đầu tiên trong trò chơi

SafeTeleport(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)