리더보드 인터페이스

에픽 온라인 서비스(Epic Online Services, EOS) 를 사용하는 개발자는 리더보드 인터페이스(Leaderboards Interface) 를 사용하여 전체 플레이어 기반의 점수에 순위를 매길 수 있습니다. 따라서 플레이어들이 친구나 전 세계의 다른 플레이어와 함께 최고 점수를 목표로 경쟁할 수 있습니다. 게임 하나당 여러 개의 리더보드를 지원하므로 다양한 소스에서 점수를 취합하여 각종 순위 모드로 순위를 매길 수 있습니다.

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

인게임 리더보드에 액세스하려면 먼저 데브 포털을 사용해서 리더보드가 트래킹할 통계를 설정하고(통계 인터페이스 참고) 리더보드 자체를 정의해야 합니다. 리더보드를 정의하려면 다음을 지정해야 합니다.

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

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

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

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

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

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

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

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

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

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

마일스톤을 참조하는 리더보드가 없으면 시스템이 알아서 마일스톤을 삭제합니다.

요약하자면:

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

• 최대 마일스톤 수(디폴트): 100

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

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

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

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

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

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

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

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

작업이 완료되면 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 구조를 사용하여 이 함수를 호출합니다.

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

에픽 온라인 서비스를 사용하는 개발자는 리더보드 인터페이스를 사용하여 전체 플레이어 기반의 점수에 순위를 매길 수 있습니다. 따라서 플레이어들이 친구나 전 세계의 다른 플레이어와 함께 최고 점수를 목표로 경쟁할 수 있습니다. 게임 하나당 여러 개의 리더보드를 지원하므로 다양한 소스에서 점수를 취합하여 각종 순위 모드로 순위를 매길 수 있습니다.

스로틀 조절, 사용 할당량, 모범 사례에 대한 일반적인 정보는 서비스 사용 제한을 참고하세요.

디플로이에서 리더보드를 사용할 때는 전체적으로 다음과 같은 제한이 적용됩니다.

사용자 또는 디플로이 별로 적용되는 사용률 제한도 있습니다. 사용자별 제한은 게임을 플레이하고 기존 리더보드를 확인하는 개별 사용자에게 적용되며, 디플로이별 제한은 이러한 리더보드를 생성 또는 삭제하는 호출에 적용됩니다.