Teleporteren tussen plaatsen

*Deze inhoud is vertaald met behulp van AI (bèta) en kan fouten bevatten. Klik hier om deze pagina in het Engels te bekijken.

Veel games zijn onderverdeeld in meerdere plaatsen, zoals een fantasiewereld met steden, kastelen, kerkers en een uitgestrekt bos. Gebruik TeleportService om gebruikers tussen plaatsen, naar verschillende servers of zelfs naar andere games te teleporteren.

Teleporteer spelers

Om spelers te teleporteren, gebruik je TeleportService:TeleportAsync(). Deze methode accepteert drie parameters:

  • De PlaceId waarnaar gebruikers moeten worden geteleporteerd.
  • Een array met de Player instanties die je wilt teleporteren.
  • Een optionele TeleportOptions instantie die aangepaste eigenschappen bevat voor de TeleportAsync() aanroep.
local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local TARGET_PLACE_ID = 12345678901234 -- vervang dit door je eigen
local playerToTeleport = Players:GetPlayers()[1] -- krijg de eerste gebruiker in de game
TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

Om de juiste spelers te teleporteren, kun je een BasePart.Touched of een ProximityPrompt.Triggered evenement gebruiken om een individuele Player te krijgen. Vervolgens kun je controleren of de speler deel uitmaakt van een team (Player.Team) of partij (Player.PartyId). Ten slotte kun je Team:GetPlayers() of SocialService:GetPlayersByPartyId() gebruiken als je de hele groep wilt teleporteren in plaats van alleen de individuele speler.

Configureer veilige teleportatie

Drie instellingen regelen de teleportbeveiliging.

InstellingBeschrijving
(Creator Dashboard) Doelgroep > Toegangsinstellingen > Toegangscontrole voor PlaatsenBeheert of spelers zich bij elke plaats in je game kunnen voegen of eerst de startplaats moeten betreden.
(Creator Dashboard) Plaats > Toegang > Directe ToegangscontroleOverschrijft je game-niveau Toegangscontrole voor Plaatsen instelling voor een niet-startplaats.
(Studio) Bestand > Ervaringsinstellingen > Beveiliging > Sta Derde Partij Teleportaties toeBeheert teleportaties van je game naar games die je niet bezit. Je kunt deze instelling uitgeschakeld laten en toch spelers tussen gepubliceerde games die je bezit teleporteren.

Toegangscontrole voor Plaatsen beheert spelers die in je game teleporteren en is de meest kritische instelling om teleport-gebaseerde exploits te voorkomen.

Toegangscontrole voor plaatsen op het Creator Hub

  • Als je Volledig open kiest, kunnen spelers zich bij elke plaats in je game voegen via teleportaties vanuit elke game, inclusief deeplinks, game-uitnodigingen, het joinen van een vriend, en meer.

    Dit is een goede keuze als je game meerdere plaatsen heeft en je wilt dat vrienden elkaar gemakkelijk kunnen joinen, ongeacht welke plaats ze zich bevinden. Als je deze optie niet kiest, zullen spelers die proberen zich bij hun vrienden in niet-startplaatsen te voegen in plaats daarvan de startplaats van je game betreden.

  • Als je Beperkt tot dezelfde universum kiest, kunnen spelers zich alleen bij niet-startplaatsen voegen via teleportaties binnen je games. Deze instelling staat zowel client- als server-geïnitieerde teleportaties toe.

    Dit is een goede keuze als je een legacy game hebt die je niet wilt migreren naar veilige teleportaties.

  • Als je Veilig binnen universum alleen kiest, kunnen spelers zich alleen bij niet-startplaatsen voegen via server-geïnitieerde teleportaties binnen deze game.

    Dit is een goede keuze als je game een strikt voortgangssysteem heeft voordat spelers toegang krijgen tot bepaalde gebieden. Het is ook een goede keuze als je game een testplaats heeft waar spelers geen toegang toe zouden moeten hebben of voor plaatsen die uitsluitend gebruik maken van gereserveerde servers.

Migreer naar veilige teleportaties

