Rappels d'interface utilisateur de Game Saves

Game Saves fournit un ensemble de rappels d’interface utilisateur qui permettent à votre jeu de réagir aux événements pendant les opérations de synchronisation. Sur XBOX et Windows, la plateforme fournit une interface utilisateur intégrée pour ces événements. Sur les autres plateformes (comme Steam Deck), votre jeu doit implémenter sa propre interface utilisateur en gérant ces rappels. La définition de rappels sur XBOX et Windows remplace l’interface utilisateur fournie par la plateforme par votre implémentation. Cela est utile si votre jeu doit offrir une expérience de joueur cohérente sur toutes les plateformes. Inscrivez les mêmes rappels partout, et l’interface utilisateur intégrée ne s’affichera pas.

Fonctionnement de la machine à états

Game Saves utilise une machine à états interne pour coordonner les rappels d’interface utilisateur avec le cycle de vie de l’opération asynchrone. Lorsqu’un rappel d’interface utilisateur se déclenche, l’opération asynchrone est suspendue. Le rappel XAsyncBlock ne se déclenche pas tant que le rappel n’est pas résolu. La machine à états ne progresse pas tant que le jeu n’appelle pas l’API de réponse correspondante ou que l’opération asynchrone n’est pas annulée. Cela signifie que :

Chaque type de rappel possède une API de réponse correspondante. Appelez l’API de réponse pour indiquer au système ce qu’il doit faire ensuite.
Les API de réponse peuvent être appelées à l’intérieur ou à l’extérieur de la fonction de rappel.
Si une action de réponse est Retry, l’opération est retentée et peut déclencher de nouveau le même rappel.
Le rappel XAsyncBlock ne se déclenche qu’une fois que l’opération atteint un état final : réussite, annulation ou basculement hors connexion.

Par exemple, si un téléversement échoue en raison de limites de débit :

PFGameSaveFilesUiSyncFailedCallback se déclenche avec l’erreur.
Le rappel XAsyncBlock ne se déclenche pas encore. La machine à états attend une réponse.
Si l’utilisateur sélectionne Retry et que la nouvelle tentative échoue également, le rappel d’échec de synchronisation se déclenche de nouveau.
Si l’utilisateur sélectionne Cancel, le rappel XAsyncBlock se déclenche avec E_PF_GAMESAVE_USER_CANCELLED.
Si une nouvelle tentative réussit, le rappel XAsyncBlock se déclenche avec S_OK.

Moment de déclenchement des rappels

Les rappels d’interface utilisateur ne se déclenchent que pendant deux opérations asynchrones :

Opération	Rappels pouvant se déclencher
`PFGameSaveFilesAddUserWithUiAsync`	Progression, échec de synchronisation, conflit d’appareil actif, conflit, stockage insuffisant
`PFGameSaveFilesUploadWithUiAsync`	Progression, échec de synchronisation

Inscription des rappels

Inscrivez tous les rappels avant d’appeler PFGameSaveFilesAddUserWithUiAsync ou PFGameSaveFilesUploadWithUiAsync :

PFGameSaveUICallbacks callbacks{};
callbacks.progressCallback = MyProgressCallback;
callbacks.progressContext = nullptr;
callbacks.syncFailedCallback = MySyncFailedCallback;
callbacks.syncFailedContext = nullptr;
callbacks.activeDeviceContentionCallback = MyActiveDeviceContentionCallback;
callbacks.activeDeviceContentionContext = nullptr;
callbacks.conflictCallback = MyConflictCallback;
callbacks.conflictContext = nullptr;
callbacks.outOfStorageCallback = MyOutOfStorageCallback;
callbacks.outOfStorageContext = nullptr;

HRESULT hr = PFGameSaveFilesSetUiCallbacks(&callbacks);

Référence des rappels

Progression

Signale la progression du téléversement ou du téléchargement. Utilisez PFGameSaveFilesUiProgressGetProgress dans le rappel pour obtenir le PFGameSaveFilesSyncState actuel, le nombre d’octets traités et le nombre total d’octets. Rappel : PFGameSaveFilesUiProgressCallback API de réponse : PFGameSaveFilesSetUiProgressResponse

Action	Effet
`Cancel`	Annule l’opération. Le rappel `XAsyncBlock` se déclenche avec `E_PF_GAMESAVE_USER_CANCELLED`.

Le rappel de progression n’a pas besoin de réponse pour continuer. L’opération progresse d’elle-même. N’appelez l’API de réponse que si l’utilisateur souhaite annuler.

États de synchronisation

L’énumération PFGameSaveFilesSyncState indique la phase dans laquelle se trouve l’opération :

