리더보드 인터페이스

온라인 리더보드를 처리하는 인터페이스

리더보드 인터페이스(Leaderboards Interface)에픽 온라인 서비스(EOS) 를 사용하는 개발자들이 전체 플레이어층의 점수에 순위를 매길 수 있는 기능을 제공합니다. 그러므로 플레이어들은 친구들이나 다른 전 세계 플레이어들과 함께 상위권을 목표로 경쟁할 수 있습니다. 각 게임은 여러 개의 리더보드를 지원하므로 다양한 소스로부터 점수를 수집하고 다양한 득점 모드로 순위를 매길 수 있습니다.

리더보드 인터페이스에 액세스하려면 플랫폼 인터페이스 함수인 EOS_Platform_GetLeaderboardsInterface`를 통해 EOS_HLeaderboards 핸들을 얻어야 합니다. 모든 리더보드 인터페이스 함수에는 첫 파라미터로 이 핸들이 필요합니다. 작업이 완료되었을 때 콜백을 트리거하려면 EOS_HPlatform` 핸들의 틱이 실행 중인지 확인해야 합니다.

리더보드 인터페이스는 리더보드를 구성하고 관리하지만 점수 데이터로 리더보드를 채우지는 않습니다. 대신, 리더보드는 통계 인터페이스가 생성하고 유지하는 데이터를 가져옵니다.

리더보드 생성하기

게임 내 리더보드에 액세스하려면 먼저 개발자 포털을 사용해서 리더보드가 추적할 통계를 설정하고(자세한 내용은 통계 인터페이스 참조) 리더보드 자체를 정의해야 합니다. 리더보드를 정의하려면 다음을 지정해야 합니다.

  • 리더보드가 추적하는 통계(또는 점수)

  • 리더보드가 플레이어 순위 지정에 사용하는 메서드

  • 리더보드 전체 수명의 시작/종료 시간

통계와 리더보드를 설정하고 나면 EOS SDK를 통해 액세스할 수 있습니다.

통계 및 마일스톤

EOS 리더보드는 EOS 통계 시스템으로 구동됩니다. 각 리더보드는 특정 통계를 추적 점수로 사용합니다. 자세한 내용은 통계 인터페이스를 참조하세요.

EOS 리더보드 인터페이스는 전 세계의 순위 데이터와 순위가 지정되지 않은 친구 데이터를 쿼리할 수 있도록 지원합니다. 시스템의 어느 통계든 친구, 클랜 또는 다른 그룹 기반의 리더보드로 사용할 수 있으며, 개별 플레이어의 통계를 쿼리하기만 하면 확인할 수 있습니다. 반면에 글로벌 리더보드에는 구체적인 환경설정이 필요합니다. 확장성의 이유 때문에 사용자가 보유할 수 있는 글로벌 리더보드 수와 에픽에서 추적하는 리더보드의 실제 항목 수 둘 다 제한됩니다. 에픽은 전체 글로벌 리더보드를 추적하지는 않고, 상위 1,000개 점수(+ 추가분 1,000개)만 계속 추적합니다. 추가분 1,000개를 유지하는 이유는 개발자가 리더보드에서 몇몇 항목을 제거하는 경우(치트, 스머핑, 멤버 탈퇴 요청 등) 1,000위권의 빈 자리를 채울 값이 필요하기 때문입니다. 상위 항목 1,000개만 추적하면 대다수 플레이어들이 리더보드에 이름을 올리지 못하겠지만 글로벌 리더보드가 상위권 플레이어에게만 가치를 두는 점을 감안하면 이것이 더 나은 결정인 것 같습니다. 친구 리더보드와 다른 비공개 소규모 그룹은 플레이어에게 더 많은 인터랙션과 가치를 제공하며, 합리적으로 달성할 수 있는 목표와 함께 의미 있는 피드백을 제시합니다.

