> ## 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 头文件和库目录结构 > 介绍 GDKX 头文件和库的新目录布局。 > [!NOTE] > > 本文介绍的目录结构是随 2025 年 10 月 GDK 引入的**简化（跨平台）布局**。 > > 从 2026 年 10 月 GDK 开始，默认安装简化布局。旧版布局仍作为一个可选的、已弃用的兼容途径提供，供需要更多迁移时间的团队使用。 > > 从 2027 年 4 月 GDK 版本开始，旧版布局将不再受支持，并将从安装程序中移除。在当前版本的 Microsoft Game Development Kit (GDK) 中，布局围绕代码共享进行了优化，并专注于特定平台。此布局的构建集成在很大程度上依赖于将复杂性隐藏在 MSBuild 自定义平台中。新布局的重点在于简化集成、支持不断增加的目标平台，以及改进对标准 MSBuild 平台和非 Microsoft 构建系统的支持。 ## 旧的头文件和库布局 Microsoft GDK 现有的文件布局概括如下。 ```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\ ``` **Gaming.Desktop.x64**、**Gaming.Xbox.Scarlett.x64** 和 **Gaming.Xbox.XboxOne.x64** 自定义 MSBuild 平台实现了构建 include/lib 路径的全部逻辑，以各种方式组合所有这些内容。如果你使用 CMake 或自定义 make 解决方案，则也必须在其中实现此逻辑。有关详细示例，请参阅 2025 年 4 月版本的 [CMakeExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample)。 2025 年 10 月和 2026 年 4 月 GDK 版本同时包含简化布局和旧版布局。从 2026 年 10 月 GDK 开始，安装程序默认仅安装简化布局。旧版布局仍可作为可选安装项进行选择，但它已被弃用，不再是推荐的开发途径。从 2027 年 4 月 GDK 版本开始，旧版布局将不再受支持，并将从安装程序中移除。 ## 新的头文件和库布局 2025 年 10 月 GDK 版本为头文件和库提供了一种替代布局，使平台集成更加容易，并能够随着时间的推移容纳更多平台。 ```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\ ``` ## 在 MSBuild 自定义平台中使用新布局现有的 **Gaming.\*.x64** MSBuild 平台默认使用旧布局，但你可以通过设置 **GDKCrossPlatform** 属性选择使用新布局。 ```xml theme={null} ... true ``` 这样会将相应的 include/lib 路径添加到项目中，而不是使用旧布局所用的各种复杂路径。在这种新的简化集成中，不再使用扩展库机制。默认情况下，所有内容在构建时都可通过 include/lib 路径获得。然后，项目需要链接到其使用的其他库。基于较旧 GDK 项目模板构建的项目应包含如下语句。 ```xml theme={null} uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies) ``` 对于新布局，**Console\_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 | 项目需要将其使用的扩展库添加到 **AdditionalDependencies** 中，因为每个扩展库都是“选择加入”的。 | 平台 | 核心库 | | - | - | | 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 | 项目还需要将其使用的其他 DLL 复制到布局中。这可以通过许多 DLL 库集成中常用的自定义生成步骤来完成，也可以通过编辑 vcxproj 或添加 props 文件来使用 **ReferenceCopyLocalPaths** 项组列表来完成。下面的 MSBuild 列出了所有可能的 DLL，但各个项目只需要其中的一部分。 ```xml theme={null} $(GameDKCoreLatest) $(GameDKXboxLatest) ``` > [!NOTE] > > `GameDKLatest` 仅由 Microsoft GDK with XBOX Extensions 设置。因此，我们引入了新的环境变量，全面支持两个版本的 Microsoft GDK 并行安装：`GameDKCoreLatest` 由 Microsoft GDK 设置，`GameDKXboxLatest` 由 Microsoft GDK with XBOX Extensions 设置。 ### 使用 Directory.Build.props 若要使用新布局快速验证现有的 GDK Gaming.\*.x64 项目，请将以下内容放入源代码树中名为 Directory.Build.props 的文件中。这会选择使用新布局，并包含大部分或全部扩展库，即使项目并未使用它们。 > [!NOTE] > > 在将 **GDKCrossPlatform** 设置为 true 进行构建时，MSBuild 规则不会使用 **GDKExtLibNames** 属性。由于该属性在使用较旧 MSBuild 规则构建时已经存在，因此在此 props 文件中用它来选择将某些其他 DLL 加入布局。 ```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.lib Microsoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs) Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs) $(AllExtensionLibs);%(AdditionalDependencies) $(AllExtensionLibs);%(XboxExtensionsDependencies) ``` ## 在 MSBuild x64 平台中使用新布局你可以使用标准 **x64** 平台（而不是 **Gaming.Desktop.x64** 平台）来构建 PC 版本。在旧布局中，这需要为扩展库添加 `` 语句，详见[在 Microsoft Game Development Kit (GDK) 中使用 x64 平台](https://docs.xbox.com/zh-CN/tools/tools-pc/visualstudio/gr-vs-templates.md#using-the-x64-platform-with-the-microsoft-game-development-kit-gdk)。在新布局中，集成说明得到了简化。 ```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) ``` 将所有必需的扩展库与原始列表一起添加到 **AdditionalDependencies** 中。 ```xml theme={null} xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies) ``` 需要按照上文所述，使用自定义生成操作或 **ReferenceCopyLocalPaths** 项组，将选择加入的扩展库 DLL 复制到二进制目录中，以形成最终布局。关于 **PreprocessorDefinitions** 以及处理带有图像资产的 .mgc 文件的其余说明保持不变。 ## 在 CMake 中使用新布局在 CMake 中使用 Microsoft Visual Studio 生成器并使用 **Gaming.\*.x64** 自定义 MSBuild 平台时，可通过以下方式启用新布局。 ```text theme={null} set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true") ``` 在 [CMakeGDKExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeGDKExample) 中，删除对 `VS_GLOBAL_GDKExtLibNames` 的使用，并将其替换为以下内容（假定使用 CMake 3.21 或更高版本），以将所用的扩展 DLL 复制到布局中。 ```text theme={null} add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD COMMAND ${CMAKE_COMMAND} -E $>,copy,true> $ $ COMMAND_EXPAND_LISTS ) ``` ## 在自定义构建系统中使用新布局使用 GDK 构建 Windows x64 版本需要以下设置。 ```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% ``` 构建 XBOX Series X|S（即 *Gaming.Xbox.Scarlett.x64*）版本需要： ```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% ``` 构建 XBOX One（即 *Gaming.Xbox.XboxOne.x64*）版本需要： ```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% ``` ## 将新布局用于 PC 内容工具对于主机开发，某些类型的内容“烘焙”是在开发 PC 上使用 XTF API、XMA2 编码库和/或自定义 Direct3D 12.X 工具完成的。访问这些内容需要特定的构建设置：构建同时面向 XBOX One 和 XBOX Series X|S 的 PC 工具需要： ```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% ``` 构建面向 XBOX Series X|S 图形的 PC 工具需要： ```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% ``` 构建面向 XBOX One 图形的 PC 工具需要： ```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% ``` ## 从已安装的文件中读取构建版本新布局不包含 `grdk.ini` 或 `gxdk.ini` 文件。若要通过解析文件来查找版本信息，请使用 `grdk.h` 或 `gxdk.h`。下面是一个 PowerShell 示例，它同样适用于较旧的 GDK 版本。 ```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) ``` ## 无需安装构建 (BWOI) 在旧布局中原本位于 `\flatDeployment` 下的 MSBuild 自定义构建平台文件，现在位于 `\xbox\build` 下，路径更短。例如，若要为 VS 2022 设置 BWOI MSBuild 规则文件夹，请使用以下命令。 ```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 ``` 然后，在用于 BWOI 的 Directory.Build.props 中设置属性，使其指向此合并后的文件夹。 ```xml theme={null} c:\temp\msbuildgdk\v170\ c:\temp\msbuildgdk\v160\ ``` ## Related topics - [GDK 头文件和库目录结构](https://docs.xbox.com/zh-CN/build/gdk-and-engines/guides/gdk-directory-structure.md) - [XSAPI C 概述](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/xbox-services-api/live-xsapi-flat-c.md) - [XBOX 主机上的 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-xbox.md) - [WdCopySearchOptions](https://docs.xbox.com/zh-CN/reference/remoting/structs/wdcopysearchoptions.md) - [目录 (xbdir.exe)](https://docs.xbox.com/zh-CN/tools/tools-console/commandlinetools/xbdir.md)