Démarrage rapide de Game Saves

PlayFab Game Saves permet aux joueurs de poursuivre leur progression de façon transparente d’un appareil à l’autre en synchronisant les données de sauvegarde dans le nuage. Ce guide de démarrage rapide vous explique comment implémenter une solution complète de sauvegarde de jeu pour les plateformes XBOX et Windows.

Prérequis

Avant de commencer, assurez-vous :

D’avoir effectué l’intégration à Game Saves
D’avoir consulté les exigences d’implémentation dans la section Vue d’ensemble
D’avoir rempli les exigences répertoriées ci-dessous
(Facultatif) D’avoir cloné ou consulté l’exemple Game Saves de bout en bout pour Windows sur GitHub : PlayFabGameSaveSample-Windows. L’exemple illustre les flux d’initialisation, de synchronisation, de gestion des conflits et de téléversement mentionnés dans ce démarrage rapide.

Ce que vous allez apprendre

Dans ce guide, vous allez apprendre à :

Initialiser le système Game Saves
Télécharger les données de sauvegarde existantes depuis le nuage
Téléverser les données de sauvegarde locales dans le nuage
Gérer les conflits et les rappels d’interface utilisateur
Gérer les scénarios d’appareil actif

Exigences de développement

Exigences logicielles

Un compte de développeur PlayFab
Visual Studio 2019 ou Visual Studio 2022 est recommandé pour le développement avec le Gaming Runtime. Pour plus de détails, consultez https://learn.microsoft.com/en-us/gaming/gdk/docs/gdk-dev/get-started/overviews/sdk-and-tools#install-visual-studio.
Un accès à la dernière version du Microsoft Game Development Kit (GDK)

Vue d’ensemble du flux Game Saves

Le système Game Saves suit un modèle simple qui fonctionne de façon transparente d’un appareil à l’autre :

Configuration initiale (une fois par session de jeu)

Initialiser les services : configurez les modules PlayFab Core et Game Saves
Authentifier l’utilisateur : connectez le joueur à l’aide de l’authentification XBOX
Télécharger les sauvegardes existantes : synchronisez sur l’appareil local les données de sauvegarde provenant d’autres appareils
Obtenir l’emplacement de sauvegarde : obtenez le dossier racine de sauvegarde local dans lequel votre jeu doit écrire les fichiers de sauvegarde

Pendant le jeu

Écrire les fichiers de sauvegarde : votre jeu écrit les données de sauvegarde dans le dossier racine de sauvegarde local, comme d’habitude
Téléverser les modifications : téléversez régulièrement dans le nuage les fichiers de sauvegarde modifiés
Continuer à jouer : répétez les étapes 5 et 6 si nécessaire pendant la session de jeu

Fin de session

Téléversement final : téléversez les dernières modifications avant que le joueur quitte le jeu
Synchronisation en arrière-plan : sur XBOX/Windows, le système gère automatiquement les derniers téléversements à la fermeture du jeu

Principaux avantages

Prise en charge hors connexion : les joueurs peuvent commencer à jouer même sans connexion Internet
Résolution automatique des conflits : une interface utilisateur intégrée gère les conflits de sauvegarde entre appareils
Téléversements incrémentiels : seuls les fichiers modifiés sont téléversés, ce qui améliore les performances
Continuité entre appareils : expérience transparente lors du passage d’un appareil à l’autre

Détails d’implémentation

Les sections suivantes fournissent des exemples de code détaillés pour chaque étape :

Étape 1 : initialiser Game Saves

Game Saves est conçu pour fonctionner aussi bien en ligne qu’hors connexion, ce qui le distingue des autres API PlayFab. Il conserve une identité d’utilisateur local persistante qui fonctionne même lorsque l’appareil démarre hors connexion.

Concepts clés

PFLocalUserHandle : un identificateur d’utilisateur persistant qui fonctionne hors connexion
PFServiceConfigHandle : la configuration de votre titre PlayFab
Conception hors connexion d’abord : le système fonctionne immédiatement, même sans connectivité Internet

