Teletrasportarsi tra i luoghi

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

Teletrasportare i giocatori

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

• Il PlaceId verso cui gli utenti devono teletrasportarsi.
• Un array contenente le istanze di Player che desideri teletrasportare.
• Un'istanza opzionale di TeleportOptions che contiene proprietà personalizzate per la chiamata 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. Puoi quindi controllare se il giocatore fa parte di un team (Player.Team) o di un party (Player.PartyId). Infine, puoi usare Team:GetPlayers() o SocialService:GetPlayersByPartyId() se desideri teletrasportare l'intero gruppo anziché solo l'individuo.

Configurare il teletrasporto sicuro

Tre impostazioni gestiscono la sicurezza del teletrasporto.

Controllo accesso per i luoghi controlla i giocatori che si teletrasportano nel 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 vuoi che gli amici possano facilmente unirsi l'uno all'altro indipendentemente da quale luogo si trovino. Se non scegli questa opzione, i giocatori che cercano di unirsi ai loro amici in luoghi non iniziali si uniranno invece al luogo iniziale del tuo gioco.

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

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

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

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

Migrare a teletrasporti sicuri

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

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

Crea schermate di teletrasporto personalizzate

Quando un utente attiva un teletrasporto, vede la schermata di caricamento standard di Roblox mentre aspetta che il nuovo luogo venga caricato. Se desiderato, puoi aggiungere una schermata di teletrasporto personalizzata chiamando TeleportService:SetTeleportGui() sul client.

Il seguente esempio imposta un ScreenGui personalizzato da ReplicatedStorage. Qualsiasi script all'interno del ScreenGui non verrà 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 dell'utente insieme ai teletrasporti, impostando l'istanza di TeleportOptions e passandola al metodo TeleportService:TeleportAsync().

Teletrasportati 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

Invia dati dell'utente insieme ai teletrasporti

Teletrasportare un utente tra 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 la valuta di gioco o l'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 usando questo metodo; i dati sono visibili al client e non sono criptati.

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, usa 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 non riusciti

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 nuovi tentativi, in particolare quelli che coinvolgono server riservati, quindi ti raccomandiamo di riprovare un certo numero di volte in caso di fallimento.

Anche se una chiamata ha successo e il teletrasporto viene avviato, può comunque fallire nell'ultimo momento senza generare un errore e lascierebbe 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 completata 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 segnalati in seguito

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- teletrasportare 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 tentativi è stato raggiunto

    if not success then
        warn(result) -- stampare la ragione del fallimento in 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, segnalare 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 usare 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)