> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Matchmaking API リファレンス

マッチメイキング機能




対戦相手や協力相手を実現するサービスです。

マッチメイキングの流れは以下です。

ホストがギャザリングの作成<br>
↓<br>
参加者が条件にみあうギャザリングを検索<br>
↓<br>
規定人数が集まったらマッチメイキング完了

GS2-Matchmaking はこの流れのうち `参加者が条件にみあうギャザリングを検索` に関してできるだけ多くのニーズをみたせるよう設計されています。<br>
ここでは、ユースケースを交えつつ、その設計例を解説します。

* 同じゲームモードを希望する対戦相手を見つけたい

ゲーム内には、カジュアルプレイヤー向けと、コアゲーマー向けの2種類のゲームモードがあります。<br>
これらのプレイヤーを混ぜることなくマッチメイキング処理を行いたいとします。

ギャザリングを作成する際にも、ギャザリングを検索する際にも、最大5つの属性値を指定できます。<br>
ギャザリングを作成する際には募集するプレイヤーが持つ属性値の範囲を指定し、<br>
ギャザリングを検索する際には、自身の属性値の値を指定して処理依頼をします。

つまり、ホストがギャザリングを作成する際に `属性値1` に募集するゲームモードを指定し、<br>
検索する側も自分が参加したいゲームモードを `属性値1` に指定することで、希望するゲームモードが同じプレイヤー同士がマッチメイキングされます。

* 1 に加えて同じレベル帯の対戦相手を見つけたい

ホストはギャザリングを作成する際に `属性値2` に募集するレベルの最小値と最大値を指定します。<br>
検索する側は自分のレベルを `属性値2` に指定することで、同じレベル帯のプレイヤー同士がマッチメイキングされます。

複数の属性値を指定した場合はすべての属性値の範囲をみたす相手を探すよう処理されます。

* 2 に加えて待ち時間が長くなったときに募集するレベル帯を広げたい

最初は狭い範囲で募集し、なるべく同じレベルのプレイヤー同士でマッチメイキングするが、なかなか対戦相手が見つからない場合、募集するレベル帯を広げて募集したいとします。<br>
ギャザリングを作成しておよそ1分ごとに発火する GS2-Script イベントがあります。<br>
このスクリプトにて、ギャザリングの属性値の範囲を緩和することで、徐々に希望する条件を緩和する処理を実装できます。

* フレンドだけが参加できるギャザリングを作る

ギャザリングを作成するときのオプションとして、参加を許可するユーザーIDリストを指定できます。<br>
これを使い、フレンドのユーザーIDリストを指定することで、参加者を限定することができます。

* ハラスメントをしてきたプレイヤーとマッチメイキングされないようにしたい

ギャザリングの作成時・検索時にユーザーIDのブラックリストを指定できます。<br>
検索時に指定したブラックリストは、条件に一致するギャザリングを発見し、参加したギャザリングのブラックリストに加えられます。<br>
検索する際に自身がブラックリストに入っている場合はマッチメイキングの対象から除外されます。

* ロール別マッチメイキング

ゲームによっては盾役1人、回復役1人、攻撃役2人でマッチメイキングを行いたいことがあります。<br>
このときに使用できるのが `ロール属性` です。

盾役として `tank` を、回復役として `healer` を、攻撃役として `attacker` というロールを想定します。<br>
ギャザリングを作成するときに各ロールの募集人数を設定します。<br>
ギャザリングの検索時に自分のロールに設定することで、ロールに関して空きのあるギャザリングだけが参加可能なギャザリングとして処理されます。

募集ロールにはエイリアスを設定することもできます。<br>
例えば、 `tank` を更に具体的なロールで表現し、 `paladin` と `warrior` と `dark_knight` のいずれかとしてギャザリングの検索を行うとします。<br>
ギャザリングを作成するときに、 `tank` のエイリアスに `paladin` と `dark_knight` を指定した場合、 `warrior` は参加できないギャザリングが作成できます。

* 追加募集

