XGameSave vous permet de gérer des blobs et des conteneurs pour gérer les données Game Saves. Nous recommandons XGameSaveFiles pour Game Saves dans les titres Microsoft Game Development Kit (GDK). Utilisez XGameSave si XGameSaveFiles n’est pas envisageable.
Pour la référence de l’API système XGameSave, consultez XGameSave (contenu de l’API).
Les termes suivants apparaissent souvent dans XGameSave.
- Verrou : mécanisme qui accorde un accès exclusif aux sauvegardes Game Saves d’un titre pour un utilisateur spécifique sur l’appareil qu’il utilise activement. Il garantit qu’aucun autre appareil ne peut modifier les sauvegardes Game Saves de l’utilisateur tant que le verrou est détenu.
- Par exemple, si un utilisateur joue au titre T sur l’appareil A, celui-ci détient un verrou sur le titre T pour l’utilisateur.
- Fournisseur : processus intermédiaire qui communique avec le système Game Save et qui est chargé de gérer les données du titre. Le fournisseur gère également le verrou d’un utilisateur sur un appareil.
- Conteneurs : équivalents des dossiers.
- Blobs : équivalents des fichiers individuels.
Gestion du fournisseur
Pour acquérir un espace de stockage, le jeu doit initialiser un fournisseur. Après la connexion, le titre tente d’acquérir un verrou sur le stockage cloud du titre en appelantXGameSaveInitializeProvider ou XGameSaveInitializeProviderAsync.
Si le titre ne parvient pas à se synchroniser depuis le cloud en raison d’une perte de connexion, déterminez si les utilisateurs peuvent continuer à jouer en mode hors connexion.
Le titre doit fermer le fournisseur avec XGameSaveCloseProvider lorsqu’il est suspendu ou arrêté. Le fournisseur ne peut pas être réutilisé d’un cycle de suspension-reprise à l’autre.
Ce point s’applique uniquement à
XGameSave. XGameSaveFiles ferme automatiquement le fournisseur.Gestion des conteneurs
Pour éviter toute perte de données lors de l’accès aux conteneurs, par exemple en créant des conteneurs avant la fin de la synchronisation, appelezXGameSaveEnumerateContainerInfo ou XGameSaveEnumerateContainerInfoByName pour afficher les conteneurs d’un utilisateur.
Utilisez XGameSaveCreateContainer pour obtenir un handle de conteneur vers un conteneur nouveau ou existant. Si le conteneur existe déjà, son handle est fourni. Si le conteneur n’existe pas, un nouveau conteneur est créé et son handle est fourni.
Utilisez XGameSaveDeleteContainer pour supprimer un conteneur. Tous les blobs du conteneur sont également supprimés.
Pour éviter les fuites de handles, fermez tous les handles de conteneur avec XGameSaveCloseContainer lorsque le conteneur n’est plus utilisé ou lorsque le titre est suspendu ou arrêté.
Gestion des blobs
La manipulation des données d’un conteneur s’effectue en appelantXGameSaveCreateUpdate.
Les détails suivants décrivent comment XGameSaveUpdate gère les modifications de blobs au sein d’un conteneur et comment chaque mise à jour est créée, modifiée et soumise.
- Une mise à jour s’applique à un seul conteneur.
- Une mise à jour peut écrire au maximum GS_MAX_BLOB_SIZE (16 Mo).
- Plusieurs blobs peuvent être modifiés en une seule mise à jour.
- Un même blob ne peut faire l’objet que d’une seule modification par mise à jour.
-
La soumission d’une mise à jour consomme le handle
XGameSaveUpdate. Fermez le handle, que la soumission ait réussi ou échoué. - Les mises à jour sont atomiques. Si une partie échoue, la mise à jour entière échoue.
-
XGameSaveCreateUpdatecrée un contexte de mise à jour pour stocker toutes vos modifications de blobs. -
XGameSaveSubmitBlobWriteécrit des données dans un blob nouveau ou existant et nécessite un contexte de mise à jour. -
XGameSaveSubmitBlobDeletesupprime le blob. -
XGameSaveSubmitUpdatesoumet le contexte de mise à jour. -
XGameSaveCloseUpdateferme le handle de mise à jour. Le titre l’appelle après chaque soumission pour éviter les fuites. -
Utilisez
XGameSaveEnumerateBlobInfoouXGameSaveEnumerateBlobInfoByNamepour accéder à tous les blobs d’un conteneur.
Les données écrites dans les blobs sont représentées en
Base64 lorsqu’elles sont exportées au format XML.Implémentation
Les étapes suivantes présentent le flux général d’une implémentation deXGameSave.
- Au démarrage ou à la reprise du titre, initialisez le fournisseur.
- Énumérez et créez les handles de conteneur.
- Soumettez régulièrement des
XGameSaveUpdatescontenant les modifications de blobs et nettoyez le handle de mise à jour lors de la soumission. - Fermez les handles de conteneur et de fournisseur lors de la suspension ou de l’arrêt du titre.
Appelez
XGameSaveInitializeProvider au démarrage du titre et lors de sa reprise. Cet appel garantit que le fournisseur s’initialise correctement et reste actif pendant l’exécution du titre. S’il n’est pas appelé, le comportement du titre peut être imprévisible.Exemple de code
Pour un exemple de code montrant comment utiliser les APIXGameSave, consultez GameSaveCombo.
Flux de Game Saves
Voici un organigramme du flux simplifié de Game Saves. Il est expliqué ci-dessous.
Démarrage du titre
Le démarrage du titre a lieu lorsque l’utilisateur lance ou reprend le titre.Connexion de l’utilisateur
Le titre lance la connexion de l’utilisateur. C’est également à cet endroit que vous appelezXGameSaveInitializeProvider.
Pour plus d’informations sur la configuration des utilisateurs, consultez Modèles d’utilisateur.
Vérification de la connexion
Le titre détermine s’il peut se connecter au réseau XBOX. Si ce n’est pas le cas, il vous appartient d’activer le mode hors connexion pour votre titre.Vérification de la propriété des données
L’appareil vérifie si l’utilisateur joue actuellement sur d’autres appareils. Un seul appareil à la fois peut accéder aux données de l’utilisateur pour un titre donné.Synchronisation des données avec le cloud
L’appareil synchronise les données du stockage local de Game Saves avec le cloud. En cas de conflit, le système affiche à l’utilisateur une boîte de dialogue de résolution de conflit. Boîte de dialogue : Laquelle voulez-vous utiliser ? Lorsque les données de l’appareil sont plus récentes que celles du cloud, le titre invite l’utilisateur à choisir entre les données locales et les données cloud.Boucle de jeu
Le titre peut librement lire et écrire dans le stockage local de Game Saves.Fin de la session de jeu
À la fin de la session de jeu, le système tente automatiquement de charger les données dans le cloud. Assurez-vous que votre titre appelleXGameSaveUninitializeProvider lors de son flux de sortie afin de ne pas laisser un fournisseur initialisé. Un arrêt structuré garantit que les données sont correctement enregistrées avant la fermeture.
Pour des informations détaillées sur la synchronisation, consultez Comprendre le flux de synchronisation de Game Saves.
Limites et quotas
Limites
XGameSaveUpdate limite chaque mise à jour à 16 Mo. Par conséquent, XGameSave ne peut gérer que des mises à jour de fichiers individuels allant jusqu’à 16 Mo. Cette limite diffère de celle de XGameSaveFiles, qui prend en charge des fichiers allant jusqu’à 64 Mo.
Quotas
La quantité maximale de données qu’un utilisateur peut enregistrer par titre est de 256 Mo. Utilisez XGameSaveGetRemainingQuota pour obtenir le quota restant. Pour obtenir une extension de stockage pour votre titre, contactez votre Developer Partner Manager (DPM).Bonnes pratiques
- N’enregistrez pas de données pour ensuite les interroger et les redemander immédiatement.
- Les dépendances de données entre conteneurs ne sont pas fiables. Chaque appel à
XGameSaveSubmitUpdateapplique toutes les modifications de manière atomique, ou aucune. - Plus vous utilisez de blobs par appel de mise à jour, plus il faut de temps pour effectuer les opérations atomiques nécessaires du système de fichiers afin de stocker les données.
FAQ
Je mets à niveau mon implémentation de Game Saves. Quelle est la bonne approche ?
Utilisez XGameSaveFiles.Puis-je utiliser XGameSave avec XGameSaveFiles ?
Oui. Toutefois, faites-le uniquement dans le cadre de migrations. Pour des informations détaillées, consultez Interopérabilité entre XGameSave et XGameSaveFiles.Dans quel chemin de fichier XGameSave enregistre-t-il ?
Console : un chemin temporaire est fourni tant que le titre est actif. Les fichiers de la console ne sont pas accessibles via l’Explorateur de fichiers. PC :%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\wgs\<HexXuid>_<SCID>\
Sachez que le chemin PC de XGameSave est différent de celui de XGameSaveFiles. Ce dernier utilise xgs.