GS2-Exchange Master Data Reference
Reference for the master data format and the models to be imported
Master Data Format
{
"version": "2019-08-19",
"rateModels": [
{
"name": "[string]Exchange Rate Model name",
"metadata": "[string?]Metadata",
"verifyActions": [
{
"action": "[string]Type of action to be executed in the Verify Action",
"request": "[string]JSON string of the request used when executing the action"
}
],
"consumeActions": [
{
"action": "[string]Type of action to be executed in the Consume Action",
"request": "[string]JSON string of the request used when executing the action"
}
],
"timingType": "[string enum]Type of exchange",
"lockTime": "[int]Waiting time (minutes) from the execution of the exchange until the reward is actually received",
"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"
}
]
}
],
"incrementalRateModels": [
{
"name": "[string]Incremental Cost Exchange Rate Model name",
"metadata": "[string?]Metadata",
"consumeAction": {
"action": "[string]Type of action to be executed in the Consume Action",
"request": "[string]JSON string of the request used when executing the action"
},
"calculateType": "[string enum]Calculation method for cost increase amount",
"baseValue": "[long]Base Value",
"coefficientValue": "[long]Coefficient Value",
"calculateScriptId": "[string]GRN of cost calculation script",
"exchangeCountId": "[string]GS2-Limit Usage Limit Model GRN for managing exchange execution counts",
"maximumExchangeCount": "[int]Maximum number of exchanges",
"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"
}
]
}
]
}| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| version | string | ✓ | 2019-08-19 | Format version of master data | ||
| rateModels | List<RateModel> | ~ 10000 items | Exchange Rate Model Exchange Rate Model is an entity that defines the rate used to exchange one resource for another. In addition to the rate at which a resource can be exchanged immediately, a rate can also be set at which a resource can be exchanged after a certain amount of time in real time has elapsed. Exchange rates that after a certain period of real time has elapsed can further define the resources required to perform an immediate exchange. | |||
| incrementalRateModels | List<IncrementalRateModel> | ~ 10000 items | Incremental Cost Exchange Rate Model Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange is performed at a rate of 1:1, but the second exchange is performed at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses. The number of exchanges can be reset after a certain period of real time has elapsed. This is useful for resetting the number of exchanges on a daily or weekly basis. |
Model
RateModel
Exchange Rate Model
Exchange Rate Model is an entity that defines the rate used to exchange one resource for another.
In addition to the rate at which a resource can be exchanged immediately, a rate can also be set at which a resource can be exchanged after a certain amount of time in real time has elapsed. Exchange rates that after a certain period of real time has elapsed can further define the resources required to perform an immediate exchange.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| rateModelId | string | * | ~ 1024 chars | Exchange Rate Model GRN * Set automatically by the server | ||||||||
| name | string | ✓ | ~ 128 chars | Exchange Rate Model name Exchange Rate 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. | |||||||||
| verifyActions | List<VerifyAction> | [] | 0 ~ 10 items | List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. | ||||||||
| consumeActions | List<ConsumeAction> | [] | 0 ~ 10 items | List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. | ||||||||
| timingType | String Enum enum { “immediate”, “await” } | “immediate” | Type of exchange Determines when rewards are delivered after performing the exchange. immediate delivers rewards instantly upon exchange execution. await requires real-time to elapse before rewards can be claimed, creating a waiting period (e.g., crafting time).
| |||||||||
| lockTime | int | {timingType} == “await” | ✓* | 0 ~ 538214400 | Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await. Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism.* Required if timingType is “await” | |||||||
| acquireActions | List<AcquireAction> | [] | 0 ~ 100 items | List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. |
AcquireAction
Acquire Action
ConsumeAction
Consume Action
VerifyAction
Verify Action
IncrementalRateModel
Incremental Cost Exchange Rate Model
Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange is performed at a rate of 1:1, but the second exchange is performed at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses.
The number of exchanges can be reset after a certain period of real time has elapsed. This is useful for resetting the number of exchanges on a daily or weekly basis.
| Type | Condition | Required | Default | Value Limits | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| incrementalRateModelId | string | * | ~ 1024 chars | Incremental Cost Exchange Rate Model GRN * Set automatically by the server | ||||||||||
| name | string | ✓ | ~ 128 chars | Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). | ||||||||||
| 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. | |||||||||||
| consumeAction | ConsumeAction | ✓ | Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. | |||||||||||
| calculateType | String Enum enum { “linear”, “power”, “gs2_script” } | ✓ | Calculation method for cost increase amount Determines how the exchange cost escalates with each exchange. linear calculates cost as baseValue + (coefficientValue * exchangeCount). power calculates cost as coefficientValue * (exchangeCount + 1)^2. gs2_script delegates the calculation to a custom GS2-Script for arbitrary logic.
| |||||||||||
| baseValue | long | {calculateType} == “linear” | ✓* | 0 ~ 9223372036854775805 | Base Value The initial cost for the first exchange when using the linear calculation type. The total cost is calculated as: baseValue + (coefficientValue * exchangeCount).* Required if calculateType is “linear” | |||||||||
| coefficientValue | long | {calculateType} in [“linear”, “power”] | ✓* | 0 ~ 9223372036854775805 | Coefficient Value The multiplier that controls how quickly costs escalate with each exchange. In linear mode, each exchange adds this value to the cost. In power mode, the cost is calculated as: coefficientValue * (exchangeCount + 1)^2.* Required if calculateType is “linear”,“power” | |||||||||
| calculateScriptId | string | {calculateType} == “gs2_script” | ✓* | ~ 1024 chars | GRN
of cost calculation script Script Trigger Reference - calculateCost* Required if calculateType is “gs2_script” | |||||||||
| exchangeCountId | string | ✓ | ~ 1024 chars | GS2-Limit Usage Limit Model GRN
for managing exchange execution counts References a GS2-Limit limit model that tracks how many times each user has performed this incremental exchange. The count is used to calculate the escalating cost and can be reset periodically (e.g., daily or weekly) using GS2-Limit’s reset timing. | ||||||||||
| maximumExchangeCount | int | 2147483646 | 0 ~ 2147483646 | Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. | ||||||||||
| acquireActions | List<AcquireAction> | [] | 0 ~ 100 items | List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange. |