각 리더보드는 리더보드 상태를 정확히 계산하는 데 필요한 통계 집합을 비닝(bin)하기 위해 여러 가지 통계 마일스톤을 참조합니다. 사용자 한 명이 가질 수 있는 리더보드 수는 지정된 사용자 계정이 가질 수 있는 통계 마일스톤의 수량과 함수 관계에 있습니다. 다음 테이블은 각 리더보드 타입에 적용되는 이 함수를 설명합니다(현재는 한 가지 타입만 지원).

리더보드 타입

설명

마일스톤 참조 수

싱글톤 리더보드

단일 집계 창에서 정의한 리더보드(시작/종료 타임스탬프 쌍).

2

리더보드를 생성할 때 마일스톤이 참조되거나(재사용된다고 읽음), 사용자가 정의했거나 사용자를 위해 정의된 기존 마일스톤 세트에 비례하여 생성됩니다. 예를 들어보겠습니다. 10월 31일 08:00~16:00에 stat total_apples_collected(합계)를 기준으로 플레이어 순위를 정한 싱글톤 리더보드를 생성한다고 합시다. 마일스톤이 현재 없다고 가정하고 이 리더보드를 생성하면 다음과 같은 마일스톤이 생성됩니다.

Leaderboards_Milestones.png

08:00~16:00에 타임스탬프로 생성한 total_apples_collected 통계들이 모두 각 playerId마다 한 개의 합계 값으로 집계됩니다. 이렇게 모인 전체 플레이어의 값들은 에픽이 정의한 싱글톤 리더보드의 순위로 오릅니다.

마일스톤 재사용을 좀 더 명확히 알아보기 위해, total_pumpkins_collected`라는 다른 통계가 있고 이것으로 앞서와 같은 기간의 두 번째 싱글톤 리더보드를 원하는 경우를 가정해보겠습니다. 이 새로운 리더보드 생성 시 total_apples_collected`를 위해 생성했던 동일한 마일스톤을 참조/재사용하게 되며, 사용 가능한 마일스톤 수가 더 줄어들지도 않습니다.

마일스톤을 참조하는 리더보드가 없으면 시스템에서 자체적으로 마일스톤을 삭제합니다.

요약:

  • 총 글로벌 리더보드: 사용 가능한 마일스톤으로 한정(위 참조)

  • 최대 마일스톤 수(기본값): 100개

  • 총 글로벌 리더보드 항목 수: 1,000개(+추가분 1,000개)

점수 계산 방법

리더보드 인터페이스는 다양한 종류의 게임이나 순위 지정 시스템을 수용할 수 있도록 여러 가지 점수 계산 방법을 제공합니다. 리더보드는 점수 집계 타입(score aggregation type) 에 따라 점수를 계산하고 순위를 지정할 수 있습니다. 리더보드에 할당된 통계에서 사용하는 것과 동일한 집계 타입을 리더보드에도 사용해야 합니다. 사용 가능한 점수 집계 타입은 다음과 같습니다.

점수 집계 타입

리더보드 동작

EOS_LSA_Min

리더보드에 보고된 플레이어의 최저 점수를 사용합니다. 최저 점수의 플레이어가 1위가 됩니다.

EOS_LSA_Max

리더보드에 보고된 플레이어의 최고 점수를 사용합니다. 최고 점수의 플레이어가 1위가 됩니다.

EOS_LSA_Sum

리더보드에 각 플레이어가 보고하는 모든 점수를 합산합니다. 최고 총점의 플레이어가 1위가 됩니다.

또한 리더보드에서 점수 값으로 사용할 통계의 이름을 지정해야 합니다.

리더보드 정보에 액세스하기

리더보드 정보에 액세스하려면 리더보드 ID가 필요합니다. 리더보드 ID는 개발자 포털에서 찾아서 게임에 직접 추가할 수 있습니다. 아니면 자신의 게임과 관련된 모든 리더보드의 목록을 EOS SDK에 쿼리할 수도 있습니다. 이를 수행하려면 다음 정보로 초기화된 'EOS_Leaderboards_QueryLeaderboardDefinitionsOptions' 구조체를 사용하여 'EOS_Leaderboards_QueryLeaderboardDefinitions'를 호출합니다.

