​

Démarrage rapide de Game Saves

​

Prérequis

• 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 chargement mentionnés dans ce démarrage rapide.

​

Ce que vous allez apprendre

• Initialiser le système Game Saves
• Télécharger les données de sauvegarde existantes depuis le cloud
• Charger les données de sauvegarde locales dans le cloud
• 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

​

Configuration initiale (une fois par session de jeu)

1. Initialiser les services : configurez les modules PlayFab Core et Game Saves
2. Authentifier l’utilisateur : connectez le joueur à l’aide de l’authentification XBOX
3. Télécharger les sauvegardes existantes : synchronisez sur l’appareil local les données de sauvegarde provenant d’autres appareils
4. 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

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

​

Fin de session

8. Chargement final : chargez les dernières modifications avant que le joueur quitte le jeu
9. Synchronisation en arrière-plan : sur XBOX/Windows, le système gère automatiquement les derniers chargements à 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
• Chargements incrémentiels : seuls les fichiers modifiés sont chargé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

​

Étape 1 : initialiser Game Saves

​

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

• 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

​

Autres plateformes

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 cloud

​

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

1. Télécharge les sauvegardes existantes provenant d’autres appareils (uniquement les fichiers nouveaux ou modifiés)
2. Conserve les horodatages des fichiers lorsque c’est possible, pour un contrôle de version correct
3. Gère les conflits automatiquement grâce à l’interface utilisateur intégrée
4. Définit l’appareil comme actif pour cet utilisateur
5. 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

• 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 : charger les données de sauvegarde dans le cloud

​

Moments suggérés pour le chargement

• 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 chargement

• KeepDeviceActive : l’appareil reste actif, ce qui permet d’autres chargements 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 chargement se poursuit en arrière-plan après la fermeture du jeu
• Autres plateformes (Steam Deck, etc.) : le chargement doit se terminer avant la sortie du jeu, faute de quoi les données de sauvegarde n’atteindront pas le cloud

​

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 ?

​

Bonnes pratiques

1. Gérez les échecs de manière appropriée : les problèmes réseau ne doivent pas faire planter votre jeu
2. Utilisez les options appropriées :
   • Utilisez KeepDeviceActive pendant le jeu pour permettre d’autres chargements
   • Utilisez ReleaseDeviceAsActive lorsque le joueur quitte le jeu ou revient au menu
3. Avertissez les utilisateurs sur les plateformes autres que XBOX : indiquez aux joueurs de ne pas quitter pendant le chargement

​

Considérations relatives à la fréquence

• Plusieurs chargements par session sont pris en charge et efficaces
• Seuls les fichiers modifiés sont chargé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)

// 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);

​

Comprendre les conflits de sauvegarde

​

Comprendre le mode hors connexion de Game Saves

​

Comprendre les changements d’appareil actif dans Game Saves

​

Débogage