适用于电脑的 C/C++ 自定义引擎集成：入门

2025-05-16

如果要准备将游戏发布到电脑上的Microsoft Store，并且游戏使用不内置支持 GDK 的基于 C/C++ 的引擎，请使用本主题。

在合作伙伴中心创建产品
将 GDK 集成到 C/C++ 游戏
在游戏中测试 Xbox 服务
发布

在合作伙伴中心创建产品

你需要先在合作伙伴中心创建启用 Xbox 服务的产品，然后才能将游戏发布到 Microsoft Store。有关合作伙伴中心的更多信息，请参阅在合作伙伴中心设置应用或游戏，用于托管合作伙伴。

将 GDK 集成到 C/C++ 游戏

若要将 GDK 集成到 C/C++ 游戏中，游戏需要 3 项内容：

描述 API 签名和数据结构的 GDK 和 Xbox 服务 API (XSAPI) 标头
导入库，告知链接器如何解析对导出的 GDK 和 XSAPI DLL 函数的外部引用
dynamic-link 库实际上包含 GDK 和 XSAPI 函数的运行时实现

若要使游戏与重要的 Xbox 生态系统体验集成，它们需要与以下两个组件进行交互：游戏运行时服务 (GRTS) 和 XSAPI。下面是非托管游戏所需的文件：

组件	GRTS	XSAPI
标头	GRTS 标头：XUser、XGameSave、XGameUI 等（来自 GDK）	XSAPI 标头：profile_c.h、achievements_c.h 等（来自 GDK）
导入库	xgameruntime.lib（来自 GDK）	来自 GDK) 的 Microsoft.Xbox.Services.GDK.C.Thunks.lib (
动态链接库	xgameruntime.dll 和其他几个 dll（GRTS 安装的 system32）	Microsoft.Xbox.Services.GDK.C.Thunks.dll (来自 GDK，需要包含在游戏包)

向项目添加游戏运行时服务和 XSAPI 的要求

以下步骤概括介绍了为确保项目满足使用游戏运行时服务和 XSAPI 的所有要求而需要对项目进行的更改。

确保将 x64 作为目标。

在 Visual Studio 中，你将转到生成 - >配置服务器 并将 活动解决方案平台 设置为 x64。
添加以下包含路径：

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 版本号是由发布版本的年、月和子版本号命名的目录。例如，对于 2022 年 6 月 GDK，目录名称为 220600。

对于 Microsoft GDK (2024 年 6 月) 或更早版本，使用 C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include and C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Include

在 Visual Studio 中，将在“配置属性”（>VC++ 目录）下的“项目属性”页中添加这些路径，>包括目录。
为导入库添加以下库路径：

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 版本号是由发布版本的年、月和子版本号命名的目录。例如，对于 2022 年 6 月 GDK，目录名称为 220600。

对于 Microsoft GDK (2024 年 6 月) 或更早版本，使用 C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release 和 C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib

在 Visual Studio 中，将在“配置属性”下的“项目属性”页中添加这些路径->VC++ 目录->库目录。
将以下库添加到链接到项目的库列表：

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

C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64\libHttpClient.GDK.lib

其中，GDK 版本号是由发布版本的年、月和子版本号命名的目录。例如，对于 2022 年 6 月 GDK，目录名称为 220600。

对于 Microsoft GDK (2024 年 6 月) 或更早版本， use C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.GDK.C.Thu nks.lib 和 C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib\libHttpClient.GDK.lib

在 Visual Studio 中，将在“配置属性”下的“项目属性”页中添加库 ->链接器->输入->其他依赖项。
定义_GAMING_DESKTOP并WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP。

在 Visual Studio 中，将在 C/C++下的“项目属性”页中添加以下行 ->命令行->其他选项：

/D "_GAMING_DESKTOP" /D "WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP"

创建 MicrosoftGame.config 文件，并确保在生成期间将其复制到与 .exe 相同的目标。

注意：如果引擎支持任何类型的“在编辑器中运行”功能，而该功能在运行时使用不同 .exe，则需要确保也将 MicrosoftGame.config 复制到 .exe 所在的相同目录中。如果 MicrosoftGame.config 与 .exe 不在同一目录中，则在使用“在编辑器中运行”功能时，Xbox 服务将无法正常工作。

对于开始开发，可以使用具有默认值的配置，如以下示例所示。标识名称、可执行文件名称和可执行文件别名的值都将替换为可执行文件的名称。

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

<Identity Name="Direct3DGame1_test"
            Publisher="CN=Publisher"
            Version="1.0.0.0"/>

<ExecutableList>
    <Executable Name="Direct3DGame1_test.exe"
                Id="Game"
                Alias="Direct3DGame1_test.exe"/>
</ExecutableList>

<ShellVisuals DefaultDisplayName="Direct3DGame1_test"
                PublisherDisplayName="PublisherName"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="Direct3DGame1_test"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>
</Game>

确保在生成期间将 Microsoft.Xbox.Services.GDK.C.Thunks.dll、 XCurl.dll 和 libHttpClient.GDK.dll 的副本复制到与 .exe 相同的目标。

注意：如果引擎支持任何类型的“在编辑器中运行”功能，而该功能在运行时使用不同 .exe，则需要确保 .exe 也引用这些 .dll。如果 .exe 未引用 .dll，则在使用“在编辑器中运行”功能时，Xbox 服务将无法正常工作。

可以在 以下目录中的 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]

XCurl.dll可在以下目录的 GDK 安装中找到：

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 版本号是由发布版本的年、月和子版本号命名的目录。例如，对于 2022 年 6 月 GDK，目录名称为 220600。

