Steamworks-Dokumentation
Steam Cloud
Kurz dargestellt
Die Steam Cloud speichert automatisch Daten Ihres Spiels auf Steam-Servern. So haben Ihre Spieler nach Anmeldung auf Steam von jedem Computer aus Zugriff auf ihre Speicherstände.
Integrationslevel
Auf der Steamworks-Website ist die Konfiguration der Dateipfade erforderlich. Uploads, Downloads sowie Aufzählen und Löschen erfordern einige API-Aufrufe aus dem Spielcode heraus an Steamworks. (Optional.)

Steam Cloud – Übersicht

Die Steam Cloud bietet ein einfaches und transparentes System zum externen Speichern von Dateien für Ihr Spiel. Alle in der Auto-Cloud-Konfiguration angegebenen oder über die Cloud-API auf das Laufwerk geschriebenen Dateien (erstellt, geändert, gelöscht etc.) werden nach Beendigung des Spiels automatisch auf den Steam-Servern repliziert.

Wenn der Benutzer zu einem anderen Computer wechselt, werden die Dateien automatisch auf den neuen Computer heruntergeladen, bevor das Spiel startet. Das Spiel liest dann die Daten entweder über die Cloud-API oder wie gewöhnlich direkt vom Laufwerk. Vermeiden Sie gerätespezifische Konfigurationen, z. B. Videoeinstellungen.

Der Steam-Client stellt sicher, dass die Dateien auf allen Computern eines Benutzers synchron bleiben.

Benutzer können die Cloud-Synchronisation in den Steam-Einstellungen global deaktivieren, indem Sie die Option „Steam-Cloud-Synchronisation für alle unterstützten Anwendungen aktivieren“ deaktivieren.

Benutzer können die Cloud-Synchronisation auch für einzelne Spiele in den Eigenschaften des jeweiligen Spiels deaktivieren.

Spacewar_Cloud_Properties.png

Hinweise und bewährte Praktiken


Steam synchronisiert die Steam-Cloud-Dateien von Nutzern vor und nach jeder Spielsitzung. Während einer Spielsitzung veränderte Dateien werden sofort nach Beendigung dieser in die Steam Cloud hochgeladen. Das Speichern sehr großer oder vieler kleiner Dateien in der Steam Cloud kann die Bandbreite von Nutzern belasten und das Beenden von Steam sowie einen Neustart des jeweiligen Spiels verzögern.

Im Allgemeinen empfehlen wir kleinere Dateien zu verwenden. Weiterhin empfehlen wir separate Dateien zu verwenden, wenn der Spielstand eines Nutzers in verschiedene Kategorien aufgeteilt werden kann, wie z. B. in Speicherstände die sich häufig ändern und solche, die sich nur selten ändern. Auf diese Weise werden unveränderte Speicherstände nicht nach jeder Spielsitzung erneut hochgeladen.

Maximale Dateigröße


Die zulässigen Größen für Steam-Cloud-Dateien können sich mit der Zeit ändern. Hier die aktuellen Maximalgrößen:

GrößeBeschränkung
100MBMaximale Größe für einen Aufruf an ISteamRemoteStorage::FileWrite oder ISteamRemoteStorage:;FileWriteStreamWriteChunk
256MBKann zu einer nicht optimalen Speicherendpunktauswahl für den Standort des Benutzers führen und dessen Upload-/Downloadleistung beeinträchtigen.

Ersteinrichtung

Um die Steam Cloud einzurichten, müssen Sie die Optionen Bytekontingent pro Nutzer und Erlaubte Anzahl von Dateien pro Nutzer auf der Seite Steam-Cloud-Einstellungen im Verwaltungsfenster der Steamworks-App einstellen.

Dieses Kontingent wird für jedes für die Cloud aktivierte Spiel pro Benutzer pro Spiel durchgesetzt. Wir empfehlen, die Werte auf für Ihren Titel angemessene Beträge zu setzen.

