Intégrer le GDK à un moteur C/C++ personnalisé

Utilisez cette rubrique si vous préparez votre jeu pour une publication sur le Microsoft Store sur PC et que votre jeu utilise un moteur C/C++ qui ne prend pas en charge le GDK de manière intégrée.

Création d’un produit dans Partner Center
Intégration du GDK dans des jeux C/C++
Test des services XBOX dans votre jeu
Publication

Création d’un produit dans Partner Center

Avant de pouvoir publier un jeu sur le Microsoft Store, vous devez créer votre produit compatible avec les services XBOX dans Partner Center. Pour plus d’informations sur Partner Center, consultez Configuration d’une application ou d’un jeu dans Partner Center, pour les partenaires gérés.

Intégration du GDK dans des jeux C/C++

Pour intégrer le GDK dans un jeu C/C++, le jeu a besoin de 4 éléments :

Le ou les en-têtes du GDK et de l’API des services XBOX (XSAPI) qui décrivent les signatures d’API et les structures de données.
Les bibliothèques d’importation qui indiquent à l’éditeur de liens comment résoudre les références externes aux fonctions exportées du GDK.
Les bibliothèques statiques XSAPI ou les bibliothèques d’importation qui indiquent à l’éditeur de liens comment résoudre les références externes aux fonctions exportées de la DLL XSAPI.
- XSAPI est disponible sous forme statique et dynamique. Reportez-vous au tableau ci-dessous pour plus d’informations et choisissez la forme statique ou dynamique.
Les bibliothèques de liens dynamiques qui contiennent l’implémentation d’exécution réelle des fonctions du GDK et de XSAPI (si vous utilisez la version dynamique de XSAPI).

Pour que les jeux s’intègrent aux expériences essentielles de l’écosystème XBOX, ils doivent interagir avec deux composants : Gaming Runtime Services (GRTS) et XSAPI. Voici les fichiers nécessaires à un jeu non managé :

Composant	GRTS (dynamique uniquement)	XSAPI (dynamique)	XSAPI (statique)
En-têtes	En-têtes GRTS : XUser, XGameSave, XGameUI, etc. (fournis avec le GDK)	En-têtes XSAPI : profile_c.h, achievements_c.h, etc. (fournis avec le GDK)	En-têtes XSAPI : profile_c.h, achievements_c.h, etc. (fournis avec le GDK)
Bibliothèque d’importation	xgameruntime.lib (fournie avec le GDK)	Microsoft.Xbox.Services.GDK.C.Thunks.lib (fournie avec le GDK)	Microsoft.Xbox.Services.142.GDK.C.lib (fournie avec le GDK)
Bibliothèque de liens dynamiques	xgameruntime.dll et quelques autres DLL (installées dans system32 par GRTS)	Microsoft.Xbox.Services.GDK.C.Thunks.dll (fournie avec le GDK, doit être incluse dans le package du jeu)	Non requise

Pour les jeux qui utilisent une architecture basée sur des plug-ins avec des fonctionnalités réparties sur plusieurs DLL, nous recommandons et prenons en charge l’intégration de XSAPI au moyen de Thunks.dll. Cette approche fonctionne de manière fiable sur les plateformes PC et XBOX.Lorsque vous liez XSAPI de manière statique dans plusieurs DLL, chaque DLL conserve sa propre copie de l’état global. Par conséquent, l’appel de XblInitialize dans une DLL n’initialise pas XSAPI dans les autres. Le partage de handles XSAPI entre des DLL disposant d’instances statiques distinctes peut entraîner des plantages ou un comportement imprévisible.Thunks.dll résout ce problème en fournissant une instance partagée unique de XSAPI et de son état. Cela évite la duplication et garantit un comportement cohérent dans toutes les DLL.Bien qu’il soit techniquement possible de lier XSAPI de manière statique dans une DLL et d’exporter les symboles, cette approche est plus complexe et sujette aux erreurs. L’utilisation de Thunks.dll est plus simple, plus sûre et entièrement prise en charge.

Ajout des prérequis pour Gaming Runtime Services et XSAPI à votre projet

Les étapes suivantes décrivent les modifications à apporter à votre projet pour vous assurer qu’il dispose de tous les prérequis nécessaires à l’utilisation de Gaming Runtime Services et de XSAPI.

