GS2-Enhance Master Data Reference

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

Master Data Format

{
  "version": "2020-08-22",
  "rateModels": [
    {
      "name": "[string]Enhancement Rate Model name",
      "description": "[string?]Description",
      "metadata": "[string?]Metadata",
      "targetInventoryModelId": "[string]GS2-Inventory Inventory Model GRN usable for enhancement targets",
      "acquireExperienceSuffix": "[string]Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience",
      "materialInventoryModelId": "[string]GS2-Inventory Inventory Model GRN usable as enhancement material",
      "acquireExperienceHierarchy": [
        "[string]Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata"
      ],
      "experienceModelId": "[string]GS2-Experience Experience Model GRN gained as a result of enhancement",
      "bonusRates": [
        {
          "rate": "[float]Experience bonus multiplier (1.0 = no bonus)",
          "weight": "[int]Lottery weight"
        }
      ]
    }
  ],
  "unleashRateModels": [
    {
      "name": "[string]Unleash Rate Model name",
      "description": "[string?]Description",
      "metadata": "[string?]Metadata",
      "targetInventoryModelId": "[string]GS2-Inventory Inventory Model GRN usable for unleash targets",
      "gradeModelId": "[string]Grade Model GRN",
      "gradeEntries": [
        {
          "gradeValue": "[long]Target grade",
          "needCount": "[int]How many items of the same type to consume"
        }
      ]
    }
  ]
}
Type Condition Required Default Value Limits Description
version string
✓
 2020-08-22 Format version of master data
rateModels List<RateModel> ~ 10000 items Enhancement Rate Model
The enhancement rate is data that defines the materials used for enhancement and the target of enhancement.

Both material data and enhancement target data must be managed in GS2-Inventory.
The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format.
Here, it is necessary to describe at which level of the metadata the experience value is stored.

A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement.
The probability of that draw is also defined in this entity.
unleashRateModels List<UnleashRateModel> ~ 10000 items Unleash Rate Model
Defines the conditions for limit breaking (unleashing) items. Associates an item managed in GS2-Inventory with a GS2-Grade grade model to enable grade progression. Each grade level can require consuming a different number of duplicate items, allowing fine-grained control over the cost of each limit break step.

Models

RateModel

Enhancement Rate Model

The enhancement rate is data that defines the materials used for enhancement and the target of enhancement.

Both material data and enhancement target data must be managed in GS2-Inventory. The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format. Here, it is necessary to describe at which level of the metadata the experience value is stored.

A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement. The probability of that draw is also defined in this entity.

Type Condition Required Default Value Limits Description
rateModelId string
*
 ~ 1024 chars Enhancement Rate Model GRN
* Set automatically by the server
name string
✓
 ~ 128 chars Enhancement Rate Model name
Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
description string ~ 1024 chars 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.
targetInventoryModelId string
✓
 ~ 1024 chars GS2-Inventory Inventory Model GRN usable for enhancement targets
Specifies the GS2-Inventory inventory model that holds the items eligible for enhancement. The item to be enhanced must belong to this inventory model.
acquireExperienceSuffix string
✓
 ~ 1024 chars Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience
A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity).
materialInventoryModelId string
✓
 ~ 1024 chars GS2-Inventory Inventory Model GRN usable as enhancement material
Specifies the GS2-Inventory inventory model that holds the items usable as enhancement materials. The experience value each material provides is defined in the item model’s metadata using the JSON hierarchy specified by acquireExperienceHierarchy.
acquireExperienceHierarchy List<string> 0 ~ 10 items Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata
GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata.
For example, to define metadata with a structure like: { “aaa”: { “bbb”: { “experienceValue”: 100 } } } Specify it as: [ “aaa”, ‘bbb’, “experienceValue” ]
Details are explained in the Microservices Introduction / GS2-Enhance section.
experienceModelId string
✓
 ~ 1024 chars GS2-Experience Experience Model GRN gained as a result of enhancement
Specifies the GS2-Experience experience model where the experience points obtained from enhancement are recorded. The experience is added to the property identified by combining the target item’s property ID with the acquireExperienceSuffix.
bonusRates List<BonusRate> 0 ~ 1000 items Experience gain bonus
Defines a weighted lottery for bonus experience multipliers during enhancement. Each entry specifies a multiplier (e.g., 1.5 for 150%) and a draw weight. When enhancement is performed, one entry is selected by weighted lottery to determine whether a “great success” bonus applies to the experience gained.

BonusRate

Experience Gain Bonus

Defines a single entry in the weighted lottery for determining the experience bonus multiplier during enhancement. By configuring multiple entries with different rates and weights, you can implement “great success” or “super success” mechanics with controlled probabilities.

Type Condition Required Default Value Limits Description
rate float 1.0 0 ~ 10000 Experience bonus multiplier (1.0 = no bonus)
The multiplier applied to the base experience value when this entry is drawn. A value of 1.0 means normal enhancement with no bonus, 1.5 means 150% experience (great success), 2.0 means 200% experience (super success), and so on.
weight int 1 0 ~ 2147483645 Lottery weight
The relative weight used in the weighted lottery when selecting the bonus rate. Higher values increase the probability of this bonus rate being selected. The actual probability is this weight divided by the sum of all weights in the bonus rate list.

UnleashRateModel

Unleash Rate Model

Defines the conditions for limit breaking (unleashing) items. Associates an item managed in GS2-Inventory with a GS2-Grade grade model to enable grade progression. Each grade level can require consuming a different number of duplicate items, allowing fine-grained control over the cost of each limit break step.

Type Condition Required Default Value Limits Description
unleashRateModelId string
*
 ~ 1024 chars Unleash Rate Model GRN
* Set automatically by the server
name string
✓
 ~ 128 chars Unleash Rate Model name
Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
description string ~ 1024 chars 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.
targetInventoryModelId string
✓
 ~ 1024 chars GS2-Inventory Inventory Model GRN usable for unleash targets
Specifies the GS2-Inventory inventory model that holds the items eligible for limit breaking. The item to be unleashed and the duplicate items consumed as material must both belong to this inventory model.
gradeModelId string
✓
 ~ 1024 chars Grade Model GRN
Specifies the GS2-Grade grade model that tracks the limit break level of the target item. When a limit break is successfully performed, the item’s grade is incremented in this grade model.
gradeEntries List<UnleashRateEntryModel>
✓
 1 ~ 1000 items List of Grade Entry
Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. For example, grade 1 might require 1 duplicate, grade 2 might require 3 duplicates, and so on.

UnleashRateEntryModel

Unleash Rate Entry Model

Defines the material cost for a single grade level in a limit break progression. Each entry specifies which grade value it applies to and how many duplicate items of the same type must be consumed to achieve that grade.

Type Condition Required Default Value Limits Description
gradeValue long
✓
 1 ~ 1000 Target grade
The grade value that this entry defines the cost for. When performing a limit break to this grade level, the number of items specified by needCount will be consumed.
needCount int
✓
 1 ~ 1000 How many items of the same type to consume
The number of duplicate items that must be consumed to perform the limit break to the target grade. These items are of the same item model as the item being unleashed.