Teletrasportare tra i luoghi

Molti giochi sono suddivisi in più luoghi, come un mondo fantasy con città, castelli, dungeon e una vasta foresta. Usa TeleportService per teletrasportare gli utenti tra i luoghi, a diversi server o persino ad altri giochi.

Teletrasportare i giocatori

Per teletrasportare i giocatori, usa TeleportService:TeleportAsync(). Questo metodo accetta tre parametri:

• L'PlaceId a cui gli utenti devono essere teletrasportati.
• Un array contenente le istanze di Player che desideri teletrasportare.
• Un'istanza opzionale di TeleportOptions che contiene proprietà personalizzate per la chiamata a TeleportAsync().

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

local TARGET_PLACE_ID = 12345678901234 -- sostituisci con il tuo
local playerToTeleport = Players:GetPlayers()[1] -- ottieni il primo utente nel gioco

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

Per ottenere i giocatori appropriati da teletrasportare, potresti utilizzare un evento BasePart.Touched o un evento ProximityPrompt.Triggered per ottenere un singolo Player. Poi puoi controllare se il giocatore fa parte di una squadra (Player.Team) o di un party (Player.PartyId). Infine, puoi usare Team:GetPlayers() o SocialService:GetPlayersByPartyId() se desideri teletrasportare l'intero gruppo piuttosto che solo l'individuo.

Configura il teletrasporto sicuro

Tre impostazioni gestiscono la sicurezza del teletrasporto.

Controllo accesso per i luoghi controlla i giocatori che si teletrasportano dentro il tuo gioco ed è l'impostazione più critica per prevenire exploit basati sul teletrasporto.

• Se scegli Completamente aperto, i giocatori possono unirsi a qualsiasi luogo nel tuo gioco tramite teletrasporti da qualsiasi gioco, inclusi link profondi, inviti di gioco, unirsi a un amico e altro ancora.

  Questa è una buona scelta se il tuo gioco ha diversi luoghi e desideri che gli amici possano unirsi facilmente l'uno all'altro indipendentemente dal luogo in cui si trovano. Se non scegli questa opzione, i giocatori che cercano di unirsi ai loro amici in luoghi non di partenza si uniranno invece al luogo di partenza del tuo gioco.

• Se scegli Limitato allo stesso universo, i giocatori possono unirsi a luoghi non di partenza solo tramite teletrasporti all'interno dei tuoi giochi. Questa impostazione consente teletrasporti sia avviati dal client che dal server.

  Questa è una buona scelta se hai un gioco legacy che non vuoi migrere a teletrasporti sicuri.

• Se scegli Sicuro solo all'interno dell'universo, i giocatori possono unirsi a luoghi non di partenza solo tramite teletrasporti avviati dal server all'interno di questo gioco.

  Questa è una buona scelta se il tuo gioco ha un sistema di progressione rigoroso prima che i giocatori possano accedere a determinate aree. È anche una buona scelta se il tuo gioco ha un luogo di test a cui i giocatori non dovrebbero avere accesso o per luoghi che utilizzano esclusivamente server riservati.

Migra a teletrasporti sicuri

Se hai un gioco esistente che utilizza teletrasporti lato client e desideri richiedere teletrasporti avviati dal server, l'obiettivo è spostare tutta la logica di teletrasporto fuori dagli script client e negli script server:

1. Trova tutti gli script client che chiamano Teleport().
2. Cambia queste chiamate per attivare invece eventi remoti. In alternativa, puoi cambiare le chiamate per utilizzare ProximityPrompts, ClickDetectors, o anche solo l'evento BasePart.Touched.
3. Reimplementa il teletrasporto in uno script server utilizzando TeleportAsync().
4. Quando non esistono più chiamate a Teleport(), cambia Controllo accesso per i luoghi in Sicuro.

Crea schermi di teletrasporto personalizzati

Quando un utente attiva un teletrasporto, vede lo schermo di caricamento standard di Roblox mentre aspetta che il nuovo luogo venga caricato. Se desideri, puoi aggiungere uno schermo di teletrasporto personalizzato chiamando TeleportService:SetTeleportGui() sul client.

