Structure de répertoires simplifiée du GDK (en-têtes et bibliothèques)

Dans les versions actuelles du Microsoft Game Development Kit (GDK), la disposition était optimisée pour le partage de code et axée sur des plateformes spécifiques. L’intégration de build pour cette disposition reposait largement sur la dissimulation de la complexité dans des plateformes MSBuild personnalisées. Pour la nouvelle disposition, l’accent est mis sur la simplification de l’intégration, la prise en charge d’une liste croissante de plateformes cibles et l’amélioration de la prise en charge des plateformes MSBuild standard comme des systèmes de build non Microsoft.

Ancienne disposition des en-têtes et bibliothèques

La disposition de fichiers existante du Microsoft GDK est résumée ci-dessous.

251000\
    GRDK\
        ExtensionLibraries\
            Xbox.Services.API.C\
                ExtensionLibrary.props
                DesignTime\CommonConfiguration\Neutral\
                    Include\
                    Lib\
                    Redist\
            ...
        GameKit\
            Include\
            Lib\
                amd64\

Les plateformes MSBuild personnalisées Gaming.Desktop.x64 implémentent la logique de construction des chemins include/lib qui combinent tout ce contenu de diverses manières. Si vous utilisiez CMake ou une solution make personnalisée, cette logique devait également y être implémentée. Pour un exemple détaillé, consultez la version d’avril 2025 de CMakeExample. L’ancienne disposition est toujours présente dans le GDK d’octobre 2025 afin de prendre en charge à la fois l’ancien et le nouveau style. Les deux dispositions sont installées par défaut. Le programme d’installation du GDK inclut désormais une option permettant d’installer uniquement la nouvelle disposition. Un futur GDK supprimera l’ancienne disposition afin de réduire l’espace occupé sur le disque dur et la taille globale du téléchargement. La date cible actuelle de suppression de l’ancienne disposition est fixée à un an après la publication du GDK d’octobre 2025.

Nouvelle disposition des en-têtes et bibliothèques

Pour la version d’octobre 2025 du GDK, la nouvelle disposition propose une organisation alternative des en-têtes et bibliothèques qui facilite l’intégration à la plateforme et permet d’accueillir d’autres plateformes au fil du temps.

251000\
    windows\
        bin\
            arm64
            x64\
        include\
        lib\
            arm64
            x64\
        redist

Utilisation de la nouvelle disposition avec les plateformes MSBuild personnalisées

Les plateformes MSBuild Gaming.*.x64 existantes utilisent l’ancienne disposition par défaut, mais vous pouvez adopter la nouvelle disposition en définissant la propriété GDKCrossPlatform.

<PropertyGroup Label="Globals">
...
  <GDKCrossPlatform>true</GDKCrossPlatform>
</PropertyGroup>

Cela ajoute au projet les chemins include/lib appropriés au lieu des divers chemins complexes utilisés par l’ancienne disposition. Dans cette nouvelle intégration simplifiée, le mécanisme des bibliothèques d’extension n’est plus utilisé. Tout le contenu est disponible par défaut au moment de la build dans les chemins include/lib. Le projet doit ensuite effectuer l’édition de liens avec les bibliothèques supplémentaires qu’il utilise. Les projets créés à partir des anciens modèles de projet GDK doivent contenir des instructions comme celle-ci.

<AdditionalDependencies>uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies)</AdditionalDependencies>

Pour la nouvelle disposition, la propriété Console_Libs répertorie les bibliothèques principales requises.

Plateforme	Bibliothèques principales
Gaming.*.x64	xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib

Le projet doit ajouter à AdditionalDependencies les bibliothèques d’extension qu’il consomme, car chacune d’elles est facultative (« opt-in »).

Plateforme	Bibliothèques principales
Xbox.LibHttpClient	libHttpClient.lib
Xbox.XCurl.API	XCurl.lib
Xbox.Game.Chat.2.Cpp.API	GameChat2.lib
Xbox.Services.API.C (Debug)	Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.Debug.lib
Xbox.Services.API.C (Release)	Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.lib
PlayFab.Party.Cpp	Party.lib
PlayFab.PartyXboxLive.Cpp	PartyXboxLive.lib
PlayFab.Services.C	PlayFabCore.lib PlayFabGameSave.lib PlayFabServices.lib
PlayFab.Multiplayer.Cpp	PlayFabMultiplayer.lib

