> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Exchange マスターデータリファレンス
マスターデータのフォーマットと インポートする各種モデルのリファレンス
## マスターデータのフォーマット
**JSON**
```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文字列"
}
]
}
]
}
```
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2019-08-19 | | マスターデータのフォーマットバージョン |
| rateModels | [List<RateModel>](#ratemodel) | | | | ~ 10000 items | 交換レートモデル
交換レートモデルはリソースとリソースを交換する際に使用するレートを定義するエンティティです。
直ちに交換できるレートだけでなく、現実時間で一定時間経過したのちに交換できるレートを設定できます。
現実時間での時間経過が必要な交換レートには、更に即時交換を実行するために必要なリソースを定義することが可能です。
1つの交換レートは、検証アクション・消費アクション・入手アクションで構成されます。
検証アクションは交換を実行する前の事前条件チェックで、1つでも失敗すると何も消費せずに交換が中止されます。
消費アクションには交換の対価を、入手アクションには交換で受け取る報酬を定義します。
検証アクションと消費アクションはそれぞれ最大10件、入手アクションは最大100件まで設定できます。
`timingType` で報酬を配送するタイミングを選択します。
`immediate` は交換の実行と同時に報酬を配送します。
`await` は対価を消費したうえで報酬の入手を先送りし、`lockTime` に指定した分数が経過してから受け取れるようになります。この待機状態は交換待機として保持され、スキップによって待ち時間を短縮できます。
`lockTime` は `timingType` が `await` の場合にのみ適用されます。
クラフトや施設の建設のように時間そのものを対価に含める仕組みには `await` を、アイテムの売却や進化素材の変換のように常設の交換には `immediate` を使用します。
購入するたびに価格が上がるレートを実現する場合は、このモデルではなくコスト上昇型交換レートモデル (IncrementalRateModel) を使用します。 |
| incrementalRateModels | [List<IncrementalRateModel>](#incrementalratemodel) | | | | ~ 10000 items | コスト上昇型交換レートモデル
通常の交換レートは常に一定のレートでの交換を提供します。
上昇型交換レートでは、交換回数に応じてコストが上昇していくレートを定義することができます。
例えば、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) とは異なり、このモデルには検証アクションと待機時間がなく、報酬は常に即時に配送されます。 |
## モデル
### RateModel
交換レートモデル
交換レートモデルはリソースとリソースを交換する際に使用するレートを定義するエンティティです。
直ちに交換できるレートだけでなく、現実時間で一定時間経過したのちに交換できるレートを設定できます。
現実時間での時間経過が必要な交換レートには、更に即時交換を実行するために必要なリソースを定義することが可能です。
1つの交換レートは、検証アクション・消費アクション・入手アクションで構成されます。
検証アクションは交換を実行する前の事前条件チェックで、1つでも失敗すると何も消費せずに交換が中止されます。
消費アクションには交換の対価を、入手アクションには交換で受け取る報酬を定義します。
検証アクションと消費アクションはそれぞれ最大10件、入手アクションは最大100件まで設定できます。
`timingType` で報酬を配送するタイミングを選択します。
`immediate` は交換の実行と同時に報酬を配送します。
`await` は対価を消費したうえで報酬の入手を先送りし、`lockTime` に指定した分数が経過してから受け取れるようになります。この待機状態は交換待機として保持され、スキップによって待ち時間を短縮できます。
`lockTime` は `timingType` が `await` の場合にのみ適用されます。
クラフトや施設の建設のように時間そのものを対価に含める仕組みには `await` を、アイテムの売却や進化素材の変換のように常設の交換には `immediate` を使用します。
購入するたびに価格が上がるレートを実現する場合は、このモデルではなくコスト上昇型交換レートモデル (IncrementalRateModel) を使用します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rateModelId | string | | ※ | | ~ 1024文字 | 交換レートモデルGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | 交換レートモデル名
交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 2048文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| verifyActions | [List<VerifyAction>](#verifyaction) | | | [] | 0 ~ 10 items | 検証アクションリスト
交換が実行される前にすべてパスする必要がある事前条件チェックです。いずれかの検証アクションが失敗すると、リソースを消費せずに交換が中止されます。レベル要件やインベントリ容量などの条件を強制するために使用されます。 |
| consumeActions | [List<ConsumeAction>](#consumeaction) | | | [] | 0 ~ 10 items | 消費アクションリスト
この交換を実行するためにプレイヤーが支払う必要があるリソース（コスト）を定義します。複数の消費アクションを指定でき、ゴールドとアイテムの両方を必要とするような複雑な交換コストを実現できます。これらのアクションは分散トランザクション内の消費アクションとして実行されます。 |
| timingType | 文字列列挙型
enum {
"immediate",
"await"
}
| | | "immediate" | | 交換の種類
交換実行後に報酬がいつ配送されるかを決定します。`immediate` は交換実行時に即座に報酬を配送します。`await` は報酬を受け取る前に実時間の経過が必要で、待機期間（例: クラフト時間）を設けます。immediate: 即時 / await: 現実時間の経過待ち / |
| lockTime | int | {timingType} == "await" | ✓※ | | 0 ~ 538214400 | 交換実行から実際に報酬を受け取れるようになるまでの待ち時間（分）
timingType が `await` の場合にのみ適用されます。交換が開始されてからプレイヤーが報酬を受け取れるようになるまでに経過する必要がある実時間の分数を指定します。待ち時間はスキップ機能を使用して短縮できます。
※ timingType が "await" であれば 必須 |
| acquireActions | [List<AcquireAction>](#acquireaction) | | | [] | 0 ~ 100 items | 入手アクションリスト
交換完了時にプレイヤーが受け取るリソース（報酬）を定義します。複数の入手アクションを指定して、さまざまなリソースタイプを同時に付与できます。これらのアクションは分散トランザクション内の入手アクションとして実行されます。 |
---
### AcquireAction
入手アクション
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 入手アクションで実行するアクションの種類 |
| request | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
---
### ConsumeAction
消費アクション
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 消費アクションで実行するアクションの種類 |
| request | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
---
### VerifyAction
検証アクション
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 検証アクションで実行するアクションの種類 |
| request | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
---
### 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) とは異なり、このモデルには検証アクションと待機時間がなく、報酬は常に即時に配送されます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| incrementalRateModelId | string | | ※ | | ~ 1024文字 | コスト上昇型交換レートモデルGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | コスト上昇型交換レートモデルの名前
コスト上昇型交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 2048文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| consumeAction | [ConsumeAction](#consumeaction) | | ✓ | | | 消費アクション（数量/値は自動的に上書きされます）
交換のコストとして消費されるリソースの種類を定義します。実際の数量は交換回数と計算方式（線形、べき乗、スクリプト）に基づいて動的に計算されます。アクションの種類と対象リソースのみ指定すればよく、数量フィールドは自動的に上書きされます。 |
| calculateType | 文字列列挙型
enum {
"linear",
"power",
"gs2_script"
}
| | ✓ | | | コスト上昇量の計算方式
交換回数に応じてコストがどのように上昇するかを決定します。`linear` はコストを baseValue +（coefficientValue × 交換回数）として計算します。`power` はコストを coefficientValue ×（交換回数 + 1）^2 として計算します。`gs2_script` は任意のロジックのためにカスタム GS2-Script に計算を委任します。linear: ベース値 + (係数 * 交換回数) / power: 係数 * (交換回数 + 1) ^ 2 / gs2_script: GS2-Script による任意のロジック / |
| baseValue | long | {calculateType} == "linear" | ✓※ | | 0 ~ 9223372036854775805 | ベース値
`linear` 計算方式を使用する場合の初回交換時の基本コストです。合計コストは baseValue +（coefficientValue × 交換回数）として計算されます。
※ calculateType が "linear" であれば 必須 |
| coefficientValue | long | {calculateType} in ["linear", "power"] | ✓※ | | 0 ~ 9223372036854775805 | 係数
交換回数に応じてコストがどれだけ速く上昇するかを制御する乗数です。`linear` モードでは、各交換でこの値がコストに加算されます。`power` モードでは、コストは coefficientValue ×（交換回数 + 1）^2 として計算されます。
※ calculateType が "linear","power"であれば 必須 |
| calculateScriptId | string | {calculateType} == "gs2_script" | ✓※ | | ~ 1024文字 | コスト計算スクリプトのGRN
Script トリガーリファレンス - [`calculateCost`](../script/#calculatecost)
※ calculateType が "gs2_script" であれば 必須 |
| exchangeCountId | string | | ✓ | | ~ 1024文字 | 交換実行回数を管理する GS2-Limit の回数制限モデル GRN
各ユーザーがこのコスト上昇型交換を何回実行したかを追跡する GS2-Limit の回数制限モデルを参照します。カウントは上昇するコストの計算に使用され、GS2-Limit のリセットタイミングを使用して定期的（例: 毎日または毎週）にリセットできます。 |
| maximumExchangeCount | int | | | 2147483646 | 0 ~ 2147483646 | 交換回数の上限
ユーザーがこのコスト上昇型交換を実行できる最大回数です。交換回数がこの上限に達すると、GS2-Limit によるカウントリセットまでそれ以降の交換が拒否されます。 |
| acquireActions | [List<AcquireAction>](#acquireaction) | | | [] | 0 ~ 100 items | 入手アクションリスト
コスト上昇型交換の完了時にプレイヤーが受け取るリソース（報酬）を定義します。報酬は交換回数に関わらず一定で、コストのみが交換ごとに増加します。 |
---