GS2-Ranking2 마스터 데이터 레퍼런스
마스터 데이터 포맷과 임포트할 각종 모델의 레퍼런스
마스터 데이터 포맷
{
"version": "2024-05-30",
"globalRankingModels": [
{
"name": "[string]글로벌 랭킹 모델 이름",
"metadata": "[string?]메타데이터",
"minimumValue": "[long?]스코어 최솟값",
"maximumValue": "[long?]스코어 최댓값",
"sum": "[bool]스코어 합산",
"orderDirection": "[문자열 열거형]정렬 방향",
"entryPeriodEventId": "[string?]스코어 등록 가능 기간 이벤트 GRN",
"rankingRewards": [
{
"thresholdRank": "[int]순위 임계값",
"metadata": "[string?]메타데이터",
"acquireActions": [
{
"action": "[string]입수 액션에서 실행할 액션의 종류",
"request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
}
]
}
],
"accessPeriodEventId": "[string?]랭킹 데이터 접근 가능 기간 이벤트 GRN",
"rewardCalculationIndex": "[문자열 열거형]보상 계산 인덱스"
}
],
"clusterRankingModels": [
{
"name": "[string]클러스터 랭킹 모델 이름",
"metadata": "[string?]메타데이터",
"clusterType": "[문자열 열거형]클러스터 타입",
"minimumValue": "[long?]최소 점수",
"maximumValue": "[long?]최대 점수",
"sum": "[bool]점수 합산",
"orderDirection": "[문자열 열거형]정렬 방향",
"entryPeriodEventId": "[string?]스코어 등록 가능 기간 이벤트 GRN",
"rankingRewards": [
{
"thresholdRank": "[int]순위 임계값",
"metadata": "[string?]메타데이터",
"acquireActions": [
{
"action": "[string]입수 액션에서 실행할 액션의 종류",
"request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
}
]
}
],
"accessPeriodEventId": "[string?]랭킹 데이터 접근 가능 기간 이벤트 GRN",
"rewardCalculationIndex": "[문자열 열거형]보상 계산 인덱스"
}
],
"subscribeRankingModels": [
{
"name": "[string]구독 랭킹 모델 이름",
"metadata": "[string?]메타데이터",
"minimumValue": "[long?]최소 점수",
"maximumValue": "[long?]최대 점수",
"sum": "[bool]점수 합산",
"orderDirection": "[문자열 열거형]정렬 방향",
"entryPeriodEventId": "[string?]스코어 등록 가능 기간 이벤트 GRN",
"accessPeriodEventId": "[string?]랭킹 데이터 접근 가능 기간 이벤트 GRN"
}
]
}| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| version | string | ✓ | 2024-05-30 | 마스터 데이터 포맷 버전 | ||
| globalRankingModels | List<GlobalRankingModel> | ~ 10 items | 글로벌 랭킹 모델 글로벌 랭킹은 모든 플레이어를 대상으로 한 랭킹을 구현하기 위한 모델입니다. 상위 1000위까지의 랭킹을 표시할 수 있습니다. GS2-Schedule의 반복 이벤트와 연결하면 반복 횟수에 따라 랭킹을 초기화할 수 있습니다. | |||
| clusterRankingModels | List<ClusterRankingModel> | ~ 10 items | 클러스터 랭킹 모델 클러스터 랭킹은 길드나 게더링 내의 플레이어를 대상으로 하는 랭킹을 구현하기 위한 모델입니다. 상위 1000위까지의 랭킹을 표시할 수 있습니다. GS2-Schedule의 반복 이벤트와 연동하면 반복 횟수에 따라 랭킹을 초기화할 수 있습니다. | |||
| subscribeRankingModels | List<SubscribeRankingModel> | ~ 10 items | 구독 랭킹 모델 구독한 다른 플레이어의 점수를 집계하여 랭킹을 작성하는 모델입니다. |
모델
GlobalRankingModel
글로벌 랭킹 모델
글로벌 랭킹은 모든 플레이어를 대상으로 한 랭킹을 구현하기 위한 모델입니다.
상위 1000위까지의 랭킹을 표시할 수 있습니다.
GS2-Schedule의 반복 이벤트와 연결하면 반복 횟수에 따라 랭킹을 초기화할 수 있습니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| globalRankingModelId | string | ※ | ~ 1024자 | 글로벌 랭킹 GRN
※ 서버가 자동으로 설정 | ||||||||
| name | string | ✓ | ~ 128자 | 글로벌 랭킹 모델 이름 글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||
| metadata | string | ~ 1024자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||||||||
| minimumValue | long | 0 ~ 9223372036854775805 | 스코어 최솟값 허용되는 스코어의 최솟값입니다. 이 값보다 낮은 스코어는 등록 시 거부됩니다. 유효하지 않거나 의도하지 않은 스코어 값을 필터링하는 데 사용합니다. | |||||||||
| maximumValue | long | 0 ~ 9223372036854775805 | 스코어 최댓값 허용되는 스코어의 최댓값입니다. 이 값을 초과하는 스코어는 등록 시 거부됩니다. 비정상적으로 높은 스코어의 등록을 방지하는 데 사용합니다. | |||||||||
| sum | bool | false | 스코어 합산 활성화하면 등록된 모든 스코어가 합산되어 합계 값으로 랭킹이 결정됩니다. 비활성화된 경우, 정렬 방향에 따른 최적의 스코어(최댓값 또는 최솟값)만 랭킹에 사용됩니다. | |||||||||
| orderDirection | 문자열 열거형 enum { “asc”, “desc” } | ✓ | 정렬 방향 랭킹 스코어의 정렬 방향입니다. 낮은 스코어일수록 상위인 경우(예: 타임어택)에는 “오름차순"을, 높은 스코어일수록 상위인 경우(예: 하이스코어)에는 “내림차순"을 사용합니다.
| |||||||||
| entryPeriodEventId | string | ~ 1024자 | 스코어 등록 가능 기간 이벤트 GRN
스코어를 등록할 수 있는 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. 반복 이벤트와 연결하면 반복 사이클마다 랭킹이 초기화되어 시즌제 랭킹을 구현할 수 있습니다. | |||||||||
| rankingRewards | List<RankingReward> | {entryPeriodEventId} != null | [] | 0 ~ 100 items | 랭킹 보상 목록 각 시즌 종료 시의 랭킹 순위에 따라 지급되는 보상 목록입니다. 스코어 등록 가능 기간 이벤트가 설정되어 있는 경우에만 이용할 수 있습니다. 각 보상은 순위 임계값과 실행할 입수 액션을 정의합니다. | |||||||
| accessPeriodEventId | string | ~ 1024자 | 랭킹 데이터 접근 가능 기간 이벤트 GRN
랭킹 결과의 열람과 보상 수령이 가능한 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. 일반적으로 스코어 등록 기간 사이의 간격으로 설정합니다. | |||||||||
| rewardCalculationIndex | 문자열 열거형 enum { “rank”, “index” } | “rank” | 보상 계산 인덱스 보상을 플레이어에게 대응시키는 방법을 결정합니다. “순위 기반"은 1부터 시작하는 랭킹 순위를 사용하며(동점 스코어의 플레이어는 동일한 순위를 공유), “인덱스 기반"은 0부터 시작하는 고유한 정렬 위치를 사용합니다(동일 순위 없음). 일반적인 사용 사례에서는 “순위 기반"을 선택하시기 바랍니다.
|
RankingReward
랭킹 보상
점수 등록 기간이 설정된 랭킹에서, 등록 기간 외 참조 기간 내에 받을 수 있는 보상을 설정합니다.
반복 설정이 유효한 경우, 가장 최근에 종료된 기간의 랭킹이 보상 수령 대상이 됩니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| thresholdRank | int | ✓ | 1 ~ 1001 | 순위 임계값 이 보상 티어의 순위 임계값입니다. 순위(또는 인덱스, rewardCalculationIndex 설정에 따라 다름)가 이 임계값 이상인 플레이어가 이 보상을 받습니다. 1001로 설정하면 랭크 외(상위 1000위 밖) 플레이어를 위한 보상을 정의할 수 있습니다. | ||
| metadata | string | ~ 1024자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||
| acquireActions | List<AcquireAction> | [] | 0 ~ 100 items | 입수 액션 리스트 플레이어가 이 랭킹 보상을 수령할 때 실행되는 입수 액션의 목록입니다. 이 순위 임계값을 달성한 보상으로 지급되는 아이템, 화폐, 기타 리소스를 정의합니다. |
AcquireAction
입수 액션
ClusterRankingModel
클러스터 랭킹 모델
클러스터 랭킹은 길드나 게더링 내의 플레이어를 대상으로 하는 랭킹을 구현하기 위한 모델입니다.
상위 1000위까지의 랭킹을 표시할 수 있습니다.
GS2-Schedule의 반복 이벤트와 연동하면 반복 횟수에 따라 랭킹을 초기화할 수 있습니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| clusterRankingModelId | string | ※ | ~ 1024자 | 클러스터 랭킹 GRN
※ 서버가 자동으로 설정 | ||||||||||
| name | string | ✓ | ~ 128자 | 클러스터 랭킹 모델 이름 클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||||
| metadata | string | ~ 1024자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||||||||||
| clusterType | 문자열 열거형 enum { “Raw”, “Gs2Guild::Guild”, “Gs2Matchmaking::SeasonGathering” } | ✓ | 클러스터 타입 랭킹의 세그멘테이션에 사용하는 그룹(클러스터)의 종류를 정의합니다. “Raw"는 소속 검증 없이 임의의 클러스터 이름을 지정할 수 있으며, “Gs2Guild::Guild"는 GS2-Guild 길드에 대한 소속을 검증하고, “Gs2Matchmaking::SeasonGathering"은 GS2-Matchmaking 시즌 개더링에 대한 소속을 검증합니다.
| |||||||||||
| minimumValue | long | 0 ~ 9223372036854775805 | 최소 점수 허용되는 점수의 최소값입니다. 이 값보다 낮은 점수는 등록 시 거부됩니다. | |||||||||||
| maximumValue | long | 0 ~ 9223372036854775805 | 최대 점수 허용되는 점수의 최대값입니다. 이 값을 초과하는 점수는 등록 시 거부됩니다. | |||||||||||
| sum | bool | false | 점수 합산 활성화하면 등록된 모든 점수가 합산되어 합계값으로 랭킹이 결정됩니다. 비활성화된 경우 최고 점수만 랭킹에 사용됩니다. | |||||||||||
| orderDirection | 문자열 열거형 enum { “asc”, “desc” } | ✓ | 정렬 방향 랭킹 점수의 정렬 방향입니다. 점수가 낮을수록 상위인 경우 “오름차순”, 점수가 높을수록 상위인 경우 “내림차순"을 사용합니다.
| |||||||||||
| entryPeriodEventId | string | ~ 1024자 | 스코어 등록 가능 기간 이벤트 GRN
스코어를 등록할 수 있는 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. 반복 이벤트와 연결하면 시즌제 랭킹을 구현할 수 있습니다. | |||||||||||
| rankingRewards | List<RankingReward> | {entryPeriodEventId} != null | [] | 0 ~ 100 items | 랭킹 보상 목록 각 시즌 종료 시의 랭킹 순위에 따라 지급되는 보상 목록입니다. 스코어 등록 가능 기간 이벤트가 설정되어 있는 경우에만 이용할 수 있습니다. | |||||||||
| accessPeriodEventId | string | ~ 1024자 | 랭킹 데이터 접근 가능 기간 이벤트 GRN
랭킹 결과의 열람과 보상 수령이 가능한 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. | |||||||||||
| rewardCalculationIndex | 문자열 열거형 enum { “rank”, “index” } | “rank” | 보상 계산 인덱스 보상을 플레이어에게 대응시키는 방법을 결정합니다. “순위 기반"은 1부터 시작하는 랭킹 순위(동점 스코어는 동일 순위), “인덱스 기반"은 0부터 시작하는 고유한 정렬 위치(동일 순위 없음)를 사용합니다.
|
SubscribeRankingModel
구독 랭킹 모델
구독한 다른 플레이어의 점수를 집계하여 랭킹을 작성하는 모델입니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| subscribeRankingModelId | string | ※ | ~ 1024자 | 구독 랭킹 GRN
※ 서버가 자동으로 설정 | ||||||||
| name | string | ✓ | ~ 128자 | 구독 랭킹 모델 이름 구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||
| metadata | string | ~ 1024자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||||||||
| minimumValue | long | 0 ~ 9223372036854775805 | 최소 점수 허용되는 점수의 최소값입니다. 이 값보다 낮은 점수는 등록 시 거부됩니다. | |||||||||
| maximumValue | long | 0 ~ 9223372036854775805 | 최대 점수 허용되는 점수의 최대값입니다. 이 값을 초과하는 점수는 등록 시 거부됩니다. | |||||||||
| sum | bool | false | 점수 합산 활성화하면 등록된 모든 점수가 합산되어 합계값으로 랭킹이 결정됩니다. 비활성화된 경우 최고 점수만 랭킹에 사용됩니다. | |||||||||
| orderDirection | 문자열 열거형 enum { “asc”, “desc” } | ✓ | 정렬 방향 랭킹 점수의 정렬 방향입니다. 점수가 낮을수록 상위인 경우 “오름차순”, 점수가 높을수록 상위인 경우 “내림차순"을 사용합니다.
| |||||||||
| entryPeriodEventId | string | ~ 1024자 | 스코어 등록 가능 기간 이벤트 GRN
스코어를 등록할 수 있는 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. 반복 이벤트와 연결하면 시즌제 랭킹을 구현할 수 있습니다. | |||||||||
| accessPeriodEventId | string | ~ 1024자 | 랭킹 데이터 접근 가능 기간 이벤트 GRN
랭킹 결과를 열람할 수 있는 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. |