Assurez-vous de cibler x64. Dans Visual Studio, accédez à Build->Configuration Manager et définissez Active solution platform sur x64.
Ajoutez les chemins d’inclusion suivants : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Include C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Include C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Include Où GDK version number est un répertoire nommé d’après l’année, le mois et le numéro de sous-version de la version. Par exemple, pour le GDK de juin 2022, le nom du répertoire est 220600. Pour Microsoft GDK (juin 2024) ou une version antérieure, utilisez C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include et C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Include Dans Visual Studio, vous ajoutez ces chemins dans la page des propriétés du projet sous Configuration Properties->VC++ Directories->Include Directories.
Ajoutez les chemins de bibliothèque suivants pour les bibliothèques d’importation : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64 C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64 Où GDK version number est un répertoire nommé d’après l’année, le mois et le numéro de sous-version de la version. Par exemple, pour le GDK de juin 2022, le nom du répertoire est 220600. Pour Microsoft GDK (juin 2024) ou une version antérieure, utilisez C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release et C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib Dans Visual Studio, vous ajoutez ces chemins dans la page des propriétés du projet sous Configuration Properties->VC++ Directories->Library Directories.
Ajoutez les bibliothèques suivantes à la liste des bibliothèques liées à votre projet : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64\xgameruntime.lib C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (or Microsoft.Xbox.Services.142.GDK.C.lib, if statically linking) C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64\libHttpClient.GDK.lib Où GDK version number est un répertoire nommé d’après l’année, le mois et le numéro de sous-version de la version. Par exemple, pour le GDK de juin 2022, le nom du répertoire est 220600. Pour Microsoft GDK (juin 2024) ou une version antérieure, utilisez C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (ou Microsoft.Xbox.Services.142.GDK.C.lib, en cas de liaison statique) et C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib\libHttpClient.GDK.lib Dans Visual Studio, vous ajoutez les bibliothèques dans la page des propriétés du projet sous Configuration Properties->Linker->Input->Additional Dependencies.
Définissez _GAMING_DESKTOP et WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP. Dans Visual Studio, vous ajoutez la ligne suivante dans la page des propriétés du projet sous C/C++->Command Line->Additional Options : /D "_GAMING_DESKTOP" /D "WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP"

Créez un fichier MicrosoftGame.config et assurez-vous qu’il est copié vers la même destination que le fichier .exe lors des builds. Remarque : si votre moteur prend en charge une fonctionnalité d’exécution dans l’éditeur qui utilise un autre fichier .exe lors de l’exécution, copiez également MicrosoftGame.config dans le même répertoire que ce fichier .exe. Si MicrosoftGame.config n’est pas présent dans le même répertoire que le fichier .exe, les services XBOX ne fonctionneront pas lorsque vous utiliserez votre fonctionnalité d’exécution dans l’éditeur. Pour commencer le développement, vous pouvez utiliser une configuration avec des valeurs par défaut comme dans l’exemple suivant. Les valeurs Identity Name, Executable Name et Executable Alias doivent toutes être remplacées par le nom de votre exécutable.

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
<Identity Name="Direct3DGame1_test"
            Publisher="CN=Publisher"
            Version="1.0.0.0"/>
<ExecutableList>
    <Executable Name="Direct3DGame1_test.exe"
                Id="Game"
                Alias="Direct3DGame1_test.exe"/>
</ExecutableList>
<ShellVisuals DefaultDisplayName="Direct3DGame1_test"
                PublisherDisplayName="PublisherName"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="Direct3DGame1_test"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>
</Game>

Assurez-vous que des copies de Microsoft.Xbox.Services.GDK.C.Thunks.dll (en cas de liaison dynamique), XCurl.dll et libHttpClient.GDK.dll sont copiées vers la même destination que le fichier .exe lors des builds. Remarque : si votre moteur prend en charge une fonctionnalité d’exécution dans l’éditeur qui utilise un autre fichier .exe lors de l’exécution, assurez-vous que ce fichier .exe référence également ces DLL. Si les DLL ne sont pas référencées par le fichier .exe, les services XBOX ne fonctionneront pas lorsque vous utiliserez votre fonctionnalité d’exécution dans l’éditeur. En cas de liaison dynamique à XSAPI, Microsoft.Xbox.Services.GDK.C.Thunks.dll se trouve dans le répertoire suivant de l’installation du GDK : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release] XCurl.dll se trouve dans le répertoire suivant de l’installation du GDK : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64 libHttpClient.GDK.dll se trouve dans le répertoire suivant de l’installation du GDK : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\x64 Où GDK version number est un répertoire nommé d’après l’année, le mois et le numéro de sous-version de la version. Par exemple, pour le GDK de juin 2022, le nom du répertoire est 220600. Pour Microsoft GDK (juin 2024) ou une version antérieure, utilisez C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\[Debug|Release], C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\CommonConfiguration\neutral et C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\CommonConfiguration\neutral

