XGameSaveFilesGetFolderWithUIAsync. Il décrit également le comportement recommandé de synchronisation cloud automatique Win32, les étapes de débogage, les recommandations en matière de quotas et de diagnostic, les bonnes pratiques en matière de performances, et répond aux questions courantes.
XGameSaveFiles fournit des API qui permettent à votre titre de lire et d’écrire des données utilisateur, de les conserver d’une session à l’autre et de les synchroniser en toute transparence avec le cloud afin que les joueurs puissent utiliser leurs données sur n’importe quel appareil. Utilisez XGameSaveFiles pour les sauvegardes de jeu dans les titres Microsoft Game Development Kit (GDK). N’utilisez XGameSave que lorsque XGameSaveFiles n’est pas disponible pour votre scénario.
Pour la référence de l’API système XGameSaveFiles, consultez XGameSaveFiles (contenu de l’API).
Les termes suivants apparaissent souvent dans XGameSaveFiles.
- 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 de jeu 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.
Logique des chemins XGameSaveFiles
XGameSaveFiles fournit un chemin de fichier que vous pouvez utiliser pour interagir avec le système Game Saves. Ce chemin de fichier est intégré à la synchronisation cloud : les données enregistrées dans ce chemin sont donc automatiquement synchronisées avec le cloud. Utilisez les API Win32 FileIO sur le chemin fourni. Pour les titres GDK, utilisez XGameSaveFiles comme approche Game Saves. XGameSaveFiles fait correspondre les conteneurs aux dossiers et les blobs aux fichiers.
Bien que XGameSaveFiles masque la majeure partie de la complexité du système de sauvegarde cloud, il impose toujours des limites sur les noms de répertoires et de fichiers, car la fonctionnalité s’appuie sur Microsoft Azure Blob Storage. Prenons l’exemple de code suivant, illustrant ce qu’un titre peut utiliser pour sa sauvegarde.
XGameSaveFilesGetFolderWithUiAsyncrenvoie [ROOT].- Tout ce qui suit [ROOT], jusqu’à la dernière barre oblique incluse, correspond à un conteneur.
- Les noms de conteneur sont limités aux lettres majuscules (A-Z), aux lettres minuscules (a-z), aux chiffres (0-9), aux traits de soulignement (_), aux points (.), aux traits d’union (-) et aux barres obliques (/).
- Les noms de conteneur sont limités à 256 caractères.
- Les noms de conteneur ne peuvent pas se terminer par un point, contenir deux points consécutifs, ni commencer par un point ou un trait d’union.
- Tout ce qui suit la dernière barre oblique dans le nom de fichier correspond à un blob.
- Les noms de fichier sont limités à 65 caractères, mais peuvent par ailleurs contenir tous les caractères Unicode pris en charge par le système de fichiers NTFS (New Technology File System).
- Le chemin complet obtenu, y compris le nom de fichier (mais sans [ROOT]), doit être inférieur à
MAX_PATH(260 caractères).
Implémentation de XGameSaveFiles
Les étapes suivantes présentent l’implémentation générale deXGameSaveFiles.
- Au lancement ou à la reprise du titre, appelez
XGameSaveFilesGetFolderWithUIAsyncpour initialiser le fournisseur et obtenir le chemin de fichier. - Lisez et écrivez librement dans le chemin de fichier pendant le jeu.
XGameSaveFilesGetFolderWithUIAsync gère automatiquement la durée de vie du fournisseur Game Saves et configure l’espace de stockage local de Game Saves.
Appelez
XGameSaveFilesGetFolderWithUIAsync au démarrage du titre et lors de sa reprise. Cet appel initialise le fournisseur Game Saves et le maintient actif pendant la session de jeu. Si vous omettez cette étape, le comportement du système peut être imprévisible.Exemple de code
Pour un exemple de code montrant comment utiliser les APIXGameSaveFiles pour accéder à des dossiers sur XBOX, consultez GameSaveFilesCombo.
Flux de Game Saves
Voici un organigramme du flux simplifié de Game Saves.
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 le processus de connexion de l’utilisateur. C’est également lors de cette opération que vous appelezXGameSaveFilesGetFolderWithUIAsync. 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, vous devez activer le mode hors connexion pour le 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é.Synchroniser les 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 ? Si 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 chemin de dossier fourni parXGameSaveFilesGetFolderWithUIAsync.
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. Ce processus a lieu environ 10 à 30 secondes après la fermeture du titre. Pour des informations détaillées sur la synchronisation, consultez Comprendre le flux de synchronisation de Game Saves.Limites et quotas
Limites
La taille de fichier maximale que vous pouvez enregistrer à l’aide deXGameSaveFiles est de 64 Mo. Ce comportement diffère de celui de XGameSave, qui limite chaque fichier à 16 Mo.
Quotas
La quantité maximale de données qu’un utilisateur peut enregistrer par titre est de 256 Mo. Utilisez XGameSaveFilesGetRemainingQuota pour obtenir le quota restant. Pour obtenir une extension de stockage afin que votre titre dispose d’une limite de stockage par utilisateur plus élevée, contactez votre Developer Program Manager (DPM).FAQ
Puis-je utiliser XGameSaveFiles avec XGameSave ?
Oui. Toutefois, n’utilisez cette approche que dans le cadre de migrations. Pour des informations détaillées, consultez Interopérabilité entre XGameSave et XGameSaveFiles.Dans quel chemin de fichier XGameSaveFiles enregistre-t-il ?
Console : le titre fournit un chemin temporaire tant qu’il est actif. Vous ne pouvez pas accéder aux fichiers de la console via l’Explorateur de fichiers. PC :%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<SCID>\
Le chemin PC de XGameSaveFiles est différent de celui de XGameSave. Ce dernier utilise wgs.
Puis-je spécifier le chemin dans lequel les données doivent être enregistrées ?
Oui, mais uniquement sur PC. Nous recommandons cette approche uniquement si vous portez votre solution depuis un autre titre. Cette solution utilise les sauvegardes cloud sans code.Documentation de référence des API
Voir aussi
Table des matières de Game Saves Oui, mais uniquement sur PC. Le portage de votre solution depuis un autre titre peut nécessiter cette approche. Cette solution utilise les sauvegardes cloud sans code.Les sauvegardes cloud sans code nécessitent que le titre soit lancé en tant que build empaquetée à l’aide de
wdapp install. Le lancement direct du fichier .exe n’active pas la redirection des sauvegardes cloud. L’alternance entre des lancements empaquetés et des lancements directs du fichier .exe peut donner l’impression que des données de sauvegarde ont disparu. Pour plus d’informations, consultez Portage de titres antérieurs vers Game Saves sur PC avec les sauvegardes cloud sans code.