> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Matchmaking SDK for Game Engine API リファレンス
ゲームエンジン向け GS2-Matchmaking SDK の モデルの仕様 と API のリファレンス
## モデル
### EzGathering
ギャザリング
マッチメイキングによって集められたゲームプレイヤーグループを表すエンティティです。
マッチメイキング用のパラメータを複数持っており、パラメータを総合的に判断してプレイヤーをグルーピングします。
プレイヤーは自身のロール・属性値・拒否リスト（一緒にプレイしたくないユーザー）を指定してギャザリングに参加します。
参加時には属性値の範囲条件、ロールの定員、ホワイトリスト制限（allowUserIds）が検証されます。
すべてのロール枠が定員に達するとギャザリングは完成状態となり、マッチメイキングが完了します。
ギャザリング名は UUID 形式で自動生成され、有効期限を設定して自動クリーンアップすることも可能です。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| gatheringId | string | | ※ | | ~ 1024文字 | ギャザリングGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | UUID | ~ 128文字 | ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。 |
| attributeRanges | [List<EzAttributeRange>](#ezattributerange) | | | [] | 0 ~ 5 items | 募集条件
このギャザリングに参加するためにプレイヤーが満たすべき属性範囲条件のリスト。
各エントリは属性名と許容される最小値・最大値の範囲を指定します。
プレイヤー自身の属性値がこの範囲内でなければ参加できません。最大5件。 |
| capacityOfRoles | [List<EzCapacityOfRole>](#ezcapacityofrole) | | | [] | 1 ~ 5 items | 募集枠リスト
このギャザリングの募集枠を定義します。
各エントリはロール名、その別名、およびそのロールに参加可能な最大人数を指定します。
すべてのロール枠が定員に達するとマッチメイキングが完了となります。最小1件、最大5件。 |
| allowUserIds | List<string> | | | [] | 0 ~ 100 items | 参加許可ユーザーIDリスト
このギャザリングへの参加を許可されたユーザーIDのホワイトリスト。
指定した場合、リストに含まれるユーザーのみがこのギャザリングのマッチメイキングに参加できます。
フレンド限定マッチメイキングや招待制マッチメイキングに利用します。最大100件。 |
| metadata | string | | | | ~ 1024文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| expiresAt | long | | | | | ギャザリングの有効期限
このギャザリングが自動的に期限切れとなり削除される時刻。
この時刻までにマッチメイキングが完了しない場合、ギャザリングはクリーンアップされます。
未指定の場合、マッチメイキングが完了するか手動で削除されるまでギャザリングは維持されます。 |
| createdAt | long | | ※ | 現在時刻 | | 作成日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
cancelMatchmaking - マッチメイキングをキャンセルしてギャザリングから離脱する
createGathering - マッチメイキング用の部屋（ギャザリング）を新規作成する
doMatchmaking - 参加可能なギャザリングを探して参加する
earlyCompleteMatchmaking - 定員に達していない状態でマッチメイキングを早期完了する
getGathering - ギャザリングの現在の状態を取得する
ping - マッチメイキング待機中のキープアライブを送信する
updateGathering - ギャザリングの募集条件を変更する
---
### EzRating
レーティング
ゲームプレイヤー毎の現在のレーティングの値を保持するエンティティです。
プレイヤーが初めてレーティング付きマッチメイキングに参加した時に自動的に作成されます。
レーティングは Glicko-2 アルゴリズムを使用して計算され、初期レート値とレーティングの不確実性を表す Rating Deviation (rd) を持ちます。
対戦回数が増えるにつれて、レート値はプレイヤーの真の実力に収束していきます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| ratingId | string | | ※ | | ~ 1024文字 | レーティングGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | レーティング名
レーティング固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| rateValue | float | | | 1500.0 | 0 ~ 65535.0 | レート値
Glicko-2 アルゴリズムで計算されたプレイヤーの現在のレーティングスコア。
RatingModel で定義された初期値（通常 1500.0）がデフォルトです。
対戦結果と対戦相手の相対的な強さに基づいて値が増減します。 |
| createdAt | long | | ※ | 現在時刻 | | 作成日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getRating - 特定カテゴリのプレイヤーのレーティングスコアを取得する
listRatings - プレイヤーの全カテゴリのレーティングスコアを取得する
---
### EzJoinedSeasonGathering
参加中のシーズンギャザリング
特定のシーズンとティアーにおいて、プレイヤーがどのシーズンギャザリングに参加しているかを追跡するレコード。
プレイヤーがシーズンギャザリングに参加した際に自動的に作成され、プレイヤーの現在のギャザリングを素早く検索するためのインデックスとして機能します。
各プレイヤーはシーズンとティアーの組み合わせごとに最大1つのシーズンギャザリングに所属できます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| seasonName | string | | ✓ | | ~ 128文字 | シーズンモデル名
シーズンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン |
| tier | long | | ✓ | | 0 ~ 9223372036854775805 | ティアー
同程度のランクのプレイヤーをグルーピングするためのティアーレベル。
SeasonModel で指定された GS2-Experience モデルにおけるプレイヤーのランクによって決定されます。
プレイヤーは同じティアーのプレイヤーとのみマッチングされ、公平な対戦が保証されます。 |
| seasonGatheringName | string | | ✓ | | ~ 128文字 | シーズンギャザリング名
このプレイヤーが参加しているシーズンギャザリングの名前。
同一シーズン・ティアー内の特定のシーズンギャザリングエンティティを参照するために使用されます。 |
**関連するメソッド:**
getJoinedSeasonGathering - 特定のシーズンでプレイヤーが参加したシーズンギャザリングを取得する
listJoinedSeasonGatherings - プレイヤーが参加したシーズンギャザリングの一覧を取得する
---
### EzSeasonGathering
シーズンギャザリング
シーズン期間中にプレイヤーを集める永続的なギャザリング。
マッチメイキング完了後に解散する通常のギャザリングとは異なり、シーズンギャザリングはシーズン中ずっと存続し参加者を蓄積します。
プレイヤーはティアー（GS2-Experience のランクに基づく）とシーズン番号でグルーピングされ、各シーズンギャザリングには SeasonModel で定義された最大参加人数の制限があります。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| seasonGatheringId | string | | ※ | | ~ 1024文字 | シーズンギャザリングGRN
※ サーバーが自動で設定 |
| seasonName | string | | ✓ | | ~ 128文字 | シーズンモデル名
シーズンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン |
| tier | long | | ✓ | | 0 ~ 9223372036854775805 | ティアー
同程度のランクのプレイヤーをグルーピングするためのティアーレベル。
SeasonModel で指定された GS2-Experience モデルにおけるプレイヤーのランクによって決定されます。
プレイヤーは同じティアーのプレイヤーとのみマッチングされ、公平な対戦が保証されます。 |
| name | string | | ✓ | UUID | ~ 128文字 | シーズンギャザリング名
シーズンギャザリング固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| participants | List<string> | | | [] | 0 ~ 1000 items | 参加者のユーザーIDリスト
このシーズンギャザリングに参加したプレイヤーのユーザーIDリスト。
プレイヤーが参加するとこのリストに追加され、最大参加人数に達するまでシーズン中ずっと増え続けます。 |
**関連するメソッド:**
doSeasonMatchmaking - 参加可能なシーズンマッチを検索して参加する
getSeasonGathering - シーズンギャザリングの現在の状態を取得する
---
### EzBallot
投票用紙
レーティング付きマッチメイキングのゲーム終了後に、各プレイヤーが対戦結果を報告するために発行される投票用紙。
レーティングモデル名、ギャザリング名、参加人数といった対戦のコンテキスト情報を含みます。
各プレイヤーはサーバーで署名された投票用紙を受け取り、ゲーム結果を記入して Vote API に提出します。
投票システムは、レーティング計算を確定するために提出された投票用紙の50%超の合意を必要とします。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| ratingName | string | | ✓ | | ~ 128文字 | レーティング名
この対戦後のレーティング計算に使用する RatingModel の名前。
この対戦の結果処理に適用されるレーティングシステムのパラメータ（初期値、ボラティリティ）を特定します。 |
| gatheringName | string | | ✓ | | ~ 128文字 | ギャザリング名
対戦結果の報告対象となるギャザリングの名前。
特定のマッチメイキングセッションを識別し、同じ対戦の全参加者からの投票を関連付けるために使用されます。 |
| numberOfPlayer | int | | ✓ | | 2 ~ 10 | 参加人数
この対戦に参加したプレイヤーの総数。
期待される投票数の決定と合意の検証（プレイヤーの50%超が一致する結果を提出する必要がある）に使用されます。
2 から 10 の範囲で指定します。 |
**関連するメソッド:**
createVote - 対戦結果報告用の署名付き投票用紙を作成する
vote - 対戦結果を投票する
voteMultiple - 全投票用紙をまとめて送信し、対戦結果を即座に確定する
---
### EzRatingModel
レーティングモデル
GS2 ではレーティングアルゴリズムとして Glicko-2 を採用しています。
Glicko-2 には複数のパラメータがありますが、GS2-Matchmaking ではそれらを総合的に表す ボラティリティ という1つのパラメータに集約しています。
ボラティリティ は変化の大きさを表すパラメータで、値が大きいほどレーティングの値の変動量が大きくなります。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128文字 | レーティングモデル名
レーティングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 128文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| volatility | int | | | 100 | 1 ~ 20000 | レーティングのボラティリティ
各対戦後にレート値がどの程度変動するかを制御する Glicko-2 のパラメータ。
値が大きいほどレーティングの変動幅が大きくなり、より早くレーティングが調整されます。
値が小さいほどレーティングが安定し、緩やかに変化します。デフォルトは 100 です。 |
**関連するメソッド:**
getRatingModel - 特定のレーティング設定の詳細を取得する
listRatingModels - レーティング設定の一覧を取得する
---
### EzSeasonModel
シーズンモデル
シーズンマッチメイキングにおいて、一定期間有効な永続ギャザリングの期間・最大参加人数・ティアー連携設定を定義するマスターデータです。
GS2-Schedule により期間を管理し、必要に応じて GS2-Experience と連携して同一ティアー内で永続ギャザリングを形成します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128文字 | シーズンモデル名
シーズンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 128文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| maximumParticipants | int | | ✓ | | 2 ~ 1000 | 最大参加人数
1つのシーズンギャザリングに参加可能なプレイヤーの最大人数。
この上限に達するとシーズンギャザリングは満員となり、それ以上のプレイヤーは参加できなくなります。
2 から 1000 の範囲で指定します。 |
| experienceModelId | string | | | | ~ 1024文字 | ティアー管理用の経験値モデルGRN
プレイヤーのティアーを決定するために使用する GS2-Experience の経験値モデルの GRN。
この経験値モデルにおけるプレイヤーのランクがマッチメイキングのティアーとして使用され、同程度のレベルのプレイヤー同士がグルーピングされます。
未指定の場合、ティアーによるグルーピングは無効となり、レベルに関係なく全プレイヤーがマッチングされます。 |
| challengePeriodEventId | string | | ✓ | | ~ 1024文字 | チャレンジ期間イベントGRN
このシーズンの有効期間を定義する GS2-Schedule イベントの GRN。
このイベントがアクティブな間のみ、シーズンギャザリングの作成・参加が可能です。
イベント期間が終了するとシーズンがクローズし、新しいマッチメイキングはできなくなります。 |
**関連するメソッド:**
getSeasonModel - 特定のシーズンマッチメイキング設定の詳細を取得する
listSeasonModels - シーズンマッチメイキング設定の一覧を取得する
---
### EzPlayer
参加者のプレイヤー情報
マッチメイキングに参加するプレイヤーを表し、ID、属性、ロール、拒否リストを含みます。
ギャザリングに参加する際、プレイヤーの属性値、希望するロール、一緒にプレイしたくないユーザーのリストを持つ Player オブジェクトが作成されます。
プレイヤーの属性はギャザリングの属性範囲条件と照合され、拒否リストは不要なペアリングを防ぐためにクロスチェックされます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| attributes | [List<EzAttribute>](#ezattribute) | | | [] | 0 ~ 5 items | 属性値のリスト
マッチメイキング条件の評価に使用されるプレイヤーの名前付き数値属性。
各属性はギャザリングの AttributeRange 条件と照合され参加資格が判定されます。
ギャザリング作成時に範囲条件を設定する場合、プレイヤー自身の属性値もその範囲内である必要があります。最大5件。 |
| roleName | string | | | "default" | ~ 128文字 | ロール名
このプレイヤーがギャザリングで埋めたいロール。
ロール区分のない一般的なマッチメイキングの場合、デフォルト値 "default" を使用します。
ロールベースのマッチメイキングの場合、プレイヤーの具体的なロール（例: "パラディン"、"ナイト"）を指定し、ギャザリングの定員定義のロール名および別名とマッチングされます。 |
| denyUserIds | List<string> | | | [] | 0 ~ 100 items | 参加拒否ユーザーIDリスト
このプレイヤーがマッチングを拒否するユーザーIDのブラックリスト。
マッチメイキング時、ギャザリングに既に参加しているプレイヤーがこのリストに含まれている場合、そのギャザリングに参加できません。
逆に、既存の参加者の拒否リストにこのプレイヤーが含まれている場合も参加がブロックされます。最大100件。 |
**関連するメソッド:**
createGathering - マッチメイキング用の部屋（ギャザリング）を新規作成する
doMatchmaking - 参加可能なギャザリングを探して参加する
**関連するモデル:**
EzCapacityOfRole - 募集枠
---
### EzAttributeRange
募集条件
ギャザリングに参加するための属性の許容範囲を定義する条件。
プレイヤーが参加を試みる際、対応する名前の属性値が指定された最小値・最大値の範囲内である必要があります。
スキルベースやレベルベースのマッチメイキングフィルターを作成するために使用されます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128文字 | 属性名
この範囲条件を適用する属性の名前。
条件が評価されるためには、プレイヤーの属性リスト内の属性名と一致する必要があります。 |
| min | int | | | 0 | 0 ~ 2147483646 | 属性値の最小値
ギャザリングに参加するために必要な属性値の下限（この値を含む）。
属性値がこの閾値を下回るプレイヤーは参加できません。 |
| max | int | | | 0 | 0 ~ 2147483646 | 属性値の最大値
ギャザリングに参加可能な属性値の上限（この値を含む）。
属性値がこの閾値を超えるプレイヤーは参加できません。 |
**関連するメソッド:**
createGathering - マッチメイキング用の部屋（ギャザリング）を新規作成する
updateGathering - ギャザリングの募集条件を変更する
**関連するモデル:**
EzGathering - ギャザリング
---
### EzCapacityOfRole
募集枠
ギャザリング内の特定のロールに対する募集枠を定義します。
各ロールは名前、オプションの別名、最大定員、および現在参加しているプレイヤーリストを持ちます。
ロールの別名により柔軟なマッチングが可能です。例えば「タンク」ロールに「パラディン」「ナイト」の別名を設定すると、どちらのサブロールを指定したプレイヤーもタンク枠を埋められます。
すべてのロールの参加者が定員に達すると、ギャザリングのマッチメイキングが完了します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| roleName | string | | | "default" | ~ 128文字 | ロール名
この募集枠のロール名。
ロール区分のない一般的なマッチメイキングの場合、デフォルト値 "default" を使用します。
ロールベースのマッチメイキング（例: "タンク"、"ヒーラー"、"アタッカー"）の場合、ここにロールカテゴリ名を指定します。 |
| roleAliases | List<string> | | | [] | 0 ~ 9 items | ロール名の別名リスト
この募集枠で受け入れ可能な代替ロール名。
これらの別名のいずれかをロール名として指定したプレイヤーが、この枠にマッチングされます。
サブロールマッチングを実現します。例: "タンク" ロールに対する "パラディン" と "ナイト" の別名。最大9件。 |
| capacity | int | | ✓ | | 1 ~ 256 | 募集人数
このロール枠を埋めることができるプレイヤーの最大数。
参加者数がこの定員に達すると、ロールは満員となりこのロールのプレイヤーはそれ以上参加できません。
1 から 256 の範囲で指定します。 |
| participants | [List<EzPlayer>](#ezplayer) | | | [] | 0 ~ 1000 items | 参加者のプレイヤー情報リスト
現在このロール枠を占有しているプレイヤーのリスト。
プレイヤーはギャザリングに参加すると追加され、離脱すると削除されます。
各プレイヤーエントリにはユーザーID、属性、ロール名、拒否リストが含まれます。ユーザーIDによる一意性が保証されます。 |
**関連するメソッド:**
createGathering - マッチメイキング用の部屋（ギャザリング）を新規作成する
**関連するモデル:**
EzGathering - ギャザリング
---
### EzAttribute
属性値
マッチメイキングのためにプレイヤーに関連付けられた名前付きの数値属性。
ギャザリングの AttributeRange 条件と組み合わせて、どのプレイヤーが参加可能かをフィルタリングするために使用されます。
例えば「レベル」属性の値が 50 のプレイヤーは、レベル 40〜60 を要求するギャザリングにマッチします。
各プレイヤーは最大5つの属性を持てます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128文字 | 属性名
属性固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| value | int | | | 0 | 0 ~ 2147483646 | 属性値
このプレイヤーの属性の数値。
マッチメイキング時にギャザリングの AttributeRange 条件で指定された最小値・最大値の範囲と照合されます。 |
**関連するモデル:**
EzPlayer - 参加者のプレイヤー情報
---
### EzGameResult
対戦結果
Vote システムを通じたレーティング計算に使用される、対戦における1人のプレイヤーの結果を表します。
各 GameResult エントリはユーザーIDとその対戦での順位（最終順位）をペアにします。
順位の値が小さいほど高い成績を示します（1位 = rank 1）。同じ順位のプレイヤーは引き分けとして扱われます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rank | int | | ✓ | | 0 ~ 2147483646 | 順位
対戦におけるプレイヤーの最終順位。1 が最上位（勝者）です。
Glicko-2 アルゴリズムによるレーティング変動の計算に使用されます。上位のプレイヤーはレーティングが上昇し、下位のプレイヤーはレーティングが低下します。
同じ順位のプレイヤーは引き分けとして処理されます。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
**関連するメソッド:**
vote - 対戦結果を投票する
voteMultiple - 全投票用紙をまとめて送信し、対戦結果を即座に確定する
---
### EzSignedBallot
署名付き投票用紙
真正性を検証するためのデジタル署名が付与された投票用紙。
マッチメイキング完了後にサーバーがプレイヤーに署名付き投票用紙を発行し、正当な参加者のみが対戦結果を提出できることを保証します。
投票用紙が Vote API に提出される際に署名が検証され、対戦コンテキスト（レーティング名、ギャザリング名、参加人数）の改ざんを防止します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| body | string | | ✓ | | ~ 1024文字 | 投票用紙本体
デジタル署名の対象となるシリアライズされた投票用紙データ。
署名と照合して検証可能な形式で、投票コンテキスト（ユーザーID、レーティング名、ギャザリング名、参加人数）を含みます。 |
| signature | string | | ✓ | | ~ 256文字 | 署名
投票用紙本体の真正性と完全性を検証するためのデジタル署名。
GS2-Key の暗号化キーを使用してサーバーで生成され、投票用紙の提出時に偽造や改ざんを防止するために検証されます。 |
**関連するメソッド:**
voteMultiple - 全投票用紙をまとめて送信し、対戦結果を即座に確定する
---
### EzTimeSpan
時間間隔（期間）
日・時間・分で構成される時間の長さを表します。
現在時刻からのギャザリングの有効期限など、相対的な時間オフセットの指定に使用されます。
全体の期間は3つのコンポーネントを合算して計算されます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| days | int | | | 0 | 0 ~ 365 | 日数
期間における日数。最大365日。デフォルトは0。 |
| hours | int | | | 0 | 0 ~ 24 | 時間
期間における時間数。最大24時間。デフォルトは0。 |
| minutes | int | | | 0 | 0 ~ 60 | 分
期間における分数。最大60分。デフォルトは0。 |
**関連するメソッド:**
createGathering - マッチメイキング用の部屋（ギャザリング）を新規作成する
---
## メソッド
### cancelMatchmaking
マッチメイキングをキャンセルしてギャザリングから離脱する
プレイヤーが現在参加しているギャザリングから離脱し、マッチメイキングを中止します。
マッチメイキング待機画面で「キャンセル」ボタンをタップしたときに使います。
注意: キャンセルしようとした瞬間にマッチメイキングが完了していた場合、ギャザリングが既に存在しないため NotFoundException（404エラー）が返されます。
ゲーム側ではこのケースをハンドリングしてください。マッチが成立したということなので、プレイヤーをそのままゲームに進めてください。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gatheringName | string | | ✓| UUID | ~ 128文字 | ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGathering](#ezgathering) | キャンセルしたギャザリング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Gathering(
gatheringName: "gathering-0001"
);
var result = await domain.CancelMatchmakingAsync(
);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Gathering(
gatheringName: "gathering-0001"
);
var future = domain.CancelMatchmakingFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Gathering(
"gathering-0001" // gatheringName
);
const auto Future = Domain->CancelMatchmaking(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
```
---
### createGathering
マッチメイキング用の部屋（ギャザリング）を新規作成する
マッチメイキングの部屋を作成し、他のプレイヤーの参加を待ちます。
ギャザリング作成時に募集条件を設定します。たとえば「アタッカー1人とヒーラー1人を募集、プレイヤーレベルは10〜20」のような指定ができます。
主な設定項目:
- capacityOfRoles: ロールごとの募集人数を定義します（例: DPS 2人 + タンク 1人 + ヒーラー 1人）。
- attributeRanges: レベルやランクなどのプレイヤー属性に基づく参加条件を設定します。
- allowUserIds: 特定のプレイヤーのみ参加可能にします（フレンド限定や招待制のマッチメイキングに便利です）。
- expiresAt: ギャザリングの有効期限を設定します。設定を推奨します。有効期限がないと、プレイヤーがゲームから離脱した後も古いギャザリングが残り続けます。有効期限を使う場合は、期限が来たらプレイヤーにギャザリングの再作成を促す仕組みにしてください。
Player パラメータの自分自身のユーザーIDは省略できます。
ギャザリング作成後、他のプレイヤーは DoMatchmaking を呼び出すことでこのギャザリングを見つけて参加できます。
すべてのロール枠が埋まるとマッチメイキングが完了し、全参加者に通知が送られます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| player | [EzPlayer](#ezplayer) | | ✓| | | 自身のプレイヤー情報 |
| attributeRanges | [List<EzAttributeRange>](#ezattributerange) | | | [] | 0 ~ 5 items | 募集条件
このギャザリングに参加するためにプレイヤーが満たすべき属性範囲条件のリスト。
各エントリは属性名と許容される最小値・最大値の範囲を指定します。
プレイヤー自身の属性値がこの範囲内でなければ参加できません。最大5件。 |
| capacityOfRoles | [List<EzCapacityOfRole>](#ezcapacityofrole) | | | [] | 1 ~ 5 items | 募集枠リスト
このギャザリングの募集枠を定義します。
各エントリはロール名、その別名、およびそのロールに参加可能な最大人数を指定します。
すべてのロール枠が定員に達するとマッチメイキングが完了となります。最小1件、最大5件。 |
| allowUserIds | List<string> | | | [] | 0 ~ 100 items | 参加許可ユーザーIDリスト
このギャザリングへの参加を許可されたユーザーIDのホワイトリスト。
指定した場合、リストに含まれるユーザーのみがこのギャザリングのマッチメイキングに参加できます。
フレンド限定マッチメイキングや招待制マッチメイキングに利用します。最大100件。 |
| expiresAt | long | | | | | ギャザリングの有効期限
このギャザリングが自動的に期限切れとなり削除される時刻。
この時刻までにマッチメイキングが完了しない場合、ギャザリングはクリーンアップされます。
未指定の場合、マッチメイキングが完了するか手動で削除されるまでギャザリングは維持されます。 |
| expiresAtTimeSpan | [EzTimeSpan](#eztimespan) | | | | | 有効期限までの時間 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGathering](#ezgathering) | 作成したギャザリング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.CreateGatheringAsync(
player: new Gs2.Unity.Gs2Matchmaking.Model.EzPlayer {
Attributes = new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzAttribute {
Name = "stage",
Value = 1,
},
new Gs2.Unity.Gs2Matchmaking.Model.EzAttribute {
Name = "level",
Value = 10,
},
},
},
attributeRanges: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
Name = "stage",
Min = 1,
Max = 1,
},
new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
Name = "level",
Min = 0,
Max = 10,
},
},
capacityOfRoles: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzCapacityOfRole {
RoleName = "default",
Capacity = 4,
},
},
allowUserIds: null,
expiresAt: null,
expiresAtTimeSpan: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var future = domain.CreateGatheringFuture(
player: new Gs2.Unity.Gs2Matchmaking.Model.EzPlayer {
Attributes = new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzAttribute {
Name = "stage",
Value = 1,
},
new Gs2.Unity.Gs2Matchmaking.Model.EzAttribute {
Name = "level",
Value = 10,
},
},
},
attributeRanges: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
Name = "stage",
Min = 1,
Max = 1,
},
new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
Name = "level",
Min = 0,
Max = 10,
},
},
capacityOfRoles: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzCapacityOfRole {
RoleName = "default",
Capacity = 4,
},
},
allowUserIds: null,
expiresAt: null,
expiresAtTimeSpan: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto Future = Domain->CreateGathering(
MakeShared()
->WithAttributes([]
{
auto v = MakeShared>>();
v->Add(
MakeShared()
->WithName(TOptional("stage"))
->WithValue(TOptional(1)));
v->Add(
MakeShared()
->WithName(TOptional("level"))
->WithValue(TOptional(10)));
return v;
}())
), // player
[]
{
auto v = MakeShared>>();
v->Add(
MakeShared()
->WithName(TOptional("stage"))
->WithMin(TOptional(1))
->WithMax(TOptional(1)));
v->Add(
MakeShared()
->WithName(TOptional("level"))
->WithMin(TOptional(0))
->WithMax(TOptional(10)));
return v;
}(), // attributeRanges
[]
{
auto v = MakeShared>>();
v->Add(
MakeShared()
->WithRoleName(TOptional("default"))
->WithCapacity(TOptional(4)));
return v;
}() // capacityOfRoles
// allowUserIds
// expiresAt
// expiresAtTimeSpan
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### doMatchmaking
参加可能なギャザリングを探して参加する
既存のギャザリングの中からプレイヤーの属性に合い、空き枠のあるものを検索し、自動的に参加します。
自分でマッチを作るのではなく、既存のマッチに参加したいプレイヤーが使うメインのAPIです。
1回の呼び出しでは一定時間だけ検索を行います。まだ適切なギャザリングが見つからない場合は `matchmakingContextToken` が返されます。
次の呼び出しでこのトークンを渡すと、前回の続きから検索を再開できます。マッチが見つかるまでループで呼び出してください。
すべてのギャザリングを検索しても参加可能なものがなかった場合、ギャザリングもトークンも `null` になります。
この場合は CreateGathering で新しいギャザリングを作成してください。
一般的なマッチメイキングの流れ:
1. DoMatchmaking をループで呼び出し、毎回トークンを渡す
2. ギャザリングが返ってきた → マッチメイキング成功、ゲームへ進む
3. ギャザリングもトークンも null → マッチが見つからなかったので、新しいギャザリングを作成する
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| player | [EzPlayer](#ezplayer) | | ✓| | | 自身のプレイヤー情報 |
| matchmakingContextToken | string | | | | ~ 5120文字 | 検索の再開に使用する マッチメイキングの状態を保持するトークン |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGathering](#ezgathering) | 参加したギャザリング|
| matchmakingContextToken | string | マッチメイキングの状態を保持するトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.DoMatchmakingAsync(
player: new Gs2.Unity.Gs2Matchmaking.Model.EzPlayer() {
UserId = "user-0001",
Attributes = new List {
new Gs2.Unity.Gs2MatchmakingEzAttribute() {
Name = "attr1",
Value = 1,
},
new Gs2.Unity.Gs2MatchmakingEzAttribute() {
Name = "attr2",
Value = 1,
},
}
}
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.DoMatchmaking(
player: new Gs2.Unity.Gs2Matchmaking.Model.EzPlayer() {
UserId = "user-0001",
Attributes = new List {
new Gs2.Unity.Gs2MatchmakingEzAttribute() {
Name = "attr1",
Value = 1,
},
new Gs2.Unity.Gs2MatchmakingEzAttribute() {
Name = "attr2",
Value = 1,
},
}
}
);
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->DoMatchmaking(
MakeShared()
->WithUserId(TOptional("user-0001"))
->WithAttributes([]
{
const auto v = MakeShared>>();
v->Add( MakeShared()
->WithName(TOptional("attr1"))
->WithValue(TOptional(1))
);
v->Add( MakeShared()
->WithName(TOptional("attr2"))
->WithValue(TOptional(1))
);
return v;
}() // player
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### earlyCompleteMatchmaking
定員に達していない状態でマッチメイキングを早期完了する
すべてのロール枠が埋まる前にマッチメイキングを終了します。
当初の募集人数より少ない人数でゲームを開始したい場合に使います。たとえば、4人用の協力ダンジョンを3人で開始するようなケースです。
このAPIを呼び出せるのは、ギャザリングを作成したプレイヤーのみです。
呼び出し後、マッチメイキングは完了扱いとなり、全参加者にマッチ完了通知が送信されます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gatheringName | string | | ✓| UUID | ~ 128文字 | ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGathering](#ezgathering) | キャンセルしたギャザリング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Gathering(
gatheringName: "gathering-0001"
);
var result = await domain.EarlyCompleteMatchmakingAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Gathering(
gatheringName: "gathering-0001"
);
var future = domain.EarlyCompleteMatchmakingFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Gathering(
"gathering-0001" // gatheringName
);
const auto Future = Domain->EarlyCompleteMatchmaking(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### getGathering
ギャザリングの現在の状態を取得する
特定のギャザリングの最新情報を取得します。参加者、募集条件、ロールの定員が含まれます。
待機画面を表示する際に使います。たとえば「2/4人参加済み、募集中: タンク1人、ヒーラー1人」のような表示ができます。
すべてのロール枠が埋まっているかを確認することで、マッチメイキングが完了したかどうかのチェックにも使えます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gatheringName | string | | ✓| UUID | ~ 128文字 | ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGathering](#ezgathering) | ギャザリング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).User(
userId: "user-0001"
).Gathering(
gatheringName: "gathering-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).User(
userId: "user-0001"
).Gathering(
gatheringName: "gathering-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->User(
"user-0001" // userId
)->Gathering(
"gathering-0001" // gatheringName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).User(
userId: "user-0001"
).Gathering(
gatheringName: "gathering-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).User(
userId: "user-0001"
).Gathering(
gatheringName: "gathering-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->User(
"user-0001" // userId
)->Gathering(
"gathering-0001" // gatheringName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### ping
マッチメイキング待機中のキープアライブを送信する
プレイヤーがまだマッチメイキングを待機中であることをサーバーに通知します。
プレイヤーがマッチメイキングの待機画面にいる間、定期的に呼び出してください。
これにより、どのプレイヤーがまだオンラインで待機中かをシステムが把握できます。
ネームスペースにタイムアウトが設定されている場合、タイムアウト期間内に ping を送らなかったプレイヤーはギャザリングから自動的に除外されることがあります。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gatheringName | string | | ✓| UUID | ~ 128文字 | ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGathering](#ezgathering) | 更新したギャザリング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Gathering(
gatheringName: "gathering-0001"
);
var result = await domain.PingAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Gathering(
gatheringName: "gathering-0001"
);
var future = domain.PingFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Gathering(
"gathering-0001" // gatheringName
);
const auto Future = Domain->Ping(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### updateGathering
ギャザリングの募集条件を変更する
まだプレイヤーを待っている既存のギャザリングの属性範囲条件を変更します。
たとえば「レベル15〜20」の条件でプレイヤーが集まらない場合、「レベル10〜25」に広げて参加可能なプレイヤーの母数を増やすことができます。
変更できるのは属性範囲のみです。ロールの定員や参加許可ユーザーIDは作成後に変更できません。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gatheringName | string | | ✓| UUID | ~ 128文字 | ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。 |
| gameSession | GameSession | | ✓| | | GameSession |
| attributeRanges | [List<EzAttributeRange>](#ezattributerange) | | | [] | 0 ~ 5 items | 募集条件
このギャザリングに参加するためにプレイヤーが満たすべき属性範囲条件のリスト。
各エントリは属性名と許容される最小値・最大値の範囲を指定します。
プレイヤー自身の属性値がこの範囲内でなければ参加できません。最大5件。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGathering](#ezgathering) | 更新したギャザリング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Gathering(
gatheringName: "gathering-0001"
);
var result = await domain.UpdateGatheringAsync(
attributeRanges: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
Name = "stage",
Min = 1,
Max = 1,
},
new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
Name = "level",
Min = 0,
Max = 50,
},
}
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Gathering(
gatheringName: "gathering-0001"
);
var future = domain.UpdateGatheringFuture(
attributeRanges: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
Name = "stage",
Min = 1,
Max = 1,
},
new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
Name = "level",
Min = 0,
Max = 50,
},
}
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Gathering(
"gathering-0001" // gatheringName
);
const auto Future = Domain->UpdateGathering(
[]
{
auto v = MakeShared>>();
v->Add(
MakeShared()
->WithName(TOptional("stage"))
->WithMin(TOptional(1))
->WithMax(TOptional(1)));
v->Add(
MakeShared()
->WithName(TOptional("level"))
->WithMin(TOptional(0))
->WithMax(TOptional(50)));
return v;
}() // attributeRanges
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### getRatingModel
特定のレーティング設定の詳細を取得する
レーティング名を指定して1つのレーティングモデルの詳細を取得します。
レーティングシステムの設定（初期レート値やボラティリティ）を表示する際に使います。
ボラティリティが高いと対戦ごとのレーティングの変動幅が大きくなり（新規プレイヤーの実力を素早く反映するのに適しています）、低いとより安定した緩やかな変動になります。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| ratingName | string | | ✓| | ~ 128文字 | レーティングモデル名
レーティングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzRatingModel](#ezratingmodel) | レーティングモデル|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).RatingModel(
ratingName: "mode1"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).RatingModel(
ratingName: "mode1"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->RatingModel(
"mode1" // ratingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).RatingModel(
ratingName: "mode1"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).RatingModel(
ratingName: "mode1"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->RatingModel(
"mode1" // ratingName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listRatingModels
レーティング設定の一覧を取得する
ネームスペースに設定されているすべてのレーティングモデルを取得します。
各レーティングモデルはプレイヤーの実力評価システムのパラメータを定義します。たとえば「ランクバトル」「アリーナ」「トーナメント」で別々のレーティングを持つことができます。
GS2 ではレーティング計算に Glicko-2 アルゴリズムを採用しています。各モデルは初期レート値（デフォルト: 1500）とボラティリティ（対戦ごとにレーティングがどの程度変動するか）を指定します。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzRatingModel>](#ezratingmodel) | レーティングモデルのリスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.RatingModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.RatingModels(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->RatingModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeRatingModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeRatingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeRatingModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeRatingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeRatingModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeRatingModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### getRating
特定カテゴリのプレイヤーのレーティングスコアを取得する
指定されたレーティング名に対するプレイヤーの現在のレート値を取得します。
1つのレーティングを表示する際に使います。たとえば対戦結果画面やロビーで「あなたのランクバトルレーティング: 1823」のように表示できます。
レート値はプレイヤーが勝つと上がり、負けると下がります。変動量は対戦相手のレーティングとボラティリティの設定によって決まります。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| ratingName | string | | ✓| | ~ 128文字 | レーティング名
レーティング固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzRating](#ezrating) | レーティング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Rating(
ratingName: "rating-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Rating(
ratingName: "rating-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Rating(
"rating-0001" // ratingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Rating(
ratingName: "rating-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Rating(
ratingName: "rating-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Rating(
"rating-0001" // ratingName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listRatings
プレイヤーの全カテゴリのレーティングスコアを取得する
プレイヤーの現在のレーティング値をすべて取得します。
ゲームに複数のレーティングカテゴリ（例: 「ランクバトル」と「アリーナ」）がある場合、それぞれのスコアが返されます。
プロフィール画面や戦績画面を作る際に使います。たとえば「ランクバトル: 1823、アリーナ: 1547」のように表示できます。
プレイヤーのレーティングはレーティング付きマッチに初めて参加した時に自動作成され、初期値（通常 1500）からスタートします。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzRating>](#ezrating) | レーティングのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.RatingsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Ratings(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Ratings(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeRatings(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeRatings(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeRatings(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeRatings(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeRatings(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeRatings(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### createVote
対戦結果報告用の署名付き投票用紙を作成する
対戦結果を報告する際に使用する投票用紙（バロット）を生成します。
レーティング付きの対戦が終了した後、各プレイヤーは誰が勝ち誰が負けたかを報告する必要があります。このAPIは、プレイヤーの身元情報と暗号署名を含む改ざん防止済みの投票用紙を作成します。
対戦結果報告の流れ:
1. 対戦が終了し、各プレイヤーのゲームクライアントが CreateVote を呼び出して署名付き投票用紙を取得する
2. 各プレイヤーが投票用紙と対戦結果を Vote API で送信する
3. サーバーがすべての投票を集計し、多数決で最終結果を決定する
4. 確定した結果に基づいてプレイヤーのレーティングが更新される
パラメータ:
- ratingName: この対戦が属するレーティングカテゴリの名前（例: "ranked_battle"）
- gatheringName: この対戦が行われたギャザリング（マッチメイキングルーム）の名前
- numberOfPlayer: 対戦の参加人数（2〜10人）
- keyId: 投票用紙の署名に使用する暗号鍵（カスタム鍵を設定していない場合はデフォルト鍵を使用）
返された投票用紙のボディと署名は、Vote または VoteMultiple API の呼び出しに必要です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| ratingName | string | | ✓| | ~ 128文字 | レーティングモデル名
レーティングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gatheringName | string | | ✓| UUID | ~ 128文字 | ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。 |
| gameSession | GameSession | | ✓| | | GameSession |
| numberOfPlayer | int | | ✓| | 2 ~ 10 | 参加人数 |
| keyId | string | | | "grn:gs2:{region}:{ownerId}:key:default:key:default" | ~ 1024文字 | 暗号鍵GRN |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzBallot](#ezballot) | 投票用紙|
| body | string | 署名対象のデータ|
| signature | string | 署名データ|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Ballot(
ratingName: "rating-0001",
gatheringName: "gathering-0001",
numberOfPlayer: 4,
keyId: "key-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Ballot(
ratingName: "rating-0001",
gatheringName: "gathering-0001",
numberOfPlayer: 4,
keyId: "key-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Ballot(
"rating-0001", // ratingName
"gathering-0001", // gatheringName
4, // numberOfPlayer
"key-0001" // keyId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Ballot(
ratingName: "rating-0001",
gatheringName: "gathering-0001",
numberOfPlayer: 4,
keyId: "key-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Ballot(
ratingName: "rating-0001",
gatheringName: "gathering-0001",
numberOfPlayer: 4,
keyId: "key-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Ballot(
"rating-0001", // ratingName
"gathering-0001", // gatheringName
4, // numberOfPlayer
"key-0001" // keyId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### vote
対戦結果を投票する
対戦後、各プレイヤーがこのAPIを個別に呼び出して、誰が勝ち誰が負けたかを報告します。
CreateVote で取得した投票用紙のボディと署名、および対戦結果（各プレイヤーの順位や勝敗のリスト）を渡します。
投票の仕組み:
- 最初のプレイヤーが投票した後、他のプレイヤーが投票するまでの猶予は5分間です
- 5分以内に全プレイヤーが投票した場合、結果は即座に確定します
- 5分以内に一部のプレイヤーが投票しなかった場合、その時点までの投票内容で多数決により結果が決定されます
- 票が同数だった場合（例: 2人が「プレイヤーAの勝ち」、2人が「プレイヤーBの勝ち」）、結果は破棄されレーティングは更新されません（この挙動はスクリプトでカスタマイズ可能です）
最もシンプルなアプローチで、各プレイヤーが独立して投票します。デメリットは結果の反映に最大5分かかる可能性がある点です。
即座に結果を反映したい場合は VoteMultiple を使ってください。勝利したプレイヤーが全員の投票用紙を集めてまとめて送信します。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| ballotBody | string | | ✓| | ~ 1024文字 | 投票用紙の署名対象のデータ |
| ballotSignature | string | | ✓| | ~ 256文字 | 投票用紙の署名 |
| gameResults | [List<EzGameResult>](#ezgameresult) | | | | 0 ~ 10 items | 投票内容。対戦を行ったプレイヤーグループ1に所属するユーザーIDのリスト |
| keyId | string | | | "grn:gs2:{region}:{ownerId}:key:default:key:default" | ~ 1024文字 | 暗号鍵GRN |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzBallot](#ezballot) | 投票用紙|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
var result = await domain.VoteAsync(
ballotBody: "ballotBody...",
ballotSignature: "ballotSignature...",
gameResults: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 1,
UserId = "user-0001",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 2,
UserId = "user-0002",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 2,
UserId = "user-0003",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 3,
UserId = "user-0004",
},
},
keyId: "key-0001"
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
var future = domain.VoteFuture(
ballotBody: "ballotBody...",
ballotSignature: "ballotSignature...",
gameResults: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 1,
UserId = "user-0001",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 2,
UserId = "user-0002",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 2,
UserId = "user-0003",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 3,
UserId = "user-0004",
},
},
keyId: "key-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
);
const auto Future = Domain->Vote(
"ballotBody...", // ballotBody
"ballotSignature...", // ballotSignature
[]
{
auto v = MakeShared>>();
v->Add(
MakeShared()
->WithRank(TOptional(1))
->WithUserId(TOptional("user-0001"))
);
v->Add(
MakeShared()
->WithRank(TOptional(2))
->WithUserId(TOptional("user-0002"))
);
v->Add(
MakeShared()
->WithRank(TOptional(2))
->WithUserId(TOptional("user-0003"))
);
v->Add(
MakeShared()
->WithRank(TOptional(3))
->WithUserId(TOptional("user-0004"))
);
return v;
}(), // gameResults
"key-0001" // keyId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### voteMultiple
全投票用紙をまとめて送信し、対戦結果を即座に確定する
各プレイヤーが個別に投票する方式（最大5分かかる）の代わりに、勝利したプレイヤーが全員の署名付き投票用紙を集めてまとめて送信します。これにより結果が即座に確定します。
推奨フロー:
1. 対戦が終了 — 各プレイヤーが CreateVote を呼び出して署名付き投票用紙を取得する
2. 各プレイヤーがゲームの通信手段（ゲームサーバーやP2P通信など）を使って、自分の投票用紙（ボディ + 署名）を勝利側のプレイヤーに送る
3. 勝利側のプレイヤーが VoteMultiple を呼び出し、集めた全投票用紙と対戦結果を送信する
4. 結果が即座に確定し、レーティングが更新される
なぜ勝利した側が投票用紙を集めるのか:
- 敗北した側は勝ったと嘘をつく理由がなく（何も得られません）、投票用紙を渡すのを拒否するかもしれません
- 敗北側が協力しなくても、過半数の投票用紙（半数超）があれば結果は受理されます
- たとえば2対2の試合で、勝利した2人が投票用紙を送れば4人中2人分 — 過半数として十分です
実装はやや複雑になりますが、結果が即座に反映されるため、プレイヤー体験としてはより良い方式です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| signedBallots | [List<EzSignedBallot>](#ezsignedballot) | | | | 0 ~ 10 items | 署名付の投票用紙リスト |
| gameResults | [List<EzGameResult>](#ezgameresult) | | | | 0 ~ 10 items | 投票内容。対戦を行ったプレイヤーグループ1に所属するユーザーIDのリスト |
| keyId | string | | | "grn:gs2:{region}:{ownerId}:key:default:key:default" | ~ 1024文字 | 暗号鍵GRN |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzBallot](#ezballot) | 投票用紙|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
var result = await domain.VoteMultipleAsync(
signedBallots: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot() {
Body = "aaa",
Signature = "bbb",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot() {
Body = "aaa",
Signature = "bbb",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot() {
Body = "aaa",
Signature = "bbb",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot() {
Body = "aaa",
Signature = "bbb",
},
},
gameResults: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 1,
UserId = "user-0001",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 2,
UserId = "user-0002",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 2,
UserId = "user-0003",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 3,
UserId = "user-0004",
},
},
keyId: "key-0001"
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
var future = domain.VoteMultipleFuture(
signedBallots: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot() {
Body = "aaa",
Signature = "bbb",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot() {
Body = "aaa",
Signature = "bbb",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot() {
Body = "aaa",
Signature = "bbb",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot() {
Body = "aaa",
Signature = "bbb",
},
},
gameResults: new List {
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 1,
UserId = "user-0001",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 2,
UserId = "user-0002",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 2,
UserId = "user-0003",
},
new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult() {
Rank = 3,
UserId = "user-0004",
},
},
keyId: "key-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
);
const auto Future = Domain->VoteMultiple(
[]
{
auto v = MakeShared>>();
v->Add(
MakeShared()
->WithBody(TOptional("aaa"))
->WithSignature(TOptional("bbb"))
);
v->Add(
MakeShared()
->WithBody(TOptional("aaa"))
->WithSignature(TOptional("bbb"))
);
v->Add(
MakeShared()
->WithBody(TOptional("aaa"))
->WithSignature(TOptional("bbb"))
);
v->Add(
MakeShared()
->WithBody(TOptional("aaa"))
->WithSignature(TOptional("bbb"))
);
return v;
}(), // signedBallots
[]
{
auto v = MakeShared>>();
v->Add(
MakeShared()
->WithRank(TOptional(1))
->WithUserId(TOptional("user-0001"))
);
v->Add(
MakeShared()
->WithRank(TOptional(2))
->WithUserId(TOptional("user-0002"))
);
v->Add(
MakeShared()
->WithRank(TOptional(2))
->WithUserId(TOptional("user-0003"))
);
v->Add(
MakeShared()
->WithRank(TOptional(3))
->WithUserId(TOptional("user-0004"))
);
return v;
}(), // gameResults
"key-0001" // keyId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
---
### getJoinedSeasonGathering
特定のシーズンでプレイヤーが参加したシーズンギャザリングを取得する
指定されたシーズン番号でプレイヤーが所属するシーズンギャザリングを取得します。
現在のシーズンでプレイヤーがどのマッチグループにいるかを確認する際に使います。たとえば、アプリ再起動後にマッチロビーの表示を復元するような場合です。
指定されたシーズンでプレイヤーがシーズンギャザリングに参加していない場合、またはギャザリングが既に存在しない場合、情報は返されません。
その場合は DoSeasonMatchmaking で新しいマッチメイキング検索を開始してください。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| seasonName | string | | ✓| | ~ 128文字 | シーズンモデル名
シーズンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzJoinedSeasonGathering](#ezjoinedseasongathering) | シーズンギャザリング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
).JoinedSeasonGathering(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
).JoinedSeasonGathering(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Season(
"season-0001", // seasonName
0 // season
)->JoinedSeasonGathering(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
).JoinedSeasonGathering(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
).JoinedSeasonGathering(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Season(
"season-0001", // seasonName
0 // season
)->JoinedSeasonGathering(
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listJoinedSeasonGatherings
プレイヤーが参加したシーズンギャザリングの一覧を取得する
プレイヤーが現在メンバーになっているすべてのシーズンギャザリングを取得します。
対戦履歴やアクティブな対戦の画面を表示する際に使います。たとえば、今シーズンにプレイヤーが参加中または参加済みのランク戦を一覧表示できます。
シーズン名でフィルタリングして、特定のランクモード（例: 「ランク1v1」のみ）の対戦だけを表示することもできます。
主な用途:
- ゲーム起動時に、プレイヤーの現在アクティブな対戦を表示する
- 対戦履歴画面を構築する
- 新しいマッチメイキング検索を始める前に、プレイヤーが既に対戦中かどうかを確認する
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| seasonName | string | | | | ~ 128文字 | シーズンモデル名
シーズンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzJoinedSeasonGathering>](#ezjoinedseasongathering) | シーズンギャザリングのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
);
var items = await domain.JoinedSeasonGatheringsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
);
var it = domain.JoinedSeasonGatherings(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Season(
"season-0001", // seasonName
0 // season
);
const auto It = Domain->JoinedSeasonGatherings(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeJoinedSeasonGatherings(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeJoinedSeasonGatherings(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeJoinedSeasonGatherings(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeJoinedSeasonGatherings(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Season(
"season-0001", // seasonName
0 // season
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeJoinedSeasonGatherings(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeJoinedSeasonGatherings(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### doSeasonMatchmaking
参加可能なシーズンマッチを検索して参加する
プレイヤーのティアー内で空き枠のあるシーズンギャザリング（永続的なマッチメイキンググループ）を検索し、自動的に参加します。
プレイヤーのティアーは、連携する GS2-Experience モデルの経験値レベルによって決まるため、実力が近いプレイヤー同士がマッチングされます。
通常の DoMatchmaking と似た仕組みですが、ティアーによるグループ分けがあります:
- 1回の呼び出しでは一定時間だけ検索します。まだマッチが見つからない場合は `matchmakingContextToken` が返されます。
- 次の呼び出しでこのトークンを渡すと、前回の続きから検索を再開できます。
- マッチが見つかるまでループで呼び出してください。
すべてのシーズンギャザリングを検索しても空きがなかった場合、シーズンギャザリングもトークンも `null` で返されます。
通常のマッチメイキングでは自分で新しいギャザリングを作成しますが、シーズンマッチメイキングではシステムが必要に応じて新しいシーズンギャザリングを自動作成します。
一般的なシーズンマッチメイキングの流れ:
1. DoSeasonMatchmaking をループで呼び出し、毎回トークンを渡す
2. シーズンギャザリングが返ってきた → マッチ成立、ゲームへ進む
3. 両方 null → 現在利用可能なマッチがない。「検索中」画面を表示して少し待ってからリトライ
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| seasonName | string | | ✓| | ~ 128文字 | シーズンモデル名
シーズンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| matchmakingContextToken | string | | | | ~ 5120文字 | 検索の再開に使用する マッチメイキングの状態を保持するトークン |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSeasonGathering](#ezseasongathering) | 参加したシーズンギャザリング|
| matchmakingContextToken | string | マッチメイキングの状態を保持するトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
);
var items = await domain.DoSeasonMatchmakingAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Season(
seasonName: "season-0001",
season: 0
);
var it = domain.DoSeasonMatchmaking(
);
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Season(
"season-0001", // seasonName
0 // season
);
const auto It = Domain->DoSeasonMatchmaking(
);
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### getSeasonGathering
シーズンギャザリングの現在の状態を取得する
特定のシーズンギャザリングの詳細を取得します。参加者リストや所属ティアーの情報が含まれます。
シーズンマッチのロビーや待機画面を表示する際に使います。たとえば「ゴールドティアー マッチ#42: 3/4人参加中」のような表示ができます。
正確なシーズンギャザリングを特定するには、シーズン番号、ティアー、ギャザリング名を指定する必要があります。
これらの情報は DoSeasonMatchmaking でシーズンギャザリングへの参加に成功した際に返されます。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| seasonName | string | | ✓| | ~ 128文字 | シーズンモデル名
シーズンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| tier | long | | ✓| | 0 ~ 9223372036854775805 | ティアー
同程度のランクのプレイヤーをグルーピングするためのティアーレベル。
SeasonModel で指定された GS2-Experience モデルにおけるプレイヤーのランクによって決定されます。
プレイヤーは同じティアーのプレイヤーとのみマッチングされ、公平な対戦が保証されます。 |
| seasonGatheringName | string | | ✓| UUID | ~ 128文字 | シーズンギャザリング名
シーズンギャザリング固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSeasonGathering](#ezseasongathering) | シーズンギャザリング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).User(
userId: "user-0001"
).Season(
seasonName: "season-0001",
season: 0
).SeasonGathering(
tier: 0,
seasonGatheringName: "gathering-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).User(
userId: "user-0001"
).Season(
seasonName: "season-0001",
season: 0
).SeasonGathering(
tier: 0,
seasonGatheringName: "gathering-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->User(
"user-0001" // userId
)->Season(
"season-0001", // seasonName
0 // season
)->SeasonGathering(
0, // tier
"gathering-0001" // seasonGatheringName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).User(
userId: "user-0001"
).Season(
seasonName: "season-0001",
season: 0
).SeasonGathering(
tier: 0,
seasonGatheringName: "gathering-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).User(
userId: "user-0001"
).Season(
seasonName: "season-0001",
season: 0
).SeasonGathering(
tier: 0,
seasonGatheringName: "gathering-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->User(
"user-0001" // userId
)->Season(
"season-0001", // seasonName
0 // season
)->SeasonGathering(
0, // tier
"gathering-0001" // seasonGatheringName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### getSeasonModel
特定のシーズンマッチメイキング設定の詳細を取得する
シーズン名を指定して1つのシーズンモデルの詳細を取得します。
特定のランクモードのルールや設定を表示する際に使います。たとえば、モード選択画面で「ランク1v1: 最大2人、アリーナ経験値でティアー決定」のように表示できます。
レスポンスには以下が含まれます:
- maximumParticipants: 1試合の参加可能人数
- experienceModelId: プレイヤーのティアーを決定するのに使用される GS2-Experience モデル。プレイヤーの経験値レベルがティアーにマッピングされ、同じティアー内のプレイヤー同士のみマッチングされます。
- challengePeriodEventId: 設定されている場合、指定された期間内のみランク戦に参加できます（例: 週末のみ、毎日19時〜22時など）
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| seasonName | string | | ✓| | ~ 128文字 | シーズンモデル名
シーズンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSeasonModel](#ezseasonmodel) | シーズンモデル|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).SeasonModel(
seasonName: "season-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).SeasonModel(
seasonName: "season-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->SeasonModel(
"season-0001" // seasonName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).SeasonModel(
seasonName: "season-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
).SeasonModel(
seasonName: "season-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
)->SeasonModel(
"season-0001" // seasonName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listSeasonModels
シーズンマッチメイキング設定の一覧を取得する
ネームスペースに定義されているすべてのシーズンモデルを取得します。
シーズンマッチメイキングは、ランク戦のある対戦ゲーム向けに設計されています。「シーズン1」「シーズン2」のように期間ごとに区切り、プレイヤーを実力に応じたティアー（階級）に分けてマッチングします。
通常のギャザリングベースのマッチメイキング（一時的な部屋を作成する方式）とは異なり、シーズンマッチメイキングではシーズン中ずっと存続する永続的なグループを使います。
同じティアーのプレイヤー同士がマッチングされるため、公平な対戦が実現できます。
各シーズンモデルでは以下を定義します:
- 1試合あたりの最大参加人数
- プレイヤーのティアーを計算するための経験値モデル（GS2-Experience と連携して、ブロンズ・シルバー・ゴールドなどの実力帯を決定します）
- オプションのチャレンジ期間イベント（GS2-Schedule と連携して、対戦可能な時間帯を制限できます）
利用可能なランクモードの一覧を表示する際に使います。たとえば「ランク1v1」「ランク3v3」のような画面です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzSeasonModel>](#ezseasonmodel) | シーズンモデルのリスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.SeasonModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.SeasonModels(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->SeasonModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSeasonModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSeasonModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Matchmaking.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSeasonModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSeasonModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Matchmaking->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeSeasonModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeSeasonModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
## イベントハンドラ
### OnJoinNotification
ギャザリングに新しい参加者が参加したときに使用するプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| gatheringName | string |ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。|
| joinUserId | string |ユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Matchmaking.OnJoinNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var gatheringName = notification.GatheringName;
var joinUserId = notification.JoinUserId;
};
```
**Unity (Vanilla)**
```cs
gs2.Matchmaking.OnJoinNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var gatheringName = notification.GatheringName;
var joinUserId = notification.JoinUserId;
};
```
**Unreal Engine 5**
```cpp
Gs2->Matchmaking->OnJoinNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GatheringName = Notification->GatheringNameValue;
const auto JoinUserId = Notification->JoinUserIdValue;
});
```
---
### OnLeaveNotification
ギャザリングから参加者が離脱したときに使用するプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| gatheringName | string |ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。|
| leaveUserId | string |ユーザーID|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Matchmaking.OnLeaveNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var gatheringName = notification.GatheringName;
var leaveUserId = notification.LeaveUserId;
};
```
**Unity (Vanilla)**
```cs
gs2.Matchmaking.OnLeaveNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var gatheringName = notification.GatheringName;
var leaveUserId = notification.LeaveUserId;
};
```
**Unreal Engine 5**
```cpp
Gs2->Matchmaking->OnLeaveNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GatheringName = Notification->GatheringNameValue;
const auto LeaveUserId = Notification->LeaveUserIdValue;
});
```
---
### OnCompleteNotification
マッチメイキングが成立したときに使用するプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| gatheringName | string |ギャザリング名
ギャザリングの一意な名前を保持します。
名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、ギャザリングを識別するために使用されます。|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Matchmaking.OnCompleteNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var gatheringName = notification.GatheringName;
};
```
**Unity (Vanilla)**
```cs
gs2.Matchmaking.OnCompleteNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var gatheringName = notification.GatheringName;
};
```
**Unreal Engine 5**
```cpp
Gs2->Matchmaking->OnCompleteNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto GatheringName = Notification->GatheringNameValue;
});
```
---
### OnChangeRatingNotification
レーティング値が変動したときに使用するプッシュ通知
| 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| ratingName | string |レーティング名
レーティング固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| userId | string |ユーザーID|
| rateValue | float |レート値
Glicko-2 アルゴリズムで計算されたプレイヤーの現在のレーティングスコア。
RatingModel で定義された初期値（通常 1500.0）がデフォルトです。
対戦結果と対戦相手の相対的な強さに基づいて値が増減します。|
#### 実装例
**Unity (UniTask)**
```csharp
gs2.Matchmaking.OnChangeRatingNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var ratingName = notification.RatingName;
var userId = notification.UserId;
var rateValue = notification.RateValue;
};
```
**Unity (Vanilla)**
```cs
gs2.Matchmaking.OnChangeRatingNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var ratingName = notification.RatingName;
var userId = notification.UserId;
var rateValue = notification.RateValue;
};
```
**Unreal Engine 5**
```cpp
Gs2->Matchmaking->OnChangeRatingNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto RatingName = Notification->RatingNameValue;
const auto UserId = Notification->UserIdValue;
const auto RateValue = Notification->RateValueValue;
});
```
---