Dokumentation Ressourcen Neuigkeiten & Updates Support
Sprache
Steamworks-Dokumentation
Errungenschaften und Statistiken
Steamworks-Dokumentation > Funktionen > Errungenschaften und Statistiken

Übersicht

Über Steam-Statistiken und -Errungenschaften können Spieler mühelos Statistiken und Errungenschaften für Ihr Spiel nachverfolgen. Nutzerdaten sind mit dem entsprechenden Steam-Account verknüpft. Die Statistiken und Errungenschaften jedes Nutzers können in dessen Steam-Communityprofil formatiert und angezeigt werden.

Verwendungszweck

Neben hochwertigen Belohnungen für Ihre Spieler sind Errungenschaften gut geeignet, anspornende und lohnende Spielerinteraktionen zu schaffen, da sie die Spielziele um neue Dimensionen erweitern und Benutzer dafür belohnen, dass sie mehr Zeit im Spiel verbringen.

Mit den Statistiken werden detaillierte Informationen erfasst, zum Beispiel die Spielzeit, die Anzahl verwendeter Powerups etc. Sie haben auch die Wahl, diese Informationen lediglich zum Aufzeichnen interner Spieldaten zu verwenden. Sie können beispielsweise Errungenschaften basierend auf Spielstatistiken vergeben, die ein Benutzer über mehrere Sitzungen und verschiedene Computer hinweg erzielt hat.

Übersicht zur Implementierung

Definieren von Statistiken und Errungenschaften für Ihr Spiel

Errungenschaften sind anwendungsspezifisch und werden in der Appverwaltung des Steamworks-Partners eingerichtet.

Sie können drei Typen von Statistiken für Ihr Spiel speichern:
  • INT: Eine 32-Bit-Ganzzahl (mit Vorzeichen) (z. B. Anzahl von gespielten Spielen).
  • FLOAT: Ein 32-Bit Gleitkommawert (z. B. Anzahl von gefahrenen Kilometern).
  • AVGRATE: Ein gleitender Durchschnitt. Siehe: Der Statistik-Datentyp AVGRATE.

Die Steamworks-Partnerwebsite bietet eine Schnittstelle zum Definieren und Aktualisieren der Statistiken und Errungenschaften für Ihr Spiel. Sie ermöglicht Folgendes:
  • Definition der Statistiken und Errungenschaften zu Beginn
  • Hinzufügen weiterer Statistiken und Errungenschaften
  • Aktualisieren der Namen, Beschreibungen und Symbole von Errungenschaften
  • Aktualisieren von Parametern und Beschränkungen für Statistiken (Höchst-/Mindestwerte, Bereichsgrößen für gleitende Durchschnitte etc.)
Statistiken haben folgende Eigenschaften:
  • ID: Eine automatisch generierte numerische ID für jede Statistik.
  • Type: Der Typ dieser Statistik – INT, FLOAT, oder AVGRATE.
  • API Name Der verwendete String zum API-Zugriff auf diese Statistik.
  • Set By: Legt fest, wer die Statistik verändern darf. Der Standardwert ist „Client“. Weitere Informationen finden Sie unter Spielserverstatistiken.
  • Increment Only: Wenn diese Eigenschaft gesetzt wurde, darf der Wert dieser Statstik nur im Verlauf der Zeit erhöht werden.
  • Max Change: Wenn diese Eigenschaft gesetzt wurde, wird eine maximale Anzahl von Änderungen des Statistikwerts von einem SetStat-Aufruf zum nächsten festgelegt.
  • Min Value: Wenn diese Eigenschaft gesetzt wurde, wird der minimale numerische Wert festgelegt, den diese Statistik annehmen kann. Standardmäßig entspricht dieser dem minimalen Wert des zugrunde liegenden numerischen Datentyps (INT_MIN oder -FLT_MAX).
  • Max Value: Wenn diese Eigenschaft gesetzt wurde, wird der maximale numerische Wert festgelegt, den diese Statistik annehmen kann. Standardmäßig entspricht dieser dem maximalen Wert des zugrunde liegenden numerischen Datentyps (INT_MAX oder FLT_MAX).
  • Default Value: Wenn diese Eigenschaft gesetzt wurde, ist dies der Standardwert, auf den diese Statistik für einen neuen Benutzer festgelegt wird. Wenn nicht gesetzt, ist der Standardwert null.
  • Aggregated: Wenn diese Eigenschaft gesetzt wurde, speichert Steam einen globalen Gesamtwert für diese Statistik. Weitere Informationen finden Sie unter „Globale Statistiken“.
  • Display Name Der Name dieser Statistik, wenn in Ihrer Anwendung angezeigt.
