Teleportasi antar tempat

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

Teleport pemain

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

• PlaceId untuk tempat yang ingin ditransfer pengguna.
• Array yang berisi instansi Player yang ingin Anda transfer.
• Instansi TeleportOptions opsional yang berisi properti khusus untuk panggilan TeleportAsync().

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

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

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

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

Konfigurasi teleportasi aman

Tiga pengaturan menangani keamanan teleportasi.

Kontrol Akses untuk Tempat mengontrol pemain yang melakukan teleportasi ke dalam game Anda dan merupakan pengaturan yang paling penting untuk mencegah eksploitasi berbasis teleportasi.

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

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

• Jika Anda memilih Terbatas pada alam semesta yang sama, pemain hanya dapat bergabung dengan tempat non-awal melalui teleportasi dalam game Anda. Pengaturan ini mengizinkan teleportasi yang dipicu oleh klien maupun server.

  Ini adalah pilihan yang baik jika Anda memiliki game warisan yang tidak ingin Anda migrasi ke teleportasi aman.

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

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

Migrasi ke teleportasi aman

Jika Anda memiliki game yang ada yang menggunakan teleportasi sisi klien dan ingin memerlukan teleportasi yang dipicu oleh server, tujuannya adalah untuk memindahkan semua logika teleportasi dari skrip klien 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 untuk menggunakan ProximityPrompts, ClickDetectors, atau bahkan hanya event BasePart.Touched.
3. Implementasikan kembali teleportasi dalam skrip server menggunakan TeleportAsync().
4. Setelah 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)

Sesuaikan opsi teleportasi

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

Teleport ke server tertentu

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

Untuk mentransfer pengguna ke server publik tertentu, setel properti TeleportOptions.ServerInstanceId sebagai ID instansi 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, setel 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, setel TeleportOptions.ShouldReserveServer ke true.

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

Kirim data pengguna bersama dengan teleportasi

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

• Jika game Anda menggunakan data pengguna aman seperti mata uang dalam game 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 sebuah 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 angka " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

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

Tangani teleportasi yang gagal

Seperti halnya panggilan API yang melibatkan permintaan jaringan, teleportasi dapat gagal dan menghasilkan error. Bungkus mereka dalam panggilan terlindungi (pcall()). Beberapa kegagalan menguntungkan dari pengulangan, terutama yang melibatkan server yang dipesan, jadi kami merekomendasikan untuk mencoba ulang beberapa kali saat terjadi kegagalan.

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

Contoh berikut ModuleScript mengembalikan fungsi SafeTeleport tunggal yang mentransfer pemain dalam sebuah 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 -- definisikan hasil pcall di luar loop agar hasil dapat dilaporkan nanti

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- teleport pengguna dalam sebuah panggilan terlindungi untuk mencegah error
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- berhenti mencoba teleportasi jika panggilan berhasil, atau jika batas percobaan 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 error daripada mencoba ulang
        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 bersama fungsi SafeTeleport untuk melakukan teleportasi dari mana saja dalam game 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)