匹配 REST API 快速入门

项目
07/13/2023

注意

强烈建议考虑使用多人游戏 SDK，因为它包括实时通知支持，从而减少了轮询需求。这将改善匹配体验并减少延迟。快速入门 - 客户端 SDK

本快速入门指南将指导您完成集成匹配功能的整个过程。本快速入门中的所有代码示例均针对 Unity - 但概念和流程（总体上）也适用于其他平台。

根据您的游戏设计，考虑使用单用户和多用户匹配部分。

本教程说明如何将票证提交到特定队列，以便查找游戏。队列可能映射到一个游戏模式或多个游戏模式（例如：同一队列中的夺旗模式和山丘之王模式）。

匹配服务处理队列中的票证之间查找匹配。找到匹配后，游戏必须将玩家连接在一起来玩游戏。

在 Game Manager 中配置匹配队列

本快速入门假定你已在 Game Manager 中配置了队列。有关如何设置匹配队列的详细信息，请参阅配置匹配队列。

单用户票证匹配

如果游戏是一对一游戏模式，或者支持单用户自行进入匹配，可考虑使用单用户匹配。单用户匹配遵循下面所示的模式。

匹配流程

创建匹配票证

用户使用 CreateMatchmakingTicket 创建匹配票证。票证创建成功后，该服务返回 TicketId。

票证创建要求您指定 Creator（用户的身份和属性）、GiveUpAfterSeconds（服务放弃匹配票证前的秒数），以及查找匹配所在的 QueueName。

Creator 字段必须包含与 QueueName 匹配的队列配置所需的用户属性。为防止用户自行放弃，最好将 GiveUpAfterSeconds 时间的值设置为 120 秒。

PlayFabMultiplayerAPI.CreateMatchmakingTicket(
    new CreateMatchmakingTicketRequest
    {
        // The ticket creator specifies their own player attributes.
        Creator = new MatchmakingPlayer
        {
            Entity = new EntityKey
            {
                Id = "<Entity ID goes here>",
                Type = "<Entity type goes here>",
            },

            // Here we specify the creator's attributes.
            Attributes = new MatchmakingPlayerAttributes
            {
                DataObject = new
                {
                    Skill = 24.4
                },
            },
        },

        // Cancel matchmaking if a match is not found after 120 seconds.
        GiveUpAfterSeconds = 120,

        // The name of the queue to submit the ticket into.
        QueueName = "myqueue",
    },

    // Callbacks for handling success and error.
    this.OnMatchmakingTicketCreated,
    this.OnMatchmakingError);

检查匹配票证的状态

您必须按 TicketId 轮询服务，才能访问匹配中票证的 Status。为执行此操作，让游戏调用 GetMatchmakingTicket。每分钟最多可轮询 10 次。例如，每 6 秒轮询一次票证状态。检索票证状态时，轮询可能会增加延迟。正因如此，我们强烈建议考虑使用此快速入门 - 客户端 SDK 中所述的多人游戏 SDK 方法。这样可以避免使用实时通知功能轮询。

当票证的状态变为 Matched 时，客户端可停止轮询票证。从那时起，票证将包含 MatchId。

PlayFabMultiplayerAPI.GetMatchmakingTicket(
    new GetMatchmakingTicketRequest
    {
        TicketId = "<ticket ID goes here>",
        QueueName = "myqueue",
    },
    this.OnGetMatchmakingTicket,
    this.OnMatchmakingError);

获得匹配

从客户端，使用来自 GetMatchmakingTicket 的响应中提供的 MatchId 调用 GetMatch。此匹配包含匹配在一起的用户的列表。

PlayFabMultiplayerAPI.GetMatch(
    new GetMatchRequest
    {
        MatchId = "<match ID goes here>",
        QueueName = "myqueue",
    },
    this.OnGetMatch,
    this.OnMatchmakingError);

取消匹配票证

如果出于某种原因，客户端需要在达到 GiveUpAfterSeconds 前取消匹配过程，请使用 TicketId 调用 CancelMatchmakingTicket。如果尚未发现匹配，则会从匹配过程中取出票证，并且其状态将变为 Canceled。

PlayFabMultiplayerAPI.CancelMatchmakingTicket(
    new CancelMatchmakingTicketRequest
    {
        QueueName = "myqueue",
        TicketId = "<ticket ID goes here>",
    },
    this.OnTicketCanceled,
    this.OnMatchmakingError);

多用户票证匹配

如果游戏允许玩家组一起进入匹配队列，则还需要执行更多操作才能进入匹配。建议您的游戏指定一个组长（创建者），以免进行不必要的调用。组长创建票证，但该组的所有成员都必须同意加入该票证。

创建匹配票证（多用户）

该组必须在游戏中选择一个票证创建者。创建者使用 CreateMatchmakingTicket 创建匹配票证，成功时返回 TicketId。票证创建要求您指定 Creator（用户的身份和属性）、GiveUpAfterSeconds（服务放弃匹配票证前的秒数）、MembersToMatchWith（其他组成员的身份）以及查找匹配所在的 QueueName。

Creator 字段必须包含与 QueueName 匹配的队列配置所需的用户属性。为防止用户自行放弃，最好将 GiveUpAfterSeconds 时间的值设置为 120 秒。

组成员加入匹配票证

创建了匹配票证后，该组的其他成员必须加入该票证才能继续此匹配过程。此时，该票证处于 WaitingForPlayers 状态。在所有 MembersToMatchWith 均加入该票证前，不会开始与其他票证进行匹配。

要让成员加入，Creator 必须通过游戏与其他成员共享 TicketId。然后每个成员都调用 JoinMatchmakingTicket，从而提供他们自己的必需属性。所有成员均加入该票证后，票证状态变为 WaitingForMatch。

PlayFabMultiplayerAPI.JoinMatchmakingTicket(
    new JoinMatchmakingTicketRequest
    {
        TicketId = "<ticket ID>",
        QueueName = "myqueue",
        Member = new MatchmakingPlayer
        {
            Entity = new EntityKey
            {
                Id = "<Entity ID goes here>",
                Type = "<Entity type goes here>",
            },
            Attributes = new MatchmakingPlayerAttributes
            {
                DataObject = new
                {
                    Skill = 19.3
                },
            },
        }
    },
    this.OnJoinMatchmakingTicket,
    this.OnMatchmakingError);

该过程的其余部分与单用户票证匹配过程相同

将玩家连接在一起

玩家匹配后，您需要让他们互相加入 - 通过服务器或通过对等连接。

如果使用专用服务器，可通过匹配 ID 唯一识别玩家应属于的玩家组。如果使用 PlayFab 的多人游戏服务器，GetMatch 将提供玩家要连接到的服务器和端口。

有关详细信息，请参阅与 PlayFab 多人游戏服务器集成。

截至本版本，匹配当前未正式支持对等连接。如果需要对等，请考虑使用 Playfab Party 或[临时解决方法。请联系我们，以便获得有关这方面的更多支持。

总结

通过使用本快速入门，您的游戏现在已有了成功的匹配流程。此外，您还应该考虑：

您的游戏如何处理组形成。
在用户等待匹配时您的游戏显示的内容。
如何处理失败和重试。

通过