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 autour du partage de code et axée sur des plateformes précises. L’intégration de build pour cette disposition reposait fortement 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 et des systèmes de build autres que Microsoft.

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

La disposition de fichiers existante du Microsoft GDK se résume comme suit.

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 mettent en œuvre la logique de construction des chemins include/lib qui combinent tout ce contenu de diverses façons. Si vous utilisiez CMake ou une solution make personnalisée, cette logique devait également y être mise en œuvre. 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 les deux styles, ancien et nouveau. Les deux dispositions sont installées par défaut. L’installation du GDK comprend maintenant 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 pour la suppression de l’ancienne disposition est d’un an après la sortie du GDK d’octobre 2025.

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

Pour la version d’octobre 2025 du GDK, la nouvelle disposition offre une solution de rechange pour les en-têtes et les bibliothèques qui facilite l’intégration des plateformes 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 qu’utilisait 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 du GDK devraient contenir des instructions comme celles-ci.

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

Pour la nouvelle disposition, la propriété Console_Libs énumère les bibliothèques de base requises.

Plateforme	Bibliothèques de base
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 « sur adhésion ».

Plateforme	Bibliothèques de base
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ées, 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 énumère toutes les DLL possibles, mais chaque projet n’aura besoin que de certaines d’entre elles.

  <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 est défini uniquement par le Microsoft GDK avec XBOX Extensions. Par conséquent, 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 ou 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 à 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>

Comment mettre à jour 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 à true dans votre fichier de 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 fasse référence à lib\arm64 au lieu de lib\x64.
Mettez à jour les références aux bibliothèques 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. Vérifiez l’utilisation de ReferenceCopyLocalPaths dans votre fichier .vcxproj qui pourrait devoir être mise à jour pour faire référence au 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. Vérifiez si votre système de projet contient des é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 effectuer une build pour PC. Dans l’ancienne disposition, il fallait 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 sur adhésion doivent être copiées dans le répertoire binaire comme ci-dessus, au moyen d’une action de build personnalisée ou du groupe d’éléments ReferenceCopyLocalPaths pour la disposition finale. Les autres instructions concernant PreprocessorDefinitions et la gestion du fichier .mgc avec les ressources d’image demeurent 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 (en supposant CMake 3.21 ou une 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

Une build pour Windows x64 avec le GDK nécessite ce qui suit.

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 trouver les informations d’édition en analysant un fichier, utilisez grdk.h. Voici un exemple en PowerShell qui fonctionne également avec les anciennes versions 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 des bibliothèques

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

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

Utilisation d’un fichier Directory.Build.props

Comment mettre à jour 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 des bibliothèques

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

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

​Utilisation d’un fichier Directory.Build.props

​Comment mettre à jour 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 des bibliothèques

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

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

Utilisation d’un fichier Directory.Build.props

Comment mettre à jour 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é