マッチメイキング完了後に、1名が離脱し 1名だけ補充したいときに使用します。<br>
このときに使用するのがパーティトークンです。パーティトークンを発行するには、パーティを編成するプレイヤーのプレイヤートークンが必要です。<br>
プレイヤートークンはプレイヤー自身が自分の代わりにパーティの代表者がマッチメイキングを行うことを許可するトークンで、3分間の有効期限があります。<br>
パーティメンバーはそれぞれ、プレイヤートークンを発行するAPIに依頼をしてプレイヤートークンを入手し、パーティの代表者に送信します。<br>
パーティの代表者はパーティメンバーからプレイヤートークンを受け取り、3分以内にパーティトークン発行APIに送信することで、パーティトークンを入手できます。<br>
パーティトークンには10分の有効期限があり、10分以内にパーティトークンを使用してギャザリング作成処理または、ギャザリング検索処理を呼び出します。<br>
こうすることで、パーティメンバー全員が参加した状態のギャザリングを作成、またはパーティメンバー全員が参加できるギャザリングに参加します。

* パーティ同士のマッチメイキング

4 vs 4 で対戦するゲームで、事前に編成したパーティを敵味方に分散することなく対戦したいことがあります。<br>
たとえば、事前に3人で編成したパーティと、事前に4人で編成したパーティ、そして1人の野良プレイヤーをマッチメイキングして、<br>
`事前に3人で編成したパーティ + 1人の野良プレイヤー` vs `事前に4人で編成したパーティ` という対戦を実現したいとします。<br>
このようなケースでは、まずは4人のマッチメイキングを実行します。<br>
すると、`3人で編成したパーティ + 1人の野良プレイヤー` と `事前に4人で編成したパーティ` の2つのギャザリングができます。<br>
その後、それぞれのパーティの代表者が 定員2人のマッチメイキングをおこない、パーティ同士がマッチメイキングされます。<br>
こうすることで `事前に3人で編成したパーティ + 1人の野良プレイヤー` vs `事前に4人で編成したパーティ` を実現できます。

* マッチメイキング中のプレイヤー間の通信

マッチメイキングが完了していない状態でプレイヤー間のやりとりを必要とすることがあります。<br>
GS2-Matchmaking では、ギャザリングの作成時にプレイヤー間の通信をする手段として2種類の方法を提供します。

- GS2-Chat と連携したチャットルーム作成
- GS2-Realtime と連携したゲームサーバの起動

募集が終わっていない状態でも、プレイヤー間でメタデータを低頻度で交換したい場合は前者を、<br>
募集しながらNPCを交えたり人数が不足した状態でゲームを遊ばせたい場合は後者を使用します。

低頻度・高頻度の判断基準として使用できるのが GS2-Chat の持つ制限です。<br>
GS2-Chat は1つのチャットルームに対して秒間3回しか発言ができません。この頻度を超える場合は GS2-Realtime を使用してください。

* マッチメイキング完了後の処理の方法

マッチメイキングが完了したときに `GS2-Gateway を使用したゲーム内プッシュ通知` か `GS2-JobQueue によるジョブ登録` でプレイヤーにマッチメイキングの完了を知らせることができます。<br>
また、GS2-Script を使用して任意のスクリプトを実行することもできます。<br>
GS2-Realtime を使用してマッチメイキング後の対戦・協力プレイを実現する場合は、マッチメイキング完了後に実行される GS2-Script で<br>
GS2-Realtime のギャザリングを作成し、そのギャザリングのIPアドレス・ポートの情報を `GS2-Gateway を使用したゲーム内プッシュ通知` か `GS2-JobQueue によるジョブ登録` を使用して通知することで、ゲームサーバに誘導できます。

[マイクロサービス紹介 / GS2-Matchmaking](../../microservices/matchmaking)



- [GS2-Matchmaking Deploy/CDK リファレンス](/ja/api_reference/matchmaking/deploy/)
  
- [GS2-Matchmaking SDK API リファレンス](/ja/api_reference/matchmaking/sdk/)
  
- [GS2-Matchmaking SDK for Game Engine API リファレンス](/ja/api_reference/matchmaking/game_engine/)
  
- [GS2-Matchmaking スクリプト トリガー リファレンス](/ja/api_reference/matchmaking/script/)
  
- [GS2-Matchmaking トランザクションアクション](/ja/api_reference/matchmaking/stamp_sheet/)
  
- [GS2-Matchmaking マスターデータリファレンス](/ja/api_reference/matchmaking/master_data/)