Téléportation entre les 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 les utilisateurs entre les 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 :

• L'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 optionnelle de TeleportOptions qui contient des propriétés personnalisées pour l'appel de 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 pouvez utiliser un événement BasePart.Touched ou un événement 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 que juste l'individu.

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 contrôle les joueurs se téléportant dans 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 depuis n'importe quel jeu, y compris des liens profonds, des invitations de jeu, rejoindre un ami, et plus encore.

  C'est un bon choix si votre jeu a 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 non de départ rejoindront à la place le lieu de départ de votre jeu.

• Si vous choisissez Limité au même univers, les joueurs ne peuvent rejoindre des lieux non de départ que par des téléportations au sein de vos jeux. Ce paramètre permet des téléportations initiées à la fois par le client et par 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 au sein de l'univers, les joueurs ne peuvent rejoindre des lieux non de départ que par des téléportations initiées par le serveur au sein de 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 déclencher 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 le 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 que le nouveau lieu se charge. 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 du 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, telles que téléporter des utilisateurs vers un serveur spécifique et envoyer des données utilisateur avec les 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 en utilisant 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 les téléportations

Téléporter un utilisateur entre des lieux supprime 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 utilisateur 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 d'un lieu à l'autre.

• Pour envoyer des données non sécurisées de base d'un lieu à l'autre, appelez TeleportOptions:SetTeleportData() avant de le passer à TeleportAsync(). Ne passez pas de données sécurisées en utilisant cette méthode ; les données sont visibles par le client et non chiffrées.

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

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

Pour récupérer toutes les données lorsqu'un utilisateur arrive au nouveau lieu après une téléportation, utilisez la fonction Player:GetJoinData(), qui renvoie 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 nombre " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Pour récupérer uniquement les données de téléportation côté 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()). Certains échecs bénéficient de nouvelles tentatives, en particulier ceux 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, elle peut toujours échouer à la dernière minute 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 les 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'a pas eu lieu.

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 pcall en dehors de la boucle pour 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, rapportez 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)