Prérequis

Avant d’initialiser Game Saves, assurez-vous :

D’avoir appelé XGameRuntimeInitialize() pour initialiser le runtime XBOX
D’avoir appelé XUserAddAsync() pour connecter un utilisateur et obtenir un XUserHandle
De disposer de votre ID de titre PlayFab issu de Game Manager

Implémentation

// Step 1: Initialize PlayFab Core
HRESULT hr = PFInitialize(nullptr);
if (FAILED(hr))
{
    // Handle initialization failure - log error and exit gracefully
    return hr;
}

// Step 2: Create service config handle with your title information
PFServiceConfigHandle serviceConfigHandle{ nullptr };
hr = PFServiceConfigCreateHandle(
    "https://<titleId>.playfabapi.com",    // Replace <titleId> with your actual PlayFab Title ID
    "<titleId>",                           // Replace <titleId> with your actual PlayFab Title ID
    &serviceConfigHandle);
if (FAILED(hr))
{
    // Handle service config creation failure
    return hr;
}

// Step 3: Initialize the Game Saves module
PFGameSaveInitArgs args = {};
// Set args.saveFolder here if you are targetting platforms such as Steam
// where you need to provide root of where the game saves are
hr = PFGameSaveFilesInitialize(&args);
if (FAILED(hr))
{
    // Handle Game Saves initialization failure
    return hr;
}

// Step 4: Create a local user handle
// NOTE: Assumes you have already obtained 'xuserHandle' from XUserAddAsync
PFLocalUserHandle localUserHandle;
hr = PFLocalUserCreateHandleWithXboxUser(serviceConfigHandle, xuserHandle, nullptr, &localUserHandle);
if (FAILED(hr))
{
    // Handle local user creation failure
    return hr;
}

// Success! The Game Saves system is now initialized and ready to use

Remplacez <titleId> par votre ID de titre PlayFab réel, issu de Game Manager. Le xuserHandle doit être obtenu à partir d’un appel réussi à XUserAddAsync.

Autres plateformes

Pour les plateformes sans authentification XBOX et sans prise en charge hors connexion, utilisez plutôt d’autres versions de PFLocalUserCreateHandle ou PFLocalUserCreateHandleWithPersistedLocalId. Consultez la documentation propre à chaque plateforme pour les détails d’implémentation. Par exemple :

PFLocalUserHandle localUserHandle;
hr = PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, nullptr, &localUserHandle);
if (FAILED(hr))
{
    // Handle local user creation failure
    return hr;
}

Étape 2 : synchroniser les données de sauvegarde depuis le nuage

Après l’initialisation, ajoutez l’utilisateur au système Game Saves pour synchroniser les données de sauvegarde existantes provenant d’autres appareils. Cette étape configure également le dossier racine de sauvegarde local dans lequel votre jeu lira et écrira les fichiers de sauvegarde.

Quand effectuer cet appel

Une fois par session de jeu, après l’authentification de l’utilisateur
Lorsque l’utilisateur revient au menu principal du jeu
Après une reprise depuis l’état suspendu/l’arrière-plan

Ce que fait cette étape

Télécharge les sauvegardes existantes provenant d’autres appareils (uniquement les fichiers nouveaux ou modifiés)
Conserve les horodatages des fichiers lorsque c’est possible, pour un contrôle de version correct
Gère les conflits automatiquement grâce à l’interface utilisateur intégrée
Définit l’appareil comme actif pour cet utilisateur
Fournit le chemin du dossier de sauvegarde dans lequel votre jeu doit écrire les fichiers

Limitations importantes

Ne peut être appelée avec succès qu’une seule fois par session Game Saves
Nécessite la réinitialisation du système Game Saves pour être appelée de nouveau
Déclenche des invites d’interface utilisateur en cas de conflits, de problèmes de stockage et de contention entre appareils

