Matchmaking SDK 快速入门 - XBOX Game Development Documentation

本快速入门指南将引导你完成使用 PlayFab Multiplayer SDK 为游戏添加匹配功能的整个流程。本教程演示如何向特定队列提交工单以查找对局。一个队列可能对应一种游戏模式或多种游戏模式(例如,同一队列中的“夺旗”模式和“山丘之王”模式)。匹配服务负责在队列中的工单之间寻找对局。找到对局后,你的游戏必须处理将玩家连接在一起以进行游戏。

PlayFab Multiplayer SDK 还提供了 PlayFab Lobby 的 API。 * 有关 C++ API 的更多信息,请参阅 Lobby SDK 快速入门 * 有关 Unity API 的更多信息,请参阅 Unity 快速入门 * 有关 Unreal API 的更多信息,请参阅 Unreal 快速入门

先决条件

你需要一个 PlayFab 帐户才能使用 PlayFab Matchmaking。有关创建帐户的说明,请参阅快速入门:Game Manager。

在 Game Manager 中配置匹配队列

该库会将为在 Game Manager 中配置的队列创建工单的用户匹配在一起。有关如何设置的详细信息,请参阅配置匹配队列。

下载并设置 PlayFab Multiplayer SDK

下载适合你平台的 C/C++ SDK,并将提供程序头文件和库文件集成到你的 build 中。

本快速入门主要关注使用 C/C++ SDK。有关 Unity 和 Unreal 接口,请参阅以下文章: * Unity 快速入门 * Unreal 快速入门

登录 PlayFab 实体

要使用 PlayFab Lobby SDK,你需要使用 PlayFab 实体密钥和实体令牌对客户端进行身份验证。通过 LoginWithCustomId REST API 登录来获取一对 PlayFab 实体密钥和令牌。此 API 也可以通过 PlayFab REST SDK 以 C/C++ 投影方式使用。

LoginWithCustomId 是快速开始使用 PlayFab 功能的一种方式,但并不适合作为你正式发布时使用的登录机制。有关登录指南,请参阅登录基础与最佳实践。

初始化 PlayFab Multiplayer SDK

按照以下基本步骤初始化 PlayFab Multiplayer SDK:

通过调用 PFMultiplayerInitialize 初始化 SDK
通过调用 PFMultiplayerSetEntityToken 设置库代表玩家使用的实体密钥和令牌。

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
}

创建匹配工单

使用 PFMultiplayerCreateMatchmakingTicket 创建匹配工单,在其中指定应作为对局一部分的所有本地用户,以及你希望与这些用户关联的任何属性。此函数还接受一个 PFMatchmakingTicketConfiguration,你可以在其中指定工单对应的队列、工单的超时,以及要匹配到此工单中的任何远程用户。

单个本地用户的匹配

你可以通过调用 PFMultiplayerCreateMatchmakingTicket 为单个本地用户启动匹配。

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);

与一组远程用户的匹配

要开始与远程用户的组匹配,可将某个客户端视为组长。让组长使用 PFMultiplayerCreateMatchmakingTicket 创建工单,并通过 configuration 参数指定组中的其他用户。工单创建后,调用 GetTicketId 以获取工单 ID。通过外部机制(例如网络网格或共享的 PlayFab Lobby)将此 ID 发送给每个其他用户,并让每个客户端使用工单 ID 调用 PFMultiplayerJoinMatchmakingTicketFromId 来加入该匹配工单。工单状态在等待指定玩家加入时将为 PFMatchmakingTicketStatus::WaitingForPlayers,当所有玩家加入工单后将变为 PFMatchmakingTicketStatus::WaitingForMatch。

// 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);

多个本地用户的匹配

在与多个本地用户进行匹配时,不是向 PFMultiplayerCreateMatchmakingTicket 或 PFMultiplayerJoinMatchmakingTicketFromId 函数传入一个 PFEntityKey,而是需要传入一个密钥列表。同样,你需要为每个用户传入一个属性列表。每个列表条目位置应彼此对应。也就是说,属性列表中的第一个条目应是 PFEntityKey 列表中第一位玩家的属性。

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);

检查匹配工单的状态

必须通过调用 PFMultiplayerStartProcessingMatchmakingStateChanges 来接收状态变更,并在处理完这些状态变更后调用 PFMultiplayerFinishProcessingMatchmakingStateChanges,以检查工单的更新。每当工单的状态发生变化时,SDK 都会返回一个 TicketStatusChanged 状态变更;当匹配完成时,SDK 会返回一个 TicketCompleted 状态变更。

使用 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);

获取对局

在收到 PFMatchmakingStateChangeType::TicketCompleted 状态变更后,调用 PFMatchmakingTicketGetMatch 以获取对局的详细信息。这些详细信息将包含对局 ID、已匹配到一起的用户、对局的首选区域,以及与对局关联的大厅编排字符串。从 PFMatchmakingMatchDetails 结构中检索所需的信息后,应使用 PFMultiplayerDestroyMatchmakingTicket 销毁工单。

使用 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);

取消匹配工单

如果你的客户端出于某种原因希望在 PFMatchmakingTicketConfiguration 中设置的超时之前取消匹配过程,请使用工单句柄调用 PFMatchmakingTicketCancel。调用此 API 并不保证工单会被取消。工单可能在取消操作被处理之前已经完成,或者取消请求可能因网络或服务错误而失败。如果希望在继续之前确认工单取消已完成,你仍可以处理匹配状态变更以获取工单的结果。否则,你可以立即调用 PFMultiplayerDestroyMatchmakingTicket。

使用 Matchmaking client SDK 的示例

HRESULT hr = PFMatchmakingTicketCancel(ticket);

PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);

(可选)将玩家连接到 Lobby 中

玩家匹配后,他们可以一起加入一个大厅。已匹配工单的 PFMatchmakingMatchDetails 包含一个 lobbyArrangementString 字段,可用于将用户加入同一个 Lobby。有关 Lobby 与 Matchmaking 如何协同工作的更多信息,请参阅结合使用 lobby 与 matchmaking。有关 PlayFab Lobbies 的更多信息,请参阅 PlayFab Lobby 概览。

使用 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));

结论

使用本快速入门,你现在应该在游戏中拥有一个成功的匹配流程。此外,你还应考虑以下方面:

你的游戏如何处理组的形成。
玩家等待对局时你的游戏显示什么。
如何处理失败和重试。

另请参阅

Lobby SDK

​先决条件

​在 Game Manager 中配置匹配队列

​下载并设置 PlayFab Multiplayer SDK

​登录 PlayFab 实体

​初始化 PlayFab Multiplayer SDK

​创建匹配工单

​单个本地用户的匹配

​与一组远程用户的匹配

​多个本地用户的匹配

​检查匹配工单的状态

​使用 Matchmaking client SDK 的示例

​获取对局

​使用 Matchmaking client SDK 的示例

​取消匹配工单

​使用 Matchmaking client SDK 的示例

​(可选)将玩家连接到 Lobby 中

​使用 Matchmaking client SDK 的示例

​结论

​另请参阅

先决条件

在 Game Manager 中配置匹配队列

下载并设置 PlayFab Multiplayer SDK

登录 PlayFab 实体

初始化 PlayFab Multiplayer SDK

创建匹配工单

单个本地用户的匹配

与一组远程用户的匹配

多个本地用户的匹配

检查匹配工单的状态

使用 Matchmaking client SDK 的示例

获取对局

使用 Matchmaking client SDK 的示例

取消匹配工单

使用 Matchmaking client SDK 的示例

(可选)将玩家连接到 Lobby 中

使用 Matchmaking client SDK 的示例

结论

另请参阅