Steamworks-Dokumentation
Steam-Bestenlisten

Übersicht

Steam unterstützt dauerhafte Bestenlisten mit automatisch sortierten Einträgen. Sie können mit diesen globale Bestenlisten und Bestenlisten von Freunden in Ihrem Spiel und auf Ihrer Community-Webseite anzeigen. Sie können für jeden Steamworks-Titel bis zu 10 000 Bestenlisten erstellen. Eine Bestenliste kann abgerufen werden, sobald die Punktzahl eines Spielers eingetragen ist.

Jede Bestenliste kann einen Eintrag pro Spieler haben. Für die Anzahl von Spielern pro Bestenliste gibt es keine Einschränkung. Jeder Eintrag umfasst eine Punktzahl für die Bestenliste (ein int32) und optional bis zu 64 int32s mit zugehörigen Daten. In diesen zugehörigen Daten können spielspezifische Informationen der Spielsitzung gespeichert werden, aus der der Eintrag auf der Bestenliste stammt. Diese Daten werden von Steam weder sortiert noch geparst und werden ersetzt, sobald ein neuer Bestenlisteneintrag für den Benutzer generiert wird.

Im Steamworks-Beispiel wurden alle derzeit in ISteamUserGameStats.h aktiven Bestenlistenfunktionen sowie zwei Beispiel-Bestenlisten implementiert. Die Bestenlisten für Ihr Spiel können auch in der Steamworks-Spielverwaltung angezeigt und verwaltet werden.

Vorbereitung

Alle asynchronen Bestenlistenfunktionen geben einen Handle für ein Steam-API-Aufrufergebnis zurück. Weitere Informationen zum Erhalt dieser Ergebnisse finden Sie im Abschnitt der Aufrufergebnisse in unserer Dokumentation „Erste Schritte“.

Erstellen einer Bestenliste

Bestenlisten sind anwendungsspezifisch und werden auf der Spielverwaltungsseite der Steamworks-Partner-Website oder über die API eingerichtet.

Erstellung im Web

In der Steamworks-Appverwaltung für Ihre App-ID können Sie unter Statistiken & Errungenschaften -> Bestenlisten Ihre Bestenlisten erstellen und verwalten.
spacewar_leaderboards

Zur Definition einer Bestenliste füllen Sie bitte die folgenden Felder aus:
  • Name: Geben Sie einen aussagekräftigen, in der internen Entwicklung verständlichen, Namen an.
  • Communityname: Wenn die Bestenliste im Communityhub angezeigt werden soll, geben Sie hier den öffentlichen Anzeigenamen ein. Wenn Sie keinen Namen eingeben, wird die Bestenliste nicht angezeigt.
  • Sortierung: Geben Sie die Sortierreihenfolge für die Bestenliste an. Das bedeutet, aufsteigend, wenn die niedrigste Punktzahl der erste Eintrag sein soll und absteigend, wenn die höchste Punktzahl der erste Eintrag sein soll.
  • Anzeigetyp: Legt fest, welche Arten von Daten in der Bestenliste angezeigt werden. Wählen Sie zwischen numerisch, Sekunden oder Millisekunden.
  • Schreibt: Wenn dies auf „trusted“ gesetzt ist, können die Bestenlistenpunktzahlen nicht von Clients, sondern nur über die Web-API SetLeaderboardScore eingestellt werden. Die Standardeinstellung ist „false“.
  • Liest: Wenn dies auf „friends“ gesetzt ist, darf das Spiel nur die Bestenliste der Freunde des Benutzers einsehen. Zum Lesen aller Punktzahlen braucht es die Web-API. Die Standardeinstellung ist „false“.

Erstellung über die API

Bestenlisten für Ihr Spiel können über die Steamworks-Appverwaltung oder programmgesteuert durch Aufrufen von ISteamUserStats::FindOrCreateLeaderboard erstellt werden. In Steam werden alle Bestenlisten für einen Steamworks-Titel über einen eindeutigen Namen identifiziert. Der Name der Bestenliste dient nur zur Identifizierung in der Steamworks-API und ist für die Benutzer in der Steam Community nicht sichtbar. Bei der Erstellung einer Bestenliste müssen Sie folgende Auswahlen treffen:

  • Sortiermethode: k_ELeaderboardSortMethodAscending (der erste Eintrag ist der Benutzer mit der niedrigsten Punktzahl) oder k_ELeaderboardSortMethodDescending (der erste Eintrag ist der Benutzer mit der höchsten Punktzahl).
  • Anzeigetyp: ELeaderboardDisplayType gibt an, was die Bestenlistenpunktzahl darstellt, und wird nur von der Community zur Formatierung von angezeigten Bestenlistenpunktzahlen verwendet.

