> For the complete documentation index, see [llms.txt](/llms.txt)

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

マスターデータのフォーマットと インポートする各種モデルのリファレンス




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


**JSON**
```json
{
  "version": "2019-04-04",
  "showcases": [
    {
      "name": "[string]陳列棚名",
      "metadata": "[string?]メタデータ",
      "salesPeriodEventId": "[string?]陳列棚の販売期間を設定した GS2-Schedule のイベントGRN",
      "displayItems": [
        {
          "displayItemId": "[string]陳列商品ID",
          "type": "[string]種類",
          "salesItem": {
            "name": "[string]商品名",
            "metadata": "[string?]メタデータ",
            "verifyActions": [
              {
                "action": "[string]検証アクションで実行するアクションの種類",
                "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
              }
            ],
            "consumeActions": [
              {
                "action": "[string]消費アクションで実行するアクションの種類",
                "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
              }
            ],
            "acquireActions": [
              {
                "action": "[string]入手アクションで実行するアクションの種類",
                "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
              }
            ]
          },
          "salesItemGroup": {
            "name": "[string]商品グループ名",
            "metadata": "[string?]メタデータ",
            "salesItems": [
              {
                "name": "[string]商品名",
                "metadata": "[string?]メタデータ",
                "verifyActions": [
                  {
                    "action": "[string]検証アクションで実行するアクションの種類",
                    "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
                  }
                ],
                "consumeActions": [
                  {
                    "action": "[string]消費アクションで実行するアクションの種類",
                    "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
                  }
                ],
                "acquireActions": [
                  {
                    "action": "[string]入手アクションで実行するアクションの種類",
                    "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
                  }
                ]
              }
            ]
          },
          "salesPeriodEventId": "[string?]この陳列商品の販売期間を設定した GS2-Schedule のイベントGRN"
        }
      ]
    }
  ],
  "randomShowcases": [
    {
      "name": "[string]ランダム陳列棚名",
      "metadata": "[string?]メタデータ",
      "maximumNumberOfChoice": "[int]選出される商品の最大数",
      "displayItems": [
        {
          "name": "[string]ランダム陳列商品ID",
          "metadata": "[string?]メタデータ",
          "verifyActions": [
            {
              "action": "[string]検証アクションで実行するアクションの種類",
              "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
            }
          ],
          "consumeActions": [
            {
              "action": "[string]消費アクションで実行するアクションの種類",
              "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
            }
          ],
          "acquireActions": [
            {
              "action": "[string]入手アクションで実行するアクションの種類",
              "request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
            }
          ],
          "stock": "[int]在庫数",
          "weight": "[int]排出重み"
        }
      ],
      "baseTimestamp": "[long]陳列する商品を再抽選の基準時間",
      "resetIntervalHours": "[int]陳列する商品を再抽選する間隔（時）",
      "salesPeriodEventId": "[string?]陳列棚の販売期間を設定した GS2-Schedule のイベントGRN"
    }
  ]
}
```


