> 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<Showcase>](#showcase) | | | | ~ 100 items | 진열대
`진열대`에는 진열할 상품을 정의할 수 있습니다.
또한 `진열대`의 상품 판매 기간을 설정할 수 있습니다. |
| randomShowcases | [List<RandomShowcase>](#randomshowcase) | | | | ~ 100 items | 랜덤 진열대
랜덤 진열대는 지정한 주기로 교체되는, 랜덤으로 선별된 상품이 진열되는 진열대 모델입니다.
선별되는 상품은 상품 풀에 등록된 상품 중에서 지정된 수량이 상품별로 설정된 가중치에 기반하여 랜덤으로 선택됩니다.
랜덤 진열대에는 GS2-Schedule의 이벤트를 연결하여 판매 기간을 설정할 수 있습니다. |
## 모델
### Showcase
진열대
`진열대`에는 진열할 상품을 정의할 수 있습니다.
또한 `진열대`의 상품 판매 기간을 설정할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| showcaseId | string | | ※ | | ~ 1024자 | 진열대 GRN
※ 서버가 자동으로 설정 |
| name | string | | ✓ | | ~ 128자 | 진열대 이름
진열대 고유의 이름. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string | | | | ~ 2048자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| salesPeriodEventId | string | | | | ~ 1024자 | 진열대의 판매 기간을 설정한 GS2-Schedule 이벤트 GRN
이 진열대 전체의 판매 기간을 제어합니다. 지정한 경우, 연관된 GS2-Schedule 이벤트 기간 중에만 진열대를 이용할 수 있습니다. 이벤트가 유효하지 않은 경우, 진열대는 비어 있는 상태로 반환됩니다. |
| displayItems | [List<DisplayItem>](#displayitem) | | | [] | 1 ~ 1000 items | 진열할 상품 리스트
이 진열대에 진열되는 상품의 리스트입니다. 각 진열 상품은 단일 상품 또는 상품 그룹 중 하나입니다. 판매 기간 이벤트가 종료되었거나 유효하지 않은 상품은 진열대 조회 시 자동으로 필터링됩니다. |
---
### DisplayItem
진열 상품
진열대에 표시되는 상품입니다. 단일 상품 또는 상품 그룹 중 하나를 참조할 수 있습니다. 각 진열 상품에는 진열대 전체의 판매 기간과는 독립적으로 GS2-Schedule 이벤트에 의한 개별 판매 기간을 설정할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| displayItemId | string | | ✓ | UUID | ~ 128자 | 진열 상품 ID
진열 상품의 고유한 이름을 유지합니다.
생략하면 시스템에 의해 UUID(Universally Unique Identifier) 형식으로 자동 할당됩니다. |
| type | 문자열 열거형
enum {
"salesItem",
"salesItemGroup"
}
| | ✓ | | | 종류
표시할 상품의 종류입니다. "salesItem"은 고정된 대가와 보상을 가진 단일 상품입니다. "salesItemGroup"은 여러 상품을 순서대로 평가하는 상품 그룹으로, 단계별 가격 인상이나 초회 한정 할인 등에 사용됩니다.salesItem: 상품 / salesItemGroup: 상품 그룹 / |
| salesItem | [SalesItem](#salesitem) | {type} == "salesItem" | ✓※ | | | 상품
※ type이(가) "salesItem" 이면 필수 |
| salesItemGroup | [SalesItemGroup](#salesitemgroup) | {type} == "salesItemGroup" | ✓※ | | | 상품 그룹
※ type이(가) "salesItemGroup" 이면 필수 |
| salesPeriodEventId | string | | | | ~ 1024자 | 이 진열 상품의 판매 기간을 설정한 GS2-Schedule의 이벤트 GRN
이 개별 진열 상품의 판매 기간을 제어합니다. 지정한 경우, 관련된 GS2-Schedule의 이벤트 기간 중에만 진열대에 표시됩니다. 진열대 전체의 판매 기간과는 독립적으로 동작합니다. |
---
### SalesItem
상품
상품을 구매하기 위해 필요한 대가와, 상품을 구매했을 때 얻을 수 있는 보상을 설정합니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128자 | 상품 이름
상품 고유의 이름. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string | | | | ~ 2048자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| verifyActions | [List<VerifyAction>](#verifyaction) | | | [] | 0 ~ 10 items | 검증 액션 리스트
구매 전에 실행되는 전제 조건 체크입니다. 모든 검증 액션이 성공한 후에 소비·획득 액션이 처리됩니다. 구매 자격 조건 체크에 사용할 수 있습니다. |
| consumeActions | [List<ConsumeAction>](#consumeaction) | | | [] | 0 ~ 10 items | 소비 액션 리스트
구매 대가로 리소스를 소비하는 액션입니다. 상품 그룹의 구매 횟수 제어를 위해 GS2-Limit의 CountUp 액션을 포함할 수 있습니다. |
| acquireActions | [List<AcquireAction>](#acquireaction) | | | [] | 1 ~ 100 items | 획득 액션 리스트
구매 보상으로 리소스를 부여하는 액션입니다. 모든 소비 액션이 정상적으로 완료된 후에 실행됩니다. |
---
### SalesItemGroup
상품 그룹
상품 그룹은 진열대에 진열하기 위한 엔티티입니다.
상품 그룹에는 여러 상품을 소속시킬 수 있으며, 소속된 상품의 앞에서부터 순서대로 구매 가능한지를 판정하여 가장 먼저 구매 가능하다고 판정된 상품이 실제로 진열됩니다.
최초 1회만 할인되는 상품이나, 스텝업 가챠처럼 구매 횟수에 따라 상품 내용이 변화하는 구조에 사용할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128자 | 상품 그룹 이름
상품 그룹 고유의 이름. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string | | | | ~ 2048자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| salesItems | [List<SalesItem>](#salesitem) | | | [] | 2 ~ 10 items | 상품 그룹에 포함할 상품
이 그룹 내 상품의 순서가 지정된 리스트입니다. GS2-Limit 카운터를 사용하여 앞에서부터 순서대로 구매 가능한지를 판정하고, 가장 먼저 구매 가능하다고 판정된 상품이 표시됩니다. 어느 것도 해당하지 않는 경우, 리스트의 마지막 상품이 폴백으로 사용됩니다. |
---
### ConsumeAction
소비 액션
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형
enum {
}
| | ✓ | | | 소비 액션에서 실행할 액션의 종류 |
| request | string | | ✓ | | ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
---
### VerifyAction
검증 액션
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형
enum {
}
| | ✓ | | | 검증 액션에서 실행할 액션의 종류 |
| request | string | | ✓ | | ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
---
### AcquireAction
입수 액션
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형
enum {
}
| | ✓ | | | 입수 액션에서 실행할 액션의 종류 |
| request | string | | ✓ | | ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
---
### RandomShowcase
랜덤 진열대
랜덤 진열대는 지정한 주기로 교체되는, 랜덤으로 선별된 상품이 진열되는 진열대 모델입니다.
선별되는 상품은 상품 풀에 등록된 상품 중에서 지정된 수량이 상품별로 설정된 가중치에 기반하여 랜덤으로 선택됩니다.
랜덤 진열대에는 GS2-Schedule의 이벤트를 연결하여 판매 기간을 설정할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| randomShowcaseId | string | | ※ | | ~ 1024자 | 랜덤 진열대 GRN
※ 서버가 자동으로 설정 |
| name | string | | ✓ | | ~ 128자 | 랜덤 진열대 이름
랜덤 진열대 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string | | | | ~ 2048자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| maximumNumberOfChoice | int | | ✓ | | 1 ~ 100 | 선택되는 상품의 최대 수
각 로테이션 기간마다 상품 풀에서 랜덤으로 추첨되는 상품의 수입니다. 가중치 기반 랜덤 선택으로 중복 없이 추첨되므로, 한 번의 로테이션에서 같은 상품이 두 번 표시되는 일은 없습니다. |
| displayItems | [List<RandomDisplayItemModel>](#randomdisplayitemmodel) | | | [] | 1 ~ 100 items | 선택 대상 진열 상품 목록
상품이 랜덤으로 추첨되는 후보 아이템의 풀입니다. 각 아이템에는 선택 확률을 결정하는 가중치와, 로테이션 전체에서 표시 가능한 횟수를 제한하는 재고 수가 있습니다. |
| baseTimestamp | long | | ✓ | | | 진열 상품 재추첨 기준 시간
로테이션 경계 계산에 사용되는 기준 타임스탬프입니다. 이 기준 시간으로부터 일정 간격(resetIntervalHours)마다 상품의 재추첨이 이루어집니다. 과거 시각을 지정해야 합니다. |
| resetIntervalHours | int | | ✓ | | 1 ~ 168 | 진열 상품을 재추첨하는 간격(시간)
각 상품 로테이션 사이의 시간 수입니다. baseTimestamp를 기준으로 간격이 경과하면 새로운 난수 시드로 진열 상품이 재추첨됩니다. 1~168시간(1주일) 범위에서 설정할 수 있습니다. |
| salesPeriodEventId | string | | | | ~ 1024자 | 진열대의 판매 기간을 설정한 GS2-Schedule의 이벤트 GRN
이 랜덤 진열대 전체의 판매 기간을 제어합니다. 지정한 경우, 관련된 GS2-Schedule의 이벤트 기간 중에만 진열대를 이용할 수 있습니다. |
---
### RandomDisplayItemModel
랜덤 진열대에 진열 가능한 상품
`weight`에 상품을 선별하는 확률을 설정할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | UUID | ~ 128자 | 랜덤 진열 상품 ID
랜덤 진열 상품의 고유한 이름을 유지합니다.
생략하면 시스템에 의해 UUID(Universally Unique Identifier) 형식으로 자동 할당됩니다. |
| metadata | string | | | | ~ 2048자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| verifyActions | [List<VerifyAction>](#verifyaction) | | | [] | 0 ~ 10 items | 검증 액션 목록
이 랜덤 진열 상품을 구매하기 전에 실행되는 전제 조건 확인입니다. 모든 검증 액션이 성공한 후에 소비·획득 액션이 처리됩니다. |
| consumeActions | [List<ConsumeAction>](#consumeaction) | | | [] | 0 ~ 10 items | 소비 액션 목록
이 랜덤 진열 상품의 구매 대가로 리소스를 소비하는 액션입니다. 트랜잭션의 소비 액션으로 실행됩니다. |
| acquireActions | [List<AcquireAction>](#acquireaction) | | | [] | 1 ~ 100 items | 획득 액션 목록
이 랜덤 진열 상품의 구매 보상으로 리소스를 지급하는 액션입니다. 트랜잭션의 획득 액션으로 실행됩니다. |
| stock | int | | ✓ | | 1 ~ 2147483646 | 재고 수
모든 로테이션을 통틀어 이 상품이 추첨될 수 있는 최대 횟수입니다. 재고가 0이 되면 이후 추첨에서 제외됩니다. 로테이션 추첨 시 상품이 선택되면 재고가 소비됩니다. |
| weight | int | | ✓ | | 1 ~ 2147483646 | 추첨 가중치
랜덤 선택에서 이 상품의 상대적인 확률 가중치입니다. 가중치가 클수록 추첨될 확률이 높아집니다. 실제 선택 확률은 이 상품의 가중치를 대상이 되는 모든 상품의 가중치 합계로 나눈 값으로 계산됩니다. |
---