Teleportasi antar tempat

Jika Anda ingin membangun pengalaman dengan banyak tempat berbeda, seperti dunia fantasi dengan banyak kota, kastil, ruang bawah tanah, dan hutan luas, Anda dapat menggunakan TeleportService untuk mengaktifkan pengguna untuk berteleportasi di antara tempat di alam semesta, server, atau bahkan ke pengalaman lain.

TeleportService tidak mendukung pengujian permainan di Roblox Studio. Anda harus mempublikasikan pengalaman dan menggunakannya di aplikasi Roblox untuk pengujian.

Menyiapkan teleportasi

Untuk mengaktifkan teleportasi dalam pengalaman Anda, gunakan TeleportService:TeleportAsync(). Metode ini menerima tiga parameter:

The PlaceId untuk pengguna untuk teleport ke.
Sebuah array yang berisi Player instansi yang mewakili pengguna untuk berteleportasi
Instansi opsional TeleportOptions yang berisi properti khusus untuk panggilan TeleportAsync() .


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

local TARGET_PLACE_ID = 1234 -- ganti dengan ID tempat Anda sendiri

local playerToTeleport = Players:GetPlayers()[1] -- dapatkan pengguna pertama dalam pengalaman

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

Anda hanya dapat memanggil TeleportAsync() dari skrip sisi server.Keterbatasan ini mengurangi eksploitasi sisi klien.Jika diperlukan, Anda dapat memanggil Teleport() dari skrip sisi klien, tetapi TeleportAsync() adalah metode yang direkomendasikan.

Jika Anda ingin mengambil tindakan pencegahan untuk menangani kesalahan saat mengatur teleportasi, lihat cara menangani teleportasi gagal.

Aktifkan teleportasi pengalaman silang

Untuk tujuan keamanan, teleportasi pengguna dari pengalaman Anda ke pengalaman lain yang dimiliki oleh orang lain, atau sebaliknya, gagal secara default.Untuk mengaktifkan teleportasi pengalaman silang, buka Pengaturan Permainan > Keamanan dan aktifkan Izinkan Teleportasi Pihak Ketiga di Studio.

Buat layar teleportasi khusus

Ketika pengguna mengaktifkan berteleportasi, mereka melihat layar pemuatan Roblox standar saat menunggu tempat baru dimuat.Anda dapat menambahkan layar teleportasi khusus untuk meningkatkan imersi bagi pengguna dengan memanggil TeleportService:SetTeleportGui() di klien dan melewati ScreenGui untuk digunakan sebelum teleportasi pengguna.Contoh berikut menetapkan ScreenGui khusus yang terletak di ReplicatedStorage sebagai layar pemuatan saat terjadi teleportasi.Ini tidak menjalankan skrip apa pun di dalam ScreenGui .


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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

Sesuaikan opsi teleportasi

Anda dapat menyesuaikan teleportasi, seperti mengirim pengguna ke server tertentu dan mengirim data pengguna bersama dengan teleportasi , dengan mengatur instansi TeleportOptions dan mengirimkannya ke metode TeleportService:TeleportAsync().

Teleport ke server spesifik

Untuk teleport pengguna ke server tertentu, atur server target menggunakan TeleportOptions dan berikan ke metode TeleportService:TeleportAsync().Jika Anda tidak menentukan server, pengguna dipindahkan ke server publik matchmade.Informasi pengguna pertama dalam daftar digunakan untuk matchmaking ke server publik itu.

Untuk teleport pengguna ke server publik tertentu, atur properti TeleportOptions.ServerInstanceId sebagai ID instans yang valid, yang merupakan identifikasi unik untuk server publik.


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

Untuk teleport pengguna ke server cadangan tertentu, atur TeleportOptions.ReservedServerAccessCode yang valid, yang merupakan kode unik untuk masuk ke server cadangan.


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

Untuk teleport pengguna ke server cadangan baru, atur TeleportOptions.ShouldReserveServer menjadi benar.


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

Kirim data pengguna bersama dengan teleportasi

Teleportasi pengguna di antara tempat menghapus semua data lokal yang terkait dengan pengguna itu.Anda dapat menggunakan pendekatan berikut untuk menangani persistensi data antara tempat.

Jika pengalaman Anda menggunakan data aman pengguna seperti mata uang atau inventaris dalam pengalaman, implementasikan penyimpanan data atau penyimpanan memori untuk mempertahankan data dari tempat ke tempat.
Untuk mengirim data dasar tidak aman dari tempat ke tempat, hubungi TeleportOptions:SetTeleportData() sebelum mengirimkannya ke TeleportAsync() .

Jangan lulus data aman menggunakan TeleportOptions:SetTeleportData() karena memiliki risiko eksploitasi.


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

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

Untuk mendapatkan semua data pengguna yang tiba dari teleport di server, gunakan fungsi Player:GetJoinData(), yang men返ikan kamus termasuk data yang terkait dengan pengguna.


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)

Untuk mengambil hanya data teleport pada klien, Anda dapat menggunakan TeleportService:GetLocalPlayerTeleportData() .

Angani teleportasi gagal

Seperti setiap panggilan API yang melibatkan permintaan jaringan, teleport bisa gagal dan menyebabkan kesalahan.Bungkus mereka dalam panggilan terlindungi ( pcall() ).Beberapa kegagalan mendapat manfaat dari pencobaan ulang, terutama yang melibatkan server yang disediakan, jadi kami sarankan mencoba ulang beberapa kali pada kegagalan.

Bahkan jika panggilan berhasil dan teleportasi dimulai, itu masih bisa gagal pada saat terakhir tanpa melempar kesalahan dan meninggalkan pengguna di server.Ketika ini terjadi, itu memicu acara TeleportService.TeleportInitFailed .

Contoh berikut ModuleScript mendefinisikan fungsi SafeTeleport untuk teleport pengguna dalam panggilan terlindung dengan logika retensi.Ini juga memiliki fungsi handleFailedTeleport untuk menangani situasi di mana panggilan berhasil, tetapi teleport tidak terjadi.


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 -- definisikan hasil panggilan di luar loop sehingga hasil dapat dilaporkan nanti

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- teleport pengguna dalam panggilan terlindungi untuk mencegah kesalahan
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- berhenti mencoba teleport jika panggilan berhasil, atau jika batas pencobaan ulang tercapai

    if not success then
        warn(result) -- cetak alasan kegagalan untuk output
    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
        -- jika teleportasi tidak valid, laporkan kesalahan alih-alih mencoba kembali
        error(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

Fungsi SafeTeleport menerima argumen yang sama dengan fungsi TeleportAsync() .Anda dapat menggunakan berikut ini ModuleScript dengan fungsi SafeTeleport untuk melakukan teleportasi dari mana saja di pengalaman Anda untuk mengurangi teleportasi gagal.


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

local SafeTeleport = require(ServerScriptService.SafeTeleport)

local TARGET_PLACE_ID = 1818 -- ganti dengan ID tempat Anda sendiri

local playerToTeleport = Players:GetPlayers()[1] -- dapatkan pengguna pertama di game

SafeTeleport(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)