Se você quiser construir uma experiência com muitos locais distintos, como um mundo de fantasia com várias cidades, castelos, masmorras e uma floresta vasta, você pode usar TeleportService para habilitar os usuários a se teletransportarem entre locais em um universo, servidores ou até mesmo para outra experiência.
TeleportService não suporta testes de jogo no Roblox Studio. Você deve publicar a experiência e usá-la no aplicativo Roblox para testes.
Configurar teletransporte
Para habilitar a teleportação em sua experiência, use TeleportService:TeleportAsync(). O método aceita três parâmetros:
- O PlaceId para os usuários se teletransportarem.
- Um array que contém as instâncias Player que representam os usuários para se teleportar.
- Uma instância opcional TeleportOptions que contém propriedades personalizadas para a chamada TeleportAsync().
Você só pode chamar TeleportAsync() do lado do servidor de scripts.Essa limitação reduz a exploração do lado do cliente.Se necessário, você pode chamar Teleport() do lado do cliente, mas TeleportAsync() é o método recomendado.
Se você quiser tomar precauções de manipulação de erros ao configurar a teleportação, veja como manusear falhas de teletransporte.
Ativar teletransporte de experiência cruzada
Para fins de segurança, teletransportar um usuário da sua experiência para outra experiência de propriedade de outros ou vice-versa falha por padrão.Para habilitar a teleportação de experiência cruzada, abra Configurações do Jogo > Segurança e ative Permitir Teletransportes de Terceiros no Studio.
Criar telas de teleporte personalizadas
Quando um usuário ativa um teleportar, ele vê a tela de carregamento padrão do Roblox enquanto aguarda que o novo local carregue.Você pode adicionar uma tela de teleporte personalizada para melhorar a imersão para os usuários ao chamar TeleportService:SetTeleportGui() no cliente e passar pelo ScreenGui para usar antes de teletransportar o usuário.O seguinte exemplo define um personalizado ScreenGui localizado em ReplicatedStorage como a tela de carregamento quando um teletransporte ocorre.Não executa nenhum script dentro do ScreenGui.
Personalizar opções de teletransporte
Você pode personalizar teletransportes, como teletransportar usuários para um servidor específico e enviar dados de usuário junto com teletransportes , definindo a instância TeleportOptions e passando-a para o método TeleportService:TeleportAsync().
Teletransportar para servidores específicos
Para teletransportar usuários para servidores específicos, defina o servidor alvo usando TeleportOptions e passe-o para o método TeleportService:TeleportAsync().Se você não especificar um servidor, os usuários são teletransportados para um servidor público matchmade.A informação do primeiro usuário na lista é usada para fazer matchmaking com esse servidor público.
Para teletransportar 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.
Para teletransportar usuários para um servidor reservado específico, defina um código válido TeleportOptions.ReservedServerAccessCode, que é um código único para entrar em um servidor reservado.
Para teletransportar usuários para um novo servidor reservado, defina TeleportOptions.ShouldReserveServer para verdadeiro.
Envie dados do usuário junto com teletransportes
Teletransportar um usuário entre locais descarta quaisquer dados locais associados a esse usuário.Você pode usar as seguintes abordagens para lidar com a persistência de dados entre locais.
Se a sua experiência utiliza dados seguros do usuário, como moeda ou inventário na experiência, implemente armazenamentos de dados ou armazenamentos de memória para manter os dados de lugar a local.
Para enviar dados básicos não seguros de lugar a local, chame TeleportOptions:SetTeleportData() antes de passá-los para TeleportAsync().
Não passe dados seguros usando TeleportOptions:SetTeleportData() porque tem o risco de exploração.
Para obter todos os dados de um usuário que chega de um teletransporte no servidor, use a função Player:GetJoinData(), que retorna um dicionário que inclui os dados associados ao usuário.
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)
Para recuperar apenas os dados de teletransporte no cliente, você pode usar TeleportService:GetLocalPlayerTeleportData().
Lidar com teletransportes falhos
Como qualquer chamada de API que envolve solicitações de rede, teletransportes podem falhar e lançar um erro.Envolva-os em chamadas protegidas ( pcall() ).Alguns falhas se beneficiam de tentativas de novo, especialmente aquelas envolvendo servidores reservados, então recomendamos tentar novamente algum número de vezes em falhas.
Mesmo que uma chamada tenha sucesso e o teletransporte se inicie, ainda pode falhar no último momento sem lançar um erro e deixar o usuário no servidor.Quando isso acontece, gera o evento TeleportService.TeleportInitFailed.
O seguinte exemplo ModuleScript define uma função SafeTeleport para teletransportar o usuário em uma chamada protegida com lógica de tentativa novamente.Também tem uma função handleFailedTeleport para lidar com situações em que a chamada foi bem-sucedida, mas o teletransporte não ocorrer.
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 -- defina os resultados da chamada fora do loop para que os resultados possam ser relatados mais tarde
repeat
success, result = pcall(function()
return TeleportService:TeleportAsync(placeId, players, options) -- teletransportar 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 -- pare de tentar se teletransportar se a chamada tiver sido bem-sucedida ou se o limite de reutilização for atingido
if not success then
warn(result) -- imprimir o motivo do erro para 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 teletransporte for inválido, relate o erro ao invés de tentar novamente
error(("Invalid teleport [%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 da função TeleportAsync().Você pode usar o seguinte ModuleScript com a função SafeTeleport para realizar teletransportes de qualquer lugar em sua experiência para reduzir falhas de teletransporte.