Teleportar entre lugares

Muitos jogos são subdivididos em vários lugares, como um mundo de fantasia com cidades, castelos, masmorras e uma vasta floresta. Use TeleportService para teleportar usuários entre lugares, para diferentes servidores ou até mesmo para outros jogos.

Teleportar jogadores

Para teleportar jogadores, use TeleportService:TeleportAsync(). Este método aceita três parâmetros:

• O PlaceId para o qual os usuários devem ser teleportados.
• Um array contendo as instâncias de Player que você deseja teleportar.
• Uma instância opcional de TeleportOptions que contém propriedades personalizadas para a chamada TeleportAsync().

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

local TARGET_PLACE_ID = 12345678901234 -- substitua pelo seu próprio
local playerToTeleport = Players:GetPlayers()[1] -- pega o primeiro usuário no jogo

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

Para obter os jogadores apropriados que devem ser teleportados, você pode usar um evento BasePart.Touched ou ProximityPrompt.Triggered para obter um Player individual. Então você pode verificar se o jogador faz parte de uma equipe (Player.Team) ou de um grupo (Player.PartyId). Finalmente, você pode usar Team:GetPlayers() ou SocialService:GetPlayersByPartyId() se quiser teleportar todo o grupo em vez do indivíduo.

Configurar teleportação segura

Três configurações controlam a segurança do teleport.

Controle de Acesso para Lugares controla os jogadores teleportando para o seu jogo e é a configuração mais crítica para prevenir fraudes baseadas em teleportes.

• Se você escolher Totalmente aberto, os jogadores podem se juntar a qualquer lugar no seu jogo através de teleportes de qualquer jogo, incluindo links profundos, convites para jogos, juntando-se a um amigo e mais.

  Esta é uma boa escolha se o seu jogo possui vários lugares e você quer que amigos possam facilmente se juntar uns aos outros, independentemente de qual lugar estão. Se você não escolher esta opção, jogadores que tentarem se juntar a amigos em lugares não iniciais se juntarão ao lugar inicial do seu jogo.

• Se você escolher Limitado ao mesmo universo, os jogadores só podem se juntar a lugares não iniciais através de teleportes dentro dos seus jogos. Esta configuração permite tanto teleportes iniciados pelo cliente quanto pelo servidor.

  Esta é uma boa escolha se você tem um jogo legado que não deseja migrar para teleportes seguros.

• Se você escolher Seguro apenas dentro do universo, os jogadores só podem se juntar a lugares não iniciais através de teleportes iniciados pelo servidor dentro deste jogo.

  Esta é uma boa escolha se o seu jogo possui um sistema de progressão rígido antes que os jogadores possam acessar certas áreas. Também é uma boa escolha se o seu jogo possui um lugar de teste que os jogadores não devem ter acesso ou para lugares que utilizam exclusivamente servidores reservados.

Migrar para teleportes seguros

Se você tem um jogo existente que utiliza teleportes do lado do cliente e deseja exigir teleportes iniciados pelo servidor, o objetivo é mover toda a lógica de teleportação para fora dos scripts do cliente e para dentro dos scripts do servidor:

1. Encontre todos os scripts do cliente que chamam Teleport().
2. Altere essas chamadas para disparar eventos remotos. Como alternativa, você pode alterar as chamadas para usar ProximityPrompts, ClickDetectors, ou até mesmo apenas o evento BasePart.Touched.
3. Reimplemente o teleport em um script de servidor usando TeleportAsync().
4. Quando não houver mais chamadas Teleport(), altere o Controle de Acesso para Lugares para Seguro.

Criar telas de teleportação personalizadas

Quando um usuário ativa um teleport, ele vê a tela de carregamento padrão do Roblox enquanto espera o novo lugar carregar. Se desejado, você pode adicionar uma tela de teleportação personalizada chamando TeleportService:SetTeleportGui() no cliente.

O seguinte exemplo define um ScreenGui personalizado do ReplicatedStorage. Quaisquer scripts dentro do ScreenGui não serão executados.

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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

Personalizar opções de teleportação

Você pode personalizar teleportações, como teleportar usuários para um servidor específico e enviar dados do usuário junto com teleportes, definindo a instância TeleportOptions e passando-a para o método TeleportService:TeleportAsync().

Teleportar para servidores específicos

Para teleportar usuários para servidores específicos, defina o servidor alvo usando TeleportOptions e passe-o para o método TeleportAsync(). Se você não especificar um servidor, os usuários serão teleportados para um servidor público; as informações do primeiro usuário na lista são usadas para emparelhamento.

Para teleportar usuários para um servidor público específico, defina a propriedade TeleportOptions.ServerInstanceId como um ID de instância válido, que é um identificador exclusivo para um servidor público.

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

Para teleportar usuários para um servidor reservado específico, defina um TeleportOptions.ReservedServerAccessCode válido, que é um código exclusivo para entrar em um servidor reservado.

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

Para teleportar usuários para um novo servidor reservado, defina TeleportOptions.ShouldReserveServer como verdadeiro.

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

Enviar dados do usuário junto com teleportes

Teleportar um usuário entre lugares descarta qualquer dado local associado a esse usuário. Você pode usar as seguintes abordagens para lidar com a persistência de dados entre lugares:

• Se o seu jogo utiliza dados seguros do usuário, como moeda do jogo ou inventário, implemente armazenamentos de dados ou armazenamentos de memória para manter dados de lugar para lugar.

• Para enviar dados não seguros básicos de lugar para lugar, chame TeleportOptions:SetTeleportData() antes de passá-lo para TeleportAsync(). Não passe dados seguros usando este método; os dados são visíveis para o cliente e não criptografados.

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

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

Para recuperar todos os dados quando um usuário chega ao novo lugar após um teleport, use a função Player:GetJoinData(), que retorna um dicionário com uma chave 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 .. " entrou com o número " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Para recuperar apenas os dados de teleport no cliente, você pode usar TeleportService:GetLocalPlayerTeleportData().

Lidar com teleportes falhados

Como qualquer chamada de API que envolve solicitações de rede, os teleportes podem falhar e gerar um erro. Envolva-os em chamadas protegidas (pcall()). Algumas falhas se beneficiam de tentativas, particularmente aquelas envolvendo servidores reservados, então recomendamos tentar novamente um certo número de vezes em caso de falha.

Mesmo que uma chamada seja bem-sucedida e o teleport seja iniciado, ele ainda pode falhar no último momento sem gerar um erro e deixar o usuário no servidor. Quando isso acontece, ele aciona o evento TeleportService.TeleportInitFailed.

O seguinte exemplo ModuleScript retorna uma única função SafeTeleport que teleportará jogadores em uma chamada protegida com lógica de tentativa. Também possui uma função handleFailedTeleport para lidar com situações nas quais a chamada foi bem-sucedida, mas o teleport não ocorreu.

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 -- define resultados de pcall fora do loop para que os resultados possam ser relatados mais tarde

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- teleportar o usuário em uma chamada protegida para evitar erro
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- parar de tentar teleportar se a chamada foi bem-sucedida ou se o limite de tentativas foi alcançado

    if not success then
        warn(result) -- imprimir a razão da falha na saída
    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
        -- se o teleport for inválido, relatar o erro em vez de tentar novamente
        error(("Teleport inválido [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

A função SafeTeleport recebe os mesmos argumentos que a função TeleportAsync(). Você pode usar o seguinte script com a função SafeTeleport para realizar teleportes de qualquer lugar no seu jogo:

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)