Teleportacja między miejscami

Wiele gier jest podzielonych na wiele miejsc, takich jak fantastyczny świat z miastami, zamkami, lochami i rozległym lasem. Użyj TeleportService, aby teleportować użytkowników między miejscami, do różnych serwerów, a nawet do innych gier.

Teleportuj graczy

Aby teleportować graczy, użyj TeleportService:TeleportAsync(). Ta metoda przyjmuje trzy parametry:

• PlaceId, do którego mają być teleportowani użytkownicy.
• Tablicę zawierającą instancje Player, które chcesz teleportować.
• Opcjonalną instancję TeleportOptions, która zawiera właściwości niestandardowe dla wywołania TeleportAsync().

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

local TARGET_PLACE_ID = 12345678901234 -- zastąp własnym
local playerToTeleport = Players:GetPlayers()[1] -- pobierz pierwszego użytkownika w grze

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})

Aby uzyskać odpowiednich graczy do teleportacji, możesz użyć zdarzenia BasePart.Touched lub ProximityPrompt.Triggered, aby uzyskać indywidualnego Player. Następnie możesz sprawdzić, czy gracz należy do drużyny (Player.Team) lub partii (Player.PartyId). W końcu możesz wykorzystać Team:GetPlayers() lub SocialService:GetPlayersByPartyId(), jeśli chcesz teleportować całą grupę, a nie tylko pojedynczego gracza.

Skonfiguruj bezpieczną teleportację

Trzy ustawienia obsługują bezpieczeństwo teleportacji.

Kontrola dostępu dla miejsc kontroluje teleportację graczy do twojej gry i jest najważniejszym ustawieniem zapobiegającym wykorzystywaniu opartemu na teleportacji.

• Jeśli wybierzesz Całkowicie otwarte, gracze mogą dołączać do dowolnego miejsca w twojej grze za pomocą teleportacji z dowolnej gry, w tym linków głębokich, zaproszeń do gry, dołączania do przyjaciela i innych.

  To dobry wybór, jeśli twoja gra ma kilka miejsc i chcesz, aby przyjaciele mogli łatwo do siebie dołączać, niezależnie od tego, w którym miejscu się znajdują. Jeśli nie wybierzesz tej opcji, gracze, którzy próbują dołączyć do swoich przyjaciół w miejscach, które nie są miejscami startowymi, dołączą zamiast tego do miejsca startowego twojej gry.

• Jeśli wybierzesz Ograniczone do tego samego uniwersum, gracze mogą dołączać do miejsc, które nie są miejscami startowymi, tylko za pomocą teleportacji w ramach twojej gry. To ustawienie pozwala na zarówno teleportacje inicjowane przez klienta, jak i serwer.

  To dobry wybór, jeśli masz grę dziedziczną, którą nie chcesz migracja do bezpiecznych teleportów.

• Jeśli wybierzesz Bezpieczne tylko w uniwersum, gracze mogą dołączać do miejsc, które nie są miejscami startowymi, tylko przez teleportacje inicjowane przez serwer w tej grze.

  To dobry wybór, jeśli twoja gra ma restrykcyjny system postępów, zanim gracze będą mogli uzyskać dostęp do niektórych obszarów. To również dobry wybór, jeśli twoja gra ma miejsce testowe, do którego gracze nie powinni mieć dostępu, lub dla miejsc, które korzystają wyłącznie z zarezerwowanych serwerów.

Migracja do bezpiecznych teleportów

Jeśli masz istniejącą grę, która używa teleportacji po stronie klienta i chcesz wymusić teleportacje inicjowane przez serwer, celem jest przeniesienie całej logiki teleportacji z skryptów klienta do skryptów serwera:

1. Znajdź wszystkie skrypty klienckie, które wywołują Teleport().
2. Zmień te wywołania, aby zamiast tego wywoływać zdarzenia zdalne. Alternatywnie, możesz zmienić wywołania, aby używały ProximityPrompts, ClickDetectors lub nawet po prostu zdarzenia BasePart.Touched.
3. Zaimplementuj teleportację w skrypcie serwera za pomocą TeleportAsync().
4. Gdy nie będzie już wywołań Teleport(), zmień Kontrola dostępu dla miejsc na Bezpieczne.

Tworzenie niestandardowych ekranów teleportacji

Gdy użytkownik wywoła teleportację, widzi standardowy ekran ładowania Roblox, gdy czeka na załadowanie nowego miejsca. Jeśli chcesz, możesz dodać niestandardowy ekran teleportacji, wywołując TeleportService:SetTeleportGui() na kliencie.