프로퍼티

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDDEFINITIONS_API_LATEST

StartTime

리더보드 시작 시간의 옵션 POSIX 타임스탬프 또는 EOS_LEADERBOARDS_TIME_UNDEFINED

EndTime

리더보드 종료 시간의 옵션 POSIX 타임스탬프 또는 EOS_LEADERBOARDS_TIME_UNDEFINED

LocalUserId

정의를 쿼리하는 사용자의 제품 사용자 ID

이 작업을 완료하고 나면 'EOS_Leaderboards_OnQueryLeaderboardDefinitionsCompleteCallback' 타입의 콜백이 성공 또는 실패를 나타내는 'EOS_Leaderboards_OnQueryLeaderboardDefinitionsCompleteCallbackInfo' 구조와 함께 실행됩니다. 성공하면 로컬 캐시에 기준을 충족하는 리더보드 목록이 포함됩니다. 그러면, 'EOS_Leaderboards_GetLeaderboardDefinitionCount'를 사용해서 시스템이 몇 개의 리더보드 정의를 찾았는지 확인하고 'EOS_Leaderboards_CopyLeaderboardDefinitionByIndex'를 호출해서 각 리더보드의 사본을 얻을 수 있습니다. 특정 리더보드 ID가 이미 목록에 들어 있을 것을 알고 있는 경우 'EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId'를 호출하면 해당 리더보드 정의의 사본을 얻을 수 있습니다.

'EOS_Leaderboards_CopyLeaderboardDefinitionByIndex'를 호출할 때는 다음과 같이 초기화된 'EOS_Leaderboards_CopyLeaderboardDefinitionByIndexOptions' 구조를 전달합니다.

프로퍼티

ApiVersion

EOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYINDEX_API_LATEST

'EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId'를 호출할 때는 다음과 같이 초기화된 'EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardIdOptions' 구조를 전달합니다.

프로퍼티

ApiVersion

EOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYLEADERBOARDID_API_LATEST

LeaderboardId

내가 정보를 얻으려는 리더보드의 ID

어느 경우든 리더보드를 정의하는 정보 사본을 받게 됩니다([EOS_Leaderboards_Definition] 타입(API:EOS_Leaderboards_Definition)). 이 정보가 더 이상 필요 없으면 'EOS_Leaderboards_LeaderboardDefinition_Release'를 호출하여 해제합니다.

리더보드 데이터 얻기

일반적으로 플레이어는 전 세계 리더보드 데이터를 보거나 친구의 데이터만 보기를 원합니다. 리더보드 인터페이스는 별도의 쿼리 메서드를 제공하여 데이터를 얻는 두 가지 방법을 모두 지원합니다.

전 세계 순위 데이터 얻기

리더보드의 전 세계 순위를 보려면 'EOS_Leaderboards_QueryLeaderboardRanksOptions' 구조와 함께 'EOS_Leaderboards_QueryLeaderboardRanks'를 호출합니다. 다음과 같이 구조를 초기화합니다.

프로퍼티

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDRANKS_API_LATEST

LeaderboardId

내가 정보를 얻으려는 리더보드의 ID

LocalUserId

순위를 쿼리하는 사용자의 제품 사용자 ID

