Dokumentacja Steamworks
Rankingi na Steam

Wprowadzenie

Na platformie Steam znajdują się rankingi z automatycznie sortowanymi wpisami. Tabele rankingów mogą być używane do wyświetlania najlepszych graczy (zarówno globalnie, jak i z listy znajomych) w grze oraz w centrum społeczności. Każdy produkt Steamworks może utworzyć do 10 000 tabel wyników, a dostęp do każdej z tych list można uzyskać natychmiast po przesłaniu wyników punktowych danego gracza.

Jeden gracz będzie miał tylko jedno miejsce w tabeli rankingowej. Nie ma ograniczeń co do liczby graczy w tabeli rankingów. Każdy wpis zawiera wynik rankingu (int32) i do 64 opcjonalnych elementów int32 z powiązanymi danymi. Powiązane dane mogą być używane do przechowywania informacji na temat rozgrywek danej gry. Dane te pozwalają na ustalenie miejsca rankingowego danego użytkownika. Te dane nie są sortowane ani przetwarzane przez Steam i są zastępowane podczas tworzenia nowej pozycji użytkownika w tabeli rankingów.

Wszystkie funkcje systemu rankingowego znaleźć można w ISteamUserGameStats.h. W przykładowej aplikacji Steamworks zaimplementowano dwa tego typu przykłady. Zobaczyć tabele rankingowe i zarządzać nimi można również za pomocą panelu administratora Steamworks.

Zanim zaczniesz

Wszystkie asynchroniczne funkcje tablic rankingowych zwracają handle do wyniku połączenia. Więcej informacji na temat uzyskiwania wyników można znaleźć w dziale wyników wywoływania w sekcji wprowadzającej do Steamworks API.

Tworzenie tabeli rankingowej

Tablice rankingowe są tworzone dla określonej aplikacji na stronie zarządzania danymi aplikacji w witrynie partnera Steamworks lub przy użyciu interfejsu API.

Tworzenie za pośrednictwem strony internetowej

Możesz tworzyć i edytować tabele wyników na stronie zarządzania danymi aplikacji https://partner.steamgames.com/apps/leaderboards.
spacewar_leaderboards

Aby utworzyć ranking, należy wypełnić następujące pola:
  • Nazwa — Powinna to być nazwa, która ma sens jeśli chodzi o względy projektowe.
  • Nazwa społeczności — Jeśli ranking jest wyświetlany w centrum społeczności, należy nadać jej oficjalną nazwę. Jeśli jej nie wprowadzisz, ranking nie pojawi się w centrum społeczności.
  • Metoda sortowania — Wybierz odpowiednią dla danego 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: liczby, sekundy lub milisekundy.
  • Zapisy — Jeśli ustawione na „zaufane”, klienci nie będą mogli wysyłać danych wyników do rankingów, można to zrobić tylko za pomocą SetLeaderboardScore (WebAPI). Domyślnie — false.
  • Odczyty — Jeśli ustawione na „znajomi”, gra może uzyskać tylko rankingi znajomych użytkownika; wszystkie wyniki można uzyskać za pomocą WebAPI. Domyślna wartość — false.

Tworzenie za pośrednictwem interfejsu API

Rankingi można tworzyć na stronie Steamworks lub za pomocą ISteamUserStats::FindOrCreateLeaderboard. Wszystkie rankingi dla produktów Steamworks są identyfikowane na platformie Steam przy użyciu przyporządkowanej im nazwy. Nazwa tabeli rankingowej służy wyłącznie do identyfikacji w interfejsie Steamworks i nie jest wyświetlana użytkownikom ze społeczności Steam. Tworząc tabelę rankingową, wybierz:

  • 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) oraz
  • Sposób wyświetlania to ELeaderboardDisplayType służy do opisu, co przedstawiają tabele rankingowe i jest używane tylko przez społeczność do formatowania wyników punktowych pojawiających się na tablicy rankingowej.

