> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-SeasonRating Master Data Reference

Reference for the master data format and the models to be imported




## Master Data Format


**JSON**
```json
{
  "version": "2024-02-23",
  "seasonModels": [
    {
      "name": "[string]Season Model name",
      "metadata": "[string?]Metadata",
      "tiers": [
        {
          "metadata": "[string?]Metadata",
          "raiseRankBonus": "[int]Raise Rank Bonus",
          "entryFee": "[int]Entry Fee",
          "minimumChangePoint": "[int]Minimum Change Point",
          "maximumChangePoint": "[int]Maximum Change Point"
        }
      ],
      "experienceModelId": "[string]Experience Model ID",
      "challengePeriodEventId": "[string?]Challenge Period Event ID"
    }
  ]
}
```


|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2024-02-23 | | Master data format version |
| seasonModels | [List&lt;SeasonModel&gt;](#seasonmodel) |  |  |  |  ~ 50 items | Season Model<br>Defines the tier structure and point adjustment rules applied during a season.<br>Specifies tier-based point change ranges, entry fees, rank-up bonuses, and the Experience Model used for point management.<br>Actual user data (points and tier affiliation) is managed by GS2-Experience. |

## Models

### SeasonModel

Season Model

Defines the tier structure and point adjustment rules applied during a season.
Specifies tier-based point change ranges, entry fees, rank-up bonuses, and the Experience Model used for point management.
Actual user data (points and tier affiliation) is managed by GS2-Experience.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| seasonModelId | string |  | * |  |  ~ 1024 chars | Season Model GRN<br>* Set automatically by the server |
| name | string |  | ✓ |  |  ~ 128 chars | Season Model name<br>Unique Season Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| metadata | string |  |  |  |  ~ 128 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| tiers | [List&lt;TierModel&gt;](#tiermodel) |  | ✓ |  | 1 ~ 100 items | List of Tier Models<br>The ordered list of tier definitions that compose the season's ranking ladder.<br>Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus).<br>Players progress through tiers based on their accumulated points managed by GS2-Experience.<br>Minimum 1 tier, maximum 100 tiers. |
| experienceModelId | string |  | ✓ |  |  ~ 1024 chars | Experience Model ID<br>GRN of the GS2-Experience experience model used to manage season points and tier progression.<br>The experience model's rank thresholds determine tier boundaries, and experience values represent the player's current season points.<br>Point changes from match results are applied to this experience model. |
| challengePeriodEventId | string |  |  |  |  ~ 1024 chars | Challenge Period Event ID<br>GRN of the GS2-Schedule event that defines the period during which the season is open for competitive matches.<br>When set, players can only participate in matches while the referenced event is active.<br>If not set, the season has no time restriction. |

---

### TierModel

Tier Model

TierModel defines the point adjustment rules for each tier within a season.
Specifies point change ranges by rank, entry fees, and promotion bonuses.
While actual point data is managed by GS2-Experience, the calculation logic for point adjustments is determined by the TierModel configuration.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| metadata | string |  |  |  |  ~ 128 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| raiseRankBonus | int |  | ✓ |  | 0 ~ 10000 | Raise Rank Bonus<br>Bonus points added when a player is promoted to this tier, providing a buffer to prevent immediate demotion.<br>For example, if set to 100, the player starts the new tier with 100 extra points above the promotion threshold.<br>Valid range: 0 to 10000. |
| entryFee | int |  | ✓ |  | 0 ~ 10000 | Entry Fee<br>Points deducted from the player before the match begins as a participation cost.<br>This fee is always subtracted regardless of the match outcome, creating a risk element in competitive play.<br>Valid range: 0 to 10000. |
| minimumChangePoint | int |  | ✓ |  | -99999999 ~ -1 | Minimum Change Point<br>The minimum (most negative) point change that can occur from a single match result, typically representing the worst-case loss.<br>Must be a negative value. The actual point change for a losing player falls between this value and 0.<br>Valid range: -99999999 to -1. |
| maximumChangePoint | int |  | ✓ |  | 1 ~ 99999999 | Maximum Change Point<br>The maximum (most positive) point change that can occur from a single match result, typically representing the best-case win.<br>Must be a positive value. The actual point change for a winning player falls between 0 and this value.<br>Valid range: 1 to 99999999. |

---