> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 简化的 GDK 目录结构(头文件与库)

> 为 MSBuild、CMake 与自定义构建启用 2025 年 10 月 GDK 中简化的目录布局(通过 GDKCrossPlatform),并将 ARM64 加入你的 x64 作品。

<Note>
  本文所描述的 Microsoft Game Development Kit(GDK)头文件与库的新布局,预计将在 2025 年 10 月 GDK 中发布。如果你对该 GDK 的预览版感兴趣,请联系你的 Microsoft 客户经理。
</Note>

在当前版本的 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 方案,也必须在其中实现相同的逻辑。详细示例参见 [CMakeExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample) 的 2025 年 4 月版本。

旧布局仍然会保留在 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 路径,取代旧布局所使用的多种复杂路径。

在这一新的简化集成中,不再使用扩展库(extension libraries)机制。默认情况下,所有内容都可以在构建时通过 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 库集成常用的 Custom Build 步骤完成,也可以通过编辑 vcxproj 或添加 props 文件,使用 **ReferenceCopyLocalPaths** item 组列表来完成。下面的 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 Extensions 的 Microsoft GDK 设置。因此,我们引入了新的环境变量,可完整支持两个版本的 Microsoft GDK 并存安装:`GameDKCoreLatest` 由 Microsoft GDK 设置。
</Note>

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

要快速使用新布局验证现有的 GDK Gaming.\*.x64 项目,可将以下内容放入源码树中名为 Directory.Build.props 的文件。这会启用新布局,并包含大多数或全部扩展库,即使项目并未使用它们。

<Note>
  使用 **GDKCrossPlatform** 设为 true 构建时,MSBuild 规则不会使用 **GDKExtLibNames** 属性。但由于该属性已经存在于旧 MSBuild 规则中,本 props 文件将其用作在布局中启用一些额外 DLL 的方式。
</Note>

```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。ARM64 构建不支持 Visual Studio 2019。
2. **启用新布局。** 通过在项目文件中将 `GDKCrossPlatform` 设为 `true`,确保项目使用新布局。
3. **创建 ARM64 配置。** 复制现有的 x64 配置(如 Debug 和 Release)以创建对应的 ARM64 配置。
4. **更新库路径。** 编辑 ARM64 配置的 VC++ Directories,使库路径引用 `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` 而非 `x64` 的 bin 目录。

<Note>
  如果作品启动时失败并报错 0xc000007b,意味着你意外地将 x64 格式的 DLL 加载到了 ARM64 进程中。请检查项目系统中的 `ReferenceCopyLocalPaths` 项是否需要更新。
</Note>

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

除了使用 **Gaming.Desktop.x64** 平台之外,你也可以使用标准的 **x64** 平台构建 PC。在旧布局中,这需要按照《Using the x64 platform with the Microsoft Game Development Kit (GDK)》中的说明为扩展库添加 `<Import Project="...\ExtensionLibrary.props">` 语句。

在新布局中,集成指令得到了精简。

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

按上文所述,通过 Custom Build 动作或使用 **ReferenceCopyLocalPaths** item 组,将可选启用的扩展库 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 $<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

- [XMA2 编码器工具](/zh-CN/build/console-features/audio/tools/xma2encodertool.md)
- [xCurl 概述](/zh-CN/build/console-features/networking/web-requests/intro-xcurl.md)
- [将 GDK 集成到 4.26 之前的 Unreal Engine 项目](/zh-CN/build/gdk-and-engines/unreal/unreal-legacy.md)
- [MicrosoftGame.config 本地化](/zh-CN/build/core-features/common/game-config/MicrosoftGameConfig-Localization.md)
- [开发一款新的 GDK 游戏](/zh-CN/home/build-first-title/developing-new-titles.md)