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

Utilisez cette rubrique si vous préparez votre jeu pour la publication sur le Microsoft Store sur PC et que votre jeu utilise un moteur basé sur C/C++ qui n’offre pas de prise en charge intégrée du GDK.

Création d’un produit dans Partner Center
Intégration du GDK dans les jeux C/C++
Test des XBOX services 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 XBOX services 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 les jeux C/C++

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

Les fichiers d’en-tête du GDK et de l’API XBOX Services (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 des DLL XSAPI.
- XSAPI est offert sous forme statique et dynamique. Consultez le 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 : les 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. (du GDK)	En-têtes XSAPI : profile_c.h, achievements_c.h, etc. (du GDK)	En-têtes XSAPI : profile_c.h, achievements_c.h, etc. (du GDK)
Bibliothèque d’importation	xgameruntime.lib (du GDK)	Microsoft.Xbox.Services.GDK.C.Thunks.lib (du GDK)	Microsoft.Xbox.Services.142.GDK.C.lib (du 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 (du GDK, doit être inclus dans le package du jeu)	Non requis

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 à l’aide de Thunks.dll. Cette approche fonctionne de façon 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 ayant des 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 seule DLL et d’en 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 exigences des Gaming Runtime Services et de XSAPI à votre projet

Les étapes suivantes décrivent les modifications à apporter à votre projet pour qu’il réponde à toutes les exigences d’utilisation des Gaming Runtime Services et de XSAPI.

Assurez-vous que la cible est 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 correspond à un répertoire nommé selon 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 serait 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, 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 correspond à un répertoire nommé selon 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 serait 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, 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 correspond à un répertoire nommé selon 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 serait 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, 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, 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é dans 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 XBOX services ne fonctionneront pas lorsque vous utilisez 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 seraient toutes 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 dans 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 XBOX services ne fonctionneront pas lorsque vous utilisez votre fonctionnalité d’exécution dans l’éditeur. En cas de liaison dynamique à XSAPI, Microsoft.Xbox.Services.GDK.C.Thunks.dll se trouve dans l’installation du GDK, dans le répertoire suivant : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release] XCurl.dll se trouve dans l’installation du GDK, dans le répertoire suivant : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64 libHttpClient.GDK.dll se trouve dans l’installation du GDK, dans le répertoire suivant : C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\x64 Où GDK version number correspond à un répertoire nommé selon 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 serait 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.

Mise à jour de MicrosoftGame.config

Le fichier MicrosoftGame.config créé à l’étape précédente contient des valeurs par défaut qui permettent un développement initial sur PC et XBOX sans configuration supplémentaire. Vous devez mettre à jour ces valeurs uniquement 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 XBOX services, mettez à jour le fichier MicrosoftGame.config de votre projet avec les détails d’identité de votre projet dans Partner Center.

Accédez au tableau de bord de 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 de 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 les 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

Les Gaming Runtime Services doivent être désinitialisés avant la fermeture de votre jeu. XSAPI n’a pas besoin d’être nettoyé explicitement 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 Bien démarrer avec les API des XBOX services 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 XBOX services dans votre jeu

Pour tester les fonctionnalités des XBOX services dans votre jeu, comme les succès, vous devez utiliser un bac à sable et des comptes de test ayant accès à ce bac à sable.

Création d’un compte de test

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

Changement de bac à sable

Après avoir créé un compte de test, utilisez-le pour accéder à votre bac à sable en suivant les étapes ci-dessous.

Pour trouver l’ID de votre bac à sable, accédez à Partner Center.
Sélectionnez XBOX services, puis sélectionnez Gameplay Settings.
L’ID de votre bac à sable se trouve dans le premier onglet et porte un nom comme « 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 changé de bac à sable pour commencer les tests. Pour plus d’informations sur les bacs à sable, consultez Vue d’ensemble des bacs à sable des XBOX services.

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 Bien démarrer avec la création de packages de titres pour PC à l’aide des outils de création de packages MSIXVC

Une fois ces deux exigences 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 les jeux C/C++

Ajout des exigences des Gaming Runtime Services et de XSAPI à votre projet

Mise à jour de MicrosoftGame.config

Initialiser le runtime de jeu et XSAPI

Désinitialisation du runtime de jeu

Test des XBOX services dans votre jeu

Création d’un compte de test

Changement de bac à sable

Publication

​Création d’un produit dans Partner Center

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

​Ajout des exigences des Gaming Runtime Services et de XSAPI à votre projet

​Mise à jour de MicrosoftGame.config

​Initialiser le runtime de jeu et XSAPI

​Désinitialisation du runtime de jeu

​Test des XBOX services dans votre jeu

​Création d’un compte de test

​Changement de bac à sable

​Publication

Création d’un produit dans Partner Center

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

Ajout des exigences des Gaming Runtime Services et de XSAPI à votre projet

Mise à jour de MicrosoftGame.config

Initialiser le runtime de jeu et XSAPI

Désinitialisation du runtime de jeu

Test des XBOX services dans votre jeu

Création d’un compte de test

Changement de bac à sable

Publication