GS2-Ranking マスターデータリファレンス

マスターデータのフォーマットと インポートする各種モデルのリファレンス

マスターデータのフォーマット

{
  "version": "2019-09-17",
  "categories": [
    {
      "name": "[string]カテゴリーモデル名",
      "metadata": "[string?]メタデータ",
      "minimumValue": "[long?]スコアの最小値",
      "maximumValue": "[long?]スコアの最大値",
      "sum": "[bool]合算モード",
      "orderDirection": "[string enum]ソート方向",
      "scope": "[string enum]ランキングの種類",
      "globalRankingSetting": {
        "uniqueByUserId": "[bool]ユーザーID毎にユニーク",
        "calculateIntervalMinutes": "[int]集計間隔(分)",
        "calculateFixedTiming": {
          "hour": "[int?]時",
          "minute": "[int?]分"
        },
        "additionalScopes": [
          {
            "name": "[string]スコープ名",
            "targetDays": "[long]集計対象日数"
          }
        ],
        "ignoreUserIds": [
          "[string]ランキングに反映しないユーザーID"
        ],
        "generation": "[string?]世代"
      },
      "entryPeriodEventId": "[string?]スコア登録期間イベントID",
      "accessPeriodEventId": "[string?]アクセス期間イベントID"
    }
  ]
}
有効化条件必須デフォルト値の制限説明
versionstring
2019-09-17マスターデータのフォーマットバージョン
categoriesList<CategoryModel>~ 1000 itemsカテゴリーモデル
カテゴリー毎に異なるランキングを作成できます。

カテゴリーには登録できるスコアの最小値・最大値を設定でき、その範囲外のスコアは破棄されます。
ランキングを集計する際にスコアを小さいものを上位(昇順)にするか、大きいものを上位(降順)にするかを設定できます。

ランキングの種類として グローバルスコープ を選択できます。
グローバルは全プレイヤーが同じ結果を参照するもので、スコープはフレンド内ランキングや、ギルド内ランキングのようなゲームプレイヤー毎に結果の異なるランキングです。

グローバルランキングはカテゴリーごとにランキングの集計間隔を15分~24時間で設定できます。
スコープランキングはリアルタイムで集計結果が反映されます。

ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。

モデル

CategoryModel

カテゴリーモデル

カテゴリー毎に異なるランキングを作成できます。

カテゴリーには登録できるスコアの最小値・最大値を設定でき、その範囲外のスコアは破棄されます。
ランキングを集計する際にスコアを小さいものを上位(昇順)にするか、大きいものを上位(降順)にするかを設定できます。

ランキングの種類として グローバルスコープ を選択できます。
グローバルは全プレイヤーが同じ結果を参照するもので、スコープはフレンド内ランキングや、ギルド内ランキングのようなゲームプレイヤー毎に結果の異なるランキングです。

グローバルランキングはカテゴリーごとにランキングの集計間隔を15分~24時間で設定できます。
スコープランキングはリアルタイムで集計結果が反映されます。

ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。

有効化条件必須デフォルト値の制限説明
categoryModelIdstring
~ 1024文字カテゴリーモデル GRN
※ サーバーが自動で設定
namestring
~ 128文字カテゴリーモデル名
カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
metadatastring~ 1024文字メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。
minimumValuelong0 ~ 9223372036854775805スコアの最小値
このカテゴリーに登録できるスコアの最小値。
この閾値を下回るスコアは登録時に拒否されます。未設定の場合、下限はありません。
maximumValuelong0 ~ 9223372036854775805スコアの最大値
このカテゴリーに登録できるスコアの最大値。
この閾値を上回るスコアは登録時に拒否されます。未設定の場合、上限はありません。
sumboolfalse合算モード
有効にすると、新しく登録されたスコアは既存のスコアを置き換えるのではなく、合計に加算されます。
ランキングは蓄積された合計値に基づいて計算されます。無効の場合、各スコア登録は独立したエントリとして扱われます。
orderDirection文字列列挙型
enum {
  “asc”,
  “desc”
}
ソート方向
ランキング集計のソート順を決定します。
“asc”(昇順)は低いスコアを上位とし、タイムベースやゴルフ式のランキングに適しています。
“desc”(降順)は高いスコアを上位とし、ポイントベースやハイスコアランキングに適しています。
定義説明
“asc”昇順
“desc”降順
scope文字列列挙型
enum {
  “global”,
  “scoped”
}
ランキングの種類
このカテゴリーのランキングタイプ。
“global” は全プレイヤーが共有する単一のリーダーボードを作成し、設定された間隔でバッチ集計されます。
“scoped” は購読したプレイヤー(フレンドやギルドメンバー等)に基づくユーザーごとのリーダーボードを作成し、スコアがリアルタイムで反映されます。
定義説明
“global”グローバル
“scoped”スコープ
globalRankingSettingGlobalRankingSetting{scope} == “global”
✓※
グローバルランキング設定
グローバルランキングモード固有の設定。集計間隔、固定時刻、スコアのユニーク性、世代管理、および追加の期間限定スコープを含みます。
scope が “global” に設定されている場合のみ適用されます。
※ scope が “global” であれば 必須
entryPeriodEventIdstring~ 1024文字スコア登録期間イベントID
スコア登録を受け付ける期間を定義する GS2-Schedule イベントの GRN。
この期間外のスコア登録リクエストは拒否されます。未設定の場合、スコアはいつでも登録できます。
accessPeriodEventIdstring~ 1024文字アクセス期間イベントID
ランキングデータを閲覧できる期間を定義する GS2-Schedule イベントの GRN。
この期間外のランキング取得リクエストは拒否されます。未設定の場合、ランキングはいつでもアクセスできます。

