> ## 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 集成到 4.26 之前的 Unreal Engine 项目

> 通过编辑 Build.cs、手动添加 include 与库路径,并使用 wdapp 启动,将 XBOX GDK 接入 4.26 之前版本的 Unreal Engine 构建。

如果你正在准备将游戏发布到 PC 上的 Microsoft Store,并且使用的是 4.26 之前版本的 Unreal Engine,请使用本主题。

## 使用较早版本的 Unreal Engine(4.26 之前)

如果你使用的是 Unreal Engine 4.26 或更新版本,请参见 [在 PC 上开始使用 Unreal](/build/gdk-and-engines/unreal/unreal)。

如果你使用的是 Unreal Engine 4.25 或更早版本,并且无法升级到 4.26 或更新版本,你仍然可以通过 Gaming Runtime 与 XBOX Services API(XSAPI)的导入库来接入关键的 XBOX 生态体验。

这些导入库允许游戏直接调用 Gaming Runtime API 与 XSAPI,而无需为游戏项目添加 GDK 平台目标。

### 为 Gaming Runtime 与 XSAPI 添加头文件与导入库

1. 找到 Unreal 项目的 build 文件:/Source/(ProjectName)/(ProjectName).Build.cs
2. 添加下面这一行以定义 **\_GAMING\_DESKTOP** 宏
   ```csharp theme={null}
       PublicDefinitions.Add("_GAMING_DESKTOP");  // 对于 Unreal 4.12 或更早版本,请改用 "Definitions.Add()"
   ```
3. 添加以下 include 路径
   ```csharp theme={null}
       // 添加 Gaming Runtime 的 include 路径
       PublicIncludePaths.Add(@"C:\Program Files (x86)\Microsoft GDK\241000\GRDK\GameKit\Include");
       // 添加 XSAPI 的 include 路径
       PublicIncludePaths.Add(@"C:\Program Files (x86)\Microsoft GDK\241000\GRDK\ExtensionLibraries\Xbox.Services.API.C\Include");
   ```

> 对于 Microsoft GDK(2024 年 6 月)或更早版本,请使用:*C:\Program Files (x86)\Microsoft GDK\230300\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include*

1. 为导入库添加以下库路径
   ```csharp theme={null}
       // 添加 Gaming Runtime 的导入库
       PublicAdditionalLibraries.Add(@"C:\Program Files (x86)\Microsoft GDK\241000\GRDK\GameKit\Lib\amd64\xgameruntime.lib");
       // 添加 XSAPI 的导入库
       PublicAdditionalLibraries.Add(@"C:\Program Files (x86)\Microsoft GDK\241000\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\Release\Microsoft.Xbox.Services.142.GDK.C.Thunks.lib");
   ```

> 对于 Microsoft GDK(2024 年 6 月)或更早版本,请使用:*C:\Program Files (x86)\Microsoft GDK\230300\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.141.GDK.C.Thunks.lib*

<Note>
  你机器上的 include 与库路径可能因 GDK 版本与安装位置不同而不同。
</Note>

### 从 C++ 代码文件访问 Gaming Runtime 与 XSAPI

1. 确定你希望在哪里添加登录、解锁成就等集成
2. 添加 Gaming Runtime 与 XSAPI 的头文件
   ```cpp theme={null}
       // 使用 Unreal Engine 4.15 或更新版本时
       THIRD_PARTY_INCLUDES_START
       
       #include "XGameRuntimeInit.h" // Gaming Runtime 
       #include "xsapi-c\services_c.h"  // XSAPI
       // 使用 Unreal Engine 4.15 或更新版本时
       THIRD_PARTY_INCLUDES_END
   ```
3. 与服务调用集成。示例见下:

* 如何操作:登录用户的最佳实践
* 更新作品管理的成就

### 在 Partner Center 中创建产品

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

### 为你的游戏创建 MicrosoftGame.config 文件

为让游戏能登录 XBOX 服务,你需要在游戏包中包含一个 **MicrosoftGame.config** 文件,并使用上一步创建的 Partner Center 项目中的值填写 "MSAAppId" 与 "TitleId" 字段。创建 config 文件最简单的方式是使用 [MicrosoftGame.config Editor](https://learn.microsoft.com/gaming/gdk/_content/gc/features/common/game-config/MicrosoftGameConfig-Editor)。有关 MicrosoftGame.config 文件的更多信息,请参阅 [MicrosoftGame.config overview](https://learn.microsoft.com/gaming/gdk/_content/gc/features/common/game-config/MicrosoftGameConfig-Overview)。

<Note>
  请确保 MicrosoftGame.config 文件与游戏的主可执行文件位于同一目录中。
</Note>

### 创建并注册游戏包

要在游戏中登录 XBOX 服务并测试服务集成,你需要创建一个包并注册它。

1. 通过选择 **File** > **Package Project** > **Windows** > **Windows (64-bit)** 打开打包对话框。
2. 在 **文件资源管理器** 对话框中选择构建输出的目录,然后选择 **选择文件夹**。
3. 使用 wdapp 启动游戏。
   ```cpp theme={null}
       wdapp launch {与 MicrosoftGame.Config 文件位于同一目录中的游戏可执行文件的完整路径}
   ```
4. 或者,可以使用 wdapp 注册包,然后从开始菜单启动游戏。
   ```cpp theme={null}
       wdapp register {包含 MicrosoftGame.Config 文件的目录的完整路径}
   ```

<Note>
  直接双击可执行文件将无法用于登录 XBOX 服务。
</Note>

## 参见

[登录与沙箱问题排查](https://learn.microsoft.com/gaming/gdk/_content/gc/services/develop/troubleshooting/live-troubleshoot-sandboxes)


## Related topics

- [PlayFab Unreal GSDK 插件概览](/zh-CN/services/playfab/multiplayer/servers/server-sdks/unreal-gsdk/index.md)
- [将 GDK 集成到自定义 C/C++ 引擎](/zh-CN/build/gdk-and-engines/custom-engine.md)
- [集成 PlayFab Unreal Engine Marketplace 插件](/zh-CN/services/playfab/multiplayer/networking/party-unreal-engine-oss-playfab-plugin-integration.md)
- [在 Unreal Engine 中使用 GDK](/zh-CN/build/gdk-and-engines/unreal/unreal.md)
- [在 GameMaker 中使用 GDK](/zh-CN/build/gdk-and-engines/gamemaker.md)