AVGRATE Statistiken haben folgende zusätzlichen Eigenschaften:
  • Window: Größe des „gleitenden Bereichs“ zur Durchschnittsermittlung Ihrer Daten.
Steam bildet automatisch einen Durchschnittswert für eine AVGRATE-Statistik. Weitere Information finden Sie im Abschnitt AVGRATE unten.

Errungenschaften haben folgende Eigenschaften:
  • ID: Eine automatisch generierte numerische ID für jede Errungenschaft.
  • API Name: Der verwendete String zum API-Zugriff auf diese Errungenschaft.
  • Progress Stat: Gibt eine Statistik an, die in der Community als Fortschrittsbalken für diese Errungenschaft angezeigt wird. Außerdem wird die Errungenschaft automatisch freigeschaltet, sobald die Statistik den Freischaltwert erreicht.
  • Display Name: Der Name der Errungenschaft, wie er in Client-Benachrichtigungen und in der Community angezeigt wird. Dieser kann lokalisiert werden.
  • Description: Eine Beschreibung dieser Errungenschaft zur Anzeige in der Community. Dieser kann lokalisiert werden.
  • Set By: Legt fest, wer die Errungenschaft verändern darf. Der Standardwert ist „Client“. Weitere Informationen finden Sie unter Spielserverstatistiken.
  • Hidden? Wenn „true“, ist eine „verborgene“ Errungenschaft auf der Communityseite des Benutzers erst sichtbar, wenn er sie freigeschaltet hat.
  • Achieved Icon: Das Symbol der erreichten Errungenschaft.
  • Unachieved Icon: Das bei Nichterreichen der Errungenschaft angezeigte Symbol.

Im Folgenden finden Sie die Liste der Errungenschaften aus Steamworks-API-Beispielanwendung (SpaceWar):
achievements_spacewar.png.

Besondere Hinweise

  • Namen und Symbole von Errungenschaften sollten für alle Altersstufen angemessen sein.
  • Standardmäßig sind Spiele zunächst auf 100 Errungenschaften beschränkt. Sobald Ihre Anwendung die Schwelle für Profilfunktionen erreicht, können Sie weitere Errungenschaften hinzufügen.

Verwendung

Aufrufen der Statistiken und Errungenschaften aus dem Spiel heraus:

Der Statistik-Datentyp AVGRATE

Dieser Typ von Statistik bietet eine Reihe einmaliger und sehr nützlicher Funktionen, muss aber etwas detaillierter erläutert werden.

Angenommen, Sie möchten einen Durchschnittswert verfolgen, zum Beispiel „Verdiente Punkte pro Stunde“. Eine Methode wäre die Verwendung von zwei Statistiken: einmal „INT TotalPoints“ und einmal FLOAT „TotalPlayTimeHours“. Dann könnten Sie die Punkte durch die Stunden teilen und hätten die Punkte pro Stunde.

Der Nachteil besteht darin, dass der berechnete Durchschnittswert sich extrem langsam ändern wird, wenn der Spieler eine erhebliche Spielzeit angehäuft hat. Tatsächlich wird der Durchschnitt immer langsamer, je mehr Zeit der Benutzer im Spiel verbringt. Wenn der Benutzer 100 Stunden im Spiel verbracht hat, wird der berechnete Durchschnitt um etwa 50 Stunden „nachgehen“. Wenn er seine Fertigkeiten verbessert, fällt die Zunahme der Punkte pro Stunde nicht so hoch wie erwartet aus.

Mit dem Statistiktyp AVGRATE können Sie den Effekt eines „gleitenden Bereichs“ auf den Durchschnitt anwenden. Beispielsweise können Sie nur die letzten Stunden Spielzeit berücksichtigen, damit die Statistik die aktuelle Fertigkeitsstufe des Spielers genauer widerspiegelt.