État	Description	Écriture sécuritaire dans le dossier de sauvegarde?
`NotStarted`	L’opération n’a pas commencé	Oui
`PreparingForDownload`	Préparation du téléchargement à partir du nuage	Oui
`Downloading`	Téléchargement à partir du nuage	Non
`PreparingForUpload`	Lecture et compression des fichiers locaux	Non
`Uploading`	Téléversement vers le nuage en cours (fichiers locaux capturés)	Oui
`SyncComplete`	Opération terminée	Oui

Échec de synchronisation

Se déclenche lorsqu’une opération de synchronisation échoue, par exemple en raison de problèmes réseau ou de limites de débit. Rappel : PFGameSaveFilesUiSyncFailedCallback Paramètres : reçoit PFGameSaveFilesSyncState (la phase qui a échoué) et HRESULT (le code d’erreur). API de réponse : PFGameSaveFilesSetUiSyncFailedResponse

Action	Effet
`Cancel`	Annule l’opération. Le rappel `XAsyncBlock` se déclenche avec `E_PF_GAMESAVE_USER_CANCELLED`.
`Retry`	Retente l’opération ayant échoué. Si la nouvelle tentative échoue, ce rappel se déclenche de nouveau.
`UseOffline`	Valide uniquement pendant `PFGameSaveFilesAddUserWithUiAsync`. Le rappel `XAsyncBlock` se déclenche avec `S_OK`, mais le système passe en mode hors connexion. Utilisez `PFGameSaveFilesIsConnectedToCloud()` pour détecter cet état.

Pour plus de détails sur le comportement du mode hors connexion, consultez Mode hors connexion de Game Saves.

Conflit d’appareil actif

Se déclenche pendant PFGameSaveFilesAddUserWithUiAsync lorsqu’un autre appareil est déjà l’appareil actif pour cet utilisateur. Le rappel reçoit des structures PFGameSaveDescriptor pour les données de sauvegarde locales et distantes, qui comprennent les noms des appareils, les horodatages et la taille des sauvegardes, que vous pouvez afficher pour aider l’utilisateur à prendre une décision. Rappel : PFGameSaveFilesUiActiveDeviceContentionCallback API de réponse : PFGameSaveFilesSetUiActiveDeviceContentionResponse

Action	Effet
`Cancel`	Annule l’opération. Le rappel `XAsyncBlock` se déclenche avec `E_PF_GAMESAVE_USER_CANCELLED`.
`Retry`	Effectue une nouvelle tentative; utile si l’utilisateur s’attend à ce que l’autre appareil se libère bientôt. Si l’autre appareil est toujours actif, ce rappel se déclenche de nouveau.
`SyncLastSavedData`	Fait de l’appareil local l’appareil actif et lance la synchronisation. L’appareil distant ne peut plus téléverser et reçoit une notification de changement d’appareil actif.

Pour plus de détails sur le comportement de l’appareil actif, consultez Changements d’appareil actif de Game Saves.

Conflit

Se déclenche pendant PFGameSaveFilesAddUserWithUiAsync lorsque les données de sauvegarde locales et infonuagiques ont divergé. Le rappel reçoit des structures PFGameSaveDescriptor pour les données de sauvegarde locales et distantes. Rappel : PFGameSaveFilesUiConflictCallback API de réponse : PFGameSaveFilesSetUiConflictResponse

Action	Effet
`Cancel`	Annule l’opération. Le rappel `XAsyncBlock` se déclenche avec `E_PF_GAMESAVE_USER_CANCELLED`.
`TakeLocal`	Conserve les données de sauvegarde locales et les téléverse dans le nuage.
`TakeRemote`	Abandonne les modifications locales et télécharge les données de sauvegarde infonuagiques.

La résolution des conflits s’applique à l’ensemble de la sauvegarde, et non à des fichiers ou dossiers individuels. Pour plus de détails sur la façon dont les conflits sont détectés au niveau de l’unité atomique et résolus globalement, consultez Conflits de Game Saves.

Stockage insuffisant

Se déclenche pendant PFGameSaveFilesAddUserWithUiAsync lorsque l’appareil local ne dispose pas de suffisamment d’espace disque pour télécharger les données de sauvegarde à partir du nuage. Le rappel reçoit requiredBytes, qui indique l’espace nécessaire. Rappel : PFGameSaveFilesUiOutOfStorageCallback API de réponse : PFGameSaveFilesSetUiOutOfStorageResponse

Action	Effet
`Cancel`	Annule l’opération. Le rappel `XAsyncBlock` se déclenche avec `E_PF_GAMESAVE_USER_CANCELLED`.
`Retry`	Effectue une nouvelle tentative après que l’utilisateur a libéré de l’espace de stockage local. S’il n’y a toujours pas assez d’espace, ce rappel se déclenche de nouveau.

En processus ou hors processus (interface utilisateur système)

L’endroit où Game Saves s’exécute dépend de la plateforme, ce qui influe sur la gestion des événements d’interface utilisateur :

