GDK 头文件和库目录结构

在当前版本的 Microsoft Game Development Kit (GDK) 中，布局围绕代码共享进行了优化，并专注于特定平台。此布局的生成集成在很大程度上依赖于将复杂性隐藏在 MSBuild 自定义平台中。新布局的重点在于简化集成、支持不断增加的目标平台列表，并改进对标准 MSBuild 平台和非 Microsoft 生成系统的支持。

旧的头文件和库布局

Microsoft GDK 的现有文件布局概述如下。

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

Gaming.Desktop.x64 自定义 MSBuild 平台实现了构建 include/lib 路径的逻辑，以各种方式组合所有这些内容。如果你使用 CMake 或自定义 make 解决方案，也必须在其中实现此逻辑。有关详细示例，请参阅 2025 年 4 月版本的 CMakeExample。 2025 年 10 月 GDK 中仍保留旧布局，以同时支持旧样式和新样式。默认情况下会同时安装新布局和旧布局。GDK 安装程序现在包含一个仅安装新布局的选项。未来的 GDK 将删除旧布局，以减少硬盘占用空间和总体下载大小。当前删除旧布局的目标日期为 2025 年 10 月 GDK 发布后一年。

新的头文件和库布局

在 2025 年 10 月 GDK 版本中，新布局为头文件和库提供了一种替代布局，使平台集成更加简单，并能够随着时间推移容纳更多平台。

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

将新布局与 MSBuild 自定义平台结合使用

现有的 Gaming.*.x64 MSBuild 平台默认使用旧布局，但你可以通过设置 GDKCrossPlatform 属性来选择使用新布局。

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

这会将相应的 include/lib 路径添加到项目中，而不是使用旧布局所用的各种复杂路径。在这种新的简化集成中，不再使用扩展库机制。默认情况下，所有内容在生成时都可以通过 include/lib 路径使用。然后，项目需要链接到其使用的其他库。基于较旧 GDK 项目模板生成的项目应包含如下语句。

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

对于新布局，Console_Libs 属性列出了所需的核心库。

平台	核心库
Gaming.*.x64	xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.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，但各个项目只需要其中的一部分。

  <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 仅由带有 XBOX 扩展的 Microsoft GDK 设置。因此，我们引入了新的环境变量，完全支持两个版本的 Microsoft GDK 并行安装：GameDKCoreLatest 由 Microsoft GDK 设置。

使用 Directory.Build.props 文件

为了使用新布局快速验证现有的 GDK Gaming.*.x64 项目，请将以下内容放入源代码树中名为 Directory.Build.props 的文件中。这会选择使用新布局，并包含大部分或全部扩展库，即使项目未使用这些库。

在将 GDKCrossPlatform 设置为 true 进行生成时，MSBuild 规则不使用 GDKExtLibNames 属性。由于该属性已存在于使用旧 MSBuild 规则的生成中，因此在此 props 文件中使用它来选择在布局中加入一些额外的 DLL。

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

如何更新 x64 游戏以添加 ARM64 支持

要为现有 x64 游戏项目添加 ARM64 支持，请按照以下步骤操作：

使用 Visual Studio 2022。 ARM64 支持需要 Visual Studio 2022。Visual Studio 2019 不支持 ARM64 生成。
启用新布局。 在项目文件中将 GDKCrossPlatform 设置为 true，确保项目使用新布局。
创建 ARM64 配置。 复制现有的 x64 配置(例如 Debug 和 Release)，以创建相应的 ARM64 配置。
更新库路径。 编辑 ARM64 配置的 VC++ 目录，使库路径引用 lib\arm64 而不是 lib\x64。
更新 XSAPI 库引用。 更新_所有_配置(而不仅仅是 ARM64)的链接语句，使用 Microsoft.Xbox.Services.143.GDK.C.lib 而不是 Microsoft.Xbox.Services.142.GDK.C.lib。
更新 ReferenceCopyLocalPaths。 检查 .vcxproj 文件中的 ReferenceCopyLocalPaths 用法，可能需要将其更新为引用 arm64 bin 文件夹而不是 x64。

如果游戏启动失败并出现错误 0xc000007b，则表示你意外尝试将 x64 格式的 DLL 加载到 ARM64 进程中。请检查项目系统中可能需要更新的 ReferenceCopyLocalPaths 项。

将新布局与 MSBuild x64 平台结合使用

可以使用标准 x64 平台代替 Gaming.Desktop.x64 平台来为 PC 生成。在旧布局中，这需要为扩展库添加 <Import Project="...\ExtensionLibrary.props"> 语句，详见“将 x64 平台与 Microsoft Game Development Kit (GDK) 结合使用”。在新布局中，集成说明得到了简化。

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

将所有必需的扩展库与原始列表一起添加到 AdditionalDependencies 中。

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

选择加入的扩展库 DLL 需要按上述方式，通过自定义生成操作或使用 ReferenceCopyLocalPaths 项组复制到二进制目录中，以形成最终布局。有关 PreprocessorDefinitions 以及处理带有图像资产的 .mgc 文件的其余说明保持不变。

将新布局与 CMake 结合使用

将 Microsoft Visual Studio 生成器与 CMake 结合使用并使用 Gaming.*.x64 自定义 MSBuild 平台时，请使用以下代码启用新布局。

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

在 CMakeGDKExample 中，删除 VS_GLOBAL_GDKExtLibNames 的使用，并将其替换为以下代码(假设使用 CMake 3.21 或更高版本)，以将使用的扩展 DLL 复制到布局中。

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
    )

将新布局与自定义生成系统结合使用

使用 GDK 为 Windows x64 生成需要以下设置。

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

从已安装的文件中读取生成版本

新布局不包含 grdk.ini 文件。要通过解析文件查找版本信息，请使用 grdk.h。以下是一个 PowerShell 示例，它也适用于较旧的 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

旧的头文件和库布局

新的头文件和库布局

将新布局与 MSBuild 自定义平台结合使用

使用 Directory.Build.props 文件

如何更新 x64 游戏以添加 ARM64 支持

将新布局与 MSBuild x64 平台结合使用

将新布局与 CMake 结合使用

将新布局与自定义生成系统结合使用

从已安装的文件中读取生成版本

​旧的头文件和库布局

​新的头文件和库布局

​将新布局与 MSBuild 自定义平台结合使用

​使用 Directory.Build.props 文件

​如何更新 x64 游戏以添加 ARM64 支持

​将新布局与 MSBuild x64 平台结合使用

​将新布局与 CMake 结合使用

​将新布局与自定义生成系统结合使用

​从已安装的文件中读取生成版本

旧的头文件和库布局

新的头文件和库布局

将新布局与 MSBuild 自定义平台结合使用

使用 Directory.Build.props 文件

如何更新 x64 游戏以添加 ARM64 支持

将新布局与 MSBuild x64 平台结合使用

将新布局与 CMake 结合使用

将新布局与自定义生成系统结合使用

从已安装的文件中读取生成版本