GS2-Exchange Master Data Reference

Master Data Format

• JSON

{
  "version": "2019-08-19",
  "rateModels": [
    {
      "name": "[string]Exchange Rate Model name",
      "metadata": "[string?]Metadata",
      "verifyActions": [
        {
          "action": "[string]Type of Verify Action",
          "request": "[string]JSON string of the request used when executing the action"
        }
      ],
      "consumeActions": [
        {
          "action": "[string]Type of 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 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 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 Acquire Action",
          "request": "[string]JSON string of the request used when executing the action"
        }
      ]
    }
  ]
}

Models

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 require a certain period of real time to elapse can also define the resources required to perform an immediate exchange.

A single exchange rate is composed of verify actions, consume actions, and acquire actions. Verify actions are the precondition checks performed before the exchange runs; if even one of them fails, the exchange is aborted without consuming anything. Consume actions define the cost of the exchange and acquire actions define the rewards received from it. Up to 10 verify actions and 10 consume actions can be set, and up to 100 acquire actions.

timingType selects when the rewards are delivered. immediate delivers the rewards at the same time the exchange runs. await consumes the cost and then defers the acquisition of the rewards, which become claimable once the number of minutes specified in lockTime has elapsed. That waiting state is held as an Exchange Await, and the wait can be shortened by skipping.

lockTime applies only when timingType is await. Use await for mechanisms in which time itself is part of the cost, such as crafting or facility construction, and immediate for a permanent exchange such as selling an item or converting evolution materials.

For a rate whose price rises with each purchase, use IncrementalRateModel instead of this model.

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.

consumeAction defines the single cost consumed on an exchange, and the quantity it consumes is recalculated from the number of exchanges performed so far. calculateType selects how the cost rises: linear calculates it as baseValue + (coefficientValue x number of exchanges), and power as coefficientValue x (number of exchanges + 1)^2. Choosing gs2_script delegates the calculation to the GS2-Script specified by calculateScriptId, which lets arbitrary logic decide the cost.

The number of exchanges is tracked by the GS2-Limit counter model referenced from exchangeCountId. Because it is a GS2-Limit counter, the reset timing configured there is what resets the cost back to its initial value, which is how a daily or weekly reset is realized.

maximumExchangeCount sets the maximum number of exchanges a user can perform. Once the count reaches this limit, further exchanges are refused until the GS2-Limit counter is reset.

acquireActions defines the rewards received from the exchange, and up to 100 of them can be set. Unlike RateModel, this model has no verify actions and no waiting time; the rewards are always delivered immediately.