Si vous voulez construire une expérience avec de nombreux endroits distincts, tels qu'un monde fantastique avec plusieurs villes, châteaux, donjons et une forêt vaste, vous pouvez utiliser TeleportService pour permettre aux utilisateurs de se téléporter entre les endroits dans un univers, des serveurs ou même à une autre expérience.
TeleportService ne prend pas en charge le test de jeu dans Roblox Studio. Vous devez publier l'expérience et l'utiliser sur l'application Roblox pour tester.
Configurer la téléportation
Pour activer la téléportation dans votre expérience, utilisez TeleportService:TeleportAsync() . La méthode accepte trois paramètres :
- Le PlaceId pour les utilisateurs à téléporter.
- Une tableau contenant les Player instances représentant les utilisateurs à téléportation.
- Une instance TeleportOptions optionnelle qui contient des propriétés personnalisées pour le TeleportAsync() appel.
Vous ne pouvez appeler que TeleportAsync() des scripts côté serveur. Cette limite réduit l'exploitation côté client. Si nécessaire, vous pouvez appeler Teleport() des scripts côté client, mais TeleportAsync() est la méthode recommandée.
Si vous voulez prendre des précautions lors de la gestion des erreurs lors de la configuration de la téléportation, voir Gestion des téléports échoués .
Activer la téléportation entre expériences
Pour des raisons de sécurité, le téléportation d'un utilisateur de votre expérience vers une autre expérience appartenant à d'autres, ou le contraire, échoue par défaut. Pour activer le téléportation d'expérience croisée, ouvrez Paramètres du jeu > Sécurité et activez Permettre les téléportations de tiers sur Studio.
Créer des écrans de téléport personnalisés
Lorsqu'un utilisateur déclenche un téléportation, il voit l'écran de chargement standard Roblox lorsqu'il attend que le nouvel endroit se charge. Vous pouvez ajouter un écran de téléport personnalisé pour
Personnalisation des options de téléportation
Vous pouvez personnaliser les téléportations, telles que téléporter les utilisateurs sur un serveur spécifique et envoyer les données de l'utilisateur avec les téléportations , en configurant l'instance TeleportOptions et en le passant à la méthode 1> Class.TeleportService:TeleportAsync() ».
Téléportation vers des serveurs spécifiques
Pour téléporter les utilisateurs sur des serveurs spécifiques, définissez le serveur cible en utilisant TeleportOptions et transmettez-le à la méthode TeleportService:TeleportAsync(). Si vous n'avez pas spécifié de serveur, les utilisateurs sont téléportés dans un serveur public match. Les informations du premier utilisateur de la liste sont utilisées pour matcher à ce serveur public.
Pour téléporter les utilisateurs à un serveur public spécifique, définissez la propriété TeleportOptions.ServerInstanceId comme un ID d'instance valide, qui est un identifiant unique pour un serveur public.
Pour téléporter les utilisateurs vers un serveur réservé spécifique, définissez un code valide TeleportOptions.ReservedServerAccessCode, qui est un code unique pour entrer dans un serveur réservé.
Pour téléporter les utilisateurs sur un nouveau serveur réservé, définissez TeleportOptions.ShouldReserveServer sur vrai.
Envoyer des données de l'utilisateur avec les téléports
Téléporter un utilisateur entre des lieux supprime tous les données locales associées à cet utilisateur. Vous pouvez utiliser les approches suivantes pour gérer la persistance des données entre les lieux.
Si votre expérience utilise des données d'utilisateur sécurisées comme de la monnaie dans l'expérience ou de l'inventaire, implémentez stores de données ou stores de mémoire pour conserver les données du lieu à la emplacement.
Pour envoyer des données de base non sécurisées d'un lieu à un emplacement, appelez TeleportOptions:SetTeleportData() avant de le transmettre à TeleportAsync().
Ne passez pas de données sécurisées à l'aide de TeleportOptions:SetTeleportData() parce qu'il y a un risque d'exploitation.
Pour obtenir toutes les données d'un utilisateur arrivant d'un téléport sur le serveur, utilisez la fonction Player:GetJoinData(), qui renvoie un dictionnaire y compris les données associées à l'utilisateur.
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)
Pour récupérer uniquement les données de téléportation sur le client, vous pouvez utiliser TeleportService:GetLocalPlayerTeleportData() .
Gestion des téléports échoués
Comme n'importe quelle demande d'API qui implique des demandes de réseau, les téléports peuvent échouer et lancer une erreur. Même si un appel réussit et que le téléportateur s'initie, il peut toujours échouer au dernier moment sans lancer d'erreur et laisser l'utilisateur dans le serveur. Lorsque cela se produit, il déclenche TeleportService.TeleportInitFailed .
Wrap teleports in a protected call ( pcall() ) and retry if it fails. The following example ModuleScript définit une fonction SafeTeleport pour téléporter l'utilisateur dans un appel protégé et une fonction 1> HandleFailedTeleport1> pour réessayer les téléports qui sont des hiccups uniques et
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 -- définir les résultats pcall en dehors de la boucle afin que les rapports puissent être soumis plus tard
repeat
success, result = pcall(function()
return TeleportService:TeleportAsync(placeId, players, options) -- téléportez l'utilisateur dans un appel protégé pour éviter les erreurs
end)
attemptIndex += 1
if not success then
task.wait(RETRY_DELAY)
end
until success or attemptIndex == ATTEMPT_LIMIT -- arrêtez de tentér de vous téléporter si le appel a été réussi, ou si la limite d'essai a été atteinte
if not success then
warn(result) -- imprimer la raison d'échec pour sortie
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
-- si la téléportation est invalide, signaler l'erreur au lieu de réessayer
error(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
end
SafeTeleport(targetPlaceId, {player}, teleportOptions)
end
TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)
return SafeTeleport
La fonction SafeTeleport reçoit les mêmes arguments que la fonction TeleportAsync(). Vous pouvez utiliser le suivant ModuleScript avec la fonction 1>SafeTeleport1> pour exécuter des téléports à partir de n'importe où dans votre expérience pour réduire les téléports échoués.