Unreal Engine入门

概述

本文档介绍如何在将 GDK 组件集成到项目中时开始使用 Unreal Engine。这将涵盖不同类型的Unreal Engine插件 & 平台扩展、如何设置它们以及提供的插件和扩展中包含哪些功能。

GDK 平台扩展 & 关联的插件由 Epic Games 维护 & 分发。

重要

作为 Unreal Engine 5.7 的一部分发布的 Microsoft GDK 插件Unreal Engine使你能够使用 Win64 平台生成 GDK 游戏。这允许为 Windows 版本提供统一的平台，从而缩短准备时间，启用单个可执行方案，并改进与当前使用 Win64 的 Unreal Engine 插件的兼容性。 WinGDK 将不再接收功能更新，被视为旧平台。 Epic Games 提供了一个迁移工具，用于将现有项目从 WinGDK 移植到 Win64。有关详细信息，请参阅 Epic Games 中的 GDK 文档。

先决条件

使用 GDK 平台扩展 & 插件进行Unreal Engine需要以下先决条件：

Microsoft适用于Unreal Engine的 GDK 插件

有多个 GDK 插件在为项目启用时提供不同的功能。本节中列出的插件目前是 Epic Games 分发的 GDK 平台扩展的一部分。

若要访问Microsoft GDK 插件和 GDK 平台扩展，您必须是 Xbox 开发人员计划的成员，包括ID@Xbox，并且通过此访问请求表单请求访问Unreal Engine的开发者社区 GDK 组。批准后，将授予你访问包含 GDK 平台扩展Unreal Engine源的访问权限。

注意

目前，电脑、Xbox Series X|S & Xbox One 开发都需要加入 Xbox 开发人员计划并请求访问 GDK 插件和 GDK 平台扩展。如有任何问题，请联系Microsoft代表寻求帮助。

要考虑的关键 GDK 插件如下所示：

插件名称	平台支持	最低引擎版本
适用于 Unreal Engine 的 Microsoft GDK 运行时插件	Win64	Unreal Engine 5.7+
适用于Unreal Engine的 Microsoft GDK 应用商店插件	Win64	Unreal Engine 5.7+
联机子系统 GDK	Win64、WinGDK、XB1、XSX	Unreal Engine 4.27+

适用于Unreal Engine的 Microsoft GDK 运行时插件提供对 GDK 运行时功能的访问权限，例如与 Xbox 兼容的游戏保存和 Xbox 用户选择。此插件作为 MSGamingRuntime 存在于 GDK 平台文件夹中。

适用于 Unreal Engine 的 Microsoft GDK 应用商店插件提供自动生成用于提交到 Xbox 电脑应用的 .msixvc 包。此插件作为 MSGameStore 存在于 GDK 平台文件夹中。

联机子系统 GDK 插件提供 GDK 与联机子系统的集成，联机子系统是一个引擎抽象层，可为成就、好友 & 匹配等关键功能提供通用接口调用。作为 OnlineSubsystemGDK，这位于所有平台文件夹（包括 Win64 支持的 GDK 文件夹）中。

提供进一步功能的其他 GDK 插件包括：

