Restauration de Game Saves

La restauration vous permet de rétablir la sauvegarde de jeu d’un joueur à un état antérieur. Utilisez-la lorsque la sauvegarde d’un joueur est corrompue, lorsqu’une mise à jour du titre introduit un bogue qui endommage les données de sauvegarde, ou lorsqu’un joueur souhaite annuler une décision de résolution de conflit.

Fonctionnement de la restauration

Game Saves suit les versions finalisées des données de sauvegarde d’un joueur. Lorsque vous déclenchez une restauration, le service crée une nouvelle version dont le contenu est identique à l’état antérieur que vous restaurez. La restauration préserve l’historique des versions d’origine : elle ne supprime ni n’écrase les versions précédentes. Les autres appareils qui se synchronisent après la restauration la voient comme une mise à jour normale. Il existe deux types de restauration. Vous déclenchez chacun d’eux en transmettant un indicateur d’option à PFGameSaveFilesAddUserWithUiAsync :

Option	Description
`PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood`	Restaure la sauvegarde cloud précédente la plus récente ayant été vérifiée. Cette sauvegarde a été chargée auparavant, puis remplacée par un chargement plus récent.
`PFGameSaveFilesAddUserOptions::RollbackToLastConflict`	Restaure l’état de sauvegarde qui a perdu lors de la résolution de conflit la plus récente.

Les deux options reviennent au comportement par défaut (synchronisation de la dernière version actuelle) s’il n’existe aucun point de restauration admissible.

Quand utiliser chaque type de restauration

Restauration vers la dernière version fiable

Utilisez RollbackToLastKnownGood lorsque vous soupçonnez que le dernier chargement est défectueux. Voici des déclencheurs courants :

Échec du chargement ou échec d’un contrôle d’intégrité après le téléchargement d’une sauvegarde.
Un plantage pendant ou immédiatement après une opération de sauvegarde.
Un joueur signale un état corrompu ou une régression.

Le service suit automatiquement les versions « fiables ». Vous n’avez pas besoin de les marquer explicitement. Une version devient fiable lorsque vous la chargez avec succès et qu’un chargement plus récent la remplace ensuite.

Restauration vers le dernier conflit

Utilisez RollbackToLastConflict lorsqu’un joueur a choisi le mauvais côté lors de la résolution d’un conflit. Comme décrit dans Conflits de Game Saves, les deux choix de résolution conservent la branche écartée. Cette option de restauration rétablit cette branche conservée.

Appel de l’API

Déclenchez la restauration en transmettant l’option appropriée à PFGameSaveFilesAddUserWithUiAsync. Vous ne pouvez appeler cette fonction qu’une seule fois par utilisateur ; pour effectuer une restauration pour un utilisateur déjà ajouté, appelez d’abord PFGameSaveFilesUninitializeAsync et attendez la fin de l’opération.

// Rollback to last known good version
XAsyncBlock async{};
async.queue = queue;
async.callback = [](XAsyncBlock* async)
{
    HRESULT hr = PFGameSaveFilesAddUserWithUiResult(async);
    if (SUCCEEDED(hr))
    {
        // Save data is now restored to the last known good version.
        // Read files from the game save folder as usual.
    }
};

HRESULT hr = PFGameSaveFilesAddUserWithUiAsync(
    localUserHandle,
    PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood,
    &async
);

Pour effectuer plutôt une restauration vers la version perdante du dernier conflit, remplacez l’indicateur d’option :

HRESULT hr = PFGameSaveFilesAddUserWithUiAsync(
    localUserHandle,
    PFGameSaveFilesAddUserOptions::RollbackToLastConflict,
    &async
);

Comportement de repli

S’il n’existe aucun point de restauration admissible pour le type de restauration demandé, l’appel se comporte comme si vous aviez transmis PFGameSaveFilesAddUserOptions::None. La dernière version actuelle est synchronisée normalement. Vérifiez les fichiers synchronisés une fois l’appel terminé pour confirmer si une restauration a eu lieu.

Configuration du titre

Vous pouvez restreindre les restaurations lancées par le client à l’aide de deux indicateurs de configuration. Lorsque vous activez l’un de ces indicateurs, seuls les outils de support et Game Manager peuvent effectuer ce type de restauration.

Indicateur	Effet
`DisableClientRollbackToLastKnownGood`	Empêche les clients de jeu de revenir à la dernière version fiable.
`DisableClientRollbackToLastConflictLoser`	Empêche les clients de jeu d’annuler la décision de résolution de conflit la plus récente.

Définissez ces indicateurs dans Game Manager, sous Progression > Game Saves.

Gestion des erreurs

HRESULT	Signification
`E_PF_GAME_SAVE_MANIFEST_NOT_ELIGIBLE_FOR_ROLLBACK`	Il n’existe aucun point de restauration admissible pour le type de restauration demandé.
`E_PF_GAME_SAVE_NOT_FINALIZED_MANIFEST_NOT_ELIGIBLE_AS_KNOWN_GOOD`	La version cible n’est pas admissible comme point de restauration fiable.
`E_PF_GAME_SAVE_SERVICE_NOT_ENABLED_FOR_TITLE`	Game Saves n’est pas activé pour ce titre. Terminez d’abord l’intégration.
`E_PF_GAME_SAVE_SERVICE_ONBOARDING_PENDING`	L’intégration du titre est toujours en cours.

Points à prendre en compte

La restauration crée une nouvelle version. Elle n’efface pas l’historique. La séquence de versions du joueur continue d’avancer.
Le service suit automatiquement les versions fiables. Il détermine les versions admissibles en fonction des cycles réussis de chargement puis de remplacement. Votre jeu n’a pas besoin de marquer explicitement les versions.
Une restauration par appel d’ajout d’utilisateur. Comme vous ne pouvez appeler PFGameSaveFilesAddUserWithUiAsync qu’une seule fois par utilisateur, le déclenchement d’une deuxième restauration nécessite d’appeler d’abord PFGameSaveFilesUninitializeAsync.
Les rappels d’interface utilisateur se déclenchent toujours. La restauration suit le même flux de synchronisation qu’un appel d’ajout d’utilisateur normal. Inscrivez vos rappels d’interface utilisateur avant d’appeler l’API.
Restreignez la restauration si nécessaire. Si votre jeu gère la récupération côté serveur ou via des outils de support, désactivez la restauration côté client à l’aide des indicateurs de configuration du titre afin d’éviter que les joueurs annulent accidentellement leur progression.
La restauration fonctionne sur toutes les plateformes. Cette API ne comporte aucune restriction propre à une plateforme.

XBOX Services

PlayFab

Fonctionnement de la restauration

Quand utiliser chaque type de restauration

Restauration vers la dernière version fiable

Restauration vers le dernier conflit

Appel de l’API

Comportement de repli

Configuration du titre

Gestion des erreurs

Points à prendre en compte

​Fonctionnement de la restauration

​Quand utiliser chaque type de restauration

​Restauration vers la dernière version fiable

​Restauration vers le dernier conflit

​Appel de l’API

​Comportement de repli

​Configuration du titre

​Gestion des erreurs

​Points à prendre en compte

Fonctionnement de la restauration

Quand utiliser chaque type de restauration

Restauration vers la dernière version fiable

Restauration vers le dernier conflit

Appel de l’API

Comportement de repli

Configuration du titre

Gestion des erreurs

Points à prendre en compte