Master Data Reference of GS2-Lottery
{
"version": "2019-02-21",
"lotteryModels": [
{
"name": "[string]Lottery Model Name",
"metadata": "[string?]metadata",
"mode": "[string]Drawing mode",
"method": "[string]Lottery Method",
"prizeTableName": "[string]Name of prize table",
"choicePrizeTableScriptId": "[string]GS2-Script script to determine the emission probability table"
}
],
"prizeTables": [
{
"name": "[string]Name of prize table",
"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 of request"
}
],
"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 | Require | Default | Limitation | Description | |
|---|---|---|---|---|---|---|
| version | ✓ | 2019-02-21 | Format version of master data | |||
| lotteryModels | List<LotteryModel> | ~ 10 items | Lottery Model | |||
| prizeTables | List<PrizeTable> | ~ 10 items | Prize Table |
LotteryModel
Lottery Model
The Lottery Model is the entity that defines the emission method and emission rate in Lottery. There are two types of emission methods: the normal lottery method draws lots with a fixed probability each time, and the rate of emission is determined by the number of lots drawn. The box lottery is a lottery method in which a predefined number of prizes are placed in a box and the prizes are removed from the box each time the lottery is drawn.
The lottery process uses an ejection probability table. GS2-Script can be used to replace a part of the ejection probability table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different lottery probability table only once in a 10-round gacha.
| Type | Condition | Require | Default | Limitation | Description | |
|---|---|---|---|---|---|---|
| lotteryModelId | string | ✓ | ~ 1024 chars | Prize Table GRN | ||
| name | string | ✓ | ~ 128 chars | Lottery Model Name | ||
| metadata | string | ~ 128 chars | metadata | |||
| mode | enum { “normal”, “box” } | ✓ | ~ 128 chars | Drawing mode | ||
| method | enum { “prize_table”, “script” } | ✓ | ~ 128 chars | Lottery Method | ||
| prizeTableName | string | {method} == “prize_table” | ✓ | ~ 128 chars | Name of prize table | |
| choicePrizeTableScriptId | string | {method} == “script” | ✓ | ~ 1024 chars | GS2-Script script to determine the emission probability table |
Enumeration type definition to specify as mode
| Enumerator String Definition | Description |
|---|---|
| normal | Normal |
| box | Box |
Enumeration type definition to specify as method
| Enumerator String Definition | Description |
|---|---|
| prize_table | Static lottery table |
| script | GS2-Script dynamic lottery table |
PrizeTable
Prize Table
Prizes can specify an acquisition action or further specify an emission probability table. By nesting the emission probability tables, a table that draws for SSR/SR/R rarity can be passed through the table. The second tier can be set up to draw for specific content. In this way, it is easier to adjust the overall emission probability of each rarity.
| Type | Condition | Require | Default | Limitation | Description | |
|---|---|---|---|---|---|---|
| prizeTableId | string | ✓ | ~ 1024 chars | Prize Table GRN | ||
| name | string | ✓ | ~ 128 chars | Name of prize table | ||
| metadata | string | ~ 128 chars | metadata | |||
| prizes | List<Prize> | ✓ | 1 ~ 100 items | List of Prizes |
Probability
Probability
| Type | Condition | Require | Default | Limitation | Description | |
|---|---|---|---|---|---|---|
| prize | DrawnPrize | ✓ | Type of prize | |||
| rate | float | ✓ | ~ 1.0 | Emission probability (0.0-1.0) |
Prize
Prize
| Type | Condition | Require | Default | Limitation | Description | |
|---|---|---|---|---|---|---|
| prizeId | string | ✓ | UUID | ~ 36 chars | Prize ID | |
| type | enum { “action”, “prize_table” } | ✓ | ~ 128 chars | Type of prize | ||
| acquireActions | List<AcquireAction> | {type} == “action” | ✓ | [] | 1 ~ 100 items | List of Acquire Action |
| drawnLimit | int | {type} == “action” | 1 ~ 100000 | Maximum number of draws | ||
| limitFailOverPrizeId | string | {type} == “action” and {drawnLimit} > 0 | ✓ | ~ 32 chars | Prize ID to be discharged instead when the maximum number of drawn has been reached. | |
| prizeTableName | string | {type} == “prize_table” | ✓ | ~ 128 chars | Name of prize table | |
| weight | int | ✓ | 1 ~ 2147483646 | Emission Weight |
Enumeration type definition to specify as type
| Enumerator String Definition | Description |
|---|---|
| action | Actions to acquire prizes |
| prize_table | Further redrawing by specifying the lottery table |
DrawnPrize
Types of prizes
| Type | Condition | Require | Default | Limitation | Description | |
|---|---|---|---|---|---|---|
| prizeId | string | ✓ | ~ 36 chars | Prize ID | ||
| acquireActions | List<AcquireAction> | ~ 100 items | List of Acquire Actions |
BoxItem
Item taken out of the lottery box
| Type | Condition | Require | Default | Limitation | Description | |
|---|---|---|---|---|---|---|
| prizeId | string | ✓ | ~ 128 chars | Prize Id | ||
| acquireActions | List<AcquireAction> | ~ 100 items | List of Acquire Action | |||
| remaining | int | ✓ | ~ 2147483646 | Remaining quantity | ||
| initial | int | ✓ | ~ 2147483646 | Initial quantity |
AcquireAction
Acquire Action