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 retourner une erreur. Game Saves fonctionne de l’une de deux façons 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 façon sur XBOX et Windows.
- En processus : le SDK effectue lui-même la synchronisation infonuagique, 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 en mode hors connexion au lieu de retourner une erreur?
Le mode hors connexion est un résultat réussi, 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() retourne false. Vous obtenez tout de même un dossier de sauvegarde local utilisable.
Une annulation délibérée (Cancel) par le joueur se termine plutôt avec E_PF_GAMESAVE_USER_CANCELLED et ne fournit aucun dossier de sauvegarde. Traitez ce cas comme « ne pas permettre de jouer ». Si votre jeu annule lui-même l’opération asynchrone avec XAsyncCancel, celle-ci 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 façon temporaire?
Non. PFGameSaveFilesInitialize ne fait que valider ses arguments et configurer l’état. Elle n’utilise pas le réseau. Chaque échec qu’elle retourne est déterministe :
E_INVALIDARG: un argument requis est manquant ou non valide. En processus, 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 ne servira à 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 plus tard.
PFGameSaveFilesAddUserWithUiAsync peut-elle échouer de façon 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 constate.
Lorsqu’une défaillance temporaire n’est pas résolue par ces nouvelles tentatives, elle est signalée par l’interface utilisateur d’échec de synchronisation, où le joueur choisit Retry, Use Offline ou Cancel. En processus sans rappel d’échec de synchronisation inscrit, elle est plutôt retournée sous forme de HRESULT brut. Ainsi, une défaillance temporaire aboutit normalement à un résultat en ligne, hors connexion ou annulé plutôt qu’à une erreur brute, avec une différence importante entre les deux chemins (voir la question suivante).
PFGameSaveFilesAddUserWithUiAsync peut également retourner des erreurs déterministes qui ne sont pas temporaires et ne peuvent pas être retentées :
E_INVALIDARG: handle ou objet asynchrone nul, ou options contradictoires.E_PF_GAMESAVE_NOT_INITIALIZED: appelée avantInitialize.E_PF_GAMESAVE_USER_ALREADY_ADDED: l’utilisateur a déjà été ajouté (et est 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 chemins :- En processus : oui. Le basculement hors connexion en cas d’échec temporaire de synchronisation ne se produit que si vous avez inscrit un rappel d’échec de synchronisation (au moyen de
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 offre 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 seulement. Avant que l’interface utilisateur de synchronisation puisse s’afficher,PFGameSaveFilesAddUserWithUiAsync collecte la configuration du service et (facultativement) connecte l’utilisateur. Des défaillances précoces de configuration, par exemple l’indisponibilité momentanée du service de la plateforme ou un 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 (relancez l’ensemble de PFGameSaveFilesAddUserWithUiAsync un peu plus tard); d’autres indiquent des problèmes de configuration (déterministes). Les échecs de connexion ou de jeton sont gérés de façon appropriée et ne font pas échouer l’appel à eux seuls.
En processus, AddUserWithUiAsync ne comporte pas cette catégorie de défaillances précoces. Les défaillances surviennent pendant la synchronisation et passent par l’interface utilisateur d’échec de synchronisation (sous réserve de l’exigence de rappel ci-dessus).
Un téléversement peut-il être annulé?
Oui.PFGameSaveFilesUploadWithUiAsync affiche une interface utilisateur (un indicateur de progression, ainsi qu’une invite d’échec de synchronisation en cas d’erreur), et le joueur peut quitter l’un ou l’autre. Dans ce cas, l’opération se termine avec E_PF_GAMESAVE_USER_CANCELLED (0x800704C7) et la sauvegarde n’est pas téléversée.
Contrairement à la synchronisation initiale, un téléversement n’a pas de résultat réussi Use Offline. Ses résultats finaux sont les suivants :
- Réussite (
S_OK) : sauvegardé dans le nuage. - Annulé (
E_PF_GAMESAVE_USER_CANCELLED) : le joueur a annulé. - Annulé par votre jeu (
E_ABORT) : votre jeu a appeléXAsyncCancelsur le téléversement. - É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() retourne ensuite false, lorsque la session était déjà hors connexion, lorsque le nuage 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 téléversement antérieur partiellement échoué. Consultez Lorsqu’un téléversement met la session hors connexion.
Traitez E_PF_GAMESAVE_USER_CANCELLED séparément des autres échecs afin de pouvoir distinguer « le joueur a annulé » de « le téléversement 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 que « vous avez transmis une valeur incorrecte » plutôt qu’un problème temporaire?
Consultez la référence HRESULT complète dans Mode hors connexion de Game Saves.
Recommandations
- Traitez les échecs de
PFGameSaveFilesInitializecomme des bogues à corriger (arguments ou configuration incorrects), et non comme des conditions d’exécution à retenter. - En processus : inscrivez toujours vos rappels d’interface utilisateur (au minimum le rappel d’échec de synchronisation) avant
PFGameSaveFilesAddUserWithUiAsync, afin que les défaillances temporaires offrent au joueur les options Retry/Use Offline au lieu d’une erreur bloquante. - Hors processus : préparez-vous à un échec brut de
PFGameSaveFilesAddUserWithUiAsyncavant toute interface utilisateur (service ou configuration). Retentez les échecs temporaires; signalez les problèmes de configuration comme des erreurs. - Conditionnez le 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 ou échec sans dossier → bloquez le jeu.