Si vous intégrez le GDK dans un projet Visual Studio Desktop existant, vous pouvez également suivre les étapes de cette rubrique pour convertir votre projet en projet GDK : Ajout du Microsoft Game Development Kit à un projet de bureau existant.

Mettre à jour MicrosoftGame.config

Le fichier MicrosoftGame.config créé à l’étape précédente contient des valeurs par défaut qui permettent de commencer le développement sur PC et XBOX sans configuration supplémentaire. Vous ne devez mettre à jour ces valeurs que lorsque vous commencez à utiliser des fonctionnalités du Gaming Runtime, du Microsoft Store et de l’identité du titre. Pour utiliser les fonctionnalités des services XBOX, mettez à jour le fichier MicrosoftGame.config de votre projet avec les détails d’identité de votre projet Partner Center.

Accédez au tableau de bord Partner Center.
Sélectionnez votre jeu dans la liste des produits.
Sélectionnez l’onglet Game setup, puis sélectionnez Identity details.
Sélectionnez Show Details pour développer la section Identity details.
Utilisez les valeurs suivantes du tableau de la section Identity details, puis copiez ces valeurs depuis Partner Center dans l’élément et le champ correspondants de MicrosoftGame.config.

Nom dans Partner Center	MicrosoftGame.config
XBOX Title ID	TitleId
Package/Identity/Name	Identity->Name
Package/Identity/Publisher	Identity->Publisher
XBOX services -> XBOX Settings -> MSAAppId	MSAAppId

Par exemple, les détails d’identité suivants dans Partner Center donneraient un fichier MicrosoftGame.config semblable à l’exemple ci-dessous :

Nom dans Partner Center	Exemple de valeur
XBOX Title ID	64353034
Package/Identity/Name	41336MicrosoftATG.Achievements2017Redux
Package/Identity/Publisher	CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
XBOX services -> XBOX Settings -> MSAAppId	0000000000000000

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

  <Identity Name='41336MicrosoftATG.Achievements2017Redux' Version="1.1.0.0" Publisher='CN=A4954634-DF4B-47C7-AB70-D3215D246AF1' />


  <TitleId>64353034</TitleId>
  <MSAAppId>0000000000000000</MSAAppId>

  <ExecutableList>
    <Executable Name="Achievements2017_desktop.exe"
                TargetDeviceFamily="PC"
                Id="Game"/>
  </ExecutableList>

  <ShellVisuals DefaultDisplayName="Achievements2017 Desktop Sample"
                PublisherDisplayName="Xbox Advanced Technology Group"
                StoreLogo="Assets\StoreLogo.png"
                Square150x150Logo="Assets\Logo.png"
                Square44x44Logo="Assets\SmallLogo.png"
                Square480x480Logo="Assets\LargeLogo.png"
                Description="Achievements2017"
                ForegroundText="dark"
                BackgroundColor="#000000"
                SplashScreenImage="Assets\SplashScreen.png"/>
</Game>

Consultez Vue d’ensemble de MicrosoftGame.config pour plus d’informations sur les valeurs de MicrosoftGame.config.

Initialiser le runtime de jeu et XSAPI

Les étapes suivantes montrent comment initialiser Gaming Runtime Services et XSAPI dans votre jeu.

Incluez l’en-tête XGameRuntime et l’en-tête services-c de XSAPI.
#include <XGameRuntime.h> #include <xsapi-c/services_c.h>

Appelez XGameRuntimeInitialize pour initialiser le runtime du GDK.

// Initialize the GameRuntime
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr))
{
    if (hr == E_GAMERUNTIME_DLL_NOT_FOUND || hr == E_GAMERUNTIME_VERSION_MISMATCH)
    {
        (void)MessageBoxW(nullptr, L"Game Runtime is not installed on this system or needs updating.", g_szAppName, MB_ICONERROR | MB_OK);
    }
    return 1;
}