插件名称	平台支持	最低引擎版本
游戏输入基础	Win64、WinGDK、XB1、XSX	Unreal Engine 5.4+
Windows) (游戏输入	Win64、WinGDK	Unreal Engine 5.4+
Xbox 通用游戏输入	XB1、XSX	Unreal Engine 5.4+
GDK 包区块安装程序	Win64、WinGDK、XB1、XSX	Unreal Engine 5.7+
GDK 虚拟键盘	Win64、WinGDK、XB1、XSX	Unreal Engine 5.7+
Windows 虚拟键盘	Win64	Unreal Engine 5.7+

游戏输入 (Windows) 、游戏输入基础和 Xbox 通用游戏输入插件提供与引擎中的 GameInput 功能的集成。它们的结构如下：

GameInput (友好名称：游戏输入基)
- 包含此列表中要实现的插件的核心功能和接口
- 平台：Win64
- GameInput_WinGDK、GameInput_XB1和GameInput_XSX扩展了 GameInput 插件，以添加对各自平台支持的支持， (父)
GameInputWindows (友好名称：游戏输入 (Windows) )
- 依赖于 GameInput，并从 GameInput 插件实现接口
- 平台：Win64
- GameInputWindows_WinGDK扩展 GameInputWindows 以添加对 WinGDK 平台的支持， (父)
XboxCommonGDKGameInput (友好名称：Xbox Common GameInput)
- 依赖于 GameInput 并从 GameInput 插件实现接口
- 平台：无指定
- 等效于 GameInputWindows，但对于两个 Xbox 平台和不同的接口实现 (由于平台之间的 GameInput 差异)
- XboxCommonGDKGameInput_XB1和XboxCommonGDKGameInput_XSX扩展了 XboxCommonGDKGameInput，以添加对其各自平台的支持， (父)

GDK 包区块安装程序插件提供了其他功能，可在生成 GDK 包时利用智能交付。与 Win64 兼容的插件位于 Engine\Platforms\GDK\Plugins 文件夹中。在各自的平台文件夹中，有特定于平台的插件，其中包含 WinGDK、XB1 & XSX 的平台后缀。

GDK 虚拟键盘插件和 Windows 虚拟键盘插件提供了附加功能，可在游戏中调用虚拟键盘。在手持设备上考虑游戏板方案时，这一点尤其重要。 Windows 虚拟键盘插件提供不依赖于 GDK 的实现，并且可以在 Win64 平台上跨店面使用。

对于 GDK 虚拟键盘插件，它利用特定于 GDK 的 API 来启用此功能。与 Win64 兼容的插件位于 Engine\Platforms\GDK\Plugins 文件夹中。在各自的平台文件夹中，有特定于平台的插件，其中包含 WinGDK、XB1 & XSX 的平台后缀。

Unreal Engine & GDK 平台扩展

Unreal Engine中特定于 GDK 的代码是 GDK 平台扩展的一部分，该扩展是基础引擎源的扩展，允许使用 GDK for PC、Xbox One 和 Xbox Series X|S 生成游戏。这些扩展包括一组 GDK 平台和 GDK 插件， (上面列出的) ，这些插件与引擎配合使用以扩展必要的功能。

开始使用 GDK 构建游戏需要这些扩展。 GDK 平台扩展的结构作为单个相互依赖的下载捆绑在一起，这意味着它还要求你将Microsoft GDK 与 Xbox 扩展 (GDKx) ) 与目标平台无关。目前不支持将这些扩展用于 GitHub 上的 GDK。

扩展将包括 Engine\Platforms 源代码，特定于 GDK 的平台包括：

WinGDK (不要采用此平台，因为它被视为旧平台。使用适用于 Win64 平台的 Microsoft GDK 应用商店 & 运行时插件，用于未来所有新的 PC GDK 项目。)
XB1
XSX

GDK & XboxCommon 文件夹提供平台之间的共享代码 (GDK 跨所有平台，XboxCommon 跨 Xbox One (XB1) 和 Xbox Series X|S (XSX) 平台) 。可在 GDK 平台扩展下载中每个平台的后续插件文件夹中找到每个平台的插件。

有关 Xbox One & Xbox Series X|S 配置的详细信息，请参阅 Epic 的 GDK 文档。

注意

如果使用 Unreal Engine 4，则将显示 XboxOneGDK 而不是 XB1。此平台在 Unreal Engine 5 中重命名为 XB1。

GDK & 引擎兼容性

每个Unreal Engine版本都将包括发行说明，这些发行说明指定编辑器支持的主要 GDK 版本。此版本已通过测试来验证与引擎的兼容性。下面是一个示例：

Unreal Engine发行说明

定义此和受支持的 GDK 版本的范围的配置文件是 Engine\Platforms\GDK\Config 文件夹中的 GDK_SDK.json 文件。下面是一个示例：

{
    "MainVersion": "250402",
    "MinVersion": "240604",
    "MaxVersion": "250499",
}

如果想要采用比Unreal Engine版本更新的 GDK，修改此文件中的 GDK 版本将允许读取较新的 GDK。虽然我们努力避免兼容性问题，但某些 GDK 可能需要对引擎进行修改才能正常工作，在修改最大版本时，无法保证兼容性超出此文件的已发布版本中定义的 Epic Games。

使用 GDK 平台扩展的项目更新

获取 GDK 平台扩展源后，需要更新项目文件才能访问 IDE 中特定于 GDK 的平台。这可以通过在引擎版本的根目录中运行 GenerateProjectFiles.bat 来完成。

完成后，你将在 IDE 解决方案平台下拉列表中看到针对每个平台生成的选项。

在 Visual Studio IDE 中Unreal Engine GDK 平台

重新生成编辑器后，你将在 Unreal 编辑器中看到这些平台设置和选项。若要对此进行测试，请选择“平台”下拉列表，并确认列表中是否存在 WinGDK、XB1 & XSX。

在 Unreal 编辑器中Unreal Engine GDK 平台

