Passer au contenu principal
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 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 :
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 :
Configuration MSBuild :

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 :

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 :
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 :
Configuration MSBuild :

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

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é :
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 :

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 :
Récupérez votre ID de titre et votre point de terminaison d’API dans PlayFab Game Manager, 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 :
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é.

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 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
  • 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 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)
Dernière modification le 8 octobre 2026