> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Lottery マスターデータリファレンス
マスターデータのフォーマットと インポートする各種モデルのリファレンス
## マスターデータのフォーマット
**JSON**
```json
{
"version": "2019-02-21",
"lotteryModels": [
{
"name": "[string]抽選モデル名",
"metadata": "[string?]メタデータ",
"mode": "[string (enum)]抽選モード",
"method": "[string (enum)]抽選方法",
"prizeTableName": "[string]排出確率テーブルの名前",
"choicePrizeTableScriptId": "[string]排出確率テーブルを決定する GS2-Script のスクリプトGRN"
}
],
"prizeTables": [
{
"name": "[string]排出確率テーブル名",
"metadata": "[string?]メタデータ",
"prizes": [
{
"prizeId": "[string]景品ID",
"type": "[string]景品の種類",
"acquireActions": [
{
"action": "[string]入手アクションで実行するアクションの種類",
"request": "[string]アクション実行時に使用されるリクエストのJSON文字列"
}
],
"drawnLimit": "[int?]最大排出数",
"limitFailOverPrizeId": "[string]制限時フェイルオーバー景品ID",
"prizeTableName": "[string]排出確率テーブルの名前",
"weight": "[int]排出重み"
}
]
}
]
}
```
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2019-02-21 | | マスターデータのフォーマットバージョン |
| lotteryModels | [List<LotteryModel>](#lotterymodel) | | | | ~ 100 items | 抽選モデル
抽選モデルは排出方式や排出テーブルの参照方法を定義するエンティティです。
排出方式は2種類用意されており、通常抽選は毎回一定の確率で抽選をする方式、Box抽選は箱の中にあらかじめ定義された数量の景品が入っており、抽選するたびに箱から景品を取り出していく抽選方式です。
抽選処理を行うにあたって、排出確率テーブルを利用しますが、
GS2-Script を使用すれば複数回抽選を実行した際に排出確率テーブルを一部だけ異なるテーブルに差し替えることができます。
この仕組みを利用することで、10連ガチャで1回だけ異なる抽選確率テーブルを適用することが可能となります。 |
| prizeTables | [List<PrizeTable>](#prizetable) | | | | ~ 100 items | 排出確率テーブル
景品には、入手アクションを指定するか、別の排出確率テーブルを参照させることもできます。
排出確率テーブルを入れ子にすることで、たとえば 1段目で SSR / SR / R などのレアリティを抽選し、2段目でそのレアリティに対応した具体的なコンテンツを抽選するといった設定が可能です。
この仕組みにより、ゲーム全体としてのレアリティ別排出確率を調整しやすくなります。 |
## モデル
### PrizeTable
排出確率テーブル
景品には、入手アクションを指定するか、別の排出確率テーブルを参照させることもできます。
排出確率テーブルを入れ子にすることで、たとえば 1段目で SSR / SR / R などのレアリティを抽選し、2段目でそのレアリティに対応した具体的なコンテンツを抽選するといった設定が可能です。
この仕組みにより、ゲーム全体としてのレアリティ別排出確率を調整しやすくなります。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| prizeTableId | string | | ※ | | ~ 1024文字 | 排出確率テーブルGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | 排出確率テーブル名
排出確率テーブル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 128文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| prizes | [List<Prize>](#prize) | | ✓ | | 1 ~ 100 items | 景品リスト
この排出確率テーブル内の景品リストです。各景品は排出重み（確率）、排出時に実行するアクション、およびオプションの排出回数制限を定義します。各景品の実際の排出確率は、その重みをテーブル内の全景品の重みの合計で割って算出されます。 |
---
### Prize
景品
排出確率テーブル内の単一の景品エントリです。
景品は入手アクション（アイテムや通貨の付与など）を直接指定するか、別の排出確率テーブルを参照してネストされた抽選を行えます。
各景品には排出重みがあり、排出される相対的な確率を決定します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| prizeId | string | | ✓ | UUID | ~ 36文字 | 景品ID
排出確率テーブル内でこの景品を一意に識別するIDです。排出回数制限の追跡や、フェイルオーバー景品の指定時の参照に使用されます。 |
| type | 文字列列挙型
enum {
"action",
"prize_table"
}
| | ✓ | | | 景品の種類
この景品が直接報酬を付与するか、別の排出確率テーブルに委譲するかを決定します。"action" は排出時に実行する入手アクションを指定します。"prize_table" は別の排出確率テーブルを参照してネストされた抽選を行います（例：1段目でレアリティを決定、2段目で具体的なアイテムを決定）。"action": 景品の入手アクション / "prize_table": 更に排出確率テーブルを指定して再抽選 / |
| acquireActions | [List<AcquireAction>](#acquireaction) | {type} == "action" | | [] | 1 ~ 100 items | 入手アクションリスト
この景品が排出された時に実行する入手アクションのリストです。複数のアクションを指定して、一度に複数の報酬を付与できます（例：アイテムと通貨を同時に付与）。
※ type が "action" であれば 有効 |
| drawnLimit | int | {type} == "action" | | | 1 ~ 1000000 | 最大排出数
この景品が全ユーザーを通じて排出される最大回数です。制限に達すると、代わりにフェイルオーバー景品（limitFailOverPrizeId）が排出されます。ジャックポットアイテムなどの数量限定景品の実装に使用されます。
※ type が "action" であれば 有効 |
| limitFailOverPrizeId | string | {type} == "action" and {drawnLimit} > 0 | ✓※ | | ~ 32文字 | 制限時フェイルオーバー景品ID
この景品の排出回数制限（drawnLimit）に達した場合に代わりに排出する景品のIDです。同じ排出確率テーブル内の別の景品を参照する必要があります。
※ type が "action" で かつ drawnLimit が 0 より大きければ 必須 |
| prizeTableName | string | {type} == "prize_table" | ✓※ | | ~ 128文字 | 排出確率テーブルの名前
抽選を委譲する排出確率テーブルの名前です。景品タイプが "prize_table" の場合にネストされた抽選に使用されます。
※ type が "prize_table" であれば 必須 |
| weight | int | | ✓ | | 1 ~ 2147483646 | 排出重み
排出確率テーブル内でのこの景品の相対的な重みです。実際の排出確率は、この景品の重みをテーブル内の全景品の重みの合計で割って算出されます。例えば3つの景品の重みが70、20、10の場合、それぞれの排出確率は70%、20%、10%になります。 |
---
### AcquireAction
入手アクション
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 入手アクションで実行するアクションの種類 |
| request | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
---
### LotteryModel
抽選モデル
抽選モデルは排出方式や排出テーブルの参照方法を定義するエンティティです。
排出方式は2種類用意されており、通常抽選は毎回一定の確率で抽選をする方式、Box抽選は箱の中にあらかじめ定義された数量の景品が入っており、抽選するたびに箱から景品を取り出していく抽選方式です。
抽選処理を行うにあたって、排出確率テーブルを利用しますが、
GS2-Script を使用すれば複数回抽選を実行した際に排出確率テーブルを一部だけ異なるテーブルに差し替えることができます。
この仕組みを利用することで、10連ガチャで1回だけ異なる抽選確率テーブルを適用することが可能となります。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| lotteryModelId | string | | ※ | | ~ 1024文字 | 抽選モデルGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | 抽選モデル名
抽選モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 2048文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| mode | 文字列列挙型
enum {
"normal",
"box"
}
| | ✓ | | | 抽選モード
景品の抽選方式を選択します。"normal" は毎回一定の確率で抽選を行います（景品は繰り返し排出されます）。"box" は仮想的な箱にあらかじめ定義された数量の景品を入れ、抽選するたびに箱から景品を取り出します（すべての景品が最終的に排出されることが保証されます）。"normal": 通常抽選 / "box": ボックス抽選 / |
| method | 文字列列挙型
enum {
"prize_table",
"script"
}
| | ✓ | | | 抽選方法
排出確率テーブルの参照方法を決定します。"prize_table" は静的に指定された排出確率テーブルを使用します。"script" はGS2-Scriptを使用して抽選時に動的に排出確率テーブルを選択し、10連ガチャで1回だけ異なる排出確率テーブルを適用するなどのシナリオを実現できます。"prize_table": 静的な排出確率テーブル / "script": GS2-Script による動的な排出確率テーブル / |
| prizeTableName | string | {method} == "prize_table" | ✓※ | | ~ 128文字 | 排出確率テーブルの名前
この抽選モデルで使用する排出確率テーブルの名前です。抽選方法が "prize_table" の場合に必須です。
※ method が "prize_table" であれば 必須 |
| choicePrizeTableScriptId | string | {method} == "script" | ✓※ | | ~ 1024文字 | 排出確率テーブルを決定する GS2-Script のスクリプトGRN
Script トリガーリファレンス - [`choicePrizeTable`](../script/#choiceprizetable)
※ method が "script" であれば 必須 |
---