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 :- Nouvelle organisation des dossiers du GDK : structure de répertoires du SDK centrée sur la plateforme
- Intégration de XGameRuntime : runtime multiplateforme avec des exigences de déploiement spécifiques
- SDK unifié PlayFab : architecture de SDK moderne pour tous les composants PlayFab
- Autres composants du SDK unifié : composants Party et Multiplayer mis à jour (le cas échéant)
Vous découvrez Game Saves? Commencez par la vue d’ensemble de Game Saves et le guide de démarrage rapide 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 :$(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 :Détails de la prise en charge des plateformes
- XBOX : utilise les dossiers
xboxpour 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
windowspour assurer la compatibilité avec l’émulation Proton
Étapes d’implémentation
-
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
-
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)
- 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 :2. Exigences de la plateforme Steam
Essentiel pour les builds Steam : Lorsque vous générez pour Steam, vous devez inclurexgameruntime.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
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 :Comportement du runtime selon la plateforme
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)
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
- 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
DLL requises pour le déploiement
Configuration du système de build
Configuration MSBuild
Configurez votre projet Visual Studio pour qu’il lie le SDK unifié :$(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 :Implémentation du code
En-têtes requis
Incluez les en-têtes nécessaires du SDK unifié dans votre projet :Séquence d’initialisation
Suivez cet ordre d’initialisation pour configurer correctement Game Saves :Séquence de nettoyage appropriée
Lors de l’arrêt de votre application, nettoyez les ressources dans l’ordre inverse :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’
EntityIDet l’EntityTokenissus 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
- Party : nouvelles API qui acceptent
PFEntityHandlepour l’authentification des utilisateurs - Multiplayer : nouvelles API qui acceptent
PFEntityHandlepour les opérations de lobby et de matchmaking
- 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é.
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
- 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
- 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
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
- 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
Références d’exemples de code
- Exemple Game Saves pour Windows : PlayFabGameSaveSample-Windows
GameSaveIntegration.cpp/.h: intégration de base de Game SavesSteamIntegration.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)
