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 Steam 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éos.

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.

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 :

Taille	Restriction
100 Mo	Taille maximale pour un appel vers ISteamRemoteStorage::FileWrite ou ISteamRemoteStorage::FileWriteStreamWriteChunk
256 Mo	Le 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 le SteamID 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.

Sauvegardes multiplateformes

Si votre jeu est pris en charge sur plusieurs plateformes, ou si vous prévoyez qu'il le devienne, vous devriez en tenir compte lors de la configuration de Steam Cloud pour votre jeu.

Si vous prévoyez d'écrire ou de lire des fichiers directement via l'interface ISteamRemoteStorage, vous pouvez contrôler la synchronisation des plateformes avec ISteamRemoteStorage::SetSyncPlatforms. La synchronisation de toutes les plateformes est le paramètre par défaut des nouveaux fichiers.

Si vous prévoyez d'utiliser Steam Auto-Cloud, certaines choses sont à prendre en compte. Premièrement, les nouveaux fichiers sont synchronisés par défaut uniquement avec le système indiqué dans la colonne Système d'exploitation du chemin racine Steam Auto-Cloud associé. Cela signifie que si vous configurez des répertoires racines spécifiques pour chaque système d'exploitation, tous les fichiers seront partitionnés par plateforme et il n'y aura donc pas de fonctionnalité de sauvegarde multiplateforme.

Pour activer les sauvegardes multiplateformes, il faut définir un chemin d'accès racine unique (le plus souvent pour Windows), puis créer des substitutions de chemin racine pour les autres plateformes prises en charge. Les fichiers correspondant à un chemin d'accès racine donné, qui possède également des substitutions de chemin racine, se synchronisent avec toutes les plateformes dans le répertoire racine d'origine et dans toutes les substitutions. Consultez la documentation de Steam Auto-Cloud pour en savoir plus.

Configuration initiale

Pour configurer Steam Cloud, vous devez définir le quota d'octets par personne et le nombre de fichiers autorisés par personne dans la section Paramètres de Steam Cloud du panneau d'administration de l'application de Steamworks.

Ce quota est appliqué à chaque jeu qui utilise le cloud, pour chaque personne. Il est recommandé de définir des valeurs raisonnables pour votre jeu.

REMARQUE : n'oubliez pas de cliquer sur Sauvegarder en bas de la page et de publier vos paramètres mis à jour. Une fois les changements publiés, l'icône du cloud sera visible dans le client Steam par toute personne qui possède votre jeu.

Si votre jeu est déjà sorti, vous pouvez cocher la case intitulée Activer la prise en charge du cloud pour les équipes de développement uniquement. Si le mode « Équipes de développement uniquement » est activé, seuls les comptes Steam qui possèdent une licence « Developer Comp » pour votre titre pourront voir l'icône du cloud et utiliser Steam Cloud. Cette option est utile pour tester de manière sécurisée l'intégration de Steam Cloud sans gêner l'expérience du public. Elle n'a aucun effet sur les jeux non sortis, puisque personne encore ne les possède. Personne ne pourra donc voir ou accéder à l'espace cloud pour l'AppID spécifique.

Vous pouvez partager l'espace de stockage du cloud entre deux AppID en remplissant le champ Partage du cloud avec l'AppID. En général, cette fonctionnalité est utilisée pour partager les sauvegardes de jeu entre une démo et un jeu complet. Vous pouvez la désactiver en introduisant la valeur 0.

API de Steam Cloud ou Steam Auto-Cloud

Steam propose deux méthodes d'utilisation de Steam Cloud. Découvrez les différences entre ces deux méthodes et déterminez celle qui convient le mieux à votre application.

La première méthode est l'API de Steam Cloud.
Cette API fournit une série de fonctions qui vous permettent d'intégrer directement Steam Cloud dans votre jeu. L'API du cloud isole les fichiers individuels des personnes qui utilisent Steam et fournit un plus grand niveau de contrôle sur Steam Cloud.

L'API de Steam Cloud est exposée via l'interface ISteamRemoteStorage. Vous trouverez un exemple d'utilisation dans le projet Exemple d'application utilisant l'API Steamworks (Spacewar).

La deuxième méthode repose sur Steam Auto-Cloud.
Steam Auto-Cloud a été conçu pour les jeux pour lesquels vous décidez de ne pas intégrer l'API de Steam Cloud. Cette méthode fournit un moyen simple et rapide pour commencer, mais il lui manque la souplesse qu'offre l'API de Steam Cloud.

