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 vaste forêt, vous pouvez utiliser TeleportService pour permettre aux utilisateurs de se téléporter entre les lieux dans un univers, des serveurs ou même vers 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 le test.
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 à se téléporter.
- Un tableau contenant les instances Player représentant les utilisateurs à téléportation.
- Une instance optionnelle TeleportOptions qui contient des propriétés personnalisées pour l'appel TeleportAsync().
Vous ne pouvez appeler que TeleportAsync() du côté du serveur à partir des scripts côté serveur.Cette limitation réduit l'exploitation côté client.Si nécessaire, vous pouvez appeler Teleport() du côté du client, mais TeleportAsync() est la méthode recommandée.
Si vous voulez prendre des précautions de gestion des erreurs lors de la configuration de la téléportation, voir comment gérer les téléportations échouées.
Activer la téléportation d'expérience croisée
Pour des raisons de sécurité, téléporter un utilisateur de votre expérience vers une autre expérience appartenant à d'autres ou vice versa échoue par défaut.Pour activer la téléportation transexpérience, ouvrez paramètres du jeu > sécurité et activez autoriser les téléportations de tiers sur Studio.
Créer des écrans de téléportation personnalisés
Lorsqu'un utilisateur déclenche une téléportation, il voit l'écran de chargement standard de Roblox en attendant que le nouvel endroit se charge.Vous pouvez ajouter un écran de téléportation personnalisé pour améliorer l'immersion pour les utilisateurs en appelant TeleportService:SetTeleportGui() sur le client et en passant par le ScreenGui avant de téléporter l'utilisateur.L'exemple suivant définit un écran de chargement personnalisé ScreenGui situé dans ReplicatedStorage lorsqu'un téléport se produit.Il n'exécute aucun script à l'intérieur du ScreenGui.
Personnaliser les options de téléportation
Vous pouvez personnaliser les téléportations, telles que téléporter les utilisateurs vers un serveur spécifique et envoyer les données utilisateur avec les téléportations , en définissant l'instance et en la passant à la méthode ».
Téléportation vers des serveurs spécifiques
Pour téléporter les utilisateurs vers des serveurs spécifiques, définissez le serveur cible en utilisant TeleportOptions et passez-le à la méthode TeleportService:TeleportAsync().Si vous ne spécifiez pas de serveur, les utilisateurs sont téléportés dans un serveur public matché.Les informations du premier utilisateur dans la liste sont utilisées pour faire correspondre à ce serveur public.
Pour téléporter les utilisateurs vers un serveur public spécifique, définissez la propriété TeleportOptions.ServerInstanceId comme ID de 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 vers un nouveau serveur réservé, définissez TeleportOptions.ShouldReserveServer à vrai.
Envoyer des données d'utilisateur avec des téléportations
Téléporter un utilisateur entre les lieux rejette toutes 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 utilisateur sécurisées comme de la monnaie ou de l'inventaire dans l'expérience, mettez en œuvre stores de données ou stores de mémoire pour maintenir les données d'un endroit à l'emplacement.
Pour envoyer des données de base non sécurisées d'un endroit à un emplacement, appelez TeleportOptions:SetTeleportData() avant de le transmettre à TeleportAsync().
Ne pas transmettre de données sécurisées en utilisant TeleportOptions:SetTeleportData() car cela comporte le 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 comprenant 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() .
Gérer les téléportations échouées
Comme toute autre demande d'API qui implique des demandes réseau, les téléports peuvent échouer et lancer une erreur.Enroupez-les dans des appels protégés ( pcall() ).Certains échecs bénéficient de réessais, notamment ceux impliquant des serveurs réservés, donc nous recommandons de réessayer un certain nombre de fois sur les échecs.
Même si un appel réussit et que la téléportation est initiée, il peut encore échouer au dernier moment sans lancer d'erreur et laisser l'utilisateur sur le serveur.Lorsque cela se produit, cela déclenche l'événement TeleportService.TeleportInitFailed.
L'exemple suivant ModuleScript définit une fonction SafeTeleport pour téléporter l'utilisateur dans un appel protégé avec une logique de réessai.Il a également une fonction handleFailedTeleport pour gérer les situations dans lesquelles l'appel a réussi, mais le téléport n'a pas survernir.
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 de l'appel à l'extérieur de la boucle afin que les résultats puissent être rapportés plus tard
repeat
success, result = pcall(function()
return TeleportService:TeleportAsync(placeId, players, options) -- téléporter l'utilisateur dans un appel protégé pour empêcher les erreurs
end)
attemptIndex += 1
if not success then
task.wait(RETRY_DELAY)
end
until success or attemptIndex == ATTEMPT_LIMIT -- arrêter de tenter de se téléporter si l'appel a réussi, ou si la limite de réessai a été atteinte
if not success then
warn(result) -- imprimer la raison de l'échec à l'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, signalez 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 SafeTeleport pour effectuer des téléportations depuis n'importe où dans votre expérience pour réduire les téléportations échouées.