5. ランキング

5.1. はじめに

ランキングは、ユーザーが登録したスコアを用いて順位を生成する機能です。 ユーザーがスコアを登録するとサーバーでそれを集計し、ゲーム内でランキングを取得することができます。

スコアの登録では、ユーザーがもつ複数種類のスコアを別々にあつかってそれぞれのランキングを生成することや、スコアに関連付けてデータを登録することなどが可能です。 例えば、好きなキャラクタを選んで遊び、ゲームクリア時にその経過時間や取得コインをスコアとして登録するゲームの場合、クリア時間と取得コインとを別のランキングにしたり、スコアに使用キャラクタ番号を関連付けたり、といった使い方ができます。

ランキングの取得では、上位のランキング、自分の順位の周辺ランキング、フレンド内だけでのランキング、などの異なる種類のランキングを取得することや、スコアに関連付けたデータで絞り込んだランキングを取得することなどが可能です。

また、通常のランキング取得よりも高頻度で呼び出し可能なキャッシュされたランキングの取得機能や、スコアの統計値を取得する機能なども用意されています。

5.2. ランキング機能が保持する情報

ランキングでは、スコアだけでなく、関連した複数のデータを登録することができます。 プリンシパル ID ごとに Figure 5.1 に示すようなデータセットがゲームサーバーに保存されます。

  • ユーザー共通データ
    • ユーザーごとに 1 つ登録できる、任意のバイナリデータ。
    • ユーザー名などを保存することができます。
  • スコア
    • スコア値。
    • カテゴリ番号ごとに異なる種類のスコアを利用できます。ランキング取得時には、カテゴリ番号ごとのランキングが生成されます。
  • グループ
    • 1つのスコアに関連付けられた、スコアの絞り込み条件に用いる値。
    • ランキング取得時に、特定のグループ値と一致するものだけを取得できます( 5.6.4.1. )。
  • パラメータ
    • 1つのスコアに関連付けられた、任意の値。
    • 使用キャラクタ番号や、スコアに関連するデータ(例:データストアにアップロードしたリプレイデータの ID )などを保存できます。
../_images/Fig_Ranking_Server_Data.png

Figure 5.1 ゲームサーバーに保存される情報

同じカテゴリに対して複数のスコアを登録した場合、その中でのハイスコアだけが保存されます。

補足

NEX ユニーク ID を利用することで、1つの プリンシパル ID に対して複数のデータセットを使うことができます。 詳細は ランキングでの NEX ユニーク ID の利用 を参照してください。

5.3. ランキング利用の流れ

