Teleportasi antar tempat

*Konten ini diterjemahkan menggunakan AI (Beta) dan mungkin mengandung kesalahan. Untuk melihat halaman ini dalam bahasa Inggris, klik di sini.

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:

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 mungkin menggunakan event BasePart.Touched atau ProximityPrompt.Triggered untuk mendapatkan Player individu. Kemudian Anda dapat memeriksa apakah pemain adalah bagian dari tim (Player.Team) atau partai (Player.PartyId). Akhirnya, Anda dapat menggunakan Team:GetPlayers() atau SocialService:GetPlayersByPartyId() jika Anda ingin mentransfer seluruh grup daripada hanya individu.

Konfigurasi teleportasi yang aman

Tiga pengaturan menangani keamanan teleportasi.

PengaturanDeskripsi
(Dashboard Pembuat) Audiens > Pengaturan Akses > Kontrol Akses untuk TempatMengontrol apakah pemain dapat bergabung dengan tempat mana pun dalam permainan Anda atau harus terlebih dahulu bergabung dengan tempat awal.
(Dashboard Pembuat) Tempat > Akses > Kontrol Akses LangsungMengganti pengaturan Kontrol Akses untuk Tempat di tingkat permainan Anda untuk tempat non-awal.
(Studio) File > Pengaturan Pengalaman > Keamanan > Izinkan Teleportasi Pihak KetigaMengontrol teleportasi dari permainan Anda ke permainan yang tidak Anda miliki. Anda dapat membiarkan pengaturan ini dinonaktifkan dan tetap mentransfer pemain antar permainan yang diterbitkan yang Anda miliki.

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

Kontrol akses untuk tempat di Creator Hub

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

    Ini adalah pilihan yang baik jika permainan Anda memiliki beberapa tempat dan Anda ingin teman-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 di 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, buat GUID dengan HttpService:GenerateGUID(false) dan atur TeleportOptions.ReservedServerId. Teleportasi pertama menggunakan ID baru membuat server; menggunakan ID yang sama mengarahkan teleportasi berikutnya ke server tersebut.

local HttpService = game:GetService("HttpService")
local TeleportService = game:GetService("TeleportService")
local TARGET_PLACE_ID = 12345678901234
local reservedServerId = HttpService:GenerateGUID(false)
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerId = reservedServerId
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)

Untuk mentransfer pengguna ke server VIP (pribadi), atur TeleportOptions.VipServerId ke DataModel.PrivateServerId dari server VIP target:

-- PrivateServerId dari server VIP tujuan, misalnya dibawa
-- dalam data teleportasi pemain atau dibaca dari penyimpanan data
local vipServerId = player:GetJoinData().TeleportData.vipServerId
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.VipServerId = vipServerId

Ketika mentransfer pengguna ke tempat lain dalam pengalaman yang sama, atur TeleportOptions.VipServerId ke game.PrivateServerId jika Anda ingin mereka tetap di server VIP yang sama:

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.VipServerId = game.PrivateServerId

Untuk informasi lebih lanjut tentang pola teleportasi server yang dipesan dan VIP, termasuk penggunaan kembali ID server dan migrasi dari kode akses warisan, lihat Teleport ke server pribadi.

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 menggunakan 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().

Uji teleportasi di Studio

Anda dapat menguji teleportasi TeleportAsync() dalam mode Uji dan Uji Tim di Studio tanpa menerbitkan pengalaman Anda. Ketika teleportasi dijalankan selama pengujian, tempat tujuan terbuka sebagai server uji baru, sehingga Anda dapat melakukan debug baik tempat asal maupun tujuan di Studio. Alat Studio seperti inspeksi server, debugger (termasuk breakpoint), dan simulator perangkat dibawa ke tempat tujuan. Anda juga dapat menguji teleportasi dalam Build dan melalui otomatisasi uji coba di server MCP Studio.

Batasan yang diketahui

Beberapa perilaku berbeda antara pengujian dan produksi:

  • PrivateServerId dan JobId: Dalam mode Uji, keduanya selalu kosong, bahkan untuk server pribadi. Dalam Uji Tim, setiap server bersifat pribadi, sehingga PrivateServerId tidak pernah kosong, bahkan untuk teleportasi ke server publik. Kode yang memeriksa apakah PrivateServerId kosong berperilaku berbeda dalam Uji Tim dibandingkan dengan produksi.
  • ReservedServerId vs. PrivateServerId: Nilai-nilai ini dapat berbeda dalam Uji Tim, meskipun mereka cocok dalam produksi. Untuk mengirim lebih banyak pemain ke server yang dipesan yang sama, gunakan kembali ReservedServerId asli, bukan PrivateServerId server tujuan.
  • Teleportasi VIP: Teleportasi yang menggunakan VipServerId gagal dalam pengujian karena server Uji Tim tidak memiliki pemilik.
  • Hanya pengalaman yang sama: Anda hanya dapat mentransfer antar tempat yang berbagi GameId dari tempat awal.
  • Metode yang tidak didukung: GetPlayerPlaceInstanceAsync() tidak berfungsi dalam pengujian.

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 mendapatkan manfaat 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, teleportasi masih dapat gagal pada saat terakhir tanpa menghasilkan kesalahan dan meninggalkan pengguna di server. Ketika ini terjadi, itu memicu event TeleportService.TeleportInitFailed.

Contoh berikut ModuleScript mengembalikan satu fungsi SafeTeleport 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 teleportasi 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 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 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)
©2026 Roblox Corporation. Roblox, logo Roblox, dan Powering Imagination termasuk dalam merek dagang kami yang terdaftar dan tidak terdaftar di AS dan negara lainnya.