HINWEIS: Vergessen Sie nicht, unten auf der Seite auf „Speichern“ zu klicken und die geänderten Einstellungen zu veröffentlichen. Nach der Veröffentlichung wird allen Besitzern Ihres Spiels das Cloud-Symbol im Steam-Client angezeigt.

Bei einem bereits veröffentlichten Spiel können Sie das Kontrollkästchen Cloud-Support nur für Entwickler aktivieren markieren. Bei dieser Auswahl wird das Cloud-Symbol nur für Accounts angezeigt, die eine „Developer Comp“-Lizenz für Ihren Titel besitzen, und nur diese Accounts können die Steam Cloud nutzen. So können Sie die Steam Cloud-Integration sicher testen, ohne das Spielerlebnis öffentlicher Benutzer zu beeinträchtigen. Dies hat keine Auswirkung auf unveröffentlichte Spiele, da noch niemand diese Spiele besitzt und daher keinen Cloud-Speicher für diese App-ID sehen oder aufrufen kann.

Sie können Cloud-Speicherplatz für zwei App-IDs gemeinsam verwenden, indem Sie das Feld Geteilte Cloud-App-ID ausfüllen. Diese Option wird häufig verwendet, um Speicherstände aus Demos in die Vollversion zu übernehmen. Ein Wert von 0 deaktiviert diese Funktion.

Steam-Cloud-API und Steam-Auto-Cloud

Steam bietet zwei verschiedene Methoden für die Nutzung der Steam Cloud. Im Folgenden geben wir Ihnen einen Überblick über die Unterschiede, damit Sie entscheiden können, welche Methode für Ihre Anwendung am besten geeignet ist.

Die erste Methode ist die Steam-Cloud-API.
Mit den Funktionen der Cloud-API können Sie die Steam Cloud direkt in Ihr Spiel integrieren. Die Cloud-API isoliert einzelne Steam-Benutzerdateien voneinander und bietet eine umfangreichere Kontrolle über die Steam Cloud.

Die Steam-Cloud-API wird über die API-Schnittstelle ISteamRemoteStorage bereitgestellt. Beispiele für deren Verwendung finden Sie im Projekt Steamworks API Example Application (SpaceWar).

Die zweite ist die Steam-Auto-Cloud.
Steam-Auto-Cloud wurde für ältere Spiele entwickelt, bei denen Sie die Steam-Cloud-API nicht so einfach implementieren können. Mit Steam-Auto-Cloud ist der Start schnell und einfach. Allerdings bietet diese Methode nicht denselben Funktionsumfang und nicht dieselbe Flexibilität wie die Steam-Cloud-API.

Wo immer möglich empfehlen wir die Verwendung der Cloud-API. Sie kann besser integriert und angepasst werden und gewährleistet Steam-Benutzern das hochwertige Erlebnis, das diese inzwischen von der Steam Cloud erwarten.

Steam-Auto-Cloud

Steam-Auto-Cloud ist eine Alternative zur Steam-Cloud-API, mit der Anwendungen die Steam Cloud verwenden können, ohne dass hierfür Code geschrieben oder das Spiel modifiziert werden muss. Sie müssen lediglich die Dateigruppen angeben, die persistent in der Cloud gespeichert werden sollen. Steam synchronisiert die Dateigruppen dann bei jedem Starten und Beenden der Anwendung. Vermeiden Sie gerätespezifische Konfigurationen, z. B. Grafikqualität.

Konfiguration

Nach Abschluss der Ersteinrichtung wird der Abschnitt zur Steam-Auto-Cloud-Konfiguration auf der Seite Steam-Cloud-Einstellungen aktiviert.

Stammverzeichnispfade geben Gruppen von Dateien an, die persistent in der Steam Cloud gespeichert werden sollen. Jeder Stammverzeichnispfad kann beliebig spezifisch sein, von einer einzelnen Datei bis hin zu allen Dateien eines bestimmten Unterordners. Verwenden Sie für jede Gruppe zu synchronisierender Dateien einen neuen Pfad.