ランキング機能を利用する基本的な流れは以下のとおりです。

  1. ゲームサーバーにログインする
  2. サービスクライアントを初期化する( 5.4.
  3. ランキングの各種機能を利用する
    • スコアを登録する( 5.5.
    • ランキングを取得する( 5.6.
    • その他、各 API を呼び出す
  4. サービスクライアントの終了処理を行い、ゲームサーバーからログアウトする

5.4. サービスクライアントの初期化および終了

ランキングのサービスクライアント( RankingClient )の初期化および終了処理は、マッチメイクでの処理と同じです( 4.3. )。

5.5. スコアを登録する

スコアを登録、変更するには、 RankingClient::UploadScore() 関数を使用します。

スコアの属性情報として RankingScoreData オブジェクトに Table 5.1 の属性値を設定できます。

Table 5.1 RankingScoreData 属性値一覧
項目名 概要 設定可能な値 初期値 設定関数
カテゴリ スコアを登録するカテゴリの番号を指定します。 32 ビットの非負整数 0 SetCategory()
スコア スコアを指定します。 32 ビットの非負整数 0 SetScore()
グループ 0 絞り込み条件として使用するグループの値を指定します。 0 ~ 255 の整数 0 SetGroup0()
グループ 1 絞り込み条件として使用するグループの値を指定します。 0 ~ 255 の整数 0 SetGroup1()
パラメータ 各スコアに紐づくデータを指定します。 64 ビットの非負整数 0 SetParam()
スコアの並び順 スコアの並び順(昇順もしくは降順)を指定します。ランキング取得時の並び順に反映されます。
RankingConstants::ORDER_BY_DESC
または
RankingConstants::ORDER_BY_ASC
RankingConstants::ORDER_BY_DESC SetOrderBy()
スコアの更新モード 同じカテゴリに対してスコアを繰り返し登録した場合に、必ず上書きするかどうかを指定します。
RankingConstants::UPDATE_MODE_NORMAL
または
RankingConstants::UPDATE_MODE_DELETE_OLD
RankingConstants::UPDATE_MODE_NORMAL SetUpdateMode()

スコアには 32 ビットの非負整数( 0 ~ 4294967295 )を指定できますが、上限下限を設定して不正なスコアが登録されないよう制限することができます。 詳しくは、 スコア上下限値の設定 を参照してください。

パラメータは、使用キャラクタ番号や、データストアにアップロードしたスコアに関連するデータの ID(例:リプレイデータ)等の保存に使用することを想定しています。

スコアの並び順に指定する値による動作の違いは以下のとおりです。

  • RankingConstants::ORDER_BY_DESC (降順):スコアの大きい方の順位が高くなります。
  • RankingConstants::ORDER_BY_ASC (昇順):スコアの小さい方の順位が高くなります。

注意

「スコアの並び順」は、同じカテゴリに対しては必ず同じ並び順を指定するようにしてください。 同じカテゴリに対して異なる並び順が指定されたデータが登録された場合、ランキング取得時のスコアの並び順に異常が発生します。

既にゲームサーバーにスコアが登録されている状態で変更する場合、あわせて NEX ゲームサーバー管理ツール( NMAS ) で全てのスコアデータを削除してください。

スコアの更新モードに指定する値による動作の違いは以下のとおりです。

  • RankingConstants::UPDATE_MODE_NORMAL :対象カテゴリの過去のスコアよりも良いスコアの場合にスコアを登録します。
  • RankingConstants::UPDATE_MODE_DELETE_OLD :対象カテゴリの過去のスコアを削除した上で新しいスコアを登録します。スコアの良し悪しに関わらず常に最新のスコアを利用する場合に使用します。

この API では自分と同じプリンシパル ID のスコアのみ登録することができます。

また、RankingClient::UploadScore() 関数の引数に NEX ユニーク ID を指定することで、プリンシパル ID よりも細かい単位でスコアを登録することができます( 11.3.1.1. )。

5.6. ランキングを取得する

ランキングを取得するには、 RankingClient::GetRanking() を使用します。

上位のランキングだけでなく、自分の周辺のランキングや、フレンドのランキングなど、複数種類のランキングから選択して取得できます。 さらに、ランキングの順位計算方法や、絞り込み条件を指定することができます。

また、ランキングはカテゴリごとに生成されます。

5.6.1. ランキングの種類

ランキングの種類を選択するには、 RankingClient::GetRanking() 関数の引数でランキングの取得モード( RankingMode )を指定します。 Table 5.2 にある種類のランキングを取得できます。

Table 5.2 ランキングの種類の一覧
種類 RankingMode 値 概要
範囲ランキング RANKING_MODE_RANGE 開始位置と長さを指定し、その範囲のランキングを取得します。
周辺ランキング RANKING_MODE_NEAR 指定ユーザーの周辺のランキングを取得します。
フレンドランキング RANKING_MODE_FRIEND_RANGE 自分のフレンド内でのランキングを取得します。フレンドが 1 人もいない場合は、自分のデータのみ取得されます。
フレンド周辺ランキング RANKING_MODE_FRIEND_NEAR フレンドランキング内で自分の周辺ランキングを取得します。
個人のランキングデータ取得 RANKING_MODE_USER 指定したユーザーのランキングデータを取得します。

範囲ランキングでは、1位から RankingConstants::MAX_RANGE_RANKING_ORDER 位までのランキングの中で開始位置と長さを指定し、ランキングを取得します。 開始位置を RankingConstants::MAX_RANGE_RANKING_ORDER - 1 より大きく指定することはできません。

上位のランキングを取得する場合は、範囲ランキングの代わりに、キャッシュされた上位ランキングの取得 API ( 5.6.6. )を利用できます。

周辺ランキングでは、指定したユーザーがリストの中央に来るようなランキングを取得します。 ただし、指定したユーザーが最上位や最下位周辺にいる場合、中央に来ないことがあります。 その場合、実際に登録されているスコアの数に関わらず、指定した件数が取得されません。

周辺ランキングは範囲ランキングと異なり取得可能な順位の制限はなく、指定したユーザーの順位が RankingConstants::MAX_RANGE_RANKING_ORDER 位より低くても取得することができます。

5.6.2. 順位計算パラメータ

順位計算パラメータ( RankingOrderParam )により、ランキングの順位計算方法、絞り込み条件を指定できます。 RankingOrderParam オブジェクトに Table 5.3 のパラメータを与える必要があります。

Table 5.3 RankingOrderParam パラメータ一覧
項目名 概要 初期値 設定関数
順位計算方法 同点が複数あった場合の順位計算の方法を指定します。 RankingConstants::ORDER_CALCULATION_113 SetOrderCalculation()
オフセット ランキングの先頭を 0 としたときの取得開始位置の指定ができます。範囲ランキング、フレンドランキング取得時のみ利用されます。 0 SetOffset()
長さ 取得するデータの最大数を指定します。 10 SetLength()
グループインデックス グループでの絞り込みを行う場合に、使用するグループインデックスを指定します( 5.6.4.1. )。 RankingConstants::FILTER_GROUP_INDEX_NONE SetFilterGroupIndex()
絞り込むグループ番号 グループでの絞り込みを行う場合に、何番で絞り込むかを指定します。 0 SetFilterGroupNum()
タイムスコープ 期間での絞り込みを行う場合に、タイムスコープを指定します( 5.6.4.2. )。 RankingConstants::TIME_SCOPE_ALL SetTimeScope()

順位計算方法に指定する値による動作の違いは以下のとおりです。

  • RankingConstants::ORDER_CALCULATION_113:同点が複数ある場合に、同じ順位とします(例: 1 位、 1 位、 3 位)。
  • RankingConstants::ORDER_CALCULATION_123:同点が複数ある場合に、更新時刻(秒単位)の古い方を上位とします。更新時刻も同じ場合は、プリンシパル ID の小さい方を上位とします。

5.6.3. ランキング取得結果

ランキングの結果は RankingResult オブジェクトに格納されます。 RankingResult オブジェクトには、指定した条件に合致するスコアの総数、ランキングの集計開始日時、ランキングデータのリスト( qVector<RankingRankData> )が含まれています。 RankingRankData で取得可能な項目の一覧は Table 5.4 を参照してください。

Table 5.4 RankingRankData で取得可能な項目
項目名 取得関数
プリンシパル ID GetPrincipalId()
NEX ユニーク ID GetUniqueId()
カテゴリ GetCategory()
順位 GetOrder()
スコア GetScore()
グループ 0 GetGroup0()
グループ 1 GetGroup1()
パラメータ GetParam()
ユーザー共通データ GetCommonData()

取得するランキングのスコアの並び順(昇順または降順)は、スコアの登録時にカテゴリ毎に RankingScoreData::SetOrderBy() によって指定した並び順に基づいたものです。ランキング取得時にスコアの並び順を変更することはできません。

補足

周辺ランキングや個人のランキングデータ取得で RankingConstants::MAX_ACCURATE_ORDER 位より下位のユーザーのランキングを取得する場合、 RankingRankData::GetOrder() により取得される順位に多少の誤差が生じることがあります。

ゲームサーバーでは、RankingConstants::MAX_ACCURATE_ORDER 位より下位の順位を計算する際にサーバーの負荷を軽減する特殊な処理を行っています。 この処理により得られる順位はまれに多少の誤差が生じることがあり、誤差は定期的に修正されますが、リアルタイムでの正確な順位が得られることは保証されません。

RankingConstants::MAX_ACCURATE_ORDER 位より上位のスコアについては、リアルタイムでの正確な順位が取得できます。

5.6.4. ランキングデータの絞り込み

ランキングデータを取得する際に、グループや登録時刻によってデータを絞り込むことができます。

5.6.4.1. グループでの絞り込み

特定の属性のスコアだけでランキングを取得したい場合、グループの値でスコアを絞り込むことができます。 スコア登録時にグループに設定した値と、絞り込み時に指定したグループの値とが一致したスコアだけを抜き出し、ランキングのデータを作成します。

RankingOrderParam::SetFilterGroupIndex() に絞り込みの対象とするグループ(グループ 0 または グループ 1 )のインデックスを指定し、RankingOrderParam::SetFilterGroupNum() に絞り込むグループの値を指定します。 絞込みの対象として指定できるグループは 2 つのうちどちらか 1 つです。

例えば、スコア登録時に グループ 0 へ性別を表す番号を保存し、グループ 1 へ国を表す番号を保存した場合、以下のような絞り込みが可能です。

  • グループのインデックスに RankingConstants::FILTER_GROUP_INDEX_0 を、 グループの値に男性の番号を指定すると、男性のみでのランキングが取得できます。
  • グループのインデックスに RankingConstants::FILTER_GROUP_INDEX_1 を、 グループの値に日本の番号を指定すると、日本のみでのランキングが取得できます。
  • 「男性かつ日本」という絞り込みを行う事はできません。

補足

1 つのカテゴリに登録されるスコアは、 ユーザーごとにグループを 1 種類に統一することを推奨します。

グループが異なる複数のスコアを同一カテゴリに登録した場合、各ユーザーのハイスコアのみが登録されるため、特定のグループで絞り込むランキングを取得しても、 ハイスコア以外のグループのランキングには現れません。

5.6.4.2. 期間での絞り込み

特定の期間内のスコアだけでランキングを取得したい場合、スコアの登録時刻で絞り込むことができます。

この特定の期間をタイムスコープと呼びます。 タイムスコープはデフォルトでは無効です。ゲーム開発時にサーバーで最大 2 つまでを設定できます。 各タイムスコープは、それぞれが独立してスコアを保存するテーブルを持ち、期間でのスコアの絞り込み処理を個別に行っています。

スコア登録時には、特に意識しなくても自動的に有効なタイムスコープにスコアが保存されます。 ランキング取得時には、タイムスコープの番号を指定することで、該当する期間で絞り込みされたランキングを取得できます。

Figure 5.2 に示すように、絞り込んだ期間内に各ユーザーが登録した中でのハイスコアがランキングに利用されます。

../_images/Fig_Ranking_Update_Mode.png

Figure 5.2 ユーザーのスコア履歴とランキングに利用されるスコア

タイムスコープには、下記の 3 種類が用意されています。 RankingOrderParam::SetTimeScope() には、このいずれかを指定します。

Table 5.5 タイムスコープの種類
設定値 概要
RankingConstants::TIME_SCOPE_ALL すべての期間。絞り込みを行わない。
RankingConstants::TIME_SCOPE_CUSTOM_0 事前に設定した期間で絞り込む。デフォルトでは無効。
RankingConstants::TIME_SCOPE_CUSTOM_1 事前に設定した期間で絞り込む。デフォルトでは無効。

RankingConstants::TIME_SCOPE_ALL は、期間での絞り込みを行いません。期間の設定を変更することはできません。

RankingConstants::TIME_SCOPE_CUSTOM_0 、 RankingConstants::TIME_SCOPE_CUSTOM_1 は、 NEX ゲームサーバー管理ツール( NMAS ) 上であらかじめ設定した絞り込みタイプを用いて絞り込みを行います。 これらはデフォルトでは無効になっているため、スコアを登録する前に NMAS で有効にする必要があります。 詳しくは、 タイムスコープタイプの設定 を参照してください。

取得したランキング結果が実際にどの日時から絞り込まれたものであるかは、 RankingResult::GetSinceTime() により取得できます。 期間での絞り込みを行わない場合( RankingConstants::TIME_SCOPE_ALL を指定した場合)、2000 年 1 月 1 日 0 時 0 分( UTC )が返ります。

5.6.5. 指定したユーザー内でのランキングを取得する

指定したユーザ内でのランキングを取得する場合は、RankingClient::GetRankingByPIDList() 、 RankingClient::GetRankingByUniqueIdList() を使用できます。 RankingClient::GetRankingByPIDList() はユーザーの指定にプリンシパル ID を使用します。指定したプリンシパル ID が複数の NEX ユニーク ID でスコアを登録している場合は、スコアが登録されているすべての NEX ユニーク ID のスコアがランキングに含まれます。RankingClient::GetRankingByUniqueIdList() はユーザーの指定に NEX ユニーク ID を使用します。

ランキングの取得モードには、RANKING_MODE_RANGE (範囲ランキング)と RANKING_MODE_NEAR (周辺ランキング)を指定できます。

指定したユーザー内でのランキングを取得する場合、取得するユーザー自身は自動的にランキングに含まれます。 RankingClient::GetRankingByPIDList() の場合、ユーザー自身のプリンシパル ID が複数の NEX ユニーク ID でスコアを登録している場合は、スコアが登録されているすべての NEX ユニーク ID のスコアがランキングに含まれます。 RANKING_MODE_RANGE (範囲ランキング)を指定した場合、引数 nexUniqueId の値は無視されます。 RANKING_MODE_NEAR (周辺ランキング)を指定した場合、引数 nexUniqueId に指定した NEX ユニーク ID のスコアを中心とした周辺ランキングが取得されます。 RankingClient::GetRankingByUniqueIdList() の場合、引数 nexUniqueId に指定した NEX ユニーク ID のスコアのみがランキングに含まれます。

5.6.6. キャッシュされた上位ランキングを取得する

上位ランキングを取得する場合には、キャッシュされた上位ランキングを取得する API ( RankingClient::GetCachedTopXRanking() 、 RankingClient::GetCachedTopXRankings() ) を使用できます。 これらの API は、最大 5 分間サーバーでキャッシュされる代わりに、通常のランキング取得 API と比べて高頻度で呼び出すことができます。 また、ガイドラインチェック用のアクセス数のカウントは、他のランキング API とは別に行われます。

キャッシュは、カテゴリ と RankingOrderParam の組み合わせごとに異なるものが作られます。ゲーム全体で、最大 200 キャッシュ程度まで利用可能です。 ユーザーが作ったコミュニティに結びつくランキングなど、ユーザーの利用に応じて数が多くなる可能性がある場合は、キャッシュ効果が薄いので、利用しないでください。

トップから何番目まで取得できるかの長さは、 NEX ゲームサーバー管理ツール( NMAS ) で指定することができます。初期値では、20 番目までのランキングを取得可能で、10, 20, 50, 100 の値を選択することができます。

ランキングの結果は RankingCachedResult オブジェクトに格納されます。 RankingCachedResult オブジェクトには、指定した条件に合致するスコアの総数、ランキングの集計開始日時、キャッシュの生成時刻、有効期限、ランキングデータのリスト( qVector<RankingRankData> )が含まれています。 RankingRankData で取得可能な項目の一覧は Table 5.4 を参照してください。

RankingClient::GetCachedTopXRankings() は、複数のカテゴリを指定可能です。 NMAS で指定された長さとカテゴリ数を掛け合わせて最大 100 まで取得できます。 初期値では、最大 5 個のカテゴリを指定できます。

RankingClient::GetCachedTopXRanking() や、 RankingClient::GetCachedTopXRankings() で取得されたデータは、更新されるような新しいスコアを登録しても、更新期限まで 新しいスコアが挿入されることがありません。 ローカルで、あらかじめ取得されているランキングキャッシュの結果に新しいスコアを挿入することにより、あたかもスコアが更新されたような状態を作る RankingCachedResult::LocalUpdate() が利用できます。 制限事項は、API リファレンスを参考にしてください。

5.7. ユーザー共通データを登録する

自分のユーザー共通データを登録、変更するには、RankingClient::UploadCommonData() 関数を使用します。

ユーザー共通データには、任意のバイナリデータをユーザーごとに 1 つ登録することができます。 登録できる共通データの最大サイズは 255 バイトです。

自分のユーザー共通データを取得するには RankingClient::GetCommonData() 関数を使用します。 削除するには RankingClient::DeleteCommonData() 関数を使用します。 これらの API では自分と同じプリンシパル ID のユーザー共通データのみ取得、変更することができます。

他人のユーザー共通データは、ランキング取得時に返される RankingRankData オブジェクトから取得できます。

注意

ユーザー共通データに UGC を含んだ内容を登録する場合は、UGC に関するガイドラインに従ってください。

5.8. スコアの属性値を変更する

スコアの属性値を変更するには RankingClient::ChangeAttributes() を使用します。 スコアに紐づく属性値であるグループとパラメータを変更することができます。

この API では自分と同じプリンシパル ID で登録されているスコアのみ変更することができます。

5.9. スコアを削除する

スコアを削除するには RankingClient::DeleteScore() 関数を使用します。 指定したカテゴリ もしくは 全カテゴリのスコアを削除します。

この API では自分と同じプリンシパル ID で登録されているスコアのみ削除することができます。

5.10. スコアを元にした予測順位を取得する

スコアを登録する前にそのスコアが何位に位置するかを取得するには RankingClient::GetApproxOrder() を使用します。 この関数の使用により、実際にスコアがランキングに登録されることはありません。

補足

5.6.3. ランキング取得結果 での補足と同様に、RankingConstants::MAX_ACCURATE_ORDER 位以下の順位計算の正確さは保証されません。

5.11. スコアの統計値を取得する

スコアの合計、最大値、最小値など、カテゴリごとのスコアの統計値を取得するには RankingClient::GetStats() を使用します。 引数には順位計算パラメータと、取得したい統計値のフラグをビット単位の論理和で指定します。 統計値を指定するフラグは Table 5.6 のとおりです。

Table 5.6 統計値指定フラグ一覧
RankingConstants::StatsFlag 説明
STATS_FLAG_TOTAL スコアの総数
STATS_FLAG_SUM スコアの合計値
STATS_FLAG_MIN スコアの最小値
STATS_FLAG_MAX スコアの最大値
STATS_FLAG_AVERAGE スコアの平均

以下の統計値については、キャッシュが使用されます。

  • STATS_FLAG_TOTAL (スコアの総数)
  • STATS_FLAG_SUM (スコアの合計値)
  • STATS_FLAG_AVERAGE (スコアの平均値)

キャッシュは、集計対象のスコアの数がある一定件数以上になった場合に RankingClient::GetStats() の呼び出しに応じて生成され、30 分程度残ります。 キャッシュが存在する場合にはキャッシュの値が返るため、常に最新の統計値が取得できる訳ではありません。

5.12. エラーハンドリング

5.12.1. API呼び出し時のエラー

API を呼び出した結果、非同期処理が開始せずにエラーが返った場合、プログラミングエラーが発生した可能性があります。 NEX の初期化処理が成功しているか、ゲームサーバーにログインできているか等のチェックを行ってください。

5.12.2. 非同期処理のエラー

エラーハンドリングの方法はマッチメイクと同じです。 4.25. エラーハンドリング を参照してください。

ランキングで発生しうるエラーについては Table 5.7 のとおりです。 ただし、NEX の通信処理等で発生するエラーを除いています。

NEX の非同期処理や、エラーハンドリングについては、 非同期処理 の説明を参照してください。

Table 5.7 ランキングエラー一覧
ReturnCode値 概要
QERROR(Ranking, InvalidArgument) 不正な引数を指定しました。実装ミスによるものなので、修正を行ってください。
QERROR(Ranking, RegistrationError) データの登録に失敗しました。サーバーの動作が不安定である可能性が高いです。
QERROR(Ranking, NotFound) リクエストに合致するデータが存在しません。 このエラーが発生した場合は、無視する、または、データが見つからなかったことをユーザーに通知する等の処理を行ってください。
QERROR(Ranking, InvalidDataSize) 不正なデータサイズです。ユーザー共通データのサイズが不正です。実装ミスによるものなので、修正を行ってください。
QERROR(Ranking, PermissionDenied) アクセス権限がありません。他人のスコアやユーザー共通データを変更しようとしました。実装ミスによるものなので、修正を行ってください。
QERROR(Ranking, Unknown) 不明なエラーが発生しました。サーバーの設定が異常です。このエラーが出た場合は、弊社にお問い合わせください。

5.13. NEX ゲームサーバー管理ツール( NMAS )

NEX ゲームサーバー管理ツール( NMAS, Nex server MAnagement System )のランキング管理機能では、ランキングに登録されたスコアの閲覧や、タイムスコープの設定、全てのスコアデータの削除などを行うことができます。 開発環境、製品環境のどちらも対応しています。

5.13.1. 管理ツールへのアクセス方法

管理ツールへは以下の URL からアクセスすることができます。

https://nmas.mng.nintendo.net/nmas/

ログイン ID とパスワードは OMAS と同じものを使用してください。

5.13.2. スコア上下限値の設定

スコアの上限値、下限値を設定し、不正なスコアがランキングに登録されないよう制限をかけることができます。 設定された範囲外のスコアが登録された場合、無効なスコアとしてクライアントが参照するランキングから隔離された状態で登録されます。 無効スコアのリストは NMAS から参照できます。

5.13.3. タイムスコープタイプの設定

期間によるスコアの絞り込みを行う場合に、どのような期間を用いて絞り込むかを設定することができます。 この絞り込みの種類をタイムスコープタイプと呼びます。

利用可能なタイムスコープタイプは以下のとおりです。 ○の部分の値は NMAS 上で任意に設定できます。

  • 周期的にリセットされる期間での絞り込み(次の周期に入る時刻にランキングがリセットされたように見えます)
    • 毎日○時( UTC ±○) ~ 現在
    • 毎週○曜日○時( UTC ±○) ~ 現在
    • 毎月○日○時( UTC ±○) ~ 現在
    • 毎月第 1 ○曜日○時( UTC ±○) ~ 現在
  • 現在からの相対的な期間での絞り込み
    • 24 時間前 ~ 現在
    • 2 日前の○時( UTC ±○) ~ 現在
    • 7 日前の○時( UTC ±○) ~ 現在
    • 14 日前の○時( UTC ±○) ~ 現在
    • 30 日前の○時( UTC ±○) ~ 現在
    • 60 日前の○時( UTC ±○) ~ 現在

デフォルトのタイムゾーンは UTC+0 です。 NMAS 上で設定を変更した場合、タイムゾーンは OMAS の個人設定にあるタイムゾーンの設定と同じ値が利用されます。

タイムスコープタイプの設定は全カテゴリで共通です。カテゴリごとに異なる設定を行うことはできません。

注意

既にゲームサーバーにスコアが登録されている状態でタイムスコープタイプの設定を変更する場合、あわせて NMAS で全てのスコアデータを削除してください。 削除をしないとランキングの取得結果に異常が生じる可能性があります。

5.13.3.1. 一時的な複数スコアの保持

相対的な期間での絞り込みタイプを利用する場合に限り、同一カテゴリに複数のスコアが一時的に保持されます。 これは、複数のスコアを登録後、時間経過によりその一部が絞り込み対象外になると、ランキングに反映されるスコアが変化する可能性があるためです。

ただし、それらの複数のスコアを任意に取得することはできず、期間で絞り込んだ中でのハイスコアのみがランキングに反映されます。

この一時的に保持される複数のスコアは、属性値の変更( 5.8. )やスコアの削除( 5.9. )を行った際には一括で処理されます。

補足

この絞り込みタイプでは前述のとおり一時的に複数のスコアが保持されますが、グループが異なる複数のスコアが同一カテゴリに保持された状態でグループの絞り込みを行っても、ハイスコアに設定されたグループの値のみが絞り込みに使用され、それ以外のスコアがランキングに現れることはありません。

これは、各ユーザーのハイスコアが選ばれたのちに、グループの絞り込みが行われるためです。 ゲームサーバー側で、期間での絞り込み処理の負荷を軽減するために、各ユーザーのハイスコアを選ぶ処理を期間ごとに事前に行っていることに起因します。

5.14. 注意事項

5.14.1. 想定しているランキング登録数について

NEX で提供しているランキング機能が想定しているスコア登録数は、10,000,000 件以内です。 これ以上のスコアを登録するとレスポンス低下などの影響が発生する可能性があります。 複数のカテゴリを使用している場合には、合計のスコア登録数が 10,000,000 件以下になるように設計してください。 10,000,000 件を超えそうなタイトルについては、事前に弊社にご相談ください。

5.14.2. デバッグ時のダミーデータ登録について

ランキング API の一部は、上位 1000 件を超えるスコア取得を制限しています。 デバッグの際は、NMAS の「ダミーデータを登録する」機能を使用して、ダミーデータを登録してください。 追加するダミーデータは 1500 件以上を推奨します。