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.

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 au stockage 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 et Auto-Cloud Steam

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 du Steam Cloud.
L'API du cloud 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 est l'Auto-Cloud Steam.
L'Auto-Cloud Steam 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 du 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 l'Auto-Cloud de Steam.

Auto-Cloud Steam

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

Configuration

Une fois la configuration initiale effectuée, vous pourrez accéder à la section de configuration de l'Auto-Cloud Steam 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.
    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.

Substitutions du chemin d'accès racine

Si votre application est disponible sur plusieurs plateformes et nécessite différents répertoires pour chaque système d'exploitation, vous pouvez utiliser la fonctionnalité de substitution du chemin d'accès racine pour spécifier une substitution des chemins d'accès racine que vous avez 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 systèmes d'exploitation] dans le menu déroulant intitulé « Répertoires racine par OS » situé ci-dessus.

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 l'Auto-Cloud pour les applications Unity

Voici un exemple de configuration de l'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 l'Auto-Cloud seront synchronisés entre les trois dossiers comme indiqué dans les exemples.

Exemple de configuration Auto-Cloud pour les applications Unity

Tests avant sortie

Si vous ajoutez l'Auto-Cloud Steam à 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 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. Tapez testcloudapppaths 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 « équipes de développement uniquement » et de publier les changements une fois le test terminé.

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 Debugging the Steamworks API pour plus d'informations.