Richten wir nun eine AVGRATE-Statistik für „Punkte pro Stunde“ ein, bei der nur die letzten 20 Stunden Spielzeit den Wert beeinflussen. Gehen Sie hierfür folgendermaßen vor:
  • Hinweis: Da dieser Durchschnitt „pro Stunde“ gilt, sind die Zeiteinheiten aller mit dieser Statistik verknüpften Parameter „hours“. Dies gilt sowohl für die Bereichseigenschaft in der Statistik selbst als auch für den „dSessionLength“-Parameter, der unten an UpdateAvgRateStat übergeben wird.
  • Erstellen Sie eine AVGRATE-Statistik namens „AvgPointsPerHour“ und eine Bereichseigenschaft 20.0 (diese Angabe ist in „hours“ (Stunden)).
  • Rufen Sie nun an geeigneten Punkten im Spiel ISteamUserStats::UpdateAvgRateStat mit folgenden Parametern auf:
    • pchName: „AvgPointsPerHour“
    • flCountThisSession: Anzahl der Punkte, die der Spieler seit dem letzten Aufruf von UpdateAvgRateStat erzielt hat.
    • dSessionLength: Die Spielzeit seit dem letzten Aufruf von UpdateAvgRateStat. Die Einheit muss dieselbe sein wie die Einheit in der Bereichseigenschaft der Statistik. In diesem Fall ist es „hours“ (Stunden).
  • Beispiel: Wenn der Spieler in der letzten Runde, die 0,225 Stunden (13,5 Minuten) gedauert hat, 77 Punkte erzielt hat, ergibt sich SteamUserStats()->UpdateAvgRateStat( "AvgPointsPerHour", 77, 0.225 ).
Im Beispiel oben verwendet Steam den aktuellen Rundendurchschnitt von 342,2 Punkten pro Stunde (77 geteilt durch 0,225) und kombiniert ihn mit dem vorherigen Wert. Das Ergebnis gibt den Gesamtdurchschnitt für die letzten 20 Stunden Spielzeit des Spielers wieder. Wenn die Statistik für diesen Spieler zum ersten Mal erhoben würde, wäre der aktuelle Wert 342,2.

In diesem Beispiel wird „hours“ als Zeiteinheit verwendet, Sie können jedoch auch beliebige andere Zeiteinheiten verwenden. Beachten Sie aber, dass Sie diese Zeiteinheit konsistent als Basis sowohl für „dSessionLength“ als auch für die Bereichseigenschaft verwenden müssen.

Abrufen von Statistiken für andere Benutzer

Sie können mit ISteamUserStats::RequestUserStats Statistiken für einen anderen Benutzer abrufen. Anschließend können Sie mit ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement, und ISteamUserStats::GetUserAchievementAndUnlockTime die Daten für diesen Benutzer abrufen. Diese Daten werden nicht automatisch aktualisiert, wenn der andere Benutzer neue Statistiken hochlädt. Rufen Sie daher zum Aktualisieren der Daten ISteamUserStats::RequestUserStats erneut auf.

Um nicht zu viel Speicher zu verbrauchen, wird ein LRU-Cache (Least Recently Used) verwendet und die Statistiken anderer Benutzer gelegentlich entfernt. In diesem Fall wird die ISteamUserStats::UserStatsUnloaded_t-Rückruf gesendet. Nach dem Senden dieses Rückrufs sind die Statistiken des entsprechenden Benutzers erst wieder verfügbar, wenn ISteamUserStats::RequestUserStats erneut aufgerufen wird.

Offlinemodus

Steam speichert einen lokalen Cache mit den Daten zu Statistiken und Errungenschaften, sodass die APIs auch im Offlinemodus normal verwendet werden können. Alle Statistiken, die nicht festgeschrieben werden können, werden gespeichert, bis der Benutzer das nächste Mal online ist. Falls auf mehreren Geräten Änderungen aufgetreten sind, führt Steam die Errungenschaften automatisch zusammen und wählt den Satz der Statistiken, bei dem mehr Fortschritt erzielt wurde. Da Steam einen lokalen Cache der Statistikdaten speichert, braucht das Spiel keinen lokalen Cache, um die Daten auf dem Laufwerk zu speichern. Solche Caches können häufig zu Konflikten führen. In diesem Fall kann es für Benutzer den Anschein haben, als sei ihr Fortschritt zurückgesetzt worden, was eine frustrierende Erfahrung ist.

Spielserverstatistiken

Neben ISteamUserStats gibt es ISteamGameServerStats für Spielserver. Diese können Statistiken für Benutzer auf dieselbe Art abrufen wie Clients (siehe oben). Außerdem können sie Statistikänderungen und das Erreichen von Errungenschaften einstellen, aber nur, wenn „Set by“ auf „GS“ (Spielserver) oder „Official GS“ eingestellt ist. Der Unterschied zwischen Spielservern und offiziellen Spielservern liegt darin, dass offizielle Spielserver von Ihnen gehostete und gesteuerte Server sind. Die Beschränkung auf offizielle Spielserver zur Festlegung von Statistiken bietet besseren Schutz vor Cheats, da Benutzer anderenfalls ihre eigenen Spielserver modifizieren oder vortäuschen können, ein Spielserver zu sein. Um offizielle Spielserver zu definieren, geben Sie hier die IP-Bereiche der Server ein.

