Documentation Steamworks
Steam Cloud
En quelques mots
Grâce à Steam Cloud, les fichiers de votre jeu sont automatiquement sauvegardés sur les serveurs Steam pour permettre aux joueurs et joueuses de retrouver leurs parties depuis n'importe quel ordinateur auquel leur compte Steam est connecté.
Niveau d'intégration
Vous devez configurer les chemins d'accès aux fichiers sur le site Web de Steamworks. Certains appels API requis depuis le code du jeu vers Steamworks pour le téléchargement, l'énumération et la suppression (facultatif).

Présentation de Steam Cloud

Steam Cloud offre une solution de stockage des fichiers à distance simple et transparente pour votre jeu. Les fichiers spécifiés dans la configuration de l'Auto-Cloud ou écrits sur le disque (créés, modifiés, supprimés, etc.) à l'aide de l'API du Cloud seront automatiquement répliqués sur les serveurs Steam au moment de quitter le jeu.

Si une personne change d'ordinateur, les fichiers sont automatiquement téléchargés sur le nouvel ordinateur avant le lancement du jeu. Le jeu peut ensuite accéder aux fichiers en les lisant via l'API du Cloud ou directement depuis le disque, comme d'habitude. Évitez les configurations spécifiques à une machine, comme les paramètres vidéo.

Le client Steam s'occupe de vérifier que les fichiers restent synchronisés sur tous les ordinateurs auxquels une personne peut accéder.

Tout le monde peut désactiver complètement la synchronisation avec Steam Cloud depuis le magasin : dans l'onglet « Cloud » des paramètres Steam, décochez « Activer la synchronisation du Steam Cloud pour les applications compatibles ».

Il est aussi possible de désactiver la synchronisation de chaque jeu de manière individuelle depuis les propriétés d'un jeu.

Propriétés de Spacewar

Remarques et bonnes pratiques


Il est important de souligner que Steam synchronisera les fichiers Steam Cloud d'un utilisateur ou une utilisatrice pour votre jeu avant et après chaque session. Tous les fichiers correspondants qui auront été modifiés au cours de la session seront téléchargés dans l'espace cloud dès que cette session prendra fin. Si votre jeu enregistre sur Steam Cloud des fichiers très larges ou un grand nombre de petits fichiers, cela peut avoir un impact significatif sur la bande passante de la personne qui joue. Cela peut aussi retarder la fermeture de Steam ou le redémarrage du jeu.

En règle générale, les fichiers de petite taille sont à préférer. Si l'état d'enregistrement pour une personne donnée peut être divisé en différentes catégories (par exemple, les choses qui sont régulièrement modifiées et celles qui le sont rarement), nous vous conseillons d'utiliser des fichiers séparés pour ces catégories. Ainsi, les états inchangés ne devront pas être à nouveau téléchargés à la fin de chaque session.

Taille maximale des fichiers


La limite absolue de la taille des fichiers sur Steam Cloud peut changer au fil du temps. Voici quelques-unes des limites actuelles :

TailleRestriction
100 MoTaille maximale pour un appel vers ISteamRemoteStorage::FileWrite ou ISteamRemoteStorage::FileWriteStreamWriteChunk
256 MoLe point de terminaison de stockage peut ne pas être optimal pour l'emplacement de l'utilisateur ou l'utilisatrice, ce qui peut impacter négativement les performances de téléchargement.

Enregistrer les chemins d'accès au fichier

Lorsque vous choisissez l'emplacement vos fichiers de sauvegarde, assurez-vous que le chemin d'accès soit uniquement pour le compte Steam utilisé. Si besoin, vous pouvez utiliser ISteamUser::GetSteamID pour obtenir l'ID Steam unique du compte. Pour pourrez ensuite accéder à l'ID du compte à partir de GetAccountID(), et ainsi disposer d'une variable unique lorsque vous définirez votre chemin d'accès.

Cross-Platform Saves


If your game is supported on multiple platforms - or even if you plan to support this in the future - you should consider this when setting up Steam Cloud for your game.

