Teleportasi antar tempat

Banyak permainan dibagi menjadi beberapa tempat, seperti dunia fantasi dengan kota, kastil, ruang bawah tanah, dan hutan yang luas. Gunakan TeleportService untuk mentransfer pengguna antar tempat, ke server yang berbeda, atau bahkan ke permainan lain.

Teleport pemain

Untuk mentransfer pemain, gunakan TeleportService:TeleportAsync(). Metode ini menerima tiga parameter:

• PlaceId untuk pengguna yang akan ditransfer.
• Sebuah array yang berisi instance Player yang ingin Anda teleport.
• Instance TeleportOptions opsional yang berisi properti kustom untuk panggilan TeleportAsync().

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

local TARGET_PLACE_ID = 12345678901234 -- ganti dengan milik Anda
local playerToTeleport = Players:GetPlayers()[1] -- ambil pengguna pertama dalam permainan

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

Untuk mendapatkan pemain yang tepat untuk ditransfer, Anda mungkin menggunakan event BasePart.Touched atau event ProximityPrompt.Triggered untuk mendapatkan Player individu. Kemudian Anda dapat memeriksa apakah pemain adalah bagian dari tim (Player.Team) atau pesta (Player.PartyId). Akhirnya, Anda dapat menggunakan Team:GetPlayers() atau SocialService:GetPlayersByPartyId() jika Anda ingin mentransfer seluruh kelompok daripada hanya individu.

Konfigurasi teleportasi yang aman

Tiga pengaturan menangani keamanan teleportasi.

Kontrol Akses untuk Tempat mengontrol pemain yang teleport ke dalam permainan Anda dan merupakan pengaturan yang paling penting untuk mencegah eksploitasi berbasis teleport.

• Jika Anda memilih Sepenuhnya terbuka, pemain dapat bergabung dengan tempat mana pun dalam permainan Anda melalui teleportasi dari permainan mana pun, termasuk tautan mendalam, undangan permainan, bergabung dengan teman, dan lainnya.

  Ini adalah pilihan yang baik jika permainan Anda memiliki beberapa tempat dan Anda ingin teman dapat dengan mudah bergabung satu sama lain tidak peduli tempat mana yang mereka masuki. Jika Anda tidak memilih opsi ini, pemain yang mencoba bergabung dengan teman mereka di tempat non-awal akan bergabung dengan tempat awal permainan Anda.

• Jika Anda memilih Terbatas pada alam semesta yang sama, pemain hanya dapat bergabung dengan tempat non-awal melalui teleportasi dalam permainan Anda. Pengaturan ini memungkinkan teleportasi yang diinisiasi oleh klien dan server.

  Ini adalah pilihan yang baik jika Anda memiliki permainan warisan yang tidak ingin Anda migrasikan ke teleportasi yang aman.

• Jika Anda memilih Aman hanya dalam alam semesta, pemain hanya dapat bergabung dengan tempat non-awal melalui teleportasi yang diinisiasi oleh server dalam permainan ini.

  Ini adalah pilihan yang baik jika permainan Anda memiliki sistem progresi yang ketat sebelum pemain dapat mengakses area tertentu. Ini juga merupakan pilihan yang baik jika permainan Anda memiliki tempat uji yang tidak boleh diakses oleh pemain atau untuk tempat yang hanya menggunakan server yang dipesan.

Migrasi ke teleportasi yang aman

Jika Anda memiliki permainan yang ada yang menggunakan teleportasi sisi klien dan ingin mewajibkan teleportasi yang diinisiasi oleh server, tujuannya adalah untuk memindahkan semua logika teleportasi keluar dari skrip klien dan ke dalam skrip server:

1. Temukan semua skrip klien yang memanggil Teleport().
2. Ubah panggilan ini untuk memicu event jarak jauh. Sebagai alternatif, Anda dapat mengubah panggilan ini untuk menggunakan ProximityPrompts, ClickDetectors, atau bahkan hanya event BasePart.Touched.
3. Implementasikan kembali teleportasi dalam skrip server menggunakan TeleportAsync().
4. Ketika tidak ada lagi panggilan Teleport(), ubah Kontrol Akses untuk Tempat menjadi Aman.