Implémentation

// Add user to Game Saves system and sync from cloud
HRESULT hr;
XAsyncBlock async{};
hr = PFGameSaveFilesAddUserWithUiAsync(localUserHandle, PFGameSaveFilesAddUserOptions::None, &async);
if (FAILED(hr))
{
    // Handle API call failure
    return hr;
}

// Wait for the operation to complete
// For production code, consider using a callback instead of blocking
hr = XAsyncGetStatus(&async, true); 
if (FAILED(hr))
{
    // Handle async operation failure (network issues, user cancellation, etc.)
    return hr;
}

hr = PFGameSaveFilesAddUserWithUiResult(&async);
if (FAILED(hr))
{
    // Handle specific operation failures (conflicts, storage issues, etc.)
    return hr;
}

// Get the local save root folder path for your game
char saveFolder[1024] = { 0 };
hr = PFGameSaveFilesGetFolder(localUserHandle, 1024, saveFolder, nullptr);
if (FAILED(hr))
{
    // Handle folder retrieval failure
    return hr;
}

// Check remaining cloud storage quota
int64_t remainingQuota{ 0 };
hr = PFGameSaveFilesGetRemainingQuota(localUserHandle, &remainingQuota);
if (FAILED(hr))
{
    // Handle quota retrieval failure
    return hr;
}

// Success! You can now read/write save files in the saveFolder directory
printf("Save folder: %s\n", saveFolder);
printf("Remaining quota: %lld bytes\n", remainingQuota);

Étapes suivantes

Une fois cet appel terminé avec succès :

Votre jeu peut lire les fichiers de sauvegarde existants dans le répertoire saveFolder
Écrire de nouveaux fichiers de sauvegarde et créer des sous-répertoires si nécessaire
L’appareil est désormais considéré comme « actif » pour cet utilisateur
Les autres appareils afficheront un avertissement si l’utilisateur tente d’y effectuer une synchronisation

Étape 3 : téléverser les données de sauvegarde dans le nuage

Une fois que votre jeu a écrit des fichiers et des sous-dossiers de sauvegarde dans le dossier racine de sauvegarde local, utilisez cette étape pour téléverser les modifications dans le nuage. Le système détecte automatiquement et charge uniquement les fichiers et sous-dossiers modifiés depuis le dernier téléversement. Les suppressions de fichiers et de dossiers sont également synchronisées automatiquement dans le nuage.

Moments suggérés pour le téléversement

Après une progression importante : lorsque le joueur atteint un point de contrôle ou termine un niveau
Avant les transitions de menu : lors du retour au menu principal ou du changement de mode de jeu
À la sortie du jeu : avant que le joueur quitte le jeu
Sauvegardes périodiques : toutes les quelques minutes pendant les longues sessions de jeu

Options de téléversement

KeepDeviceActive : l’appareil reste actif, ce qui permet d’autres téléversements ultérieurs
ReleaseDeviceAsActive : libère l’appareil de son statut actif, ce qui permet une synchronisation transparente sur d’autres appareils

Comportement selon la plateforme

XBOX/Windows : le téléversement se poursuit en arrière-plan après la fermeture du jeu
Autres plateformes (Steam Deck, etc.) : le téléversement doit se terminer avant la sortie du jeu, faute de quoi les données de sauvegarde n’atteindront pas le nuage

Implémentation

// Upload save files to cloud
XAsyncBlock async{};
HRESULT hr = PFGameSaveFilesUploadWithUiAsync(
    localUserHandle, 
    PFGameSaveFilesUploadOption::KeepDeviceActive,  // Use ReleaseDeviceAsActive when quitting
    &async);
if (FAILED(hr))
{
    // Handle API call failure
    return hr;
}

// Wait for upload to complete
// Consider using callbacks for better user experience
hr = XAsyncGetStatus(&async, true); 
if (FAILED(hr))
{
    // Handle async operation failure (network issues, storage full, etc.)
    return hr;
}

