GS2-Experience Master Data Reference

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

Master Data Format

{
  "version": "2019-01-11",
  "experienceModels": [
    {
      "name": "[string]Experience Model name",
      "metadata": "[string?]Metadata",
      "defaultExperience": "[long]Initial Experience Value",
      "defaultRankCap": "[long]Initial value of rank cap",
      "maxRankCap": "[long]Maximum rank cap",
      "rankThreshold": {
        "metadata": "[string?]Metadata",
        "values": [
          "[long]Rank Up Experience Threshold"
        ]
      },
      "acquireActionRates": [
        {
          "name": "[string]Reward addition table name",
          "mode": "[string]Reward addition table type",
          "rates": [
            "[double]Addition amount (multiplier)"
          ],
          "bigRates": [
            "[string]Addition amount (multiplier)"
          ]
        }
      ]
    }
  ]
}

	Type	Condition	Required	Default	Value Limits	Description
version	string		✓	2019-01-11		Format version of master data
experienceModels	List<ExperienceModel>				~ 100 items	Experience Model Defines the rules for an experience and rank system. Sets thresholds for the experience required to rank up, as well as the default rank cap and maximum rank cap. The rank cap limits the maximum rank a status can reach, and can be raised per-status up to the maximum rank cap (e.g., through limit breaking). Optionally includes acquire action rate tables that adjust reward multipliers based on the current rank.

Models

ExperienceModel

Experience Model

Defines the rules for an experience and rank system. Sets thresholds for the experience required to rank up, as well as the default rank cap and maximum rank cap. The rank cap limits the maximum rank a status can reach, and can be raised per-status up to the maximum rank cap (e.g., through limit breaking). Optionally includes acquire action rate tables that adjust reward multipliers based on the current rank.

	Type	Required	Default	Value Limits	Description
experienceModelId	string	*		~ 1024 chars	Experience Model GRN * Set automatically by the server
name	string	✓		~ 128 chars	Experience Model name Experience Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadata	string			~ 2048 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.
defaultExperience	long		0	0 ~ 9223372036854775805	Initial Experience Value The experience value assigned to a newly created status. Typically set to 0 so that players start at the beginning of the progression. The initial rank is determined from this value using the rank threshold table.
defaultRankCap	long	✓		0 ~ 9223372036854775805	Initial value of rank cap The default maximum rank that a newly created status can reach. Experience beyond this rank’s threshold is discarded or triggers an overflow script. The rank cap can be raised per-status up to maxRankCap through operations like limit breaking.
maxRankCap	long	✓		0 ~ 9223372036854775805	Maximum rank cap The absolute upper limit for the rank cap. Even through rank cap increase operations (such as limit breaking), the rank cap cannot exceed this value. Must be greater than or equal to defaultRankCap.
rankThreshold	Threshold	✓			Rank Up Threshold References the threshold table that defines the cumulative experience values required for each rank. The number of entries in the threshold determines the maximum possible rank, and each entry’s value specifies the experience needed to reach the next rank.
acquireActionRates	List<AcquireActionRate>			0 ~ 100 items	List of Reward addition tables Defines rank-based multiplier tables that adjust reward quantities when the status’s rank is used as a reference. Each table maps ranks to multipliers, enabling mechanics like higher-rank characters receiving more rewards from the same actions.

Threshold

Rank Up Threshold

The Rank Up Threshold is a sequence of numbers needed to determine rank (level) from experience. If the value [10, 20] is set, experience values between 1 and 9 are rank 1, experience values between 10 and 19 are rank 2, experience values at 20 are rank 3, and no more experience values can be obtained.

	Type	Condition	Required	Default	Value Limits	Description
metadata	string				~ 2048 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.
values	List<long>		✓		1 ~ 10000 items	List of Rank Up Experience Threshold An ordered array of cumulative experience values defining the rank progression. The number of entries determines the maximum achievable rank. For example, [10, 20] means rank 1 at 0-9 EXP, rank 2 at 10-19 EXP, and rank 3 at 20+ EXP (with no further gains possible).

AcquireActionRate

Reward Addition Table

Defines a rank-based multiplier table that adjusts reward quantities based on the status’s current rank. Each entry in the table corresponds to a rank and specifies a multiplier applied to the acquisition amount. Supports both standard double-precision values and big number string representations for large-scale calculations.

Type

Condition

Required

Default

Value Limits

Description

name

string

✓

~ 128 chars

Reward addition table name

A unique identifier for this reward addition table. Referenced when specifying which multiplier table to apply to a particular acquire action.

mode

string (enum)
enum {
“double”,
“big”
}

“double”

Reward addition table type

Selects the numeric precision for the multiplier values. Use “double” for standard floating-point numbers (up to 2^48), or “big” for string-represented numbers supporting up to 1024 digits when large-scale calculations are needed.

Definition	Description
“double”	Floating point number less than 2^48
“big”	Floating point number less than 1024 digits

rates

List<double>

{mode} == “double”

✓*

1 ~ 10000 items

Amount added per rank (multiplier)

An array of multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “double”.

* Required if mode is “double”

bigRates

List<string>

{mode} == “big”

✓*

1 ~ 10000 items

Amount added per rank (multiplier)

An array of string-represented multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “big” for calculations requiring large-number precision.

* Required if mode is “big”