Ein Stammverzeichnispfad besteht aus fünf Teilen:
  1. Stammverzeichnis

    Dies ist eine vordefinierte Liste von Pfaden, in denen normalerweise Spielstände gespeichert werden.
    StammverzeichnisUnterstützte BetriebssystemeZugehöriger Pfad
    App-InstallationsverzeichnisAlle[Steam-Installationsordner]\SteamApps\common\[Spielordner]\
    SteamCloudDocumentsAllePlattform-spezifischer Pfad, z. B. auf Linux: ~/.SteamCloud/[Benutzername]/[Spielordner]/
    WinMyDocumentsWindows%USERPROFILE%\Dokumente\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Gespeicherte Spiele\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. Unterverzeichnis

    Unterverzeichnispfad zu den Cloud-Dateien relativ zum Stammverzeichnis. Verwenden Sie `.`, wenn kein Unterverzeichnis vorhanden ist.

    Spezielle Auto-Cloud-Pfadwerte
    Auto-Cloud ermöglicht die Verwendung eindeutiger Steam-Benutzer-Bezeichner im Unterverzeichnis-Pfad. So können Sie Spielstände für jeden Benutzer des Computers separat speichern. Sie können ISteamUser::GetSteamID in Ihrem Spiel verwenden, um die Steam-ID oder die Account-ID des aktuellen Benutzers für Speicher- und Lesevorgänge abzurufen.
    • {64BitSteamID} – Verwenden Sie diese Variable im Steam-Pfad, um die 64-Bit-Steam-ID des Benutzers einzufügen. Eine 64-Bit Steam-ID sieht wie folgt aus: 76561198027391269.
    • {Steam3AccountID} – Verwenden Sie diese Variable im Steam-Pfad, um die 3-Bit-Steam-ID des Benutzers einzufügen. Eine Account-ID sieht wie folgt aus: 67125541.
    Beispiel: SavesDir/{64BitSteamID}
  3. Muster

    Passendes Dateimaskenmuster. Sie können * als Platzhalter verwenden. Wenn Sie alle Dateien im Verzeichnis einschließen möchten, verwenden Sie einfach*.

    Beispiel: *.sav
  4. Betriebssystem

    Legt das Betriebssystem fest, mit/von dem die Dateien synchronisiert werden. Dies ist nur erforderlich, wenn die Dateien betriebssystemspezifisch sind, was hoffentlich nicht der Fall ist.
  5. Rekursiv

    Bezieht Unterverzeichnisse bei der Suche nach Dateien mit ein. Dies ist nützlich bei Unterverzeichnissen mit nicht-deterministischen Namen, z. B. Namen oder IDs von Nicht-Steam-Benutzern. Wenn Sie eine Steam-ID verwenden, wird die Nutzung der speziellen Pfadwerte im Feld „Unterverzeichnis“ dringend empfohlen.

Stammverzeichnis-Überschreibungen

Wenn Ihre Anwendung mehrere Plattformen unterstützt und für jedes Betriebssystem andere Verzeichnisse erforderlich sind, können Sie die oben eingestellten Stammverzeichnisse mit der Root Overrides-Funktion überschreiben.

Die oben angegebenen Stammverzeichnispfade können überschrieben werden, damit auf einem andern Betriebssystem auf einen anderen Pfad verwiesen wird. Wenn Sie Stammverzeichnis-Überschreibungen verwenden, müssen Sie oben im Dropdown mit den Stammverzeichnis-Betriebssystemen die Option [Alle Betriebssysteme] angeben.

