> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Grade 마스터 데이터 레퍼런스
마스터 데이터 포맷과 임포트할 각종 모델의 레퍼런스
## 마스터 데이터 포맷
**JSON**
```json
{
"version": "2023-12-25",
"gradeModels": [
{
"name": "[string]그레이드 모델 이름",
"metadata": "[string?]메타데이터",
"defaultGrades": [
{
"propertyIdRegex": "[string]프로퍼티 ID 정규 표현식",
"defaultGradeValue": "[long]기본 그레이드 값"
}
],
"experienceModelId": "[string]GS2-Experience 경험치 모델 GRN",
"gradeEntries": [
{
"metadata": "[string?]메타데이터",
"rankCapValue": "[long]랭크 캡 값",
"propertyIdRegex": "[string]프로퍼티 ID 정규 표현식",
"gradeUpPropertyIdRegex": "[string]그레이드업용 프로퍼티 ID 정규 표현식"
}
],
"acquireActionRates": [
{
"name": "[string]보상 가산 테이블 이름",
"mode": "[string]보상 가산 테이블 종류",
"rates": [
"[double]배율 값"
],
"bigRates": [
"[string]배율 값 (빅 넘버)"
]
}
]
}
]
}
```
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2023-12-25 | | 마스터 데이터 포맷 버전 |
| gradeModels | [List<GradeModel>](#grademodel) | | | | ~ 100 items | 그레이드 모델
그레이드 모델이란 캐릭터나 장비의 랭크를 나타내는 엔티티로, 그레이드에 따라 GS2-Experience의 랭크 캡을 설정할 수 있습니다. |
## 모델
### GradeModel
그레이드 모델
그레이드 모델이란 캐릭터나 장비의 랭크를 나타내는 엔티티로, 그레이드에 따라 GS2-Experience의 랭크 캡을 설정할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| gradeModelId | string | | ※ | | ~ 1024자 | 그레이드 모델 GRN
※ 서버가 자동으로 설정 |
| name | string | | ✓ | | ~ 128자 | 그레이드 모델 이름
그레이드 모델 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string | | | | ~ 2048자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| defaultGrades | [List<DefaultGradeModel>](#defaultgrademodel) | | | | 0 ~ 100 items | 기본 그레이드 모델 리스트
신규 스테이터스 작성 시 평가되는 기본 그레이드 규칙의 순서가 있는 리스트입니다. 각 항목은 프로퍼티 ID의 정규 표현식 패턴과, 매칭된 경우 할당할 그레이드 값을 정의합니다. 어떤 패턴에도 매칭되지 않으면 기본 그레이드 값 0이 사용됩니다. |
| experienceModelId | string | | ✓ | | ~ 1024자 | GS2-Experience 경험치 모델 GRN
이 그레이드 모델과 연동시킬 GS2-Experience의 경험치 모델의 GRN입니다. 그레이드 값이 변경되면, 그레이드 엔트리의 매핑에 기반하여 연동된 경험치 모델의 랭크 캡이 자동으로 업데이트됩니다. 이를 통해 높은 그레이드가 더 높은 랭크 캡을 해제하는 그레이드 기반 성장을 구현할 수 있습니다. |
| gradeEntries | [List<GradeEntryModel>](#gradeentrymodel) | | ✓ | | 1 ~ 100 items | 그레이드 엔트리 모델 리스트
각 그레이드 값을 연동된 GS2-Experience 모델의 랭크 캡에 매핑하는 그레이드 엔트리의 순서가 있는 리스트입니다. 배열의 인덱스가 그레이드 값에 대응하므로, 첫 번째 항목(인덱스 0)이 그레이드 0의 랭크 캡을, 두 번째 항목이 그레이드 1의 랭크 캡을 정의합니다. |
| acquireActionRates | [List<AcquireActionRate>](#acquireactionrate) | | | | 0 ~ 100 items | 보상 가산 테이블 리스트
그레이드를 기반으로 보상량을 스케일링하기 위한 이름이 지정된 배율 테이블의 컬렉션입니다. 여러 테이블을 정의하여 서로 다른 종류의 보상(예: 경험치, 통화, 아이템)에 다른 스케일링 규칙을 적용할 수 있습니다. |
---
### DefaultGradeModel
기본 그레이드 모델
그레이드를 새로 생성할 때 프로퍼티 ID의 정규 표현식과의 매칭에 따라 기본 그레이드 값을 설정할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| propertyIdRegex | string | | ✓ | | ~ 1024자 | 프로퍼티 ID 정규 표현식
새로 생성된 그레이드 스테이터스의 프로퍼티 ID에 대해 매칭되는 정규 표현식 패턴입니다. 프로퍼티 ID가 이 패턴에 매칭되면, 0 대신 지정된 기본 그레이드 값이 초기 그레이드로 할당됩니다. 패턴은 순서대로 평가되며, 처음 매칭된 것이 사용됩니다. |
| defaultGradeValue | long | | ✓ | | 0 ~ 9223372036854775805 | 기본 그레이드 값
프로퍼티 ID가 propertyIdRegex 패턴에 매칭된 경우 새로 생성된 스테이터스에 할당되는 초기 그레이드 값입니다. 이 인덱스의 그레이드 엔트리가 대응하는 랭크 캡을 정의하므로, 이 값이 연동된 GS2-Experience 모델의 시작 랭크 캡을 결정합니다. |
---
### GradeEntryModel
그레이드 엔트리 모델
그레이드 값과 연동된 GS2-Experience 모델의 랭크 캡 간의 매핑을 정의합니다. 각 항목은 프로퍼티 ID 매칭에 사용되는 정규 표현식 패턴도 지정하여, 그레이드업 조작에 사용할 수 있는 리소스와 그 프로퍼티 ID의 변환 방법을 결정합니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| metadata | string | | | | ~ 2048자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| rankCapValue | long | | ✓ | | 0 ~ 9223372036854775805 | 랭크 캡 값
이 그레이드가 적용되었을 때 연동된 GS2-Experience 모델에 설정할 랭크 캡 값입니다. 플레이어의 그레이드가 이 항목에 대응하는 값으로 변경되면, 관련된 경험치 스테이터스의 랭크 캡이 이 값으로 자동 업데이트되어 도달 가능한 최대 랭크가 제어됩니다. |
| propertyIdRegex | string | | ✓ | | ~ 1024자 | 프로퍼티 ID 정규 표현식
그레이드업 매칭용 변수를 추출하기 위해 그레이드 스테이터스의 프로퍼티 ID에 적용되는 정규 표현식 패턴입니다. 이 패턴 내의 캡처 그룹(괄호로 둘러싸인 부분)은 gradeUpPropertyIdRegex에서 $1, $2 등으로 사용할 수 있습니다. 예를 들어 "character-(.+)"와 같은 패턴은 캐릭터 식별자를 추출하여 그레이드업 소재의 프로퍼티 ID 매칭에 사용합니다. |
| gradeUpPropertyIdRegex | string | | ✓ | | ~ 1024자 | 그레이드업용 프로퍼티 ID 정규 표현식
그레이드 승급을 위해 소비할 수 있는 리소스의 프로퍼티 ID를 특정하는 정규 표현식 패턴입니다. 이 패턴은 propertyIdRegex의 캡처 그룹을 $1, $2 등으로 참조할 수 있습니다. 예를 들어 propertyIdRegex에서 "sword-001"을 $1로 추출한 경우, 이 패턴을 "grade-up-material-$1"로 설정하면 해당 검에 고유한 소재를 매칭시킬 수 있습니다. |
---
### AcquireActionRate
보상 가산 테이블
현재 그레이드 값을 기준으로 보상량을 조정하는 이름이 지정된 배율 테이블을 정의합니다. 각 그레이드 값은 트랜잭션의 입수 액션에 적용되는 배율에 매핑되며, 그레이드가 높은 캐릭터나 장비일수록 더 많은 보상을 받을 수 있습니다. 표준적인 배정밀도 부동소수점수 모드와, 매우 큰 값에 대응하는 빅 넘버 모드를 모두 지원합니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string | | ✓ | | ~ 128자 | 보상 가산 테이블 이름
그레이드 모델 내에서 이 배율 테이블을 고유하게 식별하는 이름입니다. 트랜잭션의 특정 입수 액션에 그레이드 기반 보상 스케일링을 적용할 때 참조됩니다. |
| mode | 문자열 열거형
enum {
"double",
"big"
}
| | | "double" | | 보상 가산 테이블 종류
배율 값의 수치 정밀도 모드를 선택합니다. "double" 모드는 대부분의 경우에 적합한 표준 부동소수점수를 사용합니다. "big" 모드는 최대 1024자리까지의 문자열 표현 숫자를 사용하여, 매우 큰 값 계산이 필요한 게임에 대응합니다.double: 2^48 미만의 부동소수점 수 / big: 문자열 표기로 1024자리 미만의 부동소수점 수 / |
| rates | List<double> | {mode} == "double" | ✓※ | | 1 ~ 1000 items | 그레이드별 배율 리스트 (double 모드)
그레이드 값으로 인덱싱된 보상 배율의 배열로, 배정밀도 부동소수점수를 사용합니다. 인덱스 0의 항목이 그레이드 0의 배율, 인덱스 1이 그레이드 1의 배율이 됩니다. mode가 "double"로 설정된 경우에 사용됩니다.
※ mode이(가) "double" 이면 필수 |
| bigRates | List<string> | {mode} == "big" | ✓※ | | 1 ~ 1000 items | 그레이드별 배율 리스트 (big 모드)
그레이드 값으로 인덱싱된 보상 배율의 배열로, 확장된 정밀도를 위해 문자열 표현 숫자를 사용합니다. 인덱스 0의 항목이 그레이드 0의 배율, 인덱스 1이 그레이드 1의 배율이 됩니다. 매우 큰 수치 계산이 필요한 게임을 위해 mode가 "big"으로 설정된 경우에 사용됩니다.
※ mode이(가) "big" 이면 필수 |
---