Jeśli tworzysz tabele rankingowe tylko za pomocą strony [/url]partnera, możesz użyć ISteamUserStats::FindLeaderboard, aby uzyskać „handle” listy rankingowej. FindLeaderboard i FindOrCreateLeaderboard to metody asynchroniczne, które zwracają „handle” tablicy rankingowej dla określonej listy w wyniku wywoływania ISteamUserStats::LeaderboardFindResult_t.

Po utworzeniu tabeli rankingowej możesz zmienić metodę sortowania i sposób wyświetlania w witrynie Steamworks. Podczas wywoływania FindOrCreateLeaderboard dla istniejącej listy, parametry „metody sortowania” i „sposobu wyświetlania” są ignorowane.
UWAGA: jeśli tabela rankingów jest wyświetlana w centrum społeczności, należy wypełnić pole „Nazwa w społeczności”. Jeśli jej nie wprowadzisz, ranking nie pojawi się w centrum społeczności.

Przesyłanie wyników punktowych

Aby przesłać wyniki punktowe, należy wywołać ISteamUserStats::UploadLeaderboardScore, przekazując jako parametr „handle” listy rankingowej (uzyskany z FindLeaderboard), konto użytkownika i opcjonalnie inne dane, które pojawiły się przy ustawianiu nowych wyników. Jeśli konto użytkownika zostanie zaktualizowane, powiązane dane przesłane przez ISteamUserStats::UploadLeaderboardScore zastąpią wszystkie wcześniej zapisane dane. Przesyłając wyniki punktowe użytkownika do tabeli wyników, możesz wybrać jedną z dwóch metod wysyłki:

  • ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest — Steam porównuje nowe wyniki punktowe użytkownika z tymi już zapisanymi na tablicy rankingowej i zapisuje najlepsze (najniższy wynik dla tabel wyników z rosnącą kolejnością sortowania; najwyższy wynik w tabelach wyników z malejącą kolejnością sortowania).
  • ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate — Steam zawsze zamienia stare wyniki użytkownika na liście na nowe.
  • ISteamUserStats::UploadLeaderboardScore — wywołanie asynchroniczne; wynik wysyłania jest zwracany w wyniku wywołania do LeaderboardScoreUploaded_t. Wynik zawiera flagę wskazującą, czy konto użytkownika uległo zmianie, oraz nową i starą globalną ocenę użytkownika. Po przesłaniu nowych wyników punktowych tabele rankingowe Steamworks są natychmiast aktualizowane, a nową kolejność pozycji można uzyskać za pomocą metody DownloadLeaderboardEntries.

Dodawanie treści tworzonych przez użytkowników

Po przesłaniu wyników punktowych można dodać treść utworzoną przez użytkownika do pozycji na liście. Aby to zrobić, wystarczy wywołać ISteamUserStats::AttachLeaderboardUGC. Ta treść może być nagraniem rozgrywki, która przyniosła użytkownikowi zwycięstwo lub „fantomowym użytkownikiem”, z którym mogą konkurować inni gracze. Załączony uchwyt będzie dostępny po pobraniu pozycji, a inni użytkownicy będą mogli go pobrać dla siebie. Tworzenie i pobieranie treści generowanych przez użytkowników jest szczegółowo opisane w dokumentacji Steam Cloud.

Po dodaniu treść będzie dostępna, nawet jeśli użytkownik usunie lub zmieni odpowiedni plik Cloud.

Pobieranie wpisów rankingowych

ISteamUserStats::DownloadLeaderboardEntries służy do uzyskiwania pozycji w tabeli rankingowej za pomocą handla uzyskanego za pomocą ISteamUserStats::FindLeaderboard.

Po pobraniu wszystkich załadowanych elementów za pomocą GetDownloadedLeaderboardEntry dane zostaną opublikowane, a SteamLeaderboardEntries_t z LeaderboardScoresDownloaded_t zostanie unieważnione.

Pobieranie informacji rankingowych

Za pomocą uchwytu (handle) zwróconego przez FindLeaderboard uzyskać można informacje dotyczące tabeli rankingowej, korzystając przy tym z następujących metod:

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