Le projet doit également copier dans la disposition les DLL supplémentaires qu’il utilise. Vous pouvez le faire soit au moyen d’étapes de build personnalisée, typiques de nombreuses intégrations de bibliothèques DLL, soit en modifiant le fichier vcxproj ou en ajoutant un fichier props pour utiliser la liste de groupes d’éléments ReferenceCopyLocalPaths. Le code MSBuild ci-dessous répertorie toutes les DLL possibles, mais chaque projet n’en aura besoin que de certaines.

  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\libHttpClient.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\XCurl.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\GameChat2.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\Party.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PartyXboxLive.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabCore.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabGameSave.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabMultiplayer.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabServices.dll" />
  </ItemGroup>

GameDKLatest n’est défini que par le Microsoft GDK avec XBOX Extensions. C’est pourquoi nous avons introduit de nouvelles variables d’environnement qui prennent entièrement en charge l’installation côte à côte des deux versions du Microsoft GDK : GameDKCoreLatest est défini par le Microsoft GDK.

Utilisation d’un fichier Directory.Build.props

Pour valider rapidement des projets GDK Gaming.*.x64 existants avec la nouvelle disposition, placez le contenu suivant dans un fichier nommé Directory.Build.props dans votre arborescence source. Cela active la nouvelle disposition et inclut la plupart, voire la totalité, des bibliothèques d’extension, même si le projet ne les utilise pas.

La propriété GDKExtLibNames n’est pas utilisée par les règles MSBuild lors d’une build avec GDKCrossPlatform défini sur true. Comme elle est déjà présente pour les builds avec les anciennes règles MSBuild, elle est utilisée dans ce fichier props pour activer certaines DLL supplémentaires dans la disposition.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <PropertyGroup>
    <GDKCrossPlatform>true</GDKCrossPlatform>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
    <AllExtensionLibs>Appnotify.lib;winhttp.lib;crypt32.lib;libHttpClient.lib;XCurl.lib;GameChat2.lib;PlayFabCore.lib;PlayFabServices.lib;PlayFabMultiplayer.lib;Party.lib;PartyXboxLive.lib;PlayFabGameSave.lib</AllExtensionLibs>
    <AllExtensionLibs Condition="'$(Configuration)'=='Debug'">Microsoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs)</AllExtensionLibs>
    <AllExtensionLibs Condition="'$(Configuration)'!='Debug'">Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs)</AllExtensionLibs>
  </PropertyGroup>

  <ItemDefinitionGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <Link>
      <AdditionalDependencies>$(AllExtensionLibs);%(AdditionalDependencies)</AdditionalDependencies>
    </Link>
  </ItemDefinitionGroup>

  <!--
    Makes sure we deploy all the libs we need. We use the 'old layout' GDKExtLibNames property as a way to test
    what is requested to try to reduce the over-inclusion of unused DLLs.
  -->

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\libHttpClient.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\XCurl.dll" />
  </ItemGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64' AND $(GDKExtLibNames.Contains('Xbox.Game.Chat.2.Cpp.API'))">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\GameChat2.dll" />
  </ItemGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64' AND $(GDKExtLibNames.Contains('PlayFab'))">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\Party.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PartyXboxLive.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabCore.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabGameSave.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabMultiplayer.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabServices.dll" />
  </ItemGroup>

</Project>

Mise à jour d’un jeu x64 pour ajouter ARM64

Pour ajouter la prise en charge d’ARM64 à un projet de jeu x64 existant, procédez comme suit :

