簡化的 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 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

若要將 ARM64 支援新增至現有的 x64 遊戲專案，請依照下列步驟操作：

使用 Visual Studio 2022。 ARM64 支援需要 Visual Studio 2022。ARM64 組建不支援 Visual Studio 2019。
啟用新配置。 在專案檔中將 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 平台來為 PC 組建，而不使用 Gaming.Desktop.x64 平台。在舊配置中，這需要為延伸程式庫新增 <Import Project="...\ExtensionLibrary.props"> 陳述式，詳情請參閱「搭配 Microsoft Game Development Kit (GDK) 使用 x64 平台」。在新配置中，整合指示已大幅簡化。

  <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 使用新配置

當您搭配 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 使用新配置

搭配自訂組建系統使用新配置

從已安裝的檔案讀取組建版本