Se você quiser construir uma experiência com muitos lugares distintos, como um mundo de fantasia com várias cidades, castelos, masmorras e uma vasta floresta, você pode usar TeleportService para permitir que os usuários se teletransportem entre lugares em um universo, servidores ou até mesmo para outra experiência.
TeleportService não suporta playtesting no Roblox Studio. Você deve publicar a experiência e usá-la no aplicativo Roblox para testes.
Configurando Teletransporte
Para habilitar o teletransporte em sua experiência, use TeleportService:TeleportAsync() . O método aceita três parâmetros:
- O PlaceId para que os usuários se teletransportem.
- Um array contendo as Player instâncias que representam os usuários para se teleportar.
- Uma instância TeleportOptions opcional que contém propriedades personalizadas para a chamada TeleportAsync().
local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local TARGET_PLACE_ID = 1234 -- substituir com o seu próprio ID de lugar
local playerToTeleport = Players:GetPlayers()[1] -- obtenha o primeiro usuário na experiência
TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)Você só pode chamar TeleportAsync() de scripts do lado do servidor. Essa limitação reduz a exploração do lado do cliente. Se necessário, você pode chamar Teleport() de scripts do lado do cliente, mas TeleportAsync() é o método recomendado.
Habilitando Teletransporte de Experiência Cruzada
Por motivos de segurança, teletransportar um usuário de sua experiência para outra experiência pertencente a outros, ou vice-versa, falha por padrão. Para habilitar o teletransporte entre experiências, abra Configurações do Jogo > Segurança e ative Permitir Teletransportes de Terceiros no Studio.
Criando Telas de Teleporte Personalizadas
Quando um usuário aciona um teleporte, ele vê a tela de carregamento padrão do Roblox enquanto espera pelo novo lugar para carregar. Você pode adicionar uma tela de teleporte personalizada para melhorar a imersão para os usuários chamando TeleportService:SetTeleportGui() no cliente e passando pelo ScreenGui para usar antes de teleportar o usuário. O exemplo a seguir define um ScreenGui personalizado localizado em ReplicatedStorage como a tela de carregamento quando um teleporte acontece. Ele não roda nenhum script dentro do ScreenGui .
local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local teleportGui = ReplicatedStorage.TeleportGui
TeleportService:SetTeleportGui(teleportGui)Personalizando Opções de Teleporte
Você pode personalizar os teletransportes, como teletransportar usuários para um servidor específico e enviar dados do usuário junto com teletransportes, configurando a instância TeleportOptions e passando-a para o método TeleportService:TeleportAsync().
Teleportando para Servidores Específicos
Para teletransportar usuários para servidores específicos, defina o servidor de destino usando TeleportOptions e passe-o para o TeleportService:TeleportAsync() método. Se você não especificar um servidor, os usuários são teletransportados para um servidor público matchmade. As informações do primeiro usuário na lista são usadas para matchmake nesse 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.
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ServerInstanceId = targetServerIdPara teletransportar 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 = reservedServerCodePara teletransportar usuários para um novo servidor reservado, defina TeleportOptions.ShouldReserveServer como verdadeiro.
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ShouldReserveServer = trueEnviando dados do usuário junto com teletransportes
Teleportar um usuário entre lugares descarta todos os dados locais associados a esse usuário. Você pode usar as seguintes abordagens para lidar com a persistência de dados entre lugares.
- Se sua experiência usar dados de usuário seguros , como moeda ou inventário da experiência, implemente armazenamento de dados ou armazenamento de memória para manter os dados de lugar para local.
- Para enviar dados básicos não seguros de um lugar para 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.
local teleportData = {
randomNumber = RNG:NextInteger(1, 100),
}
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions:SetTeleportData(teleportData)Para obter todos os dados de um usuário que chega 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 obter apenas os dados de teleporte no cliente, você pode usar TeleportService:GetLocalPlayerTeleportData() .
Manipulação de Teletransportes Falha
Como qualquer chamada de API que envolva solicitações de rede, os teletransportes podem falhar e gerar um erro. Mesmo que uma chamada seja bem-sucedida e o teletransporte seja iniciado, ela ainda pode falhar no último momento sem gerar um erro e deixar o usuário no servidor. Quando isso acontece, ela aciona TeleportService.TeleportInitFailed .
Enrole os teletransportes em uma chamada protegida (pcall() ) e tente novamente se falhar. O exemplo a seguir ModuleScript define uma função SafeTeleport para teletransportar o usuário em uma chamada protegida e uma função handleFailedTeleport para tentar novamente teletransportes falhados que são soluços únicos e deixam cair aqueles inválidos que podem ter erros no código.
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 do pcall fora do loop para que os resultados possam ser reportados 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 for bem-sucedida ou se o limite de tentativas for atingido
if not success then
warn(result) -- imprima o motivo 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 teletransporte for inválido, denuncie o erro em vez de tentar
error(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
end
SafeTeleport(targetPlaceId, {player}, teleportOptions)
end
TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)
return SafeTeleportA função SafeTeleport recebe os mesmos argumentos que a função TeleportAsync(). Você pode usar a seguinte ModuleScript com a função SafeTeleport para realizar teletransportes de qualquer lugar da sua experiência para reduzir os teletransportes falhados.
local Players = game:GetService("Players")
local ServerScriptService = game:GetService("ServerScriptService")
local SafeTeleport = require(ServerScriptService.SafeTeleport)
local TARGET_PLACE_ID = 1818 -- substituir com o seu próprio ID de lugar
local playerToTeleport = Players:GetPlayers()[1] -- pegue o primeiro usuário no jogo
SafeTeleport(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)Fonte: https://create.roblox.com
