将 GDK 集成到自定义 C/C++ 引擎

如果你的游戏准备发布到 PC 上的 Microsoft Store,并且使用的是没有内置 GDK 支持的 C/C++ 引擎,请参阅本主题。

在 Partner Center 中创建产品
将 GDK 集成到 C/C++ 游戏
在游戏中测试 XBOX 服务
发布

在 Partner Center 中创建产品

在将游戏发布到 Microsoft Store 之前,你需要在 Partner Center 中创建启用了 XBOX 服务的产品。有关 Partner Center 的更多信息,请参阅 Setting up an app or game in Partner Center, for Managed Partners。

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

要将 GDK 集成到 C/C++ 游戏,游戏需要 4 项内容:

GDK 与 XBOX Services API(XSAPI)的 头文件,用于描述 API 签名和数据结构。
导入库(import library) ,用于告诉链接器如何解析对已导出 GDK 函数的外部引用。
XSAPI 的静态库或 导入库,用于告诉链接器如何解析对已导出 XSAPI DLL 函数的外部引用。
- XSAPI 提供静态和动态两种形式。请参考下方表格并从其中选择一种。
动态链接库,其中实际包含 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 的所有要求。

确保面向 x64。在 Visual Studio 中,进入 Build->Configuration Manager,并将 Active solution platform 设为 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 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 中添加这些路径。
添加以下导入库的库路径: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 中添加这些路径。
将以下库添加到项目要链接的库列表中: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 中添加这些库。
定义 _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"

创建一个 MicrosoftGame.config 文件,并确保它在构建期间会被拷贝到与 .exe 相同的目标目录。注意: 如果你的引擎支持在编辑器中运行(使用不同 .exe)之类的功能,也需要确保 MicrosoftGame.config 被拷贝到那个 .exe 所在目录。如果 MicrosoftGame.config 未与 .exe 位于同一目录,使用在编辑器中运行功能时 XBOX 服务将无法工作。开始开发时,你可以使用类似下例的默认值配置。Identity Name、Executable Name 和 Executable Alias 的值都要替换为你自己可执行文件的名称。

<?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 服务将无法工作。若动态链接 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。

更新 MicrosoftGame.config

上一步创建的 MicrosoftGame.config 文件使用默认值,可以在不进一步配置的情况下开始在 PC 和 XBOX 上进行早期开发,直到你开始使用 Gaming Runtime、Microsoft Store 和标题标识相关的功能。为使用 XBOX 服务功能,你需要根据 Partner Center 项目的标识详情更新项目的 MicrosoftGame.config。

前往 Partner Center 仪表板。
从产品列表中选择你的游戏。
选择 Game setup 标签页,然后选择 Identity details。
选择 Show Details 以展开 Identity details 部分。
使用 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 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 overview。

初始化 Game Runtime 与 XSAPI

以下步骤展示如何在游戏中初始化 Gaming Runtime Services 与 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
 }

反初始化 Game Runtime

在游戏退出前需要反初始化 Gaming Runtime Services。XSAPI 无需在退出前显式清理。通过调用 XGameRuntimeUninitialize 反初始化 GDK 运行时。

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

有关在游戏中使用 XSAPI 的详细概述,参见 Getting started with XBOX services APIs。
有关实现 GDK 功能的概述,参见 Game Development Kit (GDK) features。

在游戏中测试 XBOX 服务

要在游戏中测试成就等 XBOX 服务功能,你需要使用一个沙箱以及具有该沙箱访问权限的测试账户。

创建测试账户

要在游戏中测试任何 XBOX 服务功能,你需要创建具有开发沙箱访问权限的测试账户。关于创建测试账户的信息,参见 Creating test accounts。

切换沙箱

创建测试账户后,按以下步骤使用该账户访问你的沙箱。

要查找你的沙箱 ID,请前往 Partner Center。
选择 XBOX services,然后选择 Gameplay Settings。
你的沙箱 ID 位于第一个标签页,形如 “ABCDEF.0”。
打开开始菜单。
输入 Microsoft GDK Command Prompts,然后按键盘上的 Enter。
打开第一个命令提示符。
在命令提示符中输入 XblPCSandbox.exe [your sandbox ID]。
命令提示符启动多个应用后,使用你的测试账户登录 XBOX App。

如果可以成功登录,你就创建好了测试账户并切换到了自己的沙箱,可以开始测试了。关于沙箱的更多信息,参见 XBOX services Sandboxes overview。

发布

要准备发布游戏,你需要:

完成游戏与 GDK 的集成
按照 Getting started with packaging titles for a PC by using the MSIXVC packaging tools 的步骤创建游戏包

完成这两项要求后,你就可以发布了。要提交游戏,请前往 Partner Center 并按照 UI 中的指示操作。

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

在 Partner Center 中创建产品

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

为项目添加 Gaming Runtime Services 与 XSAPI 的要求

更新 MicrosoftGame.config

初始化 Game Runtime 与 XSAPI

反初始化 Game Runtime

在游戏中测试 XBOX 服务

创建测试账户

切换沙箱

发布

​在 Partner Center 中创建产品

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

​为项目添加 Gaming Runtime Services 与 XSAPI 的要求

​更新 MicrosoftGame.config

​初始化 Game Runtime 与 XSAPI

​反初始化 Game Runtime

​在游戏中测试 XBOX 服务

​创建测试账户

​切换沙箱

​发布

在 Partner Center 中创建产品

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

为项目添加 Gaming Runtime Services 与 XSAPI 的要求

更新 MicrosoftGame.config

初始化 Game Runtime 与 XSAPI

反初始化 Game Runtime

在游戏中测试 XBOX 服务

创建测试账户

切换沙箱

发布