개요

Steam은 항목을 자동으로 정렬하는 지속적인 순위표를 지원합니다. 순위표는 커뮤니티 웹페이지와 게임 내에서 전 세계 사용자와 친구들의 순위를 표시하는 데 사용할 수 있습니다. 각 Steamworks 타이틀은 최대 10,000개의 순위표를 생성할 수 있으며, 각 순위표는 사용자의 점수가 등록되면 바로 불러올 수 있습니다.

사용자는 각 순위표마다 하나의 순위에 등록될 수 있습니다. 순위표에 등록될 수 있는 플레이어 수에는 제한이 없습니다. 각 항목은 순위표의 점수(int32)와 함께 관련 데이터의 int32를 최대 64개까지 선택적으로 포함할 수 있습니다. 관련 데이터는 사용자의 순위가 결정된 게임 세션에 대한 정보를 저장하는 데 사용할 수 있습니다. Steam은 이 데이터를 분류 또는 분석하지 않으며 데이터는 사용자가 순위표에 새 점수를 등록하면 교체됩니다.

모든 순위표 함수는 ISteamUserGameStats.h에 있으며 Steamworks 예시에는 두 개의 순위표 샘플이 구현되어 있습니다. 또한 Steamworks 게임 관리자에서 게임의 순위표를 확인 및 관리할 수 있습니다.

시작하기 전에

모든 비동기 순위 함수는 핸들을 Steam API의 호출 결과에 반환합니다. 결과를 받는 방법에 대한 자세한 내용은 시작하기 문서의 호출 결과 부분을 확인하세요.

순위표 생성하기

순위표는 애플리케이션에 따라 다르며, Steamworks 파트너 사이트의 게임 관리 페이지 또는 API를 통해 설정됩니다.

웹을 통해 생성하기

통계 및 도전 과제 -> 순위표로 이동하여 Steamworks 앱 관리자에서 앱 ID의 순위표를 생성하고 관리할 수 있습니다.


순위표를 정의하려면 다음 필드를 모두 입력해야 합니다.

• 이름 - 내부 개발팀을 나타내는 적절한 이름을 설정하세요.
  
• 커뮤니티 이름 - 순위표를 커뮤니티 허브에 표시하려는 경우, 공개할 이름을 여기에 설정하세요. 이름을 입력하지 않으면 순위표가 표시되지 않습니다.
  
• 정렬 방법 - 순위표를 정렬할 순서를 설정합니다. 순위가 기준인 경우에는 오름차순을 사용하세요. 고득점이 기준인 경우에는 내림차순을 사용하세요.
  
• 표시 유형 - 순위표에 표시할 데이터의 종류를 결정합니다. 숫자, 초, 밀리초 중에서 선택하세요.
  
• 쓰기 - 신뢰함(Trusted)으로 설정하면 클라이언트에서 순위표를 설정할 수 없고 오직 SetLeaderboardScore WebAPI를 통해서만 설정이 가능합니다. 기본값은 false입니다.
  
• 읽기 - 친구(Friends)로 설정하면 사용자의 친구만 순위표를 읽을 수 있고, 모든 점수는 항상 WebAPI를 통해 읽을 수 있습니다. 기본값은 false입니다.

API를 통해 생성하기

게임의 순위표는 Steamworks 앱 관리자를 통해 생성하거나 ISteamUserStats::FindOrCreateLeaderboard를 호출하여 프로그래밍으로 생성할 수 있습니다. Steam에서 Steamworks 타이틀의 모든 순위표는 고유 이름으로 식별됩니다. 순위표 이름은 오로지 Steamworks API에서의 식별을 위해 사용되며, Steam 커뮤니티를 통해 사용자에게 표시되지 않습니다. 순위표를 생성할 때는 다음을 선택해야 합니다.

• 분류 방법 - k_ELeaderboardSortMethodAscending(가장 위에 있는 항목이 가장 점수가 낮은 사용자) 혹은 k_ELeaderboardSortMethodDescending(가장 위에 있는 항목이 가장 점수가 높은 사용자).
  