Utilisez Visual Studio 2022. La prise en charge d’ARM64 nécessite Visual Studio 2022. Visual Studio 2019 n’est pas pris en charge pour les builds ARM64.
Activez la nouvelle disposition. Assurez-vous que votre projet utilise la nouvelle disposition en définissant GDKCrossPlatform sur true dans votre fichier projet.
Créez des configurations ARM64. Copiez vos configurations x64 existantes (comme Debug et Release) pour créer les configurations ARM64 correspondantes.
Mettez à jour les chemins des bibliothèques. Modifiez les répertoires VC++ de vos configurations ARM64 afin que le chemin des bibliothèques référence lib\arm64 au lieu de lib\x64.
Mettez à jour les références à la bibliothèque XSAPI. Mettez à jour les instructions d’édition de liens pour toutes les configurations (pas seulement ARM64) afin d’utiliser Microsoft.Xbox.Services.143.GDK.C.lib au lieu de Microsoft.Xbox.Services.142.GDK.C.lib.
Mettez à jour ReferenceCopyLocalPaths. Recherchez dans votre fichier .vcxproj les utilisations de ReferenceCopyLocalPaths qui pourraient devoir être mises à jour pour référencer le dossier bin arm64 au lieu de x64.

Si le démarrage de votre titre échoue avec l’erreur 0xc000007b, cela signifie que vous avez accidentellement tenté de charger une DLL au format x64 dans votre processus ARM64. Recherchez dans votre système de projet les éléments ReferenceCopyLocalPaths qui pourraient devoir être mis à jour.

Utilisation de la nouvelle disposition avec la plateforme MSBuild x64

Au lieu d’utiliser la plateforme Gaming.Desktop.x64, vous pouvez utiliser la plateforme x64 standard pour générer pour PC. Dans l’ancienne disposition, cela nécessitait d’ajouter des instructions <Import Project="...\ExtensionLibrary.props"> pour les bibliothèques d’extension, comme décrit dans Utilisation de la plateforme x64 avec le Microsoft Game Development Kit (GDK). Dans la nouvelle disposition, les instructions d’intégration sont simplifiées.

  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
  <ExecutablePath>$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)</ExecutablePath>
  <IncludePath>$(GDKCrossPlatformPath)windows\Include;$(IncludePath);</IncludePath>
  <LibraryPath>$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)</LibraryPath>
</PropertyGroup>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
  <ExecutablePath>$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)</ExecutablePath>
  <IncludePath>$(GDKCrossPlatformPath)windows\Include;$(IncludePath);</IncludePath>
  <LibraryPath>$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)</LibraryPath>
</PropertyGroup>

Ajoutez toutes les bibliothèques d’extension requises à AdditionalDependencies, en plus de la liste d’origine.

<AdditionalDependencies>xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies)</AdditionalDependencies>

Les DLL des bibliothèques d’extension facultatives doivent être copiées dans le répertoire des binaires comme indiqué ci-dessus, à l’aide d’une action de build personnalisée ou du groupe d’éléments ReferenceCopyLocalPaths pour la disposition finale. Les autres instructions relatives à PreprocessorDefinitions et à la gestion du fichier .mgc avec les ressources d’images restent inchangées.

Utilisation de la nouvelle disposition avec CMake

Lorsque vous utilisez les générateurs Microsoft Visual Studio avec CMake et les plateformes MSBuild personnalisées Gaming.*.x64, activez la nouvelle disposition à l’aide du code suivant.

set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true")

Dans CMakeGDKExample, supprimez l’utilisation de VS_GLOBAL_GDKExtLibNames et remplacez-la par le code suivant (avec CMake 3.21 ou version ultérieure) pour copier les DLL d’extension utilisées dans la disposition.

add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E $<IF:$<BOOL:$<TARGET_RUNTIME_DLLS:${PROJECT_NAME}>>,copy,true>
    $<TARGET_RUNTIME_DLLS:${PROJECT_NAME}> $<TARGET_FILE_DIR:${PROJECT_NAME}>
    COMMAND_EXPAND_LISTS
    )

Utilisation de la nouvelle disposition avec des systèmes de build personnalisés

La génération pour Windows x64 avec le GDK nécessite les éléments suivants.

set INCLUDE=%GameDKCoreLatest%windows\include;%INCLUDE%
set LIB=%GameDKCoreLatest%windows\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKCoreLatest%windows\bin\x64;%PATH%

