> ## 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 與自訂 C/C++ 引擎整合 > 將 GDK、Gaming Runtime Services (GRTS) 和 XSAPI 整合到沒有內建 GDK 支援的 C/C++ 引擎中，以便在 PC 版和 XBOX 版 Microsoft Store 上發行。如果您正在準備將遊戲發行至 PC 版 Microsoft Store，而且遊戲使用的是沒有內建 GDK 支援的 C/C++ 架構引擎，請使用本主題。 * [在 Partner Center 中建立產品](#creating-a-product-in-partner-center) * [將 GDK 整合到 C/C++ 遊戲中](#integrating-the-gdk-into-c-c-games) * [在遊戲中測試 XBOX services](#testing-xbox-services-in-your-game) * [發行](#publishing) ## 在 Partner Center 中建立產品在將遊戲發行至 Microsoft Store 之前，您必須先在 Partner Center 中建立已啟用 XBOX services 的產品。如需 Partner Center 的詳細資訊，請參閱[在 Partner Center 中設定應用程式或遊戲 (適用於受管理的合作夥伴)](/zh-TW/services/xbox-services/fundamentals/portal-config/live-setup-partner-center-partners)。 ## 將 GDK 整合到 C/C++ 遊戲中若要將 GDK 整合到 C/C++ 遊戲中，遊戲需要 4 項內容： 1. 描述 API 簽章和資料結構的 GDK 和 XBOX Services API (XSAPI) *標頭*。 2. 告知連結器如何解析對所匯出 GDK 函式之外部參考的\_匯入程式庫\_。 3. 告知連結器如何解析對所匯出 XSAPI DLL 函式之外部參考的 XSAPI 靜態程式庫或\_匯入程式庫\_。 * XSAPI 同時提供靜態和動態兩種形式。如需詳細資訊，請參閱下表，並從靜態或動態中擇一使用。 4. 實際包含 GDK 和 XSAPI 函式執行階段實作的\_動態連結程式庫\_ (如果使用動態版本的 XSAPI)。若要讓遊戲與重要的 XBOX 生態系統體驗整合，遊戲需要與兩個元件互動：Gaming Runtime Services (GRTS) 和 XSAPI。以下是非受控遊戲所需的檔案： | 元件 | GRTS (僅限動態) | XSAPI (動態) | XSAPI (靜態) | | - | - | - | - | | 標頭 | GRTS 標頭：XUser、XGameSave、XGameUI 等 (來自 GDK) | XSAPI 標頭：profile\_c.h、achievements\_c.h 等 (來自 GDK) | XSAPI 標頭：profile\_c.h、achievements\_c.h 等 (來自 GDK) | | 匯入程式庫 | xgameruntime.lib (來自 GDK) | Microsoft.Xbox.Services.GDK.C.Thunks.lib (來自 GDK) | Microsoft.Xbox.Services.142.GDK.C.lib (來自 GDK) | | 動態連結程式庫 | xgameruntime.dll 和其他幾個 dll (由 GRTS 安裝於 system32) | Microsoft.Xbox.Services.GDK.C.Thunks.dll (來自 GDK，需要包含在遊戲套件中) | 不需要 | 對於使用外掛程式架構、功能分散於多個 DLL 的遊戲，我們建議並支援使用 `Thunks.dll` 將 XSAPI 整合到這些 DLL 中。此方法在 PC 和 XBOX 平台上都能可靠運作。當您將 XSAPI 靜態連結到多個 DLL 時，每個 DLL 都會維護自己的全域狀態複本。因此，在某個 DLL 中呼叫 `XblInitialize` 並不會在其他 DLL 中初始化 XSAPI。在具有個別靜態執行個體的 DLL 之間共用 XSAPI 控制代碼，可能會導致當機或無法預期的行為。 `Thunks.dll` 透過提供單一共用的 XSAPI 執行個體及其狀態來解決此問題。這可避免重複，並確保所有 DLL 的行為一致。雖然技術上可以將 XSAPI 靜態連結到一個 DLL 並匯出符號，但此方法較為複雜且容易出錯。使用 `Thunks.dll` 更簡單、更安全，而且受到完整支援。 ### 將 Gaming Runtime Services 和 XSAPI 的需求新增至您的專案下列步驟概述您需要對專案進行的變更，以確保專案具備使用 Gaming Runtime Services 和 XSAPI 的所有需求。 1. 確定目標為 x64。在 Visual Studio 中，請移至 **Build**->**Configuration Manager**，並將 **Active solution platform** 設定為 x64。 2. 新增下列 include 路徑：`C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Include` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Include` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Include` 其中 **GDK version number** 是以該版本的年份、月份和子版本號碼命名的目錄。例如，2022 年 6 月 GDK 的目錄名稱為 220600。若為 Microsoft GDK (2024 年 6 月) 或更早版本，請使用 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include* 和 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Include*。在 Visual Studio 中，您可以在專案屬性頁面的 **Configuration Properties**->**VC++ Directories**->**Include Directories** 下新增這些路徑。 3. 為匯入程式庫新增下列程式庫路徑：`C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64` 其中 **GDK version number** 是以該版本的年份、月份和子版本號碼命名的目錄。例如，2022 年 6 月 GDK 的目錄名稱為 220600。若為 Microsoft GDK (2024 年 6 月) 或更早版本，請使用 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release* 和 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib*。在 Visual Studio 中，您可以在專案屬性頁面的 **Configuration Properties**->**VC++ Directories**->**Library Directories** 下新增這些路徑。 4. 將下列程式庫新增至專案所連結的程式庫清單：`C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64\xgameruntime.lib` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (or Microsoft.Xbox.Services.142.GDK.C.lib, if statically linking)` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64\libHttpClient.GDK.lib` 其中 **GDK version number** 是以該版本的年份、月份和子版本號碼命名的目錄。例如，2022 年 6 月 GDK 的目錄名稱為 220600。若為 Microsoft GDK (2024 年 6 月) 或更早版本，請使用 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (如果是靜態連結，則為 Microsoft.Xbox.Services.142.GDK.C.lib)* 和 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib\libHttpClient.GDK.lib*。在 Visual Studio 中，您可以在專案屬性頁面的 **Configuration Properties**->**Linker**->**Input**->**Additional Dependencies** 下新增這些程式庫。 5. 定義 *\_GAMING\_DESKTOP* 和 *WINAPI\_FAMILY=WINAPI\_FAMILY\_DESKTOP\_APP*。在 Visual Studio 中，您可以在專案屬性頁面的 **C/C++**->**Command Line**->**Additional Options** 下新增下列這一行：`/D "_GAMING_DESKTOP" /D "WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP"` 6. 建立 MicrosoftGame.config 檔案，並確定在建置期間將其複製到與 .exe 相同的目的地。**注意：** 如果您的引擎支援任何在執行時使用不同 .exe 的編輯器內執行功能，也請將 MicrosoftGame.config 複製到該 .exe 所在的目錄。如果 MicrosoftGame.config 不在 .exe 所在的目錄中，使用編輯器內執行功能時 XBOX services 將無法運作。開始開發時，您可以使用具有預設值的設定，如下列範例所示。Identity Name、Executable Name 和 Executable Alias 的值都應取代為您的可執行檔名稱。 ```xml theme={null} ``` 7. 確定在建置期間將 **Microsoft.Xbox.Services.GDK.C.Thunks.dll** (如果是動態連結)、**XCurl.dll** 和 **libHttpClient.GDK.dll** 的複本複製到與 .exe 相同的目的地。**注意：** 如果您的引擎支援任何在執行時使用不同 .exe 的編輯器內執行功能，請確定該 .exe 也參考這些 .dll。如果 .exe 未參考這些 .dll，使用編輯器內執行功能時 XBOX services 將無法運作。如果是動態連結至 XSAPI，可以在 GDK 安裝的下列目錄中找到 **Microsoft.Xbox.Services.GDK.C.Thunks.dll**：`C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release]` 可以在 GDK 安裝的下列目錄中找到 **XCurl.dll**：`C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64` 可以在 GDK 安裝的下列目錄中找到 **libHttpClient.GDK.dll**：`C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\x64` 其中 **GDK version number** 是以該版本的年份、月份和子版本號碼命名的目錄。例如，2022 年 6 月 GDK 的目錄名稱為 220600。若為 Microsoft GDK (2024 年 6 月) 或更早版本，請使用 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\\\[Debug|Release]*、*C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\CommonConfiguration\neutral* 和 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\CommonConfiguration\neutral* 或者，如果您要將 GDK 整合到現有的 Visual Studio 桌面專案中，可以依照本主題中的步驟將專案轉換為 GDK 專案：[將 Microsoft Game Development Kit 新增至現有的桌面專案](https://learn.microsoft.com/gaming/gdk/_content/gc/gdk-dev/pc-dev/overviews/gr-add-to-existing-project)。 ### 更新 MicrosoftGame.config 上一個步驟中建立的 MicrosoftGame.config 檔案具有預設值，可讓您在 PC 和 XBOX 上進行早期開發，而不需要進一步設定。只有在開始使用 Gaming Runtime、Microsoft Store 和遊戲識別的功能時，才需要更新這些值。若要使用 XBOX services 功能，請以您的 Partner Center 專案識別詳細資料更新專案的 MicrosoftGame.config。 1. 移至 [Partner Center 儀表板](https://partner.microsoft.com/dashboard/windows/overview)。 2. 從產品清單中選取您的遊戲。 3. 選取 **Game setup** 索引標籤，然後選取 **Identity details**。 4. 選取 **Show Details** 以展開 **Identity details** 區段。 5. 使用 **Identity details** 區段表格中的下列值，然後將這些值從 Partner Center 複製到 MicrosoftGame.config 中對應的元素和欄位。 | Partner Center 中的名稱 | MicrosoftGame.config | | - | - | | XBOX Title ID | TitleId | | Package/Identity/Name | Identity->Name | | Package/Identity/Publisher | Identity->Publisher | | XBOX services -> XBOX Settings -> MSAAppId | MSAAppId | 例如，Partner Center 中的下列識別詳細資料會讓您的 MicrosoftGame.config 看起來如下方範例所示： | Partner Center 中的名稱 | 範例值 | | - | - | | XBOX Title ID | 64353034 | | Package/Identity/Name | 41336MicrosoftATG.Achievements2017Redux | | Package/Identity/Publisher | CN=A4954634-DF4B-47C7-AB70-D3215D246AF1 | | XBOX services -> XBOX Settings -> MSAAppId | 0000000000000000 | ```xml theme={null} 64353034 0000000000000000 ``` 如需 MicrosoftGame.config 中值的其他資訊，請參閱 [MicrosoftGame.config 概觀](/zh-TW/build/core-features/common/game-config/MicrosoftGameConfig-Overview)。 ### 初始化遊戲執行階段和 XSAPI 下列步驟說明如何在遊戲中初始化 Gaming Runtime Services 和 XSAPI。 1. 包含 XGameRuntime 標頭和 XSAPI services-c 標頭。 ```cpp theme={null} #include #include ``` 2. 呼叫 [XGameRuntimeInitialize](/zh-TW/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize) 以初始化 GDK 執行階段。 ```cpp theme={null} // Initialize the GameRuntime HRESULT hr = XGameRuntimeInitialize(); if (FAILED(hr)) { if (hr == E_GAMERUNTIME_DLL_NOT_FOUND || hr == E_GAMERUNTIME_VERSION_MISMATCH) { (void)MessageBoxW(nullptr, L"Game Runtime is not installed on this system or needs updating.", g_szAppName, MB_ICONERROR | MB_OK); } return 1; } ``` 3. 呼叫 [XblInitialize](/zh-TW/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize) 以初始化 XSAPI。 ```cpp theme={null} XblInitArgs xblArgs = {}; //xblArgs.queue = queue; // Uncomment this line if you've chosen to create your own XTaskQueue. Otherwise, by default, this line is not needed. xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Add your scid from your Partner Center project here; HRESULT hr = XblInitialize(&xblArgs); if (FAILED(hr)) { // Handle failure } ``` ### 取消初始化遊戲執行階段您必須在遊戲結束之前取消初始化 Gaming Runtime Services。XSAPI 不需要在結束前明確清除。呼叫 [XGameRuntimeUninitialize](/zh-TW/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize) 以取消初始化 GDK 執行階段。 ```cpp theme={null} // Uninitialize the Gaming Runtime after // all other activity has been completed. XGameRuntimeUninitialize(); ``` 如需在遊戲中使用 XSAPI 的詳細概觀，請參閱[開始使用 XBOX services API](/zh-TW/services/xbox-services/fundamentals/xbox-services-api/live-gs-xbl-apis)。
如需實作 GDK 功能的概觀，請參閱 [Game Development Kit (GDK) 功能](https://learn.microsoft.com/gaming/gdk/_content/gc/features/features-index)。 ## 在遊戲中測試 XBOX services 若要在遊戲中測試成就等 XBOX services 功能，您需要使用沙箱以及可存取該沙箱的測試帳戶。 ### 建立測試帳戶若要在遊戲中測試任何 XBOX services 功能，請建立可存取您開發沙箱的測試帳戶。如需建立測試帳戶的相關資訊，請參閱[建立測試帳戶](/zh-TW/services/xbox-services/develop/test-accounts/live-setup-testaccounts)。 ### 切換沙箱建立測試帳戶之後，請使用下列步驟以該帳戶存取您的沙箱。 1. 若要尋找您的沙箱 ID，請移至 [Partner Center](https://partner.microsoft.com/dashboard/windows/overview)。 2. 選取 **XBOX services**，然後選取 **Gameplay Settings**。您的沙箱 ID 位於第一個索引標籤上，名稱類似 "ABCDEF.0"。 3. 開啟 **開始** 功能表。 4. 輸入 **Microsoft GDK Command Prompts**，然後按下鍵盤上的 **Enter**。 5. 開啟第一個命令提示字元。 6. 在命令提示字元中，輸入 **XblPCSandbox.exe \[your sandbox ID]**。 7. 命令提示字元啟動數個應用程式之後，使用您的測試帳戶登入 XBOX 應用程式。如果您能成功登入，表示您已建立測試帳戶並切換至您的沙箱，可以開始測試。如需沙箱的詳細資訊，請參閱 [XBOX services 沙箱概觀](/zh-TW/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox)。 ## 發行若要準備好發行遊戲，您需要： * 完成遊戲與 GDK 的整合 * 依照[使用 MSIXVC 封裝工具開始封裝 PC 遊戲](/zh-TW/build/core-features/common/packaging/overviews/packaging-getting-started-for-PC)中的步驟建立遊戲套件完成這兩項需求之後，您就可以發行了。若要提交遊戲，請移至 [Partner Center](https://partner.microsoft.com/dashboard/windows/overview)，並依照 UI 中的指示操作。 ## Related topics - [Godot 與社群引擎總覽](/zh-TW/paths/community-engines/overview.md) - [搭配 Unity、Unreal 和其他引擎使用 GDK](/zh-TW/build/gdk-and-engines/gdk-and-engines.md) - [一般移植指南](/zh-TW/paths/porting/guides.md) - [PC 端對端概觀](/zh-TW/build/gdk-and-engines/overview.md) - [將 Unreal Engine 遊戲發行至 XBOX PC (UE 5.8+)](/zh-TW/build/gdk-and-engines/unreal/unreal-xbox-pc.md)