Wenn Sie die Bestenlisten nur über die Appverwaltung erstellen möchten, können Sie mit ISteamUserStats::FindLeaderboard einen entsprechenden Handle abrufen. FindLeaderboard und FindOrCreateLeaderboard sind asynchrone Methoden und geben den Bestenlisten-Handle für die angegebene Bestenliste im Aufrufergebnis von ISteamUserStats::LeaderboardFindResult_t zurück.

Nach der Erstellung der Bestenliste können Sie die Sortiermethode und den Anzeigetyp in der Spielverwaltung festlegen. Beim Aufruf von FindOrCreateLeaderboard für eine bestehende Bestenliste werden die Parameter für Sortiermethode und Anzeigetyp ignoriert.
HINWEIS: Wenn die Bestenliste im Communityhub angezeigt werden soll, müssen Sie bei der Definition das Feld „Communityname“ ausfüllen. Wenn Sie keinen Namen eingeben, wird die Bestenliste nicht angezeigt.

Aktualisieren einer Punktezahl

Zum Hochladen einer Bestenlistenpunktzahl rufen Sie einfach ISteamUserStats::UploadLeaderboardScore auf und übergeben den Handle der gewünschten Bestenliste (den Sie über FindLeaderboard erhalten haben), die Punktzahl des Benutzers und optional weitere zugehörige Daten, die beim Erreichen der neuen Punktzahl generiert wurden. Bei der Aktualisierung der Bestenliste eines Benutzers ersetzen die an ISteamUserStats::UploadLeaderboardScore übergebenen zugehörigen Daten alle eventuell bereits vorhandenen Daten dieses Typs. Beim Hochladen haben Sie die Wahl zwischen zwei Aktualisierungsmethoden:

  • ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest: Steam vergleicht die neue Punktzahl des Benutzers mit der vorherigen, in der Bestenliste gespeicherten, und behält die höhere bei (bei aufsteigender Sortierreihenfolge ist dies die niedrigere, bei absteigender Sortierreihenfolge die höhere Punktzahl).
  • ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate: Steam ersetzt die alte Punktzahl immer durch die neue.
  • ISteamUserStats::UploadLeaderboardScore ist ein asynchroner Aufruf. Das Ergebnis des Uploads wird in einem LeaderboardScoreUploaded_t-Aufrufergebnis zurückgegeben. Das Ergebnis enthält zur Kennzeichnung eine Flagge, die zeigt, ob die Punktzahl des Benutzers geändert wurde, sowie die alte und die neue globale Ranglistenposition. Nach dem Upload werden Steamworks-Bestenlisten sofort mit der neuen Punktzahl aktualisiert und die neue Reihenfolge der Einträge kann mit DownloadLeaderboardEntries abgerufen werden.

Anhängen von benutzergenerierten Inhalten

Nach dem Upload einer Punktzahl haben Sie die Option, dem betreffenden Eintrag auch benutzergenerierte Inhalte hinzuzufügen. Rufen Sie dazu einfach ISteamUserStats::AttachLeaderboardUGC auf. Dies kann eine Wiederholung der Spielzüge sein, in denen der Benutzer die Punktzahl erreicht hat, oder auch ein Geistgegner, gegen den dieser antreten kann. Der angehängte Handle steht zur Verfügung, wenn der Eintrag abgerufen wird, und kann von anderen Benutzern heruntergeladen werden. Informationen dazu, wie benutzergenerierter Inhalt generiert und heruntergeladen wird, finden Sie in der Dokumentation zur Steam Cloud.

Nachdem der Inhalt angehängt wurde, steht er auch dann zur Verfügung, wenn die zugrunde liegende Cloud-Datei vom Benutzer geändert oder entfernt wird.

Abrufen von Bestenlisteneinträgen

Mit ISteamUserStats::DownloadLeaderboardEntries werden Bestenlisteneinträge mithilfe des Bestenlisten-Handles abgerufen, der über ISteamUserStats::FindLeaderboard bezogen wird.

Nachdem Sie alle heruntergeladenen Einträge mit GetDownloadedLeaderboardEntry abgerufen haben, werden die Eintragsdaten freigegeben und verlieren SteamLeaderboardEntries_t in LeaderboardScoresDownloaded_t ihre Gültigkeit.

Abrufen von Bestenlisteninformationen

Wenn Sie über FindLeaderboard einen Bestenlisten-Handle erhalten haben, können Sie mit den folgenden Funktionen Informationen über die Bestenliste abrufen:

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