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