hr = PFGameSaveFilesUploadWithUiResult(&async);
if (FAILED(hr))
{
    // Handle upload failure
    return hr;
}

// Success! Save data is now safely stored in the cloud

Quand puis-je écrire de nouveau dans le dossier de sauvegarde?

Pendant le téléversement, le système lit et compresse vos fichiers de sauvegarde locaux avant de les téléverser. Dès que l’état de synchronisation passe à Uploading (signalé au moyen de PFGameSaveFilesUiProgressCallback), le système a fini de lire vos fichiers et vous pouvez de nouveau écrire dans le dossier de sauvegarde en toute sécurité. Vous n’avez pas besoin d’attendre la fin complète du téléversement pour reprendre les sauvegardes. Si vous n’utilisez pas le rappel de progression, attendez que le XAsyncBlock se termine avant d’écrire de nouvelles données de sauvegarde.

Pratiques exemplaires

Gérez les échecs de façon appropriée : les problèmes réseau ne doivent pas faire planter votre jeu
Utilisez les options appropriées :
- Utilisez KeepDeviceActive pendant le jeu pour permettre d’autres téléversements
- Utilisez ReleaseDeviceAsActive lorsque le joueur quitte le jeu ou revient au menu
Avertissez les utilisateurs sur les plateformes autres que XBOX : indiquez aux joueurs de ne pas quitter pendant le téléversement

Considérations relatives à la fréquence

Plusieurs téléversements par session sont pris en charge et efficaces
Seuls les fichiers modifiés sont téléversés, ce qui limite l’utilisation de la bande passante
Consultez la documentation sur les limites pour connaître les quotas et restrictions spécifiques

Étape 4 : gérer les rappels d’interface utilisateur (facultatif)

Game Saves fournit une interface utilisateur intégrée pour les plateformes XBOX et Windows. Sur les autres plateformes (comme le Steam Deck), votre jeu doit fournir sa propre interface utilisateur en gérant des rappels. Les rappels d’interface utilisateur se déclenchent pendant PFGameSaveFilesAddUserWithUiAsync et PFGameSaveFilesUploadWithUiAsync. Chaque rappel suspend l’opération asynchrone jusqu’à ce que votre jeu réponde : le rappel XAsyncBlock ne se déclenche pas tant que tous les rappels d’interface utilisateur ne sont pas résolus.

// Set up custom UI callbacks (call this before AddUser or Upload operations)
// See sample for detailed examples of these callbacks.
PFGameSaveUICallbacks callbacks{};
callbacks.progressCallback = MyProgressCallback;
callbacks.syncFailedCallback = MySyncFailedCallback;
callbacks.activeDeviceContentionCallback = MyActiveDeviceContentionCallback;
callbacks.conflictCallback = MyConflictCallback;
callbacks.outOfStorageCallback = MyOutOfStorageCallback;

HRESULT hr = PFGameSaveFilesSetUiCallbacks(&callbacks);

Pour la liste complète des types de rappels, des API de réponse, des actions utilisateur et des détails sur le fonctionnement de la machine à états, consultez Rappels d’interface utilisateur de Game Saves.

Comprendre les conflits de sauvegarde

Des conflits de sauvegarde se produisent lorsque les mêmes données de jeu ont été modifiées sur plusieurs appareils. Game Saves traite chaque sous-dossier de premier niveau comme une unité atomique pour la résolution des conflits, et les joueurs peuvent choisir de conserver soit les données locales, soit les données infonuagiques en cas de conflit. Pour des scénarios détaillés de gestion des conflits et des pratiques exemplaires, consultez Conflits de Game Saves.

Comprendre le mode hors connexion de Game Saves

