マッチメイキング REST API クイックスタート

このクイックスタート ガイドは、マッチメイキング機能を統合するためのプロセスについて説明しています。 このクイックスタート内のコード例はすべて Unity 向けです。ただし、コンセプトと流れは (一般的に) 他のプラットフォームにも適用されます。

ゲーム デザインに応じて、シングル ユーザーと複数ユーザーのマッチメイキング セクションについて考慮します。

このチュートリアルでは、ゲームを見つけるために、チケットを特定のキューに送信する方法を説明します。 キューは、ゲーム モードまたは複数のゲーム モードにマッピングされる可能性があります (例: 同じキュー内のフラグ モードのキャプチャとヒル モードのキング)。

マッチメイキング サービスは、キュー内のチケットの中から一致するものを見つける処理を行います。 マッチが見つかった場合、タイトルはゲームプレイのためにプレイヤー同士を結びつけます。

ゲーム マネージャーでマッチメイキング キューを構成する

このクイック スタートでは、ゲーム マネージャーでキューが構成されていることを前提としています。 設定方法の詳細については、「マッチメイキング キューの構成」を参照してください。

シングル ユーザー チケットのマッチメイキング

ゲームが 1v1 ゲームモードを持っているか、マッチメイキングを入力するシングル ユーザーをサポートしている場合、シングル ユーザー マッチメイキングを検討してください。 シングル ユーザーのマッチメイキングは、次に示すパターンに従います。

マッチメイキング チケットを作成する

ユーザーは、CreateMatchmakingTicket を使用して、マッチメイキング チケットを作成します。 チケットの作成が成功した場合、サービスは、TicketId を返します。

チケットを作成するには、Creator (ユーザーの ID や属性)、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 を呼び出します。 1 分あたり最大 10 回ポーリングできます。 たとえば、チケットのステータスを 6 秒ごとにポーリングします。 ポーリングにより、チケットの状態を取得するときの遅延が増える可能性があります。 このため、「クイック スタート - クライアント SDK」 で説明されている Multiplayer SDK メソッドの使用を強くお勧めします。 これにより、リアルタイム通知機能を使用してポーリングする必要がなくなります。

チケットのステータスが Matched に変わった際、クライアントはチケットのポーリングを停止することができます。 その時点から、チケットには MatchId が含まれます。

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

マッチを取得する

クライアントから、GetMatch を MatchId で呼び出しますが、ID は、GetMatchmakingTicket からの応答に含まれます。 このマッチには、一致したユーザーの一覧が含まれます。

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

マッチメイキング チケットのキャンセル

何らかの理由で GiveUpAfterSeconds に到達する前にクライアントがマッチメイキング プロセスをキャンセルしたい場合は、CancelMatchmakingTicket を TicketId で呼び出します。 マッチがまだ見つかっていない場合は、チケットはマッチメイキング プロセスから除外され、ステータスは Canceled に変わります。

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

複数ユーザー チケットのマッチメイキング

ゲームがプレイヤーのグループが一緒にマッチメイキング キューに入ることを許可している場合、マッチメイキングに入るためにしなければならないことがいくつかあります。 不要な呼び出しを行わないように、タイトルにはグループ リーダー (作成者) を割り当てることをお勧めします。 リーダーがチケットを作成しますが、グループのメンバー全員が参加に同意する必要があります。

マッチメイキング チケットを作成する (複数のユーザー)

グループはタイトルでチケット作成者を選出する必要があります。 作成者は CreateMatchmakingTicket を使用してマッチメイキングチケットを作成し、成功時に TicketId を返します。 チケットを作成するには、Creator(ユーザーの ID と属性)、GiveUpAfterSeconds (サービスがチケットのマッチングを断念するまでの秒数)、MembersToMatchWith (他のグループ メンバーの ID)、マッチを見つけるための 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 パーティーを使用するか、暫定的な回避策を使用することを検討してください。 詳細については、マイクロソフトにお問い合わせください。

まとめ

このクイック スタートを使用して、ゲームで成功したマッチメイキング フローを持つ必要があります。 以下の点について考えます。

• タイトルがグループ編成を行う方法。
• ユーザーがマッチを待っている間にタイトルが表示する内容。
• エラーの処理と再試行を行う方法。