FAQ sur la gestion des erreurs de Game Saves
Cet article répond aux questions courantes sur la façon dont Game Saves signale les défaillances : quelles erreurs sont temporaires (elles valent la peine d’être retentées), lesquelles signifient que vous avez transmis une valeur incorrecte (corrigez l’appel), et quand le système passe en mode hors connexion au lieu de renvoyer une erreur. Game Saves fonctionne de l’une des deux manières suivantes selon la plateforme, et la gestion des erreurs diffère légèrement entre les deux :- Hors processus : le service intégré de la plateforme effectue la synchronisation et affiche sa propre interface utilisateur système. Game Saves fonctionne toujours de cette manière sur XBOX et Windows.
- In-process : le SDK effectue lui-même la synchronisation cloud, sur les plateformes où le service de la plateforme n’est pas disponible (par exemple Steam Deck). Votre jeu pilote l’interface utilisateur au moyen de rappels.
Quand Game Saves passe-t-il hors connexion au lieu de renvoyer une erreur ?
Le mode hors connexion est un résultat de réussite, et non une erreur. La synchronisation initiale (PFGameSaveFilesAddUserWithUiAsync) ne passe en mode hors connexion que lorsque le joueur choisit explicitement Use Offline / Play offline dans une invite d’échec de synchronisation (ou lorsqu’un autre appareil devient l’appareil actif). Dans ce cas, l’opération asynchrone se termine avec S_OK et PFGameSaveFilesIsConnectedToCloud() renvoie false. Vous obtenez tout de même un dossier de sauvegarde local utilisable.
Une annulation (Cancel) délibérée par le joueur se termine en revanche avec E_PF_GAMESAVE_USER_CANCELLED et ne fournit aucun dossier de sauvegarde : traitez ce cas comme « ne pas autoriser le jeu ». Si votre jeu annule lui-même l’opération asynchrone avec XAsyncCancel, elle se termine plutôt avec E_ABORT, également sans dossier de sauvegarde ; traitez E_ABORT comme votre propre annulation.
Pour consulter la table de décision complète et la référence des codes d’erreur, consultez Mode hors connexion de Game Saves.
PFGameSaveFilesInitialize peut-elle échouer de manière temporaire ?
Non. PFGameSaveFilesInitialize se contente de valider ses arguments et d’initialiser l’état ; elle n’accède pas au réseau. Toutes les défaillances qu’elle renvoie sont déterministes :
E_INVALIDARG: un argument requis est manquant ou non valide. En mode in-process, cela inclut unsaveFoldermanquant ou non valide (un dossier valide est requis sur ces plateformes ; sur XBOX/GDK, l’emplacement est fixe et l’argument est ignoré).E_PF_GAMESAVE_ALREADY_INITIALIZED: vous l’avez appelée deux fois sans appel intermédiaire àPFGameSaveFilesUninitializeAsync.
Initialize échoue, réessayer n’y changera rien : corrigez l’entrée. Si elle réussit une fois pour une configuration donnée, elle ne commencera pas à échouer d’elle-même par la suite.
PFGameSaveFilesAddUserWithUiAsync peut-elle échouer de manière temporaire ?
Oui : c’est l’appel qui effectue la synchronisation réseau ; il peut donc rencontrer des défaillances temporaires (réseau indisponible, erreurs de service, actualisation de jeton, espace disque insuffisant). Les appels HTTP sont retentés selon les paramètres de nouvelle tentative HTTP du titre (PFHttpRetrySettings), mais rien ne garantit qu’une défaillance temporaire soit résolue avant que votre jeu ne la voie.
Lorsqu’une défaillance temporaire n’est pas résolue par ces nouvelles tentatives, elle est signalée via l’interface utilisateur d’échec de synchronisation, où le joueur choisit Retry, Use Offline ou Cancel. En mode in-process sans rappel d’échec de synchronisation inscrit, elle est renvoyée sous forme de HRESULT brut. Une défaillance temporaire aboutit donc normalement à un mode en ligne, à un mode hors connexion ou à une annulation plutôt qu’à une erreur brute, avec une différence importante entre les deux modes (voir la question suivante).
PFGameSaveFilesAddUserWithUiAsync peut également renvoyer des erreurs déterministes qui ne sont ni temporaires ni susceptibles d’être retentées :
E_INVALIDARG: handle ou async null, ou options contradictoires.E_PF_GAMESAVE_NOT_INITIALIZED: appelée avantInitialize.E_PF_GAMESAVE_USER_ALREADY_ADDED: l’utilisateur est déjà ajouté (et toujours connecté).
Dois-je inscrire des rappels d’interface utilisateur pour obtenir l’option hors connexion ?
C’est la principale différence entre les deux modes :- In-process : oui. Le repli hors connexion en cas d’échec temporaire de synchronisation ne se produit que si vous avez inscrit un rappel d’échec de synchronisation (via
PFGameSaveFilesSetUiCallbacks) avant d’appelerPFGameSaveFilesAddUserWithUiAsync. Si aucun rappel n’est inscrit, une défaillance temporaire termine l’opération avec le HRESULT d’erreur brut : il n’y a ni Retry ni Use Offline. Sur les plateformes sans interface utilisateur Game Saves intégrée, l’inscription des rappels est obligatoire. - Hors processus : pas pour les échecs de synchronisation ordinaires. L’interface utilisateur système intégrée de la plateforme propose automatiquement les choix Try again / Play offline ; les défaillances réseau ordinaires pendant la synchronisation offrent donc au joueur une option hors connexion sans aucun rappel du jeu. Vous pouvez tout de même inscrire des rappels pour fournir votre propre interface utilisateur.
Existe-t-il des défaillances qui se produisent avant l’affichage de toute interface utilisateur ?
Hors processus uniquement. Avant que l’interface utilisateur de synchronisation puisse s’afficher,PFGameSaveFilesAddUserWithUiAsync récupère la configuration du service et (éventuellement) connecte l’utilisateur. Des défaillances précoces lors de la configuration (par exemple, le service de la plateforme momentanément indisponible ou le titre non configuré pour Game Saves) peuvent terminer l’appel avec un HRESULT brut avant l’affichage de toute boîte de dialogue. Certaines sont temporaires (réessayez l’intégralité de PFGameSaveFilesAddUserWithUiAsync un peu plus tard) ; d’autres indiquent des problèmes de configuration (déterministes). Les défaillances de connexion ou de jeton sont gérées correctement et ne font pas échouer l’appel à elles seules.
En mode in-process, AddUserWithUiAsync ne présente pas cette catégorie de défaillances précoces : les défaillances se produisent pendant la synchronisation et passent par l’interface utilisateur d’échec de synchronisation (sous réserve de l’exigence de rappel mentionnée ci-dessus).
Un chargement peut-il être annulé ?
Oui.PFGameSaveFilesUploadWithUiAsync affiche une interface utilisateur (un indicateur de progression, et une invite d’échec de synchronisation en cas d’erreur), et le joueur peut quitter l’une ou l’autre. Dans ce cas, l’opération se termine avec E_PF_GAMESAVE_USER_CANCELLED (0x800704C7) et la sauvegarde n’est pas chargée.
Contrairement à la synchronisation initiale, un chargement n’a pas de résultat de réussite Use Offline. Ses résultats finaux sont les suivants :
- Réussite (
S_OK) : enregistré dans le cloud. - Annulé (
E_PF_GAMESAVE_USER_CANCELLED) : le joueur a annulé. - Annulé par votre jeu (
E_ABORT) : votre jeu a appeléXAsyncCancelsur le chargement. - Échec : tous les autres cas (par exemple
E_PF_GAMESAVE_NETWORK_FAILUREouE_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE).
E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD, et PFGameSaveFilesIsConnectedToCloud() renvoie ensuite false, lorsque la session était déjà hors connexion, lorsque le cloud contient une sauvegarde plus récente provenant d’un autre appareil, ou lorsque le joueur choisit Use Offline dans l’invite de reverrouillage qui suit un chargement précédent partiellement échoué. Consultez Quand un chargement met la session hors connexion.
Traitez E_PF_GAMESAVE_USER_CANCELLED séparément des autres défaillances afin de distinguer « le joueur a annulé » de « le chargement a échoué ». Il s’agit du même code d’annulation que celui utilisé par la synchronisation initiale : une seule vérification couvre donc les deux opérations.
Quelles erreurs indiquent « vous avez transmis une valeur incorrecte » plutôt qu’un problème temporaire ?
Consultez la référence complète des HRESULT dans Mode hors connexion de Game Saves.
Recommandations
- Traitez les défaillances de
PFGameSaveFilesInitializecomme des bogues à corriger (arguments ou configuration incorrects), et non comme des conditions d’exécution à retenter. - In-process : inscrivez toujours vos rappels d’interface utilisateur (au minimum le rappel d’échec de synchronisation) avant
PFGameSaveFilesAddUserWithUiAsync, afin que les défaillances temporaires proposent au joueur Retry/Use Offline plutôt qu’une erreur bloquante. - Hors processus : préparez-vous à une défaillance brute de
PFGameSaveFilesAddUserWithUiAsyncavant toute interface utilisateur (service/configuration). Réessayez en cas de défaillance temporaire ; signalez les problèmes de configuration comme des erreurs. - Conditionnez l’accès au jeu au résultat final :
S_OK+ connecté → jeu en ligne ;S_OK+ non connecté → jeu hors connexion (avertissez le joueur que les sauvegardes ne seront pas synchronisées) ; annulation/échec sans dossier → bloquez l’accès au jeu.