Teletransportarse entre lugares

Muchos juegos están subdivididos en múltiples lugares, como un mundo de fantasía con ciudades, castillos, mazmorras y un vasto bosque. Usa TeleportService para teletransportar a los usuarios entre lugares, a diferentes servidores o incluso a otros juegos.

Teletransportar jugadores

Para teletransportar jugadores, usa TeleportService:TeleportAsync(). Este método acepta tres parámetros:

• El PlaceId al que los usuarios se teletransportarán.
• Una matriz que contiene las instancias de Player que deseas teletransportar.
• Una instancia opcional de TeleportOptions que contiene propiedades personalizadas para la llamada a TeleportAsync().

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

local TARGET_PLACE_ID = 12345678901234 -- reemplaza con el tuyo
local playerToTeleport = Players:GetPlayers()[1] -- obtener el primer usuario en el juego

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

Para obtener los jugadores apropiados para teletransportar, podrías usar un evento BasePart.Touched o un evento ProximityPrompt.Triggered para obtener un Player individual. Luego puedes comprobar si el jugador es parte de un equipo (Player.Team) o una fiesta (Player.PartyId). Finalmente, puedes usar Team:GetPlayers() o SocialService:GetPlayersByPartyId() si deseas teletransportar a todo el grupo en lugar de solo al individuo.

Configurar teletransportes seguros

Tres configuraciones manejan la seguridad del teletransporte.

Control de Acceso para Lugares controla los jugadores que se teletransportan dentro de tu juego y es la configuración más crítica para prevenir exploits basados en el teletransporte.

• Si eliges Totalmente abierto, los jugadores pueden unirse a cualquier lugar en tu juego a través de teletransportes desde cualquier juego, incluidos enlaces profundos, invitaciones de juego, unirse a un amigo y más.

  Esta es una buena opción si tu juego tiene varios lugares y quieres que los amigos puedan unirse fácilmente entre sí sin importar en qué lugar estén. Si no eliges esta opción, los jugadores que intenten unirse a sus amigos en lugares que no son de inicio en su lugar se unirán al lugar de inicio de tu juego.

• Si eliges Limitado al mismo universo, los jugadores solo pueden unirse a lugares que no son de inicio a través de teletransportes dentro de tus juegos. Esta configuración permite tanto teletransportes iniciados desde el cliente como desde el servidor.

  Esta es una buena opción si tienes un juego legado que no deseas migrar a teletransportes seguros.

• Si eliges Seguro solo dentro del universo, los jugadores solo pueden unirse a lugares que no son de inicio a través de teletransportes iniciados desde el servidor dentro de este juego.

  Esta es una buena opción si tu juego tiene un sistema de progresión estricto antes de que los jugadores puedan acceder a ciertas áreas. También es una buena opción si tu juego tiene un lugar de prueba al que los jugadores no deberían tener acceso o para lugares que utilizan exclusivamente servidores reservados.

Migrar a teletransportes seguros

Si tienes un juego existente que utiliza teletransportes del lado del cliente y deseas requerir teletransportes iniciados desde el servidor, el objetivo es mover toda la lógica de teletransporte fuera de los scripts del cliente y a los scripts del servidor:

1. Encuentra todos los scripts del cliente que llaman a Teleport().
2. Cambia estas llamadas para activar eventos remotos. Alternativamente, puedes cambiar las llamadas para usar ProximityPrompts, ClickDetectors, o incluso solo el evento BasePart.Touched.
3. Reimplementa el teletransporte en un script del servidor usando TeleportAsync().
4. Cuando no existan más llamadas a Teleport(), cambia Control de Acceso para Lugares a Seguro.

Crear pantallas de teletransporte personalizadas

Cuando un usuario activa un teletransporte, ve la pantalla de carga estándar de Roblox mientras espera que se cargue el nuevo lugar. Si lo deseas, puedes agregar una pantalla de teletransporte personalizada llamando a TeleportService:SetTeleportGui() en el cliente.

El siguiente ejemplo establece un ScreenGui personalizado desde ReplicatedStorage. Cualquier script dentro del ScreenGui no se ejecuta.

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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

Personalizar opciones de teletransporte

Puedes personalizar los teletransportes, como teletransportar usuarios a un servidor específico y enviar datos de usuario junto con los teletransportes, configurando la instancia de TeleportOptions y pasándola al método TeleportService:TeleportAsync().

Teletransportar a servidores específicos

Para teletransportar usuarios a servidores específicos, establece el servidor objetivo utilizando TeleportOptions y pásalo al método TeleportAsync(). Si no especificas un servidor, los usuarios son teletransportados a un servidor público; la información del primer usuario en la lista se utiliza para el emparejamiento.

Para teletransportar usuarios a un servidor público específico, establece la propiedad TeleportOptions.ServerInstanceId como un ID de instancia válido, que es un identificador único para un servidor público.

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

Para teletransportar usuarios a un servidor reservado específico, establece un TeleportOptions.ReservedServerAccessCode válido, que es un código único para entrar a un servidor reservado.

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

Para teletransportar usuarios a un nuevo servidor reservado, establece TeleportOptions.ShouldReserveServer en verdadero.

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

Enviar datos de usuario junto con los teletransportes

Teletransportar un usuario entre lugares descarta cualquier dato local asociado con ese usuario. Puedes usar los siguientes enfoques para manejar la persistencia de datos entre lugares:

• Si tu juego utiliza datos de usuario seguros como moneda del juego o inventario, implementa almacenes de datos o almacenes en memoria para mantener datos de un lugar a otro.

• Para enviar datos no seguros básicos de un lugar a otro, llama a TeleportOptions:SetTeleportData() antes de pasarlo a TeleportAsync(). No pases datos seguros usando este método; los datos son visibles para el cliente y no están encriptados.

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

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

Para recuperar todos los datos cuando un usuario llega al nuevo lugar después de un teletransporte, usa la función Player:GetJoinData(), que devuelve un diccionario con una clave 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 .. " se unió con el número " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Para recuperar solo los datos de teletransporte en el cliente, puedes usar TeleportService:GetLocalPlayerTeleportData().

Manejar teletransportes fallidos

Como cualquier llamada a la API que involucra solicitudes de red, los teletransportes pueden fallar y generar un error. Envuelve estas operaciones en llamadas protegidas (pcall()). Algunas fallas se benefician de reintentos, particularmente aquellas que involucran servidores reservados, por lo que recomendamos reintentar un número determinado de veces ante un fallo.

Incluso si una llamada tiene éxito y se inicia el teletransporte, todavía puede fallar en el último momento sin generar un error y dejar al usuario en el servidor. Cuando esto sucede, se activa el evento TeleportService.TeleportInitFailed.

El siguiente ejemplo ModuleScript devuelve una función SafeTeleport que teletransporta jugadores en una llamada protegida con lógica de reintento. También tiene una función handleFailedTeleport para lidiar con situaciones en las que la llamada fue exitosa, pero el teletransporte no ocurrió.

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 los resultados de pcall fuera del bucle para que los resultados puedan ser reportados más tarde

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- teletransportar al usuario en una llamada protegida para prevenir errores
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- deja de intentar teletransportar si la llamada fue exitosa, o si se ha alcanzado el límite de reintentos

    if not success then
        warn(result) -- imprime el motivo del fallo en la salida
    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
        -- si el teletransporte es inválido, reporta el error en lugar de reintentar
        error(("Teletransporte inválido [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

La función SafeTeleport recibe los mismos argumentos que la función TeleportAsync(). Puedes usar el siguiente script junto con la función SafeTeleport para realizar teletransportes desde cualquier lugar en tu juego:

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)