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

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

在当前版本的 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 方案,也必须在其中实现相同的逻辑。详细示例参见 CMakeExample 的 2025 年 4 月版本。旧布局仍然会保留在 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 路径,取代旧布局所使用的多种复杂路径。在这一新的简化集成中,不再使用扩展库(extension libraries)机制。默认情况下,所有内容都可以在构建时通过 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 库集成常用的 Custom Build 步骤完成,也可以通过编辑 vcxproj 或添加 props 文件,使用 ReferenceCopyLocalPaths item 组列表来完成。下面的 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 Extensions 的 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。ARM64 构建不支持 Visual Studio 2019。
启用新布局。 通过在项目文件中将 GDKCrossPlatform 设为 true,确保项目使用新布局。
创建 ARM64 配置。 复制现有的 x64 配置(如 Debug 和 Release)以创建对应的 ARM64 配置。
更新库路径。 编辑 ARM64 配置的 VC++ Directories,使库路径引用 lib\arm64 而不是 lib\x64。
更新 XSAPI 库引用。 更新所有配置(不只是 ARM64)的链接语句,使其使用 Microsoft.Xbox.Services.143.GDK.C.lib 而不是 Microsoft.Xbox.Services.142.GDK.C.lib。
更新 ReferenceCopyLocalPaths。 检查 .vcxproj 中的 ReferenceCopyLocalPaths 用法,可能需要更新为引用 arm64 而非 x64 的 bin 目录。

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

结合 MSBuild x64 平台使用新布局

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

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

按上文所述,通过 Custom Build 动作或使用 ReferenceCopyLocalPaths item 组,将可选启用的扩展库 DLL 拷贝到二进制目录中,以形成最终布局。 PreprocessorDefinitions 以及处理带图像资源的 .mgc 文件的其余说明保持不变。

结合 CMake 使用新布局

使用 CMake 的 Microsoft Visual Studio 生成器结合 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 使用新布局

结合自定义构建系统使用新布局

从已安装的文件中读取构建版本