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

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

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




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2019-09-17",
  "categories": [
    {
      "name": "[string]카테고리 모델 이름",
      "metadata": "[string?]메타데이터",
      "minimumValue": "[long?]점수 최솟값",
      "maximumValue": "[long?]점수 최댓값",
      "sum": "[bool]합산 모드",
      "orderDirection": "[문자열 열거형]정렬 방향",
      "scope": "[문자열 열거형]랭킹 종류",
      "globalRankingSetting": {
        "uniqueByUserId": "[bool]사용자 ID별 유니크",
        "calculateIntervalMinutes": "[int]집계 간격(분)",
        "calculateFixedTiming": {
          "hour": "[int?]시",
          "minute": "[int?]분"
        },
        "additionalScopes": [
          {
            "name": "[string]스코프 이름",
            "targetDays": "[long]집계 대상 일수"
          }
        ],
        "ignoreUserIds": [
          "[string]랭킹에 반영하지 않을 사용자 ID"
        ],
        "generation": "[string?]세대"
      },
      "entryPeriodEventId": "[string?]점수 등록 기간 이벤트 ID",
      "accessPeriodEventId": "[string?]접근 기간 이벤트 ID"
    }
  ]
}
```


|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2019-09-17 | | 마스터 데이터 포맷 버전 |
| categories | [List&lt;CategoryModel&gt;](#categorymodel) |  |  |  |  ~ 1000 items | 카테고리 모델<br>카테고리마다 서로 다른 랭킹을 생성할 수 있습니다.<br><br>카테고리에는 등록 가능한 스코어의 최소값·최대값을 설정할 수 있으며, 해당 범위를 벗어나는 스코어는 폐기됩니다.<br>랭킹을 집계할 때 스코어가 작은 것을 상위(오름차순)로 할지, 큰 것을 상위(내림차순)로 할지를 설정할 수 있습니다.<br><br>랭킹의 종류로 `글로벌`과 `스코프`를 선택할 수 있습니다.<br>글로벌은 모든 플레이어가 동일한 결과를 참조하는 것이며, 스코프는 친구 내 랭킹이나 길드 내 랭킹처럼 게임 플레이어마다 결과가 다른 랭킹입니다.<br><br>글로벌 랭킹은 카테고리별로 랭킹 집계 간격을 15분~24시간으로 설정할 수 있습니다.<br>스코프 랭킹은 실시간으로 집계 결과가 반영됩니다.<br><br>랭킹 데이터에는 세대라는 설정이 있으며, 세대를 변경함으로써 등록된 스코어를 리셋할 수 있습니다. |

## 모델

### CategoryModel

카테고리 모델<br>

카테고리마다 서로 다른 랭킹을 생성할 수 있습니다.<br>

카테고리에는 등록 가능한 스코어의 최소값·최대값을 설정할 수 있으며, 해당 범위를 벗어나는 스코어는 폐기됩니다.<br>
랭킹을 집계할 때 스코어가 작은 것을 상위(오름차순)로 할지, 큰 것을 상위(내림차순)로 할지를 설정할 수 있습니다.<br>

랭킹의 종류로 `글로벌`과 `스코프`를 선택할 수 있습니다.<br>
글로벌은 모든 플레이어가 동일한 결과를 참조하는 것이며, 스코프는 친구 내 랭킹이나 길드 내 랭킹처럼 게임 플레이어마다 결과가 다른 랭킹입니다.<br>

글로벌 랭킹은 카테고리별로 랭킹 집계 간격을 15분~24시간으로 설정할 수 있습니다.<br>
스코프 랭킹은 실시간으로 집계 결과가 반영됩니다.<br>

랭킹 데이터에는 세대라는 설정이 있으며, 세대를 변경함으로써 등록된 스코어를 리셋할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| categoryModelId | string |  | ※ |  |  ~ 1024자 | 카테고리 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 카테고리 모델 이름<br>카테고리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 1024자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| minimumValue | long |  |  |  | 0 ~ 9223372036854775805 | 점수 최솟값<br>이 카테고리에 등록할 수 있는 점수의 최솟값입니다.<br>이 임곗값보다 낮은 점수는 등록 시 거부됩니다. 설정하지 않으면 하한이 없습니다. |
| maximumValue | long |  |  |  | 0 ~ 9223372036854775805 | 점수 최댓값<br>이 카테고리에 등록할 수 있는 점수의 최댓값입니다.<br>이 임곗값보다 높은 점수는 등록 시 거부됩니다. 설정하지 않으면 상한이 없습니다. |
| sum | bool |  |  | false |  | 합산 모드<br>활성화하면 새로 등록된 점수가 기존 점수를 대체하는 것이 아니라 합계에 더해집니다.<br>랭킹은 누적된 합계값을 기준으로 계산됩니다. 비활성화된 경우 각 점수 등록은 독립된 항목으로 처리됩니다. |
| orderDirection | 문자열 열거형<br>enum {<br>"asc",<br>"desc"<br>}<br> |  | ✓ |  |  | 정렬 방향<br>랭킹 집계의 정렬 순서를 결정합니다.<br>"asc"(오름차순)는 낮은 점수를 상위로 하며, 시간 기반이나 골프식 랭킹에 적합합니다.<br>"desc"(내림차순)는 높은 점수를 상위로 하며, 포인트 기반이나 하이스코어 랭킹에 적합합니다.asc: 오름차순 / desc: 내림차순 /  |
| scope | 문자열 열거형<br>enum {<br>"global",<br>"scoped"<br>}<br> |  | ✓ |  |  | 랭킹 종류<br>이 카테고리의 랭킹 타입입니다.<br>"global" 은 모든 플레이어가 공유하는 단일 리더보드를 만들며, 설정된 간격으로 배치 집계됩니다.<br>"scoped" 는 구독한 플레이어(친구나 길드 멤버 등)를 기반으로 한 사용자별 리더보드를 만들며, 점수가 실시간으로 반영됩니다.global: 글로벌 / scoped: 스코프 /  |
| globalRankingSetting | [GlobalRankingSetting](#globalrankingsetting) | {scope} == "global" | ✓※ |  |  | 글로벌 랭킹 설정<br>글로벌 랭킹 모드 전용 설정입니다. 집계 간격, 고정 시각, 점수의 유니크 여부, 세대 관리, 추가 기간 한정 스코프를 포함합니다.<br>scope 가 "global" 로 설정된 경우에만 적용됩니다.<br>※ scope이(가) "global" 이면 필수 |
| entryPeriodEventId | string |  |  |  |  ~ 1024자 | 점수 등록 기간 이벤트 ID<br>점수 등록을 받는 기간을 정의하는 GS2-Schedule 이벤트의 GRN입니다.<br>이 기간 외의 점수 등록 요청은 거부됩니다. 설정하지 않으면 점수는 언제든지 등록할 수 있습니다. |
| accessPeriodEventId | string |  |  |  |  ~ 1024자 | 접근 기간 이벤트 ID<br>랭킹 데이터를 열람할 수 있는 기간을 정의하는 GS2-Schedule 이벤트의 GRN입니다.<br>이 기간 외의 랭킹 조회 요청은 거부됩니다. 설정하지 않으면 랭킹은 언제든지 접근할 수 있습니다. |

---

### Scope

집계 스코프<br>

글로벌 랭킹 모드에서의 추가적인 기간 한정 집계 스코프를 정의합니다.<br>
일반적으로 글로벌 랭킹은 등록된 모든 스코어를 대상으로 집계됩니다.<br>
스코프를 추가하면 지정한 일수 이내에 등록된 스코어만을 대상으로 하는 별도의 랭킹을 생성할 수 있으며, 전체 기간 랭킹과 함께 데일리·위클리·먼슬리 등의 리더보드를 구현할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 스코프 이름<br>카테고리 내에서 이 집계 스코프를 고유하게 식별하는 이름입니다.<br>여러 개의 기간 한정 랭킹 보드를 구분하기 위해 사용됩니다(예: "daily", "weekly"). 최대 128자. |
| targetDays | long |  | ✓ |  | 1 ~ 365 | 집계 대상 일수<br>집계 윈도우에 포함할 일수입니다.<br>현재 시각으로부터 이 일수 이내에 등록된 스코어만 스코프 랭킹의 대상이 됩니다. 범위: 1~365일. |

---

### GlobalRankingSetting

글로벌 랭킹 설정<br>

글로벌은 모든 플레이어가 동일한 결과를 참조하는 방식입니다.<br>
랭킹 집계 간격은 15분~24시간으로 설정할 수 있습니다.<br>

랭킹 데이터에는 세대라는 설정이 있으며, 세대를 변경함으로써 등록된 점수를 초기화할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| uniqueByUserId | bool |  |  | true |  | 사용자 ID별 유니크<br>활성화하면 랭킹 내에서 사용자 ID별로 하나의 점수만 유지됩니다.<br>사용자가 새로운 점수를 등록하면 정렬 방향에 따라 더 나은 점수로 교체됩니다.<br>비활성화하면 동일 사용자로부터 여러 점수 항목이 허용되어 합산 모드나 다중 항목 경쟁이 가능해집니다. |
| calculateIntervalMinutes | int |  | ✓ |  | 15 ~ 1440 | 집계 간격(분)<br>연속되는 랭킹 재집계 사이의 간격(분)입니다.<br>시스템은 이 간격으로 등록된 모든 점수를 기반으로 글로벌 랭킹을 정기적으로 재집계합니다.<br>범위: 15~1440분(15분~24시간). |
| calculateFixedTiming | [FixedTiming](#fixedtiming) |  |  |  |  | 집계 시각 고정 설정<br>랭킹 재집계가 시작되는 하루 중 고정 시각(UTC)을 지정합니다.<br>설정하지 않으면 재집계는 정해지지 않은 기준 시각부터 일정 간격으로 실행됩니다.<br>이를 설정하면 매일 예측 가능하고 일관된 시각에 재집계가 이루어지도록 할 수 있습니다. |
| additionalScopes | [List&lt;Scope&gt;](#scope) |  |  |  | 0 ~ 10 items | 추가 스코프 목록<br>추가적인 기간 한정 집계 스코프 목록입니다.<br>각 스코프는 지정한 일수 이내에 등록된 점수만을 대상으로 하는 별도의 랭킹을 정의합니다.<br>전체 기간의 글로벌 랭킹과 함께 데일리·위클리·먼슬리 등의 리더보드를 만들 수 있습니다. 최대 10건. |
| ignoreUserIds | List&lt;string&gt; |  |  |  | 0 ~ 10000 items | 제외 사용자 ID 목록<br>랭킹 집계에서 점수를 제외할 사용자 ID 목록입니다.<br>테스트 계정, 관리자 계정 또는 알려진 부정 사용자를 리더보드에서 제외하는 데 사용합니다. 최대 10,000건. |
| generation | string |  |  |  |  ~ 256자 | 세대<br>현재 랭킹 세대를 나타내는 임의의 문자열입니다.<br>이 값을 변경하면 이전 세대의 점수는 랭킹 집계에 포함되지 않으므로 사실상 점수가 초기화됩니다.<br>시즌제 초기화나 정기적인 랭킹 초기화를 구현하는 데 사용합니다. 최대 256자. |

---

### FixedTiming

집계 시각 고정 설정<br>

글로벌 랭킹의 집계가 시작되는 고정 시각을 지정합니다.<br>
이 설정이 없으면 랭킹 집계는 정해지지 않은 기준 시각부터 일정 간격으로 실행됩니다.<br>
고정된 시·분을 지정함으로써 매일의 집계 시작 시각(UTC)을 예측 가능하게 할 수 있으며, 자정이나 특정 시각에 집계를 시작하도록 제어할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| hour | int |  |  |  | 0 ~ 23 | 시<br>랭킹 집계가 시작되는 시각의 시(UTC)입니다.<br>0~23 사이의 정수로 지정합니다. |
| minute | int |  |  |  | 0 ~ 59 | 분<br>지정한 시각의 분입니다.<br>0~59 사이의 정수로 지정합니다. |

---