Schnellstart: Matchmaking SDK
Diese Schnellstartanleitung führt Sie durch den gesamten Prozess zum Hinzufügen von Matchmaking zu Ihrem Spiel mithilfe des PlayFab Multiplayer SDK.
In diesem Tutorial wird veranschaulicht, wie Sie ein Ticket an eine bestimmte Warteschlange übermitteln, um ein Spiel zu finden. Eine Warteschlange ist wahrscheinlich einem Spielmodus oder mehreren Spielmodi zugeordnet (z. B. einem Capture the Flag-Modus und einem König des Hügelmodus in derselben Warteschlange).
Der Matchmaking-Dienst kümmert sich um die Suche nach einer Übereinstimmung zwischen Tickets in einer Warteschlange. Wenn ein Spiel gefunden wird, muss Ihr Titel die Spieler für das Gameplay miteinander verbinden.
Notiz
Das PlayFab Multiplayer SDK bietet auch APIs für PlayFab-Lobbies.
- Weitere Informationen zu C++-APIs finden Sie im Schnellstart für das Lobby SDK.
- Weitere Informationen zu Unity-APIs finden Sie im Schnellstart für Unity.
- Weitere Informationen zu Unreal-APIs finden Sie im Schnellstart für Unreal.
Voraussetzungen
Sie benötigen ein PlayFab-Konto , um PlayFab Matchmaking verwenden zu können. Anweisungen zum Erstellen eines Kontos finden Sie unter Schnellstart: Game Manager.
Konfigurieren einer Matchmaking-Warteschlange in Game Manager
Die Bibliothek gleicht Benutzer zusammen, die Tickets für Warteschlangen erstellen, die in Game Manager konfiguriert sind. Ausführliche Informationen zum Einrichten einer Warteschlange finden Sie unter Konfigurieren von Matchmaking-Warteschlangen.
Herunterladen und Einrichten des PlayFab Multiplayer SDK
Laden Sie das C/C++-SDK für Ihre Plattform herunter, und integrieren Sie den Anbieterheader und die Bibliotheksdateien in Ihren Build.
Notiz
Dieser Schnellstart konzentriert sich auf die Verwendung des C/C++-SDK. Informationen zu Unity- und Unreal-Schnittstellen finden Sie in den folgenden Artikeln:
Anmelden bei einer PlayFab-Entität
Um das PlayFab Lobby SDK verwenden zu können, müssen Sie Ihren Client mithilfe von PlayFab-Entitätsschlüsseln und Entitätstoken authentifizieren. Rufen Sie einen PlayFab-Entitätsschlüssel und ein Tokenpaar ab, indem Sie sich mit der LoginWithCustomId-REST-API anmelden. Diese API ist auch als C/C++-Projektion über das PlayFab REST SDK verfügbar.
Notiz
LoginWithCustomId ist eine schnelle Möglichkeit für die ersten Schritte mit PlayFab-Features, ist jedoch nicht als Anmeldemechanismus gedacht, mit dem Sie ausgeliefert werden. Anleitungen zur Anmeldung finden Sie unter Grundlagen und bewährte Methoden für die Anmeldung.
Initialisieren des PlayFab Multiplayer SDK
Initialisieren Sie das PlayFab Multiplayer SDK, indem Sie die folgenden grundlegenden Schritte ausführen:
- Initialisieren des SDK durch Aufrufen von PFMultiplayerInitialize
- Legen Sie den Entitätsschlüssel und das Token fest, die von der Bibliothek im Namen Ihrer Spieler verwendet werden, indem Sie PFMultiplayerSetEntityToken aufrufen.
static PFMultiplayerHandle g_pfmHandle = nullptr;
...
...
HRESULT hr = S_OK;
// Initialize the PFMultiplayer library.
hr = PFMultiplayerInitialize(titleId, &g_pfmHandle);
if (FAILED(hr))
{
// handle initialize failure
}
// Set an entity token for a local user. The token is used to authenticate PlayFab operations on behalf of this user.
// Tokens can expire, and this API token should be called again when this token is refreshed.
hr = PFMultiplayerSetEntityToken(g_pfmHandle, localUserEntity, entityToken);
if (FAILED(hr))
{
// handle set entity token failure
}
Erstellen eines Matchmaking-Tickets
Sie erstellen ein Matchmaking-Ticket mit PFMultiplayerCreateMatchmakingTicket, in dem Sie alle lokalen Benutzer angeben, die Teil der Übereinstimmung sein sollen, sowie alle Attribute, die diesen Benutzern zugeordnet werden sollen.
Diese Funktion verwendet auch eine PFMatchmakingTicketConfiguration , in der Sie angeben, für welche Warteschlange sich das Ticket befindet, ein Timeout für das Ticket und alle Remotebenutzer, die Sie diesem Ticket zuordnen möchten.
Matchmaking mit einem einzelnen lokalen Benutzer
Sie können die Matchmaking für einen einzelnen lokalen Benutzer mit einem Aufruf von PFMultiplayerCreateMatchmakingTicket starten.
const char* yourQueueName = ...; // This is the name of the queue you configured in Game Manager.
PFMatchmakingTicketConfiguration configuration{};
configuration.timeoutInSeconds = 120;
configuration.queueName = yourQueueName;
const char* attributes = "\"{\"color\":\"blue\", \"role\":\"tank\"}\"";
const PFMatchmakingTicket* ticket;
HRESULT hr = PFMultiplayerCreateMatchmakingTicket(
g_pfmHandle,
1, // number of local users
localUserEntity,
&attributes,
&configuration,
nullptr, // optional asyncContext
&ticket);
RETURN_IF_FAILED(hr);
Matchmaking mit einer Gruppe von Remotebenutzern
Um mit der Gruppensuche mit Remotebenutzern zu beginnen, ist es hilfreich, sich einen Client als Leader zu vorstellen. Lassen Sie den Leader das Ticket mit PFMultiplayerCreateMatchmakingTicket erstellen und die anderen Benutzer in der Gruppe über den Konfigurationsparameter angeben. Nachdem das Ticket erstellt wurde, rufen Sie GetTicketId auf, um die Ticket-ID abzurufen. Senden Sie diese ID an einen anderen Benutzer über einen externen Mechanismus, z. B. ein Netzwerknetz oder eine freigegebene PlayFab-Lobby, und lassen Sie jeden Client PFMultiplayerJoinMatchmakingTicketFromId mit der Ticket-ID aufrufen, um dem Matchmaking-Ticket beizutreten. Das Ticket status pfMatchmakingTicketStatus::WaitingForPlayers, während auf den Beitritt der angegebenen Spieler gewartet wird, und ändert sich in PFMatchmakingTicketStatus::WaitingForMatch, sobald alle Spieler dem Ticket beigetreten sind.
// Creating the ticket on the leader's client
const char* remoteMemberEntityId1 = ...;
const char* remoteMemberEntityId2 = ...;
std::vector<PFEntityKey> remoteMatchMemberEntityKeys;
remoteMatchMemberEntityKeys.push_back({ remoteMemberEntityId1, "title_player_account" });
remoteMatchMemberEntityKeys.push_back({ remoteMemberEntityId2, "title_player_account" });
const char* yourQueueName = ...; // This is the name of the queue you configured in Game Manager.
PFMatchmakingTicketConfiguration configuration{};
configuration.timeoutInSeconds = 120;
configuration.queueName = yourQueueName;
configuration.membersToMatchWithCount = 2; // number of remote members to match with
configuration.membersToMatchWith = remoteMatchMemberEntityKeys.data();
const char* attributes = "\"{\"color\":\"blue\", \"role\":\"tank\"}\"";
const PFMatchmakingTicket* ticket;
HRESULT hr = PFMultiplayerCreateMatchmakingTicket(
g_pfmHandle,
1, // number of local users
localUserEntity,
&attributes,
&configuration,
nullptr, // optional asyncContext
&ticket);
RETURN_IF_FAILED(hr);
// Getting the ticket ID
PCSTR ticketId;
hr = PFMatchmakingTicketGetTicketId(ticket, &ticketId);
RETURN_IF_FAILED(hr);
// Joining the ticket on the other players' clients
const char* attributes = "\"{\"color\":\"blue\", \"role\":\"healer\"}\"";
const char* yourQueueName = ...; // This is the name of the queue you configured in Game Manager.
const PFMatchmakingTicket* ticket;
HRESULT hr = PFMultiplayerJoinMatchmakingTicketFromId(
g_pfmHandle,
1, // number of local users
localUserEntity,
&attributes,
ticketId,
yourQueueName,
nullptr, // optional asyncContext
&ticket);
Matchmaking mit mehreren lokalen Benutzern
Beim Matchmaking mit mehreren lokalen Benutzern müssen Sie eine Liste von Schlüsseln übergeben, anstatt einen PFEntityKey an die Funktionen PFMultiplayerCreateMatchmakingTicket oder PFMultiplayerJoinMatchmakingTicketFromId zu übergeben. Ebenso müssen Sie eine Liste von Attributen für jeden Benutzer übergeben. Jede Listeneintragsposition sollte einander entsprechen. Das bedeutet, dass der erste Eintrag in der Attributliste die Attribute für den ersten Spieler in der PFEntityKey-Liste sein sollte.
const char* yourQueueName = ...; // This is the name of the queue you configured in Game Manager.
PFMatchmakingTicketConfiguration configuration{};
configuration.timeoutInSeconds = 120;
configuration.queueName = queueName;
std::vector<PFEntityKey> localMatchMemberEntityKeys{ ... };
std::vector<PCSTR> localMatchMemberAttributes{ ... };
const PFMatchmakingTicket* ticket;
HRESULT hr = PFMultiplayerCreateMatchmakingTicket(
g_pfmHandle,
static_cast<uint32_t>(localMatchMemberEntityKeys.size())
localMatchMemberEntityKeys.data(),
localMatchMemberAttributes.data(),
&configuration,
nullptr, // optional asyncContext
&ticket);
RETURN_IF_FAILED(hr);
Überprüfen der status des Matchmaking-Tickets
Sie müssen nach Updates für das Ticket suchen, indem Sie PFMultiplayerStartProcessingMatchmakingStateChanges aufrufen, um Zustandsänderungen zu empfangen, und dann PFMultiplayerFinishProcessingMatchmakingStateChanges aufrufen, wenn Sie mit der Verarbeitung dieser Zustandsänderungen fertig sind.
Das SDK gibt eine TicketStatusChanged-Zustandsänderung zurück, sobald sich die status des Tickets ändert, und eine TicketCompleted-Statusänderung, wenn die Matchmaking abgeschlossen ist.
Beispiel für die Verwendung des Matchmaking-Client-SDK
HRESULT hrTicketError = S_OK;
uint32_t stateChangeCount;
const PFMatchmakingStateChange * const * stateChanges;
hr = PFMultiplayerStartProcessingMatchmakingStateChanges(g_pfmHandle, &stateChangeCount, &stateChanges);
RETURN_IF_FAILED(hr);
for (uint32_t i = 0; i < stateChangeCount; ++i)
{
const PFMatchmakingStateChange& stateChange = *stateChanges[i];
switch (stateChange.stateChangeType)
{
case PFMatchmakingStateChangeType::TicketStatusChanged:
{
const auto& ticketStatusChanged = static_cast<const PFMatchmakingTicketStatusChangedStateChange&>(stateChange);
PFMatchmakingTicketStatus status;
if (SUCCEEDED(PFMatchmakingTicketGetStatus(ticketStatusChanged.ticket, &status)))
{
printf("Ticket status is now: %i.\n", status);
}
break;
}
case PFMatchmakingStateChangeType::TicketCompleted:
{
const auto& ticketCompleted = static_cast<const PFMatchmakingTicketCompletedStateChange&>(stateChange);
printf("PFMatchmaking completed with Result 0x%08x.\n", ticketCompleted.result);
if (FAILED(ticketCompleted.result))
{
// On failure, we must record the HRESULT so we can return the state change(s) and then bail
// out of this function.
hrTicketError = ticketCompleted.result;
}
break;
}
}
}
hr = PFMultiplayerFinishProcessingMatchmakingStateChanges(g_pfmHandle, stateChangeCount, stateChanges);
RETURN_IF_FAILED(hr);
// Now that we've returned the state change(s), bail out if we detected ticket failure.
RETURN_IF_FAILED(hrTicketError);
Abrufen der Übereinstimmung
Nachdem Sie die Zustandsänderung PFMatchmakingStateChangeType::TicketCompleted erhalten haben, rufen Sie PFMatchmakingTicketGetMatch auf, um die Details der Übereinstimmung abzurufen. Diese Details enthalten die Übereinstimmungs-ID, die Benutzer, die zusammengeglichen wurden, und die bevorzugte Region für die Übereinstimmung sowie eine Anordnungszeichenfolge für den Wartebereich, der der Übereinstimmung zugeordnet ist.
Nachdem Sie alle benötigten Informationen aus der PFMatchmakingMatchDetails-Struktur abgerufen haben, sollte das Ticket mit PFMultiplayerDestroyMatchmakingTicket gelöscht werden.
Beispiel für die Verwendung des Matchmaking-Client-SDK
const PFMatchmakingMatchDetails* match;
HREULT hr = PFMatchmakingTicketGetMatch(ticket, &match);
RETURN_IF_FAILED(hr);
std::string matchId = match->matchId;
std::string lobbyArrangementString = match->lobbyArrangementString;
PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);
Stornieren eines Matchmaking-Tickets
Wenn Ihr Kunde aus irgendeinem Grund den Matchmaking-Prozess vor dem im PFMatchmakingTicketConfigurationfestgelegten Timeout abbrechen möchte, rufen Sie PFMatchmakingTicketCancel mit dem Tickethandle auf.
Das Aufrufen dieser API garantiert nicht, dass das Ticket storniert wird. Das Ticket kann trotzdem abgeschlossen werden, bevor die Stornierung verarbeitet werden kann, oder die Stornierungsanforderung kann aufgrund von Netzwerk- oder Dienstfehlern fehlschlagen. Sie sollten weiterhin Matchmaking-Zustandsänderungen verarbeiten, um das Ergebnis des Tickets zu erhalten.
Beispiel für die Verwendung des Matchmaking-Client-SDK
HRESULT hr = PFMatchmakingTicketCancel(ticket);
(Optional) Verbinden Ihrer Spieler in einer Lobby
Nachdem Ihre Spieler abgeglichen haben, können sie sich in einer Lobby zusammenschließen. PfMatchmakingMatchDetails aus dem übereinstimmenden Ticket enthält ein lobbyArrangementString-Feld, das verwendet werden kann, um die Benutzer in denselben Wartebereich zu einbinden.
Weitere Informationen zur Interaktion von Lobby und Matchmaking finden Sie unter Gemeinsames Verwenden von Lobby und Matchmaking.
Weitere Informationen zu PlayFab Lobbies finden Sie unter Übersicht über die PlayFab-Lobby.
Beispiel für die Verwendung des Matchmaking-Client-SDK
const PFMatchmakingMatchDetails* match;
HREULT hr = PFMatchmakingTicketGetMatch(ticket, &match);
RETURN_IF_FAILED(hr);
std::string matchId = match->matchId;
std::string lobbyArrangementString = match->lobbyArrangementString;
PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);
PFLobbyHandle lobby;
RETURN_IF_FAILED_HR(PFMultiplayerJoinArrangedLobby(
m_pfmHandle,
&joiningUser,
lobbyArrangementString,
&joinConfig,
nullptr, // optional asyncContext
&lobby));
Abschluss
In dieser Schnellstartanleitung sollten Sie nun über einen erfolgreichen Matchmaking-Flow in Ihrem Spiel verfügen. Darüber hinaus sollten Sie Folgendes berücksichtigen:
- Wie Ihr Titel die Gruppenbildung behandelt.
- Was Ihr Titel anzeigt, während Benutzer auf eine Übereinstimmung warten.
- Behandeln von Fehlern und Wiederholungen.