> ## 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. # GDKX 標頭和程式庫目錄結構 > 說明 GDKX 標頭和程式庫的新目錄配置。 > [!NOTE] > > 本文所述的目錄結構是 2025 年 10 月 GDK 引進的**簡化 (跨平台) 配置**。 > > 從 2026 年 10 月 GDK 開始，預設會安裝簡化配置。舊版配置仍可作為選擇性且已淘汰的相容性路徑，供需要更多移轉時間的團隊使用。 > > 從 2027 年 4 月 GDK 版本開始，將不再支援舊版配置，並會從安裝程式中移除。在目前版本的 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\ ``` ```text theme={null} GXDK\ gameKit\ Include\ XboxOne\ Scarlett\ Lib\ amd64\ XboxOne\ Scarlett\ ToolKit\ Include\ XboxOne\ Scarlett\ Lib\ amd64\ XboxOne\ Scarlett\ ``` **Gaming.Desktop.x64**、**Gaming.Xbox.Scarlett.x64** 和 **Gaming.Xbox.XboxOne.x64** 自訂 MSBuild 平台實作了建立 include/lib 路徑的所有邏輯，以各種方式組合所有這些內容。如果您使用 CMake 或自訂 make 解決方案，也必須在其中實作此邏輯。如需詳細範例，請參閱 2025 年 4 月版本的 [CMakeExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample)。 2025 年 10 月和 2026 年 4 月的 GDK 版本同時包含簡化配置和舊版配置。從 2026 年 10 月 GDK 開始，安裝程式預設只會安裝簡化配置。舊版配置仍可作為選擇性安裝項目選取，但已淘汰，且不再是建議的開發路徑。從 2027 年 4 月 GDK 版本開始，將不再支援舊版配置，並會從安裝程式中移除。 ## 新的標頭和程式庫配置在 2025 年 10 月的 GDK 版本中，現在為標頭和程式庫提供了替代配置，讓平台整合更容易，並能隨著時間容納更多平台。 ```text theme={null} 251000\ windows\ bin\ arm64 x64\ include\ lib\ arm64 x64\ redist xbox\ bin\ gen8\ gen9\ devpctools\ gen8\ gen9\ x64\ x64\ build\ include\ lib\ redist\ source\ ``` ## 搭配 MSBuild 自訂平台使用新配置現有的 **Gaming.\*.x64** MSBuild 平台預設會使用舊配置，但您可以設定 **GDKCrossPlatform** 屬性來選擇採用新配置。 ```xml theme={null} ... true ``` 這會將適當的 include/lib 路徑新增至專案，而不是舊配置所使用的各種複雜路徑。在這個新的簡化整合中，不再使用延伸程式庫機制。所有內容預設都會在組建時於 include/lib 路徑中提供。接著，專案需要連結其使用的其他程式庫。以較舊 GDK 專案範本建立的專案應包含如下的陳述式。 ```xml theme={null} uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies) ``` 在新配置中，**Console\_Libs** 屬性會列出必要的核心程式庫。 | 平台 | 核心程式庫 | | - | - | | Gaming.\*.x64 | xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib | | Gaming.Xbox.Scarlett.x64 | xgameruntime.lib xgameplatform.lib d3d12\_xs.lib xg\_xs.lib pixevt.lib xmem.lib | | Gaming.Xbox.XboxOne.x64 | xgameruntime.lib xgameplatform.lib d3d12\_x.lib xg\_x.lib pixevt.lib xmem.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} $(GameDKCoreLatest) $(GameDKXboxLatest) ``` > [!NOTE] > > `GameDKLatest` 只會由含 XBOX Extensions 的 Microsoft GDK 設定。因此，我們引進了完全支援並存安裝兩個 Microsoft GDK 版本的新環境變數：`GameDKCoreLatest` 由 Microsoft GDK 設定。`GameDKXboxLatest` 由含 XBOX Extensions 的 Microsoft GDK 設定。 ### 使用 Directory.Build.props 若要使用新配置快速驗證現有的 GDK Gaming.\*.x64 專案，請將下列內容放入原始程式碼樹狀結構中名為 Directory.Build.props 的檔案。這會選擇採用新配置，並納入大部分或所有延伸程式庫，即使專案並未使用它們。 > [!NOTE] > > 當 **GDKCrossPlatform** 設定為 true 進行組建時，MSBuild 規則不會使用 **GDKExtLibNames** 屬性。由於此屬性已存在於使用較舊 MSBuild 規則的組建中，因此在此 props 檔案中用來選擇將某些其他 DLL 加入配置。 ```xml theme={null} true $(GameDKCoreLatest) $(GameDKXboxLatest) Appnotify.lib;winhttp.lib;crypt32.lib;libHttpClient.lib;XCurl.lib;GameChat2.lib;PlayFabCore.lib;PlayFabServices.lib;PlayFabMultiplayer.lib;Party.lib;PartyXboxLive.lib;PlayFabGameSave.lib Microsoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs) Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs) $(AllExtensionLibs);%(AdditionalDependencies) $(AllExtensionLibs);%(XboxExtensionsDependencies) ``` ## 搭配 MSBuild x64 平台使用新配置您可以使用標準 **x64** 平台來為 PC 組建，而不使用 **Gaming.Desktop.x64** 平台。在舊配置中，這需要為延伸程式庫新增 `` 陳述式，詳情請參閱[搭配 Microsoft Game Development Kit (GDK) 使用 x64 平台](https://docs.xbox.com/zh-TW/tools/tools-pc/visualstudio/gr-vs-templates.md#using-the-x64-platform-with-the-microsoft-game-development-kit-gdk)。在新配置中，整合指示已大幅簡化。 ```xml theme={null} $(GameDKCoreLatest) $(GameDKXboxLatest) ``` ```xml theme={null} $(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath) $(GDKCrossPlatformPath)windows\Include;$(IncludePath); $(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath) ``` ```xml theme={null} $(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath) $(GDKCrossPlatformPath)windows\Include;$(IncludePath); $(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath) ``` 將所有必要的延伸程式庫連同原始清單一起新增至 **AdditionalDependencies**。 ```xml theme={null} xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies) ``` 選擇性加入的延伸程式庫 DLL 需要如上所述，使用自訂建置動作或使用 **ReferenceCopyLocalPaths** 項目群組，複製到二進位目錄中以形成最終配置。其餘關於 **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 $>,copy,true> $ $ COMMAND_EXPAND_LISTS ) ``` ## 搭配自訂組建系統使用新配置使用 GDK 為 Windows x64 組建需要下列項目。 ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%windows\include;%INCLUDE% set LIB=%GameDKXboxLatest%windows\lib\x64;%LIB% set PATH=%GameDK%bin;%GameDKXboxLatest%windows\bin\x64;%PATH% ``` 為 XBOX Series X|S (亦即 *Gaming.Xbox.Scarlett.x64*) 組建需要： ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\gen9;%GameDKXboxLatest%xbox\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\gen9;%GameDKXboxLatest%xbox\lib\x64;%LIB% set PATH=%GameDK%bin;%GameDKXboxLatest%xbox\bin\gen9;%GameDKXboxLatest%xbox\bin\x64;%PATH% ``` 為 XBOX One (亦即 *Gaming.Xbox.XboxOne.x64*) 組建需要： ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\gen8;%GameDKXboxLatest%xbox\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\gen8;%GameDKXboxLatest%xbox\lib\x64;%LIB% set PATH=%GameDK%bin;%GameDKXboxLatest%xbox\bin\gen8;%GameDKXboxLatest%xbox\bin\x64;%PATH% ``` ## 將新配置用於 PC 內容工具在主機開發中，某些類型的內容「處理」(cooking) 會在開發電腦上使用 XTF API、XMA2 編碼程式庫和/或自訂 Direct3D 12.X 工具進行。存取此內容需要特定的組建設定：組建同時以 XBOX One 和 XBOX Series X|S 為目標的 PC 工具需要： ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB% set PATH=%GameDK%bin;%PATH% ``` 組建以 XBOX Series X|S 圖形為目標的 PC 工具需要： ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools\gen9;%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\devpctools\gen9;%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB% set PATH=%GameDKXboxLatest%xbox\devpctools\bin\gen9;%GameDK%bin;%PATH% ``` 組建以 XBOX One 圖形為目標的 PC 工具需要： ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools\gen8;%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\devpctools\gen8;%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB% set PATH=%GameDKXboxLatest%xbox\devpctools\bin\gen8;%GameDK%bin;%PATH% ``` ## 從已安裝的檔案讀取組建版本新配置不包含 `grdk.ini` 或 `gxdk.ini` 檔案。若要透過剖析檔案來尋找版本資訊，請使用 `grdk.h` 或 `gxdk.h`。以下是一個 PowerShell 範例，也適用於較舊的 GDK 版本。 ```powershell theme={null} $result = Get-ChildItem -Path $env:GameDKXboxLatest -Filter "gxdk.h" -Recurse if ($result.Count -eq 0) { $result = Get-ChildItem -Path $env:GXDKLatest -Filter "gxdk.h" -Recurse } if ($result.Count -eq 0) { Write-Error "##[error]Failed to find gxdk.h in either GameDKXboxLatest or GXDKLatest" -ErrorAction Stop } $content = Get-Content -Path $result[0].FullName if (-not ([string]$content -match '#define\s+_GXDK_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+_GXDKVER_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+_GXDK_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+_GXDK_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} GXDK" -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) ``` ## 免安裝建置 (BWOI) 在舊配置中原本位於 `\flatDeployment` 下的 MSBuild 自訂組建平台檔案，現在改為位於 `\xbox\build` 下，且路徑已縮短。例如，若要為 VS 2022 設定 BWOI MSBuild 規則資料夾，請使用下列命令。 ```cmd theme={null} rd /q /s c:\temp\msbuildgdk md c:\temp\msbuildgdk xcopy "%VSInstallDir%\MSBuild\Microsoft\VC" /s c:\temp\msbuildgdk xcopy "%GameDKXboxLatest%\xbox\build\VS2022\gen8" c:\temp\msbuildgdk /s xcopy "%GameDKXboxLatest%\xbox\build\VS2022\gen9" c:\temp\msbuildgdk /s xcopy "%GameDKXboxLatest%\xbox\build\VS2022\pc" c:\temp\msbuildgdk /s ``` 接著，在用於 BWOI 的 Directory.Build.props 中，設定屬性以指向此合併的資料夾。 ```xml theme={null} c:\temp\msbuildgdk\v170\ c:\temp\msbuildgdk\v160\ ``` ## Related topics - [GDK 標頭和程式庫目錄結構](https://docs.xbox.com/zh-TW/build/gdk-and-engines/guides/gdk-directory-structure.md) - [XSAPI C 概觀](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/xbox-services-api/live-xsapi-flat-c.md) - [XBOX 主機上的 GameInput](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-xbox.md) - [WdCopySearchOptions](https://docs.xbox.com/zh-TW/reference/remoting/structs/wdcopysearchoptions.md) - [多人遊戲工作階段目錄](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpsd/live-xbox-multiplayer-session-directory.md)