|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2019-04-04 | | マスターデータのフォーマットバージョン |
| showcases | [List&lt;Showcase&gt;](#showcase) |  |  |  |  ~ 100 items | 陳列棚<br>`陳列棚`には陳列する商品を定義できます。<br>また、`陳列棚`の商品の販売期間を設定することができます。 |
| randomShowcases | [List&lt;RandomShowcase&gt;](#randomshowcase) |  |  |  |  ~ 100 items | ランダム陳列棚<br>ランダム陳列棚は、指定した周期で入れ替わるランダムに選別された商品が陳列される陳列棚のモデルです。<br><br>選別される商品は、商品プールに登録された商品から指定数量が、商品ごとに設定された重みに基づいてランダムに選択されます。<br>ランダム陳列棚には GS2-Schedule のイベントを関連づけることで、販売期間を設定することができます。 |

## モデル

### Showcase

陳列棚<br>

`陳列棚`には陳列する商品を定義できます。<br>
また、`陳列棚`の商品の販売期間を設定することができます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| showcaseId | string |  | ※ |  |  ~ 1024文字 | 陳列棚GRN<br>※ サーバーが自動で設定 |
| name | string |  | ✓ |  |  ~ 128文字 | 陳列棚名<br>陳列棚固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| salesPeriodEventId | string |  |  |  |  ~ 1024文字 | 陳列棚の販売期間を設定した GS2-Schedule のイベントGRN<br>この陳列棚全体の販売期間を制御します。指定した場合、関連する GS2-Schedule のイベント期間中のみ陳列棚が利用可能になります。イベントが有効でない場合、陳列棚は空で返されます。 |
| displayItems | [List&lt;DisplayItem&gt;](#displayitem) |  |  | [] | 1 ~ 1000 items | 陳列する商品リスト<br>この陳列棚に陳列される商品のリストです。各陳列商品は単一の商品または商品グループのいずれかです。販売期間イベントが終了または無効な商品は、陳列棚の取得時に自動的にフィルタリングされます。 |

---

### DisplayItem

陳列する商品<br>

陳列棚に表示される商品です。単一の商品または商品グループのいずれかを参照できます。各陳列商品には、陳列棚全体の販売期間とは独立して GS2-Schedule イベントによる個別の販売期間を設定できます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| displayItemId | string |  | ✓ | UUID |  ~ 128文字 | 陳列商品ID<br>陳列商品の一意な名前を保持します。<br>省略するとシステムによって UUID（Universally Unique Identifier）フォーマットで自動的に割り当てられます。 |
| type | 文字列列挙型<br>enum {<br>&nbsp;&nbsp;"salesItem",<br>&nbsp;&nbsp;"salesItemGroup"<br>}<br> |  | ✓ |  |  | 種類<br>表示する商品の種類です。「salesItem」は固定の対価と報酬を持つ単一商品です。「salesItemGroup」は複数の商品を順番に評価する商品グループで、ステップアップ価格や初回限定割引などに使用されます。"salesItem": 商品 / "salesItemGroup": 商品グループ /  |
| salesItem | [SalesItem](#salesitem) | {type} == "salesItem" | ✓※ |  |  | 商品<br>※ type が "salesItem" であれば 必須 |
| salesItemGroup | [SalesItemGroup](#salesitemgroup) | {type} == "salesItemGroup" | ✓※ |  |  | 商品グループ<br>※ type が "salesItemGroup" であれば 必須 |
| salesPeriodEventId | string |  |  |  |  ~ 1024文字 | この陳列商品の販売期間を設定した GS2-Schedule のイベントGRN<br>この個別の陳列商品の販売期間を制御します。指定した場合、関連する GS2-Schedule のイベント期間中のみ陳列棚に表示されます。陳列棚全体の販売期間とは独立して動作します。 |

---

### SalesItem

商品<br>

商品を購入するために必要となる対価と、商品を購入したときに得られる報酬を設定します。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | 商品名<br>商品固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| verifyActions | [List&lt;VerifyAction&gt;](#verifyaction) |  |  | [] | 0 ~ 10 items | 検証アクションリスト<br>購入前に実行される前提条件チェックです。すべての検証アクションが成功した後に消費・入手アクションが処理されます。購入資格の条件チェックに使用できます。 |
| consumeActions | [List&lt;ConsumeAction&gt;](#consumeaction) |  |  | [] | 0 ~ 10 items | 消費アクションリスト<br>購入対価としてリソースを消費するアクションです。商品グループの購入回数制御のために GS2-Limit の CountUp アクションを含めることができます。 |
| acquireActions | [List&lt;AcquireAction&gt;](#acquireaction) |  |  | [] | 1 ~ 100 items | 入手アクションリスト<br>購入報酬としてリソースを付与するアクションです。すべての消費アクションが正常に完了した後に実行されます。 |

---

### SalesItemGroup

商品グループ<br>

商品グループは陳列棚に陳列するためのエンティティです。<br>
商品グループには複数の商品を所属させることができ、所属している商品の先頭から順番に購入可能かを判定し、一番最初に購入可能だと判定された商品が実際に陳列されます。<br>
初回のみ割引する商品や、ステップアップガチャのように購入回数によって商品の内容が変化する仕組みに使用できます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | 商品グループ名<br>商品グループ固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| salesItems | [List&lt;SalesItem&gt;](#salesitem) |  |  | [] | 2 ~ 10 items | 商品グループに含める商品<br>このグループ内の商品の順序付きリストです。GS2-Limit カウンターを使って先頭から順に購入可能かを判定し、最初に購入可能と判定された商品が表示されます。いずれも該当しない場合、リストの最後の商品がフォールバックとして使用されます。 |

---

### ConsumeAction

消費アクション

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 消費アクションで実行するアクションの種類 |
| request | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |

---

### VerifyAction

検証アクション

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 検証アクションで実行するアクションの種類 |
| request | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |

---

### AcquireAction

入手アクション

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 入手アクションで実行するアクションの種類 |
| request | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |

---

### RandomShowcase

ランダム陳列棚<br>

ランダム陳列棚は、指定した周期で入れ替わるランダムに選別された商品が陳列される陳列棚のモデルです。<br>

選別される商品は、商品プールに登録された商品から指定数量が、商品ごとに設定された重みに基づいてランダムに選択されます。<br>
ランダム陳列棚には GS2-Schedule のイベントを関連づけることで、販売期間を設定することができます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| randomShowcaseId | string |  | ※ |  |  ~ 1024文字 | ランダム陳列棚GRN<br>※ サーバーが自動で設定 |
| name | string |  | ✓ |  |  ~ 128文字 | ランダム陳列棚名<br>ランダム陳列棚固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| maximumNumberOfChoice | int |  | ✓ |  | 1 ~ 100 | 選出される商品の最大数<br>各ローテーション期間に商品プールからランダムに抽選される商品の数です。重み付きランダム選択で重複なく抽選されるため、1回のローテーションで同じ商品が2回表示されることはありません。 |
| displayItems | [List&lt;RandomDisplayItemModel&gt;](#randomdisplayitemmodel) |  |  | [] | 1 ~ 100 items | 選出対象の陳列商品リスト<br>商品がランダムに抽選される候補アイテムのプールです。各アイテムには選択確率を決定する重みと、ローテーション全体で表示可能な回数を制限する在庫数があります。 |
| baseTimestamp | long |  | ✓ |  |  | 陳列する商品を再抽選の基準時間<br>ローテーション境界の計算に使用される基準タイムスタンプです。この基準時間から一定間隔（resetIntervalHours）ごとに商品の再抽選が行われます。過去の時刻を指定する必要があります。 |
| resetIntervalHours | int |  | ✓ |  | 1 ~ 168 | 陳列する商品を再抽選する間隔（時）<br>各商品ローテーション間の時間数です。baseTimestamp を基準として間隔が経過すると、新しい乱数シードで陳列商品が再抽選されます。1〜168時間（1週間）の範囲で設定できます。 |
| salesPeriodEventId | string |  |  |  |  ~ 1024文字 | 陳列棚の販売期間を設定した GS2-Schedule のイベントGRN<br>このランダム陳列棚全体の販売期間を制御します。指定した場合、関連する GS2-Schedule のイベント期間中のみ陳列棚が利用可能になります。 |

---

### RandomDisplayItemModel

ランダム陳列棚に陳列可能な商品<br>

`weight` に商品を選別する確率を設定できます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ | UUID |  ~ 128文字 | ランダム陳列商品ID<br>ランダム陳列商品の一意な名前を保持します。<br>省略するとシステムによって UUID（Universally Unique Identifier）フォーマットで自動的に割り当てられます。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| verifyActions | [List&lt;VerifyAction&gt;](#verifyaction) |  |  | [] | 0 ~ 10 items | 検証アクションリスト<br>このランダム陳列商品を購入する前に実行される前提条件チェックです。すべての検証アクションが成功した後に消費・入手アクションが処理されます。 |
| consumeActions | [List&lt;ConsumeAction&gt;](#consumeaction) |  |  | [] | 0 ~ 10 items | 消費アクションリスト<br>このランダム陳列商品の購入対価としてリソースを消費するアクションです。トランザクションの消費アクションとして実行されます。 |
| acquireActions | [List&lt;AcquireAction&gt;](#acquireaction) |  |  | [] | 1 ~ 100 items | 入手アクションリスト<br>このランダム陳列商品の購入報酬としてリソースを付与するアクションです。トランザクションの入手アクションとして実行されます。 |
| stock | int |  | ✓ |  | 1 ~ 2147483646 | 在庫数<br>すべてのローテーションを通じてこの商品が抽選される最大回数です。在庫がゼロになると、以降の抽選から除外されます。ローテーション抽選時に商品が選択されると在庫が消費されます。 |
| weight | int |  | ✓ |  | 1 ~ 2147483646 | 排出重み<br>ランダム選択におけるこの商品の相対的な確率の重みです。重みが大きいほど抽選される確率が高くなります。実際の選択確率は、この商品の重みを対象となるすべての商品の重みの合計で割った値として計算されます。 |

---