> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Ranking マスターデータリファレンス
マスターデータのフォーマットと インポートする各種モデルのリファレンス
## マスターデータのフォーマット
**JSON**
```json
{
"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"
}
]
}
```
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2019-09-17 | | マスターデータのフォーマットバージョン |
| categories | [List<CategoryModel>](#categorymodel) | | | | ~ 1000 items | カテゴリーモデル
カテゴリー毎に異なるランキングを作成できます。
カテゴリーには登録できるスコアの最小値・最大値を設定でき、その範囲外のスコアは破棄されます。
ランキングを集計する際にスコアを小さいものを上位（昇順）にするか、大きいものを上位（降順）にするかを設定できます。
ランキングの種類として `グローバル` と `スコープ` を選択できます。
グローバルは全プレイヤーが同じ結果を参照するもので、スコープはフレンド内ランキングや、ギルド内ランキングのようなゲームプレイヤー毎に結果の異なるランキングです。
グローバルランキングはカテゴリーごとにランキングの集計間隔を15分～24時間で設定できます。
スコープランキングはリアルタイムで集計結果が反映されます。
ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。 |
## モデル
### CategoryModel
カテゴリーモデル
カテゴリー毎に異なるランキングを作成できます。
カテゴリーには登録できるスコアの最小値・最大値を設定でき、その範囲外のスコアは破棄されます。
ランキングを集計する際にスコアを小さいものを上位（昇順）にするか、大きいものを上位（降順）にするかを設定できます。
ランキングの種類として `グローバル` と `スコープ` を選択できます。
グローバルは全プレイヤーが同じ結果を参照するもので、スコープはフレンド内ランキングや、ギルド内ランキングのようなゲームプレイヤー毎に結果の異なるランキングです。
グローバルランキングはカテゴリーごとにランキングの集計間隔を15分～24時間で設定できます。
スコープランキングはリアルタイムで集計結果が反映されます。
ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| categoryModelId | string | | ※ | | ~ 1024文字 | カテゴリーモデルGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | カテゴリーモデル名
カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 1024文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| minimumValue | long | | | | 0 ~ 9223372036854775805 | スコアの最小値
このカテゴリーに登録できるスコアの最小値。
この閾値を下回るスコアは登録時に拒否されます。未設定の場合、下限はありません。 |
| maximumValue | long | | | | 0 ~ 9223372036854775805 | スコアの最大値
このカテゴリーに登録できるスコアの最大値。
この閾値を上回るスコアは登録時に拒否されます。未設定の場合、上限はありません。 |
| sum | bool | | | false | | 合算モード
有効にすると、新しく登録されたスコアは既存のスコアを置き換えるのではなく、合計に加算されます。
ランキングは蓄積された合計値に基づいて計算されます。無効の場合、各スコア登録は独立したエントリとして扱われます。 |
| orderDirection | 文字列列挙型
enum {
"asc",
"desc"
}
| | ✓ | | | ソート方向
ランキング集計のソート順を決定します。
"asc"（昇順）は低いスコアを上位とし、タイムベースやゴルフ式のランキングに適しています。
"desc"（降順）は高いスコアを上位とし、ポイントベースやハイスコアランキングに適しています。"asc": 昇順 / "desc": 降順 / |
| scope | 文字列列挙型
enum {
"global",
"scoped"
}
| | ✓ | | | ランキングの種類
このカテゴリーのランキングタイプ。
"global" は全プレイヤーが共有する単一のリーダーボードを作成し、設定された間隔でバッチ集計されます。
"scoped" は購読したプレイヤー（フレンドやギルドメンバー等）に基づくユーザーごとのリーダーボードを作成し、スコアがリアルタイムで反映されます。"global": グローバル / "scoped": スコープ / |
| globalRankingSetting | [GlobalRankingSetting](#globalrankingsetting) | {scope} == "global" | ✓※ | | | グローバルランキング設定
グローバルランキングモード固有の設定。集計間隔、固定時刻、スコアのユニーク性、世代管理、および追加の期間限定スコープを含みます。
scope が "global" に設定されている場合のみ適用されます。
※ scope が "global" であれば 必須 |
| entryPeriodEventId | string | | | | ~ 1024文字 | スコア登録期間イベントID
スコア登録を受け付ける期間を定義する GS2-Schedule イベントの GRN。
この期間外のスコア登録リクエストは拒否されます。未設定の場合、スコアはいつでも登録できます。 |
| accessPeriodEventId | string | | | | ~ 1024文字 | アクセス期間イベントID
ランキングデータを閲覧できる期間を定義する GS2-Schedule イベントの GRN。
この期間外のランキング取得リクエストは拒否されます。未設定の場合、ランキングはいつでもアクセスできます。 |
---
### Scope
集計スコープ
グローバルランキングモードにおける追加の期間限定集計スコープを定義します。
通常、グローバルランキングは登録されたスコア全てを対象に集計が行われます。
スコープを追加することで、指定した日数以内に登録されたスコアのみを対象とする別ランキングを作成でき、全期間ランキングと併せてデイリー・ウィークリー・マンスリーなどのリーダーボードを実現できます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128文字 | スコープ名
カテゴリー内でこの集計スコープを一意に識別する名前。
複数の期間限定ランキングボードを区別するために使用されます（例: "daily", "weekly"）。最大128文字。 |
| targetDays | long | | ✓ | | 1 ~ 365 | 集計対象日数
集計ウィンドウに含める日数。
現在時刻からこの日数以内に登録されたスコアのみがスコープランキングの対象となります。範囲: 1～365日。 |
---
### GlobalRankingSetting
グローバルランキング設定
グローバルは全プレイヤーが同じ結果を参照するものです。
ランキングの集計間隔を15分～24時間で設定できます。
ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| uniqueByUserId | bool | | | true | | ユーザーID毎にユニーク
有効にすると、ランキング内でユーザーIDごとに1つのスコアのみ保持されます。
ユーザーが新しいスコアを登録すると、ソート方向に基づいてより良いスコアに置き換えられます。
無効にすると、同一ユーザーから複数のスコアエントリが許可され、合算モードや複数エントリによる競争が可能になります。 |
| calculateIntervalMinutes | int | | ✓ | | 15 ~ 1440 | 集計間隔（分）
連続するランキング再集計の間隔（分）。
システムはこの間隔で、登録された全スコアに基づいてグローバルランキングを定期的に再集計します。
範囲: 15～1440分（15分～24時間）。 |
| calculateFixedTiming | [FixedTiming](#fixedtiming) | | | | | 集計時刻固定設定
ランキング再集計が開始される1日の固定時刻（UTC）を指定します。
未設定の場合、再集計は不定の基準時刻から定期間隔で実行されます。
これを設定することで、毎日予測可能で一貫した時刻に再集計が行われるようになります。 |
| additionalScopes | [List<Scope>](#scope) | | | | 0 ~ 10 items | 追加スコープリスト
追加の期間限定集計スコープのリスト。
各スコープは指定した日数以内に登録されたスコアのみを対象とする別ランキングを定義します。
全期間のグローバルランキングと併せて、デイリー・ウィークリー・マンスリーなどのリーダーボードを作成できます。最大10件。 |
| ignoreUserIds | List<string> | | | | 0 ~ 10000 items | 除外ユーザーIDリスト
ランキング集計からスコアを除外するユーザーIDのリスト。
テストアカウント、管理者アカウント、または既知の不正ユーザーをリーダーボードから除外するのに使用します。最大10,000件。 |
| generation | string | | | | ~ 256文字 | 世代
現在のランキング世代を表す任意の文字列。
この値を変更すると、前の世代のスコアはランキング集計に含まれなくなるため、実質的にスコアがリセットされます。
シーズン制リセットや定期的なランキングリセットの実装に使用します。最大256文字。 |
---
### FixedTiming
集計時刻固定設定
グローバルランキングの集計が開始される固定時刻を指定します。
この設定がない場合、ランキング集計は不定の基準時刻から定期間隔で実行されます。
固定の時・分を指定することで、毎日の集計開始時刻（UTC）を予測可能にでき、深夜0時や特定の時刻に集計を開始するよう制御できます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| hour | int | | | | 0 ~ 23 | 時
ランキング集計が開始される時刻の時（UTC）。
0～23 の整数で指定します。 |
| minute | int | | | | 0 ~ 59 | 分
指定した時刻の分。
0～59 の整数で指定します。 |
---