Statistiken und Errungenschaften, die von Spielservern eingestellt werden können, können nicht von Clients eingestellt werden. Spielserver können nur Statistiken und Errungenschaften von Spielern einstellen, die derzeit auf dem Server spielen. Wenn der Benutzer den Server verlässt, gibt es eine kurze „Gnadenfrist“, in der noch ausstehende Statistiken eingestellt werden können. Anschließend werden sämtliche neue Uploads abgewiesen. Dies soll Konsistenz gewährleisten und ausschließen, dass betrügerische Spielserver jederzeit beliebige Statistiken einstellen können. Aufgrund dieser Einschränkung ist es wichtig, mit dem Einstellen von Statistiken nicht bis zum Ende einer Runde zu warten. Stellen Sie sie regelmäßig ein, damit Sie sie speichern können, wenn ein Benutzer die Sitzung verlässt.

Clients erhalten automatische Updates, wenn sich ihre Statistiken auf dem Spielserver ändern. Allerdings werden, wie bei Clients, Statistiken, die vom Server für andere Benutzer geladen werden, nicht automatisch aktualisiert und können veralten.

Statistiken zurücksetzen

Während der Entwicklung tritt häufig der Fall ein, dass Sie zu Testzwecken die Statistiken und Errungenschaften für einen oder alle Accounts vollständig zurücksetzen müssen. Um Statistiken für einen Account zurückzusetzen, rufen Sie ISteamUserStats::ResetAllStats auf und setzen Sie bAchievementsToo auf true, um Errungenschaften ebenfalls zurückzusetzen. Vergessen Sie nicht, nach dem Aufruf die Statistiken und Errungenschaften zu reiterieren und den Spielstatus im Speicher zurückzusetzen. Es gibt keine Möglichkeit, Statistiken und Errungenschaften für alle Benutzer global zurückzusetzen. Einer der Gründe hierfür ist, dass selbst im Fall eines globalen Zurücksetzens alle zu dieser Zeit noch ausgeführten Spiele nicht vom Zurücksetzen betroffen wären und Speicherwerte wieder überschrieben würden. Sie können ein System zum globalen Zurücksetzen jedoch auch auf einfachere Weise in Ihr Spiel integrieren. Gehen Sie hierzu wie folgt vor:
  • Definieren Sie eine Statistik mit einem Namen wie „Version“.
  • Fügen Sie eine hartcodierte Versionsnummer für die Statistik im Spiel ein.
  • Vergleichen Sie nach dem Laden der Statistiken die „Version“-Statistik mit Ihrer hartcodierten Versionsnummer.
  • Wenn diese nicht übereinstimmen, rufen Sie ISteamUserStats::ResetAllStats auf und stellen Sie die „Version“-Statistik auf die hartcodierte Nummer ein.
Wenn Sie global zurücksetzen möchten, müssen Sie lediglich die hartcodierte Versionsnummer der Statistik ändern. Sobald die Benutzer den neuen Build erhalten, erfolgt das globale Zurücksetzen.

Konsistente Statistiken

Denken Sie stets darüber nach, in welchen Fällen zusammengehörige Statistiken inkonsistent werden könnten. Angenommen, Sie haben drei Statistiken „GamesWon“, „GamesLost“ und „GamesPlayed“. Trotz aller Bemühungen kann und wird es vorkommen, dass Statistiken nicht mehr synchron sind. In diesem Beispiel könnte dies dazu führen, dass die Anzahl der gewonnenen und verlorenen Spiele als Summe nicht mehr der Gesamtzahl der Spiele entspricht. Wenn Sie dieses Problem nun beheben, indem Sie die „GamesLost“-Statistik entfernen und sie stattdessen als „GamesPlayed“–„GamesWon“ berechnen, kann dies im Fall einer Inkonsistenz dazu führen, dass „GamesLost“ ein negativer Wert ist. Entfernen Sie in diesem Fall lieber die „GamesPlayed“-Statistik und berechnen Sie den Wert als „GamesWon“ + „GamesLost“.

Globale Statistiken