Appelez XblInitialize pour initialiser XSAPI.

 XblInitArgs xblArgs = {};
 //xblArgs.queue = queue; // Uncomment this line if you've chosen to create your own XTaskQueue. Otherwise, by default, this line is not needed.
 xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Add your scid from your Partner Center project here;
 HRESULT hr = XblInitialize(&xblArgs);
 if (FAILED(hr))
 {
     // Handle failure
 }

Désinitialisation du runtime de jeu

Gaming Runtime Services doit être désinitialisé avant que votre jeu ne se ferme. XSAPI n’a pas besoin d’être explicitement nettoyé avant la fermeture. Désinitialisez le runtime du GDK en appelant XGameRuntimeUninitialize.

 // Uninitialize the Gaming Runtime after
 // all other activity has been completed.
 XGameRuntimeUninitialize();

Consultez Prise en main des API des services XBOX pour une vue d’ensemble détaillée de l’utilisation de XSAPI dans votre jeu.
Consultez Fonctionnalités du Game Development Kit (GDK) pour des vues d’ensemble de l’implémentation des fonctionnalités du GDK.

Test des services XBOX dans votre jeu

Pour tester les fonctionnalités des services XBOX dans votre jeu, comme les succès, vous devez utiliser une sandbox et des comptes de test ayant accès à cette sandbox.

Création d’un compte de test

Pour tester les fonctionnalités des services XBOX dans votre jeu, créez des comptes de test ayant accès à votre sandbox de développement. Pour plus d’informations sur la création de comptes de test, consultez Création de comptes de test.

Changement de sandbox

Après avoir créé un compte de test, utilisez ce compte pour accéder à votre sandbox en procédant comme suit.

Pour trouver votre ID de sandbox, accédez à Partner Center.
Sélectionnez XBOX services, puis sélectionnez Gameplay Settings.
Votre ID de sandbox se trouve sur le premier onglet et se présente sous la forme « ABCDEF.0 ».
Ouvrez le menu Démarrer.
Entrez Microsoft GDK Command Prompts, puis appuyez sur Entrée sur votre clavier.
Ouvrez la première invite de commandes.
Dans l’invite de commandes, entrez XblPCSandbox.exe [your sandbox ID].
Une fois que l’invite de commandes a lancé plusieurs applications, connectez-vous à l’application XBOX avec votre compte de test.

Si vous parvenez à vous connecter, vous avez créé un compte de test et basculé vers votre sandbox pour commencer les tests. Pour plus d’informations sur les sandbox, consultez Vue d’ensemble des sandbox des services XBOX.

Publication

Pour être prêt à publier votre jeu, vous devez :

Avoir terminé l’intégration de votre jeu avec le GDK
Avoir créé un package de jeu en suivant les étapes de Prise en main de l’empaquetage de titres pour PC à l’aide des outils d’empaquetage MSIXVC

Une fois ces deux conditions remplies, vous êtes prêt à publier. Pour soumettre votre jeu, accédez à Partner Center et suivez les instructions de l’interface utilisateur.

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Création d’un produit dans Partner Center

Intégration du GDK dans des jeux C/C++

Ajout des prérequis pour Gaming Runtime Services et XSAPI à votre projet

Mettre à jour MicrosoftGame.config

Initialiser le runtime de jeu et XSAPI

Désinitialisation du runtime de jeu

Test des services XBOX dans votre jeu

Création d’un compte de test

Changement de sandbox

Publication

​Création d’un produit dans Partner Center

​Intégration du GDK dans des jeux C/C++

​Ajout des prérequis pour Gaming Runtime Services et XSAPI à votre projet

​Mettre à jour MicrosoftGame.config

​Initialiser le runtime de jeu et XSAPI

​Désinitialisation du runtime de jeu

​Test des services XBOX dans votre jeu

​Création d’un compte de test

​Changement de sandbox

​Publication

Création d’un produit dans Partner Center

Intégration du GDK dans des jeux C/C++

Ajout des prérequis pour Gaming Runtime Services et XSAPI à votre projet

Mettre à jour MicrosoftGame.config

Initialiser le runtime de jeu et XSAPI

Désinitialisation du runtime de jeu

Test des services XBOX dans votre jeu

Création d’un compte de test

Changement de sandbox

Publication