6. ランキング 2
6.1. はじめに
ランキング 2 は、ユーザーが登録したスコアを用いて順位を生成する機能です。 ユーザーがスコアを登録するとサーバーでそれを集計し、ゲーム内でランキングを取得することができます。
スコアの登録では、ユーザーがもつ複数種類のスコアを別々にあつかってそれぞれのランキングを生成することや、スコアに関連付けてデータを登録することなどが可能です。 例えば、ゲームクリア時にその経過時間や取得コイン数をスコアとして登録するゲームの場合、クリア時間と取得コイン数とを別のランキングにしたり、スコアにリプレイデータのデータ ID を関連付けたり、といった使い方ができます。
ランキングの取得では、上位のランキング、自分の順位の周辺ランキング、フレンド内だけでのランキング、などの異なる種類のランキングを取得することができます。 今日のランキング、今月のランキング、といった期間の異なるランキングを用意することも可能です。
ランキング 2 は従来のランキング機能とは独立した機能です。データベースは独立しており、お互いのデータにアクセスすることはできません。 従来のランキング機能と比べてフィルタリングの機能などがない反面、API 呼び出し回数制約が緩和されています。
ランキング 2 を利用する場合は、ランキングのガイドラインに従ってください。
6.2. ランキング 2 の基本概念
ランキング 2 では、各種スコアをユーザーおよびカテゴリごとに集計し、ランキングに反映します。
一定期間ごとにスコアはリセットされ、ランキングは空に戻ります。
各ユーザーごとに、 Figure 6.1 に示すようなデータが保存されます。

