순위표(Leaderboard) 는 인게임 통계에 기반하여 순위를 매긴 플레이어 목록입니다. 순위표는 게임에서 높은 점수를 얻도록 플레이어, 친구들, 전 세계 다른 플레이어들 간의 경쟁을 장려합니다. 게임에는 점수를 부여하는 여러 개의 모드가 있을 수 있으며, 모드마다 하나 또는 여러 개의 자체 순위표를 보유할 수 있습니다.
순위표가 엔트리의 순위를 매기는 방식은 다음과 같습니다.
- 오름차순(Ascending): 점수가 낮을수록 높은 순위가 매겨집니다.
- 포트나이트 승리 순위표는 더 많이 승리할수록 좋으므로 내림차순으로 구성됩니다.
- 내림차순(Descending): 점수가 높을수록 높은 순위가 매겨집니다.
- 레이싱 게임의 랩타임 순위표는 랩타임이 빠를수록 좋으므로 오름차순으로 구성됩니다.
온라인 서비스 순위표 인터페이스(Online Services Leaderboards Interface) 는 개발자에게 게임 내에서 순위표를 표시하고 업데이트할 수 있는 도구를 제공합니다. 순위표 데이터는 게임에서 지원하는 각 순위표가 게임을 플레이한 모든 사용자 계정의 엔트리를 보유할 수 있으므로 용량이 매우 커질 수 있습니다. 따라서 순위표 인터페이스는 데이터를 청크로 가져옵니다. 순위표 인터페이스를 구현하는 게임은 아래 함수 섹션이나, 순위표 엔트리 읽기 섹션에서 자세히 설명한 것처럼 다양한 방식으로 순위표의 청크를 요청할 수 있습니다.
API 개요
함수
다음 표에는 순위표 인터페이스가 제공하는 함수에 대한 개요가 나와 있습니다.
| 함수 | 설명 |
|---|---|
ReadEntriesForUsers |
특정 사용자의 순위표 엔트리를 읽습니다. |
ReadEntriesAroundRank |
특정 순위 인덱스 주변의 순위표 엔트리를 읽습니다. |
ReadEntriesAroundUser |
특정 사용자 주변의 순위표 엔트리를 읽습니다. |
프라이머리 구조체
순위표 인터페이스의 주요 기능은 FLeaderboardEntry 구조체를 통해 커뮤니케이션하는 것입니다.
| 멤버 | 타입 | 설명 |
|---|---|---|
AccountId |
FAccountId |
이 순위표 엔트리의 계정 ID입니다. |
Rank |
int32 |
이 순위표에서 이 계정의 순위입니다. |
Score |
int64 |
이 순위표에서 이 계정의 점수입니다. |
환경설정
통계를 사용하여 순위표 점수를 업데이트하려면 DefaultEngine.ini 와 같은 엔진 환경설정 파일에서 순위표 인터페이스를 환경설정해야 합니다. 순위표 인터페이스는 순위표의 순위를 매기기 위한 통계를 추적하기 위해 통계 인터페이스와 함께 작동합니다.
일반 구문
DefaultEngine.ini
[OnlineServices.Leaderboards]
bIsTitleManaged=true
!LeaderboardDefinitions=ClearDefinitions
+LeaderboardDefinitions=(Name=<StatName0>, Id=<Id0>, UpdateMethod=[KeepBest | Force], OrderMethod=[Ascending | Descending])
+LeaderboardDefinitions=(Name=<StatName1>, Id=<Id1>, UpdateMethod=[KeepBest | Force], OrderMethod=[Ascending | Descending])
...
순위표가 통계 변경사항에 기반하여 업데이트되도록 하려면 bIsTitleManaged 플래그를 true 로 설정해야 합니다. 이 플래그는 클라이언트가 온라인 서비스 통계 인터페이스의 FStatsUpdated 이벤트를 리스닝하고 통계 변경사항에 반응하여 순위표를 자동으로 업데이트하도록 환경설정합니다. bIsTitleManaged 플래그의 디폴트값은 false 입니다. 이 플래그를 true 로 설정하지 않으면 순위표가 DefaultEngine.ini 의 순위표 정의에서 환경설정된 통계 변경사항을 기반으로 자동 업데이트되지 않습니다.
다음 순위표 정의 표는 엔진 환경설정 파일에 순위표 정의를 추가하는 구문을 설명합니다.
순위표 정의
| 필드 | 타입 | 설명 |
|---|---|---|
Name |
String |
순위를 결정하는 통계의 이름입니다. 이는 통계 인터페이스로 환경설정된 통계의 이름과 같아야 합니다. |
Id |
int |
이 순위표와 관련된 ID 번호입니다. 통계 인터페이스의 통계 ID와는 관련이 없습니다. |
UpdateMethod |
KeepBest 또는 Force |
이 순위표 엔트리를 업데이트하는 데 사용되는 메서드입니다. KeepBest 는 이 통계에서 지금까지 달성된 최고 값을 유지합니다. Force 는 플레이어의 순위 변화와는 관계없이 순위표 엔트리를 최신 통계 값으로 업데이트합니다. |
OrderMethod |
Ascending 또는 Descending |
낮은 통계 값과 높은 통계 값 중 어느 것에 높은 순위를 부여할지 결정합니다. Ascending 은 낮은 통계 값에 높은 순위를 부여합니다. Descending 은 높은 통계 값에 높은 순위를 부여합니다. |
환경설정 예시
타이틀이 '총 게임 포인트(Total Game Points)'인 단일 순위표가 있는 단순한 게임 하나를 예시로 들어 보겠습니다. 이 순위표는 다음과 같이 통계 인터페이스로 환경설정된 동일한 이름의 통계에 의해 추적됩니다.
DefaultEngine.ini
[OnlineServices.Stats]
!StatDefinitions=ClearDefinitions
+StatDefinitions=(Name=Total_Game_Points, Id=0, ModifyMethod=Sum)
[OnlineServices.Leaderboards]
bIsTitleManaged=true
!LeaderboardDefinitions=ClearDefinitions
+LeaderboardDefinitions=(Name=Total_Game_Points, Id=0, UpdateMethod=KeepBest, OrderMethod=Descending)
이 환경설정에서 순위표는 다음과 같은 특성을 지닙니다.
- 각 플레이어에 대해
Total_Game_Points통계의 최고 점수를 유지합니다. - 총점수가 높을수록 좋으므로 내림차순으로 구성됩니다.
순위표 엔트리 읽기
순위표 인터페이스로 순위표 엔트리를 읽는 3가지 방법이 있습니다. 순위표 엔트리는 다음과 같은 방식으로 읽을 수 있습니다.
아래는 각 메서드가 위의 환경설정 예시에서 환경설정된 '총 게임 포인트' 순위표를 통해 가져오는 내용을 시각적으로 표현한 것입니다.
특정 사용자
ReadEntriesForUsers 함수를 사용하여 특정 사용자의 순위표 엔트리를 가져올 수 있습니다. 이 함수는 쿼리하고 싶은 순위에 있는 개별 사용자의 사용자 ID 목록을 가져옵니다.
예시
아래에 타이틀이 '총 게임 포인트'인 순위표가 있으며, 다음 파라미터로 ReadEntriesForUsers 를 호출한다고 가정해 보겠습니다.
UE::Online::FReadEntriesForUsers::Params Params;
Params.LocalAccountId = "LLV54WB-3C678QQ";
Params.AccountIds = {"9P8H4GQ-HNO5GA4", "3CN9H8E-VNO3G3C", "OHB8RA2-OHSEBSE"};
Params.BoardName = TEXT("Total Game Points");
호출이 성공적으로 반환된 경우, 반환된 TOnlineResult 의 가져온 것으로 표시된 열에 액세스할 수 있습니다.
| 총 게임 포인트 | |||
|---|---|---|---|
| 계정 ID | 순위 | 점수 | 가져옴 여부 |
| 3CN9H8E-VNO3G3C | 1 | 1,901 | Y |
| LLV54WB-3C678QQ | 2 | 151 | |
| OHB8RA2-OHSEBSE | 3 | 17 | Y |
| 9P8H4GQ-HNO5GA4 | 4 | 3 | Y |
| 9HQGQER-ILASDFH | 5 | 1 |
특정 순위 주변
ReadEntriesAroundRank 함수를 사용하여 특정 순위표 순위 주변의 순위표 엔트리를 가져옵니다. 이 함수는 다음 사항을 가져옵니다.
- 순위표 엔트리 읽기를 시작할 순위
- 읽을 엔트리 수 제한
예시
아래에 '총 게임 포인트'라는 타이틀의 순위표가 있으며, 다음 파라미터로 ReadEntriesAroundRank 를 호출한다고 가정해 보겠습니다.
UE::Online::FReadEntriesAroundRank::Params Params;
Params.LocalAccountId = "LLV54WB-3C678QQ";
Params.Rank = 2;
Params.Limit = 2;
Params.BoardName = TEXT("Total Game Points");
호출이 성공적으로 반환된 경우, 반환된 TOnlineResult 의 가져온 것으로 표시된 열에 액세스할 수 있습니다.
| 총 게임 포인트 | |||
|---|---|---|---|
| 계정 ID | 순위 | 점수 | 가져옴 여부 |
| 3CN9H8E-VNO3G3C | 1 | 1,901 | |
| LLV54WB-3C678QQ | 2 | 151 | |
| OHB8RA2-OHSEBSE | 3 | 17 | Y |
| 9P8H4GQ-HNO5GA4 | 4 | 3 | Y |
| 9HQGQER-ILASDFH | 5 | 1 |
프로그래밍 관점에서 순위표 최상단 순위는 1이 아니라 0입니다. 따라서 3위의 엔트리를 가져오려면 ReadEntriesAroundRank 를 Params.Rank = 2 로 호출해야 합니다.
지정된 사용자 주변
ReadEntriesAroundUser 함수를 사용하여 특정 사용자 주변의 순위표 엔트리를 가져옵니다. 이 함수는 다음 사항을 가져옵니다.
- 주변 엔트리를 읽을 사용자
- 엔트리 읽기의 시작점을 표시할 오프셋
- 읽을 총 엔트리 수 제한
오프셋은 제한을 초과할 수 있습니다. 이 경우, 제공된 사용자가 순위표 엔트리의 반환된 배열에 표시되지 않습니다. 이는 확인을 목적으로 페이지에 순위표 엔트리를 정리할 때 유용합니다.
예시
아래에 '총 게임 포인트'라는 타이틀의 순위표가 있으며, 다음 파라미터로 ReadEntriesAroundUser 를 호출한다고 가정해 보겠습니다.
UE::Online::FReadEntriesAroundUser::Params Params;
Params.LocalAccountId = "LLV54WB-3C678QQ";
Params.Offset = -1;
Params.Limit = 3;
Params.BoardName = TEXT("Total Game Points");
호출이 성공적으로 반환된 경우, 반환된 TOnlineResult 의 가져온 것으로 표시된 열에 액세스할 수 있습니다.
| 총 게임 포인트 | |||
|---|---|---|---|
| 계정 ID | 순위 | 점수 | 가져옴 여부 |
| 3CN9H8E-VNO3G3C | 1 | 1,901 | Y |
| LLV54WB-3C678QQ | 2 | 151 | Y |
| OHB8RA2-OHSEBSE | 3 | 17 | Y |
| 9P8H4GQ-HNO5GA4 | 4 | 3 | |
| 9HQGQER-ILASDFH | 5 | 1 |
추가 정보
헤더 파일
자세한 정보가 필요한 경우 Leaderboards.h 헤더 파일을 직접 참조하세요. 순위표 인터페이스 헤더 파일 Leaderboards.h 의 디렉터리 위치는 다음과 같습니다.
UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE 소스 코드를 얻는 방법에 대한 지침은 언리얼 엔진 소스 코드 내려받기 문서를 참조하세요.
함수 파라미터 및 반환 타입
파라미터를 전달하고 함수의 반환 결과를 처리하는 방법을 비롯하여 함수 파라미터 및 반환 타입에 대한 자세한 설명은 온라인 서비스 개요 페이지의 함수 섹션을 참조하세요.