Lecture de l’édition de build à partir d’un fichier installé

La nouvelle disposition ne contient pas le fichier grdk.ini. Pour obtenir les informations d’édition en analysant un fichier, utilisez grdk.h. Voici un exemple en PowerShell qui fonctionne également avec les versions antérieures du GDK.

$result = Get-ChildItem -Path $env:GameDKCoreLatest -Filter "grdk.h" -Recurse
if ($result.Count -eq 0)
{
    $result = Get-ChildItem -Path $env:GRDKLatest -Filter "grdk.h" -Recurse
}
if ($result.Count -eq 0)
{
    Write-Error "##[error]Failed to find grdk.h in either GameDKCoreLatest or GRDKLatest" -ErrorAction Stop
}

$content = Get-Content -Path $result[0].FullName

if (-not ([string]$content -match '#define\s+_GRDK_EDITION\s+([0-9][0-9][0-9][0-9][0-9][0-9])')) {
    Write-Error "##[error]Failed to find edition define" -ErrorAction Stop
}

$xbld_edition = $Matches[1]

if (-not ([string]$content -match '#define\s+_GRDKVER_PRODUCTBUILDVER_FULL\s+([0-9]+\.[0-9]+\.([0-9]+)\.[0-9]+)')) {
    Write-Error "##[error]Failed to find full version define" -ErrorAction Stop
}

$xbld_full_productbuild = $Matches[1]
$xbld_build = $Matches[2]

if (-not ([string]$content -match '#define\s+_GRDK_MM_NUM\s+([0-9]{1,2})')) {
    Write-Error "##[error]Failed to find month define" -ErrorAction Stop
}

$month = $Matches[1]

if (-not ([string]$content -match '#define\s+_GRDK_FULLYY\s+([0-9]{4})')) {
    Write-Error "##[error]Failed to find full year define" -ErrorAction Stop
}

$year = $Matches[1]

Write-Output ("_xbld_name={0} {1} GRDK" -f (Get-Culture).DateTimeFormat.GetMonthName([int]$month), $year)
Write-Output ("_xbld_edition={0}" -f $xbld_edition)
Write-Output ("_xbld_full_productbuild={0}" -f $xbld_full_productbuild)
Write-Output ("_xbld_build={0}" -f $xbld_build)

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Structure de répertoires simplifiée du GDK (en-têtes et bibliothèques)

Ancienne disposition des en-têtes et bibliothèques

Nouvelle disposition des en-têtes et bibliothèques

Utilisation de la nouvelle disposition avec les plateformes MSBuild personnalisées

Utilisation d’un fichier Directory.Build.props

Mise à jour d’un jeu x64 pour ajouter ARM64

Utilisation de la nouvelle disposition avec la plateforme MSBuild x64

Utilisation de la nouvelle disposition avec CMake

Utilisation de la nouvelle disposition avec des systèmes de build personnalisés

Lecture de l’édition de build à partir d’un fichier installé

​Ancienne disposition des en-têtes et bibliothèques

​Nouvelle disposition des en-têtes et bibliothèques

​Utilisation de la nouvelle disposition avec les plateformes MSBuild personnalisées

​Utilisation d’un fichier Directory.Build.props

​Mise à jour d’un jeu x64 pour ajouter ARM64

​Utilisation de la nouvelle disposition avec la plateforme MSBuild x64

​Utilisation de la nouvelle disposition avec CMake

​Utilisation de la nouvelle disposition avec des systèmes de build personnalisés

​Lecture de l’édition de build à partir d’un fichier installé

Ancienne disposition des en-têtes et bibliothèques

Nouvelle disposition des en-têtes et bibliothèques

Utilisation de la nouvelle disposition avec les plateformes MSBuild personnalisées

Utilisation d’un fichier Directory.Build.props

Mise à jour d’un jeu x64 pour ajouter ARM64

Utilisation de la nouvelle disposition avec la plateforme MSBuild x64

Utilisation de la nouvelle disposition avec CMake

Utilisation de la nouvelle disposition avec des systèmes de build personnalisés

Lecture de l’édition de build à partir d’un fichier installé