Se você quiser construir uma experiência com muitos locais distintos, como um mundo de fantasia com múltiplas cidades, castelos, masmorras e uma floresta vasta, você pode usar TeleportService para habilitar os usuários a se teletransportar 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 na aplicação Roblox para testes.
Configurando Teletransporte
Para habilitar a teletransporte 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 contendo as instâncias Player representando os usuários para se teleportar.
- Uma instância TeleportOptions opcional que contém propriedades personalizadas para o TeleportAsync() chamado.
Você só pode chamar TeleportAsync() a partir de scripts do lado do servidor. Essa limitação reduz a exploração do lado do cliente. Se necessário, você pode chamar Teleport() a partir de scripts do lado do cliente, mas TeleportAsync() é o mét
Se você quiser tomar precauções ao lidar com erros ao configurar teletransporte, veja Manuseio de Falhas de Teletransporte.
Habilitando Teletransporte de Experiência Cruzada
Para fins de segurança, o teletransporte de um usuário da sua experiência para outra experiência de propriedade de outros, ou o caminho oposto, falha por padrão. Para habilitar o teletransporte de experiência cruzada, abra Configurações do Jogo > Segurança e ative Permitir teletransporte de terceiros em Studio.
Criando Tela de Teleporte Personalizada
Quando um usuário ativa um teleportar, eles vêem a tela de carregamento padrão do Roblox enquanto esperam que o novo local carregue. Você pode adicionar uma tela de teleporte personal
Personalizando Opções de Teleporte
Você pode personalizar teletransportes, como teletransportar usuários para um servidor específico e enviar dados do usuário juntamente com os teletransportes, configurando a instância TeleportOptions e passando-a para o método 2> Class.TeleportService:TeleportAsync() .
Teletransporte para Servidores Específicos
Para teletransportar usuários para servidores específicos, configure o servidor de destino 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. As informações do primeiro usuário na lista são usadas para fazer matchmaking para aquele 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 de acesso de TeleportOptions.ReservedServerAccessCode, que é um código de entrada de um servidor reservado.
Para teletransportar usuários para um novo servidor reservado, set TeleportOptions.ShouldReserveServer para verdadeiro.
Enviando Dados do Usuário Juntamente 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 sua experiência utilizar dados de usuário seguros como moeda-no-lugar ou inventário, implemente armazenamento de dados ou armazenamento de memória para manter os dados do lugar para o local.
Para enviar dados básicos de não seguros de lugar em local, chame Class.TeleportOptions:SetTeleportData() antes de enviá-lo para Class.TeleportService:TeleportAsync()|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 chegando de um teleporte no servidor, use a função Player:GetJoinData(), que retorna um dicionário incluindo 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 teleporte no cliente, você pode usar TeleportService:GetLocalPlayerTeleportData() .
Mão Failed Teleports
Como qualquer chamada de API que envolve solicitações de rede, teletransportes podem falhar e exibir um erro. Mesmo que uma chamada seja bem-sucedida e o teletransporte inicie, ainda pode falhar no último momento semThrow um erro e deixar o usuário no servidor. Quando isso acontece, ele gera TeleportService.TeleportInitFailed .
Wrap teleports in a protected call ( pcall() ) and retry if it fails. The following example ModuleScript defines a SafeTeleport function to teleport the user in a protected call and a 1> HandleFailedTeleport1> function to retry failed teleports that are one-time hiccups and drops invalid ones
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 -- 定義 pcall results outside of loop, para que os resultados possam ser relatados mais tarde
repeat
success, result = pcall(function()
return TeleportService:TeleportAsync(placeId, players, options) -- teleporte 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 teletransportar se a chamada foi bem-sucedida ou se o limite de tentativa foi atingido
if not success then
warn(result) -- imprima a razão de 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 teleporte for inválido, reporte 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 que a função TeleportAsync(). Você pode usar o seguinte ModuleScript com a função 2>SafeTeleport2> para executar teletransportes de qualquer lugar em sua experiência para reduzir teletransportes falhados.