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 onde 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 de 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] -- obtenha o primeiro usuário no jogo

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

Para obter os jogadores apropriados para teleportar, você pode usar um evento BasePart.Touched ou um evento ProximityPrompt.Triggered para obter um Player individual. Em seguida, você pode verificar se o jogador faz parte de uma equipe (Player.Team) ou festa (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 lidam com a segurança do teleport.

Controle de Acesso para Lugares controla jogadores teleportando para o seu jogo e é a configuração mais crítica para prevenir exploits baseados em teleport.

• Se você escolher Totalmente aberto, os jogadores podem entrar em qualquer lugar no seu jogo através de teleportações de qualquer jogo, incluindo links diretos, convites de jogo, entrar em um amigo e mais.

  Esta é uma boa escolha se seu jogo tem vários lugares e você quer que amigos possam facilmente se juntar, não importa em qual lugar estejam. Se você não escolher essa opção, jogadores que tentarem se juntar a seus amigos em lugares que não são iniciais entrarão no lugar inicial do seu jogo.

• Se você escolher Limitado ao mesmo universo, os jogadores só podem entrar em lugares que não são iniciais através de teleportações dentro dos seus jogos. Esta configuração permite tanto teleportações iniciadas pelo cliente quanto pelo servidor.

  Esta é uma boa escolha se você tem um jogo legado que não deseja migrar para teleportações seguras.

• Se você escolher Seguro apenas dentro do universo, os jogadores só podem entrar em lugares que não são iniciais através de teleportações iniciadas pelo servidor dentro deste jogo.

  Esta é uma boa escolha se seu jogo tem um sistema de progressão rigoroso antes que os jogadores possam acessar certas áreas. Também é uma boa escolha se seu jogo tem um lugar de teste que os jogadores não deveriam ter acesso ou para lugares que usam exclusivamente servidores reservados.

Migrar para teleportações seguras

Se você tem um jogo existente que usa teleportações do lado do cliente e deseja exigir teleportações iniciadas pelo servidor, o objetivo é mover toda a lógica de teleportação para fora dos scripts do cliente e para os scripts do servidor:

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

Criar telas de teleportação personalizadas

Quando um usuário aciona 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 a partir de ReplicatedStorage. Quaisquer scripts dentro do ScreenGui não sã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 os teleports, definindo a instância de 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 são teleportados para um servidor público; as informações do primeiro usuário na lista são usadas para matchmaking.

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 único 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 único 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 os teleports

Teleportar um usuário entre lugares descarta quaisquer dados locais associados a esse usuário. Você pode usar as seguintes abordagens para lidar com a persistência de dados entre lugares:

• Se seu jogo utiliza dados seguros do usuário, como moeda do jogo ou inventário, implemente data stores ou memory stores para manter dados de lugar para lugar.

• Para enviar dados básicos não seguros 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 sã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 teleportações falhadas

Como qualquer chamada de API que envolve solicitações de rede, teleportações podem falhar e gerar um erro. Envolva-as em chamadas protegidas (pcall()). Algumas falhas se beneficiam de tentativas, particularmente aquelas envolvendo servidores reservados, então recomendamos tentar algumas 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 de ModuleScript retorna uma única função SafeTeleport que teleportará jogadores em uma chamada protegida com lógica de repetição. Ele também possui uma função handleFailedTeleport para lidar com situações em que 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 os resultados do 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 erros
        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 teleportações 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)