Als je een bestaande game hebt die client-side teleportaties gebruikt en je wilt server-geïnitieerde teleportaties vereisen, is het doel om alle teleportlogica uit client-scripts en in serverscripts te verplaatsen:

  1. Zoek alle client-scripts die Teleport() aanroepen.
  2. Verander deze aanroepen in plaats daarvan om remote events te activeren. Alternatief kun je de aanroepen veranderen in plaats daarvan gebruik te maken van ProximityPrompts, ClickDetectors, of zelfs gewoon het BasePart.Touched evenement.
  3. Herimplement de teleport in een serverscript met TeleportAsync().
  4. Wanneer er geen Teleport() aanroepen meer bestaan, verander Toegangscontrole voor Plaatsen naar Veilig.

Maak aangepaste teleportschermen

Wanneer een gebruiker een teleportatie activeert, ziet hij het standaard Roblox laadscherm terwijl hij wacht tot de nieuwe plaats is geladen. Indien gewenst, kun je een aangepast teleportscherm toevoegen door TeleportService:SetTeleportGui() aan te roepen op de client.

Het volgende voorbeeld stelt een gepersonaliseerde ScreenGui in vanuit ReplicatedStorage. Alle scripts binnen de ScreenGui worden niet uitgevoerd.

local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local teleportGui = ReplicatedStorage.TeleportGui
TeleportService:SetTeleportGui(teleportGui)

Pas teleportopties aan

Je kunt teleportaties aanpassen, zoals gebruikers naar een specifieke server teleporteren en gebruikersgegevens samen met teleportaties verzenden, door de TeleportOptions instantie in te stellen en deze door te geven aan de TeleportService:TeleportAsync() methode.

Teleporteer naar specifieke servers

Om gebruikers naar specifieke servers te teleporteren, stel je de doelsserver in met TeleportOptions en geef je deze door aan de TeleportAsync() methode. Als je geen server opgeeft, worden gebruikers naar een openbare server geteleporteerd; de informatie van de eerste gebruiker in de lijst wordt gebruikt voor matchmaking.

Om gebruikers naar een specifieke openbare server te teleporteren, stel je de TeleportOptions.ServerInstanceId eigenschap in als een geldige instantie-ID, wat een unieke identificatie is voor een openbare server.

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

Om gebruikers naar een gereserveerde server te teleporteren, genereer je een GUID met HttpService:GenerateGUID(false) en stel je TeleportOptions.ReservedServerId in. De eerste teleportatie met een nieuwe ID creëert de server; het hergebruiken van dezelfde ID leidt volgende teleportaties naar die server.

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)

Om gebruikers naar een VIP (privé) server te teleporteren, stel je TeleportOptions.VipServerId in op de DataModel.PrivateServerId van de doel VIP server:

-- De PrivateServerId van de bestemming VIP server, bijvoorbeeld gedragen
-- in de teleportgegevens van de speler of gelezen uit een gegevensopslag
local vipServerId = player:GetJoinData().TeleportData.vipServerId
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.VipServerId = vipServerId

Wanneer je gebruikers naar een andere plaats binnen dezelfde ervaring teleport, stel je TeleportOptions.VipServerId in op game.PrivateServerId als je wilt dat ze in dezelfde VIP server blijven:

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

Voor meer informatie over gereserveerde en VIP server teleportpatronen, inclusief het hergebruiken van server-ID's en migreren van legacy toegangscodes, zie Teleport naar privéservers.

Stuur gebruikersgegevens mee met teleportaties

Het teleporteren van een gebruiker tussen plaatsen verwerpt alle lokale gegevens die aan die gebruiker zijn gekoppeld. Je kunt de volgende benaderingen gebruiken om gegevenspersistentie tussen plaatsen te beheren:

  • Als je game veilige gebruikersgegevens gebruikt, zoals in-game valuta of inventaris, implementeer dan gegevensopslag of geheugenopslag om gegevens van plaats naar plaats te behouden.

  • Om basis niet-veilige gegevens van plaats naar plaats te verzenden, roep je TeleportOptions:SetTeleportData() aan voordat je deze doorgeeft aan TeleportAsync(). Verzend geen veilige gegevens met deze methode; de gegevens zijn zichtbaar voor de client en niet versleuteld.

local teleportData = {
randomNumber = RNG:NextInteger(1, 100),
}
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions:SetTeleportData(teleportData)

Om alle gegevens op te halen wanneer een gebruiker aankomt op de nieuwe plaats na een teleport, gebruik je de Player:GetJoinData() functie, die een woordenboek retourneert met een TeleportData sleutel.