Eine Stammverzeichnis-Überschreibung besteht aus fünf Teilen:
  1. Original-Stammverzeichnis

    Dies entspricht einem der oben eingestellten Stammverzeichnisse.
  2. Betriebssystem

    Das Betriebssystem, auf das die Überschreibung angewendet wird.
  3. Neues Stammverzeichnis

    Der neue Speicherort, auf den das Original-Stammverzeichnis auf dem angegebenen Betriebssystem verweist.
  4. Pfad hinzufügen/ersetzen

    Hiermit können Sie optional einen Unterverzeichnispfad hinzufügen, der zwischen dem neuen Stammverzeichnis und dem originalen Stammverzeichnis eingefügt wird.
  5. Pfad ersetzen

    Wenn aktiviert, wird das originale Unterverzeichnis vollständig durch den unter „Pfad hinzufügen/ersetzen“ angegebenen Pfad ersetzt.

Beispiel: Konfigurieren von Auto-Cloud für Unity-Anwendungen

Das folgende Beispiel zeigt die Einrichtung von Auto-Cloud für die Verwendung mit Unity und der Eigenschaft Application.persistentDataPath, bei der der Wert je nach Betriebssystem anders ist. Die Windows-Version wird als Stammverzeichnispfad konfiguriert, das Unternehmen in Unity wird auf DefaultCompany gesetzt und das Projekt wird AutocloudSample genannt. Auf macOS und Linux/SteamOS werden die alternativen Pfade von Application.persistentDataPath im Feld „Pfad hinzufügen/ersetzen“ festgelegt und „Pfad ersetzen“ wird aktiviert.

Mit diesen Einstellungen werden Auto-Cloud-Dateien zwischen den im Beispiel unter „Vorschau“ angezeigten drei Ordnern synchronisiert.

Cloud_Unity_Auto-Cloud_Example.png

Testen vor der Veröffentlichung

Wenn Sie Steam-Auto-Cloud einem bereits veröffentlichten Spiel hinzufügen und während der Ersteinrichtung den Entwicklermodus aktiviert haben, müssen Sie einige zusätzliche Schritte ausführen, um die Funktionalität zu testen.
  1. Melden Sie sich bei Steam mit einem Account an, der eine Developer Comp-Lizenz für die zu testende Anwendung besitzt.
  2. Öffnen Sie die Steam-Konsole, indem Sie in Ihrem Browser zu steam://open/console navigieren.
  3. Geben Sie testappcloudpaths <AppId> mit der App-ID der zu testenden Anwendung ein. Beispiel: testappcloudpaths 480
  4. Geben Sie set_spew_level 4 4 in die Konsole ein.
  5. Starten Sie Ihre Anwendung von Steam aus.
  6. Prüfen Sie auf Konsolenaktivität. Wenn in den Auto-Cloud-Pfaden bereits Dateien vorhanden sind, sollten diese jetzt hochgeladen werden. Speichern Sie anderenfalls einige Dateien aus Ihrer Anwendung und schließen Sie dann die Anwendung, um eine Synchronisierung auszulösen.
  7. Wechseln Sie zu einem anderen PC und wiederholen Sie die Schritte oben, um den Download von Dateien aus Steam-Auto-Cloud zu testen.
  8. Führen Sie die Tests unbedingt auf allen unterstützten Betriebssystemen durch.
  9. Setzen Sie testcloudapppaths 0 und set_spew_level 0 0 ein, um den Test zu beenden. Um den Konsolen-Tab zu schließen, können Sie den Steam-Client neu starten.

Vergessen Sie nicht nach Abschluss der Testphase den Entwicklermodus zu deaktivieren und die Änderungen, zu veröffentlichen.

Debuggen

Stellen Sie zunächst sicher, dass Sie Ihre Änderungen auf der Steam-Partnerwebsite veröffentlicht und bis zu 10 Minuten gewartet oder Ihren Steam-Client neu gestartet haben, um die veröffentlichten Änderungen zu empfangen.

Sollten Probleme mit Steam Cloud auftreten, prüfen Sie die Protokolldatei unter %Steam Install%\logs\cloud_log.txt.

Weitere Informationen finden Sie unter Debugging the Steamworks API.