Wprowadzenie

Steam posiada obsługę trwałych rankingów z automatycznie sortowanymi wpisami. Te rankingi mogą zostać wykorzystane do wyświetlania najlepszych graczy globalnie i wśród znajomych użytkownika zarówno w twojej grze, jak i na twojej stronie społeczności. Każdy produkt Steamworks może utworzyć do 10 000 rankingów, a dostęp do każdego z nich można uzyskać natychmiast po przesłaniu wyników danego gracza.

Jeden gracz będzie miał tylko jedno miejsce w danym rankingu. Nie ma ograniczeń co do liczby graczy dla każdego rankingu. Każdy wpis zawiera wynik dla rankingu (int32) i do 64 opcjonalnych elementów typu int32 z powiązanymi danymi. Powiązane dane mogą zostać użyte do przechowywania informacji specyficznych dla gry o sesji rozgrywki, która zakończyła się wpisem użytkownika w rankingu. Te dane nie są sortowane ani przetwarzane przez Steam i są zastępowane, gdy dla użytkownika zostanie utworzony nowy wpis w rankingu.

Wszystkie funkcje rankingów znaleźć można w ISteamUserGameStats.h. W przykładowej aplikacji Steamworks zaimplementowano dwa tego typu przykłady. Można również zobaczyć i zarządzać rankingami dla twojej gry na stronie administratora gry w Steamworks.

Zanim zaczniesz

Wszystkie asynchroniczne funkcje rankingów zwracają uchwyt do rezultatu wywołania API Steam. Więcej informacji na temat otrzymywania tych rezultatów znajduje się w sekcji dotyczącej rezultatów wywołania w dokumencie wprowadzającym.

Tworzenie rankingu

Rankingi są specyficzne dla danej aplikacji i można je utworzyć na stronie administratora gry na stronie partnerskiej Steamworks lub przy użyciu API.

Tworzenie poprzez stronę internetową

Możesz utworzyć i zarządzać rankingami na stronie administratora aplikacji dla twojego ID aplikacji, przechodząc do strony Statystyki i osiągnięcia -> Rankingi.


Aby zdefiniować ranking, należy wypełnić następujące pola:

• Nazwa – powinna to być nazwa, która ma sens w kontekście wewnętrznego rozwoju produktu.
  
• Nazwa w społeczności – jeśli ranking ma być wyświetlany w centrum społeczności, ta nazwa będzie widoczna publicznie. Jeśli jej nie wprowadzisz, ranking nie pojawi się.
  
• Metoda sortowania – ustaw kolejność sortowania w rankingu. Dla list opartych na pozycji gracza użyj opcji „rosnąco”, a dla list opartych na najlepszych wynikach użyj „malejąco”.
  
• Tryb wyświetlania — określa rodzaj danych wyświetlanych wraz z rankingiem. Dostępne opcje: numeryczny, sekundy lub milisekundy.
  
• Zapisy – jeśli ustawiono tę opcję na „Zaufani”, to wyniki w rankingu nie mogą być zapisywane przez klienty i jest to możliwe tylko przez WebAPI SetLeaderboardScore. Domyślna wartość: false.
  
• Odczyty – jeśli ustawiono tę opcję na „Znajomi”, gra może odczytywać wyłącznie wyniki rankingów znajomych użytkownika, a wszystkie wyniki mogą być zawsze odczytywane przez WebAPI. Domyślna wartość: false.

Tworzenie poprzez API

Rankingi dla twojej gry można utworzyć na stronie administratora aplikacji na Steamworks lub programowo, wywołując ISteamUserStats::FindOrCreateLeaderboard. Wszystkie rankingi na Steam dla tytułów Steamworks są identyfikowane według unikalnej nazwy. Nazwa rankingu służy wyłącznie do identyfikacji w API Steamworks i nie jest wyświetlana użytkownikom w Społeczności Steam. Podczas tworzenia rankingu musisz wybrać:

• Metodę sortowania — k_ELeaderboardSortMethodAscending (użytkownik o najniższym wyniku znajdzie się na najwyższej pozycji) lub k_ELeaderboardSortMethodDescending (użytkownik z najwyższym wynikiem będzie na najwyższej pozycji).
  