有关详细信息，请参阅 [从源生成Unreal Engine] (https://aka.ms/ue_build_source).

重要

Unreal Engine的 Microsoft GDK 插件提供构建 GDK 游戏作为 Win64 平台的一部分的功能。这在 Win64 上跨电脑店面提供了统一的平台，并消除了与 WinGDK 平台存在的重复烹饪和插件不兼容。
Unreal Engine的Microsoft GDK 插件是Unreal Engine内 PC GDK 集成的未来。若要详细了解它们，以及如何通过 Epic 提供的迁移脚本将现有 WinGDK 项目迁移到 Win64 + GDK 插件，请参阅 Epic 的 GDK 文档。

将 GDK 插件添加到项目

注意

默认情况下，会自动为 XB1 & XSX 启用 GDK 插件的子集。有关平台启用的功能的详细信息，请参阅引擎源中的UEBuildXboxCommon.cs。

获取并设置 GDK 平台扩展后，可以开始配置项目以开始使用 GDK。上述每个插件都将在 Unreal 编辑器的“编辑菜单”下的插件 UI 中提供。

选择插件时，请确保检查框来启用它。建议在启用所需插件以确保完整功能后重启编辑器。

在 Unreal 编辑器中启用的示例 GDK 插件

除了在编辑器中启用插件外，还应确保定义的任何生成目标也启用这些插件进行编译。可在下面找到适用于 Windows 生成目标的示例：

EnablePlugins.AddRange([
    "MSGameStore",
    "MSGamingRuntime",
    "OnlineSubsystemGDK",
]);

若要详细了解如何使用适用于Unreal Engine的 GDK 插件设置生成目标，请参阅 Epic 的 GDK 文档。

为特定于游戏的数据配置 GDK 插件

设置 GDK 插件和 GDK 平台扩展后，需要更新“项目设置”菜单中的平台 & 插件设置。

可在平台设置中找到 XB1 & XSX 平台，Unreal Engine的 Microsoft GDK 插件可在插件设置中找到：

Unreal Engine GDK 平台 & 插件设置

每个设置中都有一组类似的设置，可帮助你配置 MicrosoftGame.config 文件和打包配置。

GDK 插件项目设置第 1 部分

本地 MicrosoftGame.config 将需要你的产品信息（如游戏 ID 和应用商店 ID）才能与 GDK & Xbox 服务配合使用。可以利用“与合作伙伴中心关联”选项登录到具有合作伙伴中心访问权限的Microsoft帐户，并将产品详细信息自动拉取到本地 MicrosoftGame.config 文件，从而节省在本地启动和运行的手动步骤。

除了 MicrosoftGame.config 设置之外，还有一些用于打包和安装选项的其他设置：

GDK 插件项目设置第 2 部分

除了平台 & 插件设置之外，还需要确保 DefaultEngine.ini 具有必要的信息。应根据使用上面详述的 MS Gaming (PC GDK) 插件设置自动写入此部分。下面是使用 GDK 插件进行引用的 DefaultEngine.ini 示例：

注意

如果要在平台引擎 ini 文件 (（例如 WindowsEngine.ini) ）中指定任何替代，则需要手动修改该文件。

[/Script/MSGamingSupport.MSGamingSettings]
TitleId=00000000
PrimaryServiceConfigId=00000000-0000-0000-0000-000000000000
ProductId=ProductValue
ContentId=ContentIDValue
PackageName=PackageName
StoreId=0000000000
DefaultDisplayName=Test Game
PublisherName=CN=PublisherValue
PublisherDisplayName=Test Company
EKBID=EKBIDValue
MSAAppId=MSAppIdValue
bRequireXboxLive=True 
bUseSimplifiedUserModel=True 
ManifestVersion=1

若要利用 GDK 包区块安装插件进行智能交付，请确保在 ini 文件中也指定了这一点。

[StreamingInstall]
DefaultProviderName=GDKPackageChunkInstall

将 OnlineSubsystem 用于 GDK

OnlineSubsystem GDK 插件提供关键 Xbox 服务 API 的引擎抽象，以简化为跨许多商店 & 平台执行类似作而编写的游戏代码， (例如登录、商店购买、成就、好友、matchmaking.) 。如果要构建 GDK 游戏，建议利用此 OnlineSubsystem 。

若要配置 OnlineSubsystem GDK，需要编辑 DefaultEngine.ini (或平台引擎 ini 文件，) 包含其他详细信息，以确保它适用于你的游戏。下面是 WindowsEngine.ini 的示例：

[OnlineSubsystem]
DefaultPlatformService=GDK

[OnlineSubsystemGDK] 
eEnabled=True
AchievementMode=2017
; to specify using title-managed achievements, must match configuration in Partner Center
StatsMode=2013
; to specify using event-based stats, must match configuration in Partner Center
PrimaryServiceConfigId=00000000-0000-0000-0000-000000000000

Unreal 中使用的成就名称需要映射到合作伙伴中心中使用的成就 ID。若要映射 Unreal 中使用的成就名称，请在项目的 platforms\GDK\Config\OSS\ 目录中创建名为 Achievements.json 的文件（请注意，路径可能不存在，可能需要自己创建）。 Achievements.json 包含成就名称到合作伙伴中心 ID 的映射。例如，如果项目有 10 个成就，从成就 1 到成就 10，Achievements.json 将如下所示：

{
    "AchievementEventName" : "NotUsedInAchievement2017",
    "AchievementMap" :
    {
      "achievement 1" : 1,
      "achievement 2" : 2,
      "achievement 3" : 3,
      "achievement 4" : 4,
      "achievement 5" : 5,
      "achievement 6" : 6,
      "achievement 7" : 7,
      "achievement 8" : 8,
      "achievement 9" : 9,
      "achievement 10" : 10
    }
}

有关详细信息，请参阅在合作伙伴中心配置游戏管理的成就。

除了配置 DefaultEngine.ini & 设置Achievements.json文件外，还需要在对 Online：：GetSubsystem () 的调用中传递GDK_SUBSYSTEM。

注意

联机子系统 GDK 通过 GDK PlayFabParty 插件直接利用 PlayFab Party 作为套接字子系统。

利用 Visual Studio 和 Unreal Engine

Visual Studio 提供了附加功能（作为Visual Studio 安装程序的一部分），以便更好地与Unreal Engine集成。这包含在游戏开发中，C++有效负载。有两个可选安装组件，称为“Unreal Engine的Visual Studio Tools”和“用于Unreal Engine的 Visual Studio 调试器工具”，它们提供本机 uplugin 支持以及从 Visual Studio 中调试蓝图逻辑的功能。

Visual Studio 安装程序中Unreal Engine的Visual Studio Tools

若要详细了解Unreal Engine Visual Studio Tools，请参阅此处。

生成、烹饪 & 打包项目

可以利用 Unreal 自动化工具为每个 GDK 平台自动生成、制作和打包游戏，包括使用 Win64 平台为 GDK 插件集成创建包。为此，请使用以下语法：

RunUAT BuildCookRun -project=TestGame -Platform=Win64 -build -cook -stage -pak -archive -archivedirectory=C:\TestGame\ -package

可以通过 Unreal 编辑器生成、烹饪和打包游戏。有关此过程的阶段，请参阅生成作：Cook、Package、Deploy 和 Run。

每个平台都需要内容的独特厨师，以确保它适用于目标平台。导航到编辑器中的“平台”下拉菜单，然后选择所需平台的“烹饪内容”。

Unreal 编辑器中的“烹饪”选项

若要在编辑器中打包游戏，请导航到编辑器中的“平台”下拉菜单，然后选择所需平台的“打包项目”。这会在生成输出目录中创建 XVC/MSIXVC 包。

Unreal 编辑器中的“包”选项

测试项目

还可以利用 Unreal Automation Tool 部署和启动生成。为此，请使用以下标志：

RunUAT BuildCookRun [...]] -package -deploy -run