Il seguente esempio imposta un ScreenGui personalizzato da ReplicatedStorage. Qualsiasi script all'interno del ScreenGui non viene eseguito.

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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

Personalizza le opzioni di teletrasporto

Puoi personalizzare i teletrasporti, come teletrasportare gli utenti a un server specifico e inviare i dati degli utenti insieme ai teletrasporti, impostando l'istanza di TeleportOptions e passandola al metodo TeleportService:TeleportAsync().

Teletrasportare a server specifici

Per teletrasportare gli utenti a server specifici, imposta il server di destinazione utilizzando TeleportOptions e passalo al metodo TeleportAsync(). Se non specifichi un server, gli utenti vengono teletrasportati in un server pubblico; le informazioni del primo utente nell'elenco vengono utilizzate per il matchmaking.

Per teletrasportare gli utenti a un server pubblico specifico, imposta la proprietà TeleportOptions.ServerInstanceId come un ID di istanza valido, che è un identificatore unico per un server pubblico.

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

Per teletrasportare gli utenti a un server riservato specifico, imposta un valido TeleportOptions.ReservedServerAccessCode, che è un codice unico per entrare in un server riservato.

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

Per teletrasportare gli utenti a un nuovo server riservato, imposta TeleportOptions.ShouldReserveServer su true.

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

Inviare dati degli utenti insieme ai teletrasporti

Teletrasportare un utente tra i luoghi scarta qualsiasi dato locale associato a quell'utente. Puoi utilizzare i seguenti approcci per gestire la persistenza dei dati tra i luoghi:

• Se il tuo gioco utilizza dati sicuri come valuta di gioco o inventario, implementa data stores o memory stores per mantenere i dati da un luogo all'altro.

• Per inviare dati non sicuri di base da un luogo all'altro, chiama TeleportOptions:SetTeleportData() prima di passarli a TeleportAsync(). Non passare dati sicuri utilizzando questo metodo; i dati sono visibili al client e non sono crittografati.

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

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

Per recuperare tutti i dati quando un utente arriva nel nuovo luogo dopo un teletrasporto, utilizza la funzione Player:GetJoinData(), che restituisce un dizionario con una chiave 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 .. " è entrato con il numero " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Per recuperare solo i dati di teletrasporto sul client, puoi utilizzare TeleportService:GetLocalPlayerTeleportData().

Gestire i teletrasporti falliti

Come qualsiasi chiamata API che coinvolge richieste di rete, i teletrasporti possono fallire e generare un errore. Avvolgili in chiamate protette (pcall()). Alcuni fallimenti beneficiano di ripetizioni, in particolare quelli che coinvolgono server riservati, quindi ti consigliamo di riprovare un certo numero di volte in caso di errore.

Anche se una chiamata ha successo e il teletrasporto inizia, può comunque fallire all'ultimo momento senza generare un errore e lasciare l'utente nel server. Quando ciò accade, viene attivato l'evento TeleportService.TeleportInitFailed.

Il seguente esempio di ModuleScript restituisce una singola funzione SafeTeleport che teletrasporta i giocatori in una chiamata protetta con logica di ripetizione. Ha anche una funzione handleFailedTeleport per gestire situazioni in cui la chiamata è stata effettuata con successo, ma il teletrasporto non è avvenuto.

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 -- definire i risultati di pcall al di fuori del ciclo in modo che i risultati possano essere riportati successivamente

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- teletrasporta l'utente in una chiamata protetta per prevenire errori
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- smettere di provare a teletrasportare se la chiamata ha avuto successo, o se il limite di ripetizione è stato raggiunto

    if not success then
        warn(result) -- stampa il motivo del fallimento nell'output
    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 il teletrasporto è invalido, riporta l'errore invece di riprovare
        error(("Teletrasporto non valido [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

La funzione SafeTeleport riceve gli stessi argomenti della funzione TeleportAsync(). Puoi utilizzare il seguente script con la funzione SafeTeleport per eseguire teletrasporti da qualsiasi parte del tuo gioco:

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)