GS2-Exchange 마스터 데이터 레퍼런스
마스터 데이터 포맷과 임포트할 각종 모델의 레퍼런스
마스터 데이터 포맷
{
"version": "2019-08-19",
"rateModels": [
{
"name": "[string]교환 레이트 모델 이름",
"metadata": "[string?]메타데이터",
"verifyActions": [
{
"action": "[string]검증 액션에서 실행할 액션의 종류",
"request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
}
],
"consumeActions": [
{
"action": "[string]소비 액션에서 실행할 액션의 종류",
"request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
}
],
"timingType": "[문자열 열거형]교환 종류",
"lockTime": "[int]교환 실행부터 실제로 보상을 받을 수 있게 될 때까지의 대기 시간(분)",
"acquireActions": [
{
"action": "[string]입수 액션에서 실행할 액션의 종류",
"request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
}
]
}
],
"incrementalRateModels": [
{
"name": "[string]코스트 상승형 교환 레이트 모델의 이름",
"metadata": "[string?]메타데이터",
"consumeAction": {
"action": "[string]소비 액션에서 실행할 액션의 종류",
"request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
},
"calculateType": "[문자열 열거형]코스트 상승량 계산 방식",
"baseValue": "[long]베이스 값",
"coefficientValue": "[long]계수",
"calculateScriptId": "[string]코스트 계산 스크립트의 GRN",
"exchangeCountId": "[string]교환 실행 횟수를 관리하는 GS2-Limit의 횟수 제한 모델 GRN",
"maximumExchangeCount": "[int]교환 횟수 상한",
"acquireActions": [
{
"action": "[string]입수 액션에서 실행할 액션의 종류",
"request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
}
]
}
]
}| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| version | string | ✓ | 2019-08-19 | 마스터 데이터 포맷 버전 | ||
| rateModels | List<RateModel> | ~ 10000 items | 교환 레이트 모델 교환 레이트 모델은 리소스와 리소스를 교환할 때 사용하는 레이트를 정의하는 엔티티입니다. 즉시 교환할 수 있는 레이트뿐만 아니라, 현실 시간으로 일정 시간이 경과한 후에 교환할 수 있는 레이트도 설정할 수 있습니다. 현실 시간의 경과가 필요한 교환 레이트에는 즉시 교환을 실행하는 데 필요한 리소스를 추가로 정의할 수 있습니다. | |||
| incrementalRateModels | List<IncrementalRateModel> | ~ 10000 items | 코스트 상승형 교환 레이트 모델 일반적인 교환 레이트는 항상 일정한 레이트로 교환을 제공합니다. 상승형 교환 레이트에서는 교환 횟수에 따라 코스트가 상승하는 레이트를 정의할 수 있습니다. 예를 들어, 첫 번째 교환에서는 1:1로 교환할 수 있지만, 두 번째 교환에서는 2:1로 교환하게 되는 것과 같은 레이트를 정의할 수 있습니다. 이러한 레이트를 정의함으로써 플레이어가 게임을 진행함에 따라 얻을 수 있는 리소스의 가치를 높일 수 있습니다. 교환 횟수는 현실 시간의 경과에 따라 리셋할 수 있습니다. 이 기능을 이용하면 매일 또는 매주 교환에 필요한 코스트를 리셋할 수 있습니다. |
모델
RateModel
교환 레이트 모델
교환 레이트 모델은 리소스와 리소스를 교환할 때 사용하는 레이트를 정의하는 엔티티입니다.
즉시 교환할 수 있는 레이트뿐만 아니라, 현실 시간으로 일정 시간이 경과한 후에 교환할 수 있는 레이트도 설정할 수 있습니다.
현실 시간의 경과가 필요한 교환 레이트에는 즉시 교환을 실행하는 데 필요한 리소스를 추가로 정의할 수 있습니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| rateModelId | string | ※ | ~ 1024자 | 교환 레이트 모델 GRN
※ 서버가 자동으로 설정 | ||||||||
| name | string | ✓ | ~ 128자 | 교환 레이트 모델 이름 교환 레이트 모델 종류 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||
| metadata | string | ~ 2048자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||||||||
| verifyActions | List<VerifyAction> | [] | 0 ~ 10 items | 검증 액션 리스트 교환이 실행되기 전에 모두 통과해야 하는 사전 조건 체크입니다. 검증 액션 중 하나라도 실패하면, 리소스를 소비하지 않고 교환이 중단됩니다. 레벨 요건이나 인벤토리 용량 등의 조건을 강제하기 위해 사용됩니다. | ||||||||
| consumeActions | List<ConsumeAction> | [] | 0 ~ 10 items | 소비 액션 리스트 이 교환을 실행하기 위해 플레이어가 지불해야 하는 리소스(코스트)를 정의합니다. 여러 개의 소비 액션을 지정할 수 있어, 골드와 아이템을 모두 필요로 하는 것과 같은 복잡한 교환 코스트를 구현할 수 있습니다. 이러한 액션은 분산 트랜잭션 내의 소비 액션으로 실행됩니다. | ||||||||
| timingType | 문자열 열거형 enum { “immediate”, “await” } | “immediate” | 교환 종류 교환 실행 후 보상이 언제 전달되는지를 결정합니다. immediate는 교환 실행 시 즉시 보상을 전달합니다. await는 보상을 받기 전에 실시간의 경과가 필요하며, 대기 기간(예: 제작 시간)을 둡니다.
| |||||||||
| lockTime | int | {timingType} == “await” | ✓※ | 0 ~ 538214400 | 교환 실행부터 실제로 보상을 받을 수 있게 될 때까지의 대기 시간(분) timingType이 await인 경우에만 적용됩니다. 교환이 시작된 후 플레이어가 보상을 받을 수 있게 되기까지 경과해야 하는 실시간 분수를 지정합니다. 대기 시간은 스킵 기능을 사용하여 단축할 수 있습니다.※ timingType이(가) “await” 이면 필수 | |||||||
| acquireActions | List<AcquireAction> | [] | 0 ~ 100 items | 획득 액션 리스트 교환 완료 시 플레이어가 받는 리소스(보상)를 정의합니다. 여러 개의 획득 액션을 지정하여 다양한 리소스 타입을 동시에 지급할 수 있습니다. 이러한 액션은 분산 트랜잭션 내의 획득 액션으로 실행됩니다. |
AcquireAction
입수 액션
ConsumeAction
소비 액션
VerifyAction
검증 액션
IncrementalRateModel
코스트 상승형 교환 레이트 모델
일반적인 교환 레이트는 항상 일정한 레이트로 교환을 제공합니다.
상승형 교환 레이트에서는 교환 횟수에 따라 코스트가 상승하는 레이트를 정의할 수 있습니다.
예를 들어, 첫 번째 교환에서는 1:1로 교환할 수 있지만, 두 번째 교환에서는 2:1로 교환하게 되는 것과 같은 레이트를 정의할 수 있습니다.
이러한 레이트를 정의함으로써 플레이어가 게임을 진행함에 따라 얻을 수 있는 리소스의 가치를 높일 수 있습니다.
교환 횟수는 현실 시간의 경과에 따라 리셋할 수 있습니다.
이 기능을 이용하면 매일 또는 매주 교환에 필요한 코스트를 리셋할 수 있습니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| incrementalRateModelId | string | ※ | ~ 1024자 | 코스트 상승형 교환 레이트 모델 GRN
※ 서버가 자동으로 설정 | ||||||||||
| name | string | ✓ | ~ 128자 | 코스트 상승형 교환 레이트 모델의 이름 코스트 상승형 교환 레이트 모델 종류 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||||
| metadata | string | ~ 2048자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||||||||||
| consumeAction | ConsumeAction | ✓ | 소비 액션 (수량/값은 자동으로 덮어써집니다) 교환 비용으로 소비되는 리소스의 종류를 정의합니다. 실제 수량은 교환 횟수와 계산 방식(선형, 거듭제곱, 스크립트)에 기반하여 동적으로 계산됩니다. 액션 종류와 대상 리소스만 지정하면 되며, 수량 필드는 자동으로 덮어써집니다. | |||||||||||
| calculateType | 문자열 열거형 enum { “linear”, “power”, “gs2_script” } | ✓ | 코스트 상승량 계산 방식 교환 횟수에 따라 코스트가 어떻게 상승하는지를 결정합니다. linear는 코스트를 baseValue +(coefficientValue × 교환 횟수)로 계산합니다. power는 코스트를 coefficientValue ×(교환 횟수 + 1)^2로 계산합니다. gs2_script는 임의의 로직을 위해 커스텀 GS2-Script에 계산을 위임합니다.
| |||||||||||
| baseValue | long | {calculateType} == “linear” | ✓※ | 0 ~ 9223372036854775805 | 베이스 값linear 계산 방식을 사용하는 경우 첫 교환 시의 기본 코스트입니다. 합계 코스트는 baseValue +(coefficientValue × 교환 횟수)로 계산됩니다.※ calculateType이(가) “linear” 이면 필수 | |||||||||
| coefficientValue | long | {calculateType} in [“linear”, “power”] | ✓※ | 0 ~ 9223372036854775805 | 계수 교환 횟수에 따라 코스트가 얼마나 빠르게 상승하는지를 제어하는 승수입니다. linear 모드에서는 각 교환마다 이 값이 코스트에 더해집니다. power 모드에서는 코스트가 coefficientValue ×(교환 횟수 + 1)^2로 계산됩니다.※ calculateType이(가) “linear”,“power"이면 필수 | |||||||||
| calculateScriptId | string | {calculateType} == “gs2_script” | ✓※ | ~ 1024자 | 코스트 계산 스크립트의 GRN
Script 트리거 레퍼런스 - calculateCost※ calculateType이(가) “gs2_script” 이면 필수 | |||||||||
| exchangeCountId | string | ✓ | ~ 1024자 | 교환 실행 횟수를 관리하는 GS2-Limit의 횟수 제한 모델 GRN
각 사용자가 이 코스트 상승형 교환을 몇 번 실행했는지 추적하는 GS2-Limit의 횟수 제한 모델을 참조합니다. 카운트는 상승하는 코스트 계산에 사용되며, GS2-Limit의 리셋 타이밍을 사용하여 정기적으로(예: 매일 또는 매주) 리셋할 수 있습니다. | ||||||||||
| maximumExchangeCount | int | 2147483646 | 0 ~ 2147483646 | 교환 횟수 상한 사용자가 이 코스트 상승형 교환을 실행할 수 있는 최대 횟수입니다. 교환 횟수가 이 상한에 도달하면, GS2-Limit에 의한 카운트 리셋까지 이후의 교환이 거부됩니다. | ||||||||||
| acquireActions | List<AcquireAction> | [] | 0 ~ 100 items | 획득 액션 리스트 코스트 상승형 교환 완료 시 플레이어가 받는 리소스(보상)를 정의합니다. 보상은 교환 횟수와 관계없이 일정하며, 코스트만 교환마다 증가합니다. |