GS2-Ranking2 Master Data Reference
Reference for the master data format and the models to be imported
Master Data Format
{
"version": "2024-05-30",
"globalRankingModels": [
{
"name": "[string]Global Ranking Model name",
"metadata": "[string?]Metadata",
"minimumValue": "[long?]Minimum Score",
"maximumValue": "[long?]Maximum Score",
"sum": "[bool]Sum Scores",
"orderDirection": "[string enum]Order Direction",
"entryPeriodEventId": "[string?]Entry Period Event GRN",
"rankingRewards": [
{
"thresholdRank": "[int]Rank Threshold",
"metadata": "[string?]Metadata",
"acquireActions": [
{
"action": "[string]Type of action to be executed in the Acquire Action",
"request": "[string]JSON string of the request used when executing the action"
}
]
}
],
"accessPeriodEventId": "[string?]Access Period Event GRN",
"rewardCalculationIndex": "[string enum]Reward Calculation Index"
}
],
"clusterRankingModels": [
{
"name": "[string]Cluster Ranking Model name",
"metadata": "[string?]Metadata",
"clusterType": "[string enum]Cluster Type",
"minimumValue": "[long?]Minimum Score",
"maximumValue": "[long?]Maximum Score",
"sum": "[bool]Sum Scores",
"orderDirection": "[string enum]Order Direction",
"entryPeriodEventId": "[string?]Entry Period Event GRN",
"rankingRewards": [
{
"thresholdRank": "[int]Rank Threshold",
"metadata": "[string?]Metadata",
"acquireActions": [
{
"action": "[string]Type of action to be executed in the Acquire Action",
"request": "[string]JSON string of the request used when executing the action"
}
]
}
],
"accessPeriodEventId": "[string?]Access Period Event GRN",
"rewardCalculationIndex": "[string enum]Reward Calculation Index"
}
],
"subscribeRankingModels": [
{
"name": "[string]Subscribe Ranking Model name",
"metadata": "[string?]Metadata",
"minimumValue": "[long?]Minimum Score",
"maximumValue": "[long?]Maximum Score",
"sum": "[bool]Sum Scores",
"orderDirection": "[string enum]Order Direction",
"entryPeriodEventId": "[string?]Entry Period Event GRN",
"accessPeriodEventId": "[string?]Access Period Event GRN"
}
]
}| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| version | string | ✓ | 2024-05-30 | Format version of master data | ||
| globalRankingModels | List<GlobalRankingModel> | ~ 10 items | Global Ranking Model The global ranking is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions. | |||
| clusterRankingModels | List<ClusterRankingModel> | ~ 10 items | Cluster Ranking Model The cluster ranking model enables rankings for players within guilds or gatherings. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions. | |||
| subscribeRankingModels | List<SubscribeRankingModel> | ~ 10 items | Subscribe Ranking Model A model that aggregates scores of other players that the user has subscribed to and creates a ranking. |
Model
GlobalRankingModel
Global Ranking Model
The global ranking is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings.
By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| globalRankingModelId | string | * | ~ 1024 chars | Global Ranking GRN * Set automatically by the server | ||||||||
| name | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||||||||
| minimumValue | long | 0 ~ 9223372036854775805 | Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. Used to filter out invalid or unintended score values. | |||||||||
| maximumValue | long | 0 ~ 9223372036854775805 | Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. Used to prevent abnormally high scores from being registered. | |||||||||
| sum | bool | false | Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score (highest or lowest depending on sort direction) is used for ranking. | |||||||||
| orderDirection | String Enum enum { “asc”, “desc” } | ✓ | Order Direction The sort direction for ranking scores. Use “asc” for rankings where lower scores are better (e.g., time trials), or “desc” for rankings where higher scores are better (e.g., high scores).
| |||||||||
| entryPeriodEventId | string | ~ 1024 chars | Entry Period Event GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. | |||||||||
| rankingRewards | List<RankingReward> | {entryPeriodEventId} != null | [] | 0 ~ 100 items | Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. | |||||||
| accessPeriodEventId | string | ~ 1024 chars | Access Period Event GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. Typically set to the interval between score entry periods. | |||||||||
| rewardCalculationIndex | String Enum enum { “rank”, “index” } | “rank” | Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (players with tied scores share the same rank), while “index” uses the 0-based unique sorted position (no ties). Choose “rank” for most typical use cases.
|
RankingReward
Ranking Reward
Set the rewards that can be received during the reference period when the score registration period is set in the ranking. If the repeat setting is enabled, the most recently ended period ranking will be the target for receiving rewards.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| thresholdRank | int | ✓ | 1 ~ 1001 | Rank Threshold The rank threshold for this reward tier. Players whose rank (or index, depending on rewardCalculationIndex setting) is at or above this threshold receive this reward. Set to 1001 to define rewards for unranked players (those outside the top 1000). | ||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| acquireActions | List<AcquireAction> | [] | 0 ~ 100 items | Acquire Actions List of acquire actions executed when the player claims this ranking reward. These define the actual items, currency, or other resources granted as the reward for achieving this rank threshold. |
AcquireAction
Acquire Action
ClusterRankingModel
Cluster Ranking Model
The cluster ranking model enables rankings for players within guilds or gatherings. You can display the top 1000 rankings.
By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.
| Type | Condition | Required | Default | Value Limits | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| clusterRankingModelId | string | * | ~ 1024 chars | Cluster Ranking GRN * Set automatically by the server | ||||||||||
| name | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||||||||||
| clusterType | String Enum enum { “Raw”, “Gs2Guild::Guild”, “Gs2Matchmaking::SeasonGathering” } | ✓ | Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering.
| |||||||||||
| minimumValue | long | 0 ~ 9223372036854775805 | Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. | |||||||||||
| maximumValue | long | 0 ~ 9223372036854775805 | Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. | |||||||||||
| sum | bool | false | Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. | |||||||||||
| orderDirection | String Enum enum { “asc”, “desc” } | ✓ | Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings.
| |||||||||||
| entryPeriodEventId | string | ~ 1024 chars | Entry Period Event GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. | |||||||||||
| rankingRewards | List<RankingReward> | {entryPeriodEventId} != null | [] | 0 ~ 100 items | Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. | |||||||||
| accessPeriodEventId | string | ~ 1024 chars | Access Period Event GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. | |||||||||||
| rewardCalculationIndex | String Enum enum { “rank”, “index” } | “rank” | Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (tied scores share same rank), “index” uses the 0-based unique sorted position (no ties).
|
SubscribeRankingModel
Subscribe Ranking Model
A model that aggregates scores of other players that the user has subscribed to and creates a ranking.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| subscribeRankingModelId | string | * | ~ 1024 chars | Subscribe Ranking GRN * Set automatically by the server | ||||||||
| name | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||||||||
| minimumValue | long | 0 ~ 9223372036854775805 | Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. | |||||||||
| maximumValue | long | 0 ~ 9223372036854775805 | Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. | |||||||||
| sum | bool | false | Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. | |||||||||
| orderDirection | String Enum enum { “asc”, “desc” } | ✓ | Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings.
| |||||||||
| entryPeriodEventId | string | ~ 1024 chars | Entry Period Event GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. | |||||||||
| accessPeriodEventId | string | ~ 1024 chars | Access Period Event GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed. |