Figure 6.1 ゲームサーバーに保存される情報
6.2.1. スコア
ランキング 2 では、スコア として 32 ビットの非負整数値(0 ~ 4294967295)を用います。
ランキングの種類ごとにスコアの並び順(大小どちらが上位となるか)を設定することができます。
また、有効なスコアの範囲を設定することができます。範囲外のスコアは 不正スコア とみなされ、ランキングに現れない場所に隔離して保存されます。
6.2.2. カテゴリ
ランキング 2 における カテゴリ とは、複数種類のランキングを取り扱うための分類のことです。各スコアはカテゴリごとに集計され、それぞれ異なるランキングとして取得することができます。
同一のユーザーは、各カテゴリに 1 つの値しか登録することができません。複数の値が登録されると、上位のスコアのみが残ります。
カテゴリは、32 ビットの非負整数値です。使用するカテゴリの値が連続している必要はありません。
各カテゴリは 1 つのカテゴリタイプに属しています。
詳細は、 カテゴリ設定 を参照してください。
6.2.3. カテゴリタイプ
カテゴリタイプ は、同じ挙動のカテゴリをまとめて分類する値です。0 ~ 255 の 256 種類を使用することができます。
各カテゴリタイプはそれぞれ設定値を持っており、各カテゴリは、属しているカテゴリタイプの設定を引き継いで動作します。
カテゴリタイプの設定値は、以下の通りです。
- 有効スコアの最小値、最大値
- スコアの並び順
- 最低順位
- 過去シーズン保存数
- 定期リセットモード
- 定期リセット時刻、日、月
詳細は、 カテゴリタイプ設定 を参照してください。
6.2.4. ユーザー
ランキング 2 では、スコア登録などを行う ユーザー の管理単位として、プリンシパル ID もしくは NEX ユニーク ID を利用します。
通常は、プリンシパル ID 単位での管理を行います。
事前にプリンシパル ID に対して NEX ユニーク ID の発行と登録がされていれば、NEX ユニーク ID 単位での管理を行います。 NEX ユニーク ID の詳細については、 パスワード付き NEX ユニーク ID の利用 を参照してください。
各 API ではプリンシパル ID および NEX ユニーク ID を指定することができます。 それぞれの指定の有無で、ユーザーとして何を用いるかを Table 6.1 に示します。 プリンシパル ID を指定できない API については、API を呼び出したクライアントのプリンシパル ID が指定されたものとして考えます。
プリンシパル ID | NEX ユニーク ID | 使用される ID |
---|---|---|
なし | なし | API を呼び出したクライアントのプリンシパル ID の、プライマリ関連 NEX ユニーク ID。
関連 NEX ユニーク ID の登録が 1 つもない場合は、そのプリンシパル ID。
|
あり | なし | 指定したプリンシパル ID のプライマリ関連 NEX ユニーク ID。
関連 NEX ユニーク ID の登録が 1 つもない場合は、指定したプリンシパル ID。
|
なし | あり | 許可されない指定方法。 |
あり | あり | 指定の NEX ユニーク ID。
指定の NEX ユニーク ID が、指定のプリンシパル ID の関連 NEX ユニーク ID ではない場合、エラー。
|
6.2.5. ユーザー共通データ
各ユーザーは、名前とバイナリデータを登録することができます。これらを ユーザー共通データ と呼びます。
ユーザー共通データは、各ユーザーに 1 つずつ紐づくものであり、スコアに紐づくものではありません。
6.2.6. 定期リセットとシーズン
ランキング 2 では、定期的にランキングデータをリセットします。これを 定期リセット と呼びます。リセットすると、最新のランキングのデータは空になり、ランキングに参加している人数は 0 になります。
この定期リセットの周期を シーズン として数えます。シーズンは初期化時に 0 で、以降定期リセットが行われるたびに 1 ずつ増加し、2147483647 で止まります。
リセット時に存在していたデータは過去シーズンのデータとして保存され、参照することができます。
リセットするタイミングや過去シーズンを保存する期間については、カテゴリタイプごとに事前に設定します。
定期リセットに関する詳細は、 定期リセット設定 を参照してください。
6.3. ランキング 2 利用の流れ
ランキング 2 機能を利用する基本的な流れは以下のとおりです。
6.4. サービスクライアントの初期化および終了
ランキング 2 のサービスクライアント( Ranking2Client )の初期化および終了処理は、マッチメイクでの処理と同じです( 4.3. )。
6.5. スコアを登録する
スコアを登録、変更するには、 Ranking2Client::PutScore() を使用します。
スコアの属性情報として Ranking2ScoreData オブジェクトに Table 6.2 の属性値を設定できます。
項目名 | 概要 | 設定可能な値 | 初期値 | 設定関数 |
---|---|---|---|---|
カテゴリ | スコアを登録するカテゴリの番号を指定します。 | 32 ビットの非負整数 | 0 | SetCategory() |
スコア | スコアを指定します。 | 32 ビットの非負整数 | 0 | SetScore() |
その他データ | 各スコアに紐づく任意のデータを指定します。 | 64 ビットの非負整数 | 0 | SetMisc() |
スコアには 32 ビットの非負整数( 0 ~ 4294967295 )を指定できますが、上限下限を設定して不正なスコアが登録されないよう制限することができます。 詳しくは、 有効スコアの最小値および最大値 を参照してください。
その他データには、任意の 64 ビットの値を格納することができます。 この値はスコアに紐づくため、ユーザー共通データとは異なり、同一ユーザーが複数カテゴリにスコアを登録する場合でもそれぞれ異なる値を格納できます。 例えば、スコアに紐づくリプレイデータをデータストアに格納した場合に、そのデータ ID を保存するために使用することができます。
この API では自分と同じプリンシパル ID のスコアのみ登録することができます。
6.5.1. ランキングの最低順位
ランキング 2 では、各カテゴリタイプごとに、ランキングに残る最低順位が設定されています。 最低順位を下回るスコアを登録しても、サーバーには保存されません。 また、上位に他のユーザーがランクインしたり、最低順位の設定値を変えたりしたことによって最低順位より下位のデータが発生した場合、そのデータは定期的に削除されます。 そのため、スコア登録をしてからランキングを取得しても、ランキングに入っていない場合があります。
最低順位は、実際にランキングに残るスコアの数とは異なります。最低順位に同スコアが並んでいると、最低順位 +100 人まではランキングに残ります。 例えば、最低順位が 1000 位に設定されている場合は 1100 人のスコアを残すため、995 位から同じスコアが大量に並んだときは 995 位が 106 人まで保存されます。
6.6. ランキングを取得する
ランキングを取得するには、 Ranking2Client::GetRanking() を使用します。
上位のランキングだけでなく、自分の周辺のランキングや、フレンドのランキングなど、複数種類のランキングから選択して取得できます。
6.6.1. ランキングの種類
ランキングの種類は、Ranking2Client::GetRanking() に引数として渡す Ranking2GetParam でランキングのモードとして指定します。 Table 6.3 にある種類のランキングを取得できます。
種類 | モードの値 | 概要 |
---|---|---|
個人ランキング | Ranking2Mode:: |
指定したユーザーのランキングデータを取得します。 |
範囲ランキング | Ranking2Mode:: |
開始位置と長さを指定し、その範囲のランキングを取得します。 |
周辺ランキング | Ranking2Mode:: |
指定ユーザーの周辺のランキングを取得します。 |
フレンドランキング | Ranking2Mode:: |
自分のフレンド内でのランキングを取得します。 |
プリンシパル ID ランキング | 指定したプリンシパル ID のリストのランキングを取得します。 |
個人ランキングでは、対象のユーザーのランキングデータを取得します。 NEX ユニーク ID を指定せず、かつ、対象のユーザーが関連 NEX ユニーク ID を 1 つ以上登録している場合は、それらのすべてのデータを取得します。
範囲ランキングでは、開始位置と長さを指定し、ランキングを取得します。
周辺ランキングでは、指定したユーザーがリストの中央に来るようなランキングを取得します。 ただし、指定したユーザーが最上位や最下位周辺にいる場合、中央に来ないことがあります。 その場合でも、ランキング内のデータ数が足りない場合を除き、指定した数のデータを返します。 例えば、指定したユーザーが 3 位だった場合に、10 人分のデータを要求すると、1 位から 10 位までのデータを取得します。
フレンドランキングは、自分のフレンドと自分を含むランキングを取得します。 フレンドが 1 人もいない場合は、自分のデータのみ取得されます。 フレンドや自分のプリンシパル ID が関連 NEX ユニーク ID を登録している場合は、それらのすべてのデータを取得します。
プリンシパル ID ランキングは、取得したいユーザーのプリンシパル ID を直接指定してランキングを取得します。 このランキングは、Ranking2GetByListParam および プリンシパル ID のリストを使用する Ranking2Client::GetRanking() のオーバーロード関数を使って取得します。 指定のプリンシパル ID が関連 NEX ユニーク ID をもっている場合は、それらすべてのデータを取得します。
各ランキングは、 Ranking2Constants::MAX_RANKING_LENGTH 件までのデータを取得できます。
6.6.2. ランキング取得パラメータ
ランキング取得パラメータ( Ranking2GetParam および Ranking2GetByListParam )により、ランキングの取得条件を指定できます(Table 6.4 )。
項目名 | 概要 | 初期値 | 設定関数 |
---|---|---|---|
ランキングの種類(モード) | 取得するランキングのモード(6.6.1.)を指定します。(Ranking2GetParam のみ) | Ranking2Mode:: |
SetMode() |
カテゴリ | 取得する カテゴリ を指定します。 | 0 | SetCategory() |
過去シーズン | 何回前のシーズン(6.2.6.)を取得するかを指定します。0 が現在、1 が現在より 1 つ古いシーズン、以降は順に古いものを指します。 | 0 | SetNumSeasonsToGoBack() |
ソートフラグ | ソートのオプション指定フラグを指定します。 | Ranking2SortFlags:: |
SetSortFlags() |
オプションフラグ | オプションフラグを指定します。 | Ranking2GetOptionFlags:: |
SetOptionFlags() |
開始位置 | 取得の開始位置を指定します。個人ランキング、周辺ランキングでは指定できません。 | 0 | SetOffset() |
長さ | 取得する長さを指定します。1 以上 Ranking2Constants:: |
10 | SetLength() |
プリンシパル ID | 対象のプリンシパル ID を指定します。(Ranking2GetParam のみ) | INVALID_ |
SetPrincipalId() |
NEX ユニーク ID | 対象の NEX ユニーク ID を指定します。(Ranking2GetParam のみ) | INVALID_ |
SetNexUniqueId() |
6.6.2.1. 開始位置
ランキング取得の開始位置の指定は、順位ではありません。
範囲ランキングでは、ランキングの先頭を 0 としたときの取得開始位置の指定ができます。 例えば、同スコアにより 1 位、1 位、3 位、と並んでいたとき、開始位置に 1 を指定すると、2 番目の 1 位から取得を行います。
フレンドランキングおよびプリンシパル ID ランキングでは、取得対象となるリストの先頭を 0 としたときの取得開始位置を指定できます。 取得対象となるリストはフレンドリストもしくは指定プリンシパル ID リストですが、各ユーザーが NEX ユニーク ID を登録している場合はそれらすべての NEX ユニーク ID のリストです。 リスト長が Ranking2Constants::MAX_RANKING_LENGTH 件を超える場合、指定した開始位置から Ranking2Constants::MAX_RANKING_LENGTH 件までしか取得されないため、必要に応じて開始位置を変えて複数回の取得を行ってください。
6.6.2.2. 過去シーズン
現在よりも何回前のシーズンを取得するかを指定します。「昨日のランキング」や「2 週間前のランキング」などを取得することができます。
カテゴリタイプ設定の「過去シーズン保存数」よりも過去のデータは削除済みのため、取得できません。 また、定期リセットが行われる前に過去シーズンを取得した場合など、まだ作成されていない過去シーズンを指定した場合に、シーズンがマイナスになることがあります。
定期リセットなしの設定のときは、この値を指定できません。
6.6.2.3. ソートフラグ
ソートフラグでは、 Table 6.5 にある並べ替え方法を指定することができます。 基本的な並び順(スコアの昇順、降順)はカテゴリタイプの設定で行われており、ランキング取得時に指定することはできません。
項目名 | 概要 |
---|---|
Ranking2SortFlags:: |
API をコールしたユーザーを同順位の中の先頭にします。 |
6.6.2.4. オプションフラグ
オプションフラグでは、 Table 6.6 にある値を指定することができます。
項目名 | 概要 |
---|---|
Ranking2GetOptionFlags:: |
Mii データを取得します。ユーザー共通データ( Ranking2CommonData )のメンバとして取得できます。 取得した Mii データを利用するには別途「似顔絵ライブラリ」が必要です。 |
6.6.3. ランキング取得結果
ランキングの結果は Ranking2Info オブジェクトに格納されます。 Ranking2Info オブジェクトには、以下のものが含まれています。
- ランキングデータのリスト( qVector<Ranking2RankData> )
- 指定のパラメータに合致するデータが存在しない場合は、空のリストを返します。
- 特定のユーザーを指定するフレンドランキングなどを使用した場合、ランクインしているユーザーだけのリストを返します。
- ランキングの最低順位 の設定値
- 何位までがランキングに残るかという カテゴリタイプ設定 上の数値です。
- 取得したランキングデータのリストにその順位が必ず含まれるわけではありません。
- 同順位が並んでいると、最下位がこの順位よりも高くなることがあります。
- 例:最低順位が 100 で 98 位が 3 人いる場合は、最下位が 100 位ではなく 98 位となる。
- 該当カテゴリのランキングに登録されているスコアの数
- その時点で登録されているスコアの数です。最低順位より下位になり削除されたスコアは含みません。
- 取得したランキングデータのリストの長さではありません。
- 同順位が並んでいると、最低順位を上回る数になることがあります。
- 例:最低順位が 100 で 100 位が 5 人いる場合は、104 個のスコアが登録される。
- シーズン番号
- 取得したランキングデータのシーズン番号です。現在のシーズン番号ではありません。
Ranking2RankData で取得可能な項目を Table 6.7 に示します。
項目名 | 取得関数 |
---|---|
順位 | GetRank() |
スコア | GetScore() |
プリンシパル ID | GetPrincipalId() |
NEX ユニーク ID | GetNexUniqueId() |
ユーザー共通データ | GetCommonData() |
その他データ | GetMisc() |
6.6.4. 同点データの扱い
ランキング 2 では、同点のデータは同順位として扱います。
取得したランキングデータのリスト( qVector<Ranking2RankData> )において、同順位のデータ間の並び順は不定です。
ただし、取得時に ソートフラグ をセットすることにより、一部の並び順を決定することができます。
この他の並び順を使いたい場合は、あらかじめそれを考慮したスコアを用いてランキングを作成してください。 例えば、下位ビットに日時情報を入れ、上位ビットにスコア値を入れることで、同点のユーザーを日時順に並べることができます。
6.7. ユーザー共通データ
自分の ユーザー共通データ を登録、変更あるいは削除するには、Ranking2Client::PutCommonData() や Ranking2Client::DeleteCommonData() を使用します。
自分もしくは他人のユーザー共通データを取得するには、Ranking2Client::GetCommonData() を使用します。ランキング取得時に返される Ranking2RankData オブジェクトからも取得できます。
ユーザーの名前の最大文字数は、Ranking2Constants::MAX_USERNAME_LENGTH です。
バイナリデータの最大長(バイト数)は、Ranking2Constants::MAX_BINARY_DATA_LENGTH です。
オプションフラグ に Mii 取得フラグを指定することで、そのユーザーの Mii データを取得することができます。登録や削除はできません。
注意
ユーザー共通データに UGC を含んだ内容を登録する場合は、UGC に関するガイドラインに従ってください。 ユーザー共通データは WebAPI で削除可能です。
6.8. 設定
ランキング 2 では、カテゴリおよびカテゴリタイプの設定をすることができます。
設定の変更は WebAPI(12.3.)を用いて行います。
クライアントからは設定値の取得のみを行うことができます。
6.8.1. カテゴリ設定
カテゴリ 設定では、各カテゴリがどのカテゴリタイプに属するかを指定できます。 未設定時は、カテゴリタイプ 0 に属しています。
また、有効スコアの最小値および最大値を設定することができます。これらは、カテゴリタイプ設定に含まれていますが、カテゴリ個別にも設定することができます。 未設定時の初期値はなく、所属するカテゴリタイプの設定値を継承します。詳細は、 有効スコアの最小値および最大値 を参照してください。
6.8.2. カテゴリタイプ設定
カテゴリタイプ 設定の各値は、それぞれ Table 6.8 の意味を持ちます。
項目名 | 概要 | 設定可能な値 | 初期値 |
---|---|---|---|
有効スコアの最小値 | 正常な範囲内のスコアの最小値を指定します。 | 32 ビットの非負整数 | 0 |
有効スコアの最大値 | 正常な範囲内のスコアの最大値を指定します。 | 32 ビットの非負整数 | 4294967295 |
スコアの並び順 | スコアの並び順(大小どちらが上位となるか)を指定します。 | 0 (昇順), 1 (降順) | 1 |
最低順位 | ランキングに残る最低順位を指定します(6.5.1.)。 | 1 ~ 10000 | 10000 |
過去シーズン保存数 | 保持される過去シーズンの数を指定します(6.2.6.)。 | 0 ~ 100 | 5 |
定期リセットモード | 定期リセットの種類を指定します。 | Ranking2ResetMode | Ranking2ResetMode:: |
定期リセット時刻 | 定期リセットの時刻を指定します。 | 0 ~ 23 | 0 |
定期リセット日 | 定期リセットの日にちまたは曜日を指定します。 | 1 ~ 28(日にち)または 0 ~ 6(曜日) | 1 |
定期リセット月 | 定期リセットの月を指定します。 | 1 ~ 4095 | 4095 |
説明のため、 Figure 6.2 に設定の例を示します。

