Téléportation entre des lieux

De nombreux jeux sont subdivisés en plusieurs lieux, tels qu'un monde fantastique avec des villes, des châteaux, des donjons et une vaste forêt. Utilisez TeleportService pour téléporter des utilisateurs entre des lieux, vers différents serveurs, ou même vers d'autres jeux.

Téléporter des joueurs

Pour téléporter des joueurs, utilisez TeleportService:TeleportAsync(). Cette méthode accepte trois paramètres :

• Le PlaceId vers lequel les utilisateurs doivent être téléportés.
• Un tableau contenant les instances de Player que vous souhaitez téléporter.
• Une instance TeleportOptions optionnelle contenant des propriétés personnalisées pour l'appel TeleportAsync().

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

local TARGET_PLACE_ID = 12345678901234 -- remplacez par le vôtre
local playerToTeleport = Players:GetPlayers()[1] -- obtenir le premier utilisateur dans le jeu

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

Pour obtenir les joueurs appropriés à téléporter, vous pourriez utiliser un événement BasePart.Touched ou ProximityPrompt.Triggered pour obtenir un Player individuel. Ensuite, vous pouvez vérifier si le joueur fait partie d'une équipe (Player.Team) ou d'un groupe (Player.PartyId). Enfin, vous pouvez utiliser Team:GetPlayers() ou SocialService:GetPlayersByPartyId() si vous souhaitez téléporter l'ensemble du groupe plutôt qu'un seul.

Configurer la téléportation sécurisée

Trois paramètres gèrent la sécurité de la téléportation.

Contrôle d'Accès pour les Lieux gère les téléportations des joueurs vers votre jeu et est le paramètre le plus critique pour prévenir les exploits basés sur la téléportation.

• Si vous choisissez Entièrement ouvert, les joueurs peuvent rejoindre n'importe quel lieu de votre jeu via des téléportations de n'importe quel jeu, y compris des liens profonds, des invitations au jeu, rejoindre un ami, et plus encore.

  C'est un bon choix si votre jeu contient plusieurs lieux et que vous souhaitez que les amis puissent facilement se rejoindre peu importe le lieu dans lequel ils se trouvent. Si vous ne choisissez pas cette option, les joueurs qui essaient de rejoindre leurs amis dans des lieux qui ne sont pas le lieu de départ rejoindront plutôt le lieu de départ de votre jeu.

• Si vous choisissez Limité au même univers, les joueurs ne peuvent rejoindre des lieux qui ne sont pas le lieu de départ que via des téléportations de vos jeux. Ce paramètre permet des téléportations initiées à la fois par le client et le serveur.

  C'est un bon choix si vous avez un jeu hérité que vous ne souhaitez pas migrer vers des téléportations sécurisées.

• Si vous choisissez Sécurisé uniquement dans l'univers, les joueurs ne peuvent rejoindre des lieux qui ne sont pas le lieu de départ que par des téléportations initiées par le serveur dans ce jeu.

  C'est un bon choix si votre jeu a un système de progression strict avant que les joueurs puissent accéder à certaines zones. C'est également un bon choix si votre jeu a un lieu de test auquel les joueurs ne devraient pas avoir accès ou pour des lieux qui utilisent exclusivement des serveurs réservés.

Migrer vers des téléportations sécurisées

Si vous avez un jeu existant qui utilise des téléportations côté client et que vous souhaitez exiger des téléportations initiées par le serveur, l'objectif est de déplacer toute la logique de téléportation des scripts clients vers des scripts serveurs :

1. Trouvez tous les scripts clients qui appellent Teleport().
2. Changez ces appels pour qu'ils déclenchent plutôt des événements distants. Alternativement, vous pouvez changer les appels pour utiliser ProximityPrompts, ClickDetectors, ou même simplement l'événement BasePart.Touched.
3. Réimplémentez la téléportation dans un script serveur en utilisant TeleportAsync().
4. Lorsque plus aucun appel Teleport() n'existe, changez Contrôle d'Accès pour les Lieux en Sécurisé.

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 le chargement du nouveau lieu. Si vous le souhaitez, vous pouvez ajouter un écran de téléportation personnalisé en appelant TeleportService:SetTeleportGui() sur le client.

L'exemple suivant définit un ScreenGui personnalisé à partir de ReplicatedStorage. Tous les scripts au sein de ScreenGui ne s'exécutent pas.

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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

Personnaliser les options de téléportation

Vous pouvez personnaliser les téléportations, comme téléporter des utilisateurs vers un serveur spécifique et envoyer des données utilisateur avec des téléportations, en définissant l'instance TeleportOptions et en la passant à la méthode TeleportService:TeleportAsync().

Téléporter vers des serveurs spécifiques

Pour téléporter des utilisateurs vers des serveurs spécifiques, définissez le serveur cible à l'aide de TeleportOptions et passez-le à la méthode TeleportAsync(). Si vous ne spécifiez pas de serveur, les utilisateurs sont téléportés dans un serveur public ; les informations du premier utilisateur de la liste sont utilisées pour le matchmaking.

Pour téléporter des utilisateurs vers 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.

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

Pour téléporter des utilisateurs vers un serveur réservé spécifique, définissez un TeleportOptions.ReservedServerAccessCode valide, qui est un code unique pour entrer dans un serveur réservé.

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerAccessCode = reservedServerCode

Pour téléporter des utilisateurs vers un nouveau serveur réservé, définissez TeleportOptions.ShouldReserveServer sur true.

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

Envoyer des données utilisateur avec des téléportations

Téléporter un utilisateur entre des lieux annule 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 jeu utilise des données sécurisées comme la monnaie du jeu ou l'inventaire, implémentez des magasins de données ou des magasins de mémoire pour maintenir les données de lieu à lieu.

• Pour envoyer des données non sécurisées de lieu à lieu, appelez TeleportOptions:SetTeleportData() avant de les passer à TeleportAsync(). Ne passez pas de données sécurisées par cette méthode ; les données sont visibles par le client et non cryptées.

local teleportData = {
    randomNumber = RNG:NextInteger(1, 100),
}

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions:SetTeleportData(teleportData)

Pour récupérer toutes les données lorsque l'utilisateur arrive au nouveau lieu après un téléport, utilisez la fonction Player:GetJoinData(), qui retourne un dictionnaire avec une clé 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 .. " a rejoint avec le numéro " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Pour récupérer uniquement les données de téléport sur le client, vous pouvez utiliser TeleportService:GetLocalPlayerTeleportData().

Gérer les téléportations échouées

Comme tout appel d'API impliquant des requêtes réseau, les téléportations peuvent échouer et générer une erreur. Enveloppez-les dans des appels protégés (pcall()). Certaines défaillances bénéficient de nouvelles tentatives, en particulier celles impliquant des serveurs réservés, donc nous recommandons de réessayer un certain nombre de fois en cas d'échec.

Même si un appel réussit et que la téléportation s'initie, cela peut toujours échouer au dernier moment sans générer 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 renvoie une seule fonction SafeTeleport qui téléporte des joueurs 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 la téléportation n'est pas survenue.

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 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 éviter les erreurs
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- arrêter d'essayer de 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 dans la 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(("Téléportation invalide [%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 script suivant avec la fonction SafeTeleport pour effectuer des téléportations depuis n'importe où dans votre jeu :

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)