Scope

集計スコープ

グローバルランキングモードにおける追加の期間限定集計スコープを定義します。
通常、グローバルランキングは登録されたスコア全てを対象に集計が行われます。
スコープを追加することで、指定した日数以内に登録されたスコアのみを対象とする別ランキングを作成でき、全期間ランキングと併せてデイリー・ウィークリー・マンスリーなどのリーダーボードを実現できます。

有効化条件必須デフォルト値の制限説明
namestring
~ 128文字スコープ名
カテゴリー内でこの集計スコープを一意に識別する名前。
複数の期間限定ランキングボードを区別するために使用されます(例: “daily”, “weekly”)。最大128文字。
targetDayslong
1 ~ 365集計対象日数
集計ウィンドウに含める日数。
現在時刻からこの日数以内に登録されたスコアのみがスコープランキングの対象となります。範囲: 1~365日。

GlobalRankingSetting

グローバルランキング設定

グローバルは全プレイヤーが同じ結果を参照するものです。
ランキングの集計間隔を15分~24時間で設定できます。

ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。

有効化条件必須デフォルト値の制限説明
uniqueByUserIdbooltrueユーザーID毎にユニーク
有効にすると、ランキング内でユーザーIDごとに1つのスコアのみ保持されます。
ユーザーが新しいスコアを登録すると、ソート方向に基づいてより良いスコアに置き換えられます。
無効にすると、同一ユーザーから複数のスコアエントリが許可され、合算モードや複数エントリによる競争が可能になります。
calculateIntervalMinutesint
15 ~ 1440集計間隔(分)
連続するランキング再集計の間隔(分)。
システムはこの間隔で、登録された全スコアに基づいてグローバルランキングを定期的に再集計します。
範囲: 15~1440分(15分~24時間)。
calculateFixedTimingFixedTiming集計時刻固定設定
ランキング再集計が開始される1日の固定時刻(UTC)を指定します。
未設定の場合、再集計は不定の基準時刻から定期間隔で実行されます。
これを設定することで、毎日予測可能で一貫した時刻に再集計が行われるようになります。
additionalScopesList<Scope>0 ~ 10 items追加スコープリスト
追加の期間限定集計スコープのリスト。
各スコープは指定した日数以内に登録されたスコアのみを対象とする別ランキングを定義します。
全期間のグローバルランキングと併せて、デイリー・ウィークリー・マンスリーなどのリーダーボードを作成できます。最大10件。
ignoreUserIdsList<string>0 ~ 10000 items除外ユーザーIDリスト
ランキング集計からスコアを除外するユーザーIDのリスト。
テストアカウント、管理者アカウント、または既知の不正ユーザーをリーダーボードから除外するのに使用します。最大10,000件。
generationstring~ 256文字世代
現在のランキング世代を表す任意の文字列。
この値を変更すると、前の世代のスコアはランキング集計に含まれなくなるため、実質的にスコアがリセットされます。
シーズン制リセットや定期的なランキングリセットの実装に使用します。最大256文字。

FixedTiming

集計時刻固定設定

グローバルランキングの集計が開始される固定時刻を指定します。
この設定がない場合、ランキング集計は不定の基準時刻から定期間隔で実行されます。
固定の時・分を指定することで、毎日の集計開始時刻(UTC)を予測可能にでき、深夜0時や特定の時刻に集計を開始するよう制御できます。

有効化条件必須デフォルト値の制限説明
hourint0 ~ 23
ランキング集計が開始される時刻の時(UTC)。
0~23 の整数で指定します。
minuteint0 ~ 59
指定した時刻の分。
0~59 の整数で指定します。