Master Data Reference of GS2-Lottery
Master Data Format
{
"version": "2019-02-21",
"lotteryModels": [
{
"name": "[string]Lottery Model name",
"metadata": "[string?]Metadata",
"mode": "[string enum]Drawing mode",
"method": "[string enum]Lottery Method",
"prizeTableName": "[string]Name of prize table",
"choicePrizeTableScriptId": "[string]GS2-Script script GRN to determine the emission probability table"
}
],
"prizeTables": [
{
"name": "[string]Prize Table Name",
"metadata": "[string?]Metadata",
"prizes": [
{
"prizeId": "[string]Prize ID",
"type": "[string]Type of prize",
"acquireActions": [
{
"action": "[string]Types of actions to be performed in the acquire action",
"request": "[string]JSON string of the request used when executing the action"
}
],
"drawnLimit": "[int?]Maximum number of draws",
"limitFailOverPrizeId": "[string]Prize ID to be discharged instead when the maximum number of drawn has been reached.",
"prizeTableName": "[string]Name of prize table",
"weight": "[int]Emission Weight"
}
]
}
]
}| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| version | string | ✓ | 2019-02-21 | Format version of master data | ||
| lotteryModels | List<LotteryModel> | ~ 100 items | Lottery Model The Lottery model is an entity that defines the draw method and how to reference the draw table. Two draw methods are available: Standard Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw. The lottery process uses a prize table. GS2-Script can be used to replace a part of the prize table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different prize table only once in a 10-round gacha. | |||
| prizeTables | List<PrizeTable> | ~ 100 items | Prize Table A prize can either specify an acquire action directly or reference another probability table. By nesting probability tables, you can configure a two-step drawing process—for example, the first step determines the rarity such as SSR, SR, or R, and the second step selects a specific item corresponding to that rarity. This structure makes it easier to manage and adjust the overall distribution rates for each rarity in the game. |
Model
PrizeTable
Prize Table
A prize can either specify an acquire action directly or reference another probability table. By nesting probability tables, you can configure a two-step drawing process—for example, the first step determines the rarity such as SSR, SR, or R, and the second step selects a specific item corresponding to that rarity. This structure makes it easier to manage and adjust the overall distribution rates for each rarity in the game.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| prizeTableId | string | ✓* | ~ 1024 chars | Prize Table GRN * Automatically configured on the server | ||
| name | string | ✓ | ~ 128 chars | Prize Table Name Prize table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 128 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| prizes | List<Prize> | ✓ | 1 ~ 100 items | List of Prizes |
Prize
Prize
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| prizeId | string | ✓ | UUID | ~ 36 chars | Prize ID | |||||||
| type | String Enum enum { “action”, “prize_table” } | ✓ | Type of prize
| |||||||||
| acquireActions | List<AcquireAction> | {type} == “action” | ✓* | [] | 1 ~ 100 items | List of Acquire Action * Required if type is “action” | ||||||
| drawnLimit | int | {type} == “action” | 1 ~ 1000000 | Maximum number of draws * Enabled if type is “action” | ||||||||
| limitFailOverPrizeId | string | {type} == “action” and {drawnLimit} > 0 | ✓* | ~ 32 chars | Prize ID to be discharged instead when the maximum number of drawn has been reached. * Required if type is “action” and drawnLimit is greater than 0 | |||||||
| prizeTableName | string | {type} == “prize_table” | ✓* | ~ 128 chars | Name of prize table * Required if type is “prize_table” | |||||||
| weight | int | ✓ | 1 ~ 2147483646 | Emission Weight |
AcquireAction
Acquire Action
LotteryModel
Lottery Model
The Lottery model is an entity that defines the draw method and how to reference the draw table. Two draw methods are available: Standard Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw.
The lottery process uses a prize table. GS2-Script can be used to replace a part of the prize table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different prize table only once in a 10-round gacha.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| lotteryModelId | string | ✓* | ~ 1024 chars | Lottery Model GRN * Automatically configured on the server | ||||||||
| name | string | ✓ | ~ 128 chars | Lottery Model name Lottery model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). | ||||||||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||||||||
| mode | String Enum enum { “normal”, “box” } | ✓ | Drawing mode
| |||||||||
| method | String Enum enum { “prize_table”, “script” } | ✓ | Lottery Method
| |||||||||
| prizeTableName | string | {method} == “prize_table” | ✓* | ~ 128 chars | Name of prize table * Required if method is “prize_table” | |||||||
| choicePrizeTableScriptId | string | {method} == “script” | ✓* | ~ 1024 chars | GS2-Script script GRN
to determine the emission probability table * Required if method is “script” |