Buat layar teleportasi kustom

Ketika seorang pengguna memicu teleportasi, mereka melihat layar pemuatan standar Roblox saat mereka menunggu tempat baru untuk dimuat. Jika diinginkan, Anda dapat menambahkan layar teleportasi kustom dengan memanggil TeleportService:SetTeleportGui() di klien.

Contoh berikut mengatur ScreenGui yang disesuaikan dari ReplicatedStorage. Skrip apa pun dalam ScreenGui tidak dijalankan.

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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

Kustomisasi opsi teleportasi

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

Teleport ke server tertentu

Untuk mentransfer pengguna ke server tertentu, atur server target menggunakan TeleportOptions dan teruskannya ke metode TeleportAsync(). Jika Anda tidak menentukan server, pengguna akan ditransfer ke server publik; informasi pengguna pertama dalam daftar digunakan untuk pencocokan.

Untuk mentransfer pengguna ke server publik tertentu, atur properti TeleportOptions.ServerInstanceId sebagai ID instance yang valid, yang merupakan pengidentifikasi unik untuk server publik.

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

Untuk mentransfer pengguna ke server yang dipesan tertentu, atur TeleportOptions.ReservedServerAccessCode yang valid, yang merupakan kode unik untuk memasuki server yang dipesan.

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

Untuk mentransfer pengguna ke server yang dipesan baru, atur TeleportOptions.ShouldReserveServer menjadi true.

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

Kirim data pengguna bersama dengan teleportasi

Mentransfer pengguna antar tempat membuang semua data lokal yang terkait dengan pengguna tersebut. Anda dapat menggunakan pendekatan berikut untuk menangani persistensi data antar tempat:

• Jika permainan Anda memanfaatkan data pengguna aman seperti mata uang dalam permainan atau inventaris, implementasikan data stores atau memory stores untuk mempertahankan data dari tempat ke tempat.

• Untuk mengirim data tidak aman dasar dari tempat ke tempat, panggil TeleportOptions:SetTeleportData() sebelum meneruskannya ke TeleportAsync(). Jangan meneruskan data aman menggunakan metode ini; data tersebut terlihat oleh klien dan tidak terenkripsi.

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

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

Untuk mengambil semua data ketika seorang pengguna tiba di tempat baru setelah teleportasi, gunakan fungsi Player:GetJoinData(), yang mengembalikan kamus dengan kunci 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 .. " bergabung dengan nomor " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Untuk mengambil hanya data teleportasi di klien, Anda dapat menggunakan TeleportService:GetLocalPlayerTeleportData().

Tangani teleportasi yang gagal

Seperti panggilan API lainnya yang melibatkan permintaan jaringan, teleportasi dapat gagal dan menghasilkan kesalahan. Bungkus mereka dalam panggilan terlindungi (pcall()). Beberapa kegagalan mendapat manfaat dari pengulangan, terutama yang melibatkan server yang dipesan, jadi kami merekomendasikan untuk mencoba beberapa kali pada kegagalan.

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

Contoh berikut ModuleScript mengembalikan fungsi SafeTeleport tunggal yang mentransfer pemain dalam panggilan terlindungi dengan logika pengulangan. Ini juga memiliki fungsi handleFailedTeleport untuk menangani situasi di mana panggilan berhasil, tetapi teleportasi 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 -- mendefinisikan hasil pcall di luar loop sehingga hasil dapat dilaporkan nanti

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- mentransfer 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 untuk mentransfer jika panggilan berhasil, atau jika batas pengulangan telah tercapai

    if not success then
        warn(result) -- cetak alasan kegagalan ke 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 lagi
        error(("Teleportasi tidak valid [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

Fungsi SafeTeleport menerima argumen yang sama seperti fungsi TeleportAsync(). Anda dapat menggunakan skrip berikut dengan fungsi SafeTeleport untuk melakukan teleportasi dari mana saja dalam permainan Anda:

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)