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

# GS2-Lottery 마스터 데이터 레퍼런스

마스터 데이터 포맷과 임포트할 각종 모델의 레퍼런스




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2019-02-21",
  "lotteryModels": [
    {
      "name": "[string]추첨 모델 이름",
      "metadata": "[string?]메타데이터",
      "mode": "[문자열 열거형]추첨 모드",
      "method": "[문자열 열거형]추첨 방법",
      "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&lt;LotteryModel&gt;](#lotterymodel) |  |  |  |  ~ 100 items | 추첨 모델<br>추첨 모델은 배출 방식과 배출 테이블의 참조 방법을 정의하는 엔티티입니다.<br><br>배출 방식은 2종류가 마련되어 있으며, 일반 추첨은 매번 일정한 확률로 추첨하는 방식이고, 박스 추첨은 상자 안에 미리 정해진 수량의 경품이 들어 있어 추첨할 때마다 상자에서 경품을 꺼내는 추첨 방식입니다.<br><br>추첨 처리를 수행할 때 배출 확률 테이블을 사용하는데,<br>GS2-Script를 사용하면 여러 번 추첨을 실행할 때 배출 확률 테이블 일부만 다른 테이블로 교체할 수 있습니다.<br>이 구조를 이용하면 10연 가챠에서 1회만 다른 추첨 확률 테이블을 적용하는 것이 가능해집니다. |
| prizeTables | [List&lt;PrizeTable&gt;](#prizetable) |  |  |  |  ~ 100 items | 배출 확률 테이블<br>경품에는 입수 액션을 직접 지정하거나, 다른 배출 확률 테이블을 참조하도록 설정할 수도 있습니다.<br>배출 확률 테이블을 중첩시키면, 예를 들어 1단계에서 SSR / SR / R 등의 레어도를 추첨하고, 2단계에서 해당 레어도에 대응하는 구체적인 콘텐츠를 추첨하는 등의 설정이 가능합니다.<br>이 구조를 통해 게임 전체의 레어도별 배출 확률을 관리하고 조정하기가 더 쉬워집니다. |

## 모델

### PrizeTable

배출 확률 테이블<br>

경품에는 입수 액션을 직접 지정하거나, 다른 배출 확률 테이블을 참조하도록 설정할 수도 있습니다.<br>
배출 확률 테이블을 중첩시키면, 예를 들어 1단계에서 SSR / SR / R 등의 레어도를 추첨하고, 2단계에서 해당 레어도에 대응하는 구체적인 콘텐츠를 추첨하는 등의 설정이 가능합니다.<br>
이 구조를 통해 게임 전체의 레어도별 배출 확률을 관리하고 조정하기가 더 쉬워집니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| prizeTableId | string |  | ※ |  |  ~ 1024자 | 배출 확률 테이블 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 배출 확률 테이블 이름<br>배출 확률 테이블 고유의 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 128자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| prizes | [List&lt;Prize&gt;](#prize) |  | ✓ |  | 1 ~ 100 items | 경품 리스트<br>이 배출 확률 테이블 내의 경품 리스트입니다. 각 경품은 배출 가중치(확률), 배출 시 실행할 액션, 그리고 선택적으로 배출 횟수 제한을 정의합니다. 각 경품의 실제 배출 확률은 해당 가중치를 테이블 내 전체 경품 가중치의 합으로 나누어 산출됩니다. |

---

### Prize

경품<br>

배출 확률 테이블 내 단일 경품 엔트리입니다.<br>
경품은 입수 액션(아이템이나 통화의 부여 등)을 직접 지정하거나, 다른 배출 확률 테이블을 참조하여 중첩된 추첨을 수행할 수 있습니다.<br>
각 경품에는 배출 가중치가 있으며, 배출되는 상대적 확률을 결정합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| prizeId | string |  | ✓ | UUID |  ~ 36자 | 경품 ID<br>배출 확률 테이블 내에서 이 경품을 고유하게 식별하는 ID입니다. 배출 횟수 제한 추적 및 페일오버 경품 지정 시 참조에 사용됩니다. |
| type | 문자열 열거형<br>enum {<br>"action",<br>"prize_table"<br>}<br> |  | ✓ |  |  | 경품 종류<br>이 경품이 직접 보상을 부여하는지, 다른 배출 확률 테이블에 위임하는지를 결정합니다. "action"은 배출 시 실행할 입수 액션을 지정합니다. "prize_table"은 다른 배출 확률 테이블을 참조하여 중첩된 추첨을 수행합니다(예: 1단계에서 희귀도를 결정하고, 2단계에서 구체적인 아이템을 결정).action: 경품의 입수 액션 / prize_table: 더욱 배출 확률 테이블을 지정하여 재추첨 /  |
| acquireActions | [List&lt;AcquireAction&gt;](#acquireaction) | {type} == "action" |  | [] | 1 ~ 100 items | 입수 액션 리스트<br>이 경품이 배출될 때 실행할 입수 액션의 리스트입니다. 여러 액션을 지정하여 한 번에 여러 보상을 부여할 수 있습니다(예: 아이템과 통화를 동시에 부여).<br>※ type이(가) "action" 이면 활성화 |
| drawnLimit | int | {type} == "action" |  |  | 1 ~ 1000000 | 최대 배출 수<br>이 경품이 전체 사용자를 통틀어 배출될 수 있는 최대 횟수입니다. 제한에 도달하면 대신 페일오버 경품(limitFailOverPrizeId)이 배출됩니다. 잭팟 아이템 등 수량 한정 경품 구현에 사용됩니다.<br>※ type이(가) "action" 이면 활성화 |
| limitFailOverPrizeId | string | {type} == "action" and {drawnLimit} > 0 | ✓※ |  |  ~ 32자 | 제한 시 페일오버 경품 ID<br>이 경품의 배출 횟수 제한(drawnLimit)에 도달했을 때 대신 배출할 경품의 ID입니다. 동일한 배출 확률 테이블 내의 다른 경품을 참조해야 합니다.<br>※ type이(가) "action"이고 drawnLimit이(가) 0 보다 크면 필수 |
| prizeTableName | string | {type} == "prize_table" | ✓※ |  |  ~ 128자 | 배출 확률 테이블의 이름<br>추첨을 위임할 배출 확률 테이블의 이름입니다. 경품 타입이 "prize_table"인 경우 중첩된 추첨에 사용됩니다.<br>※ type이(가) "prize_table" 이면 필수 |
| weight | int |  | ✓ |  | 1 ~ 2147483646 | 배출 가중치<br>배출 확률 테이블 내에서 이 경품의 상대적 가중치입니다. 실제 배출 확률은 이 경품의 가중치를 테이블 내 모든 경품의 가중치 합계로 나누어 산출됩니다. 예를 들어 3개의 경품의 가중치가 각각 70, 20, 10이라면 각각의 배출 확률은 70%, 20%, 10%가 됩니다. |

---

### AcquireAction

입수 액션

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 입수 액션에서 실행할 액션의 종류 |
| request | string |  | ✓ |  |  ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |

---

### LotteryModel

추첨 모델<br>

추첨 모델은 배출 방식과 배출 테이블의 참조 방법을 정의하는 엔티티입니다.<br>

배출 방식은 2종류가 마련되어 있으며, 일반 추첨은 매번 일정한 확률로 추첨하는 방식이고, 박스 추첨은 상자 안에 미리 정해진 수량의 경품이 들어 있어 추첨할 때마다 상자에서 경품을 꺼내는 추첨 방식입니다.<br>

추첨 처리를 수행할 때 배출 확률 테이블을 사용하는데,<br>
GS2-Script를 사용하면 여러 번 추첨을 실행할 때 배출 확률 테이블 일부만 다른 테이블로 교체할 수 있습니다.<br>
이 구조를 이용하면 10연 가챠에서 1회만 다른 추첨 확률 테이블을 적용하는 것이 가능해집니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| lotteryModelId | string |  | ※ |  |  ~ 1024자 | 추첨 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 추첨 모델 이름<br>추첨 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에 영향을 미치지 않으므로, 게임 내에서 사용할 정보를 저장하는 용도로 사용할 수 있습니다. |
| mode | 문자열 열거형<br>enum {<br>"normal",<br>"box"<br>}<br> |  | ✓ |  |  | 추첨 모드<br>경품의 추첨 방식을 선택합니다. "normal"은 매번 일정한 확률로 추첨을 진행합니다(경품은 반복해서 배출됩니다). "box"는 가상의 상자에 미리 정해진 수량의 경품을 넣어두고, 추첨할 때마다 상자에서 경품을 꺼냅니다(모든 경품이 최종적으로 배출되는 것이 보장됩니다).normal: 일반 추첨 / box: 박스 추첨 /  |
| method | 문자열 열거형<br>enum {<br>"prize_table",<br>"script"<br>}<br> |  | ✓ |  |  | 추첨 방법<br>배출 확률 테이블의 참조 방법을 결정합니다. "prize_table"은 정적으로 지정된 배출 확률 테이블을 사용합니다. "script"는 GS2-Script를 사용하여 추첨 시점에 배출 확률 테이블을 동적으로 선택하며, 10연 가챠에서 1회만 다른 배출 확률 테이블을 적용하는 등의 시나리오를 실현할 수 있습니다.prize_table: 정적 배출 확률 테이블 / script: GS2-Script를 사용한 동적 배출 확률 테이블 /  |
| prizeTableName | string | {method} == "prize_table" | ✓※ |  |  ~ 128자 | 배출 확률 테이블 이름<br>이 추첨 모델에서 사용할 배출 확률 테이블의 이름입니다. 추첨 방법이 "prize_table"인 경우 필수입니다.<br>※ method이(가) "prize_table" 이면 필수 |
| choicePrizeTableScriptId | string | {method} == "script" | ✓※ |  |  ~ 1024자 | 배출 확률 테이블을 결정하는 GS2-Script의 스크립트 GRN<br>Script 트리거 레퍼런스 - [`choicePrizeTable`](../script/#choiceprizetable)<br>※ method이(가) "script" 이면 필수 |

---