> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Implémentation de Game Saves avec le GDK d'octobre 2025 > Guide essentiel pour implémenter PlayFab Game Saves avec le GDK d'octobre 2025 (2510), comprenant les exigences pour les nouvelles implémentations et des conseils de migration Ce guide explique comment implémenter PlayFab Game Saves avec le GDK d'octobre 2025 (version 2510). Que vous découvriez Game Saves ou que vous migriez depuis une implémentation précédente, ce document présente les exigences essentielles et les instructions de configuration, avec une attention particulière à la prise en charge du Steam Deck. ## Vue d'ensemble des exigences d'implémentation Pour implémenter PlayFab Game Saves avec le GDK d'octobre 2025, vous devez comprendre quatre composants clés : 1. **Nouvelle organisation des dossiers du GDK** : structure de répertoires du SDK centrée sur la plateforme 2. **Intégration de XGameRuntime** : runtime multiplateforme avec des exigences de déploiement spécifiques 3. **SDK unifié PlayFab** : architecture de SDK moderne pour tous les composants PlayFab 4. **Autres composants du SDK unifié** : composants Party et Multiplayer mis à jour (le cas échéant) Les trois premiers composants sont **requis** pour toutes les implémentations de Game Saves avec le GDK d'octobre 2025 et les versions ultérieures, y compris pour la prise en charge du Steam Deck. Le quatrième composant ne s'applique que si votre jeu utilise les fonctionnalités PlayFab Party ou Multiplayer. **Vous découvrez Game Saves?** Commencez par la [vue d'ensemble de Game Saves](/fr-CA/services/playfab/player-progression/game-saves/overview) et le [guide de démarrage rapide](/fr-CA/services/playfab/player-progression/game-saves/quickstart) pour comprendre les notions de base, puis revenez ici pour les détails d'implémentation propres au GDK d'octobre 2025. ## 1. Organisation des dossiers du GDK et configuration des chemins ### Structure actuelle du GDK Le GDK d'octobre 2025 utilise une structure de répertoires plate et centrée sur la plateforme. Il est essentiel de comprendre cette organisation pour configurer correctement votre système de build. **Organisation du GDK d'octobre 2025** : ``` \Microsoft GDK\251000\windows\include \Microsoft GDK\251000\xbox\lib\x64 \Microsoft GDK\251000\xbox\bin\x64 ``` **Vous migrez depuis un GDK antérieur?** L'ancienne structure de dossiers (`$(GDK)\GRDK\ and $(GDK)\GXDK\`) a été remplacée. Mettez à jour vos scripts de build en conséquence. ### Configuration de votre système de build #### Configuration des chemins requise Configurez votre système de build pour qu'il utilise les chemins propres à chaque plateforme : #### Exemple de configuration du système de build **Configuration CMake** : ```cmake theme={null} # Configure GDK paths for your target platform if(CMAKE_SYSTEM_NAME STREQUAL "Windows") set(GDK_INCLUDE_DIR "${GDK_PATH}/windows/include") set(GDK_LIB_DIR "${GDK_PATH}/windows/lib/x64") elseif(XBOX) set(GDK_INCLUDE_DIR "${GDK_PATH}/xbox/include") set(GDK_LIB_DIR "${GDK_PATH}/xbox/lib/x64") endif() ``` **Configuration MSBuild** : ```xml theme={null} $(GDK)\windows\include;$(IncludePath) $(GDK)\windows\lib\x64;$(LibraryPath) ``` #### Détails de la prise en charge des plateformes * **XBOX** : utilise les dossiers `xbox` pour toutes les générations récentes de consoles XBOX * **Windows** : toutes les plateformes Windows (PC, PC Steam, Steam Deck avec Proton) utilisent le dossier `windows` * **Steam Deck** : bien qu'il exécute SteamOS, il utilise le dossier `windows` pour assurer la compatibilité avec l'émulation Proton ### Étapes d'implémentation 1. **Configurer votre système de build** * Configurez les chemins d'inclusion et de bibliothèques à l'aide de la nouvelle structure du GDK * Ajoutez une logique de détection de la plateforme si vous ciblez plusieurs plateformes * Testez la compilation sur toutes les plateformes cibles 2. **Valider l'intégration de Game Saves** * Assurez-vous que toutes les bibliothèques requises sont correctement liées * Testez les fonctionnalités sur vos plateformes cibles * Vérifiez la connectivité au service PlayFab ## 2. Intégration de XGameRuntime ### Comprendre XGameRuntime XGameRuntime fournit la base des services XBOX Live et des fonctionnalités de Game Saves sur toutes les plateformes. Voici ce que vous devez savoir : #### Composants principaux **xgameruntime.lib (bibliothèque d'importation)** * Est liée à votre projet de jeu au moment de la compilation * Localise et charge automatiquement la DLL du runtime * Gère la découverte des services (local ou système) **xgameruntime.dll (bibliothèque du runtime)** * Implémente les fonctionnalités XBOX Live et Game Saves * Emplacement : `{GDK}\windows\bin\xgameruntime.dll` * **Essentielle pour les builds Steam** : doit être déployée avec votre jeu ### Exigences d'implémentation #### 1. Intégration de base Toutes les implémentations de Game Saves nécessitent l'initialisation de XGameRuntime : ```cpp theme={null} // Initialize XGameRuntime - required for all Game Saves implementations HRESULT hr = XGameRuntimeInitialize(); if (FAILED(hr)) { // Handle initialization failure return hr; } ``` #### 2. Exigences de la plateforme Steam **Essentiel pour les builds Steam** : Lorsque vous générez pour Steam, vous **devez** inclure `xgameruntime.dll` dans le répertoire de votre jeu. Sans cette DLL, lors de l'exécution sur Steam Deck : * L'authentification XBOX Live échoue * Les fonctionnalités de Game Saves ne sont pas disponibles **Structure de déploiement** : ``` YourGame/ ├── YourGame.exe ├── xgameruntime.dll // Required for Steam/Steam Deck ├── Steam_api64.dll └── Other game files... ``` Les **builds Microsoft Store** chargent automatiquement XGameRuntime depuis le système et ne nécessitent pas de déploiement de DLL. #### 3. Déploiement automatisé de la DLL **Configuration CMake** : ```cmake theme={null} # Automatically copy XGameRuntime DLL for Steam builds if(STEAM_BUILD) add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different "${GDK_PATH}/windows/bin/xgameruntime.dll" $) endif() ``` **Configuration MSBuild** : ```xml theme={null} ``` ### Comportement du runtime selon la plateforme | Plateforme | Source de la DLL | Mode du runtime | Prise en charge de Game Saves | Comportement de synchronisation | | - | - | - | - | - | | Microsoft Store | DLL système | GRTS | Prise en charge complète | Hors processus, se poursuit après l'arrêt | | PC Steam | DLL système | GRTS | Prise en charge complète | Hors processus, se poursuit après l'arrêt | | Steam Deck | DLL locale | Services locaux | Prise en charge pendant la durée de vie du jeu | **Dans le processus uniquement, s'arrête à l'arrêt** | La prise en charge du Steam Deck nécessite spécifiquement le déploiement de la DLL locale. Le système ne peut pas se rabattre sur les services système comme sur les autres plateformes. En outre, le moteur de synchronisation s'exécute dans le processus, ce qui signifie que les jeux doivent s'assurer que les données de sauvegarde critiques sont synchronisées avant l'arrêt. ## 3. Intégration du SDK unifié PlayFab ### Qu'est-ce que le SDK unifié PlayFab? Le SDK unifié PlayFab est un SDK moderne et cohérent qui réunit tous les composants PlayFab au sein d'une architecture unique. Game Saves fait désormais partie de ce système unifié, qui offre : **Avantages pour le développement de Game Saves** : * Gestion unifiée de la mémoire pour tous les composants PlayFab * Modèles d'opérations asynchrones cohérents * Traçage et diagnostics intégrés * Chargement modulaire des composants (incluez uniquement ce dont vous avez besoin) **Vous découvrez PlayFab?** Le SDK unifié simplifie l'intégration en fournissant un modèle d'API unique et cohérent pour tous les services PlayFab. Si vous implémentez Game Saves ou tout autre service PlayFab pour la première fois, vous voudrez commencer avec cette architecture moderne. ### Composants du SDK requis Les implémentations de Game Saves nécessitent les composants suivants du SDK unifié : **Composants essentiels** : * **libHttpClient** : communication HTTP/WebSocket multiplateforme * **PlayFab Core** : authentification, gestion des entités et configuration * **PlayFab GameSave** : fonctionnalités propres à Game Saves **Composants facultatifs** : * **PlayFab Services** : services partagés pour LiveOps, la gestion des comptes et d'autres systèmes de progression (recommandé si vous utilisez d'autres services PlayFab) ### Exigences relatives aux bibliothèques et aux DLL #### Bibliothèques requises pour l'édition de liens ``` Link these .lib files in your project: - libHttpClient.lib - PlayFabCore.lib - PlayFabServices.lib (optional, but recommended for additional PlayFab features) - PlayFabGameSave.lib - xgameruntime.lib ``` #### DLL requises pour le déploiement ``` Deploy these .dll files with Steam builds: - libHttpClient.dll - PlayFabCore.dll - PlayFabServices.dll (optional, but recommended) - PlayFabGameSave.dll - xgameruntime.dll ``` ### Configuration du système de build #### Configuration MSBuild Configurez votre projet Visual Studio pour qu'il lie le SDK unifié : ```xml theme={null} libHttpClient.lib; PlayFabCore.lib; PlayFabServices.lib; PlayFabGameSave.lib; xgameruntime.lib; %(AdditionalDependencies) ``` **Vous migrez depuis un GDK antérieur?** Remplacez les anciens chemins comme `$(GDK)\GRDK\...\include` par la nouvelle structure présentée ci-dessus. #### Configuration CMake Pour les projets basés sur CMake, configurez les dépendances et le déploiement : ```cmake theme={null} # Link all required Unified SDK libraries target_link_libraries(${PROJECT_NAME} PRIVATE libHttpClient PlayFabCore PlayFabServices PlayFabGameSave xgameruntime ) # Automatically deploy DLLs for Steam builds if(STEAM_BUILD) set(UNIFIED_SDK_DLLS "${GDK_PATH}/windows/bin/libHttpClient.dll" "${GDK_PATH}/windows/bin/PlayFabCore.dll" "${GDK_PATH}/windows/bin/PlayFabServices.dll" "${GDK_PATH}/windows/bin/PlayFabGameSave.dll" "${GDK_PATH}/windows/bin/xgameruntime.dll" ) foreach(DLL ${UNIFIED_SDK_DLLS}) add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different ${DLL} $) endforeach() endif() ``` ### Implémentation du code #### En-têtes requis Incluez les en-têtes nécessaires du SDK unifié dans votre projet : ```cpp theme={null} // Essential headers for Game Saves implementation #include #include #include #include ``` #### Séquence d'initialisation Suivez cet ordre d'initialisation pour configurer correctement Game Saves : ```cpp theme={null} // 1. Initialize XGameRuntime (foundation for Xbox Live services) HRESULT hr = XGameRuntimeInitialize(); if (FAILED(hr)) { // Handle initialization failure return hr; } // 2. Initialize PlayFab Core (authentication and entity management) hr = PFInitialize(nullptr); if (FAILED(hr)) { // Handle PlayFab Core initialization failure return hr; } // 3. Initialize PlayFab Services (optional - only if using other PlayFab services) hr = PFServicesInitialize(nullptr); if (FAILED(hr)) { // Handle PlayFab Services initialization failure return hr; } // 4. Create service configuration (connects to your PlayFab title) PFServiceConfigHandle serviceConfigHandle{ nullptr }; hr = PFServiceConfigCreateHandle( "https://YOUR_TITLE_ID.playfabapi.com", // Replace with your endpoint "YOUR_TITLE_ID", // Replace with your Title ID &serviceConfigHandle); if (FAILED(hr)) { // Handle service config creation failure return hr; } // 5. Initialize Game Saves with your service configuration hr = PFGameSaveFilesInitialize(serviceConfigHandle); if (FAILED(hr)) { // Handle Game Saves initialization failure return hr; } // Game Saves is now ready for use! ``` Récupérez votre ID de titre et votre point de terminaison d'API dans [PlayFab Game Manager](https://developer.playfab.com), sous les paramètres de votre titre. #### Séquence de nettoyage appropriée Lors de l'arrêt de votre application, nettoyez les ressources dans l'ordre inverse : ```cpp theme={null} // Clean up Game Saves PFGameSaveFilesUninitialize(); // Close service configuration PFServiceConfigCloseHandle(serviceConfigHandle); serviceConfigHandle = nullptr; // Async cleanup for PlayFab Services (only if initialized) XAsyncBlock async{}; HRESULT hr = PFServicesUninitializeAsync(&async); hr = XAsyncGetStatus(&async, true); // Wait for completion // Async cleanup for PlayFab Core hr = PFUninitializeAsync(&async); hr = XAsyncGetStatus(&async, true); // Wait for completion // Clean up XGameRuntime XGameRuntimeUninitialize(); ``` Utilisez toujours le modèle de nettoyage asynchrone pour PlayFab Services et Core afin de garantir une libération correcte des ressources. ## 4. Autres composants du SDK unifié PlayFab ### Modifications des API Party et Multiplayer Bien qu'elles ne soient pas directement requises pour les fonctionnalités de Game Saves, le GDK d'octobre 2025 inclut également des versions mises à jour des composants PlayFab Party et PlayFab Multiplayer dans le cadre du SDK unifié. Ces composants offrent de nouvelles API mieux intégrées au système d'authentification unifié. #### Principales modifications par rapport aux SDK autonomes **Intégration de l'authentification** : * **Ancien modèle** : auparavant, les titres utilisant les SDK Party/Multiplayer autonomes devaient gérer manuellement l'`EntityID` et l'`EntityToken` issus des résultats de connexion PlayFab et les transmettre aux API Party/Multiplayer * **Modèle du SDK unifié** : Party et Multiplayer acceptent désormais directement `PFEntityHandle`, ce qui élimine la gestion manuelle des jetons **Nouvelles API disponibles** : * Party : nouvelles API qui acceptent `PFEntityHandle` pour l'authentification des utilisateurs * Multiplayer : nouvelles API qui acceptent `PFEntityHandle` pour les opérations de lobby et de matchmaking **Avantages de la migration** (si vous utilisez Party/Multiplayer) : * Flux d'authentification simplifié avec actualisation automatique des jetons * Modèles de gestion des erreurs cohérents pour tous les composants PlayFab * Gestion unifiée de la mémoire et des modèles d'opérations asynchrones **Composants Party et Multiplayer** : si votre jeu utilise PlayFab Party ou Multiplayer, envisagez de migrer vers les nouvelles API unifiées qui acceptent directement `PFEntityHandle` pour une meilleure intégration. Toutefois, ce n'est pas nécessaire pour les fonctionnalités de Game Saves : vous pouvez ignorer la section 4 si vous utilisez uniquement Game Saves. ## 5. Implémentation sur Steam Deck La prise en charge de PlayFab Game Saves sur Steam Deck nécessite un travail d'implémentation supplémentaire important par rapport aux builds PC standard, notamment des flux d'authentification personnalisés, des rappels d'interface utilisateur complets et des stratégies de synchronisation soigneusement pensées. **Complexité de l'implémentation sur Steam Deck** : l'intégration au Steam Deck implique des flux d'authentification personnalisés, l'implémentation de rappels d'interface utilisateur et des différences critiques de comportement de synchronisation. En raison de la complexité et de l'étendue des exigences d'implémentation, l'implémentation sur Steam Deck fait l'objet d'un [guide dédié](/fr-CA/services/playfab/player-progression/game-saves/steam-deck-implementation). ### Principaux points à prendre en compte pour le Steam Deck **Différence critique de comportement de synchronisation** : * **PC Windows** : Game Saves s'exécute hors processus et peut poursuivre la synchronisation après l'arrêt du jeu * **Steam Deck** : Game Saves s'exécute uniquement dans le processus et cesse la synchronisation à l'arrêt du jeu **Exigences d'implémentation** : * Toutes les DLL du SDK unifié doivent être déployées avec votre build Steam * Flux d'authentification XUser personnalisé avec rappels d'interface utilisateur * Configuration du Registre pour les tests dans des bacs à sable autres que de production * Synchronisations fréquentes pour éviter les pertes de données **Recommandations générales de synchronisation** (utiles pour toutes les plateformes) : Bien que ces modèles soient requis pour le Steam Deck, ils sont fortement recommandés pour toutes les plateformes, en particulier les appareils portables, sur lesquels les arrêts soudains sont fréquents : * Synchronisez fréquemment les données de sauvegarde (après chaque niveau, point de contrôle ou progression importante) * Synchronisez toujours avant d'afficher une confirmation de « quitter le jeu » * Envisagez une synchronisation en arrière-plan lors des transitions de jeu * Implémentez des indicateurs de progression de la synchronisation pour garantir qu'elle se termine avant l'arrêt ### Implémentation complète sur Steam Deck Pour obtenir des détails complets sur l'implémentation sur Steam Deck, notamment : * La configuration détaillée du flux d'authentification * L'implémentation complète des rappels d'interface utilisateur * La séquence d'initialisation étape par étape * Un guide de résolution des problèmes * Des références d'exemples de code **Consultez le [guide d'implémentation sur Steam Deck](/fr-CA/services/playfab/player-progression/game-saves/steam-deck-implementation) dédié** Commencez par les exigences de ce document, puis passez au guide Steam Deck pour les détails d'implémentation propres à la plateforme. ## 6. Liste de contrôle de l'implémentation ### Prise en main (nouvelles implémentations) * [ ] **Configurez le GDK d'octobre 2025** et vérifiez l'installation * [ ] **Configurez le système de build** avec les chemins du GDK et les références de bibliothèques appropriés * [ ] **Ajoutez les bibliothèques du SDK unifié** à la configuration d'édition de liens de votre projet * [ ] **Incluez les en-têtes requis** dans votre code source * [ ] **Implémentez la séquence d'initialisation** selon le modèle du SDK unifié * [ ] **Configurez le déploiement des DLL** pour les builds Steam (4 DLL requises, 1 facultative) * [ ] **Testez les fonctionnalités de base** sur vos plateformes cibles ### Migration (implémentations existantes) * [ ] **Mettez à jour les chemins du système de build** de l'ancienne structure du GDK vers la nouvelle organisation * [ ] **Remplacez les bibliothèques autonomes** par les composants du SDK unifié * [ ] **Mettez à jour les inclusions d'en-têtes** pour utiliser les nouveaux en-têtes du SDK unifié * [ ] **Modifiez la séquence d'initialisation** pour utiliser les nouvelles API du SDK unifié * [ ] **Mettez à jour la séquence de nettoyage** avec le modèle de nettoyage asynchrone approprié * [ ] **Ajoutez les DLL supplémentaires** au déploiement Steam (1 DLL → 4-5 DLL) * [ ] **Vérifiez que les fonctionnalités** restent intactes après la migration ### Configuration du système de build * [ ] **Chemins d'inclusion** : définissez `$(GDK)\windows\include` (ou l'équivalent pour la plateforme) * [ ] **Chemins de bibliothèques** : définissez `$(GDK)\windows\lib\x64` (ou l'équivalent pour la plateforme) * [ ] **Bibliothèques liées** : ajoutez les fichiers .lib requis aux dépendances de l'éditeur de liens (4 requis, 1 facultatif) * [ ] **Déploiement des DLL** : configurez la copie automatique pour les builds Steam * [ ] **Détection de la plateforme** : ajoutez la logique nécessaire si vous générez pour plusieurs plateformes ### Tâches d'implémentation du code * [ ] **En-têtes** : incluez tous les en-têtes requis du SDK unifié * [ ] **Initialisation** : implémentez correctement la séquence d'initialisation en 5 étapes * [ ] **Gestion des erreurs** : ajoutez une vérification des erreurs appropriée à chaque étape d'initialisation * [ ] **Nettoyage** : implémentez un nettoyage en ordre inverse avec des modèles asynchrones * [ ] **Configuration** : remplacez les valeurs codées en dur par votre ID de titre PlayFab et votre point de terminaison ### Exigences de test * [ ] **PC Windows** : vérifiez les fonctionnalités de Game Saves * [ ] **Steam Deck** : terminez l'implémentation à l'aide du [guide d'implémentation sur Steam Deck](/fr-CA/services/playfab/player-progression/game-saves/steam-deck-implementation) * [ ] **Microsoft Store** : confirmez l'absence de régression des fonctionnalités * [ ] **Multiplateforme** : testez la synchronisation des sauvegardes entre toutes les plateformes (PC, Steam Deck, XBOX) ## 7. Ressources et soutien ### Liens vers la documentation * [Vue d'ensemble de Game Saves](/fr-CA/services/playfab/player-progression/game-saves/overview) * [Démarrage rapide de Game Saves](/fr-CA/services/playfab/player-progression/game-saves/quickstart) * [Guide d'implémentation sur Steam Deck](/fr-CA/services/playfab/player-progression/game-saves/steam-deck-implementation) ### Références d'exemples de code * **Exemple Game Saves pour Windows** : [PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/PlayFabGameSaveSample-Windows) * `GameSaveIntegration.cpp/.h` : intégration de base de Game Saves * `SteamIntegration.cpp/.h` : implémentation propre au Steam Deck (voir le guide Steam Deck) * `GameSaveIntegrationUI.cpp/.h` : implémentations des rappels d'interface utilisateur (voir le guide Steam Deck) ## Related topics - [Guide d'implémentation de PlayFab Game Saves sur Steam Deck](/fr-CA/services/playfab/player-progression/game-saves/steam-deck-implementation.md) - [Mode hors connexion de Game Saves](/fr-CA/services/playfab/player-progression/game-saves/offline.md) - [Version 0.2.0 de l'exemple XBOX Godot](/fr-CA/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-2-0.md) - [Structure de répertoires simplifiée du GDK (en-têtes et bibliothèques)](/fr-CA/build/gdk-and-engines/guides/gdk-directory-structure.md) - [Configuration du démarrage rapide du SDK unifié PlayFab](/fr-CA/services/playfab/sdks/unified-sdk/quickstart-setup.md)