• Typ wyświetlania — ELeaderboardDisplayType służy do opisu tego, co przedstawia wynik rankingu i jest używany tylko przez społeczność do formatowania wyników rankingu, gdy są wyświetlane.

Jeśli zdecydujesz tylko utworzyć rankingi poprzez stronę administratora aplikacji, możesz użyć ISteamUserStats::FindLeaderboard, aby uzyskać uchwyt do twojego rankingu. FindLeaderboard i FindOrCreateLeaderboard to metody asynchroniczne, które zwracają uchwyt do określonego rankingu przez rezultat wywołania ISteamUserStats::LeaderboardFindResult_t.

Gdy ranking zostanie utworzony, możesz zmodyfikować metodę sortowania i typ wyświetlania dla rankingu poprzez stronę administratora gry. Gdy FindOrCreateLeaderboard jest wywoływane dla istniejącego rankingu, parametry metody sortowania i typu wyświetlania są ignorowane.

Przesyłanie wyniku

Aby przesłać wynik rankingu, po prostu wywołaj ISteamUserStats::UploadLeaderboardScore, przekazując jako parametr uchwyt rankingu docelowego (uzyskany poprzez FindLeaderboard), wynik użytkownika i opcjonalnie inne powiązane dane wygenerowane przy ustawianiu nowego wyniku. Jeśli wynik użytkownika w rankingu zostanie zaktualizowany, powiązane dane przekazane do ISteamUserStats::UploadLeaderboardScore zastąpią wszystkie wcześniej przechowywane dane. Możesz wybrać jedną z dwóch metod aktualizowania podczas przesyłania wyniku użytkownika do rankingu:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest — Steam porówna nowy wynik z jego poprzednim, już przechowywanym wynikiem w rankingu, a następnie zachowa najlepszy wynik użytkownika (najniższy dla sortowania rosnącego, najwyższy dla sortowania malejącego).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate — Steam zawsze zastąpi stary wynik użytkownika w rankingu nowym wynikiem.
  
• ISteamUserStats::UploadLeaderboardScore to wywołanie asynchroniczne i jego rezultat jest zwracany w rezultacie wywołania LeaderboardScoreUploaded_t. Rezultat zawiera flagę wskazującą, czy wynik użytkownika uległ zmianie, a także nową i starą globalną rangę użytkownika. Po przesłaniu wyników rankingi w Steamworks są natychmiast aktualizowane, by odzwierciedlić nowy wynik, a nowa kolejność wpisów może zostać uzyskana za pomocą DownloadLeaderboardEntries.

Dołączanie treści tworzonych przez użytkowników

Istnieje możliwość dołączenia treści utworzonych przez użytkownika do wpisu po tym, jak wynik został przesłany. Aby to zrobić, po prostu wywołaj ISteamUserStats::AttachLeaderboardUGC. Ta treść może być na przykład powtórką z rozgrywki zawierającą nagranie, na którym użytkownik osiąga dany wynik, lub „duch”, z którym można się ścigać. Załączony uchwyt będzie dostępny po uzyskaniu wpisu i może zostać pobrany przez innych użytkowników. Aby utworzyć i pobrać treści generowane przez użytkowników, sprawdź dokumentację Steam Cloud.

Treści po dołączeniu będą dostępne nawet wtedy, gdy podstawowy plik w chmurze zostanie zmieniony lub usunięty przez użytkownika.

Uzyskiwanie wpisów z rankingu

ISteamUserStats::DownloadLeaderboardEntries służy do uzyskiwania wpisów z rankingu za pomocą uchwytu do rankingu uzyskanego za pomocą ISteamUserStats::FindLeaderboard.

Po uzyskaniu wszystkich pobranych wpisów z GetDownloadedLeaderboardEntry dane wpisów zostaną zwolnione, a SteamLeaderboardEntries_t w LeaderboardScoresDownloaded_t nie będzie już ważne.

Uzyskiwanie informacji o rankingu

Za pomocą uchwytu zwróconego przez FindLeaderboard możesz uzyskać informacje o rankingu, korzystając przy tym z następujących metod:

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