GS2-SeasonRating Master Data Reference

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

Master Data Format

{
  "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		Format version of master data
seasonModels	List<SeasonModel>				~ 50 items	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.

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	Required	Value Limits	Description
seasonModelId	string	*	~ 1024 chars	Season Model GRN * Set automatically by the server
name	string	✓	~ 128 chars	Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadata	string		~ 128 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.
tiers	List<TierModel>	✓	1 ~ 100 items	List of Tier Models The ordered list of tier definitions that compose the season’s ranking ladder. Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus). Players progress through tiers based on their accumulated points managed by GS2-Experience. Minimum 1 tier, maximum 100 tiers.
experienceModelId	string	✓	~ 1024 chars	Experience Model ID GRN of the GS2-Experience experience model used to manage season points and tier progression. The experience model’s rank thresholds determine tier boundaries, and experience values represent the player’s current season points. Point changes from match results are applied to this experience model.
challengePeriodEventId	string		~ 1024 chars	Challenge Period Event ID GRN of the GS2-Schedule event that defines the period during which the season is open for competitive matches. When set, players can only participate in matches while the referenced event is active. 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	Required	Value Limits	Description
metadata	string		~ 128 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.
raiseRankBonus	int	✓	0 ~ 10000	Raise Rank Bonus Bonus points added when a player is promoted to this tier, providing a buffer to prevent immediate demotion. For example, if set to 100, the player starts the new tier with 100 extra points above the promotion threshold. Valid range: 0 to 10000.
entryFee	int	✓	0 ~ 10000	Entry Fee Points deducted from the player before the match begins as a participation cost. This fee is always subtracted regardless of the match outcome, creating a risk element in competitive play. Valid range: 0 to 10000.
minimumChangePoint	int	✓	-99999999 ~ -1	Minimum Change Point The minimum (most negative) point change that can occur from a single match result, typically representing the worst-case loss. Must be a negative value. The actual point change for a losing player falls between this value and 0. Valid range: -99999999 to -1.
maximumChangePoint	int	✓	1 ~ 99999999	Maximum Change Point The maximum (most positive) point change that can occur from a single match result, typically representing the best-case win. Must be a positive value. The actual point change for a winning player falls between 0 and this value. Valid range: 1 to 99999999.