对于 Microsoft GDK (2024 年 6 月) 或更早版本，请使用 C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\[Debug|Release]， C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\CommonConfiguration\neutral，和 C：\Program Files (x86) \Microsoft GDK\[GDK 版本号]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\CommonConfiguration\neutral

注意

或者，要将 GDK 集成到现有 Visual Studio 桌面项目，则可以按照本主题中的步骤将项目转换为 GDK 项目，将 Microsoft 游戏开发工具包添加到现有桌面项目。

更新 MicrosoftGame.config

在上一步中创建的 MicrosoftGame.config 文件具有默认值，允许在电脑和 Xbox 上进行早期开发，而无需进一步配置，直到开始使用游戏运行时、Microsoft Store和游戏标识中的功能。若要使用 Xbox 服务功能，需要使用合作伙伴中心项目标识详细信息更新项目的 MicrosoftGame.config。

转到合作伙伴中心仪表板。
从产品列表中选择自己的游戏。
选择游戏设置选项卡，然后选择标识详细信息。
选择显示详细信息以展开标识详细信息部分。
使用标识详细信息部分的表中的以下值，然后将这些值从合作伙伴中心复制到 MicrosoftGame.config 中的相应元素和字段中。

合作伙伴中心中的名称	MicrosoftGame.config
Xbox 游戏 ID	TitleId
包/标识/名称	标识 ->名称
包/标识/发布者	标识 ->发布者
Xbox 服务 -> Xbox 设置 ->MSAAppId	MSAAppId

例如，合作伙伴中心中的以下标识详细信息将导致你的 MicrosoftGame.config 看起来类似下面的示例：

合作伙伴中心中的名称	示例值
Xbox 游戏 ID	64353034
包/标识/名称	41336MicrosoftATG.Achievements2017Redux
包/标识/发布者	CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
Xbox 服务 -> Xbox 设置 ->MSAAppId	0000000000000000

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

  <Identity Name='41336MicrosoftATG.Achievements2017Redux' Version="1.1.0.0" Publisher='CN=A4954634-DF4B-47C7-AB70-D3215D246AF1' />


  <TitleId>64353034</TitleId>
  <MSAAppId>0000000000000000</MSAAppId>
  
  <ExecutableList>
    <Executable Name="Achievements2017_desktop.exe"
                TargetDeviceFamily="PC"
                Id="Game"/>
  </ExecutableList>
  
  <ShellVisuals DefaultDisplayName="Achievements2017 Desktop Sample"
                PublisherDisplayName="Xbox Advanced Technology Group"
                StoreLogo="Assets\StoreLogo.png"
                Square150x150Logo="Assets\Logo.png"
                Square44x44Logo="Assets\SmallLogo.png"
                Square480x480Logo="Assets\LargeLogo.png"
                Description="Achievements2017"
                ForegroundText="dark"
                BackgroundColor="#000000"
                SplashScreenImage="Assets\SplashScreen.png"/>
</Game>

有关 MicrosoftGame.config 中的值的其他信息，请参阅MicrosoftGame.config。

初始化游戏运行时和 XSAPI

以下步骤演示如何在游戏中初始化游戏运行时服务和 XSAPI。

包括 XGameRuntime 标头和 XSAPI services-c 标头。

#include <XGameRuntime.h> 
#include <xsapi-c/services_c.h>

调用 XGameRuntimeInitialize初始化 GDK 运行时。

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

}

调用XblInitialize初始化 XSAPI。

 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
 }

取消初始化游戏运行时

在游戏退出之前，需要取消初始化游戏运行时服务。退出之前，无需显式清理 XSAPI。

通过调用 XGameRuntimeUninitialize 来取消初始化 GDK 运行时。

 // Uninitialize the Gaming Runtime after
 // all other activity has been completed.
 XGameRuntimeUninitialize();

有关在游戏中使用 XSAPI 的详细概述，请参阅 Xbox 服务 API 入门。
有关实现 GDK 功能的概述，请参阅游戏开发工具包 ( GDK) 功能。

在游戏中测试 Xbox 服务

若要在游戏中测试 Xbox 服务功能（如成就），需要使用沙盒并测试有权访问该沙盒的帐户。

创建测试帐户

若要测试游戏中的任何 Xbox 服务功能，需要创建有权访问开发沙盒的测试帐户。有关创建测试帐户的信息，请参阅创建测试帐户。

切换沙盒

创建测试帐户后，请使用该帐户通过以下步骤访问沙盒。

若要查找沙盒的 ID，请转到“合作伙伴中心”。
选择“Xbox 服务”，然后选择“游戏设置”。

注意

你的沙盒 ID 位于第一个选项卡上，并且其名称为"ABCDEF.0"。
打开开始菜单。
输入Microsoft GDK 命令提示符，然后在键盘上选择 Enter。
打开第一个命令提示符。
在命令提示符处，输入 XblPCSandbox.exe[你的沙盒 ID]。
命令提示符启动多个应用后，使用测试帐户登录到 Xbox 应用。

如果能够成功登录，则已创建测试帐户并更改为沙盒以开始测试。

有关沙盒的详细信息，请参阅 Xbox 服务沙盒概述。

发布

若要准备好发布游戏，需要：

已完成将游戏与 GDK 集成
按照使用开始为电脑打包游戏中的步骤创建游戏包

完成这两项要求后，即可发布。转到“合作伙伴中心”并按照 UI 中的说明提交游戏。

通过