Hors processus (XBOX et Windows) : sur XBOX et Windows, Game Saves s’exécute toujours hors processus. La plateforme (Connected Storage / GRTS) effectue la synchronisation et fournit des boîtes de dialogue d’interface utilisateur système intégrées pour les échecs de synchronisation, les conflits, les conflits d’appareil actif et le stockage insuffisant. Le joueur interagit directement avec ces boîtes de dialogue, et la plateforme traduit le résultat en codes de fin d’opération asynchrone identiques à ceux que votre jeu reçoit en processus. Vous pouvez tout de même inscrire des rappels pour remplacer l’interface utilisateur intégrée.
En processus (autres plateformes, comme Steam Deck) : lorsque le service de la plateforme n’est pas disponible, votre jeu héberge le moteur de synchronisation de Game Saves et gère les événements d’interface utilisateur au moyen des rappels décrits ci-dessus. Votre jeu pilote entièrement la machine à états à l’aide des API de réponse.

L’annulation est toujours un résultat possible

Quel que soit le chemin, chaque flux d’interface utilisateur peut se terminer par l’abandon de l’utilisateur sans synchronisation réussie; votre jeu doit donc toujours gérer une annulation finale :

Intention de l’utilisateur	Fin de l’opération asynchrone	`IsConnectedToCloud()`	Dossier de sauvegarde?
Continuer en ligne (réussite)	`S_OK`	`true`	Oui
Jouer hors connexion	`S_OK`	`false`	Oui
Annuler / Quitter (joueur)	`E_PF_GAMESAVE_USER_CANCELLED` (`0x800704C7`)	s.o.	Non
Annuler (le jeu a appelé `XAsyncCancel`)	`E_ABORT` (`0x80004004`)	s.o.	Non

La seule action d’« abandon » qui permet tout de même au joueur de continuer est Use Offline dans l’invite d’échec de synchronisation (un résultat réussi). Toute autre annulation est finale et ne laisse aucun dossier de sauvegarde. Traitez-la comme ne pas permettre de jouer. Consultez Mode hors connexion de Game Saves. Dans l’interface utilisateur système intégrée (hors processus), ces choix s’affichent avec le libellé de la plateforme. Par exemple, la boîte de dialogue d’échec de synchronisation propose « Try again » / « Play offline », et la boîte de dialogue de conflit d’appareil actif propose « Stop sync & continue » / « Quit game ». « Play offline » correspond au mode hors connexion (S_OK, non connecté); « Quit game » correspond à E_PF_GAMESAVE_USER_CANCELLED. L’annulation d’une invite de conflit est finale sur les deux chemins. Elle se termine avec E_PF_GAMESAVE_USER_CANCELLED et ne mène pas à une invite d’échec de synchronisation. Pour une interface utilisateur multiplateforme personnalisée (par exemple, pour correspondre à votre implémentation Steam Deck), inscrivez des rappels partout et validez les flux hors processus sur votre matériel cible. Quel que soit le chemin, conditionnez le jeu au résultat de fin d’opération : S_OK + connecté → jeu en ligne; S_OK + non connecté → jeu hors connexion (avertissez le joueur); annulation ou échec sans dossier → bloquez le jeu.

Exigences des plateformes

Plateforme	Rappels d’interface utilisateur
XBOX et Windows	Facultatifs. Définissez des rappels pour remplacer l’interface utilisateur intégrée.
Autres plateformes (par exemple, Steam Deck)	Obligatoires. Aucune interface utilisateur intégrée n’est disponible; votre jeu doit gérer tous les rappels.

Pour les détails de l’implémentation sur Steam Deck, consultez le Guide d’implémentation pour Steam Deck.

XBOX Services

PlayFab

Fonctionnement de la machine à états

Moment de déclenchement des rappels

Inscription des rappels

Référence des rappels

Progression

États de synchronisation

Échec de synchronisation

Conflit d’appareil actif

Conflit

Stockage insuffisant

En processus ou hors processus (interface utilisateur système)

L’annulation est toujours un résultat possible

Exigences des plateformes

Contenu connexe

​Fonctionnement de la machine à états

​Moment de déclenchement des rappels

​Inscription des rappels

​Référence des rappels

​Progression

​États de synchronisation

​Échec de synchronisation

​Conflit d’appareil actif

​Conflit

​Stockage insuffisant

​En processus ou hors processus (interface utilisateur système)

​L’annulation est toujours un résultat possible

​Exigences des plateformes

​Contenu connexe

Fonctionnement de la machine à états

Moment de déclenchement des rappels

Inscription des rappels

Référence des rappels

Progression

États de synchronisation

Échec de synchronisation

Conflit d’appareil actif

Conflit

Stockage insuffisant

En processus ou hors processus (interface utilisateur système)

L’annulation est toujours un résultat possible

Exigences des plateformes

Contenu connexe