Si vous préférez une intégration plus poussée avec Steam Cloud (par exemple, permettre de choisir quels fichiers sont sauvegardés dans le cloud), utilisez plutôt l'API de Steam Cloud. Sinon, vous pouvez utiliser Steam Auto-Cloud.

Steam Auto-Cloud

Steam Auto-Cloud est une alternative à l'API de Steam Cloud qui permet aux applications d'utiliser Steam Cloud sans écrire de code ou modifier le jeu. Cette fonction vous demande uniquement de spécifier les groupes de fichiers que vous voulez rendre permanents dans le cloud. Steam synchronise automatiquement les groupes de fichiers au démarrage et à l'arrêt de l'application. Évitez les configurations spécifiques à une machine, comme la qualité vidéo.

Configuration

Une fois la configuration initiale effectuée, vous pourrez accéder à la section de configuration de Steam Auto-Cloud depuis les paramètres de Steam Cloud.

Les chemins racine décrivent les groupes de fichiers qui resteront persistants sur Steam Cloud. Chaque chemin racine peut être aussi spécifique qu'un fichier unique ou aussi large que tous les fichiers d'un sous-dossier donné. Utilisez un nouveau chemin pour chaque groupe de fichiers à synchroniser.

Un chemin racine est composé de 5 parties :

