Teleport zu privaten Servern

Neben dem Teleportieren von Spielern zwischen öffentlichen Servern unterstützt TeleportService das Teleportieren zu privaten Servern, die auf bestimmte Spieler beschränkt sind. Es gibt zwei Arten von privaten Servern, zu denen Sie teleportieren können:

• Reservierte Server: Von Entwicklern erstellte Server, die über eine vom Entwickler bereitgestellte ID zugänglich sind. Nützlich für private Matches, Koop-Sitzungen oder jedes Szenario, in dem Sie kontrollieren, wer beitritt.
• VIP-Server: Von Spielern gekaufte private Server. Verwenden Sie TeleportOptions.VipServerId, um Spieler zu einem VIP-Server zu leiten, den sie gekauft haben.

Teleport zu einem reservierten Server

Reservierte Server werden nach Bedarf erstellt: Der erste Teleport mit einer neuen ReservedServerId erstellt den Server, und die Wiederverwendung derselben ID leitet nachfolgende Teleports zu diesem Server. Generieren Sie die ID mit HttpService:GenerateGUID(false):

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

local TARGET_PLACE_ID = 12345678901234

-- Die Benutzer, die teleportiert werden sollen (z. B. von Players:GetPlayers() oder einer Matchmaking-Gruppe)
local player1, player2 = Players:GetPlayers()[1], Players:GetPlayers()[2]

-- Generieren Sie eine eindeutige ID für den reservierten Server
local reservedServerId = HttpService:GenerateGUID(false)

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerId = reservedServerId

-- Der erste Teleport erstellt den Server
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player1, player2}, teleportOptions)

Wiederverwendung einer reservierten Server-ID

Um anderen Spielern später den Beitritt zum selben reservierten Server zu ermöglichen, speichern Sie die reservierte Server-ID mit einem DataStoreService-Datenstore, damit sie über Sitzungen und Server hinweg erhalten bleibt.

Auf dem Server, der den reservierten Server erstellt, generieren Sie die ID für den ersten Teleport und speichern Sie sie mit dem Schlüssel, der die Sitzung identifiziert (zum Beispiel eine Lobby-ID oder Party-ID):

local DataStoreService = game:GetService("DataStoreService")
local HttpService = game:GetService("HttpService")
local TeleportService = game:GetService("TeleportService")

local reservedServersStore = DataStoreService:GetDataStore("ReservedServers")

-- Schlüssel, der die gemeinsame Sitzung über Server hinweg identifiziert
local sessionKey = "lobby-123"

-- Eine neue ID erstellt den reservierten Server bei der Ankunft am Ziel
local reservedServerId = HttpService:GenerateGUID(false)
reservedServersStore:SetAsync(sessionKey, reservedServerId)

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerId = reservedServerId

TeleportService:TeleportAsync(TARGET_PLACE_ID, { player }, teleportOptions)

Auf jedem anderen Server, der Spieler zu diesem reservierten Server senden muss, suchen Sie die ID mit demselben Sitzungsschlüssel und setzen Sie sie als TeleportOptions.ReservedServerId des Teleports:

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

local reservedServersStore = DataStoreService:GetDataStore("ReservedServers")

local sessionKey = "lobby-123"

local existingId = reservedServersStore:GetAsync(sessionKey)
if existingId then
	local teleportOptions = Instance.new("TeleportOptions")
	teleportOptions.ReservedServerId = existingId

	TeleportService:TeleportAsync(TARGET_PLACE_ID, { player }, teleportOptions)
end

Auf einem VIP-Server, um die VIP-Server-ID auf dem Zielserver ohne einen Datenstore verfügbar zu machen, fügen Sie sie jedem Spieler mit TeleportOptions:SetTeleportData() hinzu:

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.VipServerId = game.PrivateServerId
teleportOptions:SetTeleportData({ vipServerId = game.PrivateServerId })

TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)

Bei der Ankunft lesen Sie sie aus den Beitrittsdaten des Spielers zurück. Weitere Informationen finden Sie unter Benutzerdaten zusammen mit Teleports senden.

Identifizieren eines reservierten Servers bei der Ankunft

Überprüfen Sie auf dem Zielserver, ob der aktuelle Server ein reservierter Server ist:

local isReserved = game.PrivateServerId ~= "" and game.PrivateServerOwnerId == 0

DataModel.PrivateServerId entspricht der ReservedServerId, die Sie bereitgestellt haben, und bleibt über alle Serverinstanzen für diesen reservierten Server konstant. DataModel.JobId ist einzigartig pro laufender Instanz und ändert sich, wenn der Server neu gestartet wird.

Teleport zu einem VIP-Server

VIP-Server sind private Server, die Spieler von der Spieleseite kaufen können. Um einen Spieler zu einem VIP-Server zu teleportieren, setzen Sie TeleportOptions.VipServerId auf die DataModel.PrivateServerId des Ziel-VIP-Servers.

local TeleportService = game:GetService("TeleportService")

local TARGET_PLACE_ID = 12345678901234
-- Die PrivateServerId des Ziel-VIP-Servers, zum Beispiel über
-- die Beitrittsdaten des Spielers oder aus einem Datenstore gelesen
local vipServerId = player:GetJoinData().TeleportData.vipServerId

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.VipServerId = vipServerId

TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)

TeleportOptions.VipServerId unterscheidet sich von TeleportOptions.ReservedServerId. Verwenden Sie ReservedServerId für von Entwicklern erstellte reservierte Server und VipServerId für von Spielern gekaufte VIP-Server.

Eine VIP-Server-ID ist auf die Erfahrung beschränkt, die den VIP-Server besitzt: Sie können sie mit der Platz-ID eines beliebigen Ortes in dieser Erfahrung verwenden, jedoch nicht mit einer Platz-ID aus einer anderen Erfahrung.

