> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GDKX header and library directory structure
> Describes the new directory layout for GDKX headers and libraries.
> [!NOTE]
>
> The directory structure described in this article is the **simplified (cross-platform) layout** introduced with the October 2025 GDK.
>
> Beginning with the October 2026 GDK, the simplified layout is installed by default. The legacy layout remains available as an optional, deprecated compatibility path for teams that need additional migration time.
>
> The legacy layout will no longer be supported and will be removed from the installer starting with the April 2027 GDK release.
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.
```text theme={null}
251000\
GRDK\
ExtensionLibraries\
Xbox.Services.API.C\
ExtensionLibrary.props
DesignTime\CommonConfiguration\Neutral\
Include\
Lib\
Redist\
...
GameKit\
Include\
Lib\
amd64\
```
```text theme={null}
GXDK\
gameKit\
Include\
XboxOne\
Scarlett\
Lib\
amd64\
XboxOne\
Scarlett\
ToolKit\
Include\
XboxOne\
Scarlett\
Lib\
amd64\
XboxOne\
Scarlett\
```
The **Gaming.Desktop.x64**, **Gaming.Xbox.Scarlett.x64**, and **Gaming.Xbox.XboxOne.x64** custom MSBuild platforms implement all 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](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample).
The October 2025 and April 2026 GDK releases include both the simplified and legacy layouts. Beginning with the October 2026 GDK, setup installs only the simplified layout by default. The legacy layout can still be selected as an optional installation, but it is deprecated and is no longer the recommended development path.
The legacy layout will no longer be supported and will be removed from the installer starting with the April 2027 GDK release.
## New headers and libraries layout
For the October 2025 GDK release, it now offers an alteranative layout for the headers and libraries that make the platform integration much easier and able to accommodate additional platforms over time.
```text theme={null}
251000\
windows\
bin\
arm64
x64\
include\
lib\
arm64
x64\
redist
xbox\
bin\
gen8\
gen9\
devpctools\
gen8\
gen9\
x64\
x64\
build\
include\
lib\
redist\
source\
```
## Using the new layout with MSBuild custom platforms
The existing **Gaming.\*.x64** MSBuild platforms will use the old layout by default, but you can opt into the new layout by setting the **GDKCrossPlatform** property.
```xml theme={null}
...
true
```
This results in the appropriate include/lib paths being added to the project instead of the various complex paths were used by the old layout.
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 makes use of. Projects that are built on the older GDK project templates should contain statements like the following.
```xml theme={null}
uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies)
```
For the new layout the **Console\_Libs** property will list the core required libraries.
| Platform | Core libs |
| - | - |
| Gaming.\*.x64 | xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib |
| Gaming.Xbox.Scarlett.x64 | xgameruntime.lib xgameplatform.lib d3d12\_xs.lib xg\_xs.lib pixevt.lib xmem.lib |
| Gaming.Xbox.XboxOne.x64 | xgameruntime.lib xgameplatform.lib d3d12\_x.lib xg\_x.lib pixevt.lib xmem.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. This can be done either via 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.
```xml theme={null}
$(GameDKCoreLatest)$(GameDKXboxLatest)
```
> [!NOTE]
>
> `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. `GameDKXboxLatest` is set by the Microsoft GDK with XBOX Extensions.
### Using a Directory.Build.props
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.
> [!NOTE]
>
> 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 is used in this props file as a way to opt in to some additional DLLs in the layout.
```xml theme={null}
true$(GameDKCoreLatest)$(GameDKXboxLatest)Appnotify.lib;winhttp.lib;crypt32.lib;libHttpClient.lib;XCurl.lib;GameChat2.lib;PlayFabCore.lib;PlayFabServices.lib;PlayFabMultiplayer.lib;Party.lib;PartyXboxLive.lib;PlayFabGameSave.libMicrosoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs)Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs)$(AllExtensionLibs);%(AdditionalDependencies)$(AllExtensionLibs);%(XboxExtensionsDependencies)
```
## 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 `` statements for the Extension Libraries as detailed in the [Using the x64 platform with the Microsoft Game Development Kit (GDK)](https://learn.microsoft.com/en-us/gaming/gdk/docs/tools/tools-pc/visualstudio/gr-vs-templates#using-the-x64-platform-with-the-microsoft-game-development-kit-gdk).
In the new layout, the integration instructions are streamlined.
```xml theme={null}
$(GameDKCoreLatest)$(GameDKXboxLatest)
```
```xml theme={null}
$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)$(GDKCrossPlatformPath)windows\Include;$(IncludePath);$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)
```
```xml theme={null}
$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)$(GDKCrossPlatformPath)windows\Include;$(IncludePath);$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)
```
Add all required extension libraires to **AdditionalDependencies** along with the original list.
```xml theme={null}
xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(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 using the Microsoft Visual Studio generators with CMake and using the **Gaming.\*.x64** custom MSBuild platforms, the new layout is enabled with the following.
```text theme={null}
set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true")
```
In the [CMakeGDKExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeGDKExample), remove the use of `VS_GLOBAL_GDKExtLibNames` and replace it with the following (assuming CMake 3.21 or later) to copy the used extension DLLs into the layout.
```text theme={null}
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
COMMAND ${CMAKE_COMMAND} -E $>,copy,true>
$ $
COMMAND_EXPAND_LISTS
)
```
## Using the new layout with custom build systems
Building for Windows x64 by using the GDK requires the following.
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%windows\include;%INCLUDE%
set LIB=%GameDKXboxLatest%windows\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKXboxLatest%windows\bin\x64;%PATH%
```
Building for XBOX Series X|S (a.k.a. *Gaming.Xbox.Scarlett.x64*) requires:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\gen9;%GameDKXboxLatest%xbox\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\gen9;%GameDKXboxLatest%xbox\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKXboxLatest%xbox\bin\gen9;%GameDKXboxLatest%xbox\bin\x64;%PATH%
```
Building for XBOX One (a.k.a. *Gaming.Xbox.XboxOne.x64*) requires:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\gen8;%GameDKXboxLatest%xbox\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\gen8;%GameDKXboxLatest%xbox\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKXboxLatest%xbox\bin\gen8;%GameDKXboxLatest%xbox\bin\x64;%PATH%
```
## Using the new layout for PC content tools
For console development, some kinds of content 'cooking' take place on the development PC using XTF APIs, the XMA2 encoding library, and/or custom Direct3D 12.X tooling. Accessing this content requires specific build setup:
Building PC tools that target both XBOX One and XBOX Series X|S requires:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB%
set PATH=%GameDK%bin;%PATH%
```
Building PC tools that target XBOX Series X|S graphics requires:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools\gen9;%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\devpctools\gen9;%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB%
set PATH=%GameDKXboxLatest%xbox\devpctools\bin\gen9;%GameDK%bin;%PATH%
```
Building PC tools that target XBOX One graphics requires:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools\gen8;%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\devpctools\gen8;%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB%
set PATH=%GameDKXboxLatest%xbox\devpctools\bin\gen8;%GameDK%bin;%PATH%
```
## Reading build edition from an installed file
The new layout does not contain the `grdk.ini` or `gxdk.ini` files. To find the edition information by parsing a file, use `grdk.h` or `gxdk.h`.
Here is an example in PowerShell that works with older GDK releases as well.
```powershell theme={null}
$result = Get-ChildItem -Path $env:GameDKXboxLatest -Filter "gxdk.h" -Recurse
if ($result.Count -eq 0)
{
$result = Get-ChildItem -Path $env:GXDKLatest -Filter "gxdk.h" -Recurse
}
if ($result.Count -eq 0)
{
Write-Error "##[error]Failed to find gxdk.h in either GameDKXboxLatest or GXDKLatest" -ErrorAction Stop
}
$content = Get-Content -Path $result[0].FullName
if (-not ([string]$content -match '#define\s+_GXDK_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+_GXDKVER_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+_GXDK_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+_GXDK_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} GXDK" -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)
```
## Build without install (BWOI)
The MSBuild custom build platform files that were originally located under `\flatDeployment` in the old layout are now located under `\xbox\build` with shortened paths.
For example, to setup a BWOI MSBuild rule folder for VS 2022, use these commands.
```cmd theme={null}
rd /q /s c:\temp\msbuildgdk
md c:\temp\msbuildgdk
xcopy "%VSInstallDir%\MSBuild\Microsoft\VC" /s c:\temp\msbuildgdk
xcopy "%GameDKXboxLatest%\xbox\build\VS2022\gen8" c:\temp\msbuildgdk /s
xcopy "%GameDKXboxLatest%\xbox\build\VS2022\gen9" c:\temp\msbuildgdk /s
xcopy "%GameDKXboxLatest%\xbox\build\VS2022\pc" c:\temp\msbuildgdk /s
```
Then in your Directory.Build.props used for BWOI set the properties to point to this combined folder.
```xml theme={null}
c:\temp\msbuildgdk\v170\c:\temp\msbuildgdk\v160\
```
## Related topics
- [GDK header and library directory structure](https://docs.xbox.com/build/gdk-and-engines/guides/gdk-directory-structure.md)
- [WdCopySearchOptions](https://docs.xbox.com/reference/remoting/structs/wdcopysearchoptions.md)
- [D3D12_SERIALIZED_RAYTRACING_ACCELERATION_STRUCTURE_HEADER](https://docs.xbox.com/reference/graphics/d3d12/structs/d3d12_serialized_raytracing_acceleration_structure_header_public.md)
- [GAMEPAD_REPORT structure](https://docs.xbox.com/reference/tools/xtf/xtfinput/structures/GAMEPAD_REPORT-xtfinput-xbox-windows-t.md)
- [RemoveDirectory](https://docs.xbox.com/reference/tools/xtf/xtffileio/classes/IXtfFileIOClient/methods/removedirectory-ixtffileioclient-xtffileio-xbox-microsoft-m.md)