GS2-Exchange マスターデータリファレンス

マスターデータのフォーマット

• JSON

{
  "version": "2019-08-19",
  "rateModels": [
    {
      "name": "[string]交換レートモデル名",
      "metadata": "[string?]メタデータ",
      "verifyActions": [
        {
          "action": "[string]検証アクションで実行するアクションの種類",
          "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
      ],
      "consumeActions": [
        {
          "action": "[string]消費アクションで実行するアクションの種類",
          "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
      ],
      "timingType": "[文字列列挙型]交換の種類",
      "lockTime": "[int]交換実行から実際に報酬を受け取れるようになるまでの待ち時間（分）",
      "acquireActions": [
        {
          "action": "[string]入手アクションで実行するアクションの種類",
          "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
      ]
    }
  ],
  "incrementalRateModels": [
    {
      "name": "[string]コスト上昇型交換レートモデルの名前",
      "metadata": "[string?]メタデータ",
      "consumeAction": {
        "action": "[string]消費アクションで実行するアクションの種類",
        "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
      },
      "calculateType": "[文字列列挙型]コスト上昇量の計算方式",
      "baseValue": "[long]ベース値",
      "coefficientValue": "[long]係数",
      "calculateScriptId": "[string]コスト計算スクリプトのGRN",
      "exchangeCountId": "[string]交換実行回数を管理する GS2-Limit の回数制限モデル GRN",
      "maximumExchangeCount": "[int]交換回数の上限",
      "acquireActions": [
        {
          "action": "[string]入手アクションで実行するアクションの種類",
          "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
        }
      ]
    }
  ]
}

モデル

RateModel

交換レートモデル

交換レートモデルはリソースとリソースを交換する際に使用するレートを定義するエンティティです。

直ちに交換できるレートだけでなく、現実時間で一定時間経過したのちに交換できるレートを設定できます。
現実時間での時間経過が必要な交換レートには、更に即時交換を実行するために必要なリソースを定義することが可能です。

1つの交換レートは、検証アクション・消費アクション・入手アクションで構成されます。
検証アクションは交換を実行する前の事前条件チェックで、1つでも失敗すると何も消費せずに交換が中止されます。
消費アクションには交換の対価を、入手アクションには交換で受け取る報酬を定義します。
検証アクションと消費アクションはそれぞれ最大10件、入手アクションは最大100件まで設定できます。

timingType で報酬を配送するタイミングを選択します。
immediate は交換の実行と同時に報酬を配送します。
await は対価を消費したうえで報酬の入手を先送りし、lockTime に指定した分数が経過してから受け取れるようになります。この待機状態は交換待機として保持され、スキップによって待ち時間を短縮できます。

lockTime は timingType が await の場合にのみ適用されます。
クラフトや施設の建設のように時間そのものを対価に含める仕組みには await を、アイテムの売却や進化素材の変換のように常設の交換には immediate を使用します。

購入するたびに価格が上がるレートを実現する場合は、このモデルではなくコスト上昇型交換レートモデル (IncrementalRateModel) を使用します。

AcquireAction

入手アクション

ConsumeAction

消費アクション

VerifyAction

検証アクション

IncrementalRateModel

コスト上昇型交換レートモデル

通常の交換レートは常に一定のレートでの交換を提供します。
上昇型交換レートでは、交換回数に応じてコストが上昇していくレートを定義することができます。
例えば、1回目の交換では 1:1 で交換できるが、2回目の交換では 2:1 で交換できる、といったレートを定義することができます。
このようなレートを定義することで、プレイヤーがゲームを進めることで得られるリソースの価値を上げることができます。

交換回数は現実時間の経過でリセットすることができます。
この機能を利用することで、毎日あるいは毎週交換に必要なコストをリセットすることができます。

consumeAction には交換で消費する対価を1つ定義し、その消費数量がそれまでの交換回数に応じて再計算されます。
コストの上昇のしかたは calculateType で選択します。linear は baseValue +（coefficientValue × 交換回数）、power は coefficientValue ×（交換回数 + 1）^2 として計算します。
gs2_script を選ぶと calculateScriptId に指定した GS2-Script に計算を委譲するため、任意のロジックでコストを決定できます。

交換回数は exchangeCountId で参照する GS2-Limit の回数制限モデルによって管理されます。
GS2-Limit のカウンターであるため、コストを初期値に戻すのはそこで設定したリセットタイミングです。これによって毎日あるいは毎週のリセットを実現します。

maximumExchangeCount にはユーザーが交換を実行できる最大回数を設定します。
交換回数がこの上限に達すると、GS2-Limit のカウンターがリセットされるまで以降の交換は拒否されます。

acquireActions には交換で受け取る報酬を定義し、最大100件まで設定できます。
交換レートモデル (RateModel) とは異なり、このモデルには検証アクションと待機時間がなく、報酬は常に即時に配送されます。