Sie können Statistiken auf der Admin-Seite als aggregiert kennzeichnen, damit Steam einen Gesamtwert aller durch den Benutzer erzielten Werte für diese Statistik speichert. So können Sie beispielsweise Daten wie insgesamt im Wirtschaftssystem ausgegebenes Geld, Gesamtfertigkeiten, beliebteste Waffen, beliebteste Karten, bestes Team usw. abrufen. Andererseits sollten Sie dies nicht für Statistiken wie „MostKills“ verwenden, da hier eine Summe der Werte mehrerer Benutzer sinnlos wäre. Da Benutzer Zugriff auf diese Statistiken haben, kann es zu Manipulationen dieser Daten kommen. Daher ist es bei Verwendung aggregierter Statistiken wichtig sinnvolle Grenzen festzulegen, wie zum Beispiel Mindestwerte, Höchstwerte, nur ansteigend (falls zutreffend) und maximale Änderung. Die maximale Änderung hat eine besondere Bedeutung für aggregierte Statistiken. Wenn ein neuer Wert hochgeladen wird, ändert sich der globale Wert höchstens um den Betrag der maximalen Änderung. So wird eingeschränkt, wie schnell ein Cheater die globalen Gesamtwerte beeinflussen kann.

Um auf die globalen Gesamtwerte zuzugreifen, rufen Sie ISteamUserStats::RequestGlobalStats und anschließend ISteamUserStats::GetGlobalStat für jede globale Statistik auf. Sie können auch ISteamUserStats::RequestGlobalStats für eine bestimmte Anzahl von Tagen im Verlauf aufrufen. Der Verlauf ist der Betrag um den sich diese Statistik jeden Tag geändert hat. Auf diesen Verlauf können Sie mit ISteamUserStats::GetGlobalStatHistory zugreifen.

Weiterhin können Sie die globale prozentuale Vollständigkeit von Errungenschaften vom Client abrufen. Hierfür rufen Sie zunächst ISteamUserStats::RequestGlobalAchievementPercentages auf. Iterieren Sie die Errungenschaften anschließend in der Reihenfolge von der größten zur geringsten Vollständigkeit mit ISteamUserStats::GetMostAchievedAchievementInfo und ISteamUserStats::GetNextMostAchievedAchievementInfo. Mit ISteamUserStats::GetAchievementAchievedPercent, können Sie auch die prozentuale Vollständigkeit einer bestimmten Errungenschaft abrufen.

Testen


Sie können verdiente Errungenschaften nicht vor Veröffentlichung Ihrer Anwendung in der Steam Community oder Bibliothek einsehen. Ihre Anwendung benötigt daher einen Weg, die Errungenschaften eines Nutzers sichtbar zu machen.

Über die Steam-Client-Konsole können Sie eine Errungenschaft oder Statistik entfernen, ohne Ihrem Spiel Code hinzuzufügen. Starten Sie Steam mit „steam.exe -console“ und geben Sie dann die folgenden Befehle ein:
  • achievement_clear <appid> <achievement name>
  • reset_all_stats <appid>

Die Steam Community

Sobald Ihr Spiel veröffentlicht ist, werden Informationen zu individuellen und globalen Errungenschaftsfortschritten in der Steam Community angezeigt. Jeder Spieler hat einen Link in seinem Community-Profil, der auf eine Seite mit bereits erreichten und noch freizuschaltenden Errungenschaften führt.
HINWEIS: Die Errungenschaften werden erst angezeigt, wenn Ihre Anwendung zu einem gewissen Grad für die Community sichtbar ist.

Jede Errungenschaft wird mit dem in der Steamworks-Systemsteuerung festgelegten Symbol, Namen und Beschreibung aufgelistet. Wenn Name und Beschreibung der Errungenschaft in die vom Benutzer ausgewählte Sprache lokalisiert wurden, werden sie in der entsprechenden Sprache angezeigt.

Auf dieser Seite und auf der Hauptseite Ihres Spiels auf Steam wird außerdem ein Link angezeigt, mit dem Sie globale Statistiken zu Errungenschaften aus Ihrem Spiel einstellen können. Dort wird für jede Errungenschaft der prozentuale Anteil der Steam-Spieler angegeben, der diese Errungenschaft erreicht hat. Die Sortierung erfolgt von der am häufigsten bis zur am seltensten erreichten Errungenschaft. Dies ist interessant für die Spieler und außerdem eine gute Infoquelle für Sie als Entwickler: Sind die von Ihnen gestellten besonderen Herausforderungen anspruchsvoll genug? Oder vielleicht zu anspruchsvoll? (Diese Information ist auch über die Seite für Verkaufs- und Aktivierungsberichte erhältlich.)

Noch Fragen?

Wir freuen uns auf Ihre Fragen im Diskussionsforum zu Errungenschaften und Statistiken.
Steamworks ist eine von Valve entwickelte Sammlung von Werkzeugen und Diensten, die Ihnen helfen, Ihr Spiel auf Steam zu konfigurieren, zu verwalten und zu betreiben.