작업이 완료되면 'EOS_Leaderboards_OnQueryLeaderboardRanksCompleteCallback'의 콜백 타입이 성공 또는 실패를 나타내는 'EOS_Leaderboards_OnQueryLeaderboardRanksCompleteCallbackInfo' 데이터 구조와 함께 실행됩니다. 성공하면 EOS SDK 캐시에 요청 데이터가 포함됩니다. 'EOS_Leaderboards_GetLeaderboardRecordCount'를 호출하여 기록 개수를 확인하고 'EOS_Leaderboards_CopyLeaderboardRecordByIndex'를 포함한 개별 기록의 사본을 얻을 수 있습니다. 특정 사용자에 대한 기록을 원하며 그 사용자의 ID를 아는 경우 'EOS_Leaderboards_CopyLeaderboardRecordByUserId'를 호출할 수 있습니다. 이들 두 함수는 캐시된 기록의 사본을 EOS_Leaderboards_LeaderboardRecord의 형태로 반환합니다. 사본이 더 이상 필요 없으면 'EOS_Leaderboards_LeaderboardRecord_Release'를 통해 해제합니다.

순위 미지정 친구의 데이터 얻기

어떤 플레이어에게 친구들의 점수 기록을 보여주려면 'EOS_Leaderboards_QueryLeaderboardUserScores'를 사용합니다. 다음과 같이 초기화된 'EOS_Leaderboards_QueryLeaderboardUserScoresOptions' 구조를 사용하여 이 함수를 호출합니다.

프로퍼티

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDUSERSCORES_API_LATEST

UserIds

점수를 얻으려는 사용자를 나타내는 EOS_ProductUserId 값의 배열

UserIdsCount

UserIds 파라미터에 포함된 ID의 개수

StatInfo

수집하려는 통계 그리고 각 통계에서 순위 순서를 지정할 때 사용하는 정렬 메서드

StatInfoCount

StatInfo 배열에 있는 요소의 개수

StartTime

옵션 POSIX 타임스탬프 또는 EOS_LEADERBOARDS_TIME_UNDEFINED, 결과에는 이 시간 이후에 득점한 점수만 반영

EndTime

옵션 POSIX 타임스탬프 또는 EOS_LEADERBOARDS_TIME_UNDEFINED, 결과에는 이 시간 이전에 득점한 점수만 반영

LocalUserId

사용자 점수를 쿼리하는 사용자의 제품 사용자 ID

이런 식으로 수집한 점수는 지정한 기준에 따라 정렬되지만 이는 리더보드의 점수가 아니며 리더보드를 요구하지는 않습니다. 이러한 점수에는 글로벌 순위가 없습니다. 'StatInfo' 필드는 비교할 통계뿐만 아니라 쿼리에서 얻은 다른 사용자 점수와 관련하여 사용할 순위 지정 메서드도 포함합니다.

작업이 끝난 후 'EOS_Leaderboards_OnQueryLeaderboardUserScoresCompleteCallback' 타입의 콜백이 성공 또는 실패를 나타내는 'EOS_Leaderboards_OnQueryLeaderboardUserScoresCompleteCallbackInfo' 데이터 구조와 함께 실행됩니다. 호출이 성공하면 순서대로 정리된 친구 점수 기록이 캐시에 포함됩니다. 'EOS_Leaderboards_GetLeaderboardUserScoreCount' 함수로 이용 가능한 기록 개수를 얻거나 'EOS_Leaderboards_CopyLeaderboardUserScoreByIndex'로 인덱스별 점수를 얻거나 'EOS_Leaderboards_CopyLeaderboardUserScoreByUserId'로 사용자 ID별 점수를 얻을 수 있습니다. 어느 경우든 해당 'EOS_Leaderboards_LeaderboardUserScore' 데이터 사본을 받습니다. 이 데이터가 더 이상 필요 없으면 'EOS_Leaderboards_LeaderboardUserScore_Release'를 사용해서 해제합니다.

사용 제한

퍼포먼스와 속도를 유지하기 위해 관리해야 하는 사용 제한에 대한 정보는 서비스 사용 제한 페이지를 확인하세요. 퍼포먼스와 속도를 유지하기 위해 지켜야 하는 사용 제한에 대한 정보는 서비스 사용 제한 페이지를 확인하세요. 퍼포먼스와 속도를 유지하기 위해 관리해야 하는 사용 제한에 대한 정보는 서비스 사용 제한 페이지를 확인하세요.