Game Saves fonctionne aussi bien en ligne qu’hors connexion. Lorsqu’il est connecté au nuage, toutes les API fonctionnent normalement. Hors connexion ou en cas de déconnexion, les sauvegardes locales continuent de fonctionner, mais les opérations infonuagiques retournent E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD. Utilisez PFGameSaveFilesIsConnectedToCloud() pour vérifier l’état de la connexion et implémentez des rappels d’échec de synchronisation pour gérer correctement les problèmes réseau. Pour des détails sur le comportement hors connexion et des pratiques exemplaires, consultez Mode hors connexion de Game Saves.

Comprendre les changements d’appareil actif dans Game Saves

Lorsqu’un joueur change d’appareil en cours de session, il est important d’éviter qu’il perde accidentellement sa progression en jouant simultanément sur plusieurs appareils. Si votre jeu se connecte uniquement à l’aide de la fonctionnalité Single Point of Presence (SPOP) de XBOX, ce scénario est automatiquement évité. SPOP garantit qu’un utilisateur ne peut être connecté que sur un seul appareil XBOX à la fois. Sinon, vous devez également implémenter le rappel de changement d’appareil actif pour gérer les scénarios dans lesquels un joueur change d’appareil en cours de session Pour des détails sur le comportement et des pratiques exemplaires, consultez Changements d’appareil actif dans Game Saves.

Débogage

Le moyen le plus simple de consulter les résultats et de déboguer les appels du SDK consiste à activer le traçage de débogage. L’activation du traçage de débogage vous permet à la fois de consulter les résultats dans la fenêtre de sortie du débogueur et d’intégrer ces résultats aux journaux de votre jeu.

​Démarrage rapide de Game Saves

​Prérequis

​Ce que vous allez apprendre

​Exigences de développement

​Exigences logicielles

​Vue d’ensemble du flux Game Saves

​Configuration initiale (une fois par session de jeu)

​Pendant le jeu

​Fin de session

​Principaux avantages

​Détails d’implémentation

​Étape 1 : initialiser Game Saves

​Concepts clés

​Prérequis

​Implémentation

​Autres plateformes

​Étape 2 : synchroniser les données de sauvegarde depuis le nuage

​Quand effectuer cet appel

​Ce que fait cette étape

​Limitations importantes

​Implémentation

​Étapes suivantes

​Étape 3 : téléverser les données de sauvegarde dans le nuage

​Moments suggérés pour le téléversement

​Options de téléversement

​Comportement selon la plateforme

​Implémentation

​Quand puis-je écrire de nouveau dans le dossier de sauvegarde?

​Pratiques exemplaires

​Considérations relatives à la fréquence

​Étape 4 : gérer les rappels d’interface utilisateur (facultatif)

​Comprendre les conflits de sauvegarde

​Comprendre le mode hors connexion de Game Saves

​Comprendre les changements d’appareil actif dans Game Saves

​Débogage

Démarrage rapide de Game Saves

Prérequis

Ce que vous allez apprendre

Exigences de développement

Exigences logicielles

Vue d’ensemble du flux Game Saves

Configuration initiale (une fois par session de jeu)

Pendant le jeu

Fin de session

Principaux avantages

Détails d’implémentation

Étape 1 : initialiser Game Saves

Concepts clés

Prérequis

Implémentation

Autres plateformes

Étape 2 : synchroniser les données de sauvegarde depuis le nuage

Quand effectuer cet appel

Ce que fait cette étape

Limitations importantes

Implémentation

Étapes suivantes

Étape 3 : téléverser les données de sauvegarde dans le nuage

Moments suggérés pour le téléversement

Options de téléversement

Comportement selon la plateforme

Implémentation

Quand puis-je écrire de nouveau dans le dossier de sauvegarde?

Pratiques exemplaires

Considérations relatives à la fréquence

Étape 4 : gérer les rappels d’interface utilisateur (facultatif)

Comprendre les conflits de sauvegarde

Comprendre le mode hors connexion de Game Saves

Comprendre les changements d’appareil actif dans Game Saves

Débogage