Poniższy przykład ustawia spersonalizowany ScreenGui z ReplicatedStorage. Wszelkie skrypty w ScreenGui nie będą się wykonywać.

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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

Dostosowywanie opcji teleportacji

Możesz dostosować teleportacje, takie jak teleportowanie użytkowników do konkretnego serwera oraz wysyłanie danych użytkownika wraz z teleportacjami, ustawiając instancję TeleportOptions i przekazując ją do metody TeleportService:TeleportAsync().

Teleport do konkretnych serwerów

Aby teleportować użytkowników do konkretnych serwerów, ustaw docelowy serwer za pomocą TeleportOptions i przekaż go do metody TeleportAsync(). Jeśli nie określisz serwera, użytkownicy są teleportowani do publicznego serwera; informacje o pierwszym użytkowniku na liście są używane do matchmakingu.

Aby teleportować użytkowników do konkretnego publicznego serwera, ustaw właściwość TeleportOptions.ServerInstanceId jako ważny identyfikator instancji, który jest unikalnym identyfikatorem dla publicznego serwera.

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

Aby teleportować użytkowników do konkretnego zarezerwowanego serwera, ustaw ważny TeleportOptions.ReservedServerAccessCode, który jest unikalnym kodem do wprowadzenia na zarezerwowany serwer.

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

Aby teleportować użytkowników do nowego zarezerwowanego serwera, ustaw TeleportOptions.ShouldReserveServer na true.

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

Wysyłanie danych użytkownika wraz z teleportacjami

Teleportowanie użytkownika między miejscami odrzuca wszelkie dane lokalne związane z tym użytkownikami. Możesz użyć następujących podejść do obsługi trwałości danych między miejscami:

• Jeśli twoja gra wykorzystuje bezpieczne dane użytkownika, takie jak waluta w grze lub ekwipunek, zaimplementuj sklepy danych lub magazyny pamięci, aby utrzymać dane z miejsca do miejsca.

• Aby wysłać podstawowe niebezpieczne dane z miejsca do miejsca, wywołaj TeleportOptions:SetTeleportData() przed przekazaniem go do TeleportAsync(). Nie przesyłaj danych bezpiecznych w ten sposób; dane te są widoczne dla klienta i nie są szyfrowane.

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

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

Aby odzyskać wszystkie dane, gdy użytkownik przyjedzie do nowego miejsca po teleportacji, użyj funkcji Player:GetJoinData(), która zwraca słownik z kluczem 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 .. " dołączył z numerem " .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Aby odzyskać tylko dane teleportacyjne po stronie klienta, możesz użyć TeleportService:GetLocalPlayerTeleportData().

Obsługa nieudanych teleportacji

Tak jak każda wywołanie API, które obejmuje żądania sieciowe, teleportacje mogą zawieść i zgłosić błąd. Owiń je w chronione wywołania (pcall()). Niektóre awarie zyskują na wartości w przypadku powtórzeń, szczególnie te dotyczące zarezerwowanych serwerów, dlatego zalecamy powtórzenie kilku razy przy niepowodzeniu.

Nawet jeśli wywołanie się powiedzie i teleportacja się rozpocznie, nadal może zakończyć się niepowodzeniem w ostatniej chwili bez zgłaszania błędu i pozostawić użytkownika na serwerze. Kiedy się to stanie, uruchamia to zdarzenie TeleportService.TeleportInitFailed.

Poniższy przykład ModuleScript zwraca pojedynczą funkcję SafeTeleport, która teleportuje graczy w chronionym wywołaniu z logiką ponawiania. Ma także funkcję handleFailedTeleport, aby radzić sobie z sytuacjami, w których wywołanie zakończyło się sukcesem, ale teleportacja nie miała miejsca.

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 -- zdefiniuj wyniki pcall poza pętlą, aby wyniki mogły być później zgłaszane

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- teleportuj użytkownika w chronionym wywołaniu, aby zapobiec błędom
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- przestań próbować teleportować, jeśli wywołanie się powiodło lub osiągnięto limit ponowienia

    if not success then
        warn(result) -- wydrukuj powód niepowodzenia w wyjściu
    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
        -- jeśli teleportacja jest nieprawidłowa, zgłoś błąd zamiast ponawiać
        error(("Nieprawidłowy teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

Funkcja SafeTeleport przyjmuje te same argumenty, co funkcja TeleportAsync(). Możesz użyć poniższego skryptu z funkcją SafeTeleport, aby przeprowadzić teleportacje z dowolnego miejsca w twojej grze:

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)