可以利用内置启动设置作为 Unreal 编辑器项目启动器一部分来测试独立生成。

示例项目启动器配置文件

对于通过编辑器 UI 生成的包，需要使用 GDK 工具在 Unreal 编辑器外部安装和启动它们，因为目前不支持从项目启动器中安装和启动它们。有关如何为电脑 GDK 游戏执行此作的信息，请参阅利用Microsoft游戏开发工具包工具来安装和启动电脑游戏。

使用适用于 Unreal Engine 的 Microsoft GDK 插件，你可以利用“在编辑器中播放” (PIE) 直接从 Win64 平台上的编辑器内使用 Xbox 服务测试游戏。

注意

WinGDK 平台和在编辑器中播放 (PIE) 支持存在一些已知限制。建议对此平台进行独立和打包的生成测试。

其他信息

将 PlayFab 与 Unreal Engine 配合使用

若要了解有关使用 PlayFab（包括直接集成和插件）在Unreal Engine（包括联机子系统支持）的详细信息，请参阅 PlayFab Unreal Engine快速入门页。

Windows Handheld 设备检测

Unreal Engine 5.7 支持通过 FPlatformMisc：：IsDeviceHandheld () 检测 Windows 手持设备。这将根据设备状态返回 true/false。

获取帮助

有关任何Unreal Engine特定支持或问题，包括与适用于 Unreal Engine 的 Microsoft GDK 插件或 GDK 平台扩展相关的问题，请参阅 Epic GDK 支持论坛。

如果你正在寻找与特定于 GDK 的主题相关的帮助，这些主题并非特定于Unreal Engine特定集成，请在上发布这些内容，请参阅 Xbox GDK 论坛。

使用较旧版本的 Unreal Engine

如果使用 Unreal Engine 4.26 或更早版本，则需要按照不同的步骤来定位 GDK。此外，与较新版本的引擎相比，这需要更多平台功能 & 打包的自定义集成。建议升级到 Unreal Engine 4.27 或更高版本，以获得最佳体验。

有关将 GDK 与 Unreal Engine 4.26 或更高版本配合使用的详细信息，请参阅为早期版本的 Unreal 构建 GDK 游戏。

反馈

此页面是否有帮助？

Last updated on 2025-12-11