• 표시 유형 - ELeaderboardDisplayType은 순위표 점수가 나타내는 것이 무엇이지 설명하기 위해 사용되며, 커뮤니티에서 순위표 점수가 표시될 때 서식화하기 위해 사용됩니다.

앱 관리자를 통해 순위표를 생성하기로 했다면, ISteamUserStats::FindLeaderboard를 사용해 순위표 핸들을 가져올 수 있습니다. FindLeaderboard 및 FindOrCreateLeaderboard는 비동기 방식으로, ISteamUserStats::LeaderboardFindResult_t 호출 결과를 통해 특정 순위표를 위한 순위표 핸들을 반환합니다.

순위표가 일단 생성되면, 게임 관리자를 통해 순위표의 분류 방법과 표시 유형을 변경할 수 있습니다. 기존 순위표를 위해 FindOrCreateLeaderboard를 호출하면 분류 방법 및 표시 유형 매개변수가 무시됩니다.

점수 업로드하기

순위표에 점수를 업로드하려면 ISteamUserStats::UploadLeaderboardScore를 호출하여 대상 순위표의 핸들(FindLeaderboard를 사용하여 불러온 것)과 사용자의 점수 그리고 새로운 점수를 설정할 때 생성된 관련 데이터(선택 사항)를 전달하면 됩니다. 사용자의 순위표 점수가 업데이트되면 ISteamUserStats::UploadLeaderboardScore에 전달된 관련 데이터는 이전에 저장된 데이터를 대체합니다. 사용자의 순위표 점수를 업로드할 때는 두 가지의 업데이트 방식 중 하나를 선택할 수 있습니다.

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest - Steam이 사용자의 새로운 점수와 이미 순위표에 저장되어 있는 점수를 비교하여 둘 중 더 나은 점수를 기록합니다(오름차순 정렬의 순위표는 가장 낮은 점수, 그리고 내림차순 정렬의 순위표는 가장 높은 점수).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate - Steam이 사용자의 순위표 점수를 항상 새로운 점수로 교체합니다.
  
• ISteamUserStats::UploadLeaderboardScore는 비동기 호출이며 업로드 결과는 LeaderboardScoreUploaded_t 호출 결과로 반환됩니다. 사용자의 점수가 변경되면 결과에 플래그 표시, 사용자의 예전 및 새로운 세계 순위가 포함됩니다. 업로드가 완료되면 Steamworks 순위표는 즉시 업데이트되어 새로운 점수를 나타내며 새 항목의 순서는 DownloadLeaderboardEntries를 사용해 검색할 수 있습니다.

사용자 생성 콘텐츠 첨부하기

점수를 업로드 한 후 해당 항목에 사용자 생성 콘텐츠를 첨부할 수 있습니다. 이를 위해서는 ISteamUserStats::AttachLeaderboardUGC를 실행해야 합니다. 이 콘텐츠는 사용자가 점수를 달성한 게임의 리플레이 또는 고스트 레이스가 될 수 있습니다. 첨부된 핸들은 해당 항목을 검색하여 확인할 수 있으며 다른 사용자가 다운로드할 수 있습니다. 사용자 생성 콘텐츠를 생성 및 다운로드 하려면 Steam Cloud 문서를 확인하세요.

첨부된 콘텐츠는 이후 사용자가 원본 클라우드 파일을 변경 또는 삭제하더라도 계속 이용 가능합니다.

순위표 항목 검색하기

ISteamUserStats::DownloadLeaderboardEntries는 ISteamUserStats::FindLeaderboard를 통해 검색된 순위표 핸들을 사용하여 순위표 항목을 검색하는 데 사용됩니다.

GetDownloadedLeaderboardEntry에서 모든 다운로드 항목을 검색하면 항목 데이터는 다시 사용할 수 없게 되고 LeaderboardScoresDownloaded_t의 SteamLeaderboardEntries_t는 더 이상 유효하지 않게 됩니다.

순위표 정보 검색하기

FindLeaderboard로부터 반환된 순위표 핸들을 사용하여 아래와 같은 방법으로 순위표의 정보를 검색할 수 있습니다.

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType