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 nécessite une expérience joueur cohérente sur toutes les plateformes : inscrivez les mêmes rappels partout, et l’interface utilisateur intégrée n’apparaîtra 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’a pas appelé l’API de réponse correspondante ou que l’opération asynchrone n’a pas été 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 la suite à donner.
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 repli hors connexion.

Par exemple, si un chargement é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.

Quand les rappels se déclenchent

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 chargement ou du téléchargement. Utilisez PFGameSaveFilesUiProgressGetProgress dans le rappel pour récupérer 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 ne nécessite pas 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 sans risque dans le dossier de sauvegarde ?
`NotStarted`	L’opération n’a pas commencé	Oui
`PreparingForDownload`	Préparation du téléchargement depuis le cloud	Oui
`Downloading`	Téléchargement depuis le cloud	Non
`PreparingForUpload`	Lecture et compression des fichiers locaux	Non
`Uploading`	Chargement vers le cloud 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 d’informations 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 incluent les noms des appareils, les horodatages et la taille des sauvegardes, que vous pouvez afficher pour aider l’utilisateur à décider. 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, ce qui est 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`	Rend l’appareil local actif et effectue la synchronisation. L’appareil distant ne peut plus effectuer de chargement et reçoit une notification de changement d’appareil actif.

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

Conflit

Se déclenche pendant PFGameSaveFilesAddUserWithUiAsync lorsque les données de sauvegarde locales et cloud 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 charge vers le cloud.
`TakeRemote`	Ignore les modifications locales et télécharge les données de sauvegarde cloud.

La résolution des conflits s’applique à l’intégralité de la sauvegarde, et non à des fichiers ou dossiers individuels. Pour savoir comment 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 depuis le cloud. Le rappel reçoit requiredBytes, qui indique la quantité d’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 une fois 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.

In-process ou hors processus (interface utilisateur système)

L’endroit où s’exécute Game Saves 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 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 d’achèvement asynchrone identiques à ceux que votre jeu reçoit en mode in-process. Vous pouvez tout de même inscrire des rappels pour remplacer l’interface utilisateur intégrée.
In-process (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 mode, 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	Achèvement 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`)	n/a	Non
Annuler (le jeu a appelé `XAsyncCancel`)	`E_ABORT` (`0x80004004`)	n/a	Non

La seule action d’abandon qui permet encore au joueur de continuer est Use Offline dans l’invite d’échec de synchronisation (un résultat de réussite). Toute autre annulation est finale et ne laisse aucun dossier de sauvegarde : traitez-la comme ne pas autoriser le jeu. Consultez Mode hors connexion de Game Saves. Dans l’interface utilisateur système intégrée (hors processus), ces choix apparaissent avec la formulation 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 dans les deux modes : 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, identique à votre implémentation Steam Deck), inscrivez des rappels partout et validez les flux hors processus sur votre matériel cible. Quel que soit le mode, conditionnez l’accès au jeu au résultat d’achèvement : S_OK + connecté → jeu en ligne ; S_OK + non connecté → jeu hors connexion (avertissez le joueur) ; annulation/échec sans dossier → bloquez l’accès au jeu.

Configuration requise 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 plus d’informations sur l’implémentation sur Steam Deck, consultez le Guide d’implémentation pour Steam Deck.

XBOX Services

PlayFab

Fonctionnement de la machine à états

Quand les rappels se déclenchent

Inscription des rappels

Référence des rappels

Progression

États de synchronisation

Échec de synchronisation

Conflit d’appareil actif

Conflit

Stockage insuffisant

In-process ou hors processus (interface utilisateur système)

L’annulation est toujours un résultat possible

Configuration requise des plateformes

Contenu associé

​Fonctionnement de la machine à états

​Quand les rappels se déclenchent

​Inscription des rappels

​Référence des rappels

​Progression

​États de synchronisation

​Échec de synchronisation

​Conflit d’appareil actif

​Conflit

​Stockage insuffisant

​In-process ou hors processus (interface utilisateur système)

​L’annulation est toujours un résultat possible

​Configuration requise des plateformes

​Contenu associé

Fonctionnement de la machine à états

Quand les rappels se déclenchent

Inscription des rappels

Référence des rappels

Progression

États de synchronisation

Échec de synchronisation

Conflit d’appareil actif

Conflit

Stockage insuffisant

In-process ou hors processus (interface utilisateur système)

L’annulation est toujours un résultat possible

Configuration requise des plateformes

Contenu associé