local Players = game:GetService("Players")
local function onPlayerAdded(player)
local joinData = player:GetJoinData()
local teleportData = joinData.TeleportData
local randomNumber = teleportData.randomNumber
print(player.Name .. " is binnengekomen met het nummer " .. randomNumber)
end
Players.PlayerAdded:Connect(onPlayerAdded)

Om alleen de teleportgegevens aan de client op te halen, kun je TeleportService:GetLocalPlayerTeleportData() gebruiken.

Test teleportaties in Studio

Je kunt TeleportAsync() teleportaties testen in de Test en Team Test modi van Studio zonder je ervaring te publiceren. Wanneer een teleport tijdens een test wordt uitgevoerd, opent de bestemmingsplaats als een nieuwe testserver, zodat je zowel de oorsprong als de bestemmingsplaatsen in Studio kunt debuggen. Studio-tools zoals serverinspectie, de debugger (inclusief breakpoints) en de apparaat-simulator worden overgedragen naar de bestemmingsplaats. Je kunt ook teleportaties testen in Build en via playtestautomatisering in de Studio MCP server.

Bekende beperkingen

Een paar gedragingen verschillen tussen testen en productie:

  • PrivateServerId en JobId: In Test modus zijn beide altijd leeg, zelfs voor privéservers. In Team Test is elke server privé, dus PrivateServerId is nooit leeg, zelfs niet voor teleportaties naar openbare servers. Code die controleert of PrivateServerId leeg is, gedraagt zich anders in Team Test dan in productie.
  • ReservedServerId vs. PrivateServerId: Deze waarden kunnen verschillen in Team Test, hoewel ze overeenkomen in productie. Om meer spelers naar dezelfde gereserveerde server te sturen, hergebruik je de originele ReservedServerId, niet de PrivateServerId van de bestemmingsserver.
  • VIP teleportaties: Teleportaties die VipServerId gebruiken, falen in testen omdat Team Test servers geen eigenaar hebben.
  • Alleen dezelfde ervaring: Je kunt alleen teleporteren tussen plaatsen die de GameId van de startplaats delen.
  • Niet-ondersteunde methoden: GetPlayerPlaceInstanceAsync() werkt niet in testen.

Behandel mislukte teleportaties

Net als bij elke API-aanroep die netwerkverzoeken omvat, kunnen teleportaties mislukken en een fout genereren. Wikkel ze in beschermde aanroepen (pcall()). Sommige mislukkingen profiteren van herhalingen, vooral die met gereserveerde servers, dus we raden aan om een aantal keren opnieuw te proberen bij een mislukking.

Zelfs als een aanroep succesvol is en de teleportatie wordt geïnitieerd, kan deze nog steeds op het laatste moment mislukken zonder een fout te genereren en de gebruiker in de server achterlaten. Wanneer dit gebeurt, wordt het TeleportService.TeleportInitFailed evenement geactiveerd.

Het volgende voorbeeld ModuleScript retourneert een enkele SafeTeleport functie die spelers in een beschermde aanroep met herhalingslogica teleporteert. Het heeft ook een handleFailedTeleport functie om om te gaan met situaties waarin de aanroep succesvol was, maar de teleportatie niet plaatsvond.

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 -- definieer pcall resultaten buiten de lus zodat resultaten later kunnen worden gerapporteerd
repeat
success, result = pcall(function()
return TeleportService:TeleportAsync(placeId, players, options) -- teleport de gebruiker in een beschermde aanroep om fouten te voorkomen
end)
attemptIndex += 1
if not success then
task.wait(RETRY_DELAY)
end
until success or attemptIndex == ATTEMPT_LIMIT -- stop met proberen te teleporteren als de aanroep succesvol was, of als de herhalingslimiet is bereikt
if not success then
warn(result) -- print de reden van de mislukking naar de 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
-- als de teleportatie ongeldig is, rapporteer de fout in plaats van opnieuw te proberen
error(("Ongeldige teleportatie [%s]: %s"):format(teleportResult.Name, errorMessage))
end
SafeTeleport(targetPlaceId, {player}, teleportOptions)
end
TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)
return SafeTeleport

De SafeTeleport functie ontvangt dezelfde argumenten als de TeleportAsync() functie. Je kunt het volgende script gebruiken met de SafeTeleport functie om teleportaties vanuit elke plek in je game uit te voeren:

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, het Roblox-logo en Powering Imagination behoren tot onze geregistreerde en niet-geregistreerde handelsmerken in de VS en andere landen.