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

# GDK 头文件和库目录结构

> 在 MSBuild、CMake 和自定义生成中通过 GDKCrossPlatform 选择使用简化的 2025 年 10 月 GDK 目录布局，并为 x64 游戏添加 ARM64 支持。

在当前版本的 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\
```

**Gaming.Desktop.x64** 自定义 MSBuild 平台实现了构建 include/lib 路径的逻辑，以各种方式组合所有这些内容。如果你使用 CMake 或自定义 make 解决方案，也必须在其中实现此逻辑。有关详细示例，请参阅 2025 年 4 月版本的 [CMakeExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample)。

2025 年 10 月 GDK 中仍保留旧布局，以同时支持旧样式和新样式。默认情况下会同时安装新布局和旧布局。GDK 安装程序现在包含一个仅安装新布局的选项。未来的 GDK 将删除旧布局，以减少硬盘占用空间和总体下载大小。当前删除旧布局的目标日期为 2025 年 10 月 GDK 发布后一年。

## 新的头文件和库布局

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

```text theme={null}
251000\
    windows\
        bin\
            arm64
            x64\
        include\
        lib\
            arm64
            x64\
        redist
```

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

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

```xml theme={null}
<PropertyGroup Label="Globals">
...
  <GDKCrossPlatform>true</GDKCrossPlatform>
</PropertyGroup>
```

这会将相应的 include/lib 路径添加到项目中，而不是使用旧布局所用的各种复杂路径。

在这种新的简化集成中，不再使用扩展库机制。默认情况下，所有内容在生成时都可以通过 include/lib 路径使用。

然后，项目需要链接到其使用的其他库。基于较旧 GDK 项目模板生成的项目应包含如下语句。

```xml theme={null}
<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，但各个项目只需要其中的一部分。

```xml theme={null}
  <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>
```

> [!NOTE]
>
> `GameDKLatest` 仅由带有 XBOX 扩展的 Microsoft GDK 设置。因此，我们引入了新的环境变量，完全支持两个版本的 Microsoft GDK 并行安装：`GameDKCoreLatest` 由 Microsoft GDK 设置。

### 使用 Directory.Build.props 文件

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

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

```xml theme={null}
<?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 支持，请按照以下步骤操作：

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

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

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

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

在新布局中，集成说明得到了简化。

```xml theme={null}
  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>
```

```xml theme={null}
<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>
```

```xml theme={null}
<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** 中。

```xml theme={null}
<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 平台时，请使用以下代码启用新布局。

```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 $<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 生成需要以下设置。

```cmd theme={null}
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 版本。

```powershell theme={null}
$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)
```


## Related topics

- [WdCopySearchOptions](https://docs.xbox.com/zh-CN/reference/remoting/structs/wdcopysearchoptions.md)
- [使用 2025 年 10 月 GDK 实现 Game Saves](https://docs.xbox.com/zh-CN/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [Matchmaking SDK 快速入门](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/matchmaking/quickstart-client-sdk.md)
- [Lobby SDK 快速入门](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/lobby-getting-started.md)
- [目录 (xbdir.exe)](https://docs.xbox.com/zh-CN/tools/tools-console/commandlinetools/xbdir.md)