Figure 6.2 カテゴリ設定の例
6.8.2.1. 有効スコアの最小値および最大値
有効スコアの最小値および最大値を設定し、その範囲に含まれない不正スコアがランキングに登録されないよう制限をかけることができます。 不正スコアは、クライアントが参照する通常のランキングのデータとしては登録されず、隔離された別の場所に登録されます。 不正スコアは WebAPI(12.3.) で参照や削除することができます。
有効スコアの最小値および最大値は、カテゴリタイプごとだけでなく、カテゴリごとの設定も可能です。 カテゴリごとの設定を行った場合は、カテゴリごとの設定が優先されます。
これは、例えばゲーム内の各ステージのクリア時間ランキングを作成する際に使うことができます。 Figure 6.2 の例では、ステージのクリア秒数を扱うカテゴリタイプ 10 を用意し、スコアの並び順を昇順(秒数が小さい方が上位)と設定しています。 このカテゴリタイプに各ステージで用いるカテゴリを属させ、それぞれ正常にクリアできる秒数を設定します。 30 秒未満でクリアできないステージ 1 用にカテゴリ 101 を、40 秒未満でクリアできないステージ 2 用にカテゴリ 102 を作成し、それぞれの有効スコアに、想定される範囲を設定します。 これによって、ステージごとに異なる有効スコア範囲で、クリア時間のランキングを作成することができます。
有効スコアの範囲を変更した場合、即座に全カテゴリのスコアのチェックが行われ、不正なものがあればその時点ですべて隔離されます。 すでに隔離されたデータは、有効スコアの範囲変更によって不正なスコアでなくなっても、通常のランキングには戻らず隔離されたままです。
6.8.2.2. 定期リセット設定
定期リセットを行うタイミングは、 Table 6.9 の中から選択することができます。
種類 | モードの値 | 概要 | 指定必須パラメータ |
---|---|---|---|
リセットなし | Ranking2ResetMode:: |
定期リセットを行いません。 | なし |
毎日 | Ranking2ResetMode:: |
毎日、指定時に定期リセットを行います。 | 時 |
毎週 | Ranking2ResetMode:: |
毎週、指定曜日の指定時に定期リセットを行います。 | 曜日、時 |
指定月 | Ranking2ResetMode:: |
指定した月の指定日時に定期リセットを行います。 | 月、日にち、時 |
指定月第一週 | Ranking2ResetMode:: |
指定した月の第一指定曜日に定期リセットを行います。 | 月、曜日、時 |
日時指定は UTC で行います。
定期リセット月は、各月を 1 ビットとし、下位から 1 月, 2 月, …とする全 12 ビットの値で表します。 ビットの立っている月で定期リセットを実行します。
定期リセット日は、指定する定期リセットモードによって意味が異なります。 日にちの指定が必要なモードの場合は、1 ~ 28 日を指定します。 曜日の指定が必要なモードの場合は、0(月曜日)~ 6(日曜日)を指定します。
定期リセット設定を変えた複数のカテゴリタイプに同じスコアを登録することで、リセット期間の異なる複数のランキングを作成することができます。 Figure 6.2 の例では、カテゴリタイプ 0 と 1 で、定期リセットの設定だけを変えています。 同一のスコアをカテゴリ 0 と カテゴリ 2 に登録すると、カテゴリ 0 は毎日リセットされますが、カテゴリ 2 は月曜日にのみリセットされます。 これによって、“今日のランキング”と“今週のランキング”とを容易に作成することができます。
定期リセット処理は、負荷分散のため、設定した日時ちょうどには行われません。最大 1 分程度のランダムな時間をおいて開始されます。 設定日時との誤差があることを前提として実装を行ってください。
定期リセットを行う設定にする場合、リージョンごとにカテゴリタイプを変えると、それぞれで異なるリセット時刻を指定することができます。 これにより、それぞれのリージョンでログイン人数が少ない時間帯や、ユーザーもしくはゲームにとって都合の良い時刻を選んでリセットすることが可能です。
6.8.3. クライアントからの設定値の取得
クライアントから各カテゴリの設定値を取得するには、Ranking2Client::GetCategorySetting() を使用します。
この関数では、指定したカテゴリが所属するカテゴリタイプの設定値と、指定したカテゴリの設定値とを取得し、合わせた形で返します。両方の設定に存在する値はカテゴリの設定が優先されます。
クライアントから設定を変更することはできません。
6.9. 従来のランキング機能との違い
ランキング 2 では、利便性や運用性を高めるために、いくつかの機能が変更または省略されています。
6.9.1. 変更された機能
過去のランキングの取得
ランキング取得時に、過去のランキングを指定して取得することができます( 6.6.2.2. )。
6.9.1.1. スコアの最低順位
スコアデータが増加し続ける問題を解消するため、設定された最低順位以降のスコアを自動的に削除します( 6.5.1. )。
これにともない、取得順位に誤差が生じる限界順位( RankingConstants::MAX_ACCURATE_ORDER )の仕様は削除されています。
また、最低順位までのすべての順位を通常通りに取得できるため、予測順位やキャッシュされた上位ランキングの機能はありません。
6.9.1.2. ユーザー共通データ
従来のユーザー共通データと異なり、名前とバイナリデータを別に保存することができます( 6.2.5. )。
また、ランキング 2 の保存領域に Mii データを保存しなくとも、フレンドサーバー上のデータを取得することができます( 6.6.2.4. )。
6.9.1.3. 同一順位内のソート
ランキング取得時にソートフラグをセットすることで、ランキング取得ユーザーを同一順位内の先頭に置くことができます( 6.6.2.3. )。
6.9.2. 省略された機能
6.9.2.1. グループによるフィルタリング機能
スコアに紐づけたグループを使ってフィルタリングする機能はありません。該当のカテゴリのすべてのスコアが取得対象です。
代わりに、同じスコアを登録する複数のカテゴリを用意し、スコアを登録する時点でフィルタリングしてください。 スコアを登録する Ranking2Client::PutScore() に、複数のスコアを同時に登録するオーバーロード関数が追加されており、これを利用することができます。
従来のランキングでの以下のような例について説明します。
- スコア登録時、各スコアのグループに 0 ~ 3 の値を入れる。
- グループの値が 0 だけのランキング、1 だけのランキング、などをフィルタリング機能で取得する。
これをランキング 2 で実現するには、以下のようにします。
- グループ 0 ~ 3 が使用する共通カテゴリ を用意する。
- グループ 0 専用カテゴリ~グループ 3 専用カテゴリ を用意する。
- スコア登録時、グループ X のスコアは、グループ X 専用カテゴリと、共通カテゴリと、の両方に登録する。
- グループでフィルタリングしたいときは、グループ X 専用カテゴリから取得する。
- フィルタリングしたくないときは、共通カテゴリから取得する。
6.9.2.2. 更新日時によるフィルタリング機能(タイムスコープ)
スコアの更新日時でフィルタリングする機能はありません。該当のカテゴリのすべてのスコアが取得対象です。
代わりに、定期リセットモードの異なる複数のカテゴリタイプと、それらに属するカテゴリを用意し、各カテゴリに同じスコアを登録してください。
例えば、以下のような設定を行うと、カテゴリ 0 とカテゴリ 1、カテゴリ 10 とカテゴリ 11 に入れるスコアは同じであっても、それぞれスコアの残る期間が異なる、ということが実現できます。
- カテゴリタイプ 0 :毎日リセット
- カテゴリタイプ 1 :毎月リセット
- カテゴリ 0 :アイテムを集めた得点を入れるカテゴリ。カテゴリタイプ 0。
- カテゴリ 1 :アイテムを集めた得点を入れるカテゴリ。カテゴリタイプ 1。
- カテゴリ 10 :敵を倒した得点を入れるカテゴリ。カテゴリタイプ 0。
- カテゴリ 11 :敵を倒した得点を入れるカテゴリ。カテゴリタイプ 1。
6.9.2.3. 同点の順位計算方法
同点は必ず同順位として扱います( 6.6.4. )。 従来のランキングの RankingConstants::ORDER_CALCULATION_123 のような指定はできません。
同順位にしたくない場合は、スコアの桁を上げて下位に別の数値を入れるなどの工夫を行ってください。
6.9.2.4. スコア統計値
スコア統計値(合計値や最大、最小値、平均値)を取得することはできません。
ランキング内に存在するスコアの数を取得することはできます( Ranking2Info::GetNumRankedIn() )が、最低順位による削除があるため、スコアの総登録数とは異なります。
6.9.2.5. スコアの削除
クライアントから登録済みスコアを削除する機能は用意されていません。
6.9.2.6. スコアの更新モード
登録済みのスコアより悪いスコアであっても必ず上書き登録するモード( RankingConstants::UPDATE_MODE_DELETE_OLD )に相当する機能は用意されていません。
6.10. エラーハンドリング
6.10.1. API呼び出し時のエラー
API を呼び出した結果、非同期処理が開始せずにエラーが返った場合、実装ミスの可能性があります。 NEX の初期化処理が成功しているか、ゲームサーバーにログインできているか等のチェックを行ってください。
6.10.2. 非同期処理のエラー
エラーハンドリングの方法はマッチメイクと同じです。 4.25. エラーハンドリング を参照してください。
ランキング 2 で発生しうるエラーは Table 6.10 のとおりです。 ただし、NEX の通信処理等で発生するエラーを除いています。 NEX の非同期処理や、エラーハンドリングについては、 NEX ライブラリ全般 の説明を参照してください。
ReturnCode値 | 概要 |
---|---|
QERROR(Ranking2, InvalidArgument) | 不正な引数を指定しました。実装ミスによるものなので、修正を行ってください。 |
QERROR(Ranking2, Unknown) | 不明なエラーが発生しました。サーバーの設定が異常です。このエラーが出た場合は、弊社にお問い合わせください。 |
6.11. NEX ゲームサーバー管理ツール( NMAS )
注意
NMAS の各種機能は NEX 3.10 リリース後に提供予定です。
NEX ゲームサーバー管理ツール( NMAS, Nex server MAnagement System )のランキング 2 管理機能では、ランキングに登録されたスコアの閲覧や、 カテゴリおよびカテゴリタイプ設定、全てのスコアデータの削除などを行うことができます。 開発環境、製品環境のどちらも対応しています。
6.11.1. 管理ツールへのアクセス方法
管理ツールへは以下の URL からアクセスすることができます。
https://nmas.mng.nintendo.net/nmas/
ログイン ID とパスワードは OMAS と同じものを使用してください。
6.12. 注意事項
6.12.1. 想定しているスコア数について
ランキング 2 機能が想定しているスコアの数は、1,000,000 件以内です。 1,000,000 件を超えそうなタイトルについては、事前に弊社にご相談ください。
スコア数は、以下の式によって見積もることができます。 最低順位や過去シーズン保存数の設定が一律でない場合は、それぞれのカテゴリごとに計算したものの和を取ってください。
スコア数の見込み=カテゴリ数×最低順位 (※定期リセットありの場合は、上記の数に 過去シーズン保存数 + 2 をかけてください)
デフォルトでは最低順位 10000、定期リセットなし、と設定されているため、カテゴリ数 100 が基準値です。
ランキング 2 では、最低順位よりも低いスコアは削除されるため、スコア数が延々と増え続けることは通常ありません。 例外は以下のような場合です。
- 動的にカテゴリを生成する。
- カテゴリの数によってスコア数が増加します。
- 特に、定期リセットなしの設定では動的に生成したカテゴリのデータが残り続けますので、注意してカテゴリやカテゴリタイプの設計を行ってください。