Wenn Sie ein Routing-Feld nicht festlegen, wählt die Engine den Zielserver aus. Ein Teleport ohne festgelegte privaten Server-Routing-Felder kann auf einem öffentlichen Server landen oder, wenn der Spieler kürzlich einem VIP-Server dieser Erfahrung beigetreten ist, auf diesem VIP-Server.

Ein häufiges Anwendungsbeispiel für dieses Muster ist die Rückkehr eines Spielers von einem reservierten Server zurück zum VIP-Server des Stammortes der Erfahrung. Da die game.PrivateServerId eines reservierten Servers seine eigene reservierte ID ist und nicht die des ursprünglichen VIP-Servers, tragen Sie die ID des VIP-Servers in den reservierten Server, indem Sie sie beispielsweise in teleportData beim ausgehenden Teleport übergeben oder sie in einem Datenstore speichern, wie in Wiederverwendung einer reservierten Server-ID gezeigt, und setzen Sie sie dann als TeleportOptions.VipServerId des Rückteleports.

Setzen Sie dieselbe TeleportOptions.VipServerId bei jedem Teleport, um die Spieler während des Spiels im selben VIP-Server über verschiedene Orte hinweg zu halten.

Server-IDs speichern und teilen

Das TeleportAsyncResult-Objekt, das von TeleportService:TeleportAsync() zurückgegeben wird, enthält Informationen über das Ziel:

• TeleportAsyncResult.PrivateServerId - Die private Server-ID des Zielservers. Entspricht DataModel.PrivateServerId am Ziel.
• TeleportAsyncResult.ReservedServerAccessCode - Nur für Legacy-Zugangs-Code-Teleportationen ausgefüllt. Nicht ausgefüllt, wenn ReservedServerId oder VipServerId verwendet wird.

local result = TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)
if result then
    print("Ziel PrivateServerId:", result.PrivateServerId)
end

Migration von Legacy-Zugangs-Codes

Wenn Ihr Spiel die veraltete TeleportOptions.ReservedServerAccessCode oder TeleportOptions.ShouldReserveServer verwendet, migrieren Sie zu ReservedServerId, indem Sie den Zugangs-Code-Flow durch einen GUID-basierten Flow ersetzen:

1. Ersetzen Sie ReserveServerAsync() und ReservedServerAccessCode durch HttpService:GenerateGUID(false) und ReservedServerId.
2. Speichern Sie die generierte GUID, damit Sie sie für nachfolgende Teleports zum selben Server wiederverwenden können.
3. Aktualisieren Sie alle Verwendungen von TeleportOptions, um ReservedServerId anstelle von ReservedServerAccessCode oder ShouldReserveServer festzulegen.

Vorher (veraltet)

-- Veraltet: ReserveServerAsync + ReservedServerAccessCode
local accessCode, privateServerId = TeleportService:ReserveServerAsync(TARGET_PLACE_ID)

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerAccessCode = accessCode
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)

Nachher (aktuell)

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

-- Aktuell: GenerateGUID + ReservedServerId
local reservedServerId = HttpService:GenerateGUID(false)

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerId = reservedServerId
TeleportService:TeleportAsync(TARGET_PLACE_ID, {player}, teleportOptions)

Die veralteten ReserveServerAsync() und ReservedServerAccessCode bleiben zur Rückwärtskompatibilität verfügbar, werden jedoch für neue Arbeiten nicht empfohlen. ReserveServerAsync() reserviert tatsächlich keinen Server im Voraus, sondern generiert einfach eine zufällige GUID. Bestehende reservierte Server, die mit Zugangs-Codes erstellt wurden, funktionieren weiterhin.

Fehlgeschlagene Teleports behandeln

Teleports zu privaten Servern können wie jeder Netzwerkaufruf fehlschlagen. Wickeln Sie sie in pcall ein und versuchen Sie es bei Bedarf erneut. Wenn ein Teleport initiiert wird, aber im letzten Moment fehlschlägt, wird TeleportService.TeleportInitFailed mit den ursprünglichen TeleportOptions ausgelöst, sodass Sie mit demselben Ziel erneut versuchen können.

Für eine vollständige Implementierung des erneuten Versuchs siehe Fehlgeschlagene Teleports behandeln im Hauptteleportleitfaden.

Wenn die Engine selbst einen einfachen Teleport zu einem VIP-Server routet, fallen VIP-spezifische Beitrittsfehler wie ein voller oder überfluteter Server auf einen öffentlichen Beitritt zurück, anstatt TeleportService.TeleportInitFailed auszulösen. Nur Teleports mit einer expliziten TeleportOptions.VipServerId geben diese Fehler an Ihren Wiederholungs-Handler weiter.

Beste Praktiken

• IDs auf dem Server generieren. Rufen Sie immer HttpService:GenerateGUID(false) von einem Server Script auf, um zu verhindern, dass Clients reservierte Server-IDs vorhersagen oder steuern.
• Reservierte Server-IDs speichern. Speichern Sie die GUID in einem Datenstore, wenn Spieler dem selben reservierten Server über Sitzungen hinweg erneut beitreten müssen.
• Verwenden Sie das richtige Feld. Verwenden Sie ReservedServerId für von Entwicklern erstellte reservierte Server, VipServerId für von Spielern gekaufte VIP-Server. Setzen Sie niemals beide auf derselben TeleportOptions-Instanz.
• Mischen Sie keine Routing-Felder. Sie können nur eines von ReservedServerId, VipServerId oder ServerInstanceId gleichzeitig festlegen. Das Setzen von mehr als einem verursacht einen Fehler.