> ## 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 上的 Microsoft Store 和 XBOX 上发布。 如果你的游戏准备发布到 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 服务](#testing-xbox-services-in-your-game) * [发布](#publishing) ## 在 Partner Center 中创建产品 在将游戏发布到 Microsoft Store 之前,你需要在 Partner Center 中创建启用了 XBOX 服务的产品。有关 Partner Center 的更多信息,请参阅 [Setting up an app or game in Partner Center, for Managed Partners](https://learn.microsoft.com/gaming/gdk/_content/gc/services/fundamentals/portal-config/live-setup-partner-center-partners)。 ## 将 GDK 集成到 C/C++ 游戏 要将 GDK 集成到 C/C++ 游戏,游戏需要 4 项内容: 1. GDK 与 XBOX Services API(XSAPI)的 *头文件*,用于描述 API 签名和数据结构。 2. *导入库(import library)* ,用于告诉链接器如何解析对已导出 GDK 函数的外部引用。 3. XSAPI 的静态库或 *导入库*,用于告诉链接器如何解析对已导出 XSAPI DLL 函数的外部引用。 * 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 集成进去。这种方式在 PC 与 XBOX 平台上都能可靠工作。 当你将 XSAPI 静态链接到多个 DLL 时,每个 DLL 都会维护自己的一份全局状态。因此在一个 DLL 中调用 `XblInitialize` 并不会初始化其他 DLL 中的 XSAPI。将 XSAPI 句柄在包含独立静态实例的多个 DLL 之间共享,可能会导致崩溃或不可预测的行为。 `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. 添加以下包含路径:`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(或在静态链接时使用 Microsoft.Xbox.Services.142.GDK.C.lib)` `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 服务将无法工作。开始开发时,你可以使用类似下例的默认值配置。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 服务将无法工作。若动态链接 XSAPI,**Microsoft.Xbox.Services.GDK.C.Thunks.dll** 位于 GDK 安装目录的:`C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release]`。**XCurl.dll** 位于:`C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64`。**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 Desktop 项目中,可以按照本主题的步骤将项目转换为 GDK 项目:[Adding the Microsoft Game Development Kit to an existing desktop project](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 服务功能,你需要根据 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 overview](https://learn.microsoft.com/gaming/gdk/_content/gc/features/common/game-config/MicrosoftGameConfig-Overview)。 ### 初始化 Game Runtime 与 XSAPI 以下步骤展示如何在游戏中初始化 Gaming Runtime Services 与 XSAPI。 1. 包含 XGameRuntime 头文件与 XSAPI services-c 头文件。 ```cpp theme={null} #include #include ``` 2. 调用 [XGameRuntimeInitialize](https://learn.microsoft.com/gaming/gdk/_content/gc/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](https://learn.microsoft.com/gaming/gdk/_content/gc/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 } ``` ### 反初始化 Game Runtime 在游戏退出前需要反初始化 Gaming Runtime Services。XSAPI 无需在退出前显式清理。 通过调用 [XGameRuntimeUninitialize](https://learn.microsoft.com/gaming/gdk/_content/gc/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize) 反初始化 GDK 运行时。 ```cpp theme={null} // Uninitialize the Gaming Runtime after // all other activity has been completed. XGameRuntimeUninitialize(); ``` 有关在游戏中使用 XSAPI 的详细概述,参见 [Getting started with XBOX services APIs](https://learn.microsoft.com/gaming/gdk/_content/gc/services/fundamentals/xbox-services-api/live-gs-xbl-apis)。
有关实现 GDK 功能的概述,参见 [Game Development Kit (GDK) features](https://learn.microsoft.com/gaming/gdk/_content/gc/features/features-index)。 ## 在游戏中测试 XBOX 服务 要在游戏中测试成就等 XBOX 服务功能,你需要使用一个沙箱以及具有该沙箱访问权限的测试账户。 ### 创建测试账户 要在游戏中测试任何 XBOX 服务功能,你需要创建具有开发沙箱访问权限的测试账户。关于创建测试账户的信息,参见 [Creating test accounts](https://learn.microsoft.com/gaming/gdk/_content/gc/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 App。 如果可以成功登录,你就创建好了测试账户并切换到了自己的沙箱,可以开始测试了。 关于沙箱的更多信息,参见 [XBOX services Sandboxes overview](https://learn.microsoft.com/gaming/gdk/_content/gc/services/fundamentals/sandboxes/live-setup-sandbox)。 ## 发布 要准备发布游戏,你需要: * 完成游戏与 GDK 的集成 * 按照 [Getting started with packaging titles for a PC by using the MSIXVC packaging tools](https://learn.microsoft.com/gaming/gdk/_content/gc/features/common/packaging/overviews/packaging-getting-started-for-PC) 的步骤创建游戏包 完成这两项要求后,你就可以发布了。要提交游戏,请前往 [Partner Center](https://partner.microsoft.com/dashboard/windows/overview) 并按照 UI 中的指示操作。 ## Related topics - [在 Unity、Unreal 及其他引擎中使用 GDK](/zh-CN/build/gdk-and-engines/gdk-and-engines.md) - [PC 端到端概览](/zh-CN/build/gdk-and-engines/overview.md) - [XBOX PC Remote 工具:2026 年 3 月 (2603) 发行说明](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md) - [将 GDK 集成到 4.26 之前的 Unreal Engine 项目](/zh-CN/build/gdk-and-engines/unreal/unreal-legacy.md) - [将 PlayFab GSDK 集成到 Unity 中](/zh-CN/services/playfab/multiplayer/servers/mps-unity.md)