Matchmaking REST API 快速入门

我们强烈建议你考虑使用 Multiplayer SDK,因为它包含实时消息支持,可减少轮询需求。这将改善匹配体验并降低延迟。快速入门 - Client SDK

本快速入门指南将引导你完成集成匹配功能的整个流程。本快速入门中的所有代码示例均适用于 Unity——不过,概念和流程(总体上)同样适用于其他平台。根据你的游戏设计,请考虑单个用户和多个用户匹配部分。本教程演示如何向特定队列提交工单以查找对局。一个队列可能对应一种游戏模式或多种游戏模式(例如,同一队列中的“夺旗”模式和“山丘之王”模式)。匹配服务负责在队列中的工单之间寻找对局。找到对局后,你的游戏必须处理将玩家连接在一起以进行游戏。

在 Game Manager 中配置匹配队列

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

单用户工单匹配

如果你的游戏有 1v1 游戏模式,或支持单个用户独自进入匹配,请考虑单用户匹配。单用户匹配遵循下面所示的模式。

创建匹配工单

用户使用 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 秒轮询一次工单状态。轮询可能会增加检索工单状态时的延迟。因此,我们强烈建议你考虑使用快速入门 - Client SDK 中所述的 Multiplayer 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);

其余流程与单用户工单匹配相同。

将玩家连接在一起

玩家匹配后,你需要让他们相互加入——通过服务器,或通过点对点连接。如果使用专用服务器,可以依靠 Match ID 来唯一识别他们应处于的玩家组。如果使用 PlayFab 的多人游戏服务器,GetMatch 会提供供玩家连接的服务器和端口。有关更多信息,请参阅与 PlayFab Multiplayer Servers 集成。截至本版本,匹配目前未正式支持点对点连接。如果需要点对点,请考虑使用 PlayFab Party 或临时变通方法。有关此方面的更多支持,请与我们联系。

结论

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

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

XBOX Services

PlayFab

Matchmaking 快速入门

Matchmaking REST API 快速入门

在 Game Manager 中配置匹配队列

单用户工单匹配

创建匹配工单

检查匹配工单的状态

获取对局

取消匹配工单

多用户工单匹配

创建匹配工单(多用户)

组成员加入匹配工单

将玩家连接在一起

结论

​Matchmaking REST API 快速入门

​在 Game Manager 中配置匹配队列

​单用户工单匹配

​创建匹配工单

​检查匹配工单的状态

​获取对局

​取消匹配工单

​多用户工单匹配

​创建匹配工单(多用户)

​组成员加入匹配工单

​将玩家连接在一起

​结论

Matchmaking REST API 快速入门

在 Game Manager 中配置匹配队列

单用户工单匹配

创建匹配工单

检查匹配工单的状态

获取对局

取消匹配工单

多用户工单匹配

创建匹配工单(多用户)

组成员加入匹配工单

将玩家连接在一起

结论