Simplified GDK directory structure (headers and libraries)

In current versions of the Microsoft Game Development Kit (GDK), the layout was optimized around code sharing and focused on specific platforms. Build integration for this layout relied heavily on hiding the complexity in MSBuild custom platforms. For the new layout, the focus is on simplifying the integration, supporting a growing list of target platforms, and improving support for both stock MSBuild platforms and non-Microsoft build systems.

Old headers and libraries layout

The existing file layout for the Microsoft GDK is summarized as follows.

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

The Gaming.Desktop.x64 custom MSBuild platforms implement the logic for building the include/lib paths that combine all this content in various ways. If you used CMake or a custom make solution, this logic had to be implemented there as well. For a detailed example, see the April 2025 version of CMakeExample. The old layout is still present in the October 2025 GDK to support both old and new styles. Both the new and old layouts are installed by default. The GDK setup now includes an option to install just the new layout. A future GDK will remove the old layout to reduce the hard drive footprint and overall download size. The current target date for removing the old layout will be one year from the time the October 2025 GDK is released.

New headers and libraries layout

For the October 2025 GDK release, the new layout offers an alternative layout for the headers and libraries that make the platform integration easier and able to accommodate additional platforms over time.

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

Using the new layout with MSBuild custom platforms

The existing Gaming.*.x64 MSBuild platforms use the old layout by default, but you can opt into the new layout by setting the GDKCrossPlatform property.

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

This adds the appropriate include/lib paths to the project instead of the various complex paths that the old layout used. In this new simplified integration, the extension libraries mechanism is no longer used. All content is available at build-time by default in the include/lib paths. The project then needs to link to the additional libraries it uses. Projects that are built on the older GDK project templates should contain statements like the following.

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

For the new layout, the Console_Libs property lists the core required libraries.

Platform	Core libs
Gaming.*.x64	xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib

The project needs to add to AdditionalDependencies the extension libraries it consumes because they’re each ‘opt-in’.

Platform	Core libs
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

The project also needs to copy the additional DLLs it uses into the layout. You can do this either through Custom Build steps that are typical of many DLL library integrations, or by editing the vcxproj or adding a props file to use the ReferenceCopyLocalPaths item group list. The MSBuild below lists all the possible DLLs but individual projects will only need some of these.

  <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 is only set by the Microsoft GDK with XBOX Extensions. As a result, we introduced new environment variables that fully support side-by-side installation of both versions of the Microsoft GDK: GameDKCoreLatest is set by the Microsoft GDK.

Using a Directory.Build.props file

As a way to quickly validate existing GDK Gaming.*.x64 projects by using the new layout, place the following content into a file named Directory.Build.props in your source tree. This opts in to the new layout and includes most or all extension libraries even if not used by the project.

The GDKExtLibNames property isn’t used by the MSBuild rules when building with GDKCrossPlatform set to true. Because it’s already present for building with the older MSBuild rules, it’s used in this props file as a way to opt in to some additional DLLs in the layout.

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

How to update an x64 game to add ARM64

To add ARM64 support to an existing x64 game project, follow these steps:

Use Visual Studio 2022. ARM64 support requires Visual Studio 2022. Visual Studio 2019 isn’t supported for ARM64 builds.
Enable the new layout. Make sure your project uses the new layout by setting GDKCrossPlatform to true in your project file.
Create ARM64 configurations. Copy your existing x64 configurations (such as Debug and Release) to create corresponding ARM64 configurations.
Update library paths. Edit the VC++ Directories for your ARM64 configurations so the library path references lib\arm64 instead of lib\x64.
Update XSAPI library references. Update the link statements for all configurations (not just ARM64) to use Microsoft.Xbox.Services.143.GDK.C.lib instead of Microsoft.Xbox.Services.142.GDK.C.lib.
Update ReferenceCopyLocalPaths. Check for ReferenceCopyLocalPaths usage in your .vcxproj file that might need updating to reference the arm64 bin folder instead of x64.

If the startup of your title fails with error 0xc000007b, it means you have accidentally tried to load an x64 format DLL into your ARM64 process. Check your project system for ReferenceCopyLocalPaths items that might need updating.

Using the new layout with the MSBuild x64 platform

Instead of using the Gaming.Desktop.x64 platform, you can use the stock x64 platform to build for PC. In the old layout, this required adding <Import Project="...\ExtensionLibrary.props"> statements for the Extension Libraries as detailed in Using the x64 platform with the Microsoft Game Development Kit (GDK). In the new layout, the integration instructions are streamlined.

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

Add all required extension libraries to AdditionalDependencies along with the original list.

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

Opt-in extension library DLLs need to be copied into the binary directory as above by using a Custom Build action or by using the ReferenceCopyLocalPaths item group for the final layout. The remaining instructions for PreprocessorDefinitions and handling the .mgc file with image assets remain unchanged.

Using the new layout with CMake

When you use the Microsoft Visual Studio generators with CMake and use the Gaming.*.x64 custom MSBuild platforms, enable the new layout by using the following code.

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

In the CMakeGDKExample, remove the use of VS_GLOBAL_GDKExtLibNames and replace it with the following code (assuming CMake 3.21 or later) to copy the used extension DLLs into the layout.

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
    )

Using the new layout with custom build systems

Building for Windows x64 by using the GDK requires the following.

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

Reading the build edition from an installed file

The new layout doesn’t contain the grdk.ini file. To find the edition information by parsing a file, use grdk.h. Here’s an example in PowerShell that works with older GDK releases as well.

$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

Simplified GDK directory structure (headers and libraries)

Old headers and libraries layout

New headers and libraries layout

Using the new layout with MSBuild custom platforms

Using a Directory.Build.props file

How to update an x64 game to add ARM64

Using the new layout with the MSBuild x64 platform

Using the new layout with CMake

Using the new layout with custom build systems

Reading the build edition from an installed file

​Old headers and libraries layout

​New headers and libraries layout

​Using the new layout with MSBuild custom platforms

​Using a Directory.Build.props file

​How to update an x64 game to add ARM64

​Using the new layout with the MSBuild x64 platform

​Using the new layout with CMake

​Using the new layout with custom build systems

​Reading the build edition from an installed file

Old headers and libraries layout

New headers and libraries layout

Using the new layout with MSBuild custom platforms

Using a Directory.Build.props file

How to update an x64 game to add ARM64

Using the new layout with the MSBuild x64 platform

Using the new layout with CMake

Using the new layout with custom build systems

Reading the build edition from an installed file