If you plan to read/write files directly via the ISteamRemoteStorage interface, then you can control platform sync via ISteamRemoteStorage::SetSyncPlatforms. The default for a new file is to sync to all platforms.

If you plan to use Steam Auto-Cloud, there are some key things to know. First, the default for new files is to sync to only the OS setting on the associated Auto Cloud Root path. This means that if you set up distinct roots for each OS, all files will be partitioned by platform, and hence there will be no cross-platform save functionality.

To enable cross-platform saves, you should instead define a single Root path (likely for Windows), and then create Root Overrides for the other supported platforms. Files matching a given Root path which also has platform Root Overrides will sync to all platforms in both the origianal Root and all Overrides. See the Steam Auto-Cloud documentation for more details.

Configuration initiale

To set up Steam Cloud you must set the Byte quota per user and Number of files allowed per user options on the Steam Cloud Settings page in the Steamworks App Admin panel.

This quota is enforced on each Cloud-enabled game, on a per-user-per-game basis. It's recommended to set the values to reasonable amounts for your game title.

REMARQUE : Don't forget to click Save at the bottom of the page, and Publish your updated settings. Once published the cloud icon will be visible in the Steam client for anyone that owns your game.

If your game has already been released to the public then you can check the box labeled Enable cloud support for developers only. If developers-only mode is enabled then only the steam accounts which own a "Developer Comp" license for your title will see the cloud icon and will be able to use the Steam Cloud. This is useful to safely test Steam Cloud integration without breaking the public user experience. This has no effect on unreleased games since no one owns the game yet, they won't be able to see or access any cloud storage for the specific app ID.

You are able to share Cloud storage space between two app IDs by filling out the Shared cloud APP ID field. This is most commonly used to share saved games between a demo and a full game. A value of 0 disables this feature.

API de Steam Cloud et Auto-Cloud Steam

Steam provides two different methods of utilizing the Steam Cloud, read up on how the two methods differ, and determine which would be the best for your application.

First up is the Steam Cloud API.
The Cloud API provides a series of functions which allows you to directly integrate the Steam Cloud into your game. The Cloud API isolates individual Steam users files from each other and provides a greater level of control over the Steam Cloud.

The Steam Cloud API is exposed via the ISteamRemoteStorage API interface, and you can find example usage in the Exemple d'application utilisant l'API Steamworks (Spacewar) project.

The second is Steam Auto-Cloud.
Steam Auto-Cloud was designed for games where you choose to not integrate the Steam Cloud API. It provides a quick and easy way to get started but lacks the flexibility that is available with the Steam Cloud API.

If you prefer a deeper integration with Steam Cloud (for example, allowing to choose which save files are stored in the cloud), then you should use the Cloud API. Otherwise you can use Steam Auto-Cloud.

Auto-Cloud Steam

Steam Auto-Cloud is an alternative to the Steam Cloud API that allows apps to use Steam Cloud without writing code or modifying the game in any way. It only requires that you specify the file groups which you want persisted to the Cloud. Steam will automatically sync the groups of files when the application launches and exits. Avoid machine specific configurations such as video quality.
Remarque : le fichier steam_autocloud.vdf sera créé dans chacun des chemins d'accès du cloud que vous avez indiqués sur Steamworks. Ce fichier est utilisé par Steam et peut être ignoré par votre jeu.

Setup

After completing the Configuration initiale the Steam Auto-Cloud configuration section will unlock on the Steam Cloud Settings page.

Root Paths describe groups of files which will be persisted to the Steam Cloud. Each Root Path can be as specific as a single file or as wide as all files under a given subfolder. Use a new path for each group of files to sync.