1. Racine

   Voici une liste prédéfinie de chemins où se trouvent généralement les sauvegardes de jeu.
   

   Racine	Systèmes d'exploitation pris en charge	Chemin correspondant
   Répertoire d'installation de l'application	Tous	[Répertoire d'installation de Steam]\SteamApps\common\[dossier du jeu]\
   SteamCloudDocuments	Tous	Chemin spécifique à la plateforme, par ex. sur Linux : ~/.SteamCloud/[nom]/[dossier du jeu]/
   WinMyDocuments	Windows	%USERPROFILE%\Documents\
   WinAppDataLocal	Windows	%USERPROFILE%\AppData\Local\
   WinAppDataLocalLow	Windows	%USERPROFILE%\AppData\LocalLow\
   WinAppDataRoaming	Windows	%USERPROFILE%\AppData\Roaming\
   WinSavedGames	Windows	%USERPROFILE%\Saved Games\
   MacHome	macOS	~/
   MacAppSupport	macOS	~/Library/Application Support/
   MacDocuments	macOS	~/Documents/
   LinuxHome	Linux	~/
   LinuxXdgDataHome	Linux	$XDG\_DATA\_HOME/

   
   Remarque concernant les chemins %USERPROFILE% de Windows : les chemins correspondants énumérés ci-dessus sont les emplacements par défaut. Il est désormais possible de configurer son installation Windows pour que ces dossiers se trouvent à des emplacements différents (pas nécessairement sous %USERPROFILE%). Steam utilise les API Windows nécessaires pour trouver l'emplacement actuel de ces dossiers, que leur chemin d'accès soit défini par défaut ou personnalisé.
   
   

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 à Steam Auto-Cloud
   Steam 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.

Substitutions de chemin racine

Si votre application est multiplateforme et nécessite différents répertoires pour chaque système d'exploitation, vous pouvez utiliser la fonctionnalité de substitution de chemin racine pour spécifier un remplacement pour les chemins racines définis plus haut.

Les chemins racine indiqués ci-dessus peuvent être remplacés pour correspondre à un répertoire différent sur un autre système d'exploitation. Si vous utilisez l'option de substitution du chemin d'accès racine, vous devrez choisir l'option [Tous les OS] dans le menu déroulant intitulé « Système d'exploitation » situé plus haut.

Une substitution de chemin racine est composée de 5 parties :

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.

Exemple : configurer Steam Auto-Cloud pour les applications Unity

Voici un exemple de configuration de Steam Auto-Cloud pour une utilisation avec Unity et la propriété Application.persistentDataPath où la valeur est différente suivant le système d'exploitation. La version Windows est configurée comme chemin racine. L'entreprise définie dans Unity correspond à « DefaultCompany » et le projet est intitulé « AutocloudSample ». Sur macOS et Linux/SteamOS, les autres chemins depuis Application.persistentDataPath sont définis dans le champ « Ajouter/remplacer le chemin », et l'option « Remplacer le chemin » est activée.

Avec ces paramètres, les fichiers de Steam Auto-Cloud seront synchronisés entre les trois dossiers comme indiqué dans les exemples.

Tests avant sortie

Si vous ajoutez Steam Auto-Cloud à un jeu qui est déjà sorti et que vous avez activé le mode « Équipe de développement uniquement » pendant la configuration initiale, vous devrez suivre quelques étapes supplémentaires pour tester la fonctionnalité.

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 Steam Auto-Cloud, vous devriez les voir se mettre en ligne. 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 Steam Auto-Cloud.
   
8. Assurez-vous de faire le test pour tous les systèmes d'exploitation pris en charge.
   
9. Tapez testappcloudpaths 0 et set_spew_level 0 0 pour mettre fin au test. Vous pouvez relancer le client Steam pour ne plus voir l'onglet de la console.

N'oubliez pas de désactiver le mode « équipe de développement uniquement » et de publier les changements une fois le test terminé.

Synchronisation dynamique avec le cloud

Steam Cloud prend désormais en charge la synchronisation dynamique : les changements apparaissant dans le cloud peuvent être téléchargés en local au cours d'une session sur l'application. Par exemple, voici une session de jeu mise en pause sur Steam Deck. Pour les applications qui prennent en charge la synchronisation dynamique avec le cloud, Steam synchronisera les fichiers vers Steam Cloud au moment de la mise en pause. Il sera ensuite possible de lancer le jeu sur un autre appareil qui recevra, dès le lancement du jeu, les données actualisées issues de la session interrompue sur Steam Deck. Lorsque le jeu sera fermé sur cet autre appareil, les données seront renvoyées sur le Steam Cloud. Enfin, lorsque Steam Deck sera rallumé, Steam y synchronisera les changements effectués. Une notification sera envoyée à l'application pour lui signaler que des fichiers locaux ont été modifiés. L'application pourra alors itérer ces changements et prendre les mesures adéquates. Par exemple, il est possible que le jeu soit capable de charger la progression la plus récente depuis le disque et permettre à la personne de reprendre là où elle s'était arrêtée sur l'autre appareil.

Veuillez consulter notre billet d'annonce pour plus d'informations concernant cette fonctionnalité et comment l'utiliser.

Cette fonctionnalité prend en charge toutes les applications qui gèrent leurs fichiers via l'API ISteamRemoteStorage ou via Steam Auto-Cloud.

Pour plus de détails, veuillez consulter l'article de la documentation sur l'interface ISteamRemoteStorage, notamment les sections ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount, et ISteamRemoteStorage::GetLocalFileChange.

Consultez également les sections ISteamRemoteStorage::BeginFileWriteBatch et ISteamRemoteStorage::EndFileWriteBatch de l'article. Ces wrappers doivent être utilisés pour aider Steam à synchroniser en toute sécurité les données vers le Steam Cloud lorsque le système est suspendu.

Tests avant sortie

Vous pouvez activer la synchronisation dynamique avec le cloud en local pour tester vos builds. Cette option est recommandée pour les jeux qui sont déjà sortis, car l'activation de la synchronisation dynamique avec le cloud peut entrainer une perte de données pour tous les utilisateurs et utilisatrices s'ils exécutent des builds qui ne peuvent pas gérer correctement les nouvelles méthodes et rappels d'API.

Pour tester en local depuis un PC :

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. Il est également possible d'exécuter Steam avec la commande steam -console puis en naviguant directement vers la section Console.
   
3. Tapez @cloud_testdynamicsyncapp <AppId> dans la console avec l'AppID que vous testez. Ex. : @cloud_testdynamicsyncapp 480
   
4. Lancez votre application depuis Steam.
   
5. Atteignez le niveau de progression souhaité dans le jeu.
   
6. Dans la console Steam, exécutez la commande prepare_for_suspend. Steam suspendra votre progression en jeu et enverra les fichiers modifiés vers Steam Cloud.
   
7. Facultatif : essayez le jeu sur un autre appareil et continuez votre progression. Quittez ensuite le jeu et laissez le client Steam envoyer les progrès à Steam Cloud.
   
8. Ouvrez la console sur le premier appareil et exécutez resume_suspended_games. Cela synchronisera et téléchargera tous les fichiers nécessaires avec Steam Cloud, effectuera les appels API pertinents pour votre jeu et activera à nouveau votre progression.

Pour tester en local depuis Steam Deck :

1. Connectez votre Steam Deck à un kit de développement.
   
2. Pour savoir comment utiliser la console CEF, consultez cette page.
   
3. Tapez SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) dans la console JavaScript pour lancer le test. Pour y mettre fin, tapez SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”).

Débogage

Pour commencer, assurez-vous toujours d'avoir bien publié vos changements sur le site des partenaires Steam et d'avoir attendu jusqu'à 10 minutes ou relancé votre client Steam pour que les changements publiés soient effectifs.

Si vous rencontrez un problème avec Steam Cloud, consultez le fichier journal à l'emplacement %Steam Install%\logs\cloud_log.txt.

Consultez l'article Débogage de l'API Steamworks pour plus d'informations.