A Root Path is composed of 5 parts:
  1. Racine

    Voici une liste prédéfinie de chemins où se trouvent généralement les sauvegardes de jeu.
    RacineSystèmes d'exploitation pris en chargeChemin correspondant
    Répertoire d’installation de l’applicationTous[Répertoire d'installation de Steam]\SteamApps\common\[dossier du jeu]\
    SteamCloudDocumentsTousChemin spécifique à la plateforme, par ex. sur Linux : ~/.SteamCloud/[nom]/[dossier du jeu]/
    WinMyDocumentsWindows%USERPROFILE%\Documents\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Saved Games\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. Sous-répertoire

    Chemin du sous-répertoire des fichiers du cloud relatif à la racine. Utilisez « . » s'il n'existe pas de sous-dossier.

    Valeurs de chemin spécifiques à l'Auto-Cloud
    L'Auto-Cloud permet l’utilisation d’identifiants Steam uniques dans le chemin d’accès du sous-répertoire. Vous pouvez donc stocker des fichiers de sauvegarde distincts pour chaque personne qui utilise Steam sur un même ordinateur. Vous pouvez utiliser ISteamUser::GetSteamID dans votre jeu pour obtenir le SteamID ou l'ID actuel du compte pour lequel vous devez enregistrer et lire les fichiers.
    • {64BitSteamID} : utilisez cette variable dans le chemin de Steam pour insérer le SteamID 64 bits du compte Steam. Un SteamID 64 bits ressemble à ceci : 76561198027391269.
    • {Steam3AccountID} : utilisez cette variable dans le chemin de Steam pour insérer l'ID de compte Steam 3. Un ID de compte ressemble à ceci : 67125541.
    Exemple : SavesDir/{64BitSteamID}
  3. Motif

    Filtre sur le nom de fichier. Vous pouvez utiliser * comme caractère générique. Si vous voulez tous les fichiers du répertoire, utilisez seulement *.

    Exemple : *.sav
  4. Système d'exploitation

    Définit les systèmes d'exploitation depuis et vers lesquels ces fichiers seront synchronisés. Requis uniquement si les fichiers sont spécifiques à un système d'exploitation, ce qui ne devrait pas être le cas !
  5. Récursif

    Inclusion des sous-répertoires lors d'une recherche de fichiers correspondant au masque. Cette partie est utile pour les sous-répertoires portant des noms non déterministes comme des noms de comptes ou des ID non Steam. Si des SteamID sont utilisés, alors il est vivement recommandé d'utiliser les valeurs de chemin spéciales dans le champ sous-répertoire.

Root Overrides

If your application is cross-platform and requires different directories for each OS. You can use the Root Overrides functionality to specify an override the Root Paths that you set above.

The root paths specified above can be overridden to correspond to a different path on another OS. If you use Root Overrides, you must specify [All OSes] in the Root OS drop down above.

A Root Override consists of 5 parts.
  1. Chemin racine originel

    Correspond à l'un des chemins d'accès aux racines que vous avez définis plus haut.
  2. Système d'exploitation

    Système d'exploitation auquel appliquer la substitution.
  3. Nouveau chemin racine

    Nouvel emplacement vers lequel dirige le chemin racine originel avec le système d'exploitation spécifié.
  4. Ajouter/remplacer le chemin

    Vous permet d'ajouter éventuellement un chemin de sous-répertoire qui est inséré entre le nouveau chemin racine et le sous-répertoire original.
  5. Remplacer le chemin

    Si cette option est activée, le chemin spécifié dans « Ajouter/remplacer le chemin » remplacera entièrement le sous-répertoire originel.

Example: Configuring Auto-Cloud for Unity Applications

The following is an example of setting up Auto-Cloud for use with Unity and the Application.persistentDataPath property where the value is different per OS. The Windows version is configured as the Root Path with the company in Unity set to DefaultCompany and the Project called AutocloudSample. On macOS and Linux/SteamOS, the alternate paths from Application.persistentDataPath are set in the Add/Replace Path field and Replace Path is enabled.

With these settings, Auto-Cloud files will be synchronized between the three folders as shown in the Preview samples.

Cloud_Unity_Auto-Cloud_Example.png

Pre-release Testing

If you are adding Steam Auto-Cloud to a game which is already released and you have enabled developer-only mode during the Configuration initiale then you must complete some additional steps to test the functionality.
  1. Connectez-vous à Steam avec un compte qui possède l'application que vous testez.
  2. Ouvrez la console Steam en vous rendant sur steam://open/console dans votre navigateur.
  3. Tapez testappcloudpaths <AppId> dans la console avec l'AppID que vous testez. Ex. : testappcloudpaths 480
  4. Tapez set_spew_level 4 4 dans la console.
  5. Lancez votre application depuis Steam.
  6. Recherchez une éventuelle activité dans la console. Si des fichiers existent déjà dans les chemins de l'Auto-Cloud, vous devriez les voir en cours de téléchargement. Sinon, enregistrez quelques fichiers de votre application, puis fermez-les pour déclencher une synchronisation.
  7. Accédez à un autre PC et répétez les étapes ci-dessus pour tester le téléchargement des fichiers depuis l'Auto-Cloud Steam.
  8. Assurez-vous de faire le test pour tous les systèmes d'exploitation pris en charge.
  9. Set testappcloudpaths 0 and set_spew_level 0 0 to end testing. Vous pouvez relancer le client Steam pour ne plus voir l'onglet de la console.

Don't forget to disable developers-only mode and publish the changes when you're done testing.

Synchronisation dynamique avec le cloud


Steam Cloud now supports dynamic sync - where changes appearing in the Cloud can be downloaded to the local machine during an application session. The current example is a suspended game session on the Steam Deck. For apps marked as supporting dynamic Cloud sync, Steam will synchronize files up to the Steam Cloud at the suspend time. Then, the user may run the game on another device, which will receive the updates from the Steam Deck session at launch. At exit, those changes will be uploaded to the Steam Cloud. Finally, when the Steam Deck device is awakened, Steam will synchronize the changes down to that device, and post a notification to the application that local files have changed. The application can then iterate those changes and take appropriate action. For instance, the game may be able to simply load the updated progress from disk and allow the user to pick up right where they left off on the other device.

Check out our announcement post for even more information about why this feature exists, and how to use it.

Note that this feature supports applications whether they use the ISteamRemoteStorage API to manage files, or Auto-Cloud.

For more details, see the ISteamRemoteStorage documentation, specifically ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount, and ISteamRemoteStorage::GetLocalFileChange.

See also ISteamRemoteStorage::BeginFileWriteBatch and ISteamRemoteStorage::EndFileWriteBatch - these wrappers should be used to provide hints to Steam which will help it safely sync up to the Steam Cloud at the time when the user initiates a system suspend.

Pre-release Testing


You can locally enable Dynamic Cloud Sync for your app to test your builds - this is recommended for a game that has already shipped, as enabling Dynamic Cloud Sync for all users could lead to data loss when running builds that do not handle the new API methods and callbacks.

To test locally from a PC:

  1. Sign in to Steam with an account that owns the app that you are testing.
  2. Open the Steam Console by navigating to steam://open/console in your browser. (You can also run Steam with the command-line steam -console and then navigate to the Console section directly).
  3. Enter @cloud_testdynamicsyncapp <AppId> into the console with the given App ID that you are testing. Ex: @cloud_testdynamicsyncapp 480
  4. Launch your app from Steam.
  5. Progress through the game to a desired amount
  6. In the Steam Console, enter prepare_for_suspend. Steam will suspend your game process and upload any changed files to the Steam Cloud.
  7. Optional: play the game on another device, creating further progress, and then exit and let that Steam client upload progress to the Steam Cloud.
  8. Back on the original device, in the Steam Console, enter resume_suspended_games. This will sync down any necessary files from the Steam Cloud, post the relevant API calls to your game, then un-suspend your game process.

To test locally from a Steam Deck:

  1. Connect your Steam Deck with a Devkit
  2. To use the CEF Console, see here
  3. In the JS console, enter SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) to enable testing. You can then enter SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) to disable it

Debugging

First, always ensure that you have published your changes on the Steam partner website and have waited up to 10 minutes or restarted your Steam client to receive the published changes.

If you run into issues with Steam Cloud you should check the log file located at %Steam